feat(hipfile): Add getStats functions to public api by zbyrne · Pull Request #8252 · ROCm/rocm-systems

zbyrne · 2026-07-08T16:33:52Z

Motivation

RocProfiler needs a public api for consuming telemetry from HipFile.

Technical Details

The public stats structs don't exactly match the internal data collected by the library, so simple (although sizeable) transformations are performed when populating the out params in hipFileGetStatsLX().

The new functions are added to the API tracing wrapper table, this will probably require coordinating with the profiler team.

JIRA ID

JIRA ID : AIHIPFILE-240

Test Plan

Unit tests added for all three getStats functions.

Test Result

Tests passed.

Submission Checklist

Look over the contributing guidelines at https://github.com/ROCm/ROCm/blob/develop/CONTRIBUTING.md#pull-requests.

therock-pr-bot · 2026-07-08T16:35:07Z

❌ PR Check — Action Required

Check	Status	Details
🌿 Branch Name	✅ Pass	—
📝 PR Title/Description	✅ Pass	—
⛔ Forbidden Files	✅ Pass	—
🧪 Unit Test	❌ Fail	Error: Source/code files changed without an accompanying unit test. Expected: add at least one test file named like `test_<name>.py` / `test_<name>.cpp` (or `<name>_test.`). Current:* code file(s) changed: `projects/hipfile/include/hipfile-api-trace.h`, `projects/hipfile/include/hipfile.h`, `projects/hipfile/src/amd_detail/api_trace/api-dispatch-interface.cpp`, `projects/hipfile/src/amd_detail/api_trace/api-trace-internal.h`, `projects/hipfile/src/amd_detail/api_trace/api-trace.cpp` (+3 more); no test file found
🔎 pre-commit	⏳ Pending	⏳ Still running…
🚫 Draft PR	🔜 To Be Enabled	—
🚩 Feature Flag	🔜 To Be Enabled	—
📊 Code Coverage	🔜 To Be Enabled	—

⚠️ 1 policy check(s) failed. Please address the issues above before this PR can be Reviewed.

🚫 Please fix the failed policies

❌ Unit Test

The Not ready to Review label was added to this PR. Once all policies pass, the label is removed automatically.

📖 Need help? See the Policy FAQ for details on every check and how to fix failures.

therock-pr-bot · 2026-07-08T16:35:08Z

🚫 Please fix the failed policies before requesting reviews.

The following policy checks failed:

❌ Unit Test

The Not ready to Review label has been added to this PR.
Once all policies pass, the label will be removed automatically.

Copilot

Pull request overview

This PR adds a public “Stats API” to hipFile (L1/L2/L3) so external tooling (e.g., RocProfiler) can query aggregated and per-GPU I/O telemetry, and wires those new entry points through the API tracing/dispatch table. It also introduces unit tests validating the new aggregation and derived-field behavior.

Changes:

Added new public stats structs and hipFileGetStatsL1/L2/L3 API declarations to hipfile.h.
Implemented hipFileGetStatsL1/L2/L3 in the runtime and hooked them into the api-trace dispatch table.
Added unit tests covering the three new getStats functions and basic aggregation/derivation behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
projects/hipfile/test/amd_detail/hipfile-api.cpp	Adds unit tests for the new stats APIs (L1/L2/L3).
projects/hipfile/src/amd_detail/hipfile.cpp	Implements `hipFileGetStatsL1/L2/L3` and derives aggregate/per-GPU metrics.
projects/hipfile/src/amd_detail/api_trace/api-trace.cpp	Registers the new getStats functions in the dispatch table and updates ABI enforcement indices/versioning.
projects/hipfile/src/amd_detail/api_trace/api-trace-internal.h	Adds internal declarations for the new getStats functions.
projects/hipfile/src/amd_detail/api_trace/api-dispatch-interface.cpp	Exposes public C entry points that forward to the dispatch table for getStats functions.
projects/hipfile/include/hipfile.h	Introduces the public Stats API types and function declarations.
projects/hipfile/include/hipfile-api-trace.h	Bumps dispatch table step version and adds function pointer typedefs/entries for getStats APIs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sputhala-amd

Please bump the hipFile version in both CMakeLists.txt and hipfile.h so downstream consumers like rocprofiler-systems can gate on version at build time via find_package(hipfile ) and at compile time via the HIPFILE_VERSION_* macros.

Adds the public types and function declarations for the three-level stats reporting API: hipFileStatsLevel1_t, hipFileStatsLevel2_t, hipFileStatsLevel3_t, hipFilePerGpuStats_t, hipFileOpCounter_t, and the corresponding hipFileGetStatsL1/L2/L3 functions. Fields that hipFile does not track are documented as zero-filled. Calculated fields (bandwidth, average latency) are noted as derived from tracked counters. Co-Authored-By: Claude <noreply@anthropic.com>

