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..32ab869fc --- /dev/null +++ b/tests/xhci_keepawake_check_test.py @@ -0,0 +1,140 @@ +#!/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 == 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") + 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..6aea65fe9 --- /dev/null +++ b/tools/xhci_keepawake_check.sh @@ -0,0 +1,149 @@ +#!/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 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 (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;; + --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." + require_verdict "the board does not match the rule's DMI gate" +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." + require_verdict "the rule would bind nothing on this machine" +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