The SPI Bus Treaty

SPI is a synchronous serial protocol with four signal lines — SCK (clock), MOSI (master out), MISO (master in), and an active-low chip-select per peripheral. The ESP32-S3 has two general-purpose SPI peripherals (SPI2 and SPI3) and a third dedicated to flash memory. The LilyGo T-Deck Plus, T-LoRa Pager, and M5Stack Cardputer ADV all wire SD, LoRa, and display to the same SPI peripheral block, distinguished only by chip-select line.

When two consumers attempt to drive the bus simultaneously — even momentarily — the failure modes are not graceful. The SD card's CMD0 initialization sequence is timing-sensitive: a glitch on SCK during command issuance corrupts the response and the controller enters an error state requiring a full power cycle to recover. The LoRa radio's SX1262 SPI command set assumes the bus is quiet for the duration of a transaction; concurrent SD traffic causes the radio to mis-parse its own command queue and enter undefined states. The display controller's pixel-flush sequence relies on tight timing between command bytes and data bytes; SPI contention produces visible tearing, dropped frames, or display freeze.

None of these failures present as “SPI contention.” The Guru Meditation crash dumps point at memory addresses where execution happened to be when the corruption propagated — not at the source of the corruption. The first symptom of an SPI conflict in this OS was a non-deterministic reboot during heavy field operation. The hypothesis that the SPI bus was the shared resource being contested took several months and many field sessions to establish.

The Treaty was not designed in advance. It was extracted from four specific failure modes that recurred across field operations in 2025–2026. Each is documented here with the symptom, the root cause, and the rule it produced.

The Treaty consists of four rules. They are binding on first-party OS code, third-party ELF modules loaded at runtime from SD, and any future hardware target. Violation produces immediate crashes, watchdog reboots, or test failures. The rules are short enough to be remembered and specific enough to be checked.

The Treaty is enforced by recursive mutex (spi_mutex), not by static analysis. Every site that touches the SPI bus must call spi_mutex_take() before its first transaction and spi_mutex_give() after its last. A manual audit was conducted for v1.2.0 to verify that every take has a matching give, no operations exceed the 50ms hold budget, and no consumer holds the bus during a yield.

The two extra gives are intentional defensive code: the SD filesystem driver and ELF browser each contain a recovery path that releases the mutex in error conditions where a previous acquire may not be tracked. The recursive mutex tolerates extra gives without harm.

The technique of mutex-arbitrated SPI is not new. Every operating system kernel that drives more than one SPI peripheral simultaneously uses some form of arbitration. The contribution of the SPI Bus Treaty is not the technique — it is the protocol: the named, documented, audited contract that every component must obey, published as a public reference for any future project on this hardware class.

The Treaty stands in a tradition of named arbitration protocols:

• Unix filesystem locking conventions (1970s) — established formal rules for competing processes sharing a filesystem. The conventions were not new techniques (file locks predate Unix); the contribution was naming the rules and making them platform-wide.
• Apollo Guidance Computer priority scheduling protocol (1969) — formal rules for competing tasks sharing a processor under load. The 1202 alarm during the lunar landing was the protocol working as designed: the lower-priority task was sacrificed to preserve the higher-priority one.
• Nintendo N64 RSP time budget (1996) — formal rules for competing subsystems sharing the Reality Signal Processor. The budget was not new (time-slicing predates the N64); the contribution was the documented protocol that every game developer had to follow.

In each case the solution was not a patch — it was a protocol. A named standard. A thing that could be taught, documented, and enforced across an entire platform. The SPI Bus Treaty is the application of this approach to the ESP32-S3 hardware class. To the best of our knowledge, no prior published reference for this protocol exists on this chip family. If reviewers can identify prior art, we will document and credit it — this paper is offered with that invitation.

The Treaty is enforced by three mechanisms that work together:

1. The recursive mutex (spi_mutex). Every SPI consumer must acquire the mutex before its first transaction and release after its last. The mutex is recursive, so nested operations within a single component do not deadlock. The mutex is mandatory — there is no “take if available” path. A consumer that cannot acquire the mutex must yield and retry.
2. Audit. The v1.2.0 audit (Section IV) verified that every take has a matching give. The audit is repeated for every release. Future versions will add static analysis to enforce the pattern at compile time.
3. Documentation. The Treaty is documented in this paper and in the source tree. Third-party ELF module developers are required to follow the Treaty as a condition of running on the platform. The Treaty is the public contract — any module that violates it is a bug in that module, not in the OS.

The Treaty is what makes the Ghost Engine possible. The Ghost Engine is the entire reason Pisces Moon OS exists. The relationship between the two is not incidental — the OS was designed around the Engine, and the Engine could not run without the Treaty. The treaty doesn't change. The hardware around the treaty does. The same four rules protect the bus on the T-Deck Plus (8 MB PSRAM), the T-LoRa Pager (8 MB PSRAM, deferred boot), and the Cardputer ADV (no PSRAM, mode-locked WiFi). The protocol generalized to the entire memory tier of the ESP32-S3 chip class.

Two-device live-traffic validation (bench, May 20, 2026): Mesh Messenger send/receive confirmed between T-Deck Plus and Cardputer ADV with Cap LoRa-1262, both on the LongFast channel, concurrent with active wardrive logging on both devices. SD transcripts written to /mesh_logs/messages.csv on each device while WiFi scan results were simultaneously written to wardrive CSV. Both Rule 1 (hit and run) and Rule 2 (no extended holds) survived contact with real LoRa interrupt traffic interleaved with SD writes on the same bus. The Treaty held across the 8 MB PSRAM and no-PSRAM ends of the chip tier simultaneously — proof that the protocol is correctly specified, not merely correctly observed.

The contribution of this document is the protocol itself — named, documented, audited, and offered as a starting point for any future project on this hardware class that needs to coordinate concurrent peripheral access on a shared SPI bus. The protocol is open source under AGPL-3.0. The reference implementation is at github.com/FluidFortune/pisces-moon-os.