…entations Adds hipFileGetStatsL1/L2/L3 to the profiler dispatch table: - typedefs and struct members in hipfile-api-trace.h (step version 0 -> 1) - runtime declarations in api-trace-internal.h - UpdateDispatchTable wiring and ABI enforcement assertions in api-trace.cpp - extern "C" thunks in api-dispatch-interface.cpp - stub implementations in hipfile.cpp (return hipFileInternalError) Co-Authored-By: Claude <noreply@anthropic.com>

Aggregates IO bytes, counts, latency sums, and error counts across all GPUs and both backends (fastpath + fallback). Derives average latency and bandwidth from the accumulated totals. File and buffer registration counts come from the global atomic counters. Fields with no hipFile equivalent are left zero-filled. Co-Authored-By: Claude <noreply@anthropic.com>

Delegates to hipFileGetStatsL1 for the basic counters. The 32-bucket size histograms are left zero-filled since hipFile's internal 16-bucket histograms use different bucket boundaries that cannot be losslessly mapped to the cufile format. Co-Authored-By: Claude <noreply@anthropic.com>

Delegates to hipFileGetStatsL2 for the aggregate L2 stats, then iterates all 16 GPU slots to populate per-GPU entries for active GPUs. Per-GPU mapping: - fastpath backend -> n_nvfs_reads / n_nvfs_writes - fallback backend -> n_posix_reads / n_posix_writes - bandwidth derived from bytes and duration per GPU - buffer registrations (global counter) reported on each active GPU as the best available approximation num_gpus reflects the count of GPUs with recorded activity. Co-Authored-By: Claude <noreply@anthropic.com>

## Motivation RocProfiler needs a public api for consuming telemetry from HipFile. ## Technical Details The public stats structs don't exactly match the internal data collected by the library, so simple (although sizeable) transformations are performed when populating the out params in hipFileGetStatsLX(). The new functions are added to the API tracing wrapper table, this will probably require coordinating with the profiler team. ## JIRA ID JIRA ID : AIHIPFILE-240 ## Test Plan Unit tests added for all three getStats functions. ## Test Result Tests passed. ## Submission Checklist - [x] Look over the contributing guidelines at https://github.com/ROCm/ROCm/blob/develop/CONTRIBUTING.md#pull-requests. [rocm-systems] ROCm/rocm-systems#8252 (commit a3c059c)

…9260) ## Motivation The stats API changes are causing build failures in the profiler code. We are reverting this temporarily and will set up a PR once we've ensured that our API changes will no longer break the profiler. ## Technical Details This reverts commit a3c059c. ## Issue Tracking JIRA ID: AIHIPFILE-240 ## Test Plan CI passes ## Test Result Success ## Submission Checklist - [ ] Look over the contributing guidelines at https://github.com/ROCm/rocm-systems/blob/develop/CONTRIBUTING.md.

## Motivation RocProfiler needs a public api for consuming telemetry from HipFile. ## Technical Details The public stats structs don't exactly match the internal data collected by the library, so simple (although sizeable) transformations are performed when populating the out params in hipFileGetStatsLX(). The new functions are added to the API tracing wrapper table, this will probably require coordinating with the profiler team. ## JIRA ID JIRA ID : AIHIPFILE-240 ## Test Plan Unit tests added for all three getStats functions. ## Test Result Tests passed. ## Submission Checklist - [x] Look over the contributing guidelines at https://github.com/ROCm/ROCm/blob/develop/CONTRIBUTING.md#pull-requests.

…9260) ## Motivation The stats API changes are causing build failures in the profiler code. We are reverting this temporarily and will set up a PR once we've ensured that our API changes will no longer break the profiler. ## Technical Details This reverts commit a3c059c. ## Issue Tracking JIRA ID: AIHIPFILE-240 ## Test Plan CI passes ## Test Result Success ## Submission Checklist - [ ] Look over the contributing guidelines at https://github.com/ROCm/rocm-systems/blob/develop/CONTRIBUTING.md.

#9584) ## Motivation The hipFile stats API was temporarily reverted when TheRock CI failed due to issues with the profiler SDK, which includes a vendored version of hipfile.h that was not updated. ## Technical Details This reverts commit 3aabde9. This restores commit a3c059c, which added the hipFile Stats API. This PR includes the necessary ABI checks that will be necessary for TheRock CI to pass. ## Issue Tracking JIRA ID : AIHIPFILE-240 ## Test Plan CI passes ## Test Result Success ## Submission Checklist - [x] Look over the contributing guidelines at https://github.com/ROCm/rocm-systems/blob/develop/CONTRIBUTING.md.

