rocprofiler-sdk/agent.h Source File

rocprofiler-sdk/agent.h Source File#

Rocprofiler SDK Developer API: rocprofiler-sdk/agent.h Source File
Rocprofiler SDK Developer API 0.5.0
ROCm Profiling API and tools
agent.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
26#include <rocprofiler-sdk/fwd.h>
27
28#include <hsakmt/hsakmttypes.h>
29
30#include <stdint.h>
31
32ROCPROFILER_EXTERN_C_INIT
33
34/**
35 * @defgroup AGENTS Agent Information
36 * @brief needs brief description
37 *
38 * @{
39 */
40
41/**
42 * @brief Enumeration ID for version of the rocprofiler_agent_v*_t struct in rocprofiler_i
43 *
44 */
51
52/**
53 * @brief Cache information for an agent.
54 */
56{
57 uint64_t processor_id_low; ///< Identifies the processor number
58 uint64_t size; ///< Size of the cache
59 uint32_t level; ///< Integer representing level: 1, 2, 3, 4, etc.
60 uint32_t cache_line_size; ///< Cache line size in bytes
61 uint32_t cache_lines_per_tag; ///< Cache lines per Cache Tag
62 uint32_t association; ///< Cache Associativity
63 uint32_t latency; ///< Cache latency in ns
64 HsaCacheType type;
66
67/**
68 * @brief IO link information for an agent.
69 */
71{
72 HSA_IOLINKTYPE type; ///< Discoverable IoLink Properties (optional)
73 uint32_t version_major; ///< Bus interface version (optional)
74 uint32_t version_minor; ///< Bus interface version (optional)
75 uint32_t node_from; ///< See @ref rocprofiler_agent_id_t
76 uint32_t node_to; ///< See @ref rocprofiler_agent_id_t
77 uint32_t weight; ///< weight factor (derived from CDIT)
78 uint32_t min_latency; ///< minimum cost of time to transfer (rounded to ns)
79 uint32_t max_latency; ///< maximum cost of time to transfer (rounded to ns)
80 uint32_t min_bandwidth; ///< minimum interface Bandwidth in MB/s
81 uint32_t max_bandwidth; ///< maximum interface Bandwidth in MB/s
82 uint32_t recommended_transfer_size; ///< recommended transfer size to reach maximum bandwidth
83 ///< in bytes
84 HSA_LINKPROPERTY flags; ///< override flags (may be active for specific platforms)
86
87/**
88 * @brief Memory bank information for an agent.
89 */
91{
92 HSA_HEAPTYPE heap_type;
93 HSA_MEMORYPROPERTY flags;
94 uint32_t width; ///< the number of parallel bits of the memoryinterface
95 uint32_t mem_clk_max; ///< clock for the memory, this allows computing the available
96 ///< bandwidth to the memory when needed
97 uint64_t size_in_bytes; ///< physical memory size of the memory range in bytes
99
100/**
101 * @brief Stores the properties of an agent (CPU, GPU, etc.)
102 *
103 * The `node_id` member is the KFD topology node id. It should be considered the "universal"
104 * indexing number. It is equivalent to the HSA-runtime HSA_AMD_AGENT_INFO_DRIVER_NODE_ID property
105 * of a `hsa_agent_t`. The `const char*` fields (`name`, `vendor_name`, etc.) are guaranteed to be
106 * valid pointers to null-terminated strings during tool finalization. Pointers to the agents via
107 * @see ::rocprofiler_query_available_agents are constant and will not be deallocated until after
108 * tool finalization. Making copies of the agent struct is also valid.
109 */
111{
112 uint64_t size; ///< set to sizeof(rocprofiler_agent_t) by rocprofiler. This can be used for
113 ///< versioning and compatibility handling
114 rocprofiler_agent_id_t id; ///< Internal opaque identifier
115 rocprofiler_agent_type_t type; ///< Enumeration for identifying the agent type (CPU, GPU, etc.)
116 uint32_t cpu_cores_count; ///< # of latency (= CPU) cores present on this HSA node. This value
117 ///< is 0 for a HSA node with no such cores, e.g a "discrete HSA GPU"
118 uint32_t simd_count; ///< # of HSA throughtput (= GPU) FCompute cores ("SIMD") present in a
119 ///< node. This value is 0 if no FCompute cores are present (e.g. pure
120 ///< "CPU node").
121 uint32_t mem_banks_count; ///< # of discoverable memory bank affinity properties on this
122 ///< "H-NUMA" node.
123 uint32_t caches_count; ///< # of discoverable cache affinity properties on this "H-NUMA" node.
124 uint32_t io_links_count; ///< # of discoverable IO link affinity properties of this node
125 ///< connecting to other nodes.
126 uint32_t cpu_core_id_base; ///< low value of the logical processor ID of the latency (= CPU)
127 ///< cores available on this node
128 uint32_t simd_id_base; ///< low value of the logical processor ID of the throughput (= GPU)
129 ///< units available on this node
130 uint32_t max_waves_per_simd; ///< This identifies the max. number of launched waves per SIMD.
131 ///< If NumFComputeCores is 0, this value is ignored.
132 uint32_t lds_size_in_kb; ///< Size of Local Data Store in Kilobytes per SIMD Wavefront
133 uint32_t gds_size_in_kb; ///< Size of Global Data Store in Kilobytes shared across SIMD
134 ///< Wavefronts
135 uint32_t num_gws; ///< Number of GWS barriers
136 uint32_t wave_front_size; ///< Number of SIMD cores per wavefront executed, typically 64, may
137 ///< be 32 or a different value for some HSA based architectures
138 uint32_t num_xcc; ///< Number of XCC
139 uint32_t cu_count; ///< Number of compute units
140 uint32_t array_count; ///< Number of SIMD arrays
141 uint32_t num_shader_banks; ///< Number of Shader Banks or Shader Engines, typical values are 1
142 ///< or 2
143 uint32_t simd_arrays_per_engine; ///< Number of SIMD arrays per engine
144 uint32_t cu_per_simd_array; ///< Number of Compute Units (CU) per SIMD array
145 uint32_t simd_per_cu; ///< Number of SIMD representing a Compute Unit (CU)
146 uint32_t max_slots_scratch_cu; ///< Number of temp. memory ("scratch") wave slots available to
147 ///< access, may be 0 if HW has no restrictions
148 uint32_t gfx_target_version; ///< major_version=((value / 10000) % 100)
149 ///< minor_version=((value / 100) % 100)
150 ///< patch_version=(value % 100)
151 uint16_t vendor_id; ///< GPU vendor id; 0 on latency (= CPU)-only nodes
152 uint16_t device_id; ///< GPU device id; 0 on latency (= CPU)-only nodes
153 uint32_t location_id; ///< GPU BDF (Bus/Device/function number) - identifies the device
154 ///< location in the overall system
155 uint32_t domain; ///< PCI domain of the GPU
156 uint32_t drm_render_minor; ///< DRM render device minor device number
157 uint32_t num_sdma_engines; ///< number of PCIe optimized SDMA engines
158 uint32_t num_sdma_xgmi_engines; ///< number of XGMI optimized SDMA engines
159 uint32_t num_sdma_queues_per_engine; ///< number of SDMA queue per one engine
160 uint32_t num_cp_queues; ///< number of Compute queues
161 uint32_t max_engine_clk_ccompute; ///< maximum engine clocks for CPU, including any boost
162 ///< capabilities
163 uint32_t max_engine_clk_fcompute; ///< GPU only. Maximum engine clocks for GPU, including any
164 ///< boost capabilities
165 HSA_ENGINE_VERSION sdma_fw_version; ///< GPU only
166 HSA_ENGINE_ID
167 fw_version; ///< GPU only. Identifier (rev) of the GPU uEngine or Firmware, may be 0
168 HSA_CAPABILITY capability; ///< GPU only
169 uint32_t cu_per_engine; ///< computed
170 uint32_t max_waves_per_cu; ///< computed
171 uint32_t family_id; ///< Family code
172 uint32_t workgroup_max_size; ///< GPU only. Maximum total number of work-items in a work-group.
173 uint32_t grid_max_size; ///< GPU only. Maximum number of fbarriers per work-group. Must be at
174 ///< least 32.
175 uint64_t local_mem_size; ///< GPU only. Local memory size
176 uint64_t hive_id; ///< XGMI Hive the GPU node belongs to in the system. It is an opaque and
177 ///< static number hash created by the PSP
178 uint64_t gpu_id; ///< GPU only. KFD identifier
179 rocprofiler_dim3_t workgroup_max_dim; ///< GPU only. Maximum number of work-items of each
180 ///< dimension of a work-group.
181 rocprofiler_dim3_t grid_max_dim; ///< GPU only. Maximum number of work-items of each dimension
182 ///< of a grid.
186 const char* name; ///< Name of the agent. Will be identical to product name for CPU
187 const char* vendor_name; ///< Vendor of agent (will be AMD)
188 const char* product_name; ///< Marketing name
189 const char* model_name; ///< GPU only. Will be something like vega20, mi200, etc.
190 uint32_t node_id; ///< Node sequence number. This will be equivalent to the HSA-runtime
191 ///< HSA_AMD_AGENT_INFO_DRIVER_NODE_ID property
192 int32_t logical_node_id; ///< Logical sequence number. This will always be [0..N) where N is
193 ///< the total number of agents
195 int32_t reserved_padding0; ///< padding logical_node_id to 64 bytes
196
197 /// @var logical_node_type_id
198 /// @brief Logical sequence number with respect to other agents of same type. This will always
199 /// be [0..N) where N is the total number of X agents (where X is a ::rocprofiler_agent_type_t
200 /// value). This field is intended to help with environment variable indexing used to mask GPUs
201 /// at runtime (i.e. HIP_VISIBLE_DEVICES and ROCR_VISIBLE_DEVICES) which start at zero and only
202 /// apply to GPUs, e.g., logical_node_type_id value for first GPU will be 0, second GPU will
203 /// have value of 1, etc., regardless of however many agents of a different type preceeded (and
204 /// thus increased the ::node_id or ::logical_node_id).
205 ///
206 /// Example: a system with 2 CPUs and 2 GPUs, where the node ids are 0=CPU, 1=GPU, 2=CPU, 3=GPU,
207 /// then then CPU node_ids 0 and 2 would have logical_node_type_id values of 0 and 1,
208 /// respectively, and GPU node_ids 1 and 3 would also have logical_node_type_id values of 0
209 /// and 1.
211
213
214/**
215 * @brief Callback function type for querying the available agents.
216 *
217 * If callback is invoked, returns the ::rocprofiler_status_t value returned from callback
218 *
219 * @param [in] version Enum specifying the version of agent info
220 * @param [in] agents Array of pointers to agents
221 * @param [in] num_agents Number of agents in array
222 * @param [in] user_data Data pointer passback
223 * @return ::rocprofiler_status_t
224 * @retval ::ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI size of the agent struct in application is
225 * larger than the agent struct for rocprofiler-sdk
226 * @retval ::ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT Invalid ::rocprofiler_agent_version_t value
227 */
230 const void** agents,
231 size_t num_agents,
232 void* user_data);
233
234/**
235 * @brief Receive synchronous callback with an array of available agents at moment of invocation
236 *
237 * @param [in] version Enum value specifying the struct type of the agent info
238 * @param [in] callback Callback function accepting list of agents
239 * @param [in] agent_size Should be set to sizeof(rocprofiler_agent_t)
240 * @param [in] user_data Data pointer provided to callback
241 * @return ::rocprofiler_status_t
242 */
246 size_t agent_size,
247 void* user_data) ROCPROFILER_API ROCPROFILER_NONNULL(2);
248
249/** @} */
250
251ROCPROFILER_EXTERN_C_FINI
uint32_t simd_arrays_per_engine
Number of SIMD arrays per engine.
Definition agent.h:143
const rocprofiler_agent_io_link_t * io_links
Definition agent.h:185
uint64_t size
Size of the cache.
Definition agent.h:58
uint32_t node_id
Node sequence number. This will be equivalent to the HSA-runtime HSA_AMD_AGENT_INFO_DRIVER_NODE_ID pr...
Definition agent.h:190
uint32_t num_shader_banks
Number of Shader Banks or Shader Engines, typical values are 1 or 2.
Definition agent.h:141
uint32_t simd_count
Definition agent.h:118
uint16_t vendor_id
GPU vendor id; 0 on latency (= CPU)-only nodes.
Definition agent.h:151
int32_t logical_node_type_id
Logical sequence number with respect to other agents of same type. This will always be [0....
Definition agent.h:194
uint64_t size_in_bytes
physical memory size of the memory range in bytes
Definition agent.h:97
int32_t logical_node_id
Logical sequence number. This will always be [0..N) where N is the total number of agents.
Definition agent.h:192
const char * product_name
Marketing name.
Definition agent.h:188
uint32_t min_bandwidth
minimum interface Bandwidth in MB/s
Definition agent.h:80
uint32_t max_latency
maximum cost of time to transfer (rounded to ns)
Definition agent.h:79
uint32_t workgroup_max_size
GPU only. Maximum total number of work-items in a work-group.
Definition agent.h:172
uint32_t association
Cache Associativity.
Definition agent.h:62
uint32_t grid_max_size
GPU only. Maximum number of fbarriers per work-group. Must be at least 32.
Definition agent.h:173
uint32_t cu_per_simd_array
Number of Compute Units (CU) per SIMD array.
Definition agent.h:144
uint64_t gpu_id
GPU only. KFD identifier.
Definition agent.h:178
uint32_t recommended_transfer_size
recommended transfer size to reach maximum bandwidth in bytes
Definition agent.h:82
uint32_t cache_line_size
Cache line size in bytes.
Definition agent.h:60
uint32_t location_id
GPU BDF (Bus/Device/function number) - identifies the device location in the overall system.
Definition agent.h:153
uint32_t num_sdma_xgmi_engines
number of XGMI optimized SDMA engines
Definition agent.h:158
rocprofiler_agent_id_t id
Internal opaque identifier.
Definition agent.h:114
uint32_t mem_banks_count
Definition agent.h:121
const char * name
Name of the agent. Will be identical to product name for CPU.
Definition agent.h:186
uint32_t cu_per_engine
computed
Definition agent.h:169
uint32_t node_from
See rocprofiler_agent_id_t.
Definition agent.h:75
uint32_t array_count
Number of SIMD arrays.
Definition agent.h:140
HSA_CAPABILITY capability
GPU only.
Definition agent.h:168
HsaCacheType type
Definition agent.h:64
uint32_t weight
weight factor (derived from CDIT)
Definition agent.h:77
HSA_ENGINE_ID fw_version
GPU only. Identifier (rev) of the GPU uEngine or Firmware, may be 0.
Definition agent.h:167
HSA_IOLINKTYPE type
Discoverable IoLink Properties (optional)
Definition agent.h:72
uint32_t num_xcc
Number of XCC.
Definition agent.h:138
uint32_t gfx_target_version
major_version=((value / 10000) % 100) minor_version=((value / 100) % 100) patch_version=(value % 100)
Definition agent.h:148
uint32_t max_engine_clk_ccompute
maximum engine clocks for CPU, including any boost capabilities
Definition agent.h:161
uint32_t caches_count
Definition agent.h:123
uint32_t max_slots_scratch_cu
Number of temp. memory ("scratch") wave slots available to access, may be 0 if HW has no restrictions...
Definition agent.h:146
uint32_t family_id
Family code.
Definition agent.h:171
rocprofiler_dim3_t grid_max_dim
GPU only. Maximum number of work-items of each dimension of a grid.
Definition agent.h:181
uint32_t lds_size_in_kb
Size of Local Data Store in Kilobytes per SIMD Wavefront.
Definition agent.h:132
uint32_t min_latency
minimum cost of time to transfer (rounded to ns)
Definition agent.h:78
uint32_t gds_size_in_kb
Size of Global Data Store in Kilobytes shared across SIMD Wavefronts.
Definition agent.h:133
int32_t reserved_padding0
padding logical_node_id to 64 bytes
Definition agent.h:195
uint32_t width
the number of parallel bits of the memoryinterface
Definition agent.h:94
uint32_t cpu_core_id_base
low value of the logical processor ID of the latency (= CPU) cores available on this node
Definition agent.h:126
uint32_t cu_count
Number of compute units.
Definition agent.h:139
uint32_t num_gws
Number of GWS barriers.
Definition agent.h:135
HSA_HEAPTYPE heap_type
Definition agent.h:92
HSA_LINKPROPERTY flags
override flags (may be active for specific platforms)
Definition agent.h:84
uint32_t domain
PCI domain of the GPU.
Definition agent.h:155
uint32_t num_sdma_queues_per_engine
number of SDMA queue per one engine
Definition agent.h:159
uint32_t num_cp_queues
number of Compute queues
Definition agent.h:160
uint32_t mem_clk_max
clock for the memory, this allows computing the available bandwidth to the memory when needed
Definition agent.h:95
uint64_t processor_id_low
Identifies the processor number.
Definition agent.h:57
uint32_t cpu_cores_count
Definition agent.h:116
uint32_t max_engine_clk_fcompute
GPU only. Maximum engine clocks for GPU, including any boost capabilities.
Definition agent.h:163
uint32_t num_sdma_engines
number of PCIe optimized SDMA engines
Definition agent.h:157
const rocprofiler_agent_mem_bank_t * mem_banks
Definition agent.h:183
uint32_t drm_render_minor
DRM render device minor device number.
Definition agent.h:156
uint32_t simd_id_base
low value of the logical processor ID of the throughput (= GPU) units available on this node
Definition agent.h:128
uint16_t device_id
GPU device id; 0 on latency (= CPU)-only nodes.
Definition agent.h:152
const char * vendor_name
Vendor of agent (will be AMD)
Definition agent.h:187
uint32_t max_waves_per_simd
This identifies the max. number of launched waves per SIMD. If NumFComputeCores is 0,...
Definition agent.h:130
uint64_t hive_id
XGMI Hive the GPU node belongs to in the system. It is an opaque and static number hash created by th...
Definition agent.h:176
HSA_MEMORYPROPERTY flags
Definition agent.h:93
rocprofiler_dim3_t workgroup_max_dim
GPU only. Maximum number of work-items of each dimension of a work-group.
Definition agent.h:179
uint32_t node_to
See rocprofiler_agent_id_t.
Definition agent.h:76
const char * model_name
GPU only. Will be something like vega20, mi200, etc.
Definition agent.h:189
uint32_t version_major
Bus interface version (optional)
Definition agent.h:73
uint32_t cache_lines_per_tag
Cache lines per Cache Tag.
Definition agent.h:61
uint32_t latency
Cache latency in ns.
Definition agent.h:63
uint32_t simd_per_cu
Number of SIMD representing a Compute Unit (CU)
Definition agent.h:145
uint32_t wave_front_size
Number of SIMD cores per wavefront executed, typically 64, may be 32 or a different value for some HS...
Definition agent.h:136
rocprofiler_agent_type_t type
Enumeration for identifying the agent type (CPU, GPU, etc.)
Definition agent.h:115
uint64_t size
set to sizeof(rocprofiler_agent_t) by rocprofiler. This can be used for versioning and compatibility ...
Definition agent.h:112
uint32_t level
Integer representing level: 1, 2, 3, 4, etc.
Definition agent.h:59
uint32_t version_minor
Bus interface version (optional)
Definition agent.h:74
uint32_t io_links_count
Definition agent.h:124
uint32_t max_waves_per_cu
computed
Definition agent.h:170
HSA_ENGINE_VERSION sdma_fw_version
GPU only.
Definition agent.h:165
uint64_t local_mem_size
GPU only. Local memory size.
Definition agent.h:175
const rocprofiler_agent_cache_t * caches
Definition agent.h:184
uint32_t max_bandwidth
maximum interface Bandwidth in MB/s
Definition agent.h:81
rocprofiler_agent_version_t
Enumeration ID for version of the rocprofiler_agent_v*_t struct in rocprofiler_i.
Definition agent.h:46
rocprofiler_status_t(* rocprofiler_query_available_agents_cb_t)(rocprofiler_agent_version_t version, const void **agents, unsigned long num_agents, void *user_data)
Callback function type for querying the available agents.
Definition agent.h:228
rocprofiler_status_t rocprofiler_query_available_agents(rocprofiler_agent_version_t version, rocprofiler_query_available_agents_cb_t callback, unsigned long agent_size, void *user_data)
Receive synchronous callback with an array of available agents at moment of invocation.
rocprofiler_agent_v0_t rocprofiler_agent_t
Definition agent.h:212
@ ROCPROFILER_AGENT_INFO_VERSION_NONE
Definition agent.h:47
@ ROCPROFILER_AGENT_INFO_VERSION_0
Definition agent.h:48
@ ROCPROFILER_AGENT_INFO_VERSION_LAST
Definition agent.h:49
Cache information for an agent.
Definition agent.h:56
Memory bank information for an agent.
Definition agent.h:91
Stores the properties of an agent (CPU, GPU, etc.)
Definition agent.h:111
rocprofiler_status_t
Status codes.
Definition fwd.h:55
rocprofiler_agent_type_t
Agent type.
Definition fwd.h:129
Agent Identifier.
Definition fwd.h:541
Multi-dimensional struct of data used to describe GPU workgroup and grid sizes.
Definition fwd.h:566