rea/docs/gpu-code-objects.md

Static CUDA and HIP code objects

inspect_gpu_code_objects answers which GPU targets and kernel declarations a local artifact carries. It reads ELF/PE sections, standalone CUDA fatbins, CUBIN/PTX and Clang HIP bundles, including CCOB v1/v2/v3. It neither executes the artifact nor invokes CUDA/ROCm tools. GPU execution, SASS disassembly and host launch correlation remain outside coverage.

Start with a target inventory:

{ "path": "/artifacts/library.so", "view": { "collection": "targets" } }

Target rows aggregate inventoried payloads and distinguish an unrequested kernel analysis from a complete or partial one. objects pages expose exact object IDs, compression declarations and encoded/header locations. Fields, exact filters, batch IDs and stable pagination select the facts delivered to the caller. IDs are positional within the recorded artifact SHA-256. Selecting object_ids in a new inspection requires expected_sha256 from that inventory; a changed file is rejected before parsing selected payloads.

target is the inventory declaration used for selection; payload_target is the independently observed inner declaration when available. Object pages keep both values, their kind, target_consistency and inspection coverage even with selected fields. Conflicting base architectures retain both values, mark object/report/target coverage partial and annotate the affected kernels. CUBIN flags establish a base architecture: base-only explicitly leaves feature-profile agreement unknown, including a and f variants. A standalone declaration is single-source, and unexamined payloads remain unexamined. An exact AMDGPU target is normalized at its note owner for comparison with a Clang bundle declaration; raw values remain intact. Unresolved feature comparisons stay unknown.

A HIP target ID identifies a toolchain target, not its payload representation. Recognized raw or wrapped LLVM bitcode stays unsupported for kernel metadata inspection, with the bundle ID, range and selected payload digest retained. Bitcode validity and inner targets remain unexamined; malformed recognized ELF still reports malformed. Standalone bitcode is outside GPU container coverage.

HIP bundle and metadata note recognition accept both the legacy amdgcn triple and LLVM's amdgpu subarchitecture triples, including declared generic processors such as gfx11-generic and gfx9-4-generic. Notes with the empty or explicit unknown environment use the same processor and feature comparison while retaining their raw triple spelling. CUDA's legacy fatbinary compression flag is retained as an unsupported codec with its encoded and decoded extents; compressed bytes are not treated as PTX text. CCOB is recognized by the exact four signature bytes CCOB; high-bit-corrupted bytes are not decoded as ASCII and accepted as a bundle. CCOB v1 has no stored total size: the complet