[danielbolsson]

AIRUNTIME-2703, AIRUNTIME-2704 · sixth of nine in the stack rooted at #10221 · base is #10637

What this changes

An API whose argument is a pointer to a struct used to record only the address. Replay had nothing to reconstruct from, so 44 such APIs were either hand-written shims or no-op stubs, and the ones left as stubs lost their payload silently.

DEREF_FIELDS declares, per API and parameter, what the pointer points at — a fixed struct, count elements of a fixed size, a NUL-terminated string, or an array of device addresses — and the generator emits both the capture-side copy and the playback-side reconstruct-and-pass. The recorded capture-time address is kept for comparison only; the value handed to the runtime is always a local of the pointee's own type. Output handle parameters get the same treatment through _OUT_BUFFER_PARAMS, which is what stops an export writing into a stale capture-time address.

_OUT_BUFFER_PARAMS also has to cover the callee-filled buffer that is not a handle. hipDeviceGetLuid takes a char*, which the pointee rule would otherwise size as one character for the runtime to memcpy eight bytes into. It gets an explicit 8. Only the Windows path writes, so the overflow is unreachable on Linux and no Linux-only test run can find it — worth an eye on review rather than on CI.

On top of that mechanism, the handler families that needed more than a declaration: graphs rebuilt node by node against graph_node_map, the symbol registry resolving __device__ globals through hipModuleGetGlobal, ipc_handle_map, the driver ctx_map and link_state_map, and the memcpy2D/3D and batch-memop families. Archive format goes to v6.

A call that failed at capture and fails the same way at replay is fidelity, not a replay error, and the dispatcher now reports it as such instead of aborting.

Reviewing this

Hand-written	gen_hrr_api_args.py, hip_capture.cpp, hip_playback.cpp/.h, hip_code_object.cpp/.hpp, DESIGN.md
Generated	hrr_api_args.h, hip_capture_generated.cpp, hip_playback_generated.cpp — run gen_hrr_api_args.py, confirm an empty diff
Expectations delta	hrr_api_matrix_expectations.h — the rows this PR reclassifies, relative to #10637's baseline

One deliberate stub

hipMemPoolImportFromShareableHandle becomes a no-op here. Its export side now genuinely mints an fd, so the recorded handle names something else in the replaying process and faults inside the pool import. The PR above replaces the stub with a refusal that names the API and the reason.

Validation

Full HRR unit suite on gfx950, GPU 7: 86/86, both the GPU-free pass (26/26) and the GPU pass. All four runnable api-matrix tiers pass.

Made with Cursor

[LeoZhao-BJ]

I think we should brainstorm a more generic approach for handling HRR payload capture/replay, instead of continuing to add or customize shims API by API.

Two directions seem worth exploring:

1. Keep a declarative per-API spec, but centralize the generated capture/replay logic

   Instead of hand-writing or expanding bespoke shim logic for each affected API, we could describe pointer payloads in a compact metadata table, then let common
   capture/replay helpers handle the actual deep-copy and reconstruction.

   For example, the generator could emit specs such as:

   hipGraphAddMemcpyNode:
   pDependencies: array<hipGraphNode_t>, count=numDependencies
   pCopyParams: struct

   hipMemcpyParam2DAsync:
   pCopy: struct<hip_Memcpy2D>

   The generated shim would then call shared helpers like:

   capture_deep_fields(api_id, args, field_specs)
   replay_rebuild_fields(ctx, args, field_specs)

   This would keep the per-API knowledge declarative, while moving the risky behavior — null handling, truncation policy, host/device pointer translation,
   lifetime, and refusal logic — into one place.

2. Move deep-copied payloads into a generic TLV-style event tail

   Instead of growing each hrr_args_* struct with fields like foo_bytes, foo_present, and foo_n, we could encode deep-copied payloads as generic typed field
   records appended after the fixed event payload.

   Each captured field could carry:

   field_id
   field_kind
   element_size
   original_count
   recorded_count
   byte_size
   bytes[]

   This would let replay distinguish:

   • fully captured payloads;
   • truncated payloads;
   • absent/null payloads;
   • host buffers;
   • device pointer arrays;
   • unsupported/unreplayable pointer kinds.

   It would also make policy enforcement generic. For example, if original_count > recorded_count, replay should fail loudly or mark the graph/event incomplete,
   rather than silently replaying only the captured prefix and treating the partial operation as faithful.

The broader goal would be to classify pointer parameters by semantic kind, not just by C type:

StructByPointer
ArrayByCount
String
DevicePointer
DevicePointerArray
HostInputBuffer
HostOutputBuffer
OutputHandle
CallbackFunction
OSHandle
JitOptionValueArray
Unreplayable

Then each semantic kind has a common capture/replay policy. Most APIs could be handled by generated metadata and shared helpers, while only genuinely semantic families — kernel launches, graph lifecycle, IPC handle remapping, JIT option interpretation, symbol registration — would need hand-written replay logic.

This should reduce the need to add bespoke shims for every API while also making the behavior safer and more consistent across the replay stack.

[danielbolsson]

I think we should brainstorm a more generic approach for handling HRR payload capture/replay, instead of continuing to add or customize shims API by API.

Two directions seem worth exploring:

1. Keep a declarative per-API spec, but centralize the generated capture/replay logic
   Instead of hand-writing or expanding bespoke shim logic for each affected API, we could describe pointer payloads in a compact metadata table, then let common
   capture/replay helpers handle the actual deep-copy and reconstruction.
   For example, the generator could emit specs such as:
   hipGraphAddMemcpyNode:
   pDependencies: array<hipGraphNode_t>, count=numDependencies
   pCopyParams: struct
   hipMemcpyParam2DAsync:
   pCopy: struct<hip_Memcpy2D>
   The generated shim would then call shared helpers like:
   capture_deep_fields(api_id, args, field_specs)
   replay_rebuild_fields(ctx, args, field_specs)
   This would keep the per-API knowledge declarative, while moving the risky behavior — null handling, truncation policy, host/device pointer translation,
   lifetime, and refusal logic — into one place.

This is largely built already. gen_hrr_api_args.py has a Deref class that is exactly the declarative per-API spec as you propose. Your proposal is basically a rename of something already there.

Your strongest point here is the truncation one, and it is a real gap today. Let's adress that!

2. Move deep-copied payloads into a generic TLV-style event tail
   Instead of growing each hrr_args_* struct with fields like foo_bytes, foo_present, and foo_n, we could encode deep-copied payloads as generic typed field
   records appended after the fixed event payload.

This is an interesting architectural change proposal. I suggest that we first land the current PR stack and discuss future design directions from there.

[LeoZhao-BJ]

let's land this PR first and may have epic to optimize architecture later

[systems-assistant]

TheRock Submodule Bump Activity

Newest first

• 2026-10-02 — Included in TheRock via ROCm/TheRock#8588.