Statistics API reference

Statistics API reference#

The hipFile statistics API reports I/O and operation counters accumulated by the driver. Statistics are organized into three cumulative levels: Level 1 provides basic I/O and operation counters, Level 2 adds I/O size histograms, and Level 3 adds per-GPU statistics.

Fields that hipFile does not track are zero-filled, and calculated fields such as bandwidth and average latency are derived from the counters that are tracked. See the Doxygen descriptions for the tracking status of individual fields.

Statistics types and functions#

The maximum-GPU and UUID-length macros, the operation counter and leveled statistics structures, and the functions to query Level 1, Level 2, and Level 3 statistics from the hipFile driver.

HIPFILE_API hipFileError_t hipFileGetStatsL1(hipFileStatsLevel1_t *stats)#

Get Level 1 hipFile statistics.

Parameters:: stats – [out] Pointer to a hipFileStatsLevel1_t structure to be filled
Returns:: A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileGetStatsL2(hipFileStatsLevel2_t *stats)#

Get Level 2 hipFile statistics.

Parameters:: stats – [out] Pointer to a hipFileStatsLevel2_t structure to be filled
Returns:: A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_API hipFileError_t hipFileGetStatsL3(hipFileStatsLevel3_t *stats)#

Get Level 3 hipFile statistics.

Parameters:: stats – [out] Pointer to a hipFileStatsLevel3_t structure to be filled
Returns:: A hipFileError_t struct that holds both hipFile and HIP error values

HIPFILE_MAX_GPUS#: Maximum number of GPUs tracked by the stats API.

HIPFILE_GPU_UUID_LEN#: Length of the GPU UUID field in hipFilePerGpuStats_t.

struct hipFileOpCounter_t#

#include <hipfile.h>

Counter tracking successful and failed occurrences of an operation.

Public Members

uint64_t ok#: Number of successful operations.

uint64_t err#: Number of failed operations.

struct hipFileStatsLevel1_t#

#include <hipfile.h>

Level 1 statistics: basic I/O and operation counters.

Fields that hipFile does not track are zero-filled. Calculated fields (bandwidth, average latency) are derived from the counters that are tracked.

Public Members

hipFileOpCounter_t read_ops#: Read operation counters.

hipFileOpCounter_t write_ops#: Write operation counters.

hipFileOpCounter_t hdl_register_ops#: File handle register operation counters.

hipFileOpCounter_t hdl_deregister_ops#: File handle deregister operation counters (zero-filled)

hipFileOpCounter_t buf_register_ops#: Buffer register operation counters.

hipFileOpCounter_t buf_deregister_ops#: Buffer deregister operation counters (zero-filled)

uint64_t read_bytes#: Total bytes read.

uint64_t write_bytes#: Total bytes written.

uint64_t read_bw_bytes_per_sec#: Read bandwidth (bytes/sec), derived from bytes and latency sum.

uint64_t write_bw_bytes_per_sec#: Write bandwidth (bytes/sec), derived from bytes and latency sum.

uint64_t read_lat_avg_us#: Average read latency (us), derived from latency sum and op count.

uint64_t write_lat_avg_us#: Average write latency (us), derived from latency sum and op count.

uint64_t read_ops_per_sec#: Read operations per second (zero-filled)

uint64_t write_ops_per_sec#: Write operations per second (zero-filled)

uint64_t read_lat_sum_us#: Sum of read latencies (us)

uint64_t write_lat_sum_us#: Sum of write latencies (us)

hipFileOpCounter_t batch_submit_ops#: Batch submit operation counters (zero-filled)

hipFileOpCounter_t batch_complete_ops#: Batch complete operation counters (zero-filled)

hipFileOpCounter_t batch_setup_ops#: Batch setup operation counters (zero-filled)

hipFileOpCounter_t batch_cancel_ops#: Batch cancel operation counters (zero-filled)

hipFileOpCounter_t batch_destroy_ops#: Batch destroy operation counters (zero-filled)

hipFileOpCounter_t batch_enqueued_ops#: Batch enqueue operation counters (zero-filled)

hipFileOpCounter_t batch_posix_enqueued_ops#: POSIX batch enqueue operation counters (zero-filled)

hipFileOpCounter_t batch_processed_ops#: Batch process operation counters (zero-filled)

hipFileOpCounter_t batch_posix_processed_ops#: POSIX batch process operation counters (zero-filled)

hipFileOpCounter_t batch_nvfs_submit_ops#: NVFS batch submit operation counters (zero-filled)

hipFileOpCounter_t batch_p2p_submit_ops#: P2P batch submit operation counters (zero-filled)

hipFileOpCounter_t batch_aio_submit_ops#: AIO batch submit operation counters (zero-filled)

hipFileOpCounter_t batch_iouring_submit_ops#: io_uring batch submit operation counters (zero-filled)

hipFileOpCounter_t batch_mixed_io_submit_ops#: Mixed IO batch submit operation counters (zero-filled)

hipFileOpCounter_t batch_total_submit_ops#: Total batch submit operation counters (zero-filled)

