Skip to content

Commit 99231c7

Browse files
SrirakshaNagSrirakshaNag
committed
Add SPM experimental public API header
1 parent 39a9025 commit 99231c7

File tree

3 files changed

+274
-45
lines changed

3 files changed

+274
-45
lines changed

‎projects/rocprofiler-sdk/source/include/rocprofiler-sdk/experimental/CMakeLists.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
# Experimental components of the ROCProfiler SDK API.
33
#
44

5-
set(ROCPROFILER_EXPERIMENTAL_HEADER_FILES counters.h registration.h thread_trace.h)
5+
set(ROCPROFILER_EXPERIMENTAL_HEADER_FILES counters.h registration.h thread_trace.h spm.h)
66

77
install(
88
FILES ${ROCPROFILER_EXPERIMENTAL_HEADER_FILES}

‎projects/rocprofiler-sdk/source/include/rocprofiler-sdk/experimental/spm.h‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
// MIT License
2+
//
3+
// Copyright (c) 2025 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+
25+
#include <rocprofiler-sdk/agent.h>
26+
#include <rocprofiler-sdk/counters.h>
27+
#include <rocprofiler-sdk/defines.h>
28+
#include <rocprofiler-sdk/fwd.h>
29+
30+
ROCPROFILER_EXTERN_C_INIT
31+
32+
/**
33+
* @brief (experimental) SPM parameter type and value.
34+
*
35+
**/
36+
typedef struct ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_spm_configuration_t
37+
{
38+
size_t size; ///< Size of this struct
39+
double frequency; ///< Input frequency (in GHz) is estimated to number of scclock count. Used
40+
///< to determine sample interval.
41+
uint64_t buffer_size; ///< Buffer size of user mode buffer in KB
42+
uint64_t timeout; ///< Timeout for the user mode buffer in ms
43+
} rocprofiler_spm_configuration_t;
44+
45+
/**
46+
* @brief (experimental) Create SPM Counter Configuration. A config is bound to an agent but can
47+
* be used across many contexts. The config has a fixed set of counters
48+
* that are collected (and specified by counter_list) and parameters. The available
49+
* counters for an agent can be queried using
50+
* ::rocprofiler_iterate_spm_supported_counters. An existing config
51+
* may be supplied via config_id to use as a base for the new config.
52+
* All counters and parameters in the existing config will be copied over to the new
53+
* config. The existing config will remain unmodified and usable with
54+
* the new config id being returned in config_id.
55+
*
56+
* @param [in] agent_id Agent identifier
57+
* @param [in] counters_list List of GPU counters
58+
* @param [in] counters_count Size of counters list
59+
* @param [in] parameters SPM parameter configuration
60+
* @param [in,out] config_id Identifier for GPU SPM counters group. If an existing
61+
config is supplied, that profiles counters and parameters will be copied
62+
over to a new config (returned via this id)
63+
* @return ::rocprofiler_status_t
64+
* @retval ROCPROFILER_STATUS_SUCCESS if config created
65+
* @retval ROCPROFILER_STATUS_ERROR if config could not be created
66+
* @retval ROCPROFILER_STATUS_ERROR_METRIC_NOT_VALID_FOR_AGENT if agent does not support an input
67+
counter
68+
* @retval ROCPROFILER_STATUS_ERROR_INVALID_ARGUMENT if counters count is zero and no existing
69+
config is supplied
70+
* @retval ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI incompatible aqlprofile version is used
71+
* @retval ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED if the ROCPROFILER_SPM_BETA_ENABLED is not set
72+
* @retval ROCPROFILER_STATUS_ERROR_EXCEEDS_HW_LIMIT if input counters exceed the hardware limit
73+
* @retval ROCPROFILER_STATUS_ERROR_AGENT_NOT_FOUND if agent not found
74+
* @retval ROCPROFILER_STATUS_ERROR_COUNTER_NOT_FOUND if an input counter is not found in metrics
75+
file
76+
*/
77+
ROCPROFILER_SDK_EXPERIMENTAL
78+
rocprofiler_status_t
79+
rocprofiler_spm_create_counter_config(rocprofiler_agent_id_t agent_id,
80+
rocprofiler_counter_id_t* counters_list,
81+
size_t counters_count,
82+
rocprofiler_spm_configuration_t* parameters,
83+
rocprofiler_counter_config_id_t* config_id)
84+
ROCPROFILER_API ROCPROFILER_NONNULL(2);
85+
86+
/**
87+
* @brief (experimental) Destroy SPM Profile Configuration.
88+
*
89+
* @param [in] config_id
90+
* @return ::rocprofiler_status_t
91+
* @retval ROCPROFILER_STATUS_SUCCESS if config destroyed
92+
* @retval ROCPROFILER_STATUS_ERROR_PROFILE_NOT_FOUND if the profile is not found
93+
* @retval ROCPROFILER_STATUS_ERROR if config could not be destroyed
94+
*/
95+
ROCPROFILER_SDK_EXPERIMENTAL
96+
rocprofiler_status_t
97+
rocprofiler_spm_destroy_counter_config(rocprofiler_counter_config_id_t config_id)
98+
ROCPROFILER_API;
99+
100+
/**
101+
* @brief (experimental) SPM record flags.
102+
*
103+
**/
104+
typedef enum ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_spm_record_flag_t
105+
{
106+
ROCPROFILER_SPM_RECORD_FLAG_DATA_NONE = 0, ///< records with data loss
107+
ROCPROFILER_SPM_RECORD_FLAG_DATA, ///< records with data
108+
ROCPROFILER_SPM_RECORD_FLAG_END, ///< End of agent service
109+
ROCPROFILER_SPM_RECORD_FLAG_DATA_LOST, ///< flag value none
110+
ROCPROFILER_SPM_RECORD_FLAG_LAST,
111+
} rocprofiler_spm_record_flag_t;
112+
113+
/**
114+
* @brief (experimental) Kernel dispatch data for profile counting callbacks.
115+
*
116+
*/
117+
typedef struct ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_spm_dispatch_counting_service_data_t
118+
{
119+
uint64_t size; ///< Size of this struct
120+
rocprofiler_async_correlation_id_t correlation_id; ///< Correlation ID for this dispatch
121+
rocprofiler_kernel_dispatch_info_t dispatch_info; ///< Dispatch info
122+
} rocprofiler_spm_dispatch_counting_service_data_t;
123+
124+
typedef struct ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_spm_counter_record_t
125+
{
126+
uint64_t size; ///< Size of this structure. Used for versioning and validation.
127+
rocprofiler_dispatch_id_t
128+
dispatch_id; ///< dispatch id used to determine the dispatch this record belongs to.
129+
rocprofiler_counter_instance_id_t id; ///< Counter instance id
130+
rocprofiler_agent_id_t agent_id; ///< Agent on which the record is collected
131+
rocprofiler_timestamp_t timestamp; ///< timestamp of the sample
132+
uint64_t value; ///< SPM sample for the counter with counter instance id: id
133+
/// @var id
134+
/// @brief counter id, ROCPROFILER_DIMENSION_XCC,
135+
/// ROCPROFILER_DIMENSION_INSTANCE, ROCPROFILER_DIMENSION_SHADER_ENGINE embedded in it
136+
/// @var agent id
137+
/// @brief identifies the agent on which SPM data was collected
138+
/// @var timestamp
139+
/// @brief GPU timestamp when sample was collected
140+
/// @var value
141+
/// @brief sampled counter value
142+
/// @var dispatch_id
143+
/// @brief A value greater than zero indicates that this counter record is associated with a
144+
/// specific dispatch.
145+
///
146+
/// This value can be mapped to a dispatch via the `dispatch_info` field (@see
147+
/// ::rocprofiler_kernel_dispatch_info_t) of a ::rocprofiler_spm_dispatch_counting_service_data_t
148+
/// ::rocprofiler_spm_dispatch_counting_service_record_t records (which will be insert into the
149+
/// buffer prior to the associated ::rocprofiler_spm_counter_record_t records).
150+
} rocprofiler_spm_counter_record_t;
151+
152+
/**
153+
* @brief (experimental) Counting record callback. This is a callback is invoked when the kernel
154+
* execution is complete and contains the counter profile data requested in
155+
* ::rocprofiler_spm_dispatch_counting_service_cb_t. Only used with
156+
* ::rocprofiler_configure_callback_spm_dispatch_service
157+
*
158+
* @param [in] dispatch_data kernel dispatch data
159+
* @param [in] records array of pointers to the rocprofiler_spm_counter_record_t.
160+
Memory of records is managed by the SDK. It is valid only within this callback
161+
* @param [in] record_count size of the record array
162+
* @param [in] flags rocprofiler_spm_record_flag_t
163+
* @param [in] userdata user data supplied by dispatch callback
164+
* @param [in] record Callback data supplied via dispatch configure service
165+
166+
*/
167+
ROCPROFILER_SDK_EXPERIMENTAL
168+
typedef void (*rocprofiler_spm_dispatch_counting_record_cb_t)(
169+
const rocprofiler_spm_dispatch_counting_service_data_t* dispatch_data,
170+
const rocprofiler_spm_counter_record_t** records,
171+
size_t record_count,
172+
int flags,
173+
rocprofiler_user_data_t userdata,
174+
void* record_callback_args);
175+
/**
176+
* @brief (experimental) Kernel Dispatch Callback. This is a callback that is invoked before the
177+
* kernel is enqueued into the HSA queue. What counters to collect for a kernel are set via passing
178+
* back a profile config (config) in this callback. These counters will be collected and emplaced in
179+
* the buffer with ::rocprofiler_buffer_id_t used when setting up this callback or will be returned via
180+
* a callback used when setting up this callback
181+
*
182+
* @param [in] dispatch_data kernel dispatch data
183+
* @param [out] config spm counter config
184+
* @param [out] user_data User data unique to this dispatch. Returned in record callback
185+
* @param [in] callback_data_args Callback supplied via dispatch configure service
186+
*/
187+
ROCPROFILER_SDK_EXPERIMENTAL
188+
typedef void (*rocprofiler_spm_dispatch_counting_service_cb_t)(
189+
const rocprofiler_spm_dispatch_counting_service_data_t* dispatch_data,
190+
rocprofiler_counter_config_id_t* config,
191+
rocprofiler_user_data_t* user_data,
192+
void* callback_data_args);
193+
194+
/**
195+
* @brief (experimental) Query Agent SPM Counters Availability.
196+
*
197+
* @param [in] agent_id GPU agent identifier
198+
* @param [in] cb callback to caller to get counters
199+
* @param [in] user_data data to pass into the callback
200+
* @return ::rocprofiler_status_t
201+
* @retval ROCPROFILER_STATUS_SUCCESS if all counters found for agent
202+
* @retval ROCPROFILER_STATUS_ERROR_AGENT_NOT_FOUND invalid agent
203+
* @retval ROCPROFILER_STATUS_ERROR_AGENT_ARCH_NOT_SUPPORTED agent has no supported SPM counter
204+
*/
205+
ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_status_t
206+
rocprofiler_iterate_spm_supported_counters(rocprofiler_agent_id_t agent_id,
207+
rocprofiler_available_counters_cb_t cb,
208+
void* user_data) ROCPROFILER_API ROCPROFILER_NONNULL(2);
209+
210+
/**
211+
* @brief (experimental) Configure callback dispatch profile Counting Service.
212+
* Collects the counters in dispatch packets and calls a callback
213+
* with the counters collected during that dispatch.
214+
*
215+
* @param [in] context_id context id
216+
* @param [in] dispatch_callback callback to perform when dispatch is enqueued
217+
* @param [in] dispatch_callback_args callback data for dispatch callback
218+
* @param [in] record_callback Record callback for completed profile data
219+
* @param [in] record_callback_args Callback args for record callback
220+
* @return ::rocprofiler_status_t
221+
*
222+
* @return ::rocprofiler_status_t
223+
* @retval ROCPROFILER_STATUS_SUCCESS if the context can be configured for SPM dispatch service
224+
* @retval ROCPROFILER_STATUS_ERROR if the context cannot be configured for SPM dispatch service
225+
* @retval ROCPROFILER_STATUS_ERROR_NOT_IMPLEMENTED if the ROCPROFILER_SPM_BETA_ENABLED is not set
226+
* @retval ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED for configuration locked
227+
* @retval ROCPROFILER_STATUS_ERROR_INCOMPATIBLE_ABI incompatible aqlprofile version is used
228+
* @retval ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID invalid input context has not already been
229+
* created
230+
* @retval ROCPROFILER_STATUS_ERROR_CONTEXT_CONFLICT conflicting services being enabled in the
231+
* context
232+
*/
233+
234+
ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_status_t
235+
rocprofiler_configure_callback_spm_dispatch_service(
236+
rocprofiler_context_id_t context_id,
237+
rocprofiler_spm_dispatch_counting_service_cb_t dispatch_callback,
238+
void* dispatch_callback_args,
239+
rocprofiler_spm_dispatch_counting_record_cb_t record_callback,
240+
void* record_callback_args) ROCPROFILER_API ROCPROFILER_NONNULL(2, 4);
241+
;
242+
243+
/**
244+
* @brief (experimental) Configure buffered dispatch spm service.
245+
* Collects the counters in dispatch packets and stores them
246+
* in a buffer with @p buffer_id. The buffer may contain packets from more than
247+
* one dispatch (denoted by correlation id). Will trigger the
248+
* callback based on the parameters setup in buffer_id_t.
249+
*
250+
* @param [in] context_id context id
251+
* @param [in] buffer_id id of the buffer to use for the counting service
252+
* @param [in] callback callback to perform when dispatch is enqueued
253+
* @param [in] callback_data_args callback data
254+
* @return ::rocprofiler_status_t
255+
* @retval ROCPROFILER_STATUS_ERROR_BUFFER_NOT_FOUND
256+
* @retval ROCPROFILER_STATUS_ERROR_CONTEXT_INVALID invalid input context has not already been
257+
* @retval ROCPROFILER_STATUS_ERROR_AGENT_DISPATCH_CONFLICT
258+
* @retval ROCPROFILER_STATUS_SUCCESS if the context can be configured for SPM buffer dispatch
259+
* service
260+
*/
261+
262+
rocprofiler_status_t
263+
rocprofiler_configure_buffer_spm_dispatch_service(
264+
rocprofiler_context_id_t context_id,
265+
rocprofiler_buffer_id_t buffer_id,
266+
rocprofiler_spm_dispatch_counting_service_cb_t callback,
267+
void* callback_data_args) ROCPROFILER_API ROCPROFILER_NONNULL(3);
268+
269+
ROCPROFILER_EXTERN_C_FINI

‎projects/rocprofiler-sdk/source/include/rocprofiler-sdk/spm.h‎

Lines changed: 4 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -22,48 +22,8 @@
2222

2323
#pragma once
2424

25-
#include <rocprofiler-sdk/defines.h>
26-
#include <rocprofiler-sdk/fwd.h>
25+
#if defined(ROCPROFILER_SDK_EXPERIMENTAL_WARNINGS)
26+
# warning "rocprofiler-sdk/experimental/spm.h should be included for now"
27+
#endif
2728

28-
ROCPROFILER_EXTERN_C_INIT
29-
30-
/**
31-
* @defgroup SPM_SERVICE SPM Service
32-
* @brief Streaming Performance Monitoring
33-
*
34-
* @{
35-
*/
36-
37-
/**
38-
* @brief (experimental) ROCProfiler SPM Record.
39-
*
40-
*/
41-
typedef struct ROCPROFILER_SDK_EXPERIMENTAL rocprofiler_spm_record_t
42-
{
43-
/**
44-
* Counters, including identifiers to get counter information and Counters
45-
* values
46-
*/
47-
rocprofiler_counter_record_t* counters;
48-
uint64_t counters_count;
49-
} rocprofiler_spm_record_t;
50-
51-
/**
52-
* @brief Configure SPM Service.
53-
*
54-
* @param [in] context_id
55-
* @param [in] buffer_id
56-
* @param [in] counter_config
57-
* @param [in] interval
58-
* @return ::rocprofiler_status_t
59-
*/
60-
ROCPROFILER_SDK_EXPERIMENTAL
61-
rocprofiler_status_t
62-
rocprofiler_configure_spm_service(rocprofiler_context_id_t context_id,
63-
rocprofiler_buffer_id_t buffer_id,
64-
rocprofiler_counter_config_id_t counter_config,
65-
uint64_t interval) ROCPROFILER_API;
66-
67-
/** @} */
68-
69-
ROCPROFILER_EXTERN_C_FINI
29+
#include <rocprofiler-sdk/experimental/spm.h>

0 commit comments

Comments
 (0)