diff --git a/CLAUDE.md b/CLAUDE.md index 3c00d068..36424893 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -162,7 +162,7 @@ Variables: (`cfg/c64-https-$(BACKEND).cfg`; default ip65). Changing it requires `make clean` — see above. - `USE_X25519_SIBLING=1` — swap the in-tree X25519 for the - `libs/x25519@v0.11.0` sibling. **UCI links; + `libs/x25519@v0.11.1` sibling. **UCI links; ip65 overflows CRYPTO_OVERLAY** — see "Known issues". Off by default either way. - `EMBED_P256_OVERLAY=1` — stage the P-256 verify image into the @@ -218,7 +218,7 @@ buffers in the crypto BSS — see per-module headers for details): X25519 / field arithmetic Default: in-tree `src/crypto/{x25519,fe25519}.s`. - Opt-in: sibling `libs/x25519@v0.11.0` via `make USE_X25519_SIBLING=1` + Opt-in: sibling `libs/x25519@v0.11.1` via `make USE_X25519_SIBLING=1` — links under UCI from the v0.10.1/v0.11.0 wave pins, still overflows under ip65, and ships in nothing; see Known issues. The v0.6.0 pin is c64-lib-contract-aligned (SPEC §8.1) and adds the @@ -235,7 +235,7 @@ buffers in the crypto BSS — see per-module headers for details): SHA-256 (in-tree; no sibling) sha256_init, sha256_update, sha256_final - ECDSA P-256 (`libs/nistcurves@v0.10.1` sibling, + ECDSA P-256 (`libs/nistcurves@v0.11.0` sibling, c64-lib-contract SPEC §1-§8.1 aligned) ecdsa_verify_256 — TLS dispatcher in src/crypto/ecdsa_verify.s packs the BE struct + calls the sibling entry @@ -283,9 +283,18 @@ below for the post-W1 hot/cold split): [c64-lib-contract](https://github.com/JC-000/c64-lib-contract) for the contract spec and `docs/library-ingestion-architecture.md` for the c64-https rollout plan. - - **Read `SPEC.md` on `main`, not the latest git tag.** The contract's - tags lag badly: newest tag is v0.4.0 while `main` is **v0.7.2** - (checked 2026-08-13). Sections added since v0.4.0 that bind a + - **Pin the contract tag — this advice inverted on 2026-08-15.** It + used to read "read `SPEC.md` on `main`, not the latest git tag", + because tags lagged badly (newest v0.4.0 against a v0.7.2 `main`). + v0.10.3 is the contract repo's first GitHub release and is both the + newest tag and the newest SPEC, so tag-pinning is now correct. + One caveat the release notes get wrong: they claim "every version + since v0.4.1 is tagged (gapless series)", and **0.10.1 has no tag** + (31 changelog versions against 30 tags, measured 2026-08-15). It was + a doc-only reorder, so nothing is lost — but tooling must not assume + every changelog version resolves as a ref. + + Sections added since v0.4.0 that bind a *consumer* rather than an adopter: **§13 Network backend ABI** (v0.6.0 — written from c64-https's own net surface; our intake issue [#70](https://github.com/JC-000/c64-https/issues/70) is @@ -842,8 +851,10 @@ Five latent bugs and three new ones were cleared to get here: `reu_mul_init.o` alongside the `mul_8x8.o` / `data_shared.o` drops already there. c64-https is the §8.0 APP_OWNED case for that primitive, so the member is surplus in every configuration — - and provably inert in the shipped ones, since all four REU-profile - PRGs are byte-identical with and without the drop. + and provably inert in the shipped ones, since the REU-profile PRGs + were byte-identical with and without the drop. (Measured when four + variants shipped; the lineup is three now and carries no REU-profile + image at all, so the drop is inert in the release by construction.) Note the near miss: had ld65 resolved instead of erroring, `reu_mul_init` would have bound to nistcurves' table builder @@ -890,13 +901,19 @@ Five latent bugs and three new ones were cleared to get here: `tools/test_x25519.py` RFC 7748 vector 2 — whose u ends `0x93` — passes 73/73 on the in-tree build.) - The pin is now **v0.11.0**. The v0.6.0 -> v0.10.0 migrations the + The pin is now **v0.11.1**. The v0.6.0 -> v0.10.0 migrations the wrapper had to absorb (the §4 `LIB_X25519_CODE` / `LIB_X25519_INIT_CODE` segment renames, the `x25_x1` buffer added by v0.7.0's #64 fix) are done and documented in - `tools/integration/build_x25519.sh`'s header. v0.11.0 itself is a - pure export-surface change — upstream states the library PRG is - byte-identical to v0.8.0 — so it needed no wrapper work at all. + `tools/integration/build_x25519.sh`'s header. v0.11.0 and v0.11.1 + are both pure export-surface / link-guard changes — upstream states + the library PRG is byte-identical across v0.8.0 through v0.11.1 — + so neither needed any wrapper work. v0.11.1 adds §6.6/§6.7 + placement guards (the previously-silent SQTAB placement hazard now + dies as a named `lderror` in both directions) and makes + `ZP_CONFIG_NO_EXPORTS` / `REU_CONFIG_NO_EXPORTS` actually reachable + from a consumer `-D`; none of that binds c64-https while the flag + stays off. The `USE_NISTCURVES_ONCHIP` / `USE_X25519_SIBLING` mutual exclusion at `Makefile:90` still stands, and its stated reason is @@ -1100,6 +1117,116 @@ Five latent bugs and three new ones were cleared to get here: invocation. Never set it for a REU-profile build: that is precisely the silent-garbage case above. +### VIC-II blanking — worth 6.3%, not the fleet's "20-25%" + +`src/vic.s` provides `vic_blank` / `vic_unblank` (clear/set DEN, bit 4 of +`$D011`). Until 2026-08-15 c64-https did **no** blanking anywhere, so +every shipped PRG paid full badline DMA through the whole handshake. + +**Blanking is scoped to the three CPU-bound primitives, deliberately** — +`x25519_base` and `x25519_scalarmult` (`src/tls_ecdh.s`) and the +`ecdsa_verify` dispatch (`src/crypto/ecdsa_verify.s`). Those are the great +majority of handshake wall-clock and produce no screen output of their +own. Wrapping `tls_connect` instead would be slightly smaller and faster +but would hide the CH / SH / HK1 / KEYS / ENC1 / RX progress markers, +which are this project's primary field diagnostic — a stock-C64 user +would get a black screen for 36 minutes with no way to tell a slow run +from a wedged one. Blanking mid-run also means `ecdsa_verify`'s two +dispatch arms are now `jsr` + `php`/`plp` + `rts` rather than tail-calls, +so the verify carry survives the unblank; the 3 negative CAVP vectors in +`tools/test_ecdsa_kat_oracle.py` are what prove that carry handling. + +**The measurement — and the correction.** `c64-nist-curves` and +`c64-x25519` both label their benchmark tables "VIC blanked", and +`tools/bench_x25519.py` carried the comment "for ~20-25% speedup". That +figure is wrong by about 3.5x. VICE, NTSC, stock 1 MHz, `x25519_base`, +same PRG, only the trampoline's blank flag varying: + + config jiffies note + blanked 12,637 reproduced exactly on a repeat run + unblanked 13,494 + delta 6.35% reduction / 6.78% speedup + +Reproduce with `tools/bench_x25519.py` and the same with `--no-blank`. +n=1 per arm is adequate here because VICE's simulated cycle counter is +deterministic (the repeat confirmed it) **and** the result matches +first-principles badline cost: a 25-row text display takes 25 badlines +per frame at ~43 cycles each against a 17,045-cycle NTSC frame — + + 25 x 43 / 17,045 = 6.31% predicted + measured 1,083 cycles/frame vs 1,075 predicted (+0.7%) + +20-25% is roughly the figure you would get with sprite DMA in play; for +a text-mode screen with no sprites — every screen c64-https draws — it +overstates the win threefold. **The sibling repos' tables still carry the +old claim**; that has not been reported upstream yet. + +Still worth doing: 6.3% of a ~36-minute stock-C64 handshake is over two +minutes, for 18 bytes of code. Just do not plan around it as a quarter. + +#### The turbo sweep — the tax does NOT shrink with clock + +`make VIC_BLANK=0` degrades `vic_blank`/`vic_unblank` to a bare `RTS`, so +the A/B pair differs only in whether DEN is touched — same call sites, +same JSR overhead, same 62,977 B image size. That is the software control +that made this measurable without waiting on +[c64-test-harness#150](https://github.com/JC-000/c64-test-harness/issues/150). + +U64E (10.43.23.81), `bench_ecdsa_u64e.py`, **onchip** profile — the +CPU-bound one, where the effect is not diluted: + + MHz vector blanked unblanked reduction n + 48 pos 28.433 s 30.502 s **6.78%** 3 <- tight, spreads <0.2% + 48 pos 28.924 s 31.137 s 7.11% 1 + 48 neg 26.636 s 28.674 s 7.11% 1 + 16 pos 82.605 s 86.515 s 4.52% 1 + 16 neg 78.049 s 85.067 s 8.25% 1 + 8 pos 163.446 s 174.400 s 6.28% 1 + 8 neg 157.246 s 166.837 s 5.75% 1 + +**Read the n=3 row and treat the n=1 rows as bracketing, not as a trend.** +The n=1 spread is 4.5-8.3%, which is wide enough to invent a clock trend +that is not there; the n=3 pair at 48 MHz has spreads under 0.2% and +lands at 6.78%. + +And the **REU** profile at 48 MHz, n=3, as a cross-check: + + profile blanked unblanked reduction + onchip 28.433 s 30.502 s 6.78% + REU 56.844 s 60.859 s 6.60% + +**Two predictions, both wrong, both wrong the same way — and the second +failure is what explains the first.** + + 1. *"The tax shrinks with turbo."* The VIC runs at ~1 MHz while the CPU + runs up to 64, so the steal should become a rounding error. It does + not: 6.78% at 48 MHz against 6.35% in VICE at 1 MHz — flat across a + 48x clock range. + 2. *"The REU profile dilutes it."* REU verify carries a ~48 s DMA floor + that turbo cannot touch, so if badlines only taxed CPU execution the + REU reduction should have been ~1.3%. Measured 6.60% — no dilution + at all. + +The reconciliation is that **badline DMA is a tax on the bus, not on the +CPU.** Everything that needs the bus pays the same ~6.3%: 6502 execution +and REU DMA transfers alike, at any clock, on either profile. Once that +is the model, all four numbers are the same number — + + 6.31% first-principles (25 badlines x ~43 cyc / 17,045-cyc NTSC frame) + 6.35% VICE, 1 MHz, x25519 (pure CPU) + 6.60% U64E, 48 MHz, REU profile (CPU + REU DMA) + 6.78% U64E, 48 MHz, onchip profile (pure CPU) + +— and the REU floor's clock-invariance and the badline tax's +fraction-invariance stop looking like a contradiction. Do not reason from +one to the other without measuring; that is exactly what produced both +wrong predictions above. + +Still unmeasured: **1 MHz on real hardware** (VICE covers that point +honestly and agrees; a hardware run costs ~23 min per arm and was judged +not worth the shared-device time), and **the C64U**, which was offline +(no ICMP, no REST) for this campaign. + ### ECDSA P-256 verify wall-clock `ecdsa_verify` of the RFC 6979 test vector on a U64E at 48 MHz turbo @@ -1447,15 +1574,70 @@ RFC 6979 vector, - **comb profile: parity at 16/32 MHz, +12% at 48 MHz** (18.4 vs 16.5 s). The U64E side is confirmed: a 2026-07-26 rerun at n=6 per positive vector gave median 18.39 s, spread 18.31-18.45 s - (±0.4%) across all three vectors. Plausibly the Lim-Lee table + (±0.4%) across all three vectors. + + **CAUSE UNKNOWN — and the previously recorded one is arithmetically + impossible.** This entry used to read "plausibly the Lim-Lee table fetches from REU bank 2 — a DMA-anchored cost whose share grows - with clock. The residual uncertainty is the C64U's 16.5 s - (itself n=2); re-measure that side before treating the gap as - exactly 12%. + with clock". That cannot produce this delta. The Lim-Lee comb moves + 32 window steps x 64 B = **2 KB** of REU traffic per verify + (`points256_comb.s:168`, h=8 over a 256-bit scalar), i.e. about + **2 ms** at the REU's ~1 MB/s. The delta is **1.9 s** — roughly + 900x larger. No plausible device-to-device REU speed difference + closes a factor of 900. + + For contrast, the figure that legitimately IS DMA-anchored: the REU + *profile's* 48.2 s floor comes from `reu_fetch_mul_row` moving 512 B + per call (`mul_8x8.s:280`) at 32 rows per `fp_mul` + (`fp256.s:191`) = 16 KB per field multiply. At ~1 MB/s that floor + implies ~48 MB and therefore ~2,900 `fp_mul` calls per verify, which + is the right order for P-256 — so the row-fetch path accounts for + its floor completely, with nothing left to attribute elsewhere. + + Do not re-attach a mechanism to this delta without checking the + magnitude first (see the `causal-claims-need-measurement` memory + note; this is a textbook instance). The residual uncertainty is + also still live: the C64U's 16.5 s is n=2, so re-measure **both** + devices at n>=3 before treating the gap as real at all, let alone + as exactly 12%. - Crossovers vs REU shift down on the U64E because its REU floor is higher: onchip wins above ~18 MHz (C64U: ~22), comb above ~5 MHz (C64U: ~7). Comb still dominates no-comb onchip at - every clock. Best U64E verify: **18.4 s @ 48 MHz** (comb). + every clock. Best U64E verify at the v0.6.0 pin: 18.4 s @ 48 MHz. + +#### Comb re-measured at the current pin (2026-08-15) + +The comb rows above are v0.6.0-era. Re-run on the U64E against the +**shipped `c64-https-uci-comb.prg`** (hash-matched to `dist/`), at the +`libs/nistcurves` **v0.11.0** pin and **with VIC blanking active**, +n=3 medians, RFC 6979 vector, all correctness=PASS: + + MHz v0.6.0 current delta + 16 49.1 s 46.986 s -4.3% + 32 24.6 s 24.440 s -0.7% + 48 18.4 s 16.402 s -10.9% + + refit T(f) = 1.4 + 731/f (max |resid| 1.1%; was D=2.2, C=747) + extrapolated 64 MHz: ~12.8 s + +**Do not read the per-clock deltas individually.** They are against +n=2 medians taken months earlier, and the 32 MHz arm has an 8% +internal spread this run (min 22.683, med 24.440, max 24.662) against +1.8% at 48 MHz and 0.4% at 16 MHz. The refit is the trustworthy +summary: C moved 747 -> 731, i.e. the CPU work is essentially where it +was and the gain is mostly blanking plus noise. + +**Best U64E verify is now 16.4 s @ 48 MHz**, and comb is **1.73x** +faster than no-comb onchip at that clock (16.402 vs 28.433, both n=3, +both blanked, same session). The MANIFEST's user-facing claim is +worded from these two numbers. + +**Corroboration for the unexplained device gap above.** The v0.6.0 +data had C64U 16.5 s against U64E 18.4 s at 48 MHz — the "+12%" whose +stated cause was refuted earlier in this section. The U64E now measures +**16.402 s**, essentially the old C64U figure, so the gap has closed +without anyone addressing it. That is what a measurement artefact looks +like, and it is further reason not to re-attach a mechanism to it. v0.3.0's hot-path code is essentially unchanged from v0.2.0; the small wall-clock improvement is within measurement noise across @@ -1721,34 +1903,41 @@ ld65 and ca65 edge cases; they are intentional and should stay: ## Packaging `make package` builds the release artifacts into `dist/` (gitignored). -**All four backend x profile combinations ship**, `make clean` between -every one: - - - `c64-https-uci-reu.prg` `make BACKEND=uci` - - `c64-https-uci-onchip.prg` `+ USE_NISTCURVES_ONCHIP=1` - - `c64-https-ip65-reu.prg` `make BACKEND=ip65` - - `c64-https-ip65-onchip.prg` `+ USE_NISTCURVES_ONCHIP=1` - -ip65 is now packaged (it was previously excluded on a link failure that -the #68 refit closed) — it is the only artifact that serves a stock C64 -+ RR-Net cartridge, and `ip65-onchip` is the only image a bone-stock -machine with no REU can run at all. - -The REU-vs-onchip guidance in `MANIFEST.txt` is the measured **~18 MHz** -crossover, not the older ~7 MHz figure: the REU profile carries a -wall-clock floor (DMA anchored to the ~1 MHz bus) that turbo cannot -touch, the onchip profile has none, and on a U64E the sign flips between -the 16 and 20 MHz CPU-speed settings. See the ECDSA wall-clock section. - -Disk images: - - - `c64-https-.d64` x4 — one PRG each, `LOAD"*",8,1` - - `c64-https-uci.d64`, `c64-https-ip65.d64` — both of that backend's - profiles on one disk - -There is deliberately **no all-in-one image**: the four PRGs total 868 -blocks against a .d64's 664 free. Each backend's pair does fit (UCI 496, -ip65 372), which makes the per-backend disk the largest useful bundle. +**Three products ship**, `make clean` between every one, matrix in +`tools/package/_common.sh`: + + - `c64-https-ip65-onchip.prg` `make BACKEND=ip65 USE_NISTCURVES_ONCHIP=1` + MAXIMUM COMPATIBILITY. Bone-stock C64 + RR-Net, no REU, no + turbo. The only image a completely unmodified machine runs. + - `c64-https-uci-onchip.prg` `make BACKEND=uci USE_NISTCURVES_ONCHIP=1` + Turbo, no REU. + - `c64-https-uci-comb.prg` `make BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1` + Turbo + REU, fastest. 1.73x quicker verify than uci-onchip + (16.402 s vs 28.433 s, U64E 48 MHz, n=3, both blanked). + +**The two REU-profile images were retired from the lineup** +(`uci-reu`, `ip65-reu`). They are still buildable and still the fastest +choice below ~18 MHz — the REU profile's DMA floor is a floor, but its +CPU work is lower — so this is a curation decision, not a measurement +one. The cost is borne by a stock C64 *with* an REU, which now gets +`ip65-onchip` at ~1,820 s per handshake where `ip65-reu` would have done +~1,082 s at 1 MHz. If that user group matters, `ip65-reu` is one line in +`PACKAGE_VARIANTS` away from returning. + +`uci-comb` is the newest and needs three things stated plainly: it is +**not** a no-REU image despite building on the on-chip field layer (it +claims REU bank 2 for the 16 KB Lim-Lee table, +`LIB_NISTCURVES_REU_BANKS_USED = $04`); it pays a boot precompute of +**45 s at 48 MHz / ~34 s at 64 MHz / ~36 min at 1 MHz** (measured, see +below); and it only wins above ~5 MHz, so it is strictly a turbo +product. Its archive comes from upstream's `lib-p256-comb-onchip` +(v0.11.0), not from member surgery. + +Disk images: **one product per disk, three disks**, `LOAD"*",8,1`. +Per-backend combo images were retired with the lineup change — three +UCI variants are 3 x 248 = 744 blocks against a .d64's 664 free, so a +combo disk would have had to silently omit a product. One variant per +disk means the label is the whole contents. `c64-https-listener.py` is a **single self-extracting Python file** (was a zip + `run.sh` + venv + pip). It has **no third-party dependency at @@ -1809,13 +1998,23 @@ drive emulation the ~250-block load never completes inside any sane budget, and the symptom is a screen stuck on `LOADING` that looks like a bad image rather than a slow one. `verify_release.py` passes both flags. -The comb profile stays deliberately excluded (REU bank 2 residency + -~40 min boot precompute at 1 MHz make it wrong for a general release). +**The comb profile now SHIPS** (`uci-comb`). It was excluded from the +lineup while its costs — REU bank 2 residency plus the boot precompute — +looked disqualifying for a general release. What changed: the precompute +was measured properly at **45 s @48 MHz / ~34 s @64 MHz** (the ~36 min +figure is the 1 MHz end, and nobody runs comb at 1 MHz — it loses to the +plain REU profile below ~5 MHz anyway), and upstream v0.11.0 made the +archive reachable without member surgery. It is a turbo product and the +MANIFEST says so. Validation record (2026-07-27, then-HEAD cb6eab4, `libs/nistcurves` -pin v0.6.0 — the wall-clock rows below are v0.6.0 figures and have not -been re-measured at any later pin; the only point that has is the -48 MHz UCI REU one, in "The one re-measured point" above): +pin v0.6.0). **This record predates the three-product lineup** — it +validates `uci-reu` / `ip65-reu`, which no longer ship, and does not +cover `uci-comb`, which now does. Kept as history, not as current +coverage; the current release's evidence is the `make package-verify` +run plus the comb KAT and the re-measured comb sweep above. The +wall-clock rows below are v0.6.0 figures except the 48 MHz UCI REU one +("The one re-measured point") and the comb rows: - onchip PRG passes the 3-vector ECDSA KAT in VICE **without** REU (and with, as control) — the no-REU claim is verified, and boot.s's unconditional reu_mul_init is harmless with no REU diff --git a/Makefile b/Makefile index 4e03aa66..ac68af80 100644 --- a/Makefile +++ b/Makefile @@ -79,6 +79,15 @@ endif ifdef HTTPS_PORT CA65FLAGS += -D HTTPS_PORT=$(HTTPS_PORT) endif +# VIC-II blanking around the CPU-bound crypto primitives (src/vic.s). +# ON by default and that is what ships; `make VIC_BLANK=0` degrades +# vic_blank/vic_unblank to bare RTS so the badline tax can be measured +# A/B with everything else in the image identical. That control build is +# a measurement tool, not a shipping configuration — see the "VIC-II +# blanking" section of CLAUDE.md for the numbers it produced. +ifeq ($(VIC_BLANK),0) +CA65FLAGS += -D NO_VIC_BLANK=1 +endif # Lazy (=) so the USE_NISTCURVES_ONCHIP_COMB block below can retarget # CFG to the cfg variant after this line. LD65FLAGS = -C $(CFG) -Ln build/labels.txt -m build/c64-https.map --dbgfile build/c64-https.dbg diff --git a/README.md b/README.md index 5dbe7444..0f4bae3f 100644 --- a/README.md +++ b/README.md @@ -12,19 +12,20 @@ An HTTPS client for the Commodore 64 in 6502 assembly. Implements TLS 1.3 over T Grab a release — latest is [**v0.2.0**](https://github.com/JC-000/c64-https/releases/tag/v0.2.0). Every build is prebuilt, as a `.prg` and as a bootable `.d64`. -No assembler, no cc65, no Python packages, no build step. Two questions pick -your image, and `MANIFEST.txt` in the release walks through them: +No assembler, no cc65, no Python packages, no build step. **Three products, +one disk each** — the label is the whole contents, and `MANIFEST.txt` in the +release walks you through the choice: -| | REU present | no REU | +| image | for | note | |---|---|---| -| **Ultimate 64 / C64 Ultimate** | `c64-https-uci-reu` | `c64-https-uci-onchip` | -| **stock C64 + RR-Net** | `c64-https-ip65-reu` | `c64-https-ip65-onchip` | +| `c64-https-ip65-onchip` | bone-stock C64 + RR-Net cartridge | maximum compatibility: no REU, no turbo, nothing optional. If you are not sure what you have, this is the one that runs. ~36 min per handshake at 1 MHz. | +| `c64-https-uci-onchip` | Ultimate 64 / C64 Ultimate at turbo, REU off | boots straight to the menu | +| `c64-https-uci-comb` | Ultimate 64 / C64 Ultimate at turbo, REU **on** | fastest — 1.73x quicker verify (16.4 s vs 28.4 s, U64E at 48 MHz). Builds a 16 KB table into REU bank 2 at each boot first: ~34 s at 64 MHz, ~45 s at 48 MHz. | -The `reu` images are faster below roughly 18 MHz — which is every real stock -C64 — because they offload the ECDSA verify to REU DMA. The `onchip` images -need no REU at all and win above that crossover, so they are the right pick -for Ultimate turbo modes. `ip65-onchip` is the only image a bone-stock -machine with no expansion RAM can run end to end. +The screen blanks during the slow crypto on every image — that is deliberate, +it stops the VIC-II stealing bus cycles and buys ~6.5%. The progress line +returns between handshake phases, so a blank screen for minutes at a time is +the crypto running, not a hang. `c64-https-listener.py` in the same release is a single self-extracting file that stands up the server side to point the C64 at: it mints its own @@ -213,9 +214,10 @@ cd c64-https make # build/c64-https.prg (default BACKEND=ip65, REU profile) make BACKEND=uci # the Ultimate 64 / C64 Ultimate (UCI) variant make USE_NISTCURVES_ONCHIP=1 # the no-REU "onchip" P-256 verify profile +make VIC_BLANK=0 # measurement control only: VIC blanking off (never ship) make run # build and launch in VICE (x64sc) make clean # remove build artifacts -make package # all four backend x profile release artifacts into dist/ +make package # the three release products into dist/ ``` **Run `make clean` whenever you change `BACKEND=` or any flag.** make @@ -274,7 +276,8 @@ Progress: - [x] ip65 submodule integration — 6.8 KB binary blob at $2000 (TCP/UDP/DNS/DHCP/ARP + RR-Net CS8900a) - [x] Network wrapper with ZP time-sharing — save/restore $02-$1B around ip65 calls - [x] Crypto primitives — ChaCha20, Poly1305, AEAD (from c64-wireguard), SHA-256, HMAC-DRBG (from c64-aes256-ecdsa) -- [x] Optimized X25519/fe25519 — REU DMA multiply tables, mult66 quarter-square, self-mod code, 4x-unrolled cswap. `tools/bench_x25519.py` measures one basepoint scalar multiply at **12,635 jiffies = 211 s (3.5 min)** of C64 time (NTSC, VIC-II blanked, ~14 s wall clock under VICE warp) +- [x] Optimized X25519/fe25519 — REU DMA multiply tables, mult66 quarter-square, self-mod code, 4x-unrolled cswap. `tools/bench_x25519.py` measures one basepoint scalar multiply at **12,637 jiffies = 211 s (3.5 min)** of C64 time (NTSC, VIC-II blanked, ~21 s wall clock under VICE warp); the same multiply costs 13,494 jiffies unblanked +- [x] VIC-II blanking during the CPU-bound crypto — `src/vic.s`, scoped to the two X25519 scalar multiplies and the ECDSA verify so the on-screen handshake progress markers stay visible between phases. Worth **6.3-6.8%**, measured both in VICE at 1 MHz and on a U64E at 8/16/48 MHz; see the VIC-II blanking section of `CLAUDE.md` - [x] HKDF-SHA256 — Extract, Expand, Expand-Label, Derive-Secret (RFC 5869 + TLS 1.3) - [x] TLS 1.3 record layer — encrypt/decrypt with ChaCha20-Poly1305, nonce construction, sequence numbers - [x] TLS 1.3 handshake — ClientHello builder (x25519 key_share, SNI), ServerHello parser, streaming transcript hash @@ -291,9 +294,9 @@ Progress: ### Known Issues -- **The handshake is slow, and the ECDSA P-256 verify dominates it.** Every figure here is quoted from the measurement record in `CLAUDE.md`. Except where noted they were taken at the **`libs/nistcurves` v0.6.0 pin**, and the pin is now v0.10.1, so treat them as a baseline rather than as current. End-to-end handshake + GET against the local listener, U64E, master 2ceb5b1: **80.8 s** (REU profile, 48 MHz), **45.5 s** (onchip profile, 48 MHz), **1,157.7 s** (REU, stock 1 MHz). One point of that sweep has been carried forward: 48 MHz REU measures **82.1 s** at v0.9.1 and **82.4 s** at v0.10.1 (n=1 each, so the 0.4% step between them is noise; the 1.6% from v0.6.0 is the FIPS 186-5 public-key validation gate v0.7.0 added). No other clock or profile has been re-measured. On the REU-less stock-C64 path (ip65 + onchip, no REU, honest 1 MHz in VICE) the whole run measured **2,159.7 s = 36.0 min**, of which the verify stretch alone was 1,416.7 s. That is fine for the local listener, which holds the connection open; it exceeds a typical 10-30 s real-world server handshake window. +- **The handshake is slow, and the ECDSA P-256 verify dominates it.** Every figure here is quoted from the measurement record in `CLAUDE.md`. Except where noted they were taken at the **`libs/nistcurves` v0.6.0 pin**, and the pin is now v0.11.0, so treat them as a baseline rather than as current. The one profile re-measured at the current pin is comb: 46.986 / 24.440 / 16.402 s verify at 16 / 32 / 48 MHz (U64E, n=3, VIC blanking active). End-to-end handshake + GET against the local listener, U64E, master 2ceb5b1: **80.8 s** (REU profile, 48 MHz), **45.5 s** (onchip profile, 48 MHz), **1,157.7 s** (REU, stock 1 MHz). One point of that sweep has been carried forward: 48 MHz REU measures **82.1 s** at v0.9.1 and **82.4 s** at v0.10.1 (n=1 each, so the 0.4% step between them is noise; the 1.6% from v0.6.0 is the FIPS 186-5 public-key validation gate v0.7.0 added). No other clock or profile has been re-measured. On the REU-less stock-C64 path (ip65 + onchip, no REU, honest 1 MHz in VICE) the whole run measured **2,159.7 s = 36.0 min**, of which the verify stretch alone was 1,416.7 s. That is fine for the local listener, which holds the connection open; it exceeds a typical 10-30 s real-world server handshake window. - **P-384** ECDSA is stubbed at the TLS layer. The dispatcher advertises `ecdsa_secp384r1_sha384` (0x0503) and routes to `src/crypto/ecdsa_verify_384.s`, but no P-384 build target completes. Measured 2026-08-14: `make p384-overlay` from a clean tree stops at `No rule to make target 'build/labels.txt'`, and after a main build has produced that file it stops at `Segment 'LIB_NISTCURVES_SHA384_TABLES' overflows memory area 'OVERLAY_REGION' by 1536 bytes`. Cert chains requiring P-384 will not verify. -- **`USE_X25519_SIBLING=1` now links under UCI, and still does not under ip65.** The duplicate-symbol failure this entry used to record — `ld65: Error: Duplicate external identifier: 'reu_mul_tables_init'`, on **both** backends — was closed by the `libs/nistcurves` v0.10.1 / `libs/x25519` v0.11.0 bump plus one line of archive surgery: `tools/integration/build_nistcurves_p256.sh` now also drops `reu_mul_init.o`, the SPEC §8.2 `reu_mul` provider that `src/boot.s` supplies itself. Measured at those pins: `make clean && make BACKEND=uci USE_X25519_SIBLING=1` produces a 62,977 B PRG, and ip65 stops instead at `Segment 'X25519_RODATA' overflows memory area 'CRYPTO_OVERLAY' by 3584 bytes` — a placement problem (ip65's overlay slot is 4,212 B against UCI's 7,680 B), not a symbol collision. The flag remains **off by default** and no shipped artifact contains the sibling; the in-tree X25519 in `src/crypto/{x25519,fe25519}.s` is what every release PRG is built from. Flipping the default is a separate decision that wants a hardware handshake behind it. +- **`USE_X25519_SIBLING=1` now links under UCI, and still does not under ip65.** The duplicate-symbol failure this entry used to record — `ld65: Error: Duplicate external identifier: 'reu_mul_tables_init'`, on **both** backends — was closed by the `libs/nistcurves` v0.10.1 / `libs/x25519` v0.11.0 bump plus one line of archive surgery: `tools/integration/build_nistcurves_p256.sh` now also drops `reu_mul_init.o`, the SPEC §8.2 `reu_mul` provider that `src/boot.s` supplies itself. Re-measured at the current v0.11.0 / v0.11.1 pins, unchanged: `make clean && make BACKEND=uci USE_X25519_SIBLING=1` produces a 62,977 B PRG, and ip65 stops instead at `Segment 'X25519_RODATA' overflows memory area 'CRYPTO_OVERLAY' by 3584 bytes` — a placement problem (ip65's overlay slot is 4,212 B against UCI's 7,680 B), not a symbol collision. The flag remains **off by default** and no shipped artifact contains the sibling; the in-tree X25519 in `src/crypto/{x25519,fe25519}.s` is what every release PRG is built from. Flipping the default is a separate decision that wants a hardware handshake behind it. - **Live internet HTTP GET (UCI backend)** has not been re-verified since the FPGA-fence rework; only the local multi-segment listener is exercised regularly. - **VICE 3.9** previously appeared to crash on chained HMAC-SHA256 calls (backend-independent — affects the crypto-only test suites), but this was caused by hardcoded port numbers bypassing the test harness port allocator. With proper `ViceInstanceManager` usage (no hardcoded ports), all N=1..10 chained calls succeed reliably. @@ -341,7 +344,8 @@ python3 tools/test_package_verify.py # 31 cases: pure-logic tests for the rele python3 tools/test_pytest_boundary.py # 5 checks: the pytest collection boundary below is intact # Benchmark -python3 tools/bench_x25519.py # X25519 basepoint multiply: 12,635 jiffies / 211 s C64 time, ~14 s wall under warp +python3 tools/bench_x25519.py # X25519 basepoint multiply: 12,637 jiffies / 211 s C64 time (VIC blanked) +python3 tools/bench_x25519.py --no-blank # same multiply unblanked: 13,494 jiffies — the badline A/B # Integration tests (require the bridge/TAP rig + dnsmasq; see scripts/setup-bridge-tap.sh below) python3 tools/test_dns.py # 4 tests: DNS resolution via ip65 over TAP (label, known host, second host, unknown host) diff --git a/libs/nistcurves b/libs/nistcurves index 1edd6348..ba2833e7 160000 --- a/libs/nistcurves +++ b/libs/nistcurves @@ -1 +1 @@ -Subproject commit 1edd6348a2d30db5db239ed835d7610b777421d9 +Subproject commit ba2833e7e30f91913ed07cc9c280c8c467837489 diff --git a/libs/x25519 b/libs/x25519 index e9af04ec..53e22ad4 160000 --- a/libs/x25519 +++ b/libs/x25519 @@ -1 +1 @@ -Subproject commit e9af04ec1a69c6b25a1c938fb0967bcfb38319c3 +Subproject commit 53e22ad46631a359140d1011f19cee8ab8780c45 diff --git a/src/contract_footprint_asserts.s b/src/contract_footprint_asserts.s index eb6d818a..4f638dce 100644 --- a/src/contract_footprint_asserts.s +++ b/src/contract_footprint_asserts.s @@ -6,9 +6,11 @@ ; profile-dependent in a way the §1/§3/§8.0/§13.3 gates are not (see the ; comb exclusion below). ; -; Contract: https://github.com/JC-000/c64-lib-contract — read SPEC.md on -; `main`, NOT the newest git tag (tags lag; main is v0.10.0 as of -; 2026-08-15). Clause referenced here: §6.6 (consumer footprint asserts). +; Contract: https://github.com/JC-000/c64-lib-contract — pin the tag +; (v0.10.3 or later; the old "read `main`, tags lag" advice inverted at +; that release — see the header of src/lib_contract_asserts.s, including +; the one hole in the tag series). Clause referenced here: §6.6 (consumer +; footprint asserts). ; ; --------------------------------------------------------------------- ; WHAT §6.6 IS FOR @@ -70,36 +72,39 @@ ; leaving an opaque segment overflow to be bisected. ; ; --------------------------------------------------------------------- -; WHY THE COMB PROFILE IS EXCLUDED +; THE COMB EXCLUSION IS GONE (libs/nistcurves v0.11.0) ; --------------------------------------------------------------------- -; The comb archive would FAIL this assert today (27,000 + 1,650 = 28,650 -; against 16,384) and the failure would be a false alarm: the comb PRG -; links and runs, so the declared number is wrong, not the build. +; This file used to wrap everything below in `.ifndef USE_NISTCURVES_COMB`, +; because the comb archive would have FAILED the assert with 27,000 + 1,650 +; = 28,650 against 16,384 — and that failure would have been a false alarm: +; the comb PRG linked and ran, so the declared number was wrong, not the +; build. ; -; The cause is ours, not upstream's. `tools/integration/build_nistcurves_p256.sh` -; builds the comb profile from upstream's FULL `lib-onchip` archive and -; then `rm -f`s ~7 members (fp384, mod384, curve384, points384_*, ...) to -; narrow it to the P-256 comb set. Upstream's `lib_manifest_onchip.o` -; legitimately describes the archive upstream shipped; it survives our -; member surgery still describing the pre-surgery set. The `reu` and -; `onchip` profiles are unaffected because they build from upstream's -; already-minimal `lib-p256-verify` / `lib-p256-verify-onchip` targets, -; which carry per-variant manifests. +; The cause was ours. `tools/integration/build_nistcurves_p256.sh` built the +; comb profile from upstream's FULL `lib-onchip` archive and then `rm -f`d +; ~13 non-P-256 members to narrow it. Upstream's `lib_manifest_onchip.o` +; legitimately described the archive upstream shipped, and it survived that +; surgery still describing the pre-surgery set — exactly the harm SPEC §6.1 +; names ("an archive whose member set a consumer has edited is outside every +; §5/§8.0 manifest claim it ships"). ; -; This is precisely the harm SPEC §6.1 names: "an archive whose member set -; a consumer has edited is outside every §5/§8.0 manifest claim it ships." -; The sanctioned remedy is §6.2 `CONTRACT_DEFINES` / `CONTRACT_ZP_DEFINES` -; plus §6.3's `lib-app-owned` target, so the configuration is reachable -; without surgery. Neither exists in the pinned v0.9.1; both ARE implemented -; on libs/nistcurves master (v0.10.1, measured). Retiring the surgery is -; therefore unblocked by the wave bump and is sequenced in c64-https#70 — -; when it lands, delete the .ifdef below and the comb profile is covered -; by the same assert as the other two. +; Fixed at the v0.11.0 pin. Upstream added `lib-p256-comb` / +; `lib-p256-comb-onchip` in response to c64-nist-curves#117, each carrying +; its own §6.4 manifest triple under the `LIB_P256_COMB_ONLY` switch, so the +; wrapper stages a narrow archive that upstream actually ships and the +; declared footprint describes what we link. The comb profile is now covered +; by the same assert as `reu` and `onchip`, with no gating at all. ; -; The comb profile is deliberately excluded from `make package`, so no -; shipped artifact is affected by the gap this exclusion leaves open. +; Two things worth knowing if this ever needs re-litigating: +; - the switch was PRG-NEUTRAL — the comb image is byte-identical +; (`63c7ce868cdd…`) built either way, so the archive change altered the +; manifest and nothing else; +; - the wrapper still drops three members for other reasons +; (`mul_8x8.o`, `data_shared.o`, `reu_mul_init.o` — the §8.0 APP_OWNED +; collision set, c64-https#119). That surgery does not affect the +; numbers this assert reads, because those are per-variant §6.4 values, +; but it is why the §8.0 disjointness asserts are still not writable. -.ifndef USE_NISTCURVES_COMB .import LIB_NISTCURVES_RESIDENT_BYTES .import LIB_NISTCURVES_COLD_BYTES @@ -116,4 +121,3 @@ .assert LIB_NISTCURVES_RESIDENT_BYTES + LIB_NISTCURVES_COLD_BYTES <= __CRYPTO_RESIDENT_SIZE__, lderror, "libs/nistcurves declared footprint (LIB_NISTCURVES_RESIDENT_BYTES + _COLD_BYTES) exceeds CRYPTO_RESIDENT. Contract SPEC 6.6. Most likely cause is a 6.4 regression: the archive ships a whole-library manifest instead of a per-variant one (27000 B is the whole-library value). Check with od65 --dump-exports on the staged lib_manifest*.o before assuming the library really grew." .endif -.endif ; USE_NISTCURVES_COMB diff --git a/src/crypto/ecdsa_verify.s b/src/crypto/ecdsa_verify.s index 74025985..a847894f 100644 --- a/src/crypto/ecdsa_verify.s +++ b/src/crypto/ecdsa_verify.s @@ -21,6 +21,10 @@ .include "constants.inc" +; --- VIC-II blanking around the CPU-bound verify (src/vic.s) --- +.import vic_blank +.import vic_unblank + ; --- External sibling (c64-nist-curves) entry points --- .import ecdsa_verify_256 .import ec_scalar_mul_var @@ -87,12 +91,28 @@ ecdsa_verify: ; Boot banks out BASIC ROM before any crypto runs (src/boot.s ; writes $36 to $01); the legacy defensive re-bank here was ; redundant and has been removed to save bytes. + ; + ; Blank the VIC across the whole dispatch: this is the single + ; longest CPU-bound stretch of the handshake, and it produces no + ; screen output of its own, so badline DMA here is pure loss. + ; At the v0.6.0 REU pin the verify was 59.2 s of a U64E's 80.8 s + ; handshake at 48 MHz, and 1,416.7 s of a stock 1 MHz ip65 run's + ; 2,159.7 s — i.e. roughly two thirds of the whole handshake in + ; both cases. See src/vic.s for why blanking is scoped to the + ; heavy primitives rather than wrapped around tls_connect. + ; + ; Both dispatch arms were tail-calls before blanking landed. They + ; are now JSRs so there is a return site to unblank at; the carry + ; that each arm returns is the verify result and is preserved + ; across the unblank by the PHP/PLP pair below. + jsr vic_blank + lda ecdsa_curve_id beq @p256 ; Phase 4a: P-384 dispatcher composes the dual-overlay swap - ; (sha384 -> curve) + sibling ecdsa_verify_384. Tail-call so - ; the dispatcher's carry return propagates as our return. - jmp ecdsa_verify_384_tls + ; (sha384 -> curve) + sibling ecdsa_verify_384. + jsr ecdsa_verify_384_tls + jmp @done @p256: ; The TLS-populated ecdsa_sig_r, ecdsa_sig_s, ecdsa_hash, @@ -101,7 +121,13 @@ ecdsa_verify: ; the sibling's ecdsa_verify_256 ingests. Just hand it the base. lda #ecdsa_sig_r - jmp ecdsa_verify_256 ; carry = verify result, returns to caller + jsr ecdsa_verify_256 ; carry = verify result + +@done: + php ; save the verify carry + jsr vic_unblank + plp ; ...and hand it to our caller + rts ; ============================================================================= diff --git a/src/lib_contract_asserts.s b/src/lib_contract_asserts.s index a5f51899..9f411351 100644 --- a/src/lib_contract_asserts.s +++ b/src/lib_contract_asserts.s @@ -5,11 +5,25 @@ ; only *believes* about its vendored libraries become link-time errors ; when they stop being true. ; -; Contract: https://github.com/JC-000/c64-lib-contract — read SPEC.md on -; `main`, NOT the newest git tag (tags lag: newest tag v0.4.0, main is -; v0.8.0 as of 2026-08-14). Clauses referenced here: §1 (version -; identification), §3 (REU layout), §5 (aggregate manifest equates), -; §8.0 (shared-primitive ownership bitmask), §13.3 (rx ring shape). +; Contract: https://github.com/JC-000/c64-lib-contract — **pin the tag**. +; +; That advice INVERTED at contract v0.10.3 (2026-08-15), the repo's first +; GitHub release. This file used to say "read SPEC.md on `main`, NOT the +; newest git tag", and it was right at the time: tags lagged badly, newest +; v0.4.0 against a v0.8.0 main. They no longer do — v0.10.3 is both the +; newest tag and the newest SPEC. +; +; One caveat, because the release notes state it wrongly. They claim +; "every version since v0.4.1 is tagged (gapless series)"; it is not. +; Measured against the v0.10.3 changelog: 31 changelog versions, 30 tags, +; and **0.10.1 has no tag**. It was a doc-only section reorder with zero +; normative change, so the hole costs nothing — but do not write tooling +; that assumes every changelog version is resolvable as a ref. Pin +; v0.10.3 or later. +; +; Clauses referenced here: §1 (version identification), §3 (REU layout), +; §5 (aggregate manifest equates), §8.0 (shared-primitive ownership +; bitmask), §13.3 (rx ring shape). ; ; --------------------------------------------------------------------- ; WHY `.assert ..., lderror` AND NOT `.if ... .error` @@ -29,9 +43,20 @@ ; The form that works is `.assert , lderror, ""`, which defers ; evaluation to ld65 — the same reasoning the contract itself applies in ; §13.0/§13.8 ("NET_BACKEND_FAMILIES is .import'ed, so its value is not -; known until link") — so §1 and §13 of the contract disagree, and §1 is -; the one that does not run. Written up in c64-https#70 for escalation -; upstream. Do not "fix" the asserts below back into `.if` form. +; known until link") — so §1 and §13 of the contract disagreed, and §1 was +; the one that did not run. +; +; **Fixed upstream at contract v0.10.2** (c64-lib-contract#107, filed off +; this repo's v0.10.0 alignment pass): §7's ABI-gate bullet had restated +; the same broken `.if`-on-import form that v0.8.1 had already corrected +; in §1, and it is now `.assert`/`lderror` with a §1 cross-reference. The +; companion defect in the same issue — §8.0's consumes-mask snippet using +; `.if ::` on an unset `-D` selector, which fails to assemble in the +; adopter's own default build — is now `.ifdef`. +; +; Both were copy-paste hazards rather than anything c64-https shipped: +; the asserts below were written in the working form from the start, which +; is how the defect was noticed. Do not "fix" them back into `.if` form. ; ; --------------------------------------------------------------------- ; WHAT IS *NOT* ASSERTED HERE, AND WHY diff --git a/src/tls_ecdh.s b/src/tls_ecdh.s index b7a6e982..35c97c7e 100644 --- a/src/tls_ecdh.s +++ b/src/tls_ecdh.s @@ -27,6 +27,8 @@ .import x25519_base .import x25519_scalarmult +.import vic_blank +.import vic_unblank .import x25519_clamp .import x25_scalar .import x25_u @@ -56,8 +58,12 @@ tls_ecdh_generate_keypair: bpl @copy_priv ; Compute public key = scalar * basepoint(9) - ; x25519_base handles clamping and copies basepoint to x25_u + ; x25519_base handles clamping and copies basepoint to x25_u. + ; Blanked: no screen output happens inside, and badline DMA costs + ; ~6.3% of the 6510 (measured, see src/vic.s). + jsr vic_blank jsr x25519_base + jsr vic_unblank ; Copy x25_result -> tls_ecdhe_pubkey ldx #31 @@ -98,7 +104,9 @@ tls_ecdh_compute_shared: bpl @copy_srv ; Compute shared secret = scalar * server_pubkey + jsr vic_blank jsr x25519_scalarmult + jsr vic_unblank ; Copy x25_result -> tls_shared_secret ldx #31 diff --git a/src/vic.s b/src/vic.s new file mode 100644 index 00000000..047f2361 --- /dev/null +++ b/src/vic.s @@ -0,0 +1,161 @@ +; ============================================================================= +; src/vic.s — VIC-II blanking around the CPU-bound crypto primitives. +; +; Clearing DEN (bit 4 of $D011) stops the VIC-II fetching character and +; sprite data, which removes the badline DMA that steals the 6510's bus for +; 40-43 cycles on every eighth raster line. +; +; c64-https shipped without any blanking at all until this file landed, so +; every consumer PRG was paying that tax across a handshake that runs for +; 82 s on a U64E at 48 MHz and ~36 minutes on a stock C64 over ip65. +; +; --------------------------------------------------------------------- +; WHAT IT IS ACTUALLY WORTH — 6.3%, NOT 20-25% +; --------------------------------------------------------------------- +; The figure repeated across this fleet is wrong and this file is where +; that gets corrected. `c64-nist-curves` and `c64-x25519` both ship their +; own vic_blank/vic_unblank and label every benchmark table "VIC blanked"; +; c64-https's own tools/bench_x25519.py carried the comment "for ~20-25% +; speedup". Measured, the number is **6.3%**. +; +; VICE, NTSC, stock 1 MHz, x25519_base, same PRG, only the trampoline's +; blank flag varying (tools/bench_x25519.py, with and without --no-blank): +; +; blanked 12,637 jiffies <- reproduced exactly on a re-run +; unblanked 13,494 jiffies +; reduction 6.35% (speedup 6.78%) +; +; That matches first-principles badline cost almost exactly, which is why +; it is believable at n=1 (VICE's simulated cycle counter is deterministic, +; and the repeat confirmed it): a 25-row display has 25 badlines per frame, +; each stealing ~43 cycles, against a 17,045-cycle NTSC frame — +; +; 25 x 43 / 17,045 = 6.31% predicted +; measured 1,083 cycles/frame vs 1,075 predicted (+0.7%) +; +; The 20-25% figure is roughly what you would get if sprite DMA were also +; in play; for a text-mode display with no sprites — which is every screen +; c64-https draws — it overstates the win by about 3.5x. +; +; Confirmed on real hardware, U64E, ecdsa_verify, n=3 (`make VIC_BLANK=0` +; builds the control): +; +; profile MHz blanked unblanked reduction +; onchip 48 28.433 s 30.502 s 6.78% +; REU 48 56.844 s 60.859 s 6.60% +; +; Neither turbo nor the REU profile's DMA floor dilutes it, because the +; badline steal is a tax on the BUS, not on the CPU — REU DMA pays it too. +; See CLAUDE.md's "VIC-II blanking" section for the two predictions that +; got this wrong before it was measured. +; +; This does not make blanking not worth doing: 6.3% of a 36-minute stock-C64 +; handshake is still over two minutes, for 18 bytes and no risk. It does +; mean nobody should plan around it as though it were a quarter of runtime. +; +; --------------------------------------------------------------------- +; WHY THIS IS SCOPED, NOT WRAPPED AROUND THE WHOLE HANDSHAKE +; --------------------------------------------------------------------- +; The obvious implementation — blank once around `tls_connect` — is a +; couple of bytes smaller and marginally faster, and it was deliberately +; not chosen. `src/tls13.s` prints a progress marker at each handshake +; phase (CH / SH / HK1 / KEYS / ENC1 / RX / GOT2), and those markers are +; the primary field diagnostic for this project: CLAUDE.md's triage +; procedure for a stalled handshake is "read the last marker on screen, +; then read net_last_error". Blanking across the whole handshake would +; leave a stock-C64 user staring at a black screen for 36 minutes with no +; way to tell a slow run from a wedged one. +; +; So blanking is applied only inside the three calls that actually dominate +; wall-clock, all of which run with no screen output of their own: +; +; src/tls_ecdh.s x25519_base (keypair generation) +; src/tls_ecdh.s x25519_scalarmult (shared secret) +; src/crypto/ecdsa_verify.s ecdsa_verify_256 / ecdsa_verify_384_tls +; +; Those are >90% of the handshake's CPU time, so this captures nearly all +; of the available win while every marker still prints between phases. +; +; --------------------------------------------------------------------- +; PLACEMENT +; --------------------------------------------------------------------- +; These bodies live in LOADER_OVERFLOW, not in CODE and not in +; CRYPTO_CODE, and the choice was forced by measurement rather than taste: +; +; - CODE/LOADER looks roomy under UCI (602 B free) but is the wrong +; read. Under ip65 the same segment carries boot + TLS + HTTP + the +; net wrapper and has essentially no slack — putting 30 bytes there +; overflows `LOADER` by 10 (`ld65: Warning: cfg/c64-https-ip65.cfg(90): +; Segment 'CODE' overflows memory area 'LOADER' by 10 bytes`). +; - CRYPTO_CODE would fit, but CRYPTO_HOT / CRYPTO_RESIDENT had 68 bytes +; free at the v0.10.2 pin and is the region that has twice overflowed +; on a library bump. Spending its margin on display control would be +; a poor trade. +; +; LOADER_OVERFLOW is the sanctioned outlet for exactly this — it is where +; http.s's Content-Length parser went for the same reason — and it rides +; in the NET_CODE tail under both backends, so it is resident whenever +; crypto runs. CRYPTO_CODE therefore pays only the two JSRs in +; ecdsa_verify.s. +; +; --------------------------------------------------------------------- +; ASSUMPTIONS +; --------------------------------------------------------------------- +; - The display is enabled when vic_blank is called. Restore is +; `ORA #DEN` rather than a saved-byte restore, matching the sibling +; libraries' convention; c64-https never blanks the screen for any +; other reason and runs no raster effects, so there is no state to +; preserve beyond the DEN bit itself. +; - Blanking does not disturb timekeeping. The jiffy clock is driven by +; a CIA timer IRQ and the UCI adapter's bounded waits read CIA1 TOD; +; neither depends on the VIC, so `uci_wait_idle` and friends keep +; their 5 s wall-clock budgets while the screen is off. +; - Not re-entrant, and does not need to be: the three call sites are +; sequential, never nested. +; ============================================================================= + + .export vic_blank + .export vic_unblank + +VIC_CTRL1 = $d011 ; VIC-II control register 1 +VIC_DEN = $10 ; bit 4 — display enable + + .segment "LOADER_OVERFLOW" + +.ifdef NO_VIC_BLANK + +; ----------------------------------------------------------------------------- +; `make VIC_BLANK=0` — the measurement control. Both entries degrade to a +; bare RTS so an A/B pair differs only in whether DEN is touched: the call +; sites, their JSR overhead, and every other byte of the image stay put. +; Never ship this; it exists so the badline tax can be measured on real +; hardware without the harness-side control that c64-test-harness#150 asks +; for. +; ----------------------------------------------------------------------------- +vic_blank: +vic_unblank: + rts + +.else + +; ----------------------------------------------------------------------------- +; vic_blank - clear DEN, stopping badline DMA. +; Clobbers: A. Preserves X, Y, C. +; ----------------------------------------------------------------------------- +vic_blank: + lda VIC_CTRL1 + and #<(~VIC_DEN) + sta VIC_CTRL1 + rts + +; ----------------------------------------------------------------------------- +; vic_unblank - set DEN, restoring the display. +; Clobbers: A. Preserves X, Y, C. +; ----------------------------------------------------------------------------- +vic_unblank: + lda VIC_CTRL1 + ora #VIC_DEN + sta VIC_CTRL1 + rts + +.endif diff --git a/tools/bench_x25519.py b/tools/bench_x25519.py index d9f5f59d..3025925e 100644 --- a/tools/bench_x25519.py +++ b/tools/bench_x25519.py @@ -69,7 +69,10 @@ def build_trampoline(labels, blank=True): code += bytes([0x85, 0xA2]) # STA $A2 code += bytes([0x58]) # CLI - # Blank VIC-II (disable DEN bit 4 of $D011) for ~20-25% speedup + # Blank VIC-II (disable DEN bit 4 of $D011). Worth ~6.3%, NOT the + # "~20-25%" this comment used to claim -- see the measurement in + # CLAUDE.md's "VIC-II blanking" section. Run this script with and + # without --no-blank to reproduce. if blank: code += bytes([0xAD, 0x11, 0xD0]) # LDA $D011 code += bytes([0x29, 0xEF]) # AND #$EF diff --git a/tools/integration/build_nistcurves_p256.sh b/tools/integration/build_nistcurves_p256.sh index d349cf8d..ae45bcbe 100755 --- a/tools/integration/build_nistcurves_p256.sh +++ b/tools/integration/build_nistcurves_p256.sh @@ -60,13 +60,31 @@ LIB_SRC="$LIB_DIR/src" LIB_BUILD="$LIB_DIR/build" OUT_DIR="$PROJECT_ROOT/build/lib" if [ "$PROFILE" = "onchip-comb" ]; then - # Comb-accelerated turbo profile: stage from the FULL onchip archive - # (the only shipped archive whose ecdsa256.o is the comb variant and - # which carries points256_comb.o + data_p256_limlee.o), then drop - # everything non-P-256 in step 4b. Consumer boot obligation grows by - # ec_precompute_256 (REU bank 2 $0000-$3FFF anchors, SPEC §8.3/§8.5). - UPSTREAM_TARGET="lib-onchip" - UPSTREAM_ARCHIVE="$LIB_BUILD/lib/nistcurves-onchip.a" + # Comb-accelerated turbo profile. + # + # Through the v0.10.2 pin this staged from the FULL `lib-onchip` + # archive and deleted ~13 non-P-256 members by hand, because no + # narrowed comb archive existed. That was SPEC §6.1 non-conformant + # (an edited member set is outside every §5/§8.0 manifest claim the + # archive ships) and it is why src/contract_footprint_asserts.s had + # to exclude this profile from the §6.6 assert: the surviving + # manifest described the pre-surgery set, 27,000 B against a + # 16,384 B region. + # + # libs/nistcurves v0.11.0 added `lib-p256-comb-onchip` in response + # (c64-nist-curves#117), carrying its own §6.4 manifest triple under + # the LIB_P256_COMB_ONLY switch. Member set = the + # lib-p256-verify-onchip set with the comb-fast ecdsa256.o replacing + # ecdsa256_nocomb.o, plus points256_comb.o + data_p256_limlee.o. + # So the surgery in step 4b is retired and the archive we link is + # one upstream actually ships. + # + # Consumer boot obligation still grows by ec_precompute_256 (REU + # bank 2 $0000-$3FFF anchors, SPEC §8.3/§8.5): measured 45 s at + # 48 MHz on a U64E, i.e. ~36 min at 1 MHz. See c64-https#120 for + # loading the table from disk instead. + UPSTREAM_TARGET="lib-p256-comb-onchip" + UPSTREAM_ARCHIVE="$LIB_BUILD/lib/nistcurves-p256-comb-onchip.a" STAGING="$PROJECT_ROOT/build/lib/nistcurves_p256_onchip_comb_staging" ARCHIVE="$OUT_DIR/nistcurves-p256-onchip-comb.a" SIZES="$OUT_DIR/nistcurves-p256-onchip-comb.sizes.txt" @@ -186,6 +204,10 @@ done case "$ZP_MEMBER" in zp_config.o) ZP_VARIANT_DEFINE=() ;; zp_config_p256verify.o) ZP_VARIANT_DEFINE=('-D' 'LIB_P256_VERIFY_ONLY') ;; + # v0.11.0's comb archives (c64-nist-curves#117). Gate name confirmed + # against libs/nistcurves/src/zp_config.s:162 and Makefile:302 rather + # than inferred from the member basename. + zp_config_p256comb.o) ZP_VARIANT_DEFINE=('-D' 'LIB_P256_COMB_ONLY') ;; zp_config_p384verify.o) ZP_VARIANT_DEFINE=('-D' 'LIB_P384_VERIFY_ONLY') ;; zp_config_p384curve.o) ZP_VARIANT_DEFINE=('-D' 'LIB_P384_CURVE_ONLY') ;; zp_config_sha384.o) ZP_VARIANT_DEFINE=('-D' 'LIB_SHA384_ONLY') ;; @@ -272,16 +294,16 @@ check_zp_slot fp_mul_j 58 # $3a # sibling's, which is a different routine writing through a different # buffer set. rm -f "$STAGING/mul_8x8.o" "$STAGING/data_shared.o" "$STAGING/reu_mul_init.o" -# 4b. onchip-comb: the full onchip archive carries both curves + SHA-384 + -# reference-inverse extras; keep only the P-256 comb verify set. -if [ "$PROFILE" = "onchip-comb" ]; then - rm -f "$STAGING"/fp384_onchip.o "$STAGING"/mod384.o "$STAGING"/curve384.o \ - "$STAGING"/points384_core.o "$STAGING"/points384_comb.o \ - "$STAGING"/data_p384.o "$STAGING"/data_p384_limlee.o \ - "$STAGING"/ecdsa384.o "$STAGING"/ecdsa384_msg.o \ - "$STAGING"/sha384*.o "$STAGING"/data_sha.o \ - "$STAGING"/inv256.o "$STAGING"/data_p256_invref.o -fi +# 4b. RETIRED at the libs/nistcurves v0.11.0 pin. This used to delete ~13 +# non-P-256 members (fp384/mod384/curve384/points384_*/data_p384*/ +# ecdsa384*/sha384*/data_sha/inv256/data_p256_invref) from the full +# `lib-onchip` archive, because no narrowed comb archive existed. +# `lib-p256-comb-onchip` is now that archive, so there is nothing to +# strip — see the UPSTREAM_TARGET block at the top of this file. +# +# Do not reinstate this without also restoring the §6.6 comb exclusion in +# src/contract_footprint_asserts.s: the two moved together, and deleting +# members silently invalidates the §6.4 manifest the assert reads. if [ "$PROFILE" = "onchip" ] || [ "$PROFILE" = "onchip-comb" ]; then # Rebuild (not drop): fp256_onchip.o imports og_common/og_src_ld which # only this TU provides. The SHARED_* defines strip everything that diff --git a/tools/package/_common.sh b/tools/package/_common.sh index ef56ce17..bcc8d3b2 100644 --- a/tools/package/_common.sh +++ b/tools/package/_common.sh @@ -12,27 +12,21 @@ # |||<1541 filename>|| # # 1541 filenames are <=16 chars and lowercase here because c1541 uppercases -# into PETSCII on write. They are the same on the single-variant disk and on -# the per-backend disk, so a user only ever learns one name. Keep them stable -# across releases — people type them. +# into PETSCII on write. Keep them stable across releases — people type them. +# +# The field no longer selects a disk: per-backend combo images were +# retired when the UCI lineup reached three variants (3 x 248 blocks against a +# .d64's 664). It is retained because build_prgs.sh records it in build-info +# and verify_release.py tolerates its absence in old records. # # Nothing here is version-specific: adding a profile or a backend is one line, # and every downstream script picks it up with no further edits. PACKAGE_VARIANTS=( - "uci-reu|c64-https-uci-reu.prg|BACKEND=uci|uci-reu|uci|Ultimate 64 / C64 Ultimate (UCI networking). Needs the REU enabled. Faster below ~18 MHz — the right pick at stock 1 MHz." - "uci-onchip|c64-https-uci-onchip.prg|BACKEND=uci USE_NISTCURVES_ONCHIP=1|uci-noreu|uci|Ultimate 64 / C64 Ultimate (UCI networking). No REU required. Faster above ~18 MHz — the right pick at 32/48/64 MHz turbo." - "ip65-reu|c64-https-ip65-reu.prg|BACKEND=ip65|ip65-reu|ip65|Stock C64 + RR-Net / cs8900a cartridge. Needs an REU. Faster below ~18 MHz, i.e. at any speed a real stock C64 runs at." - "ip65-onchip|c64-https-ip65-onchip.prg|BACKEND=ip65 USE_NISTCURVES_ONCHIP=1|ip65-noreu|ip65|Stock C64 + RR-Net / cs8900a cartridge, no REU at all. The only image a bone-stock C64 can run end to end; slowest (~36 min per handshake at 1 MHz)." + "ip65-onchip|c64-https-ip65-onchip.prg|BACKEND=ip65 USE_NISTCURVES_ONCHIP=1|ip65-noreu|ip65|MAXIMUM COMPATIBILITY. Bone-stock C64 + RR-Net / cs8900a cartridge. No REU, no turbo, nothing optional at all — the only image a completely unmodified machine can run end to end. Slowest: ~36 min per handshake at 1 MHz." + "uci-onchip|c64-https-uci-onchip.prg|BACKEND=uci USE_NISTCURVES_ONCHIP=1|uci-noreu|uci|TURBO, NO REU. Ultimate 64 / C64 Ultimate at 32/48/64 MHz with the REU disabled or absent. Boots straight to the menu." + "uci-comb|c64-https-uci-comb.prg|BACKEND=uci USE_NISTCURVES_ONCHIP_COMB=1|uci-comb|uci|TURBO + REU — FASTEST. Ultimate 64 / C64 Ultimate at 32/48/64 MHz with the REU enabled. ~1.7x faster verify than the no-REU turbo image (measured: 16.4 s vs 28.4 s on a U64E at 48 MHz). Costs a one-time table build at every boot: ~34 s at 64 MHz, ~45 s at 48 MHz. Needs REU bank 2." ) -# Backends, in matrix order, deduplicated. Used for the per-backend disks. -package_backends() { - local line - for line in "${PACKAGE_VARIANTS[@]}"; do - printf '%s\n' "$(variant_field "$line" 5)" - done | awk 'NF && !seen[$0]++' -} - # Field accessors — `variant_field <1-based index>`. variant_field() { printf '%s' "$1" | cut -d'|' -f"$2"; } @@ -62,12 +56,28 @@ submodule_pins() { git -C "$PROJECT_ROOT" config --file .gitmodules \ --get-regexp '^submodule\..*\.path$' 2>/dev/null \ | awk '{print $2}' | sort | while read -r sub; do - local sha tag - sha="$(git -C "$PROJECT_ROOT" ls-tree HEAD "$sub" | awk '{print $3}')" - [ -n "$sha" ] || continue - tag="$(git -C "$PROJECT_ROOT/$sub" describe --tags --exact-match "$sha" \ + local head_sha built_sha tag + # The COMMITTED gitlink... + head_sha="$(git -C "$PROJECT_ROOT" ls-tree HEAD "$sub" | awk '{print $3}')" + # ...and what is actually CHECKED OUT, which is what the PRGs were + # built against. These differ whenever a submodule bump has not been + # committed yet, and reporting the gitlink in that state puts a wrong + # library version in a release manifest with no warning — observed for + # real: a build against nistcurves v0.11.0 / x25519 v0.11.1 produced a + # MANIFEST claiming v0.10.1 / v0.11.0. + built_sha="$(git -C "$PROJECT_ROOT/$sub" rev-parse HEAD 2>/dev/null || true)" + [ -n "$built_sha" ] || built_sha="$head_sha" + [ -n "$built_sha" ] || continue + # --tags matters: c64-x25519 has tagged releases lightweight, and + # `describe` without it considers annotated tags only. + tag="$(git -C "$PROJECT_ROOT/$sub" describe --tags --exact-match "$built_sha" \ 2>/dev/null || true)" [ -n "$tag" ] || tag="(untagged)" - printf '%s %s %s\n' "$sub" "$sha" "$tag" + # Say so loudly rather than quietly reporting the built sha: a release + # whose submodules are not committed cannot be rebuilt from HEAD. + if [ -n "$head_sha" ] && [ "$built_sha" != "$head_sha" ]; then + tag="$tag !! UNCOMMITTED BUMP — HEAD gitlink is ${head_sha%"${head_sha#????????????}"}" + fi + printf '%s %s %s\n' "$sub" "$built_sha" "$tag" done } diff --git a/tools/package/build_d64.sh b/tools/package/build_d64.sh index c7f8f694..6a91befa 100755 --- a/tools/package/build_d64.sh +++ b/tools/package/build_d64.sh @@ -95,14 +95,13 @@ for line in "${PACKAGE_VARIANTS[@]}"; do make_disk "$DIST/c64-https-$key.d64" "$key" "01" "$DIST/$prg" "$name" done -# --- One image per backend, carrying that backend's profiles ------------------ -for backend in $(package_backends); do - args=() - for line in "${PACKAGE_VARIANTS[@]}"; do - [ "$(variant_field "$line" 5)" = "$backend" ] || continue - args+=("$DIST/$(variant_field "$line" 2)" "$(variant_field "$line" 4)") - done - make_disk "$DIST/c64-https-$backend.d64" "c64-https $backend" "01" "${args[@]}" -done +# --- No per-backend combo images ------------------------------------------ +# Retired deliberately. Their premise was "a user only ever learns one +# name", and that breaks the moment a backend carries three variants: the +# UCI set is 3 x 248 = 744 blocks against a .d64's 664, so a combo image +# could not hold the lineup even if we wanted one. Rather than ship a disk +# that silently omits a variant, every image now carries exactly the one +# product named on its label, so what a consumer downloads is what they +# get. See PACKAGE_VARIANTS in _common.sh for the three products. echo "[package] disk images complete." diff --git a/tools/package/build_prgs.sh b/tools/package/build_prgs.sh index aa73b8d5..95b88bf5 100755 --- a/tools/package/build_prgs.sh +++ b/tools/package/build_prgs.sh @@ -43,6 +43,18 @@ cd "$PROJECT_ROOT" mkdir -p "$DIST" +# Clear stale PRGs from a previous, differently-shaped run — the same reason +# build_d64.sh clears stale .d64s. Without this, RETIRING a variant leaves its +# PRG behind and write_manifest.sh hashes every artifact present in dist/, so +# the dropped variant reappears in the checksum list with no disk, no +# description and no verification behind it. Observed for real when the +# lineup went from four variants to three: c64-https-{ip65,uci}-reu.prg +# survived into MANIFEST.txt as though they had shipped. +# +# Scoped to our own PRGs on purpose: dist/ also holds the generated listener, +# and a blanket wipe would delete work this script cannot rebuild. +rm -f "$DIST"/c64-https-*.prg + GIT_HEAD="$(git rev-parse HEAD)" GIT_HEAD_SHORT="$(git rev-parse --short HEAD)" GIT_DIRTY="" diff --git a/tools/package/verify_release.py b/tools/package/verify_release.py index 843446f2..682849e9 100755 --- a/tools/package/verify_release.py +++ b/tools/package/verify_release.py @@ -131,15 +131,12 @@ def expected_d64_images(variants: list[dict]) -> list[Path]: failed check rather than a check nobody ran. """ ok = [r for r in variants if r.get("result") == "OK"] + # One image per variant, and ONLY that. The per-backend combo disks were + # retired when the UCI lineup reached three variants: 3 x 248 = 744 + # blocks does not fit a .d64's 664, so a combo image would have had to + # silently omit a product. Every disk now carries exactly the one + # variant named on its label. images = [DIST / f"c64-https-{r['key']}.d64" for r in ok] - backends: list[str] = [] - for r in ok: - # backend= is written by build_prgs.sh; older build-info files predate - # it, so fall back to the key's prefix rather than crashing. - b = r.get("backend") or r["key"].split("-")[0] - if b not in backends: - backends.append(b) - images += [DIST / f"c64-https-{b}.d64" for b in backends] return sorted(set(images)) diff --git a/tools/package/write_manifest.sh b/tools/package/write_manifest.sh index a228556e..31ec913a 100755 --- a/tools/package/write_manifest.sh +++ b/tools/package/write_manifest.sh @@ -71,23 +71,46 @@ echo "-------------------------------------------------------------------------- echo " WHICH ONE DO I WANT?" echo "------------------------------------------------------------------------------" echo -echo "Two questions decide it." +echo "Three things decide it." echo echo "1. How is your C64 on the network?" echo " Ultimate 64 / Ultimate 64 Elite / C64 Ultimate -> the 'uci' images" echo " a stock C64 with an RR-Net / cs8900a cartridge -> the 'ip65' images" echo -echo "2. Do you have a RAM Expansion Unit (REU), and how fast is the CPU?" -echo " 'reu' images use the REU to accelerate the ECDSA verify. They need" -echo " one, and they are FASTER below about 18 MHz — which includes every" -echo " real stock C64 at 1 MHz." -echo " 'onchip' images need NO REU at all and do the same work on the CPU." -echo " They are FASTER above about 18 MHz, so they are the right pick for" -echo " Ultimate turbo modes (32/48/64 MHz)." -echo " The ~18 MHz crossover is measured, not estimated: the REU's DMA rate is" -echo " anchored to the ~1 MHz bus, so the REU profile carries a wall-clock" -echo " floor no amount of turbo removes, while the on-chip profile scales with" -echo " the clock. On a U64E the sign flips between the 16 and 20 MHz settings." +echo "2. Which of the three do I want?" +echo " Three products, one disk each. The disk carries exactly what its" +echo " label says — there are no combined images to pick through." +echo +echo " ip65-onchip a completely unmodified C64 + RR-Net cartridge." +echo " No REU, no turbo, no options. If you are not sure" +echo " what you have, this is the one that will run." +echo " ~36 min per handshake at 1 MHz." +echo +echo " uci-onchip Ultimate 64 / C64 Ultimate at turbo, REU off." +echo " Boots straight to the menu." +echo +echo " uci-comb Ultimate 64 / C64 Ultimate at turbo, REU ON." +echo " The fastest image: ~1.7x quicker verify than" +echo " uci-onchip. It builds a 16 KB table into REU" +echo " bank 2 at every boot before the menu appears —" +echo " ~34 s at 64 MHz, ~45 s at 48 MHz. That is the" +echo " program working, not a hang." +echo +echo " Why the split: below about 5 MHz the extra table work costs more" +echo " than it saves, and below ~18 MHz the plain REU multiply path wins" +echo " outright — so the comb image is a turbo product and the compat" +echo " image is a stock-clock one. Both crossovers are measured, not" +echo " estimated; see the wall-clock sections of CLAUDE.md." +echo +echo "3. The screen goes blank during the slow parts. That is deliberate." +echo " Every image blanks the VIC-II across the two X25519 scalar" +echo " multiplies and the ECDSA verify, which stops the video chip" +echo " stealing bus cycles and buys about 6.5%. Measured, not guessed:" +echo " 6.35% in VICE at 1 MHz, 6.78% (on-chip) and 6.60% (REU) on a" +echo " U64E at 48 MHz." +echo " The screen comes back between handshake phases, so the progress" +echo " line keeps updating — if it is blank for minutes at a time, that" +echo " is the crypto running, not a hang." echo for line in "${PACKAGE_VARIANTS[@]}"; do key="$(variant_field "$line" 1)" @@ -101,7 +124,7 @@ for line in "${PACKAGE_VARIANTS[@]}"; do fi echo " $prg" echo " $note" - echo " disk: c64-https-$key.d64 (also on c64-https-$(variant_field "$line" 5).d64)" + echo " disk: c64-https-$key.d64" echo done echo "------------------------------------------------------------------------------" @@ -134,16 +157,16 @@ echo "-------------------------------------------------------------------------- echo " DISK IMAGES (.d64)" echo "------------------------------------------------------------------------------" echo -echo " Each variant ships as its own single-PRG 1541 image, plus one image per" -echo " networking backend carrying both of that backend's profiles. Load with:" +echo " One product per disk, one PRG per disk. Load with:" echo -echo " LOAD\"*\",8,1 (single-variant disks — one file, first on disk)" -echo " LOAD\"UCI-REU\",8,1 (or whichever name the directory shows)" +echo " LOAD\"*\",8,1" echo " RUN" echo -echo " There is deliberately no all-in-one image: the four PRGs total 868 blocks" -echo " and a .d64 has 664 free. Each backend's pair does fit (UCI 496, ip65 372)," -echo " so the per-backend disk is the largest bundle a real 1541 can hold." +echo " There are deliberately no combined images. A .d64 has 664 free blocks and" +echo " each UCI PRG is 248, so the three-product lineup (744 blocks) cannot fit on" +echo " one disk and a per-backend image would have had to silently omit a product." +echo " Shipping one variant per disk means the label is the whole contents: what" +echo " you downloaded is what boots." echo if [ -f "$D64_LIST" ]; then while IFS= read -r ln; do diff --git a/tools/test_package_verify.py b/tools/test_package_verify.py index 65315529..842e79e7 100644 --- a/tools/test_package_verify.py +++ b/tools/test_package_verify.py @@ -144,13 +144,16 @@ def test_expected_images_from_build_record() -> None: {"key": "ip65-onchip", "prg": "d.prg", "result": "OK", "backend": "ip65"}, ] names = sorted(p.name for p in vr.expected_d64_images(variants)) - check("four singles plus two per-backend images", names, [ + # One disk per variant and nothing else. The per-backend combo images were + # retired when the UCI lineup reached three variants (3 x 248 blocks does + # not fit a .d64's 664), so a combo disk would have had to silently omit a + # product. This test previously pinned the combo contract and is what + # caught the change — keep it pinning the CURRENT one. + check("one disk per variant, no combo images", names, [ "c64-https-ip65-onchip.d64", "c64-https-ip65-reu.d64", - "c64-https-ip65.d64", "c64-https-uci-onchip.d64", "c64-https-uci-reu.d64", - "c64-https-uci.d64", ]) @@ -162,8 +165,8 @@ def test_expected_images_skip_failed_variants() -> None: {"key": "uci-onchip", "prg": "b.prg", "result": "FAILED", "backend": "uci"}, ] names = sorted(p.name for p in vr.expected_d64_images(variants)) - check("only the built variant's disk plus its backend disk", names, - ["c64-https-uci-reu.d64", "c64-https-uci.d64"]) + check("only the built variant's disk", names, + ["c64-https-uci-reu.d64"]) def test_expected_images_empty_when_nothing_built() -> None: @@ -175,12 +178,17 @@ def test_expected_images_empty_when_nothing_built() -> None: def test_expected_images_tolerate_old_build_info() -> None: - """backend= was added late; a build-info without it must not crash.""" + """backend= was added late; a build-info without it must not crash. + + The derivation no longer READS backend= (combo disks are gone), so this is + now purely a no-crash guard on old records rather than a check that the + backend is inferred correctly. + """ print("\n-- a build record predating backend= still derives correctly --") variants = [{"key": "ip65-onchip", "prg": "d.prg", "result": "OK"}] names = sorted(p.name for p in vr.expected_d64_images(variants)) - check("backend inferred from the key prefix", names, - ["c64-https-ip65-onchip.d64", "c64-https-ip65.d64"]) + check("no crash without backend=", names, + ["c64-https-ip65-onchip.d64"]) # --------------------------------------------------------------------------- diff --git a/tools/uci/_reu_preflight.py b/tools/uci/_reu_preflight.py index 0c4ba630..da85b106 100644 --- a/tools/uci/_reu_preflight.py +++ b/tools/uci/_reu_preflight.py @@ -140,19 +140,42 @@ def detect_crypto_profile(labels_path: Path | str) -> tuple[str, str]: return ("reu", f"could not read {labels_path} — assuming REU profile") banks = labels.get(_BANKS_EQUATE) - if banks == 0: - return ("onchip", f"{_BANKS_EQUATE}=0") + # The manifest equate is AUTHORITATIVE whenever it is present, and it + # decides in BOTH directions. The on-chip symbols are a fallback for + # when it is absent, not co-equal votes. + # + # This ordering is load-bearing, and getting it wrong shipped a real + # hole. The comb profile (USE_NISTCURVES_ONCHIP_COMB) generates multiply + # rows on the CPU — so `gen_mul_row`, `fe_gen_mul_row` and + # `sqtab_reserved` are all present — while still claiming REU **bank 2** + # for the 16 KB Lim-Lee anchor table: it links with + # LIB_NISTCURVES_REU_BANKS_USED = $04, not 0. Under the previous + # symbol-union-first ordering those three symbols outvoted the equate, + # the comb build was classified "onchip", and the device REU check was + # skipped entirely — printing "no REU required" for an image that does + # not work without one. Measured on a real comb build, 2026-08-15. + # + # That is exactly the failure #97's preflight exists to prevent, and it + # matters more now that comb is a shipped product whose whole premise is + # REU-plus-turbo. + if banks is not None: + if banks == 0: + return ("onchip", f"{_BANKS_EQUATE}=0") + return ("reu", f"{_BANKS_EQUATE}=${banks:02X} — claims REU bank(s)") + + # No manifest equate: fall back to the symbol union. Union rather than + # conjunction so renaming any single symbol upstream cannot silently + # reclassify an onchip build as REU-profile and block the configuration + # we recommend to REU-less users. found = [name for name in _ONCHIP_SYMBOLS if name in labels] if found: - return ("onchip", "+".join(found)) - - if banks is None: - # No manifest equate and no onchip symbol. Most likely a genuine - # REU-profile build; possibly a library layout we do not know. - # Fail closed — the check is skippable, 44 minutes of spin is not. - return ("reu", f"no {_BANKS_EQUATE} and no on-chip row generator") - return ("reu", f"{_BANKS_EQUATE}={banks}") + return ("onchip", "+".join(found) + f" (no {_BANKS_EQUATE})") + + # No manifest equate and no onchip symbol. Most likely a genuine + # REU-profile build; possibly a library layout we do not know. + # Fail closed — the check is skippable, 44 minutes of spin is not. + return ("reu", f"no {_BANKS_EQUATE} and no on-chip row generator") def _extract_config_value(resp: Any, category: str, item: str) -> str | None: