From efd3dd7013e2fab28a757f5bb1a23fc130a1a1de Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sun, 8 Nov 2026 18:44:06 -0400 Subject: [PATCH 1/2] tools+docs: the AXB35-02 plug test gets its precondition in one command (engine#823) precondition nobody could check in one command -- is the shipped keepawake rule even applicable to the machine in front of me, and are the controllers awake right now? -- so the one thing that would make the plug meaningful could not be verified before doing it. tools/xhci_keepawake_check.sh # read-only: DMI match, per-controller power state, verdict tools/xhci_keepawake_check.sh --require-awake # exit 1 unless every controller the rule matches is in D0 It reads the rule's own predicates (board_name == AXB35-02, vendor 0x1022, devices 0x1587/0x1588/0x1589/0x158b, driver xhci_hcd) and walks every PCI function rather than a hardcoded list, because a BIOS update can move them and a hardcoded list is how a check silently stops checking anything. Four verdicts, only one of which means "go ahead and plug": NOT THIS BOARD, would bind nothing, N asleep, all awake. Read-only by default; --apply/--revert perform the rule's single action (power/control=on|auto, root) so the mechanism is verifiable without a reboot, and revert is the documented way back. Measured on the board (kernel 7.4.0-rc1-1bit, stock Ubuntu dev boot i.e. WITHOUT the rule): 0000:c5:00.4 0x1587 xhci_hcd D3cold auto 0000:c7:00.0 0x1588 xhci_hcd D0 auto <- front USB-A / BT / JetKVM 0000:c7:00.3 0x1589 xhci_hcd D3cold auto 0000:c7:00.4 0x158b xhci_hcd D3cold auto verdict: 4 controller(s) match the rule; 3 of them are NOT in D0 so the premise still holds on the current kernel -- the fix is not addressing something a newer kernel already fixed -- and --apply moves all three D3cold -> D0 with --revert putting them back, which is the rule's mechanism verified on this kernel. tests/xhci_keepawake_check_test.py builds fake sysfs trees (--sysfs-root) and asserts all four verdicts, because CI is not an AXB35-02: a non-board machine must print NOT THIS BOARD and exit 0 rather than reporting a verdict, an unknown-id AXB35 must say the rule would bind nothing, three-asleep must fail --require-awake, all-awake must pass it. Registered as ctest xhci_keepawake_check. docs/axb35-usb-ports.md records the diagnosis, the rule, the measured table, the four verdicts and what is still owed (the plug, and the _DSM comparison against Windows if a port is still dead after it). Verified: ctest -R 'xhci_keepawake|spec_decode' in a CI-parity configure -> 2/2 Passed; the test file's 13 checks pass; bash -n; copyright --check rc 0 for these files (main is red on an unrelated duplicated header, fixed separately in #1565). refs #823, refs #1474's file (no entry touched). --- CMakeLists.txt | 5 ++ docs/axb35-usb-ports.md | 78 +++++++++++++++++ tests/xhci_keepawake_check_test.py | 128 +++++++++++++++++++++++++++ tools/xhci_keepawake_check.sh | 135 +++++++++++++++++++++++++++++ 4 files changed, 346 insertions(+) create mode 100644 docs/axb35-usb-ports.md create mode 100644 tests/xhci_keepawake_check_test.py create mode 100755 tools/xhci_keepawake_check.sh diff --git a/CMakeLists.txt b/CMakeLists.txt index d6a68bd00..35fb56854 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -750,6 +750,11 @@ if(Python3_Interpreter_FOUND) # one had a body (#1573, fixed by #1574). add_test(NAME declared_vs_defined COMMAND ${Python3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/declared_vs_defined_test.py) + # The AXB35-02 xHCI keepawake check (docs/axb35-usb-ports.md, engine#823): board-specific, so the test builds fake sysfs + # trees and asserts each verdict -- including "NOT THIS BOARD", which is what CI will get from the real /sys run and must + # never be reported as a pass for the board. + add_test(NAME xhci_keepawake_check COMMAND ${Python3_EXECUTABLE} + ${CMAKE_SOURCE_DIR}/tests/xhci_keepawake_check_test.py) # docs/npu-leaderboard.md is generated by tools/npu_leaderboard.py from bench/npu-leaderboard/*.json and says # "edit the records, not this file", but nothing regenerated it: a record could change and the page would keep # the old table, still reading as measured. This regenerates into a temp file and fails on any difference, and diff --git a/docs/axb35-usb-ports.md b/docs/axb35-usb-ports.md new file mode 100644 index 000000000..906f3c57a --- /dev/null +++ b/docs/axb35-usb-ports.md @@ -0,0 +1,78 @@ + +# AXB35-02 (Bosgame BeyondMax): the rear USB-A and Type-C ports + +**Status: fix merged, mechanism verified on the board, functional plug test still outstanding.** engine#823. + +On this board, stock boots leave three of the four xHCI functions in `D3cold`, so the rear USB-A ports and both Type-C ports never +enumerate; only the controller that carries the front USB-A (and Bluetooth, and the JetKVM) stays in `D0`. Windows drives every +port, the board's ACPI exposes no UCSI (`USBC000`/`PNP0CA0`), and `ec_su_axb35` has no USB controls — so a Windows-only port-power +path has always been the standing hypothesis, and the shipped answer is to keep the controllers awake rather than to find that +path. + +## What ships + +`os/v3/puppy/embed/etc/udev/rules.d/91-1bit-xhci-keepawake.rules`, gated so it can only ever bind on this machine: + +``` +ACTION=="add|bind", SUBSYSTEM=="pci", DRIVER=="xhci_hcd", ATTR{[dmi/id]board_name}=="AXB35-02", +ATTR{vendor}=="0x1022", ATTR{device}=="0x1587|0x1588|0x1589|0x158b", TEST=="power/control", ATTR{power/control}="on" +``` + +## How to tell whether it applies to the machine in front of you + +```sh +tools/xhci_keepawake_check.sh # read-only: DMI match, per-controller state, verdict +tools/xhci_keepawake_check.sh --require-awake # exit 1 unless every controller the rule matches is in D0 +``` + +Read-only by default. `--apply` / `--revert` perform the rule's own single action (`power/control = on|auto`) and need root; they +exist so the mechanism can be checked without a reboot, and `--revert` is the documented way back. `--sysfs-root` checks a tree +other than `/sys`, which is how `tests/xhci_keepawake_check_test.py` exercises every verdict on a machine that is not the board. + +The verdict is one of four, and only one of them is "go ahead and plug": + +| verdict | meaning | +|---|---| +| `NOT THIS BOARD` | the DMI gate does not match; nothing about #823 can be concluded from this machine | +| `would bind nothing` | the board matches but no xHCI function carries the rule's device ids (a BIOS that moved them) | +| `N asleep` | the rule is absent (a non-1bit boot) or not applied; **a plug test here would test nothing** | +| `all awake` | a plug into a rear USB-A or a Type-C port is a valid test of #823 | + +## Measured on the board (2026-11-08, kernel `7.4.0-rc1-1bit`) + +``` +== machine: board_name='AXB35-02' bios='1.09' product='BeyondMax Series' +function vendor device driver power control +0000:c5:00.4 0x1022 0x1587 xhci_hcd D3cold auto <- the rule matches this function +0000:c7:00.0 0x1022 0x1588 xhci_hcd D0 auto <- the rule matches this function +0000:c7:00.3 0x1022 0x1589 xhci_hcd D3cold auto <- the rule matches this function +0000:c7:00.4 0x1022 0x158b xhci_hcd D3cold auto <- the rule matches this function +== verdict: 4 controller(s) match the rule; 3 of them are NOT in D0 +``` + +That is a stock Ubuntu dev boot, i.e. *without* the rule: the premise of #823 still holds on the current kernel, so the fix is not +addressing something a newer kernel had already fixed. Forcing `power/control=on` on those three (exactly the rule's action) moves +them `D3cold → D0` and their root hubs' ports appear in `/sys/bus/usb/devices`; `--revert` puts them back. So the mechanism works +on this kernel; what has not happened is the plug. + +## What is still owed + +One device into a rear USB-A or a Type-C port **on a 1bit-OS boot**, checked with `--require-awake` first. If a port is then still +dead the next diagnostic is the one no one has run: compare `_DSM` on the xHCI/USB4 ACPI nodes against what Windows sends. Until +that plug, the honest row is *"fix merged and its mechanism verified on the board; functional confirmation pending"* — which is what +the release notes should say rather than leaving users to discover it. diff --git a/tests/xhci_keepawake_check_test.py b/tests/xhci_keepawake_check_test.py new file mode 100644 index 000000000..4a20b43ab --- /dev/null +++ b/tests/xhci_keepawake_check_test.py @@ -0,0 +1,128 @@ +#!/usr/bin/env python3 +# Copyright 2026 bong-water-water-bong +# SPDX-License-Identifier: Apache-2.0 +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""tools/xhci_keepawake_check.sh against fake sysfs trees, because CI is not an AXB35-02. + +engine#823's port finding is board-specific, so the check that guards it must be testable on a machine that is *not* the board. +The script therefore takes `--sysfs-root`, and this file builds trees that exercise each verdict it can reach: + + * a machine the rule does not cover -> "NOT THIS BOARD", exit 0 (and never a silent pass) + * the board with three controllers asleep -> report exit 0, `--require-awake` exit 1 + * the board with all four awake -> `--require-awake` exit 0 + * the board whose PCI ids the rule does not name -> "would bind nothing", exit 0 + +Each fake tree is only the files the script reads (dmi/id/board_name, bus/pci/devices/*/class|vendor|device|power_state| +power/control, and a driver symlink), so the test asserts the *verdict logic*, not the real hardware. +""" +import os +import shutil +import subprocess +import sys +import tempfile + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +TOOL = os.path.join(ROOT, "tools", "xhci_keepawake_check.sh") + +fails = 0 + + +def check(cond, what): + global fails + print(f"{'PASS' if cond else 'FAIL'} {what}") + if not cond: + fails += 1 + + +def make_tree(root, board, controllers): + """controllers: list of (slot, device_id, driver, power_state, control)""" + os.makedirs(os.path.join(root, "class/dmi/id"), exist_ok=True) + with open(os.path.join(root, "class/dmi/id/board_name"), "w") as fh: + fh.write(board + "\n") + with open(os.path.join(root, "class/dmi/id/bios_version"), "w") as fh: + fh.write("1.09\n") + with open(os.path.join(root, "class/dmi/id/product_name"), "w") as fh: + fh.write("BeyondMax Series\n") + devs = os.path.join(root, "bus/pci/devices") + os.makedirs(devs, exist_ok=True) + for slot, did, drv, ps, ctl in controllers: + d = os.path.join(devs, slot) + os.makedirs(os.path.join(d, "power"), exist_ok=True) + for name, val in (("class", "0x0c0330"), ("vendor", "0x1022"), ("device", did), ("power_state", ps)): + with open(os.path.join(d, name), "w") as fh: + fh.write(val + "\n") + with open(os.path.join(d, "power/control"), "w") as fh: + fh.write(ctl + "\n") + # a driver symlink is what the script reads to know it is bound to xhci_hcd + drvdir = os.path.join(root, "drivers", drv) + os.makedirs(drvdir, exist_ok=True) + os.symlink(drvdir, os.path.join(d, "driver")) + + +def run(tree, *args): + return subprocess.run([TOOL, "--sysfs-root", tree, *args], capture_output=True, text=True, timeout=120) + + +BOARD_CONTRL = [ + ("0000:c5:00.4", "0x1587", "xhci_hcd", "D3cold", "auto"), + ("0000:c7:00.0", "0x1588", "xhci_hcd", "D0", "auto"), + ("0000:c7:00.3", "0x1589", "xhci_hcd", "D3cold", "auto"), + ("0000:c7:00.4", "0x158b", "xhci_hcd", "D3cold", "auto"), +] + +tmp = tempfile.mkdtemp(prefix="xhci-check-test.") +try: + # 1. not the board: the check must say so and still exit 0 (a non-board machine cannot conclude anything) + t = os.path.join(tmp, "other") + make_tree(t, "B650M", BOARD_CONTRL) + r = run(t) + check(r.returncode == 0, f"a non-AXB35 board exits 0 (rc={r.returncode})") + check("NOT THIS BOARD" in r.stdout, "and says NOT THIS BOARD rather than reporting a verdict") + r2 = run(t, "--require-awake") + check(r2.returncode == 0, "… and --require-awake on a non-board machine is not a failure either") + + # 2. the board, three asleep (what a stock Ubuntu boot looks like): report passes, --require-awake must not + t = os.path.join(tmp, "asleep") + make_tree(t, "AXB35-02", BOARD_CONTRL) + r = run(t) + check(r.returncode == 0, f"the board with three asleep reports cleanly (rc={r.returncode})") + check("4 controller(s) match the rule; 3 of them are NOT in D0" in r.stdout, + f"it counts 4 matched / 3 asleep: {[l for l in r.stdout.splitlines() if 'verdict' in l][:1]}") + check("would test nothing" in r.stdout, "and says a plug test on this boot would test nothing") + r = run(t, "--require-awake") + check(r.returncode == 1, f"--require-awake fails when a controller is asleep (rc={r.returncode})") + + # 3. the board, all awake (what a 1bit-OS boot with the rule should look like) + t = os.path.join(tmp, "awake") + make_tree(t, "AXB35-02", [(s, d, drv, "D0", "on") for s, d, drv, _p, _c in BOARD_CONTRL]) + r = run(t, "--require-awake") + check(r.returncode == 0, f"--require-awake passes when all applicable controllers are in D0 (rc={r.returncode})") + check("all awake" in r.stdout, "and says a plug test on this boot would be valid") + + # 4. the board, but the PCI ids the rule names are not present (a BIOS that moved them) + t = os.path.join(tmp, "otherids") + make_tree(t, "AXB35-02", [("0000:aa:00.0", "0x0001", "xhci_hcd", "D0", "auto")]) + r = run(t) + check(r.returncode == 0, f"an AXB35 with unknown xHCI ids exits 0 (rc={r.returncode})") + check("would bind nothing" in r.stdout, "and reports that the rule would bind nothing instead of claiming success") +finally: + shutil.rmtree(tmp, ignore_errors=True) + +# 5. on THIS machine, whatever it is, the script must reach a verdict and exit 0 in report mode -- never crash, never hang. +r = subprocess.run([TOOL], capture_output=True, text=True, timeout=120) +check(r.returncode == 0, f"the real /sys run reaches a verdict (rc={r.returncode})") +check("verdict:" in r.stdout, "and prints one") + +print(f"\n{'all checks passed' if not fails else f'{fails} CHECK(S) FAILED'}") +sys.exit(1 if fails else 0) diff --git a/tools/xhci_keepawake_check.sh b/tools/xhci_keepawake_check.sh new file mode 100755 index 000000000..f5465fa0f --- /dev/null +++ b/tools/xhci_keepawake_check.sh @@ -0,0 +1,135 @@ +#!/usr/bin/env bash +# Copyright 2026 bong-water-water-bong +# SPDX-License-Identifier: Apache-2.0 +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# xhci_keepawake_check.sh -- does the shipped xHCI keepawake rule apply to THIS machine, and are the controllers awake? +# +# engine#823: on the Bosgame BeyondMax (AXB35-02) three of the four xHCI functions sit in D3cold on a stock boot, so the rear +# USB-A and both Type-C ports never enumerate; the gate is /etc/udev/rules.d/91-1bit-xhci-keepawake.rules, and the one thing the +# issue still owed was a *plug* test on a board boot. That test has a precondition nobody could check in one command: is the rule +# applicable to the machine under my hands, and are the controllers actually awake right now? This script answers both, read-only, +# and refuses to pretend on a machine the rule does not cover. +# +# xhci_keepawake_check.sh # report: DMI match, per-controller state, verdict; exit 0 +# xhci_keepawake_check.sh --require-awake # exit 1 if an applicable controller is NOT in D0 (plug test would be void) +# xhci_keepawake_check.sh --sysfs-root DIR # check a tree other than /sys (what the test uses) +# +# Read-only by default. `--apply` / `--revert` perform the rule's own single action (`power/control = on|auto`) on the +# controllers the rule matches, which needs root; they exist so the mechanism can be verified without a reboot, and `--revert` +# is the documented way back. +# +# Exit: 0 = checked (the verdict can be "not this board", "all awake", or "some asleep"), 1 = --require-awake not met, +# 2 = usage/IO problem. Never 0 by accident: a machine where the rule does not apply says so. +set -u + +SYSFS=${SYSFS:-/sys} +MODE=report +while [ $# -gt 0 ]; do + case "$1" in + --require-awake) MODE=require; shift;; + --apply) MODE=apply; shift;; + --revert) MODE=revert; shift;; + --sysfs-root) SYSFS=${2:?--sysfs-root needs a directory}; shift 2;; + -h|--help) sed -n '17,40p' "$0"; exit 0;; + *) echo "xhci_keepawake_check: unknown argument '$1'" >&2; exit 2;; + esac +done + +# The rule's own predicates, in one place. board_name is the DMI gate; vendor/device are the AMD Strix Halo xHCI functions the +# rule names (0x1587/0x1588/0x1589/0x158b); DRIVER must be xhci_hcd. +BOARD=${BOARD:-AXB35-02} +VENDOR=${VENDOR:-0x1022} +DEVICES=${DEVICES:-0x1587 0x1588 0x1589 0x158b} +DRIVER=${DRIVER:-xhci_hcd} + +dmi_board=$(cat "$SYSFS/class/dmi/id/board_name" 2>/dev/null || true) +dmi_bios=$(cat "$SYSFS/class/dmi/id/bios_version" 2>/dev/null || true) +dmi_product=$(cat "$SYSFS/class/dmi/id/product_name" 2>/dev/null || true) + +echo "== machine: board_name='${dmi_board:-?}' bios='${dmi_bios:-?}' product='${dmi_product:-?}'" +if [ "$dmi_board" != "$BOARD" ]; then + echo "== verdict: NOT THIS BOARD -- the keepawake rule (board_name == '$BOARD') does not apply here, so nothing about it" + echo " can be concluded from this machine. engine#823's port finding is AXB35-02-specific." + exit 0 +fi +echo "== board matches the rule's DMI gate ('$BOARD')" + +# Walk every PCI function, not a hardcoded list: a BIOS update can move them, and a hardcoded list is how a check silently stops +# checking anything. Only AMD xHCI functions whose device id the rule names are "applicable". +applicable=0 +asleep=0 +printf '%-14s %-8s %-10s %-8s %-9s %s\n' function vendor device driver power control +for fn in "$SYSFS"/bus/pci/devices/*; do + [ -e "$fn/class" ] || continue + cls=$(cat "$fn/class" 2>/dev/null || true) + case "$cls" in 0x0c0330*) ;; *) continue;; esac # xHCI host controller + v=$(cat "$fn/vendor" 2>/dev/null || true) + d=$(cat "$fn/device" 2>/dev/null || true) + drv=$(basename "$(readlink -f "$fn/driver" 2>/dev/null || echo none)" 2>/dev/null || echo none) + ps=$(cat "$fn/power_state" 2>/dev/null || echo '?') + ctl=$(cat "$fn/power/control" 2>/dev/null || echo '?') + hit="" + if [ "$v" = "$VENDOR" ]; then + for want in $DEVICES; do [ "$d" = "$want" ] && hit=yes; done + fi + printf '%-14s %-8s %-10s %-8s %-9s %s%s\n' "$(basename "$fn")" "$v" "$d" "$drv" "$ps" "$ctl" \ + "$([ -n "$hit" ] && echo " <- the rule matches this function")" + if [ -n "$hit" ] && [ "$drv" = "$DRIVER" ]; then + applicable=$((applicable + 1)) + [ "$ps" != "D0" ] && asleep=$((asleep + 1)) + if [ "$MODE" = apply ] || [ "$MODE" = revert ]; then + want=$([ "$MODE" = apply ] && echo on || echo auto) + if ! ( : > "$fn/power/control" ) 2>/dev/null; then + echo " $MODE needs write access to $fn/power/control (run as root)" >&2 + else + printf '%s' "$want" > "$fn/power/control" && echo " $MODE: power/control -> $want" + fi + fi + fi +done + +if [ "$applicable" -eq 0 ]; then + echo "== verdict: the rule's DMI gate matches but no AMD xHCI function with the rule's device ids was found --" + echo " the rule would bind nothing here (BIOS changed the ids?). Reported, not guessed." + exit 0 +fi + +if [ "$MODE" = apply ] || [ "$MODE" = revert ]; then + sleep 2 + echo "== after $MODE:" + for fn in "$SYSFS"/bus/pci/devices/*; do + [ -e "$fn/class" ] || continue + case "$(cat "$fn/class" 2>/dev/null)" in 0x0c0330*) ;; *) continue;; esac + d=$(cat "$fn/device" 2>/dev/null || true) + for want in $DEVICES; do + if [ "$d" = "$want" ]; then + printf ' %-14s power=%-8s control=%s\n' "$(basename "$fn")" \ + "$(cat "$fn/power_state" 2>/dev/null || echo '?')" "$(cat "$fn/power/control" 2>/dev/null || echo '?')" + fi + done + done +fi + +echo "== verdict: $applicable controller(s) match the rule; $asleep of them are NOT in D0" +if [ "$asleep" -eq 0 ]; then + echo "== all awake: a plug test on this boot would be a valid test of engine#823's ports." + exit 0 +fi +echo "== with $asleep asleep the rule is either absent (a non-1bit boot) or not yet applied; a plug into a rear USB-A" +echo "== or a Type-C port would fail for the reason the rule exists, so it would test nothing." +if [ "$MODE" = require ]; then + exit 1 +fi +exit 0 From de01dae1607667af6f53d3e21f65aab5aa95904b Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sun, 8 Nov 2026 20:16:11 -0400 Subject: [PATCH 2/2] tools: --require-awake fails CLOSED on the two "cannot confirm" verdicts (engine#823 review) The CHANGES review was right and it is the point of the tool: `--require-awake` is "the precondition in one command", so it has to fail closed. It exited **0** on two of the four verdicts: | verdict | before | after | |---|---|---| | `NOT THIS BOARD` | 0 | **1** | | `would bind nothing` | 0 | **1** | | `N asleep` | 1 | 1 | | `all awake` | 0 | 0 | A green on "not this board" reads as *the rule is in force here*, and a green on "would bind nothing" reads as *something is being kept awake* - on a boot where a plug into a rear or Type-C port would fail for the rule's reason and be read as evidence about the ports. Report mode is unchanged and still exits 0 on every verdict: its job is to describe a machine, and the doc's exit line now separates the two modes instead of listing one contract for both. The test was pinning the fail-open behaviour (`--require-awake on a non-board machine is not a failure either`), so it now pins the opposite, and a new case covers "would bind nothing" in both modes. Verified: `tests/xhci_keepawake_check_test.py` **all checks passed**, `bash -n` clean, `shellcheck -S warning` 0, and on this AXB35-02 the read-only run is unchanged. --- tests/xhci_keepawake_check_test.py | 14 +++++++++++++- tools/xhci_keepawake_check.sh | 22 ++++++++++++++++++---- 2 files changed, 31 insertions(+), 5 deletions(-) diff --git a/tests/xhci_keepawake_check_test.py b/tests/xhci_keepawake_check_test.py index 4a20b43ab..32ab869fc 100644 --- a/tests/xhci_keepawake_check_test.py +++ b/tests/xhci_keepawake_check_test.py @@ -90,7 +90,19 @@ def run(tree, *args): check(r.returncode == 0, f"a non-AXB35 board exits 0 (rc={r.returncode})") check("NOT THIS BOARD" in r.stdout, "and says NOT THIS BOARD rather than reporting a verdict") r2 = run(t, "--require-awake") - check(r2.returncode == 0, "… and --require-awake on a non-board machine is not a failure either") + check(r2.returncode == 1, "--require-awake FAILS on a non-board machine: the precondition cannot be confirmed here") + check("NOT a precondition met" in r2.stdout, "and says so rather than exiting quietly") + + # 1b. the board's DMI gate matches but NO function carries the rule's device ids: nothing would be kept awake, so a + # plug test would prove nothing - --require-awake must fail closed here too (the class this fix is about). + t = os.path.join(tmp, "bind-nothing") + make_tree(t, "AXB35-02", [("0000:c5:00.4", "0x9999", "xhci_hcd", "D0", "on")]) # a device id the rule does not name + r = run(t) + check(r.returncode == 0, f"report mode still exits 0 when the rule would bind nothing (rc={r.returncode})") + check("would bind nothing" in r.stdout, "and says the rule would bind nothing") + r2 = run(t, "--require-awake") + check(r2.returncode == 1, "--require-awake FAILS when the rule would bind nothing (nothing is being kept awake)") + check("NOT a precondition met" in r2.stdout, "and says so") # 2. the board, three asleep (what a stock Ubuntu boot looks like): report passes, --require-awake must not t = os.path.join(tmp, "asleep") diff --git a/tools/xhci_keepawake_check.sh b/tools/xhci_keepawake_check.sh index f5465fa0f..6aea65fe9 100755 --- a/tools/xhci_keepawake_check.sh +++ b/tools/xhci_keepawake_check.sh @@ -23,19 +23,33 @@ # and refuses to pretend on a machine the rule does not cover. # # xhci_keepawake_check.sh # report: DMI match, per-controller state, verdict; exit 0 -# xhci_keepawake_check.sh --require-awake # exit 1 if an applicable controller is NOT in D0 (plug test would be void) +# xhci_keepawake_check.sh --require-awake # exit 0 ONLY when every applicable controller is in D0; exit 1 for "some +# asleep", "not this board" and "the rule would bind nothing" - a precondition +# step must fail closed, because a green there reads as "the rule is in force" void) # xhci_keepawake_check.sh --sysfs-root DIR # check a tree other than /sys (what the test uses) # # Read-only by default. `--apply` / `--revert` perform the rule's own single action (`power/control = on|auto`) on the # controllers the rule matches, which needs root; they exist so the mechanism can be verified without a reboot, and `--revert` # is the documented way back. # -# Exit: 0 = checked (the verdict can be "not this board", "all awake", or "some asleep"), 1 = --require-awake not met, +# Exit (report mode): 0 = checked (the verdict can be "not this board", "all awake", or "some asleep"), 1 = --require-awake not met, # 2 = usage/IO problem. Never 0 by accident: a machine where the rule does not apply says so. set -u SYSFS=${SYSFS:-/sys} MODE=report + +# A verdict that cannot CONFIRM the precondition is a FAILURE under --require-awake, and only there: report mode exists to +# describe a machine ("not this board", "the rule would bind nothing") and must stay exit 0. engine#823's precondition step is +# `--require-awake`, so a green there would let someone plug a port into a boot where the rule is not in force and read the +# result as evidence about the rule. +require_verdict() { # + if [ "$MODE" = require ]; then + echo "== --require-awake: $1, so this is NOT a precondition met (exit 1)" + exit 1 + fi + exit 0 +} while [ $# -gt 0 ]; do case "$1" in --require-awake) MODE=require; shift;; @@ -62,7 +76,7 @@ echo "== machine: board_name='${dmi_board:-?}' bios='${dmi_bios:-?}' product=' if [ "$dmi_board" != "$BOARD" ]; then echo "== verdict: NOT THIS BOARD -- the keepawake rule (board_name == '$BOARD') does not apply here, so nothing about it" echo " can be concluded from this machine. engine#823's port finding is AXB35-02-specific." - exit 0 + require_verdict "the board does not match the rule's DMI gate" fi echo "== board matches the rule's DMI gate ('$BOARD')" @@ -103,7 +117,7 @@ done if [ "$applicable" -eq 0 ]; then echo "== verdict: the rule's DMI gate matches but no AMD xHCI function with the rule's device ids was found --" echo " the rule would bind nothing here (BIOS changed the ids?). Reported, not guessed." - exit 0 + require_verdict "the rule would bind nothing on this machine" fi if [ "$MODE" = apply ] || [ "$MODE" = revert ]; then