Activity API#
The activity records are asynchronously logged to the pool and can be associated with the respective API callbacks using the correlation ID. More...
Data Structures | |
| struct | roctracer_properties_t |
| Memory pool properties. More... | |
Typedefs | |
| typedef activity_record_t | roctracer_record_t |
| Activity record. More... | |
| typedef void(* | roctracer_allocator_t) (char **ptr, size_t size, void *arg) |
| Memory pool allocator callback. More... | |
| typedef void(* | roctracer_buffer_callback_t) (const char *begin, const char *end, void *arg) |
| Memory pool buffer callback. More... | |
| typedef void | roctracer_pool_t |
| Tracer memory pool type. More... | |
Detailed Description
The activity records are asynchronously logged to the pool and can be associated with the respective API callbacks using the correlation ID.
Activity API can be used to enable collecting of the records with timestamping data for API calls and the kernel submits.
Typedef Documentation
◆ roctracer_allocator_t
| typedef void(* roctracer_allocator_t) (char **ptr, size_t size, void *arg) |
Memory pool allocator callback.
If *ptr is NULL, then allocate memory of size bytes and save address in *ptr.
If *ptr is non-NULL and size is non-0, then reallocate the memory at *ptr with size size and save the address in *ptr. The memory will have been allocated by the same callback.
If *ptr is non-NULL and size is 0, then deallocate the memory at *ptr. The memory will have been allocated by the same callback.
size is the size of the memory allocation or reallocation, or 0 if deallocating.
arg Argument provided in the roctracer_properties_t passed to the roctracer_open_pool function.
◆ roctracer_buffer_callback_t
| typedef void(* roctracer_buffer_callback_t) (const char *begin, const char *end, void *arg) |
Memory pool buffer callback.
The callback that will be invoked when a memory pool buffer becomes full or is flushed.
begin pointer to first entry entry in the buffer.
end pointer to one past the end entry in the buffer.
arg the argument specified when the callback was defined.
◆ roctracer_pool_t
| typedef void roctracer_pool_t |
Tracer memory pool type.
◆ roctracer_record_t
| typedef activity_record_t roctracer_record_t |
Activity record.
Asynchronous activity events generate activity records.
Function Documentation
◆ roctracer_close_pool()
| ROCTRACER_API roctracer_status_t roctracer_close_pool | ( | ) |
Close default tracer memory pool, if defined, and set to undefined.
All enabled activities that use the pool must have completed writing to the pool, before deleting the pool. Deleting a pool automatically disables any activities that specify the pool, and flushes it.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully or there is no default pool.
◆ roctracer_close_pool_expl()
| ROCTRACER_API roctracer_status_t roctracer_close_pool_expl | ( | roctracer_pool_t * | pool | ) |
Close tracer memory pool.
All enabled activities that use the pool must have completed writing to the pool, before deleting the pool. Deleting a pool automatically disables any activities that specify the pool, and flushes it.
- Parameters
-
[in] pool Memory pool to close. If NULL, the default memory pool is closed if defined. The default memory pool is set to undefined if closed.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully or pool was NULL and there is no default pool.
◆ roctracer_default_pool()
| ROCTRACER_API roctracer_pool_t* roctracer_default_pool | ( | ) |
Query the current default memory pool.
- Returns
- Return the current default memory pool, or NULL is none is defined.
◆ roctracer_default_pool_expl()
| ROCTRACER_API roctracer_pool_t* roctracer_default_pool_expl | ( | roctracer_pool_t * | pool | ) |
Query and set the default memory pool.
- Parameters
-
[in] pool If not NULL, change the current default pool to pool. If NULL, the default pool is not changed.
- Returns
- Return the current default memory pool before any change, or NULL if none is defined.
◆ roctracer_disable_domain_activity()
| ROCTRACER_API roctracer_status_t roctracer_disable_domain_activity | ( | activity_domain_t | domain | ) |
Disable activity record logging for all operations of a domain.
- Parameters
-
[in] domain The domain.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully.
◆ roctracer_disable_op_activity()
| ROCTRACER_API roctracer_status_t roctracer_disable_op_activity | ( | activity_domain_t | domain, |
| uint32_t | op | ||
| ) |
Disable activity record logging for a specified operation of a domain.
- Parameters
-
[in] domain The domain. [in] op The activity operation ID in domain.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully.
◆ roctracer_enable_domain_activity()
| ROCTRACER_API roctracer_status_t roctracer_enable_domain_activity | ( | activity_domain_t | domain | ) |
Enable activity record logging for all operations of a domain using the default memory pool.
- Parameters
-
[in] domain The domain.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully. ROCTRACER_STATUS_ERROR No default pool is defined.
◆ roctracer_enable_domain_activity_expl()
| ROCTRACER_API roctracer_status_t roctracer_enable_domain_activity_expl | ( | activity_domain_t | domain, |
| roctracer_pool_t * | pool | ||
| ) |
Enable activity record logging for all operations of a domain providing a memory pool.
- Parameters
-
[in] domain The domain. [in] pool The memory pool to write the activity record. If NULL, use the default memory pool.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully. ROCTRACER_STATUS_ERROR poolis NULL and no default pool is defined.
◆ roctracer_enable_op_activity()
| ROCTRACER_API roctracer_status_t roctracer_enable_op_activity | ( | activity_domain_t | domain, |
| uint32_t | op | ||
| ) |
Enable activity record logging for a specified operation of a domain using the default memory pool.
- Parameters
-
[in] domain The domain. [in] op The activity operation ID in domain.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully. ROCTRACER_STATUS_ERROR No default pool is defined.
◆ roctracer_enable_op_activity_expl()
| ROCTRACER_API roctracer_status_t roctracer_enable_op_activity_expl | ( | activity_domain_t | domain, |
| uint32_t | op, | ||
| roctracer_pool_t * | pool | ||
| ) |
Enable activity record logging for a specified operation of a domain providing a memory pool.
- Parameters
-
[in] domain The domain. [in] op The activity operation ID in domain.[in] pool The memory pool to write the activity record. If NULL, use the default memory pool.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully. ROCTRACER_STATUS_ERROR poolis NULL and no default pool is defined.
◆ roctracer_flush_activity()
| ROCTRACER_API roctracer_status_t roctracer_flush_activity | ( | ) |
Flush available activity records for the default memory pool.
If flushing encounters an activity record still being written, flushing stops. Use a subsequent flush when the record has completed being written to resume the flush.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully.
◆ roctracer_flush_activity_expl()
| ROCTRACER_API roctracer_status_t roctracer_flush_activity_expl | ( | roctracer_pool_t * | pool | ) |
Flush available activity records for a memory pool.
If flushing encounters an activity record still being written, flushing stops. Use a subsequent flush when the record has completed being written to resume the flush.
- Parameters
-
[in] pool The memory pool to flush. If NULL, flushes the default memory pool.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully.
◆ roctracer_next_record()
| ROCTRACER_API roctracer_status_t roctracer_next_record | ( | const activity_record_t * | record, |
| const activity_record_t ** | next | ||
| ) |
Get a pointer to the next activity record.
A memory pool generates buffers that contain multiple activity records. This function steps to the next activity record.
- Parameters
-
[in] record Pointer to ac activity record in a memory pool buffer. [out] next Pointer to the following activity record in the memory pool buffer.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully.
◆ roctracer_open_pool()
| ROCTRACER_API roctracer_status_t roctracer_open_pool | ( | const roctracer_properties_t * | properties | ) |
Create tracer memory pool.
Sets the default memory pool to the created pool if not already defined. Otherwise, return an error.
- Parameters
-
[in] properties Tracer memory pool properties.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully. ROCTRACER_STATUS_ERROR_DEFAULT_POOL_ALREADY_DEFINED The default pool is already defined. Unable to create the pool. ROCTRACER_STATUS_ERROR_MEMORY_ALLOCATION Unable to allocate memory for the pool. Unable to create the pool.
◆ roctracer_open_pool_expl()
| ROCTRACER_API roctracer_status_t roctracer_open_pool_expl | ( | const roctracer_properties_t * | properties, |
| roctracer_pool_t ** | pool | ||
| ) |
Create tracer memory pool.
If pool is not NULL, returns the created memory pool. Does not change the default memory pool.
If pool is NULL, sets the default memory pool to the created pool if not already defined. Otherwise, return an error.
- Parameters
-
[in] properties Tracer memory pool properties. [out] pool Tracer memory pool created if not NULL.
- Return values
-
ROCTRACER_STATUS_SUCCESS The function has been executed successfully. ROCTRACER_STATUS_ERROR_DEFAULT_POOL_ALREADY_DEFINED poolis NULL and the default pool is already defined. Unable to create the pool.ROCTRACER_STATUS_ERROR_MEMORY_ALLOCATION Unable to allocate memory for the pool. Unable to create the pool.