| Name | KHR_perfcounter |
| Name strings | KD_KHR_perfcounter |
| Contributors | Avi Shapira, Yaki Tebeka |
| Contacts | OpenKODE working group, Khronos Group |
| Status | Approved by OpenKODE working group February 2008 |
| Version | Version 5, 2008-06-20 |
| Number | 2 |
| Dependencies | Requires OpenKODE Core 1.0. This extension is written based on the wording of the OpenKODE Core 1.0 specification. |
This extension provides a unified API through which different performance counter suppliers expose performance counters.
Performance counters suppliers may be:
CPU vendors - CPU utilization counters.
Operating systems: Counters related to memory, I/O, threads, etc.
Graphic system: Graphic driver utilization counters, graphic memory usage counters, GPU utilization counters, FPS, etc.
Any other program, system or service that would like to expose performance counters.
When this extension is present, its facilities are accessed by including its header file:
#include <KD/KHR_perfcounter.h>
Although not mandatory, it is recommended that vendors use the following counter names, in order to promote interoperability.
"CPU X utilization"
"CPU X user mode utilization"
"CPU X kernel mode utilization"
where X is a decimal integer giving the
CPU number.
"File read bytes / sec"
"File write bytes / sec"
"I/O read bytes / sec"
"I/O write bytes / sec"
Information on a single performance counter.
typedef struct KDCounterInfoKHR {
const KDchar *vendorName;
const KDchar *name;
const KDchar *description;
KDint64 minValue;
KDint64 maxValue;
KDfloat32 defaultScale;
} KDCounterInfoKHR;vendorName
Counter vendor name.
name
Counter name (should be short).
description
Counter description (as detailed as possible).
minValue
Counter minimal value.
maxValue
Counter maximal value (can get KD_INFINITE_COUNTER_VAL_KHR).
defaultScale
Scale factor that transforms the counter value to the [0,100] range.
Use KD_UNKNOWN_COUNTER_VAL_KHR for counters to which there is no predefined default scale.
Return the number of performance counters.
This function retrieves the number of performance counters supported by the implementation.
On success, the function returns the number of counters,
or 0 if none. On failure, the function returns -1
and stores
one of the error codes below into the error indicator
returned by kdGetError.
Retrieve information on a performance counter.
On success, the function returns a pointer to a
KDCounterInfoKHR structure giving information
on the requested counter.
On failure, the function returns KD_NULL
and stores
one of the error codes below into the error indicator
returned by kdGetError.
Make counters active.
This function activates the counters whose indexes appear in the
first numindexes elements of the array
indexes. Note that activating a lot of
counters may reduce system performance.
If numindexes is negative, or if
indexes is not a readable array
of at least numindexes KDint
values,
then undefined behavior results.
On success, the function returns 0.
On failure, it returns -1 and stores
one of the error codes below into the error indicator
returned by kdGetError.
Makes counters inactive.
This function deactivates the counters whose indexes appear in the
first numindexes elements of the array
indexes.
If numindexes is negative, or if
indexes is not a readable array
of at least numindexes KDint
values,
then undefined behavior results.
On success, the function returns 0.
On failure, it returns -1 and stores
one of the error codes below into the error indicator
returned by kdGetError.
Start the performance counters sampling.
This function initializes all performance counter values to 0 and starts the active ones sampling.
On success, the function returns 0.
On failure, it returns -1 and stores
one of the error codes below into the error indicator
returned by kdGetError.
Stop the performance counters sampling.
On success, the function returns 0.
On failure, it returns -1 and stores
one of the error codes below into the error indicator
returned by kdGetError.
Retrieves list of counter values.
This function stores counter values into the array
value. For each integer from 0 to
numindexes-1 inclusive, a
counter index is read out of that position in the
indexes array, and the current
value of the counter of that index is stored in the
corresponding position in the
values array.
If numindexes is negative, or if
indexes is not a readable array
of at least numindexes KDint
values,
or if values is not a writable array
of at least numindexes KDint64
elements,
then undefined behavior results.
On success, the function returns 0.
On failure, it returns -1 and stores
one of the error codes below into the error indicator
returned by kdGetError.
Functions are no longer declared as function pointer types. Used KDINT64_MAX for infinite counter value, since a counter value is a KDint64. Changed struct member names to match style of OpenKODE Core. Added definition of error codes.
Added contributor list and revision history. Added list of recommended counter names.