/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-roctracer-docs/checkouts/docs-5.0.0/inc/roctracer.h Source File

/home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-roctracer-docs/checkouts/docs-5.0.0/inc/roctracer.h Source File#

ROC Tracer: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-roctracer-docs/checkouts/docs-5.0.0/inc/roctracer.h Source File
roctracer.h
Go to the documentation of this file.
1 /*
2 Copyright (c) 2018 Advanced Micro Devices, Inc. All rights reserved.
3 
4 Permission is hereby granted, free of charge, to any person obtaining a copy
5 of this software and associated documentation files (the "Software"), to deal
6 in the Software without restriction, including without limitation the rights
7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 copies of the Software, and to permit persons to whom the Software is
9 furnished to do so, subject to the following conditions:
10 
11 The above copyright notice and this permission notice shall be included in
12 all copies or substantial portions of the Software.
13 
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 THE SOFTWARE.
21 */
22 
24 //
25 // ROC Tracer API
26 //
27 // ROC-tracer library, Runtimes Generic Callback/Activity APIs.
28 // The goal of the implementation is to provide a generic independent from
29 // specific runtime profiler to trace API and asyncronous activity.
30 //
31 // The API provides functionality for registering the runtimes API callbacks and
32 // asyncronous activity records pool support.
33 //
35 
36 #ifndef INC_ROCTRACER_H_
37 #define INC_ROCTRACER_H_
38 
39 #include <stdint.h>
40 #include <stddef.h>
41 #ifndef __cplusplus
42 #include <stdbool.h>
43 #endif
44 
45 #include <ext/prof_protocol.h>
46 
47 #define ROCTRACER_VERSION_MAJOR 4
48 #define ROCTRACER_VERSION_MINOR 0
49 
50 #ifdef __cplusplus
51 extern "C" {
52 #endif // __cplusplus
53 
55 // Returning library version
58 
60 // Library errors enumaration
61 typedef enum {
73 
75 // Returning the last error
76 const char* roctracer_error_string();
77 
79 // Traced runtime domains
80 
81 // Activity domain type
82 typedef activity_domain_t roctracer_domain_t;
83 
84 // Return Op string by given domain and Op code
85 // NULL returned on the error and the library errno is set
86 const char* roctracer_op_string(
87  uint32_t domain, // tracing domain
88  uint32_t op, // activity op ID
89  uint32_t kind); // activity kind
90 
91 // Return Op code and kind by given string
93  uint32_t domain, // tracing domain
94  const char* str, // [in] op string
95  uint32_t* op, // [out] op code
96  uint32_t* kind); // [out] op kind code if not NULL
97 
99 // Callback API
100 //
101 // ROC tracer provides support for runtime API callbacks and activity
102 // records logging. The API callbacks provide the API calls arguments and are
103 // called on different phases, on enter, on exit, on kernel completion.
104 // Methods return non-zero on error and library errno is set.
105 
106 // Runtime API callback type
107 typedef activity_rtapi_callback_t roctracer_rtapi_callback_t;
108 
109 // Enable runtime API callbacks
111  activity_domain_t domain, // tracing domain
112  uint32_t op, // API call ID
113  activity_rtapi_callback_t callback, // callback function pointer
114  void* arg); // [in/out] callback arg
116  activity_domain_t domain, // tracing domain
117  activity_rtapi_callback_t callback, // callback function pointer
118  void* arg); // [in/out] callback arg
120  activity_rtapi_callback_t callback, // callback function pointer
121  void* arg); // [in/out] callback arg
122 
123 // Disable runtime API callbacks
125  activity_domain_t domain, // tracing domain
126  uint32_t op); // API call ID
128  activity_domain_t domain); // tracing domain
130 
132 // Activity API
133 //
134 // The activity records are asynchronously logged to the pool and can be associated
135 // with the respective API callbacks using the correlation ID. Activity API can
136 // be used to enable collecting of the records with timestamping data for API
137 // calls and the kernel submits.
138 // Methods return non zero on error and library errno is set.
139 
140 // Activity record type
141 typedef activity_record_t roctracer_record_t;
142 
143 // Return next record
144 static inline roctracer_status_t roctracer_next_record(
145  const activity_record_t* record, // [in] record ptr
146  const activity_record_t** next) // [out] next record ptr
147 {
148  *next = record + 1;
150 }
151 
152 // Tracer allocator type
153 typedef void (*roctracer_allocator_t)(
154  char** ptr, // memory pointer
155  size_t size, // memory size
156  void* arg); // allocator arg
157 
158 // Pool callback type
160  const char* begin, // [in] available buffered trace records
161  const char* end, // [in] end of buffered trace records
162  void* arg); // [in/out] callback arg
163 
164 // Tracer properties
165 typedef struct {
166  uint32_t mode; // roctracer mode
167  size_t buffer_size; // buffer size
168  roctracer_allocator_t alloc_fun; // memory alocator function pointer
169  void* alloc_arg; // memory alocator function pointer
170  roctracer_buffer_callback_t buffer_callback_fun; // tracer record callback function
171  void* buffer_callback_arg; // tracer record callback arg
173 
174 // Tracer memory pool type
175 typedef void roctracer_pool_t;
176 
177 // Create tracer memory pool
178 // The first invocation sets the default pool
180  const roctracer_properties_t* properties, // tracer pool properties
181  roctracer_pool_t** pool); // [out] returns tracer pool if not NULL,
182  // otherwise sets the default one if it is not set yet
183 static inline roctracer_status_t roctracer_open_pool(
184  const roctracer_properties_t* properties) // tracer pool properties
185 {
186  return roctracer_open_pool_expl(properties, NULL);
187 }
188  // otherwise the error is generated
189 
190 // Close tracer memory pool
192  roctracer_pool_t* pool); // [in] memory pool, NULL is a default one
193 static inline roctracer_status_t roctracer_close_pool()
194 {
195  return roctracer_close_pool_expl(NULL);
196 }
197 
198 // Return current default pool
199 // Set new default pool if the argument is not NULL
201  roctracer_pool_t* pool); // [in] new default pool if not NULL
202 static inline roctracer_pool_t* roctracer_default_pool()
203 {
204  return roctracer_default_pool_expl(NULL);
205 }
206 
207 // Enable activity records logging
209  activity_domain_t domain, // tracing domain
210  uint32_t op, // activity op ID
211  roctracer_pool_t* pool); // memory pool, NULL is a default one
212 static inline roctracer_status_t roctracer_enable_op_activity(
213  activity_domain_t domain, // tracing domain
214  uint32_t op) // activity op ID
215 {
216  return roctracer_enable_op_activity_expl(domain, op, NULL);
217 }
219  activity_domain_t domain, // tracing domain
220  roctracer_pool_t* pool); // memory pool, NULL is a default one
221 static inline roctracer_status_t roctracer_enable_domain_activity(
222  activity_domain_t domain) // tracing domain
223 {
224  return roctracer_enable_domain_activity_expl(domain, NULL);
225 }
227  roctracer_pool_t* pool); // memory pool, NULL is a default one
228 static inline roctracer_status_t roctracer_enable_activity()
229 {
230  return roctracer_enable_activity_expl(NULL);
231 }
232 
233 // Disable activity records logging
235  activity_domain_t domain, // tracing domain
236  uint32_t op); // activity op ID
238  activity_domain_t domain); // tracing domain
240 
241 // Flush available activity records
243  roctracer_pool_t* pool); // memory pool, NULL is a default one
244 static inline roctracer_status_t roctracer_flush_activity()
245 {
246  return roctracer_flush_activity_expl(NULL);
247 }
248 
249 // Get system timestamp
251  uint64_t* timestamp); // [out] return timestamp
252 
253 // Load/Unload methods
257 
258 // Set properties
260  roctracer_domain_t domain, // tracing domain
261  void* propertes); // tracing properties
262 
263 #ifdef __cplusplus
264 } // extern "C" block
265 #endif // __cplusplus
266 
267 #endif // INC_ROCTRACER_H_
roctracer_pool_t * roctracer_default_pool_expl(roctracer_pool_t *pool)
void roctracer_pool_t
Definition: roctracer.h:175
void(* roctracer_buffer_callback_t)(const char *begin, const char *end, void *arg)
Definition: roctracer.h:159
roctracer_status_t roctracer_open_pool_expl(const roctracer_properties_t *properties, roctracer_pool_t **pool)
roctracer_status_t roctracer_get_timestamp(uint64_t *timestamp)
roctracer_status_t roctracer_disable_op_activity(activity_domain_t domain, uint32_t op)
roctracer_status_t roctracer_op_code(uint32_t domain, const char *str, uint32_t *op, uint32_t *kind)
void roctracer_unload()
roctracer_status_t roctracer_enable_op_callback(activity_domain_t domain, uint32_t op, activity_rtapi_callback_t callback, void *arg)
roctracer_status_t roctracer_enable_activity_expl(roctracer_pool_t *pool)
uint32_t roctracer_version_minor()
void roctracer_flush_buf()
uint32_t roctracer_version_major()
roctracer_status_t
Definition: roctracer.h:61
@ ROCTRACER_STATUS_HIP_API_ERR
Definition: roctracer.h:68
@ ROCTRACER_STATUS_HSA_ERR
Definition: roctracer.h:70
@ ROCTRACER_STATUS_HCC_OPS_ERR
Definition: roctracer.h:69
@ ROCTRACER_STATUS_UNINIT
Definition: roctracer.h:64
@ ROCTRACER_STATUS_ERROR
Definition: roctracer.h:63
@ ROCTRACER_STATUS_BAD_PARAMETER
Definition: roctracer.h:67
@ ROCTRACER_STATUS_ROCTX_ERR
Definition: roctracer.h:71
@ ROCTRACER_STATUS_SUCCESS
Definition: roctracer.h:62
@ ROCTRACER_STATUS_BREAK
Definition: roctracer.h:65
@ ROCTRACER_STATUS_BAD_DOMAIN
Definition: roctracer.h:66
roctracer_status_t roctracer_disable_domain_activity(activity_domain_t domain)
activity_rtapi_callback_t roctracer_rtapi_callback_t
Definition: roctracer.h:107
activity_record_t roctracer_record_t
Definition: roctracer.h:141
roctracer_status_t roctracer_disable_callback()
roctracer_status_t roctracer_disable_domain_callback(activity_domain_t domain)
roctracer_status_t roctracer_enable_op_activity_expl(activity_domain_t domain, uint32_t op, roctracer_pool_t *pool)
roctracer_status_t roctracer_disable_op_callback(activity_domain_t domain, uint32_t op)
roctracer_status_t roctracer_close_pool_expl(roctracer_pool_t *pool)
const char * roctracer_op_string(uint32_t domain, uint32_t op, uint32_t kind)
roctracer_status_t roctracer_flush_activity_expl(roctracer_pool_t *pool)
void(* roctracer_allocator_t)(char **ptr, size_t size, void *arg)
Definition: roctracer.h:153
roctracer_status_t roctracer_set_properties(roctracer_domain_t domain, void *propertes)
bool roctracer_load()
roctracer_status_t roctracer_enable_domain_activity_expl(activity_domain_t domain, roctracer_pool_t *pool)
const char * roctracer_error_string()
roctracer_status_t roctracer_enable_domain_callback(activity_domain_t domain, activity_rtapi_callback_t callback, void *arg)
roctracer_status_t roctracer_disable_activity()
roctracer_status_t roctracer_enable_callback(activity_rtapi_callback_t callback, void *arg)
activity_domain_t roctracer_domain_t
Definition: roctracer.h:82
Definition: roctracer.h:165
size_t buffer_size
Definition: roctracer.h:167
uint32_t mode
Definition: roctracer.h:166
roctracer_allocator_t alloc_fun
Definition: roctracer.h:168
roctracer_buffer_callback_t buffer_callback_fun
Definition: roctracer.h:170
void * alloc_arg
Definition: roctracer.h:169
void * buffer_callback_arg
Definition: roctracer.h:171