rocprofiler-sdk/registration.h Source File

rocprofiler-sdk/registration.h Source File#

Rocprofiler SDK Developer API: rocprofiler-sdk/registration.h Source File
Rocprofiler SDK Developer API 0.5.0
ROCm Profiling API and tools
registration.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
28ROCPROFILER_EXTERN_C_INIT
29
30/**
31 * @defgroup REGISTRATION_GROUP Tool registration
32 *
33 * Data types and functions for tool registration with rocprofiler
34 * @{
35 */
36
37/**
38 * @brief A client refers to an individual or entity engaged in the configuration of ROCprofiler
39 * services. e.g: any third party tool like PAPI or any internal tool (Omnitrace). A pointer to this
40 * data structure is provided to the client tool initialization function. The name member can be set
41 * by the client to assist with debugging (e.g. rocprofiler cannot start your context because there
42 * is a conflicting context started by `<name>` -- at least that is the plan). The handle member is
43 * a unique identifer assigned by rocprofiler for the client and the client can store it and pass it
44 * to the @ref rocprofiler_client_finalize_t function to force finalization (i.e. deactivate all of
45 * it's contexts) for the client.
46 */
48{
49 const char* name; ///< clients should set this value for debugging
50 const uint32_t handle; ///< internal handle
52
53/**
54 * @brief Prototype for the function pointer provided to tool in ::rocprofiler_tool_initialize_t.
55 * This function can be used to explicitly invoke the client tools ::rocprofiler_tool_finalize_t
56 * finalization function prior to the `atexit` handler which calls it.
57 *
58 * If this function pointer is invoked explicitly, rocprofiler will disable calling the
59 * ::rocprofiler_tool_finalize_t functioin pointer during it's `atexit` handler.
60 */
62
63/**
64 * @brief Prototype for the initialize function where a tool creates contexts for the set of
65 * rocprofiler services used by the tool.
66 * @param [in] finalize_func Function pointer to explicitly invoke the finalize function for the
67 * client
68 * @param [in] tool_data `tool_data` field returned from ::rocprofiler_configure in
69 * ::rocprofiler_tool_configure_result_t.
70 */
72 void* tool_data);
73
74/**
75 * @brief Prototype for the finalize function where a tool does any cleanup or output operations
76 * once it has finished using rocprofiler services.
77 * @param [in] tool_data `tool_data` field returned from ::rocprofiler_configure in
78 * ::rocprofiler_tool_configure_result_t.
79 */
80typedef void (*rocprofiler_tool_finalize_t)(void* tool_data);
81
82/**
83 * @brief Data structure containing a initialization, finalization, and data.
84 *
85 * After rocprofiler has retrieved all instances of ::rocprofiler_tool_configure_result_t from the
86 tools -- via either ::rocprofiler_configure and/or ::rocprofiler_force_configure,
87 * rocprofiler will invoke all non-null `initialize` functions and provide the user a function
88 pointer which will explicitly invoke
89 * the `finalize` function pointer. Both the `initialize` and `finalize` functions will be passed
90 the value of the `tool_data` field.
91 * The `size` field is used for ABI reasons, in the event that rocprofiler changes the
92 ::rocprofiler_tool_configure_result_t struct
93 * and it should be set to `sizeof(rocprofiler_tool_configure_result_t)`
94 */
96{
97 size_t size; ///< size of this struct (in case of future extensions)
100 void* tool_data; ///< data to provide to init and fini callbacks
102
103/**
104 * @brief Query whether rocprofiler has already scanned the binary for all the instances of @ref
105 * rocprofiler_configure (or is currently scanning). If rocprofiler has completed it's scan, clients
106 * can directly register themselves with rocprofiler.
107 *
108 * @param [out] status 0 indicates rocprofiler has not been initialized (i.e. configured), 1
109 * indicates rocprofiler has been initialized, -1 indicates rocprofiler is currently initializing.
110 * @return ::rocprofiler_status_t
111 * @retval ::ROCPROFILER_STATUS_SUCCESS Returned unconditionally
112 */
114rocprofiler_is_initialized(int* status) ROCPROFILER_API ROCPROFILER_NONNULL(1);
115
116/**
117 * @brief Query rocprofiler finalization status.
118 *
119 * @param [out] status 0 indicates rocprofiler has not been finalized, 1 indicates rocprofiler has
120 * been finalized, -1 indicates rocprofiler is currently finalizing.
121 * @return ::rocprofiler_status_t
122 * @retval ::ROCPROFILER_STATUS_SUCCESS Returned unconditionally
123 */
125rocprofiler_is_finalized(int* status) ROCPROFILER_API ROCPROFILER_NONNULL(1);
126
127/**
128 * @brief This is the special function that tools define to enable rocprofiler support. The tool
129 * should return a pointer to
130 * @ref rocprofiler_tool_configure_result_t which will contain a function pointer to (1) an
131 * initialization function where all the contexts are created, (2) a finalization function (if
132 * necessary) which will be invoked when rocprofiler shutdown and, (3) a pointer to any data that
133 * the tool wants communicated between the @ref rocprofiler_tool_configure_result_t::initialize and
134 * @ref rocprofiler_tool_configure_result_t::finalize functions. If the user
135 *
136 * @param [in] version The version of rocprofiler: `(10000 * major) + (100 * minor) + patch`
137 * @param [in] runtime_version String descriptor of the rocprofiler version and other relevant info.
138 * @param [in] priority How many client tools were initialized before this client tool
139 * @param [in, out] client_id tool identifier value.
140 * @return rocprofiler_tool_configure_result_t*
141 *
142 * @code{.cpp}
143 * #include <rocprofiler-sdk/registration.h>
144 *
145 * static rocprofiler_client_id_t my_client_id;
146 * static rocprofiler_client_finalize_t my_fini_func;
147 * static int my_tool_data = 1234;
148 *
149 * static int my_init_func(rocprofiler_client_finalize_t fini_func,
150 * void* tool_data)
151 * {
152 * my_fini_func = fini_func;
153 *
154 * assert(*static_cast<int*>(tool_data) == 1234 && "tool_data is wrong");
155 *
156 * rocprofiler_context_id_t ctx;
157 * rocprofiler_create_context(&ctx);
158 *
159 * if(int valid_ctx = 0;
160 * rocprofiler_context_is_valid(ctx, &valid_ctx) != ROCPROFILER_STATUS_SUCCESS ||
161 * valid_ctx != 0)
162 * {
163 * // notify rocprofiler that initialization failed
164 * // and all the contexts, buffers, etc. created
165 * // should be ignored
166 * return -1;
167 * }
168 *
169 * if(rocprofiler_start_context(ctx) != ROCPROFILER_STATUS_SUCCESS)
170 * {
171 * // notify rocprofiler that initialization failed
172 * // and all the contexts, buffers, etc. created
173 * // should be ignored
174 * return -1;
175 * }
176 *
177 * // no errors
178 * return 0;
179 * }
180 *
181 * static int my_fini_func(void* tool_data)
182 * {
183 * assert(*static_cast<int*>(tool_data) == 1234 && "tool_data is wrong");
184 * }
185 *
186 * rocprofiler_tool_configure_result_t*
187 * rocprofiler_configure(uint32_t version,
188 * const char* runtime_version,
189 * uint32_t priority,
190 * rocprofiler_client_id_t* client_id)
191 * {
192 * // only activate if main tool
193 * if(priority > 0) return nullptr;
194 *
195 * // set the client name
196 * client_id->name = "ExampleTool";
197 *
198 * // make a copy of client info
199 * my_client_id = *client_id;
200 *
201 * // compute major/minor/patch version info
202 * uint32_t major = version / 10000;
203 * uint32_t minor = (version % 10000) / 100;
204 * uint32_t patch = version % 100;
205 *
206 * // print info
207 * printf("Configuring %s with rocprofiler-sdk (v%u.%u.%u) [%s]\n",
208 * client_id->name, major, minor, patch, runtime_version);
209 *
210 * // create configure data
211 * static auto cfg = rocprofiler_tool_configure_result_t{ &my_init_func,
212 * &my_fini_func,
213 * &my_tool_data };
214 *
215 * // return pointer to configure data
216 * return &cfg;
217 * }
218 * @endcode
219 */
221rocprofiler_configure(uint32_t version,
222 const char* runtime_version,
223 uint32_t priority,
224 rocprofiler_client_id_t* client_id) ROCPROFILER_PUBLIC_API;
225
226// NOTE: we use ROCPROFILER_PUBLIC_API above instead of ROCPROFILER_API because we always
227// want the symbol to be visible when the user includes the header for the prototype
228
229/**
230 * @brief Function pointer typedef for @ref rocprofiler_configure function
231 * @param [in] version The version of rocprofiler: `(10000 * major) + (100 * minor) + patch`
232 * @param [in] runtime_version String descriptor of the rocprofiler version and other relevant info.
233 * @param [in] priority How many client tools were initialized before this client tool
234 * @param [in, out] client_id tool identifier value.
235 */
236typedef rocprofiler_tool_configure_result_t* (*rocprofiler_configure_func_t)(
237 uint32_t version,
238 const char* runtime_version,
239 uint32_t priority,
240 rocprofiler_client_id_t* client_id);
241
242/**
243 * @brief Function for explicitly registering a configuration with rocprofiler. This can be invoked
244 * before any ROCm runtimes (lazily) initialize and context(s) can be started before the runtimes
245 * initialize.
246 * @param [in] configure_func Address of @ref rocprofiler_configure function. A null pointer is
247 * acceptable if the address is not known
248 * @return ::rocprofiler_status_t
249 * @retval ::ROCPROFILER_STATUS_SUCCESS Registration was successfully triggered.
250 * @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED Returned if rocprofiler has already been
251 * configured, or is currently being configured
252 */
255
256/** @} */
257
258ROCPROFILER_EXTERN_C_FINI
rocprofiler_status_t
Status codes.
Definition fwd.h:55
rocprofiler_tool_finalize_t finalize
cleanup
rocprofiler_tool_initialize_t initialize
context creation
const char * name
clients should set this value for debugging
unsigned long size
size of this struct (in case of future extensions)
const uint32_t handle
internal handle
void * tool_data
data to provide to init and fini callbacks
void(* rocprofiler_tool_finalize_t)(void *tool_data)
Prototype for the finalize function where a tool does any cleanup or output operations once it has fi...
void(* rocprofiler_client_finalize_t)(rocprofiler_client_id_t)
Prototype for the function pointer provided to tool in rocprofiler_tool_initialize_t....
int(* rocprofiler_tool_initialize_t)(rocprofiler_client_finalize_t finalize_func, void *tool_data)
Prototype for the initialize function where a tool creates contexts for the set of rocprofiler servic...
rocprofiler_tool_configure_result_t *(* rocprofiler_configure_func_t)(uint32_t version, const char *runtime_version, uint32_t priority, rocprofiler_client_id_t *client_id)
Function pointer typedef for rocprofiler_configure function.
rocprofiler_tool_configure_result_t * rocprofiler_configure(uint32_t version, const char *runtime_version, uint32_t priority, rocprofiler_client_id_t *client_id)
This is the special function that tools define to enable rocprofiler support. The tool should return ...
rocprofiler_status_t rocprofiler_is_initialized(int *status)
Query whether rocprofiler has already scanned the binary for all the instances of rocprofiler_configu...
rocprofiler_status_t rocprofiler_force_configure(rocprofiler_configure_func_t configure_func)
Function for explicitly registering a configuration with rocprofiler. This can be invoked before any ...
rocprofiler_status_t rocprofiler_is_finalized(int *status)
Query rocprofiler finalization status.
A client refers to an individual or entity engaged in the configuration of ROCprofiler services....
Data structure containing a initialization, finalization, and data.