rocprofiler-sdk/counters.h Source File

rocprofiler-sdk/counters.h Source File#

Rocprofiler SDK Developer API: rocprofiler-sdk/counters.h Source File
Rocprofiler SDK Developer API 0.6.0
ROCm Profiling API and tools
counters.h
Go to the documentation of this file.
1// MIT License
2//
3// Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved.
4//
5// Permission is hereby granted, free of charge, to any person obtaining a copy
6// of this software and associated documentation files (the "Software"), to deal
7// in the Software without restriction, including without limitation the rights
8// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9// copies of the Software, and to permit persons to whom the Software is
10// furnished to do so, subject to the following conditions:
11//
12// The above copyright notice and this permission notice shall be included in all
13// copies or substantial portions of the Software.
14//
15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21// SOFTWARE.
22
23#pragma once
24
27#include <rocprofiler-sdk/fwd.h>
28
29ROCPROFILER_EXTERN_C_INIT
30
31/**
32 * @defgroup COUNTERS Hardware counters Information
33 * @brief Query functions related to hardware counters
34 * @{
35 */
36
37/**
38 * @brief Query counter id information from record_id.
39 *
40 * @param [in] id record id from rocprofiler_record_counter_t
41 * @param [out] counter_id counter id associated with the record
42 * @return ::rocprofiler_status_t
43 * @retval ROCPROFILER_STATUS_SUCCESS if id decoded
44 */
47 rocprofiler_counter_id_t* counter_id) ROCPROFILER_API
48 ROCPROFILER_NONNULL(2);
49
50/**
51 * @brief Query dimension position from record_id. If the dimension does not exist
52 * in the counter, the return will be 0.
53 *
54 * @param [in] id record id from @ref rocprofiler_record_counter_t
55 * @param [in] dim dimension for which positional info is requested (currently only
56 * 0 is allowed, i.e. flat array without dimension).
57 * @param [out] pos value of the dimension in id
58 * @return ::rocprofiler_status_t
59 * @retval ROCPROFILER_STATUS_SUCCESS if dimension decoded
60 */
64 size_t* pos) ROCPROFILER_API ROCPROFILER_NONNULL(3);
65
66/**
67 * @brief Callback that gives a list of available dimensions for a counter
68 *
69 * @param [in] id Counter id the dimension data is for
70 * @param [in] dim_info An array of dimensions for the counter
71 * @ref rocprofiler_iterate_counter_dimensions was called on.
72 * @param [in] num_dims Number of dimensions
73 * @param [in] user_data User data supplied by
74 * @ref rocprofiler_iterate_agent_supported_counters
75 */
79 size_t num_dims,
80 void* user_data);
81
82/**
83 * @brief Return information about the dimensions that exists for a specific counter
84 * and the extent of each dimension.
85 *
86 * @param [in] id counter id to query dimension info for.
87 * @param [in] info_cb Callback to return dimension information for counter
88 * @param [in] user_data data to pass into the callback
89 * @return ::rocprofiler_status_t
90 * @retval ROCPROFILER_STATUS_SUCCESS if dimension exists
91 * @retval ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND if counter is not found
92 * @retval ROCPROFILER_STATUS_ERROR_DIM_NOT_FOUND if counter does not have this dimension
93 */
97 void* user_data) ROCPROFILER_API;
98
99/**
100 * @brief Query Counter info such as name or description.
101 *
102 * @param [in] counter_id counter to get info for
103 * @param [in] version Version of struct in info, see @ref rocprofiler_counter_info_version_id_t for
104 * available types
105 * @param [out] info rocprofiler_counter_info_{version}_t struct to write info to.
106 * @return ::rocprofiler_status_t
107 * @retval ROCPROFILER_STATUS_SUCCESS if counter found
108 * @retval ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND if counter not found
109 * @retval ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI Version is not supported
110 */
114 void* info) ROCPROFILER_API ROCPROFILER_NONNULL(3);
115
116/**
117 * @brief This call returns the number of instances specific counter contains.
118 *
119 * @param [in] agent_id rocprofiler agent identifier
120 * @param [in] counter_id counter id (obtained from iterate_agent_supported_counters)
121 * @param [out] instance_count number of instances the counter has
122 * @return ::rocprofiler_status_t
123 * @retval ROCPROFILER_STATUS_SUCCESS if counter found
124 * @retval ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND if counter not found
125 */
128 rocprofiler_counter_id_t counter_id,
129 size_t* instance_count) ROCPROFILER_API
130 ROCPROFILER_NONNULL(3);
131
132/**
133 * @brief Callback that gives a list of counters available on an agent. The
134 * counters variable is owned by rocprofiler and should not be free'd.
135 *
136 * @param [in] agent_id Agent ID of the current callback
137 * @param [in] counters An array of counters that are avialable on the agent
138 * @ref rocprofiler_iterate_agent_supported_counters was called on.
139 * @param [in] num_counters Number of counters contained in counters
140 * @param [in] user_data User data supplied by
141 * @ref rocprofiler_iterate_agent_supported_counters
142 */
144 rocprofiler_agent_id_t agent_id,
145 rocprofiler_counter_id_t* counters,
146 size_t num_counters,
147 void* user_data);
148
149/**
150 * @brief Query Agent Counters Availability.
151 *
152 * @param [in] agent_id GPU agent identifier
153 * @param [in] cb callback to caller to get counters
154 * @param [in] user_data data to pass into the callback
155 * @return ::rocprofiler_status_t
156 * @retval ROCPROFILER_STATUS_SUCCESS if counters found for agent
157 * @retval ROCPROFILER_STATUS_ERROR if no counters found for agent
158 */
162 void* user_data) ROCPROFILER_API
163 ROCPROFILER_NONNULL(2);
164
165/** @} */
166
167ROCPROFILER_EXTERN_C_FINI
uint64_t rocprofiler_counter_dimension_id_t
A dimension for counter instances. Some example dimensions include XCC, SM (Shader),...
Definition fwd.h:501
uint64_t rocprofiler_counter_instance_id_t
Unique record id encoding both the counter and dimensional values (positions) for the record.
Definition fwd.h:493
rocprofiler_status_t
Status codes.
Definition fwd.h:53
rocprofiler_counter_info_version_id_t
Enumeration for specifying the counter info struct version you want.
Definition fwd.h:406
Agent Identifier.
Definition fwd.h:578
Counter ID.
Definition fwd.h:586
Details for the dimension, including its size, for a counter record.
Definition fwd.h:707
rocprofiler_status_t rocprofiler_iterate_counter_dimensions(rocprofiler_counter_id_t id, rocprofiler_available_dimensions_cb_t info_cb, void *user_data)
Return information about the dimensions that exists for a specific counter and the extent of each dim...
rocprofiler_status_t rocprofiler_iterate_agent_supported_counters(rocprofiler_agent_id_t agent_id, rocprofiler_available_counters_cb_t cb, void *user_data)
Query Agent Counters Availability.
rocprofiler_status_t(* rocprofiler_available_counters_cb_t)(rocprofiler_agent_id_t agent_id, rocprofiler_counter_id_t *counters, unsigned long num_counters, void *user_data)
Callback that gives a list of counters available on an agent. The counters variable is owned by rocpr...
Definition counters.h:143
rocprofiler_status_t rocprofiler_query_record_counter_id(rocprofiler_counter_instance_id_t id, rocprofiler_counter_id_t *counter_id)
Query counter id information from record_id.
rocprofiler_status_t rocprofiler_query_record_dimension_position(rocprofiler_counter_instance_id_t id, rocprofiler_counter_dimension_id_t dim, unsigned long *pos)
Query dimension position from record_id. If the dimension does not exist in the counter,...
rocprofiler_status_t(* rocprofiler_available_dimensions_cb_t)(rocprofiler_counter_id_t id, const rocprofiler_record_dimension_info_t *dim_info, unsigned long num_dims, void *user_data)
Callback that gives a list of available dimensions for a counter.
Definition counters.h:76
rocprofiler_status_t rocprofiler_query_counter_instance_count(rocprofiler_agent_id_t agent_id, rocprofiler_counter_id_t counter_id, unsigned long *instance_count)
This call returns the number of instances specific counter contains.
rocprofiler_status_t rocprofiler_query_counter_info(rocprofiler_counter_id_t counter_id, rocprofiler_counter_info_version_id_t version, void *info)
Query Counter info such as name or description.