Skip to content
22 changes: 22 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -319,6 +319,28 @@ Second device: C64 Ultimate "Starlight", `U64_HOST=10.53.21.158`, fw 1.1.0,
Scratch DMA addresses come from `build_policy_and_arbiter()`
(`_memory_policy.py`, parses `build/labels.txt`) — never hardcode them.

**The acquire budget is `C64_DEVICE_LOCK_TIMEOUT`, default 1800 s**, and
it is one number: every rig here and `tests/rig_ip65_rrnet_hw.py` takes
the lock through `acquire_device_lock()` in `_device_lock_helper.py`, and
`tools/test_device_lock_timeout.py` fails if one grows its own back (it
also pins the malformed-value and progress-window behaviour). The budget
is **not** how long you may queue behind a running rig: the harness's
`acquire` re-arms its deadline indefinitely behind a live, progressing
holder, so the budget only bounds waits it refuses to extend — a wedged
holder, or a *handoff chain*. **The chain boundary is the FOURTH change
of holder identity, not the third**: `_MAX_HOLDER_HANDOFFS` is 3, but the
harness extends while `handoffs <= 3` and its own docstring says
otherwise (a harness doc bug — its WARNING text agrees with its code).
Pinned by `test_the_handoff_boundary_is_four_changes_not_three`; do not
re-derive it from their prose. That case is what several lanes cycling
one U64E *would* produce — the mechanism is lab-measured, no such
timeout has been captured from a real run here — and it is why the old
hardcoded 120 s could fail against a device that was merely busy. A
malformed value is fatal before the device is touched; a wait prints
progress to stderr every 30 s (elapsed, budget, holder PID, lockfile age
with a STALE flag past the 60 s progress window, queue depth), never to
stdout.

boot_check.py / phase2_check.py / phase3_tcp_echo.py — boot, DHCP, TCP
rig_http_local.py / rig_http_live.py — plaintext HTTP
rig_https_local.py — HTTPS vs local TLS 1.3 listener
Expand Down
32 changes: 32 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -739,6 +739,37 @@ The device address comes from `U64_HOST`. Every rig script defaults it to
device-queue helper — defaults to a different address, so **set `U64_HOST`
explicitly** rather than relying on a default agreeing with itself.

The device is shared — across sessions and across the `c64-*` repos — so every
script here queues for it, and the wait has **one** budget:
`C64_DEVICE_LOCK_TIMEOUT`, default **1800 s (30 min)**. Every rig takes the
lock through `acquire_device_lock()` in `tools/uci/_device_lock_helper.py`, and
`tools/test_device_lock_timeout.py` fails if any script grows a budget of its
own back. A malformed value (`30m`, `2 min`, `0`) is a hard error before the
device is touched rather than a silent fall back to the default; an empty value
falls back with a notice. While waiting, a progress line goes to **stderr**
every 30 s — elapsed, budget, holder PID, lockfile age (flagged stale past the
60 s progress window) and queue depth — so a half-hour block is distinguishable
from a hang. stdout stays parseable.

That budget is **not** the longest run you may queue behind. The harness
re-arms its deadline on every poll while the holder is alive and its lockfile
is fresh, so a waiter sits behind one long healthy holder indefinitely; the
budget bounds only the waits it refuses to extend — a dead or wedged holder,
and a **handoff chain**. Several lanes cycling one device is the case that
bites: after the **fourth** change of holder identity the harness stops
extending for the rest of that acquire (four, not three — `_MAX_HOLDER_HANDOFFS`
is 3 but extension survives `handoffs <= 3`), and from there the budget is
everything. Take that boundary from `tools/test_device_lock_timeout.py`, which
asserts it against the harness's real behaviour: the upstream docstring that
said three was fixed in c64-test-harness#232 and is now deliberately
literal-free, so there is no number there to check yours against. That is issue #212, and it
is why the old hardcoded 120 s could fail against a device that was merely
busy. Raise it when you know you are behind a long run:

