From 50dc940e13245da57660bfb040abd194cec88c26 Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Mon, 24 Aug 2026 13:05:24 -0500 Subject: [PATCH 1/6] uci: bound net_poll's copy by the request; $8A is UDP-only, $8B breadcrumb (#140) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit net_poll took the SOCKET_READ response header straight into uci_poll_rem and copied, surviving a wild header only because the copy loop re-checks ring-full and DATA_AV per byte. Measured on a U64E (fw 3.14d, real github.com session): a 512 B request with ~690 B queued is answered with header $FFFF; a 22 B request with 22 B queued with $0016. On TCP the header is a count only when the queue fits the request, and the $FFFF sentinel otherwise. So c64-wireguard's drop-on-over-claim check does not port: a first cut of it aborted every real handshake at the first read (two runs). What lands instead is a bound — the copy count is capped at uci_req_len, the request this poll actually made; bytes beyond it were never delivered and stay queued, so nothing is lost. $8A UCI_ERR_LONG_READ keeps c64-wireguard's datagram disposition and is never emitted here. A header above the request that is NOT $FFFF — a value the firmware has no documented mode for — leaves $8B UCI_ERR_BAD_READ_HDR as a best- effort breadcrumb (C=0, copy still capped, §13.1 short-write pattern), allocated in c64-lib-contract SPEC §13.2's table (#139) before use. Evidence: cap-only build PASS on the U64E at 48 MHz, github.com HTTP 200, CFIN 48.5 s, PRG eccb7ec7. The cap+$8B build (2396d97d) hit $88 NO_SOCKET at TCP_CONNECT 2/2 — the device's after-N-loads connect degradation, before net_poll runs — so its twelve added bytes are hardware-unverified today; stated on the PR rather than claimed. rig_https_local/_live now dump uci_req_len/uci_read_hdr post-mortem. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 7 ++++- docs/engineering-notes.md | 52 ++++++++++++++++++++++++++++++++++ src/net/uci/net.s | 55 ++++++++++++++++++++++++++++++------ src/net/uci/uci_errors.inc | 22 +++++++++++---- tools/uci/rig_https_live.py | 1 + tools/uci/rig_https_local.py | 2 +- 6 files changed, 122 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 580600d4..c0511c7d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,7 +184,12 @@ drops a symbol fails the link by name on both backends. Surface: - Error codes: ip65 `$40-$7F` (`ip65_errors.inc`, `NET_ERR_IP65_*`), UCI `$80-$BF` (`uci_errors.inc`, `UCI_ERR_*`). The UCI range is ONE namespace shared with c64-wireguard — `$8A UCI_ERR_LONG_READ` is theirs - and reserved here; allocate new codes in SPEC §13.2's table first. + and UDP-only: on TCP the SOCKET_READ header is not a delivered count + (fw 3.14d answers a 512 B request with `$FFFF` on every session), so + `net_poll` caps the copy at the request and never emits `$8A` (#140); + a header above the request that is NOT `$FFFF` leaves the breadcrumb + `$8B UCI_ERR_BAD_READ_HDR` (C=0, stream continues). Allocate new codes + in SPEC §13.2's table first — `$8B` was the first one allocated that way. - Gone, per §13.1: `net_tcp_set_recv_cb` (stub), `net_recv_ready`, `net_dhcp` (alias), and `net_print_ip` — IP printing is consumer UI and is now `print_local_ip` in `boot.s`, one copy for both backends. diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index a7931020..7da6e7e2 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -2839,3 +2839,55 @@ region ends); hashes changed, as they must. 2026-08-24 and only a cross-repo diff noticed. - c64-wireguard#48 keeps its own items (UDP-family renames, manifests); `d9cd021`'s ring clamp is flagged there as §13.3 context for wg#46. + +### #140 — the SOCKET_READ header is not a length (same day) + +Filed by the c64-wireguard lane while reviewing the above: `net_poll` took +the response header straight into `uci_poll_rem` and copied; a wild +header was survived only because the copy loop re-checks ring-full and +DATA_AV per byte. They had learned it the hard way — c64-wireguard PR #62 +trusted the header and copied ~18 KB through `$D000`, leaving packet +bytes in the VIC registers. + +**First cut, and why it was wrong.** Ported their UDP check verbatim: +compare the header to `uci_req_len`, and on an over-claim drop the +response, emit `$8A UCI_ERR_LONG_READ`, mark the socket `NET_TCP_ERROR`. +It fired on **every** real github.com session, at the first poll, with +the ring empty (`tls_last_state=2`). Adding the pair to the rig's +post-mortem dump gave the numbers: + + uci_req_len $0200 + uci_read_hdr $FFFF + +fw 3.14d answers a 512 B TCP `SOCKET_READ` with `$FFFF` — the same +sentinel c64-wireguard measured for a 1500 B UDP request. On TCP the +header is not a delivered count; the FIFO simply delivers what it has +(bounded by the request) and `DATA_AV` drops. "Over-claim" is therefore +routine on this path and the wrong frame for a code; a drop would abort +every handshake, which is exactly what it did. + +**What landed instead**: the copy count is capped at `uci_req_len` — a +memory-safety bound, not an error. Bytes beyond the request were never +delivered (they stay in the firmware for the next poll), so the cap loses +nothing. `$8A` stays reserved with c64-wireguard's UDP meaning (datagram +length exceeded the request → datagram dropped) and this adapter never +emits it; the registry row in c64-lib-contract#139 is being reworded to +scope the meaning by transport, because two UCI-family adapters were +about to give one byte two operational meanings — the `$88` failure one +row down, caught by the cross-repo view a second time in one release +cycle. + +The reverse port — our ring-free clamp into c64-wireguard — does NOT +apply either: their inbound is a flat interlocked buffer with no wrap, +and on 3.14d any request size other than 512 breaks their read path +outright (GideonZ/1541ultimate#802). + +**Detector kept.** A bare cap would also have normalised a third case — +a header above the request that is *not* `$FFFF`, which the firmware has +no documented mode for — silently. The review on c64-lib-contract#139 +asked for that to stay distinguishable, and it does: `$8B +UCI_ERR_BAD_READ_HDR`, a best-effort breadcrumb on the §13.1 short-write +pattern (copy still capped, C=0, stream continues, code left in +`net_last_error`). Allocated in SPEC §13.2's table before the adapter +emitted it — the first code to go through the rule the table exists for. + diff --git a/src/net/uci/net.s b/src/net/uci/net.s index 2e3590ec..433da499 100644 --- a/src/net/uci/net.s +++ b/src/net/uci/net.s @@ -10,15 +10,13 @@ ; GET_IPADDR command. Does NOT run DHCP ourselves — ; the firmware already did that before the PRG started. ; -; Exports two symbol families: -; -; (a) net_abi.inc contract — the long-term public names. -; (b) legacy caller names currently imported by boot.s / http.s / -; tls_record_io.s — kept as thin aliases until those callers are -; migrated onto net_abi.inc in a later phase. -; -; Also publishes `net_banner_str`, the backend-specific banner line -; consumed by boot.s's startup print. +; Exports exactly the surface src/net_abi.inc imports (c64-lib-contract +; SPEC §13 core/TCP/DNS families, issue #70) plus the two c64-https +; extensions declared there: net_recv_byte (the drain entry) and +; net_banner_str (the backend-specific banner line boot.s prints). +; Error codes live in uci_errors.inc, in the §13.2 UCI range $80-$BF, +; which is ONE namespace shared with c64-wireguard — allocate in SPEC +; §13.2's table first. .include "uci_regs.inc" .include "uci_errors.inc" @@ -292,6 +290,45 @@ net_poll: rts @have_data: + ; --- Bound the copy by the request (#140, SPEC §13.3) -------------- + ; The response header is NOT a delivered-byte count on the TCP + ; SOCKET_READ path. Measured on fw 3.14d (U64E, 2026-08-24, real + ; github.com session, first poll, ring empty): request $0200, + ; header $FFFF — the same sentinel c64-wireguard saw for a 1500 B + ; UDP request. The copy below used to survive that only because it + ; re-checks ring-full and DATA_AV per byte; a refactor of the loop + ; would have turned the header into a runaway copy. So the count is + ; capped at uci_req_len — what this poll actually asked for, which + ; the ring clamp above may have made smaller than UCI_READ_CHUNK_MAX. + ; Bytes beyond the request were never delivered (they stay in the + ; firmware for the next poll), so capping loses nothing and is not + ; a trim of real data. A drop-and-error here (the first cut of this + ; check, emitting UCI_ERR_LONG_READ) aborted every real handshake at + ; ServerHello: "header > request" is routine on TCP, so $8A is a + ; UDP-path code and this adapter never emits it. + lda uci_req_len+0 + cmp uci_poll_rem+0 + lda uci_req_len+1 + sbc uci_poll_rem+1 ; C=1 iff req >= header (16-bit) + bcs @len_bounded + ; header > request. $FFFF is the firmware's routine "more than you + ; asked" sentinel; anything else above the request is a header the + ; firmware has no documented mode for. Leave a breadcrumb for that + ; case ($8B, best-effort: C=0, stream continues — the cap below + ; makes it safe either way) so a post-mortem can tell the two + ; apart. Allocated in c64-lib-contract SPEC §13.2 before use. + lda uci_poll_rem+0 + and uci_poll_rem+1 + cmp #$FF + beq @len_cap ; $FFFF sentinel — routine, no breadcrumb + lda #UCI_ERR_BAD_READ_HDR + sta net_last_error +@len_cap: + lda uci_req_len+0 + sta uci_poll_rem+0 + lda uci_req_len+1 + sta uci_poll_rem+1 +@len_bounded: ; Copy exactly (uci_poll_rem) bytes from UCI_RESP_DATA into the ; ring at tcp_recv_buf + tcp_recv_tail, advancing the masked tail. ; The store uses SMC on @rb_store so we can hit the full 4 KB diff --git a/src/net/uci/uci_errors.inc b/src/net/uci/uci_errors.inc index 3107962b..f2c1fd73 100644 --- a/src/net/uci/uci_errors.inc +++ b/src/net/uci/uci_errors.inc @@ -21,12 +21,22 @@ UCI_ERR_READ_FAIL = $86 ; SOCKET_READ returned an error bit UCI_ERR_SHORT_WRITE = $87 ; SOCKET_WRITE wrote fewer bytes than requested UCI_ERR_NO_SOCKET = $88 ; socket-open response yielded no socket_id UCI_ERR_WAIT_TIMEOUT = $89 ; a bounded wait exceeded its wall-clock budget -UCI_ERR_LONG_READ = $8A ; SOCKET_READ claimed more bytes than we asked - ; for. Allocated by c64-wireguard (2026-08-24); - ; reserved here with the same meaning. This - ; adapter does not emit it yet — net_poll - ; stops at DATA_AV rather than checking the - ; claimed length against the request. +UCI_ERR_LONG_READ = $8A ; UDP path (c64-wireguard, 2026-08-24): + ; SOCKET_READ reported a datagram length + ; exceeding the request; the datagram is + ; dropped. Reserved here, NEVER emitted: on + ; the TCP path the header is not a delivered + ; count (fw 3.14d answers a 512 B request with + ; $FFFF on every session), so net_poll caps the + ; copy at the request instead (#140). +UCI_ERR_BAD_READ_HDR = $8B ; SOCKET_READ header exceeded the request and + ; was NOT the $FFFF sentinel — a value the + ; firmware has no documented mode for. Best- + ; effort breadcrumb (§13.1 short-write pattern): + ; the copy is still capped at the request and + ; net_poll returns normally; the code stays in + ; net_last_error for post-mortems. Allocated in + ; SPEC §13.2's table first (c64-lib-contract#139). ; TCP state values stored in net_tcp_state. The NET_TCP_* spellings in ; net_states.inc are the contract's (§13.1); these aliases keep the diff --git a/tools/uci/rig_https_live.py b/tools/uci/rig_https_live.py index dca7a39d..3df5a856 100644 --- a/tools/uci/rig_https_live.py +++ b/tools/uci/rig_https_live.py @@ -338,6 +338,7 @@ def main() -> int: "net_init", "net_initialized", "uci_socket_id", "net_last_error", "net_tcp_state", "tcp_recv_head", "tcp_recv_tail", + "uci_req_len", "uci_read_hdr", # #140: SOCKET_READ request vs claim "http_resp_buf", "http_resp_len", "http_status", "tls_state", "tls_last_state", ] diff --git a/tools/uci/rig_https_local.py b/tools/uci/rig_https_local.py index 8ce272fe..bd74b3f9 100644 --- a/tools/uci/rig_https_local.py +++ b/tools/uci/rig_https_local.py @@ -715,7 +715,7 @@ def r16(name: str) -> int: "tls_recv_progress", "tls_recv_sub_progress"): if name in labels: print(f" {name:22s} : 0x{r8(name):02X}") - for name in ("tcp_recv_head", "tcp_recv_tail", + for name in ("tcp_recv_head", "tcp_recv_tail", "uci_req_len", "uci_read_hdr", "http_status", "http_resp_len"): if name in labels: print(f" {name:22s} : ${r16(name):04X}") From a22e27c034bf35942692100985fb96268495c82d Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Mon, 24 Aug 2026 13:09:52 -0500 Subject: [PATCH 2/6] =?UTF-8?q?uci:=20$FFFF=20is=20the=20SOCKET=5FREAD=20n?= =?UTF-8?q?o-data=20sentinel=20on=20both=20transports=20=E2=80=94=20commen?= =?UTF-8?q?ts=20and=20docs=20corrected=20(#140)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Code unchanged (byte-identical PRG): the cap plus the DATA_AV check already copy zero bytes on the sentinel. What was wrong was every comment saying $FFFF meant 'more than you asked': the first-poll $FFFF was an idle poll waiting for ServerHello, as c64-wireguard's idle-UDP measurement (11/11 sizes) makes clear. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 11 +++++----- docs/engineering-notes.md | 16 ++++++++++++++ src/net/uci/net.s | 43 +++++++++++++++++++------------------- src/net/uci/uci_errors.inc | 25 ++++++++++++---------- 4 files changed, 58 insertions(+), 37 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c0511c7d..9d1fb4f0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,11 +184,12 @@ drops a symbol fails the link by name on both backends. Surface: - Error codes: ip65 `$40-$7F` (`ip65_errors.inc`, `NET_ERR_IP65_*`), UCI `$80-$BF` (`uci_errors.inc`, `UCI_ERR_*`). The UCI range is ONE namespace shared with c64-wireguard — `$8A UCI_ERR_LONG_READ` is theirs - and UDP-only: on TCP the SOCKET_READ header is not a delivered count - (fw 3.14d answers a 512 B request with `$FFFF` on every session), so - `net_poll` caps the copy at the request and never emits `$8A` (#140); - a header above the request that is NOT `$FFFF` leaves the breadcrumb - `$8B UCI_ERR_BAD_READ_HDR` (C=0, stream continues). Allocate new codes + and datagram-only. **`$FFFF` is the SOCKET_READ no-data sentinel on both + transports** (idle polls answer it) and must be excluded before any + over-claim test — both fleet adapters misfiled it independently (#140). + `net_poll` caps the copy at the request and never emits `$8A`; a header + above the request that is NOT `$FFFF` leaves `$8B UCI_ERR_BAD_READ_HDR` + (C=0, stream continues) — the stream-family counterpart of `$8A`. Allocate new codes in SPEC §13.2's table first — `$8B` was the first one allocated that way. - Gone, per §13.1: `net_tcp_set_recv_cb` (stub), `net_recv_ready`, `net_dhcp` (alias), and `net_print_ip` — IP printing is consumer UI and diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index 7da6e7e2..a6776f73 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -2891,3 +2891,19 @@ pattern (copy still capped, C=0, stream continues, code left in `net_last_error`). Allocated in SPEC §13.2's table before the adapter emitted it — the first code to go through the rule the table exists for. +**Correction, same evening — `$FFFF` is the no-data sentinel.** The +c64-wireguard lane measured every *idle* UDP `SOCKET_READ` returning +header `$FFFF`, `rx_len` 0, across 11 sizes. Re-reading our own capture: +`tls_last_state=2` means the first polls after ClientHello, while +ServerHello is still in flight — idle polls. "~690 B queued" above was +an inference, not a measurement, and the mechanism note warned against +exactly that. So `$FFFF` is the firmware's no-data sentinel on both +transports; the drop-and-error cut aborted on an empty read, and +c64-wireguard's "`$8A` fires routinely during healthy sessions" runbook +line was the same misfiling, documented as a firmware quirk for four +days. The shipped code is unaffected (cap, then the `DATA_AV` check +copies zero bytes) but every comment that said "more than you asked" +was wrong and is corrected. Registry rows now pair `$8A` (datagram: +drop, terminal) with `$8B` (stream: cap, advisory) as one observation +with family-specific disposition, and require excluding `$FFFF` first. + diff --git a/src/net/uci/net.s b/src/net/uci/net.s index 433da499..00f4e726 100644 --- a/src/net/uci/net.s +++ b/src/net/uci/net.s @@ -291,32 +291,33 @@ net_poll: @have_data: ; --- Bound the copy by the request (#140, SPEC §13.3) -------------- - ; The response header is NOT a delivered-byte count on the TCP - ; SOCKET_READ path. Measured on fw 3.14d (U64E, 2026-08-24, real - ; github.com session, first poll, ring empty): request $0200, - ; header $FFFF — the same sentinel c64-wireguard saw for a 1500 B - ; UDP request. The copy below used to survive that only because it - ; re-checks ring-full and DATA_AV per byte; a refactor of the loop - ; would have turned the header into a runaway copy. So the count is - ; capped at uci_req_len — what this poll actually asked for, which - ; the ring clamp above may have made smaller than UCI_READ_CHUNK_MAX. - ; Bytes beyond the request were never delivered (they stay in the - ; firmware for the next poll), so capping loses nothing and is not - ; a trim of real data. A drop-and-error here (the first cut of this - ; check, emitting UCI_ERR_LONG_READ) aborted every real handshake at - ; ServerHello: "header > request" is routine on TCP, so $8A is a - ; UDP-path code and this adapter never emits it. + ; The response header is not a delivered-byte count. On fw 3.14d + ; $FFFF is the NO-DATA sentinel on both transports (c64-wireguard: + ; every idle UDP poll; here: the idle polls after ClientHello while + ; ServerHello is still in flight answer $FFFF to a 512 B request). + ; The copy below survived it only because it re-checks ring-full + ; and DATA_AV per byte and so copied zero bytes; a refactor of the + ; loop would have turned the header into a runaway copy. So the + ; count is capped at uci_req_len — what this poll actually asked + ; for, which the ring clamp above may have made smaller than + ; UCI_READ_CHUNK_MAX. Bytes beyond the request were never delivered + ; (they stay queued for the next poll), so the cap loses nothing. + ; A drop-and-error here (the first cut, emitting UCI_ERR_LONG_READ) + ; aborted every real handshake on its first idle poll — the same + ; misfiling c64-wireguard carried for four days as a "firmware + ; quirk". $FFFF MUST be excluded before any over-claim test. lda uci_req_len+0 cmp uci_poll_rem+0 lda uci_req_len+1 sbc uci_poll_rem+1 ; C=1 iff req >= header (16-bit) bcs @len_bounded - ; header > request. $FFFF is the firmware's routine "more than you - ; asked" sentinel; anything else above the request is a header the - ; firmware has no documented mode for. Leave a breadcrumb for that - ; case ($8B, best-effort: C=0, stream continues — the cap below - ; makes it safe either way) so a post-mortem can tell the two - ; apart. Allocated in c64-lib-contract SPEC §13.2 before use. + ; header > request. $FFFF is the no-data sentinel (routine, copied + ; as zero bytes by the DATA_AV check); anything else above the + ; request is a header the firmware has no documented mode for. + ; Leave a breadcrumb for that case ($8B, best-effort: C=0, stream + ; continues — the cap below makes it safe either way) so a + ; post-mortem can tell the two apart. Allocated in c64-lib-contract + ; SPEC §13.2 before use; the datagram-family counterpart is $8A. lda uci_poll_rem+0 and uci_poll_rem+1 cmp #$FF diff --git a/src/net/uci/uci_errors.inc b/src/net/uci/uci_errors.inc index f2c1fd73..98e82ae0 100644 --- a/src/net/uci/uci_errors.inc +++ b/src/net/uci/uci_errors.inc @@ -21,17 +21,20 @@ UCI_ERR_READ_FAIL = $86 ; SOCKET_READ returned an error bit UCI_ERR_SHORT_WRITE = $87 ; SOCKET_WRITE wrote fewer bytes than requested UCI_ERR_NO_SOCKET = $88 ; socket-open response yielded no socket_id UCI_ERR_WAIT_TIMEOUT = $89 ; a bounded wait exceeded its wall-clock budget -UCI_ERR_LONG_READ = $8A ; UDP path (c64-wireguard, 2026-08-24): - ; SOCKET_READ reported a datagram length - ; exceeding the request; the datagram is - ; dropped. Reserved here, NEVER emitted: on - ; the TCP path the header is not a delivered - ; count (fw 3.14d answers a 512 B request with - ; $FFFF on every session), so net_poll caps the - ; copy at the request instead (#140). -UCI_ERR_BAD_READ_HDR = $8B ; SOCKET_READ header exceeded the request and - ; was NOT the $FFFF sentinel — a value the - ; firmware has no documented mode for. Best- +UCI_ERR_LONG_READ = $8A ; Datagram family (c64-wireguard): the + ; SOCKET_READ header claimed more than the + ; request and was NOT the $FFFF no-data + ; sentinel; the datagram is dropped. Reserved + ; here, NEVER emitted: on a stream the same + ; observation is $8B below. $FFFF is the + ; firmware's no-data sentinel on BOTH + ; transports and must be excluded before any + ; over-claim test (#140; both adapters got + ; this wrong independently). +UCI_ERR_BAD_READ_HDR = $8B ; Stream family: SOCKET_READ header exceeded + ; the request and was NOT the $FFFF no-data + ; sentinel — a value the firmware has no + ; documented mode for. Best- ; effort breadcrumb (§13.1 short-write pattern): ; the copy is still capped at the request and ; net_poll returns normally; the code stays in From a4f9274b85072b47ef1a11cb429aba8ceef4ec2b Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Mon, 24 Aug 2026 13:12:58 -0500 Subject: [PATCH 3/6] =?UTF-8?q?uci:=20$8A/$8B=20are=20reserved=20defensive?= =?UTF-8?q?ly=20=E2=80=94=20no=20non-sentinel=20over-claim=20has=20been=20?= =?UTF-8?q?observed=20(#140)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/engineering-notes.md | 14 ++++++++++++++ src/net/uci/uci_errors.inc | 7 +++++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index a6776f73..047fff68 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -2907,3 +2907,17 @@ was wrong and is corrected. Registry rows now pair `$8A` (datagram: drop, terminal) with `$8B` (stream: cap, advisory) as one observation with family-specific disposition, and require excluding `$FFFF` first. +**And the founding incident retires too.** The contract reviewer went +back to c64-wireguard PR #62 (`6fecc97`), the commit `$8A` was born +on: its own message says the copy count came straight from the header +into a loop whose SMC store bumps its own high byte, from a buffer at +`$89D4`. `$FFFF` = 65535 as a copy count from an idle poll writes +straight through `$D000` — the ~18 KB, the VIC damage, all of it, with +no firmware over-claim involved. So after excluding the sentinel there +is **no measured non-sentinel over-claim on either transport**; `$8A` +and `$8B` are reserved defensively, and the registry says so. The rule +that travels: exclude the sentinel before any length arithmetic, and +never let a device-supplied count be the only bound on a store loop — +which is what the cap in `net_poll` now guarantees regardless of what +the header says. + diff --git a/src/net/uci/uci_errors.inc b/src/net/uci/uci_errors.inc index 98e82ae0..2cbe650d 100644 --- a/src/net/uci/uci_errors.inc +++ b/src/net/uci/uci_errors.inc @@ -29,8 +29,11 @@ UCI_ERR_LONG_READ = $8A ; Datagram family (c64-wireguard): the ; observation is $8B below. $FFFF is the ; firmware's no-data sentinel on BOTH ; transports and must be excluded before any - ; over-claim test (#140; both adapters got - ; this wrong independently). + ; length arithmetic (#140; both adapters got + ; this wrong independently). No non-sentinel + ; over-claim has been observed on either + ; transport; both codes are reserved + ; defensively. UCI_ERR_BAD_READ_HDR = $8B ; Stream family: SOCKET_READ header exceeded ; the request and was NOT the $FFFF no-data ; sentinel — a value the firmware has no From 3e7639c012fa1f9b49fcae82b46e9e22709bc08b Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Tue, 25 Aug 2026 12:56:16 -0500 Subject: [PATCH 4/6] =?UTF-8?q?notes:=20UDP=20header=20measured=20by=20the?= =?UTF-8?q?=20c64-wireguard=20lane=20=E2=80=94=20no=20observable=20over-cl?= =?UTF-8?q?aim=20on=20either=20transport=20(#140)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/engineering-notes.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index 047fff68..df04519b 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -2921,3 +2921,17 @@ never let a device-supplied count be the only bound on a store loop — which is what the cap in `net_poll` now guarantees regardless of what the header says. + +**The UDP header, measured (c64-wireguard lane, 2026-08-25, fresh power +cycle, each row repeated):** 600/768/1024/1280 B datagrams against a +512 B request all return `rx_len` 512 and header `$0200` — the delivered +count, never the true size, never above the request. So on 3.14d the +over-claim condition has **no observable trigger on either transport**: +TCP's header is a sentinel on idle polls, UDP's is the delivered count. +The two transports are not uniform, and each adapter had generalised +from its own to the other. Consequences recorded in c64-lib-contract#139: +`$8A`/`$8B` stay allocated but the "adapter drops it" clause is gone — +a truncated 1280 B datagram is byte-identical to a complete 512 B one in +every readable register, so truncation is silent and the consumer's MTU +pin is the sole defence (now stated in SPEC §13.3). For c64-https the +TCP cap in `net_poll` (#143) remains the right bound and is unaffected. From 5ae269560d0cbf976ab79ee76a483273cbb4d29b Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Wed, 26 Aug 2026 06:50:00 -0500 Subject: [PATCH 5/6] uci: cap-shape-independent 16-bit clamp in net_poll; 512 is a consumer constant, real SOCKET_READ ceiling is 894 (#140) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old clamp (cmp #>MAX / bcc / bne / lda lo / beq) accepted the equal-high-byte case only when the low byte was zero — right for $0200, wrong for any other cap, and in this direction it would have raised a sub-cap request to the cap (the wikipedia-stall class). c64-wireguard hit the same shape at $037D and read it as firmware misbehaviour. Rewritten as a full 16-bit compare; UCI_READ_CHUNK_MAX stays 512 but its comment now states the real ceiling (894, never exactly 894 on 3.14d), where 512 came from, and why raising it is a measured follow-up (per-byte fence cost at stock speed). Co-Authored-By: Claude Fable 5 --- docs/engineering-notes.md | 30 ++++++++++++++++++++++++++++++ src/net/uci/net.s | 18 +++++++++++------- src/net/uci/uci_errors.inc | 14 ++++++++++++-- 3 files changed, 53 insertions(+), 9 deletions(-) diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index df04519b..de2f12fe 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -2935,3 +2935,33 @@ a truncated 1280 B datagram is byte-identical to a complete 512 B one in every readable register, so truncation is silent and the consumer's MTU pin is the sole defence (now stated in SPEC §13.3). For c64-https the TCP cap in `net_poll` (#143) remains the right bound and is unaffected. + +**Correction (c64-wireguard lane, 2026-08-26): the 512 cap was theirs, and +ours.** `UCI_READ_CHUNK_MAX = 512` was c64-wireguard's Phase 3 MVP +constant; having only ever asked for 512 they measured only ever +receiving 512 and reported it as a firmware ceiling — and our +`uci_errors.inc` says the same "conservative MVP choice". The real cap is +**894** = `CMD_MAX_REPLY_LEN` (896) − 2 (GideonZ/1541ultimate#802, +root-caused by chrisgleissner, re-measured on a U64E: 512-893 B datagrams +arrive whole with the header reporting the TRUE length). A 1024 request +is rejected with `82,PARAMETER(S) OUT OF RANGE` on STATUS — which our +adapter, like theirs, drains without reading. **Never request exactly +894 on 3.14d**: it fills the response queue exactly and the FPGA repeats +it forever. So "the header never reports the true length" was an +artifact of always truncating; the indistinguishability problem is real +only for genuinely oversized datagrams. Unchanged: no non-sentinel +over-claim observed; `$FFFF` is `lwip_recv()` returning −1 stored as +signed 16-bit. + +Two consequences here. (1) Our clamp had the same latent trap the +wireguard lane hit when their cap moved to `$037D`: `cmp #>MAX / bcc / +bne / lda lo / beq` accepts the equal-high-byte case only when the low +byte is zero — correct for `$0200`, wrong for any other cap, and in our +direction it would have *raised* a sub-cap request to the cap, i.e. the +wikipedia-stall class. Rewritten as a full 16-bit compare in #143 so +the constant can move. (2) Raising `UCI_READ_CHUNK_MAX` toward 893 is a +plausible throughput win on TCP (fewer ~40 ms round-trips per flight) +but every byte read carries a fence (~5.45 ms at 1 MHz), so it is a +measured follow-up, not a free change — and any test around it should +find the accepted length by bisection, not hard-code it. + diff --git a/src/net/uci/net.s b/src/net/uci/net.s index 00f4e726..514cf95d 100644 --- a/src/net/uci/net.s +++ b/src/net/uci/net.s @@ -166,14 +166,18 @@ net_poll: bne :+ rts ; ring effectively full — poll again later : - ; clamp to UCI_READ_CHUNK_MAX (512 = $0200) - lda uci_req_len+1 - cmp #>UCI_READ_CHUNK_MAX - bcc @len_clamped ; high < 2 -> under 512, keep - bne @len_use_max ; high > 2 -> over, clamp + ; clamp to UCI_READ_CHUNK_MAX — full 16-bit compare. The previous + ; shape (cmp #>MAX / bcc / bne / lda lo / beq) accepted the + ; equal-high-byte case only when the low byte was zero: correct + ; for $0200, silently wrong for any other cap (c64-wireguard hit + ; exactly that at $037D and read the result as firmware + ; misbehaviour). Written cap-shape-independently so raising the + ; constant cannot reintroduce it. lda uci_req_len+0 - beq @len_clamped ; exactly 512, keep -@len_use_max: + cmp #UCI_READ_CHUNK_MAX ; C=1 iff req >= MAX + bcc @len_clamped ; req < MAX -> keep lda #UCI_READ_CHUNK_MAX diff --git a/src/net/uci/uci_errors.inc b/src/net/uci/uci_errors.inc index 2cbe650d..eb86a600 100644 --- a/src/net/uci/uci_errors.inc +++ b/src/net/uci/uci_errors.inc @@ -56,6 +56,16 @@ UCI_TCP_CONNECT_FAIL = NET_TCP_CONNECT_FAIL UCI_DATA_QUEUE_MAX = 800 ; SOCKET_READ max-length cap we ask for per net_poll cycle. -; 512 bytes is well under the 4 KB ring and the firmware data queue, -; and matches the conservative Phase 3 MVP choice. +; +; 512 is a CONSUMER choice, not the firmware's limit — it was c64-wireguard's +; Phase 3 MVP constant, and both repos carried it as a hardware ceiling +; because nothing larger had ever been requested. The real ceiling is 894 +; (= CMD_MAX_REPLY_LEN 896 - the 2-byte header; GideonZ/1541ultimate#802, +; re-measured on a U64E: 512-893 B arrive whole in one poll). NEVER request +; exactly 894 on fw 3.14d: the reply exactly fills the response queue and +; the FPGA repeats it forever with DATA_AV asserted (guard only in 3.15, +; not downloadable). Raising this toward 893 is a measured follow-up, not a +; free win: every byte read carries a uci_fence (~5.45 ms at 1 MHz), and +; net_poll's clamp is written cap-shape-independently so the change is one +; constant. UCI_READ_CHUNK_MAX = 512 From 6e07f2419dffb644275ffcfcd63c366aaee4ef9d Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Fri, 28 Aug 2026 14:11:19 -0500 Subject: [PATCH 6/6] uci: scope the SOCKET_READ ceiling to firmware, and qualify $86 (#140) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two accuracy fixes, both comment/doc-only — the PRG is byte-identical (4a1a9fe5…, the image hardware-verified against github.com today). The read ceiling is firmware-dependent and 894 was only ever 3.14d's. GideonZ/1541ultimate#806 is merged and shipping in the 3.15 build now on the U64E: it accepts up to 1472 and the 894 hang is gone, but a reply over 893 payload bytes is split across response blocks via Data More, and the 2-byte header then counts the whole command rather than the first block. net_poll reads ONE block, so 893 — not 894, not 1472 — is our cap on either firmware, and going past it needs a multi-block reader first. UCI_READ_CHUNK_MAX is unchanged at 512. $86 was documented as the wedge half of the KEYS/ENC1/RX discriminator, which invites reading a bare $86 as a wedge. net_poll sets it on any SOCKET_READ error bit, including the one that ends a normal fetch: today's PASS run dumped net_last_error=$86 alongside http_status=200 and http_get C=0. It discriminates only inside that stall. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 5 ++++- docs/engineering-notes.md | 8 ++++++++ src/net/uci/uci_errors.inc | 29 ++++++++++++++++++++--------- 3 files changed, 32 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9d1fb4f0..d6d2c6e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -278,7 +278,10 @@ it never writes device config. `C64_SKIP_REU_PREFLIGHT=1` bypasses. wall) and a REU-profile build with no REU (`net_last_error=$00` — the row-fetch DMA no-ops, the X25519 secret is wrong, the first AEAD tag fails, and it *spins* for ~44 min). Check `net_last_error`; the REU half - is now excluded by the preflight above. + is now excluded by the preflight above. `$86` discriminates only *within* + that stall: it is set on any SOCKET_READ error bit, including the one + that ends a normal fetch, so it is present in PASSING runs too + (github.com HTTP 200, 2026-08-28) and is never on its own a wedge. - **Lease poisoning**: resetting the C64 with a live firmware socket makes `GET_IPADDR` return 0.0.0.0 forever ("REQUESTING DHCP" loop). Only a wall power cycle clears it. Rigs therefore let fetches finish and send diff --git a/docs/engineering-notes.md b/docs/engineering-notes.md index de2f12fe..c304d928 100644 --- a/docs/engineering-notes.md +++ b/docs/engineering-notes.md @@ -985,6 +985,14 @@ Disabled ⇒ stalls at RX (issue #97). enable the REU, or use an onchip build (c64-https-uci-onchip.prg needs none) + `$86` is a discriminator only *inside* this stall, never on its own. + `net_poll` sets it on any SOCKET_READ error bit, and one such bit ends + an ordinary fetch: the live github.com run of 2026-08-28 finished + `http_status=200`, `http_get` C=0, and still dumped + `net_last_error=$86` with `net_tcp_state=$00` (the `$86` path forces + `NET_TCP_ERROR`, then `net_tcp_close` returns it to CLOSED). Reading a + bare `$86` as a wedge is the #97 mistake in a new costume. + `tls_recv_sub_progress` is `$02` in BOTH and distinguishes nothing. Do not act on the screen alone — that mistake was made on #97 and cost an outside contributor a wasted cold power cycle. diff --git a/src/net/uci/uci_errors.inc b/src/net/uci/uci_errors.inc index eb86a600..d353b73a 100644 --- a/src/net/uci/uci_errors.inc +++ b/src/net/uci/uci_errors.inc @@ -59,13 +59,24 @@ UCI_DATA_QUEUE_MAX = 800 ; ; 512 is a CONSUMER choice, not the firmware's limit — it was c64-wireguard's ; Phase 3 MVP constant, and both repos carried it as a hardware ceiling -; because nothing larger had ever been requested. The real ceiling is 894 -; (= CMD_MAX_REPLY_LEN 896 - the 2-byte header; GideonZ/1541ultimate#802, -; re-measured on a U64E: 512-893 B arrive whole in one poll). NEVER request -; exactly 894 on fw 3.14d: the reply exactly fills the response queue and -; the FPGA repeats it forever with DATA_AV asserted (guard only in 3.15, -; not downloadable). Raising this toward 893 is a measured follow-up, not a -; free win: every byte read carries a uci_fence (~5.45 ms at 1 MHz), and -; net_poll's clamp is written cap-shape-independently so the change is one -; constant. +; because nothing larger had ever been requested. The FIRMWARE ceiling is +; version-dependent; 893 is OURS on every version. +; +; fw 3.14d 894 = CMD_MAX_REPLY_LEN 896 - the 2-byte header +; (GideonZ/1541ultimate#802, re-measured on a U64E: +; 512-893 B arrive whole in one poll). NEVER request +; exactly 894: the reply exactly fills the response queue +; and the FPGA repeats it forever with DATA_AV asserted. +; fw 3.15 + #806 accepts up to 1472 and the 894 hang is gone, but a reply +; over 893 payload bytes comes back SPLIT across response +; blocks (the command interface's Data More mechanism), and +; the 2-byte header is then the total for the whole command +; rather than the count in the first block. net_poll reads +; ONE block, so a request above 893 would silently drop the +; continuation. +; +; So 893 is the number to raise toward on either firmware, and going past it +; needs a multi-block reader first. Not a free win either: every byte read +; carries a uci_fence (~5.45 ms at 1 MHz). net_poll's clamp is written +; cap-shape-independently so the change is one constant. UCI_READ_CHUNK_MAX = 512