gazagnaire.org / space-wire
SpaceOS wire protocol codecs for host-guest communication
fork atom
space-wire / README.md
at main 3.1 kB view raw view code

space-wire#

SpaceOS wire protocol codecs.

space-wire defines the binary codecs for all SpaceOS host-guest communication structures. Every codec is built on top of the wire library's declarative Wire.Codec combinator system, producing fixed-size encode/decode functions with no allocation beyond the target buffer.

The package covers six codec families:

  • Msg -- the 256-byte fixed-size frame that is the fundamental unit of SpaceOS IPC. Contains an 8-byte header (version, type, APID, payload length, reserved) and a 248-byte zero-padded payload. Supports ten message types: TM, TC, EVR, PRM_GET, PRM_SET, PRM_RSP, DP, HEALTH, LOG, ERROR.
  • Shared_mem -- accessor functions for the 4096-byte shared memory page used for host-guest coordination. Includes heartbeat counters, mission time with seqlock protocol, status/command words, and a health string.
  • Superblock -- 48-byte block device header with magic number (0x53504F53 = "SPOS"), format version, tenant ID, block layout, epoch, UUID, and CRC-32C.
  • Param_entry -- 252-byte parameter store entries with generational versioning and CRC-32C integrity.
  • Event_log -- 76-byte event log records with timestamp, severity level, event code, and payload.
  • Dp_payload -- 80-byte data product notification with block location, classification, priority, name, and CRC-32C.
  • Error_payload -- 8-byte ERROR/NACK payload identifying the offending frame.

Installation#

opam install space-wire

Usage#

(* Encode and decode a 256-byte frame *)
let frame = Space_wire.Msg.v TM ~apid:0x100 "sensor:temp=22.5" in
let buf = Bytes.make Space_wire.Msg.frame_size '\x00' in
Wire.Codec.encode Space_wire.Msg.codec frame buf 0;

let decoded = Wire.Codec.decode Space_wire.Msg.codec buf 0 in
assert (Space_wire.Msg.equal frame decoded);

(* Read mission time from shared memory with seqlock *)
let mt = Space_wire.Shared_mem.read_mission_time shm_page in
Printf.printf "Mission time: %Ld.%09d\n" mt.seconds mt.nanos

Demo#

The package includes a demo binary (space-wire-demo) that simulates a complete host-guest session over a Unix socketpair, exercising all codec types: superblock initialization, parameter store read/write, event log ring buffer, data product storage with CRC validation, heartbeat monitoring, mission time via seqlock, telecommands, and ERROR/NACK handling.

dune exec space-wire/bin/demo.exe

API#

  • Space_wire.Msg -- 256-byte frame codec, message type enum, and constructors
  • Space_wire.Shared_mem -- 4096-byte shared memory page accessors with seqlock mission time protocol
  • Space_wire.Superblock -- 48-byte superblock codec with magic and CRC-32C validation
  • Space_wire.Param_entry -- 252-byte parameter entry codec with generational versioning
  • Space_wire.Event_log -- 76-byte event log record codec with severity levels
  • Space_wire.Dp_payload -- 80-byte data product notification codec
  • Space_wire.Error_payload -- 8-byte error/NACK payload codec