Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
82a549a
package-m3-demo: a "just run it" disk for the uci-m3 variant
JC-000 Oct 1, 2026
4d19a11
rig_https_m3_demo: judge the negative only by text after its own banner
JC-000 Oct 1, 2026
5557f84
package-m3-demo: release-ready assets; firmware stated by interface, …
JC-000 Oct 1, 2026
52fe8c7
package-m3-demo: README claims measured on this image or labelled (ad…
JC-000 Oct 1, 2026
7ed1147
package-m3-demo: scrubbed make env, flags.stamp check, refuse a dirty…
JC-000 Oct 5, 2026
ca9129f
rigs (uci-m3): wait for the re-init's own DHCP OK; demo rig on shared…
JC-000 Oct 5, 2026
d1b28fd
rig_https_m3_demo: re-mount by image_file alone; drop the dead /Temp …
JC-000 Oct 5, 2026
2fe7efc
rig device prep: a uci-m3 build needs no REU, and is run with it off
JC-000 Oct 5, 2026
85b7702
rig_https_m3_demo: delete our own /Temp upload after the unmount
JC-000 Oct 5, 2026
0783640
rigs (uci-m3): no stale-text verdicts; restore drive A safely; per-ru…
JC-000 Oct 5, 2026
24f449f
package-m3-demo: README records the toolchain (path + sha256) from fl…
JC-000 Oct 5, 2026
c646de1
rig_https_m3_demo: re-mount any earlier image; delete the upload last…
JC-000 Oct 5, 2026
53640e1
detect_crypto_profile: an M3 build with the REU body sink is not 'none'
JC-000 Oct 5, 2026
91a14d0
rig_https_m3 ab: refuse a B that is not an on-chip build
JC-000 Oct 5, 2026
551c12b
test_device_prep: rig_https_m3 is discovered now, not registered
JC-000 Oct 5, 2026
b54fcb6
package-m3-demo: README firmware line and figures from the 2026-10-06…
JC-000 Oct 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -616,7 +616,7 @@ LINK_MAP := build/c64-https.map
LINK_DBG := build/c64-https.dbg
LINK_OUTPUTS := $(PRG) $(LABELS) $(LINK_MAP) $(LINK_DBG)

.PHONY: all link run clean ip65-libs ip65-blob package package-verify
.PHONY: all link run clean ip65-libs ip65-blob package package-verify package-m3-demo

all: $(PRG)

Expand Down Expand Up @@ -1305,5 +1305,12 @@ package-verify:
$(PACKAGE_PYTHON) tools/test_package_verify.py
$(PACKAGE_PYTHON) tools/package/verify_release.py

# The BACKEND=uci-m3 "just run it" demo (TLS on the Ultimate's ESP32): one
# PRG + .d64 + README in dist/m3-demo/. Not part of `package`: the M3
# variant is secondary and stays out of PACKAGE_VARIANTS. The script builds
# from clean twice (reproducibility) and reads the PRG back out of the .d64.
package-m3-demo:
bash tools/package/build_m3_demo.sh

# The per-object dependency files written by the build/%.o rule above.
-include $(ALL_OBJS:.o=.d)
232 changes: 232 additions & 0 deletions tools/package/build_m3_demo.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,232 @@
#!/usr/bin/env bash
# =============================================================================
# tools/package/build_m3_demo.sh — the "just run it" BACKEND=uci-m3 demo.
#
# Produces dist/m3-demo/ from a clean tree:
#
# c64-https-uci-m3-demo.prg the M3 client, default target en.wikipedia.org
# c64-https-uci-m3-demo.d64 that PRG alone, bootable with LOAD"*",8,1
# README.txt what it is, what it needs, how to run it, and
# the provenance (commit, flags, sha256s)
# SHA256SUMS sha256 of the PRG, the .d64 and README.txt,
# in `shasum -a 256 -c` form
#
# These four are the GitHub pre-release's assets; nothing else is written.
#
# Separate from `make package` on purpose. The M3 variant is SECONDARY (the
# 6510 crypto is the product), so it is not in PACKAGE_VARIANTS, and nothing
# here reads or writes that matrix or the shipped products in dist/.
#
# It refuses a working tree with any change, untracked files included: the
# README names a commit, and the PRG must be what that commit builds.
#
# make runs in a scrubbed environment (PATH, HOME, TMPDIR only), so neither
# an exported knob (HTTPS_SNI=..., VIC_BLANK=0) nor one given on the
# `make package-m3-demo` command line (it reaches here through MAKEFLAGS)
# can leak into the demo build. build/flags.stamp is then checked to hold
# the uci-m3 cfg and no -D beyond the backend's own.
#
# It proves its own output before writing the README:
# - a second clean build reproduces the PRG byte for byte;
# - c1541 reads the PRG back out of the .d64, byte for byte.
# Any failure exits non-zero and leaves no README, so a half-made demo never
# looks finished.
#
# Usage: make package-m3-demo [C1541=... to override the tool]
# =============================================================================
set -euo pipefail

PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
cd "$PROJECT_ROOT"

C1541="${C1541:-c1541}"
OUT="dist/m3-demo"
NAME="c64-https-uci-m3-demo"
DISK_FILE="c64-https-m3" # the 1541 file name (<= 16 chars)
DEMO_HOST="en.wikipedia.org"
DEMO_PATH="/wiki/Commodore_64"
MAKE_ARGS=(BACKEND=uci-m3 "HTTPS_HOST=$DEMO_HOST" "HTTPS_PATH=$DEMO_PATH")

# What the firmware side published; quoted in the README, checked nowhere
# here (the device is not involved in a build).
# The requirement is the interface; the build named is only where it was
# validated. The upstream PR numbers are not known yet; the README carries a
# marked slot for them (UPSTREAM_PRS overrides it once they exist).
FIRMWARE="M3-SPEC v1 + errata v1.1/v1.2 firmware (validated on esp-tls/m3-master 3a1ff9ff: fw 3.15, FPGA 126, ESP 1.309)"
UPSTREAM_PRS="${UPSTREAM_PRS:-[TO BE FILLED IN: 1541ultimate upstream PR number(s)]}"
SPEC="M3-SPEC v1 (= r7.7), sha256 c265fdfcfdd08dee989a96eee25fae66fb6650ee4be8bb24f8dd791d9ee3db9f, with errata v1.1 (f9a39ff334b34cb0e1a63d5d508675de552ac8eacb23ccd6095a7f4c72788f9a) and v1.2 (a6802f40db3229d53591ef6e0773641d723186e779dd8726abff5915cbe551a4)"

die() { echo "[m3-demo] ERROR: $*" >&2; exit 1; }
sha() { shasum -a 256 "$1" | cut -d' ' -f1; }

command -v "$C1541" >/dev/null 2>&1 \
|| die "c1541 not found in PATH (it ships with VICE). Set C1541=... to override."

[ -z "$(git status --porcelain --untracked-files=all)" ] \
|| { git status --short --untracked-files=all >&2
die "the working tree is not clean (untracked files count): commit or remove the changes above"; }

rm -rf "$OUT"
mkdir -p "$OUT"
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT

scrubbed_make() {
env -i PATH="$PATH" HOME="$HOME" ${TMPDIR:+TMPDIR="$TMPDIR"} make "$@"
}

# The demo is the bare backend: its -D set, its cfg, the default target.
check_stamp() {
local stamp=build/flags.stamp defines
grep -qx 'BACKEND=uci-m3' "$stamp" || die "$stamp: BACKEND is not uci-m3"
grep -q '^LD65FLAGS=-C cfg/c64-https-uci-m3.cfg ' "$stamp" \
|| die "$stamp: not linked with cfg/c64-https-uci-m3.cfg"
defines="$(grep '^CA65FLAGS=' "$stamp" | grep -o -- '-D [^ ]*' | tr '\n' ' ')"
[ "$defines" = "-D BACKEND_UCI=1 -D BACKEND_UCI_M3=1 " ] \
|| die "$stamp: unexpected defines: $defines"
grep -qx ".define HTTPS_HOST_STR \"$DEMO_HOST\"" build/https_host.inc \
&& grep -qx ".define HTTPS_PATH_STR \"$DEMO_PATH\"" build/https_host.inc \
&& grep -qx '.define HTTPS_SNI_STR ""' build/https_host.inc \
|| die "build/https_host.inc does not hold the demo target"
}

build_once() {
scrubbed_make clean >/dev/null
scrubbed_make "${MAKE_ARGS[@]}" >"$tmp/build.log" 2>&1 \
|| { tail -20 "$tmp/build.log" >&2; die "build failed: make ${MAKE_ARGS[*]}"; }
check_stamp
}

echo "[m3-demo] building: make ${MAKE_ARGS[*]}"
build_once
cp build/c64-https.prg "$OUT/$NAME.prg"
flags_line="$(grep '^CA65FLAGS=' build/flags.stamp | sed 's/--bin-include-dir [^ ]*//g; s/ */ /g')"
# Path and sha256 of each tool make linked, from the stamp: a ca65 that is
# not cc65's shows here, since nothing else in this script can tell.
toolchain="$(grep '^TOOLCHAIN=' build/flags.stamp | sed 's/^TOOLCHAIN=//' \
| awk '{ for (i = 1; i + 2 <= NF; i += 3) print " " $i, $(i+1), $(i+2) }')"

echo "[m3-demo] rebuilding from clean to prove the PRG is reproducible"
build_once
[ "$(sha build/c64-https.prg)" = "$(sha "$OUT/$NAME.prg")" ] \
|| die "the second clean build differs from the first"

echo "[m3-demo] writing $NAME.d64"
"$C1541" -format "c64-https-m3,m3" d64 "$OUT/$NAME.d64" >/dev/null
"$C1541" -attach "$OUT/$NAME.d64" -write "$OUT/$NAME.prg" "$DISK_FILE,p" >/dev/null
"$C1541" -attach "$OUT/$NAME.d64" -read "$DISK_FILE" "$tmp/readback.prg" >/dev/null
cmp -s "$tmp/readback.prg" "$OUT/$NAME.prg" \
|| die "the PRG read back out of the .d64 differs from the one written"
listing="$("$C1541" -attach "$OUT/$NAME.d64" -list \
| grep -Ev '^(OPENCBM:|D64 disk image |Unit [0-9]+ drive )')"

commit="$(git rev-parse HEAD)"
prg_sha="$(sha "$OUT/$NAME.prg")"
d64_sha="$(sha "$OUT/$NAME.d64")"
prg_bytes="$(wc -c < "$OUT/$NAME.prg" | tr -d ' ')"

cat > "$OUT/README.txt" <<EOF
c64-https M3 demo — HTTPS on a C64, with TLS done by the Ultimate's ESP32
==========================================================================

The C64 speaks HTTP; the Ultimate's ESP32 runs the TLS session (connect,
handshake, certificate verification against its Mozilla CA store) through the
M3 TLS-socket commands of the Ultimate Command Interface. This is a
SECONDARY variant of c64-https: the main product does all of TLS 1.3 on the
6510 itself and does not need this firmware.

