This page contains changes for a test release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

ROCProfiler Sessions

ROCProfiler Sessions#

rocprofiler: ROCProfiler Sessions

ROCProfiler Session Modes. More...

Modules

 Session Filters Handling
 

Data Structures

struct  rocprofiler_session_id_t
 Session Identifier. More...
 

Enumerations

enum  rocprofiler_replay_mode_t { ROCPROFILER_NONE_REPLAY_MODE = -1 }
 Replay Profiling Modes. More...
 

Functions

ROCPROFILER_API rocprofiler_status_t rocprofiler_create_session (rocprofiler_replay_mode_t replay_mode, rocprofiler_session_id_t *session_id) ROCPROFILER_VERSION_9_0
 Create Session A ROCProfiler Session is having enough information about what needs to be collected or traced and it allows the user to start/stop profiling/tracing whenever required. More...
 
ROCPROFILER_API rocprofiler_status_t rocprofiler_destroy_session (rocprofiler_session_id_t session_id) ROCPROFILER_VERSION_9_0
 Destroy Session Destroy session created by rocprofiler_create_session, please refer to the samples for how to use. More...
 
ROCPROFILER_API rocprofiler_status_t rocprofiler_create_ready_session (rocprofiler_replay_mode_t replay_mode, rocprofiler_filter_kind_t filter_kind, rocprofiler_filter_data_t data, uint64_t data_count, size_t buffer_size, rocprofiler_buffer_callback_t buffer_callback, rocprofiler_session_id_t *session_id, rocprofiler_filter_property_t property, rocprofiler_sync_callback_t callback) ROCPROFILER_VERSION_9_0
 Create Ready Session A one call to create a ready profiling or tracing session, so that the session will be ready to collect counters with a one call to rocprofiler_start_session. More...
 
ROCPROFILER_API rocprofiler_status_t rocprofiler_start_session (rocprofiler_session_id_t session_id) ROCPROFILER_VERSION_9_0
 Activate Session Activating session created by rocprofiler_create_session, please refer to the samples for how to use. More...
 
ROCPROFILER_API rocprofiler_status_t rocprofiler_terminate_session (rocprofiler_session_id_t session_id) ROCPROFILER_VERSION_9_0
 Deactivate Session Deactivate session created by rocprofiler_create_session, please refer to the samples for how to use. More...
 

Detailed Description

ROCProfiler Session Modes.

Enumeration Type Documentation

◆ rocprofiler_replay_mode_t

Replay Profiling Modes.

Enumerator
ROCPROFILER_NONE_REPLAY_MODE 

No Replay to be done, Mostly for tracing tool or if the user wants to make sure that no replays will be done.

Function Documentation

◆ rocprofiler_create_ready_session()

ROCPROFILER_API rocprofiler_status_t rocprofiler_create_ready_session ( rocprofiler_replay_mode_t  replay_mode,
rocprofiler_filter_kind_t  filter_kind,
rocprofiler_filter_data_t  data,
uint64_t  data_count,
size_t  buffer_size,
rocprofiler_buffer_callback_t  buffer_callback,
rocprofiler_session_id_t session_id,
rocprofiler_filter_property_t  property,
rocprofiler_sync_callback_t  callback 
)

Create Ready Session A one call to create a ready profiling or tracing session, so that the session will be ready to collect counters with a one call to rocprofiler_start_session.

::rocprofiler_session_set_filter can be used to set optional filters like specific GPUs/Kernel Names/Counter Names and more. The Creation of the session is responsible for the creation of the buffer saving the records generated while the session is active. Session can be started using rocprofiler_start_session and can be stopped using rocprofiler_terminate_session

Parameters
[in]counterscounter filter data, it is required from the user to create the filter with ::ROCPROFILER_FILTER_PROFILER_COUNTER_NAMES and to provide an array of counter names needed and their count
[in]replay_modeThe Replay strategy that should be used if replay is needed
[in]filter_kindFilter kind associated with these filters
[in]dataPointer to the filter data
[in]data_countFilter data array count
[in]buffer_sizeSize of the memory pool that will be used to save the data from profiling or/and tracing, if the buffer was allocated before it will be reallocated with the new size in addition to the old size
[in]buffer_callbackAsynchronous callback using Memory buffers saving the data and then it will be flushed if the user called rocprofiler_flush_data or if the buffer is full or if the application finished execution
[out]session_idPointer to the created session id, the session is alive up till rocprofiler_destroy_session being called, however, the session id can be used while the session is active which can be activated using rocprofiler_start_session and deactivated using rocprofiler_terminate_session but rocprofiler_flush_data can use session_id even if it is deactivated for flushing the saved records
[in]propertyFilter Property (Optional)
[in]callbackSynchronous callback for API traces (Optional)
Return values
ROCPROFILER_STATUS_SUCCESSThe function has been executed successfully.
ROCPROFILER_STATUS_ERROR_NOT_INITIALIZED,ifrocprofiler_initialize wasn't called before or if rocprofiler_finalize is called
::ROCPROFILER_STATUS_ERROR_SESSION_MODE_FILTER_MISMATCH
The session doesn't have the required mode for that filter type
ROCPROFILER_STATUS_ERROR_FILTER_DATA_CORRUPTED
Data can't be read or corrupted
ROCPROFILER_STATUS_ERROR_INCORRECT_SIZEIf the size is less than one potential record size

