Add serial/protocol modules to plan, binary format to arch, -flto to Makefiles
architecture.md: replace JSON control payloads with binary serialization; add Protocol Serialization section describing little-endian wire format, put/get buffer layer, and write_*/read_* protocol layer. planning.md: mark common/media_ctrl/v4l2_ctrl done; insert serial (#4) and protocol (#6) modules with descriptions. conventions.md: document -flto and its implication (no manual static for inlining — compiler handles it at link time). Makefiles: add -flto to CFLAGS in all four Makefiles. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -125,10 +125,10 @@ Header fields:
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| `0x0001` | Video frame |
|
||||
| `0x0002` | Control request (JSON) |
|
||||
| `0x0003` | Control response (JSON) |
|
||||
| `0x0002` | Control request |
|
||||
| `0x0003` | Control response |
|
||||
|
||||
Video frame payloads are raw compressed frames. Control payloads are JSON — the same request/response structure as the V4L2 RPC protocol, but carried inline on the same connection rather than on a separate port.
|
||||
Video frame payloads are raw compressed frames. Control payloads are binary-serialized structures — see [Protocol Serialization](#protocol-serialization).
|
||||
|
||||
### Unified Control and Video on One Connection
|
||||
|
||||
@@ -248,6 +248,35 @@ The final deliverable is a single configurable node binary. During development,
|
||||
|
||||
---
|
||||
|
||||
## Protocol Serialization
|
||||
|
||||
Control message payloads use a compact binary format. The wire encoding is **little-endian** throughout — all target platforms (Raspberry Pi ARM, x86 laptop) are little-endian, and little-endian is the convention of most modern protocols (USB, Bluetooth LE, etc.).
|
||||
|
||||
### Serialization Layer
|
||||
|
||||
A `serial` module provides the primitive read/write operations on byte buffers:
|
||||
|
||||
- `put_u8`, `put_u16`, `put_u32`, `put_i32`, `put_u64` — write a value at a position in a buffer
|
||||
- `get_u8`, `get_u16`, `get_u32`, `get_i32`, `get_u64` — read a value from a position in a buffer
|
||||
|
||||
These are pure buffer operations with no I/O. Fields are never written by casting a struct to bytes — each field is placed explicitly, which eliminates struct padding and alignment assumptions.
|
||||
|
||||
### Protocol Layer
|
||||
|
||||
A `protocol` module builds on `serial` and the transport to provide typed message functions:
|
||||
|
||||
```c
|
||||
write_v4l2_set_control(stream, id, value);
|
||||
write_v4l2_get_control(stream, id);
|
||||
write_v4l2_enumerate_controls(stream);
|
||||
```
|
||||
|
||||
Each `write_*` function knows the exact wire layout of its message, packs the full frame (header + payload) into a stack buffer using `put_*`, then issues a single write to the stream. The corresponding `read_*` functions unpack responses using `get_*`.
|
||||
|
||||
This gives a clean two-layer separation: `serial` handles byte layout, `protocol` handles message semantics and I/O.
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
- What is the graph's representation format — in-memory object graph, serialized config, or both?
|
||||
|
||||
Reference in New Issue
Block a user