# 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

```ocaml
(* 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