HardwareLoopProtocol.jl

HardwareLoopProtocol

The shared-memory protocol between a GNSS receiver process and the allocation-free loop process that closes the tracking loops of a hardware correlator.

The two processes share one memory segment — a file, conventionally under /dev/shm on Linux, mapped by both — and nothing else: no serialisation, no syscalls on the hot path, no futex. The segment holds

• a header (magic, protocol version, layout hash, channel count, the band table and both sides' heartbeats), refused on any mismatch;
• one command ring (receiver → loop): arm, release, configure, shutdown, each acknowledged by a status event in the channel's ring;
• one loop-wide nav ring (loop → receiver) of navigation-solution and per-satellite events, plus a seqlock snapshot of the newest solution, used when the loop runs vector tracking (navigation_mode);
• per hardware channel one event ring (loop → receiver) of fixed-size tagged events in loop order — records, bits, epoch states, status — plus a seqlock snapshot of the newest epoch state for readers that only want "now".

Every ring is single-producer single-consumer. Producers never block: a full event ring overwrites its oldest entry and the consumer learns how much history it lost from the sequence numbers; a full command ring refuses the command (try_publish! returns false) — a command must never be lost silently. Head and tail are 64-bit counters written with release and read with acquire ordering through Julia's atomic pointer intrinsics; every slot and the snapshot carry a sequence word so a torn read is detected rather than believed.

The package depends on nothing but Base and is written so that a --trim=safe build of the loop process can carry it: no strings are built on the hot path, every record is isbits, and the mapping is done with plain ccalls.

The same code serves an in-process transport: create_segment with nothing for the path backs the segment with a heap buffer, so the simulated device tests and the software-only CI path run the very code the binary runs.