Codify commodity-hardware constraint: auto-fallback XDP mode + ADR amendment#20
Merged
Merged
Conversation
The project's deployment target is "any x86_64 / ARM64 Linux server with kernel >= 5.10" — no SmartNIC, no specific NIC vendor, no kernel patches, no DPDK toolchain. This was already true in spirit (PR 8 deleted the DPDK backend, ADR-002 picked xdpilone over libbpf-rs to keep the build dep footprint small) but wasn't written down. Two operational consequences had been left implicit: * `deploy/xdp/load.sh` defaulted to `native` mode, which fails on NICs whose drivers don't implement the XDP RX hook (older virtio, some embedded NICs, every veth device used in tests). Operators on commodity hardware would hit a confusing "operation not supported" on first attach. * HW-mode XDP offload (Netronome / Corigine SmartNICs) had no docs flagging it as out-of-scope; nothing told a future contributor why it isn't a default. Fixes: * `load.sh` gains an `auto` mode (now the default): try `native` first, fall back to `skb` (generic kernel-side XDP) if the driver doesn't support it. SKB mode runs in the kernel's generic XDP hook so it works on every Linux NIC since 5.10, at the cost of ~30–40% throughput vs native. Operator output prints which mode it ended up using. * `load.sh` detach loop now tries all three mode flags so re-runs are idempotent regardless of which mode was used last. * ADR-002 gains a sixth decision driver — "Commodity hardware" — spelling out what's in (auto fallback, native/skb modes) and what's explicitly out (HW offload, driver-private fast paths, DPDK). * README's stale "AF_XDP and DPDK backends" feature line replaced with the auto-fallback story; ADR-002 added to the docs list. * `operations.md` AF_XDP setup section explains the auto mode and lists which commodity NICs get native vs skb. * `smoke-test.sh` switches to passing `skb` explicitly (veth doesn't support native) with a comment on why. After this change: `sudo deploy/xdp/load.sh eth0` is the one-liner that works on any commodity Linux box, no NIC-vendor dance. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Writes down what was already true in spirit: `lb-node` runs on any x86_64 / ARM64 Linux server with kernel ≥ 5.10. No SmartNIC, no vendor-specific driver flags, no DPDK toolchain, no kernel patches.
Two operational holes closed:
Also updates README + operations.md to match (the README's stale "AF_XDP and DPDK backends" line was particularly load-bearing).
Test plan
🤖 Generated with Claude Code