Skip to content

Commit c2ab2ff

Browse files
SrirakshaNagSrirakshaNag
committed
Add SPM experimental public API header
1 parent ff122e7 commit c2ab2ff

File tree

3 files changed

+261
-45
lines changed

3 files changed

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