Skip to main content

Architecture

Discord-PXE is split into a firmware-facing boot layer, a bare-metal x86-64 runtime, a custom network/security stack, a Discord Gateway layer, and optional shard-control logic.

BIOS PXE
   │
   ▼
stage1.pxe
   │
   ├─ PXENV+
   ├─ cached DHCP
   └─ TFTP runtime.bin
   │
   ▼
x86-64 runtime
   │
   ├─ memory / exceptions / timers
   ├─ SMP / AP workers
   ├─ shell / serial / VFS
   ├─ native NIC / ARP / IPv4 / DNS
   ├─ TCP
   ├─ TLS 1.2 / X.509 / crypto
   ├─ WebSocket
   └─ Discord Gateway
             │
             ▼
       local shard pool
             │
             ▼
   optional controller leases

1. Stage-1 PXE loader​

The first image is responsible for:

  • discovering PXENV+
  • preserving the original PXE stack environment
  • reading cached DHCP information
  • publishing network handoff values
  • downloading runtime.bin
  • protecting low-memory firmware state while the image grows
  • closing TFTP before the runtime fully takes over

The runtime image begins at physical 0x20000.

Firmware memory remains live until the handoff is complete

One hardware bug occurred because the growing runtime crossed the PXE firmware's original stack region. The loader now explicitly protects that area until firmware use ends.

2. Runtime transition​

The runtime begins in 16-bit mode, collects machine information, builds page tables, and transitions into x86-64 long mode.

After the transition it initializes:

  • exception/protection state
  • timing
  • heap/memory services
  • PCI discovery
  • SMP/AP startup
  • crypto
  • networking
  • filesystem/config
  • shell/serial
  • HTTP/status surfaces

3. SMP model​

The runtime discovers processors through ACPI/MADT and brings APs online.

Stable mode​

All APs may be online, but the current known-good shard scheduler advances protocol state machines on the BSP.

That is the hardware-proven 128-shard baseline.

Experimental parallel mode​

AP workers can process disjoint shard subsets, but non-reentrant shared crypto scratch and shared NIC TX require serialization.

This path remains experimental.

4. Network stack​

There is no host OS socket API underneath the runtime.

Realtek NIC
  -> Ethernet
  -> ARP
  -> IPv4
  -> UDP / DNS
  -> TCP
  -> TLS
  -> WebSocket
  -> Discord Gateway

Stage 1 publishes network information such as:

  • client IP
  • server IP
  • gateway
  • subnet
  • router
  • DNS

The long-mode runtime then uses the native Realtek path.

5. TLS and X.509​

The runtime implements the TLS client path used to reach Discord Gateway.

Hardware-proven pieces include:

  • RDRAND-backed ClientRandom
  • X25519 ephemeral key generation
  • X.509 chain verification
  • RSA verification
  • SHA-256 / HMAC / PRF
  • AES-GCM
  • TLS 1.2 authenticated session
  • WebSocket upgrade over authenticated TLS

Each shard has private high-level TLS/session state.

Some low-level crypto helpers still use global scratch, which is the main SMP re-entrancy boundary.

6. Shard context ownership​

The runtime reserves up to 128 local descriptors.

A shard context tracks or references:

  • ID / total
  • lifecycle state
  • sequence
  • heartbeat state
  • Identify bucket
  • TCP
  • TLS
  • WebSocket
  • Discord
  • RX/TX
  • reconnect/backoff
  • lease
  • session/resume
  • last error

The descriptor itself is small; active transport workspaces are allocated separately.

7. Connection admission​

The runtime does not simply open every Gateway connection immediately.

Admission is tied to:

  • DNS readiness
  • shard lifecycle
  • connection wave
  • Identify bucket
  • network-enabled state

This avoids building a backlog of sockets that cannot legally Identify yet.

8. Singleton takeover​

Boot first proves the singleton path.

When shardstart is invoked:

  1. DNS must already be READY.
  2. shard resources are prepared.
  3. singleton Gateway transport is stopped.
  4. shard transport becomes the Discord owner.

The singleton therefore acts as a regression/control path.

9. Gateway lifecycle​

ASSIGNED
  -> connection admitted
  -> TCP
  -> TLS
  -> WebSocket HTTP 101
  -> Gateway Hello
  -> Identify / Resume
  -> READY
  -> heartbeat / ACK

Transient failure:

READY/STARTING
  -> TCP/TLS failure
  -> BACKOFF
  -> deadline
  -> connection reset
  -> retry

FATAL state is reserved for failures that should not loop forever.

10. Controller boundary​

The Go controller is optional and external to the bare-metal data plane.

It owns:

  • node check-in
  • capacity
  • deterministic contiguous leases
  • Identify claims
  • guild routing
  • lease expiry

The PXE runtime still owns the actual transport/Gateway state machine.

11. Important ownership rules​

These are architectural constraints, not style preferences:

  • do not call back into PXE firmware after destroying its execution environment
  • keep bootstrap stacks outside growing runtime code
  • keep shard transport workspaces isolated
  • do not allow multiple CPUs to mutate one shard context simultaneously
  • serialize shared NIC TX
  • serialize or redesign non-reentrant crypto scratch
  • do not guess Discord Identify concurrency
  • treat multi-node ownership as a lease

For implementation detail, continue with Technical Internals.