…)" (ROCm#9260) This reverts commit 3aabde9.

## Motivation  ROCm Systems Profiler should be able to provide storage telemetry - letting users correlate file/buffer registrations, read/write throughput, fast-path vs. fallback usage, and I/O errors with GPU and application activity in a single Perfetto trace or RocPD database. This is increasingly important for GPU-direct storage workloads where the storage path is a common performance bottleneck that was previously invisible in the profiler. Depends on: - [x] #8252 - [x] #9584 - [x] #10548 - [x] ROCm/TheRock#7982 Todo: - [x] Ensure version gating for hipFile public API on 0.5.0? ## Technical Details  - **hipFile backend wrapper** (`source/lib/backends/hipfile/`) - Thin policy seam around `hipFileGetStatsL3`; isolates the profiler from hipFile's C API and enables mock-based unit tests. - **PMC collector** (`library/pmc/collectors/hipfile/`) - Snapshots hipFile's per-GPU stats on the process-sampling thread and stores the whole snapshot as a single typed `hipfile_pmc_sample` per GPU per poll. - **Trace-cache sample type (`source/lib/core/trace_cache/`) - Adding the typed sample follows the existing `gpu_pmc_sample` / `ainic_pmc_sample` pattern and uses the shared plumbing. - **Metric groups and defaults** - `ROCPROFSYS_HIPFILE_METRICS` selects read/write pairs by group (`fastpath`, `fallback`, `bandwidth`, `bytes`, `ops`, `unaligned`, `errors`, or `all`/`none`). - Defaults to `fastpath, fallback, bandwidth, bytes, errors` so traces focus on path usage and transfer rate without collecting every counter. - `ROCPROFSYS_HIPFILE_METRICS=none` skips device enumeration.` - **Build-time and runtime gating** - `ROCPROFSYS_BUILD_HIPFILE` is tri-state `AUTO` / `ON` / `OFF` (default `AUTO`). - `cmake/Packages.cmake` sets a derived INTERNAL `ROCPROFSYS_HIPFILE_SUPPORT` (AINIC-style) and never shadows the user cache: AUTO + missing/too-old package → disable, STATUS ON + missing/too-old package → FATAL_ERROR (version found, version required, hipfile_DIR / CMAKE_PREFIX_PATH) OFF → never search - `ROCPROFSYS_USE_HIPFILE` (env/config, default OFF) enables collection at run time; zero overhead when disabled or when the target does not use hipFile. - The backend compiles against `hipfile.h` but does not link `libhipfile`. `wrapper.hpp` resolves the two entry points it uses (`hipFileGetVersion`, `hipFileGetStatsL3`) with `dlopen`/`dlsym` at first sample. - Consequently `libhipfile.so.0` is not required for the profiler to start. Absent library, missing stats API (`hipFile` 0.4 reuses SONAME .so.0), or a too-old reported version all degrade to a warning and no hipFile tracks. - **Runtime guards** - Does not set `HIPFILE_STATS_LEVEL` (hipFile already defaults to 1). `USE_HIPFILE=ON` with `HIPFILE_STATS_LEVEL=0`, or with `USE_PROCESS_SAMPLING=OFF`, logs a warning and produces no hipFile tracks. - **Version checks** - Requires hipFile 0.5.0+ at build time (for `hipFileGetStatsL3`) and re-checks the loaded `libhipfile` at run time; logs a warning and skips collection if the runtime is too old. - **Example workload and validation** - `examples//hipfile/hipfile-io.cpp` runs a short read/write loop for telemetry validation. - `hipfile-io` is skipped when `ROCPROFSYS_HIPFILE_SUPPORT` is off - `tests/pytest/test_hipfile_telemetry.py` plus RocPD/Perfetto validation rules under `tests/rocpd-validation-rules/hipfile-telemetry/`. - **Documentation and changelog** - How-to: `docs/how-to/hipfile-telemetry.rst` (build/run settings, metric interpretation, linking contract, troubleshooting). - CHANGELOG entry under the unreleased 1.9.0 section. - **Follow-up for future** - Expose remaining hipFile telemetry that is already collected but not shown to the user. - Emit process-scoped file/buffer registration counters on a process track (as the CPU collector does), if useful. - Add `rocprof-sys-avail` reporting of which hipFile metrics can be collected. - Add a `--hipfile[=metrics]` domain flag so storage telemetry composes with existing presets (do not enable hipFile inside `trace-gpu` / `--gpu`; no dedicated storage preset until that flag exists). - When hipFile fills per-slot UUID (AIHIPFILE-272), join those to SDK agents (same as AMD SMI) so permutations/HIP_VISIBLE_DEVICES UUID lists map correctly without parsing the env var. ## Issue Tracking    JIRA ID: AIPROFSYST-710 ## Test Plan  - [ ] Unit tests: `hipfile-backend-tests`, `pmc-hipfile-collector-tests` - [ ] Integration: `ctest -R hipfile` / `pytest tests/pytest/test_hipfile_telemetry.py` (requires GPU + hipFile build) - [ ] Manual: profile a hipFile workload with `ROCPROFSYS_USE_HIPFILE=ON` and confirm `hipFile GPU<N> <metric>` tracks in Perfetto/RocPD ## Test Result  <img width="4062" height="952" alt="image" src="https://github.com/user-attachments/assets/db32f269-ad9e-4649-a958-807e72b604e7" /> <img width="4624" height="1164" alt="image" src="https://github.com/user-attachments/assets/d137757a-c3e9-4e4d-8ac8-b8201c57f6ea" /> ## Submission Checklist - [x] Look over the contributing guidelines at https://github.com/ROCm/rocm-systems/blob/develop/CONTRIBUTING.md. --------- Signed-off-by: David Galiffi <David.Galiffi@amd.com> Co-authored-by: David Galiffi <David.Galiffi@amd.com>