```bash
C64_DEVICE_LOCK_TIMEOUT=7200 python3 tools/uci/rig_https_live.py # queue for 2 h
```

**Prerequisite — `c64-test-harness` (same as the VICE suites above).** It is a separate public package, not vendored here; `requirements.txt` carries only `cryptography`. Without it every script in this directory dies at import with `ModuleNotFoundError: No module named 'c64_test_harness'`:

```bash
Expand Down Expand Up @@ -816,6 +847,7 @@ control. `tools/test_finished_verify.py` is the VICE-only equivalent.
Environment variables honored by `rig_https_local.py`:

- `U64_HOST` (default `192.168.1.81`) — U64E address
- `C64_DEVICE_LOCK_TIMEOUT` (default `1800`) — seconds to queue for the shared device; see the paragraph above
- `TURBO_MHZ` (default `48`) — C64 CPU speed. `TURBO_MHZ=1` runs the test at stock 1 MHz with every wall-clock budget auto-scaled, and is validated end-to-end on real U64E hardware; the handshake + GET itself measured 1,157.7 s (~19 min) there, not the full budget.
- `HTTPS_PORT` (default `443`, falls back to `4433` if the bind fails)
- `SENTINEL_POLL_TIMEOUT`, `ACCEPT_TIMEOUT` — per-test overrides in seconds; default to `600 * max(1, 48 / TURBO_MHZ)`.
Expand Down
1 change: 1 addition & 0 deletions pytest.ini
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
[pytest]
testpaths =
tools/test_build_flags_stamp.py
tools/test_device_lock_timeout.py
tools/test_flags_stamp_skip_is_loud.py
tools/test_ip65_hw_checks_unit.py
tools/test_net_test_env.py
Expand Down
13 changes: 11 additions & 2 deletions tests/rig_ip65_rrnet_hw.py
Original file line number Diff line number Diff line change
Expand Up @@ -183,12 +183,16 @@

PROJECT_ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(PROJECT_ROOT / "tools"))
sys.path.insert(0, str(PROJECT_ROOT / "tools" / "uci"))
for _p in ("/Users/someone/Documents/c64-test-harness/src",):
if os.path.isdir(_p) and _p not in sys.path:
sys.path.insert(0, _p)

import ip65_hw_checks as hw # noqa: E402
from _skip_policy import cannot_run, not_applicable # noqa: E402
from _device_lock_helper import ( # noqa: E402
LockTimeoutConfigError, acquire_device_lock,
)
from https_e2e import ( # noqa: E402
press_key, get_screen_text, wait_for_screen_text,
start_https_listener, stop_https_listener,
Expand Down Expand Up @@ -228,7 +232,9 @@
U64_HOST = os.environ.get("U64_HOST", "10.43.23.81")
HTTPS_PORT = int(os.environ.get("HTTPS_PORT", "4433"))
FETCH_BUDGET_S = float(os.environ.get("E2E_TIMEOUT", "4800"))
LOCK_TIMEOUT_S = 120.0
# The device-lock budget is no longer a constant here: it is the one
# shared, C64_DEVICE_LOCK_TIMEOUT-overridable number owned by
# tools/uci/_device_lock_helper.py.
TURBO_MHZ = int(os.environ.get("TURBO_MHZ", "1"))
#: Phase-timeline resolution. At 1 MHz a phase lasts minutes and a 5 s
#: cadence is free; at turbo the whole handshake is under a minute, so 5 s
Expand Down Expand Up @@ -813,7 +819,10 @@ def main() -> int:

lock = DeviceLock(U64_HOST)
try:
lock.acquire_or_raise(timeout=LOCK_TIMEOUT_S)
acquire_device_lock(lock)
except LockTimeoutConfigError as exc:
return cannot_run(str(exc), executed=0, total=1, certifies=CERTIFIES,
opt_out_env=None)
except DeviceLockTimeout as exc:
return cannot_run(f"another lane holds {U64_HOST}: {exc}",
executed=0, total=1, certifies=CERTIFIES,
Expand Down
Loading