feat(hipfile): Add getStats functions to public api

projects/hipfile/include/hipfile-api-trace.h

@@ -15,7 +15,7 @@
 // Increment the step version when new runtime API functions are added.
 // If the corresponding table version increases, reset the step version
 // to zero.
-#define HIPFILE_RUNTIME_API_TABLE_STEP_VERSION 0
+#define HIPFILE_RUNTIME_API_TABLE_STEP_VERSION 1
 
 // hipFile API interface
 typedef const char *(*PfnHipFileGetOpErrorString)(hipFileOpError_t status);
@@ -60,6 +60,9 @@ typedef hipFileError_t (*PfnHipFileSetParameterSizeT)(hipFileSizeTConfigParamete
 typedef hipFileError_t (*PfnHipFileSetParameterBool)(hipFileBoolConfigParameter_t param, bool value);
 typedef hipFileError_t (*PfnHipFileSetParameterString)(hipFileStringConfigParameter_t param,
                                                        const char                    *desc_str);
+typedef hipFileError_t (*PfnHipFileGetStatsL1)(hipFileStatsLevel1_t *stats);
+typedef hipFileError_t (*PfnHipFileGetStatsL2)(hipFileStatsLevel2_t *stats);
+typedef hipFileError_t (*PfnHipFileGetStatsL3)(hipFileStatsLevel3_t *stats);
 
 // hipFile API dispatch table
 struct hipFileDispatchTable {
@@ -99,6 +102,12 @@ struct hipFileDispatchTable {
     // PLEASE DO NOT EDIT ABOVE!
 
     // HIPFILE_RUNTIME_API_TABLE_STEP_VERSION == 1
+    PfnHipFileGetStatsL1 pfn_hipfile_get_stats_l1;
+    PfnHipFileGetStatsL2 pfn_hipfile_get_stats_l2;
+    PfnHipFileGetStatsL3 pfn_hipfile_get_stats_l3;
+    // PLEASE DO NOT EDIT ABOVE!
+
+    // HIPFILE_RUNTIME_API_TABLE_STEP_VERSION == 2
 
     // *******************************************************************************************
     //                                            READ BELOW

projects/hipfile/include/hipfile.h

@@ -1069,6 +1069,195 @@ hipFileError_t hipFileSetParameterBool(hipFileBoolConfigParameter_t param, bool
 HIPFILE_API
 hipFileError_t hipFileSetParameterString(hipFileStringConfigParameter_t param, const char *desc_str);
 
+// ***********************************************************************
+//  STATS API
+// ***********************************************************************
+
+/*!
+ * @defgroup stats Stats API
+ *
+ * @brief Functions for querying hipFile I/O statistics
+ */
+
+/*!
+ * @brief Maximum number of GPUs tracked by the stats API
+ * @ingroup stats
+ */
+#define HIPFILE_MAX_GPUS 16
+
+/*!
+ * @brief Length of the GPU UUID field in hipFilePerGpuStats_t
+ * @ingroup stats
+ */
+#define HIPFILE_GPU_UUID_LEN 16
+
+/*!
+ * @brief Counter tracking successful and failed occurrences of an operation
+ * @ingroup stats
+ */
+typedef struct hipFileOpCounter {
+    uint64_t ok;  //!< Number of successful operations
+    uint64_t err; //!< Number of failed operations
+} hipFileOpCounter_t;
+
+/*!
+ * @brief Level 1 statistics: basic I/O and operation counters
+ * @ingroup stats
+ *
+ * Fields that hipFile does not track are zero-filled. Calculated fields
+ * (bandwidth, average latency) are derived from the counters that are tracked.
+ */
+typedef struct hipFileStatsLevel1 {
+    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)
+} hipFileStatsLevel1_t;
+
+/*!
+ * @brief Level 2 statistics: includes Level 1 plus I/O size histograms
+ * @ingroup stats
+ *
+ * The size histograms are zero-filled; hipFile tracks histograms with different
+ * bucket boundaries that are not directly mappable to this format.
+ */
+typedef struct hipFileStatsLevel2 {
+    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)
+} hipFileStatsLevel2_t;
+
+/*!
+ * @brief Per-GPU statistics used in Level 3
+ * @ingroup stats
+ *
+ * Fields that hipFile does not track are zero-filled. The fastpath backend
+ * maps to @c n_nvfs_reads / @c n_nvfs_writes, and the fallback backend maps
+ * to @c n_posix_reads / @c n_posix_writes.
+ */
+typedef struct hipFilePerGpuStats {
+    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 writes_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)
+} hipFilePerGpuStats_t;
+
+/*!
+ * @brief Level 3 statistics: includes Level 2 plus per-GPU statistics
+ * @ingroup stats
+ */
+typedef struct hipFileStatsLevel3 {
+    hipFileStatsLevel2_t detailed;                        //!< Level 2 statistics
+    uint32_t             num_gpus;                        //!< Number of GPUs with recorded activity
+    hipFilePerGpuStats_t per_gpu_stats[HIPFILE_MAX_GPUS]; //!< Per-GPU statistics
+} hipFileStatsLevel3_t;
+
+/*!
+ * @brief Get Level 1 hipFile statistics
+ * @ingroup stats
+ *
+ * @param [out] stats Pointer to a hipFileStatsLevel1_t structure to be filled
+ *
+ * @return \hipfile_error_return
+ */
+HIPFILE_API
+hipFileError_t hipFileGetStatsL1(hipFileStatsLevel1_t *stats);
+
+/*!
+ * @brief Get Level 2 hipFile statistics
+ * @ingroup stats
+ *
+ * @param [out] stats Pointer to a hipFileStatsLevel2_t structure to be filled
+ *
+ * @return \hipfile_error_return
+ */
+HIPFILE_API
+hipFileError_t hipFileGetStatsL2(hipFileStatsLevel2_t *stats);
+
+/*!
+ * @brief Get Level 3 hipFile statistics
+ * @ingroup stats
+ *
+ * @param [out] stats Pointer to a hipFileStatsLevel3_t structure to be filled
+ *
+ * @return \hipfile_error_return
+ */
+HIPFILE_API
+hipFileError_t hipFileGetStatsL3(hipFileStatsLevel3_t *stats);
+
 // Not a part of the public API
 #undef __HIPFILE_NODISCARD
 

projects/hipfile/src/amd_detail/api_trace/api-dispatch-interface.cpp

@@ -169,3 +169,18 @@ hipFileSetParameterString(hipFileStringConfigParameter_t param, const char *desc
 {
     return hipFile::GetHipFileDispatchTable()->pfn_hipfile_set_parameter_string(param, desc_str);
 }
+hipFileError_t
+hipFileGetStatsL1(hipFileStatsLevel1_t *stats)
+{
+    return hipFile::GetHipFileDispatchTable()->pfn_hipfile_get_stats_l1(stats);
+}
+hipFileError_t
+hipFileGetStatsL2(hipFileStatsLevel2_t *stats)
+{
+    return hipFile::GetHipFileDispatchTable()->pfn_hipfile_get_stats_l2(stats);
+}
+hipFileError_t
+hipFileGetStatsL3(hipFileStatsLevel3_t *stats)
+{
+    return hipFile::GetHipFileDispatchTable()->pfn_hipfile_get_stats_l3(stats);
+}

projects/hipfile/src/amd_detail/api_trace/api-trace-internal.h

@@ -61,5 +61,8 @@ hipFileError_t hipFileGetParameterString(hipFileStringConfigParameter_t param, c
 hipFileError_t hipFileSetParameterSizeT(hipFileSizeTConfigParameter_t param, size_t value);
 hipFileError_t hipFileSetParameterBool(hipFileBoolConfigParameter_t param, bool value);
 hipFileError_t hipFileSetParameterString(hipFileStringConfigParameter_t param, const char *desc_str);
+hipFileError_t hipFileGetStatsL1(hipFileStatsLevel1_t *stats);
+hipFileError_t hipFileGetStatsL2(hipFileStatsLevel2_t *stats);
+hipFileError_t hipFileGetStatsL3(hipFileStatsLevel3_t *stats);
 
 } // namespace hipFile

projects/hipfile/src/amd_detail/api_trace/api-trace.cpp

@@ -58,6 +58,9 @@ namespace {
         ptr_dispatch_table->pfn_hipfile_set_parameter_size_t = hipFile::hipFileSetParameterSizeT;
         ptr_dispatch_table->pfn_hipfile_set_parameter_bool   = hipFile::hipFileSetParameterBool;
         ptr_dispatch_table->pfn_hipfile_set_parameter_string = hipFile::hipFileSetParameterString;
+        ptr_dispatch_table->pfn_hipfile_get_stats_l1         = hipFile::hipFileGetStatsL1;
+        ptr_dispatch_table->pfn_hipfile_get_stats_l2         = hipFile::hipFileGetStatsL2;
+        ptr_dispatch_table->pfn_hipfile_get_stats_l3         = hipFile::hipFileGetStatsL3;
     }
 
 #if HIPFILE_ROCPROFILER_REGISTER > 0
@@ -169,14 +172,18 @@ HIPFILE_ENFORCE_ABI(hipFileDispatchTable, pfn_hipfile_set_parameter_size_t, 28)
 HIPFILE_ENFORCE_ABI(hipFileDispatchTable, pfn_hipfile_set_parameter_bool, 29)
 HIPFILE_ENFORCE_ABI(hipFileDispatchTable, pfn_hipfile_set_parameter_string, 30)
 // HIPFILE_RUNTIME_API_TABLE_STEP_VERSION == 1
+HIPFILE_ENFORCE_ABI(hipFileDispatchTable, pfn_hipfile_get_stats_l1, 31)
+HIPFILE_ENFORCE_ABI(hipFileDispatchTable, pfn_hipfile_get_stats_l2, 32)
+HIPFILE_ENFORCE_ABI(hipFileDispatchTable, pfn_hipfile_get_stats_l3, 33)
+// HIPFILE_RUNTIME_API_TABLE_STEP_VERSION == 2
 
 // If HIPFILE_ENFORCE_ABI entries are added for each new function pointer in the table,
 // the number below will be one greater than the number in the last HIPFILE_ENFORCE_ABI line. For example:
-//  HIPFILE_ENFORCE_ABI(<table>, <functor>, 30)
-//  HIPFILE_ENFORCE_ABI_VERSIONING(<table>, 31) <- 30 + 1 = 31
-HIPFILE_ENFORCE_ABI_VERSIONING(hipFileDispatchTable, 31)
+//  HIPFILE_ENFORCE_ABI(<table>, <functor>, 33)
+//  HIPFILE_ENFORCE_ABI_VERSIONING(<table>, 34) <- 33 + 1 = 34
+HIPFILE_ENFORCE_ABI_VERSIONING(hipFileDispatchTable, 34)
 
-static_assert(HIPFILE_RUNTIME_API_TABLE_MAJOR_VERSION == 0 && HIPFILE_RUNTIME_API_TABLE_STEP_VERSION == 0,
+static_assert(HIPFILE_RUNTIME_API_TABLE_MAJOR_VERSION == 0 && HIPFILE_RUNTIME_API_TABLE_STEP_VERSION == 1,
               "If you encounter this error, add the new HIPFILE_ENFORCE_ABI(...) code for the updated "
               "function pointers, "
               "and then modify this check to ensure it evaluates to true.");