Files
-----
$NAME.prg $prg_bytes bytes
sha256 $prg_sha
$NAME.d64 the PRG alone, as "$DISK_FILE"
sha256 $d64_sha

Directory of the .d64:
$(printf '%s\n' "$listing" | sed 's/^/ /')

Built from
----------
commit $commit
make ${MAKE_ARGS[*]}
$flags_line
toolchain (path, sha256):
$toolchain
The PRG is deterministic: \`make clean && make ${MAKE_ARGS[*]}\` at that
commit reproduces the sha256 above (this script checked it twice).

What it needs
-------------
- An Ultimate 64 (Elite) running firmware with the M3 TLS sockets:
$FIRMWARE.
1541ultimate upstream PR(s): $UPSTREAM_PRS
- Its WiFi module up (the ESP32 does the TLS), the network connected, and
the clock set by SNTP (certificate dates are checked).
- The Ultimate's Command Interface enabled.
- No REU. Turbo is optional but recommended: the client paces every UCI
register access for the FPGA, so large pages are slow at 1 MHz (not
measured there; see the measured 48 MHz times below).
Interface implemented: $SPEC.

How to run it
-------------
Mount the .d64 on drive 8, then:
LOAD"*",8,1
RUN
The program starts the network (I re-runs it), then:
G fetch a page. It asks for HOST and PATH; RETURN on an empty
field keeps the default, $DEMO_HOST $DEMO_PATH.
Q quit to BASIC.
A fetch prints OPEN TLS (ULTIMATE)..., TLS HANDSHAKE OK, PROTOCOL TLS 1.3,
REQUEST SENT, the first 200 bytes of the body, then CONNECTION CLOSED.
A body cut short of its own framing prints BODY INCOMPLETE and the
firmware's status line before CONNECTION CLOSED.

Three URLs to try
-----------------
1. $DEMO_HOST $DEMO_PATH (the default)
2. github.com /robots.txt
3. 208-80-153-224.nip.io / (a NEGATIVE: a Wikipedia address
under a name its certificate does not carry. Expected:
TLS HANDSHAKE FAILED / 94,CERTIFICATE NAME MISMATCH: 0x00000004.
It depends on two things outside this project: the nip.io DNS service,
and 208.80.153.224 still serving Wikipedia. If either changes, pick
another <ip-with-dashes>.nip.io name for a site whose certificate does
not name it.)

Measured with THIS image (PRG sha256 above), validated on an Ultimate 64
Elite (U64E), firmware 3.15 git 3a1ff9ff, 48 MHz, REU disabled, the .d64
mounted on drive 8 and loaded with LOAD"*",8,1
(tools/uci/rig_https_m3_demo.py), 2026-10-06:
1. HTTP 200, 751,848 B, complete by its chunked framing, 207 s from G to
CONNECTION CLOSED (the page size changes as the article is edited).
2. HTTP 200, 16,739 B consumed == Content-Length, 9 s.
3. Refused: 94,CERTIFICATE NAME MISMATCH: 0x00000004.
Other Ultimate models, and other clock speeds, have not been tested.

What an unsupported device shows
--------------------------------
(Per the M3 spec and our model tests, not yet observed on hardware with
this image.)
- Firmware without the M3 commands: I prints NETWORK INIT FAILED and the
firmware's answer, 21,UNKNOWN COMMAND.
- No Command Interface (a plain C64, or the interface disabled): NETWORK
INIT FAILED.
- M3 firmware but no usable TLS module (WiFi off, no ESP32, a build without
TLS): G waits up to 30 s for the module, then prints TLS HANDSHAKE FAILED
and 90,TLS NOT AVAILABLE (or 87 no entropy / 92 no trusted time).
- Any refusal prints the firmware's own status line, e.g. 93 (certificate
not trusted), 94 (name mismatch), 95 (expired).
- NETWORK INTERFACE NOT RESPONDING - PRESS RESET means the interface
stopped answering; the program halts on purpose. Press the reset button
(if it repeats, power-cycle the Ultimate).

Source: https://github.com/JC-000/c64-https (src/net/uci-m3/).
EOF

# SHA256SUMS last, over everything a release would attach (shasum -c format).
( cd "$OUT" && shasum -a 256 "$NAME.prg" "$NAME.d64" README.txt > SHA256SUMS )

echo "[m3-demo] done: $OUT"
echo "[m3-demo] $NAME.prg $prg_sha"
echo "[m3-demo] $NAME.d64 $d64_sha"
55 changes: 52 additions & 3 deletions tools/test_device_prep.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@
# on-chip row generator is the REU profile; the equate at 0 is on-chip.
LABELS_REU = "al 006000 .ecdsa_verify_256\nal 00A000 .tls_rec_buf\n"
LABELS_ONCHIP = "al 000000 .LIB_NISTCURVES_REU_BANKS_USED\nal 006000 .gen_mul_row\n"
LABELS_M3 = "al 00AF9F .m3_owned\nal 00BC00 .sqtab_lo\n"

#: A device at the factory default: 1 MHz, turbo off, no REU. This is the
#: ordinary state of a freshly power-cycled U64E, not a broken one — which is
Expand Down Expand Up @@ -362,6 +363,36 @@ def test_onchip_build_never_writes_the_reu() -> None:
assert "no REU configuration needed" in out


def test_m3_build_switches_the_reu_off() -> None:
"""uci-m3 needs no REU, and its runs prove it: the REU is turned OFF."""
report, writers, out = _run(FakeClient([READY_STATE, DEFAULT_STATE]),
labels=LABELS_M3)
assert report["profile"] == "none", out
assert writers.reu == [(False, None)], f"REU not switched off:\n{out}"
assert report["wanted"]["reu"] == "Disabled"
assert report["after"][f"{CAT_CART}/RAM Expansion Unit"] == "Disabled"


def test_m3_build_with_the_reu_off_writes_nothing() -> None:
report, writers, out = _run(FakeClient([DEFAULT_STATE]), labels=LABELS_M3)
assert writers.reu == [], f"redundant REU write:\n{out}"
assert "reu" in report["skipped_write"]


def test_m3_build_unreadable_reu_is_switched_off_anyway() -> None:
"""Disabling is the safe direction, so an unreadable state writes."""
blind = dict(READY_STATE)
blind[f"{CAT_CART}/RAM Expansion Unit"] = _HarnessError("read refused")
report, writers, out = _run(FakeClient([blind]), labels=LABELS_M3)
assert writers.reu == [(False, None)], out


def test_m3_build_refused_disable_is_exit_4() -> None:
exc = _assert_raises_prep(FakeClient([READY_STATE]), "refused disable",
labels=LABELS_M3, reu_raises=_HarnessError("400"))
assert "Disabled" in str(exc)


# --------------------------------------------- the REU write can itself fail

def test_a_refused_reu_write_is_exit_4_with_a_ladder_not_a_traceback() -> None:
Expand Down Expand Up @@ -558,6 +589,16 @@ def test_skipping_prep_warns_that_the_clock_is_unmanaged() -> None:
#: changes.
KNOWN_UNPREPPED: dict[str, str] = {}

#: Rigs the discovery rule below cannot see that still depend on the clock
#: and REU state the prep sets: the demo rig boots from the drive
#: (LOAD"*",8,1), not by DMA. Registered by name.
REGISTERED_RIGS = ("rig_https_m3_demo.py",)


def _covered_rigs():
"""What the contract covers: the discovered rigs plus the registered."""
return sorted(set(_crypto_path_rigs()) | {UCI / n for n in REGISTERED_RIGS})


def _crypto_path_rigs():
"""Discover the rigs this contract covers, rather than listing them.
Expand Down Expand Up @@ -609,7 +650,7 @@ def test_the_discovery_rule_finds_the_known_rigs() -> None:
"rig_https_live.py", "rig_https_local.py",
"rig_https_wiki.py", "rig_https_banner.py",
"rig_close_retry.py", "rig_https_refetch.py",
"rig_trust_policy.py"}
"rig_trust_policy.py", "rig_https_m3.py"}
assert names == expected, (
f"the discovery rule now selects {sorted(names)}, not "
f"{sorted(expected)}. If a rig was added or renamed that is fine — "
Expand All @@ -618,6 +659,14 @@ def test_the_discovery_rule_finds_the_known_rigs() -> None:
)


def test_registered_rigs_exist_and_are_not_discovered() -> None:
"""A registration is for a rig the rule misses; one it finds is noise."""
for name in REGISTERED_RIGS:
assert (UCI / name).is_file(), f"REGISTERED_RIGS names a missing file: {name}"
found = {p.name for p in _crypto_path_rigs()} & set(REGISTERED_RIGS)
assert not found, f"{sorted(found)} are discovered now: drop the registration"


def _call_lines(tree, name):
"""Line numbers of every ``name(...)`` call in *tree*."""
return sorted(
Expand All @@ -635,7 +684,7 @@ def test_every_crypto_rig_prepares_before_it_checks() -> None:
a convention, not a fix, and #197's defect was exactly four rigs holding
a guard with no setup behind it.
"""
for path in _crypto_path_rigs():
for path in _covered_rigs():
tree = ast.parse(path.read_text(), filename=str(path))
prep = _call_lines(tree, "prepare_device")
flight = _call_lines(tree, "preflight_reu")
Expand Down Expand Up @@ -680,7 +729,7 @@ def test_every_prepping_rig_hands_over_its_run_artifact_dir() -> None:
supplies its own Python-level default) it would write nothing at all.
So every call site passes `artifact_dir` explicitly.
"""
for path in _crypto_path_rigs():
for path in _covered_rigs():
if path.name in KNOWN_UNPREPPED:
continue
tree = ast.parse(path.read_text(), filename=str(path))
Expand Down
Loading