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

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

ROC Profiler: /home/docs/checkouts/readthedocs.org/user_builds/advanced-micro-devices-rocprofiler-docs/checkouts/docs-5.3.3/inc/rocprofiler.h Source File
inc
Go to the documentation of this file.
 /******************************************************************************
 Copyright (c) 2018 Advanced Micro Devices, Inc. All rights reserved.
  
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
  
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
  
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 *******************************************************************************/
  
 //
 // ROC Profiler API
 //
 // The goal of the implementation is to provide a HW specific low-level
 // performance analysis interface for profiling of GPU compute applications.
 // The profiling includes HW performance counters (PMC) with complex
 // performance metrics and traces.
 //
 // The library can be used by a tool library loaded by HSA runtime or by
 // higher level HW independent performance analysis API like PAPI.
 //
 // The library is written on C and will be based on AQLprofile AMD specific
 // HSA extension. The library implementation requires HSA API intercepting and
 // a profiling queue supporting a submit callback interface.
 //
  
 #ifndef INC_ROCPROFILER_H_
 #define INC_ROCPROFILER_H_
  
 #include <hsa/amd_hsa_kernel_code.h>
 #include <hsa/hsa.h>
 #include <hsa/hsa_ext_amd.h>
 #include <hsa/hsa_ven_amd_aqlprofile.h>
 #include <stdint.h>
  
 #define ROCPROFILER_VERSION_MAJOR 8
 #define ROCPROFILER_VERSION_MINOR 0
  
 #ifdef __cplusplus
 extern "C" {
 #endif  // __cplusplus
  
 // Returning library version
  
 uint32_t rocprofiler_version_major();
 uint32_t rocprofiler_version_minor();
  
 // Global properties structure
  
 typedef struct {
   uint32_t intercept_mode;
   uint32_t code_obj_tracking;
   uint32_t memcopy_tracking;
   uint32_t trace_size;
   uint32_t trace_local;
   uint64_t timeout;
   uint32_t timestamp_on;
   uint32_t hsa_intercepting;
   uint32_t k_concurrent;
   uint32_t opt_mode;
   uint32_t obj_dumping;
 } rocprofiler_settings_t;
  
 // Returning the error string method
  
 hsa_status_t rocprofiler_error_string(
     const char** str);  // [out] the API error string pointer returning
  
 // Profiling features and data
 //
 // Profiling features objects have profiling feature info, type, parameters and data
 // Also profiling data samplaes can be iterated using a callback
  
 // Profiling feature kind
 typedef enum {
   ROCPROFILER_FEATURE_KIND_METRIC = 0,
   ROCPROFILER_FEATURE_KIND_TRACE = 1,
   ROCPROFILER_FEATURE_KIND_SPM_MOD = 2,
   ROCPROFILER_FEATURE_KIND_PCSMP_MOD = 4
 } rocprofiler_feature_kind_t;
  
 // Profiling feture parameter
 typedef hsa_ven_amd_aqlprofile_parameter_t rocprofiler_parameter_t;
  
 // Profiling data kind
 typedef enum {
   ROCPROFILER_DATA_KIND_UNINIT = 0,
   ROCPROFILER_DATA_KIND_INT32 = 1,
   ROCPROFILER_DATA_KIND_INT64 = 2,
   ROCPROFILER_DATA_KIND_FLOAT = 3,
   ROCPROFILER_DATA_KIND_DOUBLE = 4,
   ROCPROFILER_DATA_KIND_BYTES = 5
 } rocprofiler_data_kind_t;
  
 // Profiling data type
 typedef struct {
   rocprofiler_data_kind_t kind;  // result kind
   union {
     uint32_t result_int32;  // 32bit integer result
     uint64_t result_int64;  // 64bit integer result
     float result_float;     // float single-precision result
     double result_double;   // float double-precision result
     struct {
       void* ptr;
       uint32_t size;
       uint32_t instance_count;
       bool copy;
     } result_bytes;  // data by ptr and byte size
   };
 } rocprofiler_data_t;
  
 // Profiling feature type
 typedef struct {
   rocprofiler_feature_kind_t kind;            // feature kind
   union {
     const char* name;                         // feature name
     struct {
       const char* block;                      // counter block name
       uint32_t event;                         // counter event id
     } counter;
   };
   const rocprofiler_parameter_t* parameters;  // feature parameters array
   uint32_t parameter_count;                   // feature parameters count
   rocprofiler_data_t data;                    // profiling data
 } rocprofiler_feature_t;
  
 // Profiling features set type
 typedef void rocprofiler_feature_set_t;
  
 // Profiling context
 //
 // Profiling context object accumuate all profiling information
  
 // Profiling context object
 typedef void rocprofiler_t;
  
 // Profiling group object
 typedef struct {
   unsigned index;                    // group index
   rocprofiler_feature_t** features;  // profiling info array
   uint32_t feature_count;            // profiling info count
   rocprofiler_t* context;            // context object
 } rocprofiler_group_t;
  
 // Profiling mode mask
 typedef enum {
   ROCPROFILER_MODE_STANDALONE = 1,   // standalone mode when ROC profiler supports a queue
   ROCPROFILER_MODE_CREATEQUEUE = 2,  // ROC profiler creates queue in standalone mode
   ROCPROFILER_MODE_SINGLEGROUP = 4   // only one group is allowed, failed otherwise
 } rocprofiler_mode_t;
  
 // Profiling handler, calling on profiling completion
 typedef bool (*rocprofiler_handler_t)(rocprofiler_group_t group, void* arg);
  
 // Profiling preperties
 typedef struct {
   hsa_queue_t* queue;             // queue for STANDALONE mode
                                   // the queue is created and returned in CREATEQUEUE mode
   uint32_t queue_depth;           // created queue depth
   rocprofiler_handler_t handler;  // handler on completion
   void* handler_arg;              // the handler arg
 } rocprofiler_properties_t;
  
 // Create new profiling context
 hsa_status_t rocprofiler_open(hsa_agent_t agent,                      // GPU handle
                               rocprofiler_feature_t* features,        // [in] profiling features array
                               uint32_t feature_count,                 // profiling info count
                               rocprofiler_t** context,                // [out] context object
                               uint32_t mode,                          // profiling mode mask
                               rocprofiler_properties_t* properties);  // profiling properties
  
 // Add feature to a features set
 hsa_status_t rocprofiler_add_feature(const rocprofiler_feature_t* feature,     // [in]
                                      rocprofiler_feature_set_t* features_set); // [in/out] profiling features set
  
 // Create new profiling context
 hsa_status_t rocprofiler_features_set_open(hsa_agent_t agent,                       // GPU handle
                                            rocprofiler_feature_set_t* features_set, // [in] profiling features set
                                            rocprofiler_t** context,                 // [out] context object
                                            uint32_t mode,                           // profiling mode mask
                                            rocprofiler_properties_t* properties);   // profiling properties
  
 // Delete profiling info
 hsa_status_t rocprofiler_close(rocprofiler_t* context);  // [in] profiling context
  
 // Context reset before reusing
 hsa_status_t rocprofiler_reset(rocprofiler_t* context,  // [in] profiling context
                                uint32_t group_index);   // group index
  
 // Return context agent
 hsa_status_t rocprofiler_get_agent(rocprofiler_t* context,        // [in] profiling context
                                    hsa_agent_t* agent);           // [out] GPU handle
  
 // Supported time value ID
 typedef enum {
   ROCPROFILER_TIME_ID_CLOCK_REALTIME = 0, // Linux realtime clock time
   ROCPROFILER_TIME_ID_CLOCK_REALTIME_COARSE = 1, // Linux realtime-coarse clock time
   ROCPROFILER_TIME_ID_CLOCK_MONOTONIC = 2, // Linux monotonic clock time
   ROCPROFILER_TIME_ID_CLOCK_MONOTONIC_COARSE = 3, // Linux monotonic-coarse clock time
   ROCPROFILER_TIME_ID_CLOCK_MONOTONIC_RAW = 4, // Linux monotonic-raw clock time
 } rocprofiler_time_id_t;
  
 // Return time value for a given time ID and profiling timestamp
 hsa_status_t rocprofiler_get_time(
   rocprofiler_time_id_t time_id, // identifier of the particular time to convert the timesatmp
   uint64_t timestamp, // profiling timestamp
   uint64_t* value_ns, // [out] returned time 'ns' value, ignored if NULL
   uint64_t* error_ns); // [out] returned time error 'ns' value, ignored if NULL
  
 // Queue callbacks
 //
 // Queue callbacks for initiating profiling per kernel dispatch and to wait
 // the profiling data on the queue destroy.
  
 // Dispatch record
 typedef struct {
   uint64_t dispatch;                                   // dispatch timestamp, ns
   uint64_t begin;                                      // kernel begin timestamp, ns
   uint64_t end;                                        // kernel end timestamp, ns
   uint64_t complete;                                   // completion signal timestamp, ns
 } rocprofiler_dispatch_record_t;
  
 // Profiling callback data
 typedef struct {
   hsa_agent_t agent;                                   // GPU agent handle
   uint32_t agent_index;                                // GPU index
   const hsa_queue_t* queue;                            // HSA queue
   uint64_t queue_index;                                // Index in the queue
   uint32_t queue_id;                                   // Queue id
   hsa_signal_t completion_signal;                      // Completion signal
   const hsa_kernel_dispatch_packet_t* packet;          // HSA dispatch packet
   const char* kernel_name;                             // Kernel name
   uint64_t kernel_object;                              // Kernel object address
   const amd_kernel_code_t* kernel_code;                // Kernel code pointer
   uint32_t thread_id;                                   // Thread id
   const rocprofiler_dispatch_record_t* record;         // Dispatch record
 } rocprofiler_callback_data_t;
  
 // Profiling callback type
 typedef hsa_status_t (*rocprofiler_callback_t)(
     const rocprofiler_callback_data_t* callback_data,  // [in] callback data
     void* user_data,                                   // [in/out] user data passed to the callback
     rocprofiler_group_t* group);                       // [out] returned profiling group
  
 // Queue callbacks
 typedef struct {
     rocprofiler_callback_t dispatch;                          // dispatch callback
     hsa_status_t (*create)(hsa_queue_t* queue, void* data);   // create callback
     hsa_status_t (*destroy)(hsa_queue_t* queue, void* data);  // destroy callback
 } rocprofiler_queue_callbacks_t;
  
 // Set queue callbacks
 hsa_status_t rocprofiler_set_queue_callbacks(
     rocprofiler_queue_callbacks_t callbacks,           // callbacks
     void* data);                                       // [in/out] passed callbacks data
  
 // Remove queue callbacks
 hsa_status_t rocprofiler_remove_queue_callbacks();
  
 // Start/stop queue callbacks
 hsa_status_t rocprofiler_start_queue_callbacks();
 hsa_status_t rocprofiler_stop_queue_callbacks();
  
 // Start/stop profiling
 //
 // Start/stop the context profiling invocation, have to be as many as
 // contect.invocations' to collect all profiling data
  
 // Start profiling
 hsa_status_t rocprofiler_start(rocprofiler_t* context,     // [in/out] profiling context
                                uint32_t group_index);      // group index
  
 // Stop profiling
 hsa_status_t rocprofiler_stop(rocprofiler_t* context,     // [in/out] profiling context
                               uint32_t group_index);      // group index
  
 // Read profiling
 hsa_status_t rocprofiler_read(rocprofiler_t* context,     // [in/out] profiling context
                               uint32_t group_index);      // group index
  
 // Read profiling data
 hsa_status_t rocprofiler_get_data(rocprofiler_t* context, // [in/out] profiling context
                                   uint32_t group_index);  // group index
  
 // Get profiling groups count
 hsa_status_t rocprofiler_group_count(const rocprofiler_t* context,  // [in] profiling context
                                      uint32_t* group_count);        // [out] profiling groups count
  
 // Get profiling group for a given index
 hsa_status_t rocprofiler_get_group(rocprofiler_t* context,       // [in] profiling context
                                    uint32_t group_index,         // profiling group index
                                    rocprofiler_group_t* group);  // [out] profiling group
  
 // Start profiling
 hsa_status_t rocprofiler_group_start(rocprofiler_group_t* group);  // [in/out] profiling group
  
 // Stop profiling
 hsa_status_t rocprofiler_group_stop(rocprofiler_group_t* group);  // [in/out] profiling group
  
 // Read profiling
 hsa_status_t rocprofiler_group_read(rocprofiler_group_t* group);  // [in/out] profiling group
  
 // Get profiling data
 hsa_status_t rocprofiler_group_get_data(rocprofiler_group_t* group);  // [in/out] profiling group
  
 // Get metrics data
 hsa_status_t rocprofiler_get_metrics(const rocprofiler_t* context);  // [in/out] profiling context
  
 // Definition of output data iterator callback
 typedef hsa_ven_amd_aqlprofile_data_callback_t rocprofiler_trace_data_callback_t;
  
 // Method for iterating the events output data
 hsa_status_t rocprofiler_iterate_trace_data(
     rocprofiler_t* context,                      // [in] profiling context
     rocprofiler_trace_data_callback_t callback,  // callback to iterate the output data
     void* data);                                 // [in/out] callback data
  
 // Profiling features and data
 //
 // Profiling features objects have profiling feature info, type, parameters and data
 // Also profiling data samplaes can be iterated using a callback
  
 // Profiling info kind
 typedef enum {
   ROCPROFILER_INFO_KIND_METRIC = 0, // metric info
   ROCPROFILER_INFO_KIND_METRIC_COUNT = 1, // metric features count, int32
   ROCPROFILER_INFO_KIND_TRACE = 2, // trace info
   ROCPROFILER_INFO_KIND_TRACE_COUNT = 3, // trace features count, int32
   ROCPROFILER_INFO_KIND_TRACE_PARAMETER = 4, // trace parameter info
   ROCPROFILER_INFO_KIND_TRACE_PARAMETER_COUNT = 5 // trace parameter count, int32
 } rocprofiler_info_kind_t;
  
 // Profiling info query
 typedef union {
   rocprofiler_info_kind_t info_kind; // queried profiling info kind
   struct {
     const char* trace_name; // queried info trace name
   } trace_parameter;
 } rocprofiler_info_query_t;
  
 // Profiling info data
 typedef struct {
   uint32_t agent_index; // GPU HSA agent index
   rocprofiler_info_kind_t kind; // info data kind
   union {
     struct {
       const char* name; // metric name
       uint32_t instances; // instances number
       const char* expr; // metric expression, NULL for basic counters
       const char* description; // metric description
       const char* block_name; // block name
       uint32_t block_counters; // number of block counters
     } metric;
     struct {
       const char* name; // trace name
       const char* description; // trace description
       uint32_t parameter_count; // supported by the trace number parameters
     } trace;
     struct {
       uint32_t code; // parameter code
       const char* trace_name; // trace name
       const char* parameter_name; // parameter name
       const char* description; // trace parameter description
     } trace_parameter;
   };
 } rocprofiler_info_data_t;
  
 // Return the info for a given info kind
 hsa_status_t rocprofiler_get_info(
   const hsa_agent_t* agent, // [in] GFXIP handle
   rocprofiler_info_kind_t kind, // kind of iterated info
   void *data); // [in/out] returned data
  
 // Iterate over the info for a given info kind, and invoke an application-defined callback on every iteration
 hsa_status_t rocprofiler_iterate_info(
   const hsa_agent_t* agent, // [in] GFXIP handle
   rocprofiler_info_kind_t kind, // kind of iterated info
   hsa_status_t (*callback)(const rocprofiler_info_data_t info, void *data), // callback
   void *data); // [in/out] data passed to callback
  
 // Iterate over the info for a given info query, and invoke an application-defined callback on every iteration
 hsa_status_t rocprofiler_query_info(
   const hsa_agent_t *agent, // [in] GFXIP handle
   rocprofiler_info_query_t query, // iterated info query
   hsa_status_t (*callback)(const rocprofiler_info_data_t info, void *data), // callback
   void *data); // [in/out] data passed to callback
  
 // Create a profiled queue. All dispatches on this queue will be profiled
 hsa_status_t rocprofiler_queue_create_profiled(
   hsa_agent_t agent_handle,uint32_t size, hsa_queue_type32_t type,
   void (*callback)(hsa_status_t status, hsa_queue_t* source, void* data),
   void* data, uint32_t private_segment_size, uint32_t group_segment_size,
   hsa_queue_t** queue);
  
 // Profiling pool
 //
 // Support for profiling contexts pool
 // The API provide capability to create a contexts pool for a given agent and a set of features,
 // to fetch/relase a context entry, to register a callback for the contexts completion.
  
 // Profiling pool handle
 typedef void rocprofiler_pool_t;
  
 // Profiling pool entry
 typedef struct {
   rocprofiler_t* context;             // context object
   void* payload;                      // payload data object
 } rocprofiler_pool_entry_t;
  
 // Profiling handler, calling on profiling completion
 typedef bool (*rocprofiler_pool_handler_t)(const rocprofiler_pool_entry_t* entry, void* arg);
  
 // Profiling preperties
 typedef struct {
   uint32_t num_entries;                // pool size entries
   uint32_t payload_bytes;              // payload size bytes
   rocprofiler_pool_handler_t handler;  // handler on context completion
   void* handler_arg;                   // the handler arg
 } rocprofiler_pool_properties_t;
  
 // Open profiling pool
 hsa_status_t rocprofiler_pool_open(
   hsa_agent_t agent,                   // GPU handle
   rocprofiler_feature_t* features,     // [in] profiling features array
   uint32_t feature_count,              // profiling info count
   rocprofiler_pool_t** pool,           // [out] context object
   uint32_t mode,                       // profiling mode mask
   rocprofiler_pool_properties_t*);     // pool properties
  
 // Close profiling pool
 hsa_status_t rocprofiler_pool_close(
   rocprofiler_pool_t* pool);          // profiling pool handle
  
 // Fetch profiling pool entry
 hsa_status_t rocprofiler_pool_fetch(
   rocprofiler_pool_t* pool,           // profiling pool handle
   rocprofiler_pool_entry_t* entry);   // [out] empty profiling pool entry
  
 // Release profiling pool entry
 hsa_status_t rocprofiler_pool_release(
   rocprofiler_pool_entry_t* entry);   // released profiling pool entry
  
 // Iterate fetched profiling pool entries
 hsa_status_t rocprofiler_pool_iterate(
   rocprofiler_pool_t* pool,           // profiling pool handle
   hsa_status_t (*callback)(rocprofiler_pool_entry_t* entry, void* data), // callback
   void *data); // [in/out] data passed to callback
  
 // Flush completed entries in profiling pool
 hsa_status_t rocprofiler_pool_flush(
   rocprofiler_pool_t* pool);          // profiling pool handle
  
 // HSA intercepting API
  
 // HSA callbacks ID enumeration
 typedef enum {
   ROCPROFILER_HSA_CB_ID_ALLOCATE = 0, // Memory allocate callback
   ROCPROFILER_HSA_CB_ID_DEVICE = 1,   // Device assign callback
   ROCPROFILER_HSA_CB_ID_MEMCOPY = 2,  // Memcopy callback
   ROCPROFILER_HSA_CB_ID_SUBMIT = 3,   // Packet submit callback
   ROCPROFILER_HSA_CB_ID_KSYMBOL = 4,  // Loading/unloading of kernel symbol
   ROCPROFILER_HSA_CB_ID_CODEOBJ = 5   // Loading/unloading of kernel symbol
 } rocprofiler_hsa_cb_id_t;
  
 // HSA callback data type
 typedef struct {
   union {
     struct {
       const void* ptr;                                // allocated area ptr
       size_t size;                                    // allocated area size, zero size means 'free' callback
       hsa_amd_segment_t segment;                      // allocated area's memory segment type
       hsa_amd_memory_pool_global_flag_t global_flag;  // allocated area's memory global flag
       int is_code;                                    // equal to 1 if code is allocated
     } allocate;
     struct {
       hsa_device_type_t type;                         // type of assigned device
       uint32_t id;                                    // id of assigned device
       hsa_agent_t agent;                              // device HSA agent handle
       const void* ptr;                                // ptr the device is assigned to
     } device;
     struct {
       const void* dst;                                // memcopy dst ptr
       const void* src;                                // memcopy src ptr
       size_t size;                                    // memcopy size bytes
     } memcopy;
     struct {
       const void* packet;                             // submitted to GPU packet
       const char* kernel_name;                        // kernel name, not NULL if dispatch
       hsa_queue_t* queue;                             // HSA queue the kernel was submitted to
       uint32_t device_type;                           // type of device the packed is submitted to
       uint32_t device_id;                             // id of device the packed is submitted to
     } submit;
     struct {
       uint64_t object;                                // kernel symbol object
       const char* name;                               // kernel symbol name
       uint32_t name_length;                           // kernel symbol name length
       int unload;                                     // symbol executable destroy
     } ksymbol;
     struct {
       uint32_t storage_type;                          // code object storage type
       int storage_file;                               // origin file descriptor
       uint64_t memory_base;                           // origin memory base
       uint64_t memory_size;                           // origin memory size
       uint64_t load_base;                             // codeobj load base
       uint64_t load_size;                             // codeobj load size
       uint64_t load_delta;                            // codeobj load size
       uint32_t uri_length;                            // URI string length
       char* uri;                                      // URI string
       int unload;                                     // unload flag
     } codeobj;
   };
 } rocprofiler_hsa_callback_data_t;
  
 // HSA callback function type
 typedef hsa_status_t (*rocprofiler_hsa_callback_fun_t)(
   rocprofiler_hsa_cb_id_t id, // callback id
   const rocprofiler_hsa_callback_data_t* data, // [in] callback data
   void* arg); // [in/out] user passed data
  
 // HSA callbacks structure
 typedef struct {
   rocprofiler_hsa_callback_fun_t allocate; // memory allocate callback
   rocprofiler_hsa_callback_fun_t device; // agent assign callback
   rocprofiler_hsa_callback_fun_t memcopy; // memory copy callback
   rocprofiler_hsa_callback_fun_t submit; // packet submit callback
   rocprofiler_hsa_callback_fun_t ksymbol; // kernel symbol callback
   rocprofiler_hsa_callback_fun_t codeobj; // codeobject load/unload callback
 } rocprofiler_hsa_callbacks_t;
  
 // Set callbacks. If the callback is NULL then it is disabled.
 // If callback returns a value that is not HSA_STATUS_SUCCESS the  callback
 // will be unregistered.
 hsa_status_t rocprofiler_set_hsa_callbacks(
   const rocprofiler_hsa_callbacks_t callbacks, // HSA callback function
   void* arg); // callback user data
  
 #ifdef __cplusplus
 }  // extern "C" block
 #endif  // __cplusplus
  
 #endif  // INC_ROCPROFILER_H_