Skip to content

Commit 109da40

Browse files
committed
[docs] specify bounded native USB workspace readout
Signed-off-by: Viwat Vchirawongkwin <viwat.v@chula.ac.th>
1 parent 96497b9 commit 109da40

2 files changed

Lines changed: 35 additions & 0 deletions

File tree

‎docs/specifications/firmware/specs.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -572,6 +572,34 @@ start in that case. Inspection MUST neither rerun mounting nor modify media.
572572
Fresh source-bound performance/resource and physical qualification gates
573573
apply to all five changed images; the observer does not waive those gates.
574574

575+
**Native-USB acquisition-tool output amendment (2026-09-06).** The maintained
576+
host acquisition tool MUST preserve the same single device-generated
577+
`PYBLE_WORKSPACE_OBSERVATION:` JSON line when inspecting native-USB refusal
578+
recovery. With deasserted DTR, the pinned native CDC output path may overwrite
579+
pending bytes; a successful short UID response does not prove a longer
580+
unpaced observation print will be complete. For the exact Waveshare and Pico
581+
profiles, generate the observation once, serialize once, require an ASCII
582+
line of at most 1,024 bytes, and emit it through `sys.stdout.write` in chunks
583+
of at most 16 characters with a 50 ms delay after each chunk. A 100 ms drain
584+
interval precedes and follows output. No extra framing, per-chunk newlines,
585+
hex encoding, host-created observation fields, or repair of missing bytes is
586+
allowed. The leading and trailing newline and all JSON bytes are unchanged.
587+
The maximum deliberately requested pacing is 3,400 ms; the existing absolute
588+
12-second stdout read deadline, transcript bound, exact raw-REPL delimiters,
589+
empty-stderr requirement, and outer acquisition deadline remain fail-closed.
590+
591+
This is transient host-test-tool generated inspection code, not firmware image
592+
code or an app workflow change. DTR and RTS remain deasserted, raw-REPL entry
593+
must not soft-reset the VM, the exact physical UID must be checked first, and
594+
the sealed boot getter is called only once for the fresh challenge. All
595+
candidate/source, nonce, actual media readback, advertisement, and publication
596+
gates remain unchanged. The original raw bytes, including failed captures,
597+
must be retained. Other observation transports retain their existing behavior.
598+
An adversarial overwritable-FIFO host test must demonstrate the old long-print
599+
loss and exact paced output under an explicit bounded drain model. A stdout
600+
write return is not delivery proof. Host tests do not establish USB scheduling
601+
guarantees or replace final-candidate HIL.
602+
575603
The complete-device erased scan accepts a read status only when it is `None`,
576604
boolean `True`, or exact integer zero, matching successful native block-read
577605
outcomes. Boolean `False` is a failed read, not integer-zero success. Floating

‎tests/firmware_tests/hil/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,13 @@ all derived acquisition siblings. Detailed fields and fail-closed predicates
9999
are frozen in firmware specs §4.7 and §5.3.4. Changes to the observer require
100100
fresh five-profile build, resource/performance, and physical qualification.
101101

102+
The host-generated native-USB refusal query paces the same one JSON line in
103+
16-character stdout writes, separated by 50 ms, with a 1,024-byte ASCII ceiling
104+
and bounded pre/post drain intervals. This avoids one-shot FIFO pressure while
105+
leaving DTR/RTS and the original VM boot unchanged. It is not a new receipt
106+
format or a guarantee of delivery: missing bytes, delimiters, nonce, or fields
107+
still fail the existing parser and acquisition. Keep failed raw captures.
108+
102109
Use `v061_workspace_acquire.py` for the physical acquisition, with a clean
103110
qualification checkout, protected final candidate, reviewed mode-`0600`
104111
private binding JSON, and a new receipt filename in a private directory:

0 commit comments

Comments
 (0)