Name String
cl_codeplay_performance_counters
Contact
Kenneth Benzie, Codeplay Software Ltd. (k.benzie at codeplay.com)
Contributors
Kenneth Benzie, Codeplay Software Ltd.
Ewan Crawford, Codeplay Software Ltd.
Version
Version 1, June 17, 2019
Number
OpenCL Extension #XX
Status
Proposal
Dependencies
OpenCL 1.2 and the cl_khr_create_command_queue extension are required.
Overview
The performance counter extension grants the application access to performance counters to determine the runtime characteristics of executed commands.
New API Enums
Accepted as param_name parameter to clGetDeviceInfo:
Enumeration |
Value |
|---|---|
CL_DEVICE_PERFORMANCE_COUNTERS_CODEPLAY |
0x4260 |
Accepted as a key in the properties key value array parameter to clCreateCommandQueueWithPropertiesKHR:
Enumeration |
Value |
|---|---|
CL_QUEUE_PERFORMANCE_COUNTERS_CODEPLAY |
0x4261 |
Accepted as param_name parameter to clGetEventProfilingInfo:
Enumeration |
Value |
|---|---|
CL_PROFILING_COMMAND_PERFORMANCE_COUNTERS_CODEPLAY |
0x4262 |
Accepted as unit member of cl_performance_counter_codeplay:
Enumeration |
Value |
|---|---|
CL_PERFORMANCE_COUNTER_UNIT_GENERIC_CODEPLAY |
0x0 |
CL_PERFORMANCE_COUNTER_UNIT_PERCENTAGE_CODEPLAY |
0x1 |
CL_PERFORMANCE_COUNTER_UNIT_NANOSECONDS_CODEPLAY |
0x2 |
CL_PERFORMANCE_COUNTER_UNIT_BYTES_CODEPLAY |
0x3 |
CL_PERFORMANCE_COUNTER_UNIT_BYTES_PER_SECOND_CODEPLAY |
0x4 |
CL_PERFORMANCE_COUNTER_UNIT_KELVIN_CODEPLAY |
0x5 |
CL_PERFORMANCE_COUNTER_UNIT_WATTS_CODEPLAY |
0x6 |
CL_PERFORMANCE_COUNTER_UNIT_VOLTS_CODEPLAY |
0x7 |
CL_PERFORMANCE_COUNTER_UNIT_AMPS_CODEPLAY |
0x8 |
CL_PERFORMANCE_COUNTER_UNIT_HERTZ_CODEPLAY |
0x9 |
CL_PERFORMANCE_COUNTER_UNIT_CYCLES_CODEPLAY |
0xA |
Accepted as storage member of cl_performance_counter_codeplay:
Enumeration |
Value |
|---|---|
CL_PERFORMANCE_COUNTER_RESULT_TYPE_INT32_CODEPLAY |
0x0 |
CL_PERFORMANCE_COUNTER_RESULT_TYPE_INT64_CODEPLAY |
0x1 |
CL_PERFORMANCE_COUNTER_RESULT_TYPE_UINT32_CODEPLAY |
0x2 |
CL_PERFORMANCE_COUNTER_RESULT_TYPE_UINT64_CODEPLAY |
0x3 |
CL_PERFORMANCE_COUNTER_RESULT_TYPE_FLOAT32_CODEPLAY |
0x4 |
CL_PERFORMANCE_COUNTER_RESULT_TYPE_FLOAT64_CODEPLAY |
0x5 |
New API Structures
Accepted as param_value parameter to clGetDeviceInfo:
typedef struct cl_performance_counter_codeplay {
cl_performance_counter_unit_codeplay unit;
cl_performance_counter_storage_codeplay storage;
cl_uint uuid;
char name[256];
char category[256];
char description[256];
} cl_performance_counter_codeplay;
Accepted as descs member of cl_performance_counter_config_codeplay:
typedef struct cl_performance_counter_desc_codeplay {
cl_uint uuid;
void* data;
} cl_performance_counter_desc_codeplay;
Accepted as a value in the properties key value array parameter to clCreateCommandQueueWithPropertiesKHR:
typedef struct cl_performance_counter_config_codeplay {
cl_uint count;
cl_performance_counter_desc_codeplay* descs;
} cl_performance_counter_config_codeplay;
Accepted as param_value parameter to clGetEventProfilingInfo:
typedef struct cl_performance_counter_result_codeplay {
union {
cl_int int32;
cl_long int64;
cl_uint uint32;
cl_ulong uint64;
cl_float float32;
cl_double float64;
};
} cl_performance_counter_result_codeplay;
Modifications to the OpenCL API Specification
Add a new row to OpenCL 1.2 specification - “Table 4.3 OpenCL Device Queries”
Column |
Text |
|---|---|
cl_device_info |
CL_DEVICE_PERFORMANCE_COUNTERS_CODEPLAY |
Return Type |
cl_performance_counter_codeplay[] |
Description |
Returns a list of performance counters supported by device. This is an array of cl_performance_counter_codeplay structures. Each item in the list describes the unit of measurement, storage type, unique identifier, name, category, and description of a performance counter which can be enabled. This information is intended for use in profiling tools. If the device does not support performance counters param_value_size_ret will return a value of 0. |
Add a new row to OpenCL 1.2 extension specification - “Table 9.22.1 List of supported cl_queue_properties values and description.”
Column |
Text |
|---|---|
Queue Properties |
CL_QUEUE_PERFORMANCE_COUNTERS_CODEPLAY |
Property Value |
cl_performance_counter_config_codeplay* |
Description |
This property value is a pointer to a cl_performance_counter_config_codeplay structure containing a count specifying the number of enabled counters and the descs array of cl_performance_counter_desc_codeplay structures specifying which performance counters are to be enabled defined by uuid the unique identifier of the counter attained using the CL_DEVICE_PERFORMANCE_COUNTERS_CODEPLAY clGetDeviceInfo query. The data member is an optional extension point for further configurability of performance counters. |
Add a new row to OpenCL 1.2 specification - “Table 5.19 clGetEventProfilingInfo parameter queries”
Column |
Text |
|---|---|
cl_profiling_info |
CL_PROFILING_COMMAND_PERFORMANCE_COUNTERS_CODEPLAY |
Return Type |
cl_performance_counter_result_codeplay[] |
Description |
Returns a list of performance counter results. This is an array of cl_performance_counter_result_codeplay structures, the order of results matches the order the counters were enabled at command queue creation. Each item in the list contains a result value in one of the union members defined by the storage type of the associated (has the same uuid) performance counter attained using the CL_DEVICE_PERFORMANCE_COUNTERS_CODEPLAY clGetDeviceInfo query. If the event is a user event, or the command queue associated with the event was not created with performance counters enabled CL_INVALID_VALUE will be returned. |
Revision History
Rev |
Data |
Author |
Changes |
|---|---|---|---|
1 |
2019/06/17 |
Kenneth Benzie |
Initial proposal |
2 |
2021/06/30 |
Ewan Crawford |
Use enums from Codeplay reserved Khronos range |