uint64_t batch_read_bytes#: Total batch read bytes (zero-filled)

uint64_t batch_write_bytes#: Total batch write bytes (zero-filled)

uint64_t batch_read_bw_bytes#: Batch read bandwidth (zero-filled)

uint64_t batch_write_bw_bytes#: Batch write bandwidth (zero-filled)

uint64_t batch_submit_lat_avg_us#: Average batch submit latency (zero-filled)

uint64_t batch_completion_lat_avg_us#: Average batch completion latency (zero-filled)

uint64_t batch_submit_ops_per_sec#: Batch submit operations per second (zero-filled)

uint64_t batch_complete_ops_per_sec#: Batch complete operations per second (zero-filled)

uint64_t batch_submit_lat_sum_us#: Sum of batch submit latencies (zero-filled)

uint64_t batch_completion_lat_sum_us#: Sum of batch completion latencies (zero-filled)

uint64_t last_batch_read_bytes#: Last batch read bytes (zero-filled)

uint64_t last_batch_write_bytes#: Last batch write bytes (zero-filled)

struct hipFileStatsLevel2_t#

#include <hipfile.h>

Level 2 statistics: includes Level 1 plus I/O size histograms.

The size histograms are zero-filled; hipFile tracks histograms with different bucket boundaries that are not directly mappable to this format.

Public Members

hipFileStatsLevel1_t basic#: Level 1 statistics.

uint64_t read_size_kb_hist[32]#: Histogram of read sizes in KiB (zero-filled)

uint64_t write_size_kb_hist[32]#: Histogram of write sizes in KiB (zero-filled)

struct hipFilePerGpuStats_t#

#include <hipfile.h>

Per-GPU statistics used in Level 3.

Fields that hipFile does not track are zero-filled. The fastpath backend maps to n_nvfs_reads / n_nvfs_writes, and the fallback backend maps to n_posix_reads / n_posix_writes.

Public Members

char uuid[HIPFILE_GPU_UUID_LEN]#: GPU UUID (zero-filled)

uint64_t read_bytes#: Total bytes read.

uint64_t read_bw_bytes_per_sec#: Read bandwidth (bytes/sec), derived from bytes and duration.

uint64_t read_utilization#: Read utilization percentage (zero-filled)

uint64_t read_duration_us#: Total read duration (us)

uint64_t n_total_reads#: Total number of reads across all backends.

uint64_t n_p2p_reads#: Number of PCIe P2P DMA reads (zero-filled)

uint64_t n_nvfs_reads#: Number of fastpath reads.

uint64_t n_posix_reads#: Number of fallback (POSIX) reads.

uint64_t n_unaligned_reads#: Number of unaligned reads.

uint64_t n_dr_reads#: Number of dynamic-routing reads (zero-filled)

uint64_t n_sparse_regions#: Number of sparse regions (zero-filled)

uint64_t n_inline_regions#: Number of inline regions (zero-filled)

uint64_t n_reads_err#: Number of read errors.

uint64_t write_bytes#: Total bytes written.

uint64_t write_bw_bytes_per_sec#: Write bandwidth (bytes/sec), derived from bytes and duration.

uint64_t write_utilization#: Write utilization percentage (zero-filled)

uint64_t write_duration_us#: Total write duration (us)

uint64_t n_total_writes#: Total number of writes across all backends.

uint64_t n_p2p_writes#: Number of PCIe P2P DMA writes (zero-filled)

uint64_t n_nvfs_writes#: Number of fastpath writes.

uint64_t n_posix_writes#: Number of fallback (POSIX) writes.

uint64_t n_unaligned_writes#: Number of unaligned writes.

uint64_t n_dr_writes#: Number of dynamic-routing writes (zero-filled)

uint64_t n_writes_err#: Number of write errors.

uint64_t n_mmap#: Number of buffer registrations (global counter, not per-GPU)

uint64_t n_mmap_ok#: Successful buffer registrations (same as n_mmap)

uint64_t n_mmap_err#: Failed buffer registrations (zero-filled)

uint64_t n_mmap_free#: Number of buffer deregistrations (zero-filled)

uint64_t reg_bytes#: Total bytes registered (zero-filled)

struct hipFileStatsLevel3_t#

#include <hipfile.h>

Level 3 statistics: includes Level 2 plus per-GPU statistics.

per_gpu_stats is indexed by GPU ordinal, not packed: entry i holds the stats for GPU i, and slots for inactive GPUs are zero-filled. num_gpus is the count of active GPUs, not the largest populated index. Consumers must iterate all HIPFILE_MAX_GPUS slots rather than 0..num_gpus-1.

Public Members

hipFileStatsLevel2_t detailed#: Level 2 statistics.

uint32_t num_gpus#: Count of active GPUs.

hipFilePerGpuStats_t per_gpu_stats[HIPFILE_MAX_GPUS]#: Per-GPU statistics, indexed by GPU ordinal.

Statistics API reference

Contents

Statistics API reference#

Statistics types and functions#