Skip to main content

Hardware Testing

Discord-PXE is validated in layers. A successful build proves syntax/linkage; a successful VM boot proves one emulated environment; neither replaces physical hardware validation.

The current known-good baseline is a complete 128-shard READY bring-up in stable BSP scheduler mode.

Do not skip layers

If PXE, native networking, DNS, or singleton TLS is broken, do not jump directly into shard scheduler debugging. Re-prove the lower layers first.

1. Build and boot​

Use the normal flow:

git pull
run.bat

Capture serial at:

115200 8N1
flow control: none

2. Validate machine/runtime bring-up​

A healthy boot should report transitions similar to:

[MODE] x86-64 long mode active
[SMP] processors online=... expected=...
[SMP] multicore worker dispatch verified
[RTL] native polling backend online ...
[IP] address=... router=... dns=...

On the currently tested Haswell-class machine, 4 logical processors are expected and all 4 come online.

Stable scheduler does not mean single-core runtime

The AP worker system is hardware-proven. The stable shard protocol scheduler still runs shard state machines on the BSP because shared crypto scratch and NIC TX ownership need stronger SMP validation.

3. Validate DNS and singleton Discord​

Before taking over with the shard pool, wait for the singleton path to prove:

[DNS] query sent
[DNS] gateway.discord.gg=...
[TCP] gateway connection established
[X509] leaf chain verified locally
[X509] verified leaf RSA key ready
[TLS] authenticated tls established
[DISCORD] http 101 + websocket accept verified
[DISCORD] READY, bot online

If singleton Discord is unhealthy, treat it as a control-case failure.

4. Two-shard isolation test​

Run:

shardtest2

Then:

shardteststatus

A complete pass reports:

[SHARDTEST] PASS: 2/2 isolated shards READY with TLS + heartbeat ACKs

The acceptance routine checks both behavior and isolation:

  • separate TCP contexts
  • separate local ports
  • separate TLS workspaces
  • separate WebSocket workspaces
  • separate Discord workspaces
  • READY state
  • authenticated TLS
  • heartbeat acknowledgements
  • no shard-level error

5. Full stable 128-shard test​

The current hardware-proven local path is:

shardplan 128 0 128
shardstart

The plan should announce that Identify concurrency is forced to 1 until runtime /gateway/bot discovery is available.

A healthy shard advances through:

connection admitted
tcp start
tcp SYN sent
tcp connected
TLS client key flight + Finished sent
TLS authenticated; WebSocket upgrade sent
HTTP 101 + WebSocket accept verified
Gateway Hello
Gateway Identify sent
READY, shard online

Success criteria​

For the stable BSP baseline:

  • shard IDs 0..127 reach READY
  • no CPU exception/reset occurs
  • shell remains responsive
  • transient TCP/TLS failures may enter BACKOFF
  • transient failures are acceptable only if the shard rebuilds and returns to READY
  • repeated invalid-session storms are not acceptable

Useful commands​

shards
shardreset <local-slot>
shardstop
shardlease <seconds>

See the Command Reference for the complete runtime shell, argument syntax, side effects, and expected failure messages.

shards​

Use it to inspect:

  • local ownership plan
  • lifecycle state
  • TCP/TLS/WebSocket/Gateway pointers
  • heartbeat counters
  • reconnect count
  • last error
  • lease state

shardreset N​

Rebuilds one local slot without intentionally restarting every other shard.

shardlease 30​

Exercises controller-style lease expiry. When the deadline passes, shard-owned network traffic is stopped.

Error interpretation​

TCP reset by gateway​

A reset alone is not automatically a failed run. If the shard enters BACKOFF, reconnects, and returns to READY, the reconnect path is functioning.

TLS state enters FAILED​

A small number of transient failures may recover in a large BSP run. Widespread synchronized TLS failures point more strongly toward shared implementation state or transport contention.

Gateway invalid session storm​

Suspect Identify scheduling or session-start exhaustion before assuming the TLS path is broken.

DNS starts but no query is sent​

Inspect ARP/TX/DNS state before touching TLS.

Experimental SMP validation​

SMP shard execution exists in source but remains disabled by default.

The first hardware attempt exposed:

  • shared crypto scratch
  • shared native TX assumptions

The corrected experimental path serializes non-reentrant crypto and shared TX work, but it still requires hardware acceptance before becoming the default.

Recommended validation progression:

8 -> 16 -> 32 -> 64 -> 128

Keep stable BSP mode available as the fallback until the full SMP run is clean.

What to save from a hardware run​

Keep the entire serial session when possible. The most useful evidence includes:

commit:
physical hardware / VM:
CPU:
NIC:
PXE firmware:
PXE/TFTP server:
serial adapter / port:
singleton healthy:
shard plan:
first failing shard:
last successful layer:
shards output:
shardteststatus output:

For deeper marker-by-marker analysis, see Troubleshooting and Diagnostics.