AI/rocm-systems
2
0
Çatalla 0
Kod Konular Değişiklik İstekleri İşlemler Paketler Projeler Sürüm Viki Aktivite

Update documentation (#275)

Kaynağa Gözat 
- finished most of the TODOs
Bu işleme şunda yer alıyor:
Jonathan R. Madsen
2023-12-04 13:43:22 -06:00
işlemeyi yapan: GitHub
ebeveyn 022d7abc29
işleme 1c02e7a92a
5 değiştirilmiş dosya ile 144 ekleme ve 163 silme
Yama Dosyasını İndir Diff Dosyasını İndir Tüm dosyaları genişlet Tüm dosyaları daralt
source/include/rocprofiler-sdk/buffer_tracing.h
+84 -139
Dosyayı Görüntüle
@@ -37,184 +37,122 @@ ROCPROFILER_EXTERN_C_INIT
/**
* @brief ROCProfiler Buffer HSA API Tracer Record.
* TODO(aelwazir): Add comments against every variable
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_tracing_operation_t operation; // rocprofiler/hsa.h
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_thread_id_t thread_id;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_CALLBACK_TRACING_HSA_API
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_tracing_operation_t operation; ///< ::rocprofiler_hsa_api_id_t
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
rocprofiler_thread_id_t thread_id; ///< id for thread generating this record
} rocprofiler_buffer_tracing_hsa_api_record_t;
/**
* @brief ROCProfiler Buffer HIP API Tracer Record.
* TODO(aelwazir): Add comments against every variable
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_tracing_operation_t operation; // rocprofiler/hip.h
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_thread_id_t thread_id;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_CALLBACK_TRACING_HIP_API
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_tracing_operation_t operation; ///< ::rocprofiler_hip_api_id_t
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
rocprofiler_thread_id_t thread_id; ///< id for thread generating this record
} rocprofiler_buffer_tracing_hip_api_record_t;
/**
* @brief ROCProfiler Buffer Marker Tracer Record.
* TODO(aelwazir): Add comments against every variable
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_tracing_operation_t operation; // rocprofiler/marker.h
rocprofiler_timestamp_t timestamp;
rocprofiler_thread_id_t thread_id;
uint64_t marker_id; // rocprofiler_marker_id_t
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_CALLBACK_TRACING_MARKER_API
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_tracing_operation_t operation; ///< ::rocprofiler_marker_api_id_t
rocprofiler_timestamp_t timestamp; ///< time in nanoseconds
rocprofiler_thread_id_t thread_id; ///< id for thread generating this record
uint64_t marker_id; // rocprofiler_marker_id_t
// const char* message; // (Need Review?)
} rocprofiler_buffer_tracing_marker_record_t;
/**
* @brief ROCProfiler Buffer Memory Copy Tracer Record.
* TODO(aelwazir): Add comments against every variable
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_agent_id_t agent_id;
rocprofiler_queue_id_t queue_id;
rocprofiler_kernel_id_t kernel_id;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_MEMORY_COPY
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
rocprofiler_agent_id_t agent_id; ///< agent identifier
rocprofiler_queue_id_t queue_id; ///< queue identifier
rocprofiler_kernel_id_t kernel_id; ///< kernel identifier
} rocprofiler_buffer_tracing_memory_copy_record_t;
/**
* @brief ROCProfiler Buffer Kernel Dispatch Tracer Record.
* TODO(aelwazir): Add comments against every variable
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_agent_id_t agent_id;
rocprofiler_queue_id_t queue_id;
rocprofiler_kernel_id_t kernel_id;
uint32_t private_segment_size;
uint32_t group_segment_size;
rocprofiler_dim3_t workgroup_size;
rocprofiler_dim3_t grid_size;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_KERNEL_DISPATCH
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
rocprofiler_agent_id_t agent_id; ///< agent kernel was dispatched on
rocprofiler_queue_id_t queue_id; ///< queue kernel was dispatched on
rocprofiler_kernel_id_t kernel_id; ///< identifier for kernel
uint32_t private_segment_size; /// runtime private memory segment size
uint32_t group_segment_size; /// runtime group memory segment size
rocprofiler_dim3_t workgroup_size; /// runtime workgroup size (grid * threads)
rocprofiler_dim3_t grid_size; /// runtime grid size
} rocprofiler_buffer_tracing_kernel_dispatch_record_t;
/**
* @brief ROCProfiler Buffer Page Migration Tracer Record.
* TODO(aelwazir): Add comments against every variable
* @brief ROCProfiler Buffer Page Migration Tracer Record. Not implemented.
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_queue_id_t queue_id;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ROCPROFILER_BUFFER_TRACING_PAGE_MIGRATION
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
// Not Sure What is the info needed here?
} rocprofiler_buffer_tracing_page_migration_record_t;
/**
* @brief ROCProfiler Buffer Scratch Memory Tracer Record.
* TODO(aelwazir): Add comments against every variable
* @brief ROCProfiler Buffer Scratch Memory Tracer Record. Not implemented.
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_queue_id_t queue_id;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_SCRATCH_MEMORY
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
// Not Sure What is the info needed here?
} rocprofiler_buffer_tracing_scratch_memory_record_t;
/**
* @brief ROCProfiler Buffer Queue Scheduling Tracer Record.
* TODO(aelwazir): Add comments against every variable
* @brief ROCProfiler Buffer Queue Scheduling Tracer Record. Not implemented.
*/
typedef struct
{
uint64_t size;
rocprofiler_buffer_tracing_kind_t kind;
rocprofiler_correlation_id_t correlation_id;
rocprofiler_timestamp_t start_timestamp;
rocprofiler_timestamp_t end_timestamp;
rocprofiler_queue_id_t queue_id;
uint64_t size; ///< size of this struct
rocprofiler_buffer_tracing_kind_t kind; ///< ::ROCPROFILER_BUFFER_TRACING_SCRATCH_MEMORY
rocprofiler_correlation_id_t correlation_id; ///< correlation ids for record
rocprofiler_timestamp_t start_timestamp; ///< start time in nanoseconds
rocprofiler_timestamp_t end_timestamp; ///< end time in nanoseconds
// Not Sure What is the info needed here?
} rocprofiler_buffer_tracing_queue_scheduling_record_t;
// TODO(aelwazir): Review with Jonathan if Code Object is in the buffer tracing
/**
* @brief ROCProfiler Code Object Tracer Buffer Record.
*
* We need to guarantee that these records are in the buffer before the
* corresponding Exit Phase API calls are called.
*/
// typedef struct {
// rocprofiler_buffer_tracing_record_header_t header;
// rocprofiler_tracing_code_object_kind_id_t kind;
// } rocprofiler_buffer_tracing_code_object_header_t;
/**
* @brief ROCProfiler Code Object Load Tracer Buffer Record.
*
*/
// typedef struct {
// rocprofiler_buffer_tracing_code_object_header_t header;
// uint64_t load_base; // code object load base
// uint64_t load_size; // code object load size
// const char *uri; // URI string (NULL terminated)
// rocprofiler_timestamp_t timestamp;
// // uint32_t storage_type; // code object storage type (Need Review?)
// // int storage_file; // origin file descriptor (Need Review?)
// // uint64_t memory_base; // origin memory base (Need Review?)
// // uint64_t memory_size; // origin memory size (Need Review?)
// // uint64_t load_delta; // code object load delta (Need Review?)
// } rocprofiler_buffer_tracing_code_object_load_record_t;
/**
* @brief ROCProfiler Code Object UnLoad Tracer Buffer Record.
*
*/
// typedef struct {
// rocprofiler_buffer_tracing_code_object_header_t header;
// uint64_t load_base; // code object load base
// rocprofiler_timestamp_t timestamp;
// } rocprofiler_buffer_tracing_code_object_unload_record_t;
/**
* @brief ROCProfiler Code Object Kernel Symbol Tracer Buffer Record.
*
*/
// typedef struct {
// rocprofiler_buffer_tracing_code_object_header_t header;
// const char *kernel_name; // kernel name string (NULL terminated)
// uint64_t kernel_descriptor; // kernel descriptor (Need to be changed from
// // uint64_t to ::rocprofiler_address_t)
// // rocprofiler_timestamp_t timestamp; // (Need Review?)
// } rocprofiler_buffer_tracing_code_object_kernel_symbol_record_t;
/**
* @brief ROCProfiler Buffer External Correlation Tracer Record.
* @brief ROCProfiler Buffer External Correlation Tracer Record. Not implemented.
*/
typedef struct
{
@@ -243,20 +181,28 @@ typedef int (*rocprofiler_buffer_tracing_kind_operation_cb_t)(
/**
* @brief Configure Buffer Tracing Service.
*
* @param [in] context_id
* @param [in] kind
* @param [in] operations
* @param [in] operations_count
* @param [in] buffer_id
* @param [in] context_id Associated context to control activation of service
* @param [in] kind Buffer tracing category
* @param [in] operations Array of specific operations (if desired)
* @param [in] operations_count Number of specific operations (if non-null set of operations)
* @param [in] buffer_id Buffer to store the records in
* @return ::rocprofiler_status_t
* @retval ::ROCPROFILER_STATUS_ERROR_CONFIGURATION_LOCKED ::rocprofiler_configure initialization
* phase has passed
* @retval ::ROCPROFILER_STATUS_ERROR_CONTEXT_NOT_FOUND context is not valid
* @retval ::ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED Context has already been configured
* for the ::rocprofiler_buffer_tracing_kind_t kind
* @retval ::ROCPROFILER_STATUS_ERROR_KIND_NOT_FOUND Invalid ::rocprofiler_buffer_tracing_kind_t
* @retval ::ROCPROFILER_STATUS_ERROR_OPERATION_NOT_FOUND Invalid operation id for
* ::rocprofiler_buffer_tracing_kind_t kind was found
*
*/
rocprofiler_status_t ROCPROFILER_API
rocprofiler_status_t
rocprofiler_configure_buffer_tracing_service(rocprofiler_context_id_t context_id,
rocprofiler_buffer_tracing_kind_t kind,
rocprofiler_tracing_operation_t* operations,
size_t operations_count,
rocprofiler_buffer_id_t buffer_id);
rocprofiler_buffer_id_t buffer_id) ROCPROFILER_API;
/**
* @brief Query the name of the buffer tracing kind. The name retrieved from this function is a
@@ -307,20 +253,19 @@ rocprofiler_query_buffer_tracing_kind_operation_name(rocprofiler_buffer_tracing_
uint64_t* name_len) ROCPROFILER_API;
/**
* @brief Iterate over all the mappings of the buffer tracing kinds and get a buffer with the id
* mapped to a constant string. The strings provided in the arg will be valid pointers for the
* entire duration of the program. It is recommended to call this function once and cache this data
* in the client instead of making multiple on-demand calls.
* @brief Iterate over all the buffer tracing kinds and invokes the callback for each buffer tracing
* kind.
*
* TODO(aelwazir): to be modified
* This is typically used to invoke ::rocprofiler_iterate_buffer_tracing_kind_operations for each
* buffer tracing kind.
*
* @param [in] callback Callback function invoked for each enumeration value in @ref
* rocprofiler_buffer_tracing_kind_t with the exception of the `NONE` and `LAST` values.
* @param [in] data User data passed back into the callback
*/
rocprofiler_status_t ROCPROFILER_API
rocprofiler_iterate_buffer_tracing_kinds(rocprofiler_buffer_tracing_kind_cb_t callback, void* data)
ROCPROFILER_NONNULL(1);
rocprofiler_status_t
rocprofiler_iterate_buffer_tracing_kinds(rocprofiler_buffer_tracing_kind_cb_t callback,
void* data) ROCPROFILER_API ROCPROFILER_NONNULL(1);
/**
* @brief Iterates over all the operations for a given @ref
@@ -333,11 +278,11 @@ rocprofiler_iterate_buffer_tracing_kinds(rocprofiler_buffer_tracing_kind_cb_t ca
* rocprofiler_buffer_tracing_kind_t with the exception of the `NONE` and `LAST` values.
* @param [in] data User data passed back into the callback
*/
rocprofiler_status_t ROCPROFILER_API
rocprofiler_status_t
rocprofiler_iterate_buffer_tracing_kind_operations(
rocprofiler_buffer_tracing_kind_t kind,
rocprofiler_buffer_tracing_kind_operation_cb_t callback,
void* data) ROCPROFILER_NONNULL(2);
void* data) ROCPROFILER_API ROCPROFILER_NONNULL(2);
/** @} */