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

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

ROC Tracer: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-roctracer-docs/checkouts/docs-5.7.0/inc/roctracer.h Source File
roctracer.h
Go to the documentation of this file.
1 /* Copyright (c) 2018-2022 Advanced Micro Devices, Inc.
2 
3  Permission is hereby granted, free of charge, to any person obtaining a copy
4  of this software and associated documentation files (the "Software"), to deal
5  in the Software without restriction, including without limitation the rights
6  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7  copies of the Software, and to permit persons to whom the Software is
8  furnished to do so, subject to the following conditions:
9 
10  The above copyright notice and this permission notice shall be included in
11  all copies or substantial portions of the Software.
12 
13  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19  THE SOFTWARE. */
20 
47 #ifndef ROCTRACER_H_
48 #define ROCTRACER_H_
49 
50 /* Placeholder for calling convention and import/export macros */
51 #if !defined(ROCTRACER_CALL)
52 #define ROCTRACER_CALL
53 #endif /* !defined (ROCTRACER_CALL) */
54 
55 #if !defined(ROCTRACER_EXPORT_DECORATOR)
56 #if defined(__GNUC__)
57 #define ROCTRACER_EXPORT_DECORATOR __attribute__((visibility("default")))
58 #elif defined(_MSC_VER)
59 #define ROCTRACER_EXPORT_DECORATOR __declspec(dllexport)
60 #endif /* defined (_MSC_VER) */
61 #endif /* !defined (ROCTRACER_EXPORT_DECORATOR) */
62 
63 #if !defined(ROCTRACER_IMPORT_DECORATOR)
64 #if defined(__GNUC__)
65 #define ROCTRACER_IMPORT_DECORATOR
66 #elif defined(_MSC_VER)
67 #define ROCTRACER_IMPORT_DECORATOR __declspec(dllimport)
68 #endif /* defined (_MSC_VER) */
69 #endif /* !defined (ROCTRACER_IMPORT_DECORATOR) */
70 
71 #define ROCTRACER_EXPORT ROCTRACER_EXPORT_DECORATOR ROCTRACER_CALL
72 #define ROCTRACER_IMPORT ROCTRACER_IMPORT_DECORATOR ROCTRACER_CALL
73 
74 #if !defined(ROCTRACER)
75 #if defined(ROCTRACER_EXPORTS)
76 #define ROCTRACER_API ROCTRACER_EXPORT
77 #else /* !defined (ROCTRACER_EXPORTS) */
78 #define ROCTRACER_API ROCTRACER_IMPORT
79 #endif /* !defined (ROCTRACER_EXPORTS) */
80 #endif /* !defined (ROCTRACER) */
81 
82 #include <stddef.h>
83 #include <stdint.h>
84 
85 #include "ext/prof_protocol.h"
86 
87 #ifdef __cplusplus
88 extern "C" {
89 #endif /* __cplusplus */
90 
110 #define ROCTRACER_VERSION_4_1
111 
131 #define ROCTRACER_VERSION_MAJOR 4
132 
137 #define ROCTRACER_VERSION_MINOR 1
138 
147 
156 
169 typedef enum {
245 
258 
272 typedef activity_domain_t roctracer_domain_t;
273 
288  uint32_t domain, uint32_t op, uint32_t kind) ROCTRACER_VERSION_4_1;
289 
311 roctracer_op_code(uint32_t domain, const char* str, uint32_t* op,
312  uint32_t* kind) ROCTRACER_VERSION_4_1;
313 
327  roctracer_domain_t domain, void* properties) ROCTRACER_VERSION_4_1;
328 
346 typedef activity_rtapi_callback_t roctracer_rtapi_callback_t;
347 
369  activity_domain_t domain, uint32_t op, activity_rtapi_callback_t callback,
370  void* arg) ROCTRACER_VERSION_4_1;
371 
388  activity_domain_t domain, activity_rtapi_callback_t callback,
389  void* arg) ROCTRACER_VERSION_4_1;
390 
407  activity_domain_t domain, uint32_t op) ROCTRACER_VERSION_4_1;
408 
420  activity_domain_t domain) ROCTRACER_VERSION_4_1;
421 
439 typedef activity_record_t roctracer_record_t;
440 
456 roctracer_next_record(const activity_record_t* record,
457  const activity_record_t** next) ROCTRACER_VERSION_4_1;
458 
478 typedef void (*roctracer_allocator_t)(char** ptr, size_t size, void* arg);
479 
492 typedef void (*roctracer_buffer_callback_t)(const char* begin, const char* end,
493  void* arg);
494 
500 typedef struct {
504  uint32_t mode;
505 
509  size_t buffer_size;
510 
516 
520  void* alloc_arg;
521 
526 
532 
536 typedef void roctracer_pool_t;
537 
563 
583 
599 
611 
623 
630 
649  activity_domain_t domain, uint32_t op,
651 
666  activity_domain_t domain, uint32_t op) ROCTRACER_VERSION_4_1;
667 
684  activity_domain_t domain, roctracer_pool_t* pool) ROCTRACER_VERSION_4_1;
685 
698  activity_domain_t domain) ROCTRACER_VERSION_4_1;
699 
711  activity_domain_t domain, uint32_t op) ROCTRACER_VERSION_4_1;
712 
722  activity_domain_t domain) ROCTRACER_VERSION_4_1;
723 
739 
752 
771  roctracer_timestamp_t* timestamp) ROCTRACER_VERSION_4_1;
772 
775 #ifdef __cplusplus
776 } /* extern "C" block */
777 #endif /* __cplusplus */
778 
779 #endif /* ROCTRACER_H_ */
ROCTRACER_API roctracer_status_t roctracer_disable_op_activity(activity_domain_t domain, uint32_t op) ROCTRACER_VERSION_4_1
Disable activity record logging for a specified operation of a domain.
void roctracer_pool_t
Tracer memory pool type.
Definition: roctracer.h:536
void(* roctracer_buffer_callback_t)(const char *begin, const char *end, void *arg)
Memory pool buffer callback.
Definition: roctracer.h:492
ROCTRACER_API roctracer_pool_t * roctracer_default_pool_expl(roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
Query and set the default memory pool.
ROCTRACER_API roctracer_status_t roctracer_next_record(const activity_record_t *record, const activity_record_t **next) ROCTRACER_VERSION_4_1
Get a pointer to the next activity record.
ROCTRACER_API roctracer_pool_t * roctracer_default_pool() ROCTRACER_VERSION_4_1
Query the current default memory pool.
ROCTRACER_API roctracer_status_t roctracer_flush_activity_expl(roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
Flush available activity records for a memory pool.
ROCTRACER_API roctracer_status_t roctracer_flush_activity() ROCTRACER_VERSION_4_1
Flush available activity records for the default memory pool.
ROCTRACER_API roctracer_status_t roctracer_open_pool_expl(const roctracer_properties_t *properties, roctracer_pool_t **pool) ROCTRACER_VERSION_4_1
Create tracer memory pool.
activity_record_t roctracer_record_t
Activity record.
Definition: roctracer.h:439
ROCTRACER_API roctracer_status_t roctracer_enable_op_activity_expl(activity_domain_t domain, uint32_t op, roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
Enable activity record logging for a specified operation of a domain providing a memory pool.
ROCTRACER_API roctracer_status_t roctracer_close_pool_expl(roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
Close tracer memory pool.
ROCTRACER_API roctracer_status_t roctracer_enable_domain_activity(activity_domain_t domain) ROCTRACER_VERSION_4_1
Enable activity record logging for all operations of a domain using the default memory pool.
ROCTRACER_API roctracer_status_t roctracer_close_pool() ROCTRACER_VERSION_4_1
Close default tracer memory pool, if defined, and set to undefined.
void(* roctracer_allocator_t)(char **ptr, size_t size, void *arg)
Memory pool allocator callback.
Definition: roctracer.h:478
ROCTRACER_API roctracer_status_t roctracer_open_pool(const roctracer_properties_t *properties) ROCTRACER_VERSION_4_1
Create tracer memory pool.
ROCTRACER_API roctracer_status_t roctracer_disable_domain_activity(activity_domain_t domain) ROCTRACER_VERSION_4_1
Disable activity record logging for all operations of a domain.
ROCTRACER_API roctracer_status_t roctracer_enable_domain_activity_expl(activity_domain_t domain, roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
Enable activity record logging for all operations of a domain providing a memory pool.
ROCTRACER_API roctracer_status_t roctracer_enable_op_activity(activity_domain_t domain, uint32_t op) ROCTRACER_VERSION_4_1
Enable activity record logging for a specified operation of a domain using the default memory pool.
ROCTRACER_API roctracer_status_t roctracer_enable_domain_callback(activity_domain_t domain, activity_rtapi_callback_t callback, void *arg) ROCTRACER_VERSION_4_1
Enable runtime API callback for all operations of a domain.
ROCTRACER_API roctracer_status_t roctracer_enable_op_callback(activity_domain_t domain, uint32_t op, activity_rtapi_callback_t callback, void *arg) ROCTRACER_VERSION_4_1
Enable runtime API callback for a specific operation of a domain.
activity_rtapi_callback_t roctracer_rtapi_callback_t
Runtime API callback type.
Definition: roctracer.h:346
ROCTRACER_API roctracer_status_t roctracer_disable_domain_callback(activity_domain_t domain) ROCTRACER_VERSION_4_1
Disable runtime API callback for all operations of a domain.
ROCTRACER_API roctracer_status_t roctracer_disable_op_callback(activity_domain_t domain, uint32_t op) ROCTRACER_VERSION_4_1
Disable runtime API callback for a specific operation of a domain.
ROCTRACER_API roctracer_status_t roctracer_set_properties(roctracer_domain_t domain, void *properties) ROCTRACER_VERSION_4_1
Set the properties of a domain.
ROCTRACER_API roctracer_status_t roctracer_op_code(uint32_t domain, const char *str, uint32_t *op, uint32_t *kind) ROCTRACER_VERSION_4_1
Query the operation code given a domain and the name of an operation.
ROCTRACER_API const char * roctracer_op_string(uint32_t domain, uint32_t op, uint32_t kind) ROCTRACER_VERSION_4_1
Query textual name of an operation of a domain.
activity_domain_t roctracer_domain_t
Enumeration of domains that can be traced.
Definition: roctracer.h:272
roctracer_status_t
ROC Tracer API status codes.
Definition: roctracer.h:169
ROCTRACER_API const char * roctracer_error_string() ROCTRACER_VERSION_4_1
Query the textual description of the last error for the current thread.
@ ROCTRACER_STATUS_HIP_API_ERR
Deprecated error code.
Definition: roctracer.h:227
@ ROCTRACER_STATUS_ERROR_DEFAULT_POOL_UNDEFINED
No default pool is defined.
Definition: roctracer.h:189
@ ROCTRACER_STATUS_HSA_ERR
Deprecated error code.
Definition: roctracer.h:239
@ ROCTRACER_STATUS_ERROR_DEFAULT_POOL_ALREADY_DEFINED
The default pool is already defined.
Definition: roctracer.h:193
@ ROCTRACER_STATUS_HIP_OPS_ERR
Deprecated error code.
Definition: roctracer.h:231
@ ROCTRACER_STATUS_HCC_OPS_ERR
Deprecated error code.
Definition: roctracer.h:235
@ ROCTRACER_STATUS_ERROR_INVALID_DOMAIN_ID
The domain ID is invalid.
Definition: roctracer.h:181
@ ROCTRACER_STATUS_ERROR_INVALID_ARGUMENT
An invalid argument was given to the function.
Definition: roctracer.h:185
@ ROCTRACER_STATUS_ERROR_NOT_IMPLEMENTED
The operation is not currently implemented.
Definition: roctracer.h:207
@ ROCTRACER_STATUS_ERROR_MISMATCHED_EXTERNAL_CORRELATION_ID
External correlation ID pop mismatch.
Definition: roctracer.h:201
@ ROCTRACER_STATUS_UNINIT
Deprecated error code.
Definition: roctracer.h:211
@ ROCTRACER_STATUS_ERROR_MEMORY_ALLOCATION
Memory allocation error.
Definition: roctracer.h:197
@ ROCTRACER_STATUS_ERROR
A generic error has occurred.
Definition: roctracer.h:177
@ ROCTRACER_STATUS_BAD_PARAMETER
Deprecated error code.
Definition: roctracer.h:223
@ ROCTRACER_STATUS_ROCTX_ERR
Deprecated error code.
Definition: roctracer.h:243
@ ROCTRACER_STATUS_SUCCESS
The function has executed successfully.
Definition: roctracer.h:173
@ ROCTRACER_STATUS_BREAK
Deprecated error code.
Definition: roctracer.h:215
@ ROCTRACER_STATUS_BAD_DOMAIN
Deprecated error code.
Definition: roctracer.h:219
#define ROCTRACER_VERSION_4_1
The function was introduced in version 4.1 of the interface and has the symbol version string of "ROC...
Definition: roctracer.h:110
ROCTRACER_API roctracer_status_t roctracer_get_timestamp(roctracer_timestamp_t *timestamp) ROCTRACER_VERSION_4_1
Get the system clock timestamp.
ROCTRACER_API uint32_t roctracer_version_major() ROCTRACER_VERSION_4_1
Query the major version of the installed library.
ROCTRACER_API uint32_t roctracer_version_minor() ROCTRACER_VERSION_4_1
Query the minor version of the installed library.
#define ROCTRACER_API
Definition: roctracer.h:78
Memory pool properties.
Definition: roctracer.h:500
size_t buffer_size
Size of buffer in bytes.
Definition: roctracer.h:509
uint32_t mode
ROC Tracer mode.
Definition: roctracer.h:504
roctracer_allocator_t alloc_fun
The allocator function to use to allocate and deallocate the buffer.
Definition: roctracer.h:515
roctracer_buffer_callback_t buffer_callback_fun
The function to call when a buffer becomes full or is flushed.
Definition: roctracer.h:525
void * alloc_arg
The argument to pass when invoking the alloc_fun allocator.
Definition: roctracer.h:520
void * buffer_callback_arg
The argument to pass when invoking the buffer_callback_fun callback.
Definition: roctracer.h:530