◆ rocprofiler_create_session()

ROCPROFILER_API rocprofiler_status_t rocprofiler_create_session ( rocprofiler_replay_mode_t  replay_mode,
rocprofiler_session_id_t session_id 
)

Create Session A ROCProfiler Session is having enough information about what needs to be collected or traced and it allows the user to start/stop profiling/tracing whenever required.

Session will hold multiple mode, that can be added using ::rocprofiler_add_session_mode, it is required to add at least one session mode, if it is tracing or profiling and using ::rocprofiler_session_set_filter can set specific data that is required for the profiler or the tracer such as the counters for profiling or the APIs for tracing before calling rocprofiler_start_session, also ::rocprofiler_session_set_filter can be used to set optional filters like specific GPUs/Kernel Names/API Names and more. Session can be started using rocprofiler_start_session and can be stopped using rocprofiler_terminate_session

Parameters
[in]replay_modeThe Replay strategy that should be used if replay is needed
[out]session_idPointer to the created session id, the session is alive up till rocprofiler_destroy_session being called, however, the session id can be used while the session is active which can be activated using rocprofiler_start_session and deactivated using rocprofiler_terminate_session but rocprofiler_flush_data can use session_id even if it is deactivated for flushing the saved records
Return values
ROCPROFILER_STATUS_SUCCESSThe function has been executed successfully.
ROCPROFILER_STATUS_ERROR_NOT_INITIALIZED,ifrocprofiler_initialize wasn't called before or if rocprofiler_finalize is called

◆ rocprofiler_destroy_session()

ROCPROFILER_API rocprofiler_status_t rocprofiler_destroy_session ( rocprofiler_session_id_t  session_id)

Destroy Session Destroy session created by rocprofiler_create_session, please refer to the samples for how to use.

This marks the end of session and its own id life and none of the session related functions will be available after this call.

Parameters
[in]session_idThe created session id
Return values
ROCPROFILER_STATUS_SUCCESSThe function has been executed successfully
ROCPROFILER_STATUS_ERROR_NOT_INITIALIZED,ifrocprofiler_initialize wasn't called before or if rocprofiler_finalize is called
ROCPROFILER_STATUS_ERROR_SESSION_NOT_FOUND
may return if the session is not found

◆ rocprofiler_start_session()

ROCPROFILER_API rocprofiler_status_t rocprofiler_start_session ( rocprofiler_session_id_t  session_id)

Activate Session Activating session created by rocprofiler_create_session, please refer to the samples for how to use.

Parameters
[in]session_idSession ID representing the created session
Return values
ROCPROFILER_STATUS_SUCCESSThe function has been executed successfully
ROCPROFILER_STATUS_ERROR_NOT_INITIALIZED,ifrocprofiler_initialize wasn't called before or if rocprofiler_finalize is called
ROCPROFILER_STATUS_ERROR_SESSION_NOT_FOUND
may return if the session is not found
::ROCPROFILER_STATUS_ERROR_SESSION_MODE_NOT_ADDEDif there is no session_mode added
::ROCPROFILER_STATUS_ERROR_MISSING_SESSION_CALLBACKif any session_mode is missing callback set
ROCPROFILER_STATUS_ERROR_HAS_ACTIVE_SESSION
if there is already active session

◆ rocprofiler_terminate_session()

ROCPROFILER_API rocprofiler_status_t rocprofiler_terminate_session ( rocprofiler_session_id_t  session_id)

Deactivate Session Deactivate session created by rocprofiler_create_session, please refer to the samples for how to use.

Parameters
[in]session_idSession ID for the session that will be terminated
Return values
ROCPROFILER_STATUS_SUCCESSThe function has been executed successfully
ROCPROFILER_STATUS_ERROR_SESSION_NOT_FOUND
may return if the session is not found
ROCPROFILER_STATUS_ERROR_SESSION_NOT_ACTIVEif the session is not active