2.6 KiB
Raw Blame History

Relay capture format, revision 1

The byte stream has no padding between fields. Every integer field uses least significant byte first. Storage addresses and transfer boundaries are independent of fields. A packet has at most 1024 bytes and at most 32 records.

Header (6 bytes): a5 5a, version 01, one-byte record count, two-byte payload length. Payload: exactly count records, each tag byte, length byte, then length data bytes. Trailer (4 bytes): FNV-1a-32 of the header and payload, starting with 2166136261; for each byte XOR then multiply by 16777619 modulo 2^32.

Tag 1: exactly 10 data bytes: source u16, value u32, auxiliary u32. Tick is zero. Tag 2: 0–32 raw label bytes. Source and tick are zero; value is FNV-1a-32 of the label; auxiliary is its length. Tag 3: exactly 16 bytes: source u32, tick u64, value u32, auxiliary zero. Other tags are retained as opaque records with zero source and tick, value equal to FNV-1a-32(data), auxiliary equal to length.

The decoder first checks minimum length (10), then header magic/version/count, then exact total length, then checksum, then records in order. Error codes are 2 capacity, 3 header, 4 length, 5 checksum, 6 record. Count/length disagreement, invalid tag length or a record crossing payload end is a record error. A rejected record is not emitted. Previously decoded records remain observable. Header rejection leaves declared zero; after header acceptance declared contains count. Checksum is zero until total length is accepted, then contains the stored trailer.

O fields: sequence, error, capture byte count, number of feed calls, declared count, emitted count, stored checksum, fingerprint. E fields: sequence, zero-based index, tag, length, source, tick, value, auxiliary. All are unsigned decimal except error (still nonnegative). Each emitted event updates fingerprint, initially zero, by repeatedly x=(33*x+field) mod 2^32 for tag,length,source,tick low32,tick high32, value,auxiliary in this order. Output is O followed by its E rows. An incomplete capture may be completed by any number of feed calls before finish. Finish is idempotent; feeding after finish is argument error 1. Invalid pad is argument error 1. Failed feed preserves existing bytes. Feed increments chunks on success, including an empty library feed. The command adapter supplies nonempty feeds.

The feedv interface checks the whole vector before copying any fragment: capacity or a nonempty null fragment fails without copying bytes. It then applies each fragment as one successful feed. The command adapter builds a vector from the requested chunk width and uses this interface.