Copilot AI review requested due to automatic review settings July 8, 2026 16:33

zbyrne requested a review from a team as a code owner July 8, 2026 16:33

zbyrne marked this pull request as draft July 8, 2026 16:34

github-actions Bot added the project: hipfile label Jul 8, 2026

Copilot started reviewing on behalf of zbyrne July 8, 2026 16:34

View session

therock-pr-bot Bot added the Not ready to Review label Jul 8, 2026

Copilot AI reviewed Jul 8, 2026

View reviewed changes

zbyrne force-pushed the users/zbyrne/hipfile/public-stats-api branch from 6abbac7 to 53128ff Compare July 8, 2026 16:42

systems-assistant Bot added the organization: ROCm label Jul 8, 2026

zbyrne force-pushed the users/zbyrne/hipfile/public-stats-api branch 2 times, most recently from 43be4af to 48f0522 Compare July 13, 2026 16:53

zbyrne changed the title ~~[hipfile] Add getStats functions to public api~~ feat(hipfile): Add getStats functions to public api Jul 13, 2026

zbyrne marked this pull request as ready for review July 14, 2026 15:53

sputhala-amd reviewed Jul 14, 2026

View reviewed changes

sputhala-amd mentioned this pull request Jul 17, 2026

feat(rocprof-sys): Add hipFile GPU-direct storage I/O telemetry collection #8524

Closed

1 of 4 tasks

zbyrne and others added 5 commits July 24, 2026 09:29

derobins force-pushed the users/zbyrne/hipfile/public-stats-api branch from 48f0522 to 5a8edcf Compare July 24, 2026 16:42

derobins approved these changes Jul 24, 2026

View reviewed changes

derobins merged commit a3c059c into develop Jul 24, 2026
177 of 186 checks passed

derobins deleted the users/zbyrne/hipfile/public-stats-api branch July 24, 2026 19:32

sputhala-amd mentioned this pull request Aug 24, 2026

feat(rocprof-sys): Add hipFile GPU-direct storage I/O telemetry #10630

Merged

6 of 9 tasks

pull Bot pushed a commit to Stars1233/rocm-systems that referenced this pull request Sep 1, 2026

Reapply "feat(hipfile): Add getStats functions to public api (ROCm#8252…

e4dc59b

…)" (ROCm#9260) This reverts commit 3aabde9.

Navigation Menu

Repository navigation

feat(hipfile): Add getStats functions to public api - #8252

feat(hipfile): Add getStats functions to public api#8252
derobins merged 5 commits into
developfrom
users/zbyrne/hipfile/public-stats-api

zbyrne commented Jul 8, 2026 •

edited by derobins

Loading

Uh oh!

therock-pr-bot Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

therock-pr-bot Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sputhala-amd left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

zbyrne commented Jul 8, 2026 • edited by derobins Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Technical Details

JIRA ID

Test Plan

Test Result

Submission Checklist

Uh oh!

therock-pr-bot Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ PR Check — Action Required

Uh oh!

therock-pr-bot Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sputhala-amd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zbyrne commented Jul 8, 2026 •

edited by derobins

Loading

therock-pr-bot Bot commented Jul 8, 2026 •

edited

Loading

therock-pr-bot Bot commented Jul 8, 2026 •

edited

Loading