flight_recorder.c
Overview
@file flight_recorder.c Binary flight-recorder format: framed records (magic, metadata, configuration, events, end) with little-endian integers and truncation handling; read/write operations with overflow detection.
depends on woz_log.h flight_recorder.h woz_uwb_facade.h
flowchart TD fr_capture_config --> fr_write_config
API
Fstatic void p8(uint8_t *b, size_t *o, uint8_t v)
Write a 1-byte unsigned integer to buffer at offset o and advance o.
fr_emit, fr_write_config, fr_write_end, fr_write_ev, fr_write_metaFstatic void p16(uint8_t *b, size_t *o, uint16_t v)
Write a 2-byte little-endian unsigned integer to buffer at offset o and advance o.
fr_emit, fr_write_config, fr_write_ev, fr_write_metaFstatic void p32(uint8_t *b, size_t *o, uint32_t v)
Write a 4-byte little-endian unsigned integer to buffer at offset o and advance o.
fr_write_config, fr_write_end, fr_write_ev, fr_writer_initFstatic void p64(uint8_t *b, size_t *o, uint64_t v)
Write an 8-byte little-endian unsigned integer to buffer at offset o and advance o.
fr_write_config, fr_write_evFstatic void pbytes(uint8_t *b, size_t *o, const uint8_t *s, size_t n)
Copy n bytes from s to buffer at offset o and advance o.
fr_emit, fr_write_config, fr_write_ev, fr_write_metaFstatic uint8_t g8(const uint8_t *b, size_t *o)
Read and advance a 1-byte unsigned integer from buffer at offset o.
fr_read_nextFstatic uint16_t g16(const uint8_t *b, size_t *o)
Read and advance a 2-byte little-endian unsigned integer from buffer at offset o.
fr_read_nextFstatic uint32_t g32(const uint8_t *b, size_t *o)
Read and advance a 4-byte little-endian unsigned integer from buffer at offset o.
fr_read_nextFstatic uint64_t g64(const uint8_t *b, size_t *o)
Read and advance an 8-byte little-endian unsigned integer from buffer at offset o.
fr_read_nextFstatic int fr_emit(fr_writer_t *w, uint8_t type, const uint8_t *payload, size_t plen)
Emit one framed record: [u8 type][u16 payload_len][payload]. Latches overflow (and leaves the buffer at its last complete record) if it would not fit.
fr_write_config, fr_write_end, fr_write_ev, fr_write_meta · calls p16, p8, pbytesFvoid fr_writer_init(fr_writer_t *w, uint8_t *buf, size_t cap)
Initialize a flight-recorder writer with an output buffer; write the magic prefix if capacity permits, otherwise latch overflow flag.
fr_clear, fr_set_enabled · calls p32Fint fr_write_meta(fr_writer_t *w, uint16_t port, const char *sha)
Emit a META record containing flight-recorder version, host port, and optional commit SHA; return 0 on success or -1 on buffer overflow.
fr_set_enabled · calls fr_emit, p16, p8, pbytesFint fr_write_config(fr_writer_t *w, const struct fr_config *c)
Emit a CONFIG record containing Aliro session parameters and UWB radio configuration; truncate URSK and radio controller data to maximum lengths if needed; return 0 on success or -1 on buffer overflow.
fr_capture_config · calls fr_emit, p16, p32, p64, p8, pbytesFint fr_write_ev(fr_writer_t *w, const struct fr_ev *e)
Emit an EV record containing DW3000 register snapshot and received frame data; truncate frame to maximum length if needed; return 0 on success or -1 on buffer overflow.
fr_capture_ev · calls fr_emit, p16, p32, p64, p8, pbytesFint fr_write_end(fr_writer_t *w, uint32_t n_events, bool truncated)
Emit an END record with event count and truncation flag; return 0 on success or -1 on buffer overflow.
fr_finalize · calls fr_emit, p32, p8Fvoid fr_reader_init(fr_reader_t *r, const uint8_t *buf, size_t len)
Initialize a flight-recorder reader to parse a binary buffer; do not validate the magic prefix until the first read.
Fint fr_read_next(fr_reader_t *r, struct fr_record *out)
Parse one flight-recorder record from the reader buffer; check magic prefix on first call, validate frame format and type; return the record type on success, 0 for clean end-of-buffer, or -1 on malformed input.
g16, g32, g64, g8Fstatic uint64_t fr_ts5(const uint8_t t[5])
Decode a 5-byte little-endian unsigned integer.
fr_capture_evFvoid fr_set_enabled(bool on)
Stub callback that enables or disables flight recording. No-op when the flight recorder is disabled.
fr_write_meta, fr_writer_initFbool fr_enabled(void)
Returns true if the flight recorder is enabled and capturing events; false otherwise. Stub when disabled.
Fvoid fr_set_dump_sink(void (*sink)(const char *line))
Set an optional callback function to receive each line of flight-recorder dump output; if NULL, output goes to stdout.
Fvoid fr_capture_config(const struct woz_uwb_aliro_cfg *c)
Stub callback invoked when the flight recorder captures the Aliro session configuration. No-op when the flight recorder is disabled.
fr_write_configFvoid fr_capture_ev(uint8_t ep, uint32_t status, uint16_t datalength)
Snapshot the DW3000 registers this entry point will read, then append the
event. Reads are side-effect-free, but they do cost SPI while armed — capture
is opt-in and perturbs walk-up timing exactly like the lab/uwbdiag traces
do, so arm it only for a capture run.
fr_ts5, fr_write_evFsize_t fr_finalize(const uint8_t **buf)
Append the END record once, then hand back the finalised buffer.
fr_dump · calls fr_write_endFstatic void fr_emit_line(const char *line)
Emit a line to the registered dump sink if set, otherwise print to stdout.
fr_dumpFvoid fr_dump(void)
Stub callback that dumps the flight recorder ring buffer to the host interface. No-op when the flight recorder is disabled.
fr_emit_line, fr_finalizeFvoid fr_clear(void)
Stub callback that clears the flight recorder ring buffer. No-op when the flight recorder is disabled.
fr_writer_init