[bong-water-water-bong]

Root cause

docs/hrx.md (the 2026-10-31 SVM A/B table and "The HSA runtime" bullet), and the comment in app/hrx_runtime.h,
all say the release-shipped libhsa-runtime64.so.1 "does not register HRX0 for a dev build" and that a distro
copy is simply "untested". The A/B's release arm is REL=$HOME/wt/engine-c18/libhsa-release/libhsa-runtime64.so.1
(~/lb/tattn-hsa-ab.sh:20) — a directory that holds that one file and nothing else — while the image installs the
full 10-file flat kit (the runtime plus its eight librocm_sysdeps_* siblings and librocprofiler-register.so.0).
ROCr 1.21.0's build has those as NEEDED, so the lone file cannot be dlopened at all:

$ python3 -c 'import ctypes,sys; ctypes.CDLL(sys.argv[1])' ~/wt/engine-c18/libhsa-release/libhsa-runtime64.so.1
OSError: librocm_sysdeps_elf.so.1: cannot open shared object file: No such file or directory

The "no HRX0" row measured the directory, not the runtime.

Measured after (this box, one gpu-hold ticket, hrx-system@82804197b, no-SVM trio, HRX_CTS_DEVICE=gpu:0)

Probe = libhrx's own hrx_cts_device (7 Catch2 cases, all device-bound). Each arm's runtime is confirmed from its
own openat trace:

arm	runtime the loader ended up with	device	cases
no path (bare soname from ldconfig)	distro ROCr 1.18.0 5b113248…	none (hsa_amd_queue_create not found)	rc 1
IREE_HAL_AMDGPU_LIBHSA_PATH = the pin	clang-24 ROCr 1.22.0 21a66824…	HRX0	7/7 pass
LD_LIBRARY_PATH = the image's 10-file kit	clang-23 ROCr 1.21.0 f6ef689d…	HRX0	7/7 pass
one file, same bytes, no siblings	fell through to the distro	none, error names the distro	rc 1

Symbol check (util/libhsa_tables.h → 121 entry points the driver resolves by name): the pin and the image copy export
all 121; 1.22 adds five the driver never resolves and 1.21 adds none over it, so the two builds are interchangeable
by symbol set. 1.18.0 misses exactly hsa_amd_queue_create.

What the patch does

• docs/hrx.md: keeps the dated A/B table, and adds the two corrections under it (the arm's directory, and the closure
  measurement), plus the diagnostic trap: a runtime path that cannot be dlopened does not fail loudly — the loader
  appends that error, keeps searching, falls through to the bare soname, and the error printed names the distro copy
  (runtime/…/amdgpu/util/libhsa.c:252-278, :349-400, :410-424). "Missing symbol in the system library" usually
  means the runtime you named could not be loaded.
• docs/hrx.md "The runtime is named at init" bullet: the reason to name it is a missing entry point in an old ROCr and
  a missing closure, not "the release copy can't register a device".
• app/hrx_runtime.h: the same sentence in the comment over the HRX: HSA runtime <path> sha256 <hex> line (comment
  only, no behaviour change).
• docs/releases.md: the image's runtime row beside the pin, with build ids (1.22.0-local-build-430d3d8f clang 24 vs
  1.21.0-local-build-d134b782 clang 23), so a release check's identity digest (f6ef689d…, unchanged on the c17,
  c19 and c20 board boots) matches a row instead of nothing.

No closes #: this is the doc half of engine#713's criterion 5 (a docs fix, nothing to close). tools/copyright.py --check clean; the only code touched is a comment, so no behaviour changes (CI's build job still runs it).

[bong-water-water-bong]

#964 ready for review at cd615e6 — docs-only (3 files, +43/-12): docs/hrx.md (the 2026-10-31 A/B rows are kept; the two corrections are added under them), app/hrx_runtime.h (comment only), docs/releases.md (the image's runtime row beside the pin).

