Discord-PXE Technical Internals
This section documents Discord-PXE as a bare-metal distributed systems project rather than as a simple Discord client.
It is organized around boot boundaries, ownership, memory isolation, protocol state, failure recovery, and hardware verification.
The pages in this section describe behavior implemented in the public Discord-PXE repository. Source links point to the files that own the relevant state machines and hardware-facing paths.
The singleton runtime is the hardware-proven reference and is preserved on the baseline branch. The multi-shard work on main is intentionally being validated in small steps before larger local shard counts are treated as proven.
Where the documentation walks through assembly, the code box leads with NASM original, followed by a separate Execution order tab and then Rust, C, and Python translations.
The NASM tab is the authoritative implementation from Discord-PXE. The Execution order tab walks the same routine in plain sequential steps. Rust and C preserve the state transitions and control-flow intent in systems-language form, while Python acts as a higher-level behavioral model. None of the translation tabs claim that the runtime is written in those languages or that they compile to identical machine code.
Sections that benefit from code, but do not require it for the explanation, use a clearly labeled Code example of … dropdown. Those examples stay collapsed by default and use the same NASM-first pattern where practical: NASM, Execution order, Rust, C, and Python.
System model
┌──────────────────────────────────────────────┐
│ PXE firmware / ROM │
│ - DHCP/PXE handoff │
│ - TFTP services │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ 16-bit stage-1 loader │
│ - validates PXENV+ │
│ - preserves firmware-sensitive state │
│ - downloads runtime.bin │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ x86-64 bare-metal runtime │
│ - paging / long mode │
│ - memory / CPU / console │
│ - NIC / IP / TCP │
│ - crypto / TLS │
│ - HTTP / WebSocket │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Discord Gateway │
│ - Hello / Identify / Resume │
│ - sequence + heartbeat state │
│ - session / reconnect state │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Local shard scheduler │
│ - up to 128 local slots │
│ - per-shard transport workspaces │
│ - backoff / reset / fatal state │
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Optional Go controller │
│ - node check-in │
│ - capacity-weighted shard leases │
│ - Identify coordination │
│ - guild → shard → node routing │
└──────────────────────────────────────────────┘
Core invariants
1. The PXE environment is part of the runtime contract
The firmware stack is not just a bootloader convenience. Early code still relies on PXE ROM services while loading the larger runtime, so stack placement and protected low-memory regions matter.
The loader explicitly preserves the original PXE entry environment and avoids overwriting regions firmware may still depend on.
See Boot Chain.
2. Shard isolation includes transport memory, not only Discord state
A shard cannot be considered independent if it has a unique shard ID but shares TCP sequence state, TLS buffers, WebSocket workspaces, or Discord receive buffers with another shard.
The current architecture gives each active shard explicit pointers to its own TCP, TLS, WebSocket, Discord, RX, and TX state.
See Shard Context & Memory Layout.
3. The singleton path remains the regression oracle
The proven single-connection runtime is preserved while sharded replacements are introduced layer by layer.
That means a failure can be asked in a useful form:
Did the protocol break, or did the context conversion break?
See Design Decisions.
4. Protocol success is measured across layers
A TCP connect is not a Discord success. A TLS handshake is not a Gateway success. A Gateway READY is not sufficient proof of multi-shard isolation.
The two-shard acceptance path verifies transport/workspace separation and live heartbeat acknowledgements in addition to READY.
See Diagnostics.
5. Shard ownership is time-bounded
When multiple physical PXE nodes are involved, ownership is a lease rather than a permanent assignment.
This prevents stale nodes from believing they still own a shard indefinitely after controller or network failure.
See Controller Protocol.
6. Gateway Identify concurrency is global
Discord's Identify concurrency applies across the bot's total shard population, not independently per PXE box.
Local and cross-node scheduling therefore cannot simply let every shard Identify as soon as TCP/TLS/WebSocket are ready.
See Gateway Sharding.
Boot & Runtime
Boot Chain
How the 16-bit loader validates PXE firmware structures, obtains DHCP state, protects firmware-sensitive memory, downloads runtime.bin, and transfers into the x86-64 runtime.
Startup Trace & Serial Markers
The complete stage-1 letter sequence, 16-bit discovery trace, x86-64 initialization order, and reference for runtime prefixes such as [UART], [CPU], [RTL], [TCP], [TLS], [DISCORD], and [SHARD].
Shard Context & Memory Layout
The 256-byte top-level shard descriptor, state/flag layout, per-shard pointers, lazy workspace allocation, and why the actual per-shard memory footprint is much larger than the descriptor itself.
Transport Stack
Network Stack
How Discord-PXE owns IP/TCP behavior directly and how the sharded path keeps each connection's local port, sequence space, callbacks, counters, and failure state separate.
TCP Reliability & Flow
TCP payload limits, checksums, retry state, reliable retransmission workspaces, and the connection-level assumptions that have to stay correct before TLS can be trusted.
TLS & WebSocket
The large per-shard TLS workspace, handshake transcript, key material, record state, WebSocket request/accept workspace, and how those layers bind to one shard's private TCP context.
Gateway & Control
Gateway Sharding
Gateway sequence, heartbeat jitter, ACK tracking, Identify state, session/resume behavior, fatal close handling, and shard routing.
Scheduler & Lifecycle
How a shard moves through assigned, starting, ready, backoff, and fatal states; how only one failed shard is reset; and how reconnect state is preserved when a resumable session remains valid.
Controller Protocol
The Go controller's lease generation, deterministic capacity-weighted contiguous ranges, node expiry, Identify claims, and guild routing.
Verification & Decisions
Diagnostics
Serial breadcrumbs, shell diagnostics, two-shard acceptance, layer-by-layer failure localization, and why live hardware evidence matters more than a successful build.
Design Decisions
Why the project keeps a baseline branch, uses staged scaling, allocates private workspaces, coordinates Identify globally, and keeps the controller separate from the bare-metal data plane.
Primary source entry points
| Subsystem | Source |
|---|---|
| Stage-1 loader | src/stage1/loader.asm |
| Runtime boot / long-mode path | src/legacy/pxe_boot.asm |
| Shard descriptor + local plan | legacy_shards.inc |
| Per-shard TCP | legacy_shard_tcp.inc |
| Reliable shard TCP | legacy_shard_tcp_reliable.inc |
| Per-shard TLS | legacy_shard_tls.inc |
| Per-shard WebSocket | legacy_shard_websocket.inc |
| Gateway state | legacy_shard_gateway.inc |
| Shard lifecycle | legacy_shard_lifecycle.inc |
| Shell diagnostics | legacy_shell.inc |
| Controller | controller/main.go |