thejayman77/trikkeSensors
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

tighten transport failure semantics

Browse Source
This commit is contained in:
Jay
2026-08-17 17:33:44 -04:00
parent 3c95f3d7be
commit 73e5680fc3
11 changed files with 144 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/binary-record-v1.md
+10 -6
View File
@@ -89,11 +89,13 @@ new samples rather than overwriting older ones; sequence gaps and the cumulative
lost-sample counter expose that permanent loss.
The shared transport state machine distinguishes three nonfatal states. `RETRY`
means zero bytes were accepted and the complete frame may be submitted again.
`PENDING` means the backend owns an in-flight frame, so firmware may only poll
that transfer. `COMPLETE` permits the output task to reuse its packet buffer and
consume more samples. This prevents a timeout after partial progress from
causing an ambiguous whole-frame duplicate.
is valid only from initial submission: it means zero bytes were accepted and the
complete frame may be submitted again. `PENDING` means the backend owns an
in-flight frame, so firmware may only poll that transfer. A `RETRY` returned by
polling fails closed as `FATAL`, because generic code cannot prove whole-frame
resubmission is duplicate-safe. `COMPLETE` permits the output task to reuse its
packet buffer and consume more samples. This prevents a timeout after partial
progress from causing an ambiguous whole-frame duplicate.
The direct USB Serial/JTAG backend atomically copies a complete frame into its TX
ring, then polls a bounded transmit-drain wait. A timeout remains `PENDING`; it
@@ -104,7 +106,9 @@ USB drain is not end-to-end application delivery confirmation. A host process
may attach after earlier frames have already left the endpoint, or fail after
the endpoint accepts them. CRC and sequence checks make resulting loss visible,
but an application acknowledgement and replay window are still required to
guarantee receipt.
guarantee receipt. Accordingly, USB `COMPLETE` means endpoint drain, while the
planned reliable BLE backend will reserve `COMPLETE` for an application ACK of
the exact frame.
Receivers report bytes left in an incomplete trailing frame when capture ends.
Those bytes cannot pass CRC validation and are not silently admitted as samples.