Self-checks: tools/copyright.py --check rc 0; no behaviour change (the only code file touched is a comment); the device table in the body is one gpu-hold ticket (~/wt/hipab/lhsasel/) with each arm's runtime confirmed from its own openat trace. CI build will still exercise it.

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit e102be2)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 713 - Partially compliant Compliant requirements: The build will bootstrap its own toolchain under the tree The toolchain is pinned and will be bumped by workflow The pinned toolchain version is written into the release table The build no longer requires /opt/rocm-therock to be present The build defaults to using the bootstrapped toolchain Non-compliant requirements: The PR does not include the actual build system changes to implement the bootstrapping Requires further human verification: The actual build process and toolchain bootstrapping logic needs to be verified in a fresh environment

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Runtime Loading Clarification The documentation updates clarify that the runtime loading mechanism requires the full set of librocm_sysdeps_* libraries and librocprofiler-register.so.0 to be present in the same directory for successful dlopen. This is a critical detail for ensuring that the runtime can be properly loaded and used, especially in environments where only a single file copy might be present. * **The arm did not use the set the image installs.** That A/B arm pointed `IREE_HAL_AMDGPU_LIBHSA_PATH` at a **single-file** extract of the same bytes, and ROCr 1.21.0's build needs its eight `librocm_sysdeps_*` siblings plus `librocprofiler-register.so.0` in the same directory. Without them `dlopen` fails (`librocm_sysdeps_elf.so.1: cannot open shared object file`) and no device can appear, whatever the SVM mode. Runtime Digest and Closure Verification The documentation now emphasizes that both the SHA256 digest and the closure (i.e., the presence of all required libraries in the same directory) are necessary for verifying a usable runtime. This is important for ensuring that the runtime can be loaded correctly, as a digest alone does not guarantee that all dependencies are present. * **Every binary in the set must be there.** `dlopen` of a single-file copy of those same bytes in a directory without its eight `librocm_sysdeps_*.so*` siblings fails (`librocm_sysdeps_elf.so.1: cannot open shared object file`) — the same digest, in a directory that cannot load it. The image installs the full 10-file flat set, and that one loads. Digest **plus closure** identifies a usable runtime, so check both (`sha256sum`, `ldd`). * **A distro `libhsa-runtime64` cannot work.** ROCr `1.18.0` (`5b11324814140eb5…`, 3,902,416 B) lacks `hsa_amd_queue_create`, one of the 121, so an HRX process that resolves the bare soname from the system path gets no device (engine#713's acceptance table). A payload dir may also carry the pin **relocated** (`f5462dc3…`: the same 5,141,585 B with 185 bytes changed, `DT_RPATH`→`DT_RUNPATH $ORIGIN`).

[bong-water-water-bong]

#964 ready for review at cd615e6 — all checks green: build pass (5m47s), 5× Analyze pass, CodeQL pass, pr_agent pass (37s), hw_gate skipping by design; mergeStateStatus: CLEAN.

The earlier pr_agent red was a concurrency self-cancel (cancelled after 13s, no steps); the re-run reports nothing to change. Docs-only (docs/hrx.md, docs/releases.md, plus a comment in app/hrx_runtime.h); tools/copyright.py --check rc 0; no closes # (doc half of #713 criterion 5).

[bong-water-water-bong]

VERDICT: READY at cd615e663. Docs only, and the numbers in it check out against the files on this box.

Both digests and both sizes are exactly right:

4,957,049 B  f6ef689d163b42de…  …/rootfs-skeleton/opt/rocm-therock/lib/libhsa-runtime64.so.1   (the image's copy)
5,141,585 B  21a6682452e159cf…  …/_rocm_sdk_core/lib/libhsa-runtime64.so.1                       (the dev pin)

and the same image copy appears in ~/wt/os3i/sfs-c16/opt/rocm-therock/lib/, i.e. it really is what a built SFS carries.

The "1.22 adds five" claim holds arithmetically against the exported symbol sets: the image's 1.21.0 exports 279 hsa* symbols and the pin's 1.22.0 exports 284 — five more, exactly as the text says. (The "121" is the driver's resolved set, not total exports, so the two numbers are not in conflict.)

The two corrections are the kind this doc needed: "the arm pointed at a single-file extract" is a defect of the measurement, not of the runtime, and saying so stops the next person from concluding from that table that the image's ROCr is broken. Same for the fall-through caveat — a runtime that cannot be dlopened does not fail loudly, and the error then names the distro copy rather than the path you passed, which is the trap I hit myself in an earlier session on this box.

One nit: app/hrx_runtime.h's comment now says "several libhsa-runtime64.so.1 copies exist on a box", and docs/hrx.md around line 955 still says "Three libhsa-runtime64.so.1 exist on a box" in the paragraph just below the one this PR rewrites. Three is still true for this box, so it is not wrong — just note that the header no longer says a number and the doc still does.

[github-actions]

Persistent review updated to latest commit e4a1037

[github-actions]

Persistent review updated to latest commit 40520fe

[github-actions]

Persistent review updated to latest commit e5f20d9

[github-actions]

Persistent review updated to latest commit 43256d5

[github-actions]

Persistent review updated to latest commit 8d81e99

[github-actions]

Persistent review updated to latest commit 824bbca

[github-actions]

Persistent review updated to latest commit 402f615

[github-actions]

Persistent review updated to latest commit c7c8acc

[github-actions]

Persistent review updated to latest commit e102be2