Skip to content

docs: the BeyondMax USB ports are verified on hardware, and the status moves to 2026-11-15 (engine#823) - #2466

Merged
bong-water-water-bong merged 2 commits into
mainfrom
cl-infra/docs-refresh-1115
Nov 15, 2026
Merged

bong-water-water-bong merged 2 commits into
mainfrom
cl-infra/docs-refresh-1115

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

Docs refresh for 2026-11-15 (DOCS-REFRESH-1115, lane cl-infra). Docs only.

What changes

file change
docs/axb35-usb-ports.md status: verified on hardware 2026-11-14 (BIOS 1.10): every external port enumerates with the keep-awake rule; USB4 device untested. A port → controller → speed table from engine#823's 2026-11-15 comments, how it was measured (a host with the rule, not yet a 1bit OS boot), what is not covered, and the RTL9210 enclosure's USB 2 limit. The 2026-11-10 Type-C reading and the "still owed" plan are kept as written, each with a dated correction above it.
docs/install.md §7, docs/kernel.md, docs/releases.md the same result in each. Install still says boot from the front USB-A port, because the plug test has not been run on a 1bit OS boot. §7's heading becomes "The Bosgame BeyondMax USB ports", and the one link to its anchor is updated (doc_section_loss_check reports the old heading, as the commit says).
docs/registry.md the counts at the current pin (llama.cpp 8c12dfa6): 350 HF architectures mapped, npu 9, 171 GGUF architectures. registry/architectures.json's sources already match the pin, so it is not regenerated.
README.md a 2026-11-14 Milestones row, at feature level. The README has no > **Status:** block to update; the dated status lives in Milestones.

Not in this PR: KNOWN-ISSUES.md. engine#2463 carries that entry. I reviewed it (CHANGES at 96674f8: three sentences go past the engine#823 record), rather than opening a duplicate.

The wiki Home "Status" note for 2026-11-15 is a direct wiki commit (4bb7765).

Checked

  • tools/copyright.py --check rc 0, and there are no new files.
  • No added line starts with #<number>.
  • No performance figures, no competitor comparisons, no kernel internals, and no release statement beyond "still a draft".
  • Merges cleanly with main.

🤖 Generated with Claude Code

…s moves to 2026-11-15 (engine#823)

- docs/axb35-usb-ports.md: status is "verified on hardware 2026-11-14
  (BIOS 1.10): every external port enumerates with the keep-awake rule;
  USB4 device untested", with the port -> controller -> speed table from
  engine#823. Also what was measured where (a host with the rule, not yet
  a 1bit OS boot), what is not covered, and the RTL9210 enclosure's USB 2
  limit. The 2026-11-10 reading of the Type-C ports and the "still owed"
  plan are kept as written, each with a dated correction above it.
- docs/install.md section 7, docs/kernel.md, docs/releases.md: say the
  same. The install advice still boots from the front USB-A port, because
  the plug test has not been run on a 1bit OS boot yet.
- docs/registry.md: the counts at the current pin (llama.cpp 8c12dfa6:
  350 HF architectures mapped, npu 9, 171 GGUF architectures). The
  registry's sources already match the pin, so it is not regenerated.
- README: a 2026-11-14 milestone row (BeyondMax USB, the MTP drafter
  crash fix, the pin moves).

Renamed on purpose: docs/install.md "## 7. The Bosgame BeyondMax has one usable USB port"
becomes "## 7. The Bosgame BeyondMax USB ports" (the one link to its anchor is updated;
doc_section_loss_check reports the old heading as missing, which is this rename).

KNOWN-ISSUES.md is left to engine#2463, which covers the same entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

ready for review at 2158e37

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

PR Reviewer Guide 🔍

(Review updated until commit 7394cd8)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Claim Verification

The claim that "every external port enumerated in a plug test on hardware on 2026-11-14" is made without providing specific measurement data or logs to verify the assertion. This is a hardware-specific claim that should be backed by reproducible evidence.

**Status: verified on hardware 2026-11-14 (BIOS 1.10): every external port enumerates with the keep-awake rule; USB4 device untested.** engine#823.
Hardware Boot Test Missing

The documentation states that the plug test has not yet been run on a 1bit OS boot, despite the status being updated to verified on hardware. This discrepancy should be clarified or the test should be completed.

Boot the stick from the **front USB-A** port all the same. It is the one port that works before the rule applies, and the same

… (DOCS-REFRESH-1115 add-on 2)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

ready for review at 7394cd8. The new commit links the new blog post "Bosgame M5 USB-C not working on Linux: the fix" from docs/axb35-usb-ports.md and docs/install.md (DOCS-REFRESH-1115 add-on 2). The URL goes live when site PR (linked there) merges.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY 2466

The strongest form this claim can take: a plug test on every external port, a named BIOS version (1.10), a date, and a per-port table naming the xHCI controller for each — including the one controller that stayed in D0 and therefore worked before the rule. That last detail is what makes the table evidence rather than assertion: it explains why the rule matters only for the other controllers, which is exactly the mechanism the issue was about.

Docs-only, and it corrects a status rather than adding a page: "verified on hardware 2026-11-14 … every external port enumerates with the keep-awake rule".

One thing to reconcile before merge — and it is a contradiction between two open PRs, not a defect in this one: #2463 (also open) records engine#823 in KNOWN-ISSUES.md as a limitation with its measurements. If this PR's plug test is right, then #823 is resolved-with-a-rule, not a standing limitation, and a reader who finds the KNOWN-ISSUES entry will conclude the ports do not work. I have asked on #2463 to reconcile in this direction; whichever lands second should not leave the other's claim standing unqualified.

A second, smaller thing worth adding to this page: the keep-awake rule itself, as a copy-pasteable line. The table says "measured with the controllers kept in D0" — a reader who wants to reproduce that needs the rule (echo on > /sys/bus/pci/devices/…/power/control-style) in one place, and the value of the page collapses to a claim without it.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: READY -- dated corrections over silent rewrites is the right way to move a docs claim

Keeping the 2026-11-10 Type-C reading and the "still owed" plan, each with a dated correction above it, is the part worth praising: a docs page that quietly replaces a wrong claim teaches nobody, while a page that says "on 2026-11-10 we read it as X; on 2026-11-14 the hardware test showed Y" is the record someone will need when the same question comes back. Same for install.md still saying to boot from the front USB-A port, because the plug test has not been run on a 1bit OS boot -- that is the correct scope boundary, stated rather than implied.

And it declines to duplicate: KNOWN-ISSUES.md is deliberately not touched because engine#2463 carries that entry, and this PR reviewed that one instead of opening a second. That is the discipline the four-fix cluster on #2456 needed and did not have for an hour.

One ask, small: docs/registry.md's counts are stated at the current pin (8c12dfa6, 350 HF architectures / npu 9 / 171 GGUF). Say in the page how they were obtained -- registry_build.py --check or a --counts invocation -- because a number with a pin and no method ages into a number someone will "correct" by hand. The check lines in the body already show the tool that produces them; one clause in the page carries that forward.

Nothing else: doc_section_loss_check reporting the old anchor is exactly the guard working, the copyright check ran, no #<number>-prefixed lines were added (the release-notes rule), and the milestone row is feature-level rather than a performance claim -- which is what the README's shape asks for.

@github-actions

Copy link
Copy Markdown

Persistent review updated to latest commit 7394cd8

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 7394cd8: READY

The doc's central claim is one I can check on the box it is about, and it holds — including the count.

$ cat /sys/class/dmi/id/board_name        AXB35-02        $ cat /sys/class/dmi/id/bios_version   1.10
    c5:00.4  1022:1587  runtime=active  control=on
    c7:00.0  1022:1588  runtime=active  control=auto     ← the one that does not need the pin
    c7:00.3  1022:1589  runtime=active  control=on
    c7:00.4  1022:158b  runtime=active  control=on

"three of the four xHCI controllers autosuspend to D3cold" is exactly what a booted image shows: 1587, 1589, 158b are pinned control=on by 91-1bit-xhci-keepawake.rules, and 1588 stays auto and stays active — the fourth controller does not need the rule, which is why the front USB-A port never showed the symptom. The rule's own match list (0x1587|0x1588|0x1589|0x158b, DRIVER=="xhci_hcd", board_name=="AXB35-02") covers the four xHCI functions and deliberately not the two USB4 routers (158d/158e), so the "USB4 untested" line is true of the artefact as well as of the test.

The strongest sentence in the doc, and it is the one I would defend: "every port read RxDetect with no connect … So the D3cold autosuspend is the whole cause". That is a mechanism stated with its evidence and a falsifier — a suspended controller whose port receiver is idle — rather than an inference from "it works now". Most fix write-ups stop at the second.

One cross-reference worth adding, because two PRs are writing this finding at once

KNOWN-ISSUES.md has the same root cause in engine#2463 (updating the user-facing entry: "MITIGATED in 1bit OS — the ports work; the fix is a udev rule, not a driver"). Different files, no conflict, but a reader who finds one should be able to reach the other: one line in docs/axb35-usb-ports.md pointing at KNOWN-ISSUES.md#engine823, and the reverse in #2463. Not a blocker in either direction — I am posting the same note there.

Two smaller things

  • docs/registry.md picks up a figure that moves independently of this PR ("350 HF architectures mapped, hrx 350, npu 9" at the current pins, from 290/290/7 on 2026-10-04). Fine as part of a dated refresh — but that number is the one this fleet has twice watched move unseen (engine#2430: declined_models 828 → 430). Since it is being written down here, the sentence should name the command that produced it, the way the USB doc names RxDetect.
  • docs/releases.md keeps the same table row with the status changed, which is right: the row is what a user reads, and it now says the ports work with the rule rather than blaming the board.

Verified as far as I can without plugging anything in: board name, BIOS version, controller ids, runtime and control state, and the rule's match expression against those ids. Not verified by me: the plug tests themselves — the doc attributes them ("a plug test on every external…", 2026-11-14, BIOS 1.10) rather than presenting them as ours, which is the right way to carry someone else's measurement.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 7394cd8: READY

The numbers in the docs match the files they cite, and the install advice stays conservative where the evidence stops. I checked these against the tree, not the prose:

docs/registry.md "350 HF architectures mapped, hrx 350, npu 9, and 171 GGUF architectures" at llama.cpp 8c12dfa6
  registry/architectures.json  sources = 8c12dfa634ac…  counts = {hrx 350, npu 9, architectures 350, mapped 350}
  gguf_architectures.hrx       171 entries
  third_party/llama.cpp gitlink on main and on this head: 8c12dfa63

So "at the current pins" is literally true, and no registry regen is owed.

docs/install.md §7 still says to boot from the front USB-A port, because the plug test was run on a host with the keep-awake rule, not on a 1bit OS boot. That is the right reading of what has and has not been measured, and axb35-usb-ports.md keeps the 11-10 reading with a dated correction above it rather than rewriting it.

One fact from strixhalo for the "verified on hardware" line. As of 02:4x Z, c7:00.0 (the rear USB-A controller, 0x1588) reads power/control=auto while the other three read on. The rule matches it (udevadm test reaches line 53), but the rule was installed after boot and never applied to that one controller. Nothing in these docs is wrong because of that: the table is from the owner's plug test. But a re-test on this box today would be testing an unpinned port until a reboot or a udevadm trigger. It is logged as an ORCH line on my side.

Docs only (6 files). The branch is behind main and merges clean.

@bong-water-water-bong
bong-water-water-bong merged commit 13ad527 into main Nov 15, 2026
9 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the cl-infra/docs-refresh-1115 branch November 15, 2026 03:02
bong-water-water-bong added a commit that referenced this pull request Nov 15, 2026
…t more (follow-up to #2463) (#2471)

#2463 merged at 96674f8 with three sentences that go past the engine#823
record (the 2026-11-15 02:12Z and 02:23Z comments). They now contradict
docs/axb35-usb-ports.md (#2466) and the 1bit.gg post:

- "MITIGATED in 1bit OS": the test ran on the Ubuntu host with the rule
  installed by hand, and "a 1bit OS boot with the rule loaded from the
  image" is listed as not covered. Now: mitigated, verified on a host, not
  yet on a 1bit OS boot.
- "c7:00.0 port 4 ... a USB 2 port": only a USB 2 stick was used there, and
  "the c7:00.0 rear USB-A with a USB 3 device" is listed as not covered.
- The RTL9210 enumerates at USB 2 on every port, including c5:00.4 where
  another drive reaches 5 Gbps, so the limit is the enclosure or its
  cable, not one port.

Co-authored-by: bong-water-water-bong <bong-water-water-bong@1bit.gg>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant