Crate tag_side_channel_check 

tag-side-channel-check: hardware check for the tagcore memory side channel and keepalive.

Port of host/commandline/tag-side-channel-check.cc. Attaches to a tag and checks, without changing tag state or writing tag memory:

• the target’s DBGMCU ID code reads while the tag runs;
• a multi-chunk SRAM read succeeds;
• unaligned and wrapping ranges return MemAccess::InvalidRange;
• on STM32U3, a write over monitor_shared returns MemAccess::Protected (the guard refuses it before any write);
• status and memory reads from two threads on one Tag never fail;
• last_error() is clean after a successful RPC;
• with --idle, the session survives an idle period with keep-alive calls, or, with --no-keepalive, the control case;
• reads after detach return MemAccess::NotAttached.

Three opt-in checks change tag memory or exercise failures, and need the operator’s agreement first:

• --write-test <addr> writes two patterns to one SRAM word, reads each back, then restores and re-reads the original value. The address must be word aligned, in SRAM and outside monitor_shared on both families; it is never forced.
• --start-running sends Start to a tag already RUNNING or HIBERNATING and expects PERM without a transport failure. It refuses to send Start to a tag in any other state.
• --unplug <s> polls status for up to s seconds while the operator unplugs the base, and expects the failure to be reported as a transport failure. It ends the run.

Prints one PASS or FAIL line per check and exits 1 on any FAIL. See host/libraries/tagcore/TODO.md. Not for shipping.

Usage: tag-side-channel-check [-d] [-b BUS:DEVICE] [--idle S] [--interval S] [--no-keepalive] [--threads S] [--write-test ADDR] [--start-running] [--unplug S]. Defaults: no idle check, KeepAlive every 2 s, a 10 s two-thread check. --idle with an --interval below 1 exits 1 before attaching. With --unplug the idle and after-detach checks are skipped, since the base is gone. Option errors exit 2 (clap).

Hardware side effects

The attach resets the tag, so “while the tag runs” means the monitor firmware after that reset, not a run in progress. Without the opt-in checks nothing is written to the tag. --write-test accepts any aligned address from the end of monitor_shared to the U375’s SRAM end (0x2004_0000); on an STM32L432, whose SRAM1 ends at 0x2000_C000, the range check alone does not keep the write inside SRAM, so take the address from the map file.

Structs

Cli 🔒

check tagcore memory access and keepalive on a live tag

Constants

FAILURES 🔒

FAIL lines reported so far; only the main thread calls report.

L4_DBGMCU_IDCODE 🔒

DBGMCU_IDCODE address on the STM32L4.

SRAM_BASE 🔒

Start of SRAM on both families, used for the read checks.

SRAM_LIMIT 🔒

Upper bound for –write-test addresses: the largest SRAM of the targets (STM32U375, 256 KB). The operator still picks the word from the map file.

U3_DBGMCU_IDCODE 🔒

DBGMCU_IDCODE address on the STM32U3.

Functions

failures 🔒

The number of FAIL lines reported so far.

finish 🔒

Prints the summary line and returns exit status 1 if any check failed, 0 otherwise.

hex 🔒

Formats a word as 0x and eight upper-case hex digits.

main 🔒

Validates the options, attaches and runs the checks in order, ending with the detach check.

parse_address 🔒

Parses an address as strtoul(text, &end, 0) does, requiring the whole string to be consumed and the value to fit 32 bits.

plausible_idcode 🔒

A plausible STM32 DBGMCU_IDCODE has a nonzero 12-bit device ID.

read_word 🔒

Reads one little-endian word, returning the access result and the word (unchanged from initial when the read fails).

report 🔒

Prints one PASS or FAIL line and counts failures.

settled_status 🔒

Polls status until the tag reports a definite state; attach connects under reset, so the first status can be STATE_UNSPECIFIED while the tag boots. None on an RPC failure or after about 10 s.

start_running_test 🔒

Sends Start to a running tag and checks the error reports PERM. Refuses to send Start unless the tag reports RUNNING or HIBERNATING, so it can never start an idle tag.

two_thread_check 🔒

Runs both threads for seconds and reports whether every call succeeded.

unplug_test 🔒

Polls status every 100 ms for up to seconds while the operator unplugs the base, and checks the failure is reported as a transport failure.

write_test 🔒

Writes patterns to one SRAM word agreed with the operator, reads each back, then restores the original; one PASS or FAIL line per step.