Activity API

Activity API#

ROC Tracer: 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...
 

Functions

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. More...
 
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. More...
 
ROCTRACER_API roctracer_status_t roctracer_open_pool (const roctracer_properties_t *properties) ROCTRACER_VERSION_4_1
 Create tracer memory pool. More...
 
ROCTRACER_API roctracer_status_t roctracer_close_pool_expl (roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
 Close tracer memory pool. More...
 
ROCTRACER_API roctracer_status_t roctracer_close_pool () ROCTRACER_VERSION_4_1
 Close default tracer memory pool, if defined, and set to undefined. More...
 
ROCTRACER_API roctracer_pool_troctracer_default_pool_expl (roctracer_pool_t *pool) ROCTRACER_VERSION_4_1
 Query and set the default memory pool. More...
 
ROCTRACER_API roctracer_pool_troctracer_default_pool () ROCTRACER_VERSION_4_1
 Query the current default memory pool. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
ROCTRACER_API roctracer_status_t roctracer_flush_activity () ROCTRACER_VERSION_4_1
 Flush available activity records for the default memory pool. 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_SUCCESSThe 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]poolMemory 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_SUCCESSThe 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]poolIf 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]domainThe domain.
Return values
ROCTRACER_STATUS_SUCCESSThe 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]domainThe domain.
[in]opThe activity operation ID in domain.
Return values
ROCTRACER_STATUS_SUCCESSThe 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]domainThe domain.
Return values
ROCTRACER_STATUS_SUCCESSThe function has been executed successfully.
ROCTRACER_STATUS_ERRORNo 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]domainThe domain.
[in]poolThe memory pool to write the activity record. If NULL, use the default memory pool.
Return values
ROCTRACER_STATUS_SUCCESSThe function has been executed successfully.
ROCTRACER_STATUS_ERRORpool is 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]domainThe domain.
[in]opThe activity operation ID in domain.
Return values
ROCTRACER_STATUS_SUCCESSThe function has been executed successfully.
ROCTRACER_STATUS_ERRORNo 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]domainThe domain.
[in]opThe activity operation ID in domain.
[in]poolThe memory pool to write the activity record. If NULL, use the default memory pool.
Return values
ROCTRACER_STATUS_SUCCESSThe function has been executed successfully.
ROCTRACER_STATUS_ERRORpool is 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_SUCCESSThe 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]poolThe memory pool to flush. If NULL, flushes the default memory pool.
Return values
ROCTRACER_STATUS_SUCCESSThe 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]recordPointer to ac activity record in a memory pool buffer.
[out]nextPointer to the following activity record in the memory pool buffer.
Return values
ROCTRACER_STATUS_SUCCESSThe 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]propertiesTracer memory pool properties.
Return values
ROCTRACER_STATUS_SUCCESSThe function has been executed successfully.
ROCTRACER_STATUS_ERROR_DEFAULT_POOL_ALREADY_DEFINEDThe default pool is already defined. Unable to create the pool.
ROCTRACER_STATUS_ERROR_MEMORY_ALLOCATIONUnable 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]propertiesTracer memory pool properties.
[out]poolTracer memory pool created if not NULL.
Return values
ROCTRACER_STATUS_SUCCESSThe function has been executed successfully.
ROCTRACER_STATUS_ERROR_DEFAULT_POOL_ALREADY_DEFINEDpool is NULL and the default pool is already defined. Unable to create the pool.
ROCTRACER_STATUS_ERROR_MEMORY_ALLOCATIONUnable to allocate memory for the pool. Unable to create the pool.