OpenKODE Core extension: KD_KHR_perfcounter


NameKHR_perfcounter
Name stringsKD_KHR_perfcounter
ContributorsAvi Shapira
ContactsOpenKODE working group, Khronos Group
StatusPrototype implemented
VersionVersion 2, 2007-03-23
NumberTBD
Dependencies Requires OpenKODE Core 1.0 Provisional. This extension is written based on the wording of the OpenKODE Core 1.0 Provisional specification.

1. Overview

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.

2. Recommended counter names

Although not mandatory, it is recommended that vendors use the following counter names, in order to promote interoperability.

2.1. CPU

  • "CPU X utilization"

  • "CPU X user mode utilization"

  • "CPU X kernel mode utilization"

where X is a decimal integer giving the CPU number.

2.2. Memory

  • "Physical memory usage"

  • "Virtual memory usage"

  • "Cache pages fault / sec"

2.3. I/O

  • "File read bytes / sec"

  • "File write bytes / sec"

  • "I/O read bytes / sec"

  • "I/O write bytes / sec."

2.4. Operating system

  • "Processes amount"

  • "Threads amount"

  • "Context switched / sec"

2.5. Graphic system

  • "Graphic driver utilization"

  • "GPU X utilization"

  • "GPU X vertex processors utilization"

  • "GPU X fragment processors utilization"

  • "GPU memory usage"

  • "Primitive count"

  • "Culled primitive count"

where X is a decimal integer giving the GPU number.

3. New constants

KD_INFINITE_COUNTER_VAL_KHR (KDINT64_MAX)

Defines an infinite counter value.

KD_UNKNOWN_COUNTER_VAL_KHR (-1)

Represents an unknown value.

4. New types

4.1. KDCounterInfoKHR

Information on a single performance counter.

Synopsis

typedef struct KDCounterInfoKHR {
    const KDchar *st_vendorName;
    const KDchar *st_name;
    const KDchar *st_description;
    KDint64 d_minValue;
    KDint64 d_maxValue;
    KDfloat32 d_defaultScale;
} KDCounterInfoKHR;

Description

st_vendorName

Counter vendor name.

st_name

Counter name (should be short).

st_description

Counter description (as detailed as possible).

d_minValue

Counter minimal value.

d_maxValue

Counter maximal value (can get KD_INFINITE_COUNTER_VAL_KHR).

d_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.

5. New functions

5.1. kdGetNumberOfCountersKHR

Return the number of performance counters.

Synopsis

typedef KDint (*PFNKDGETNUMBEROFCOUNTERSKHR)(void);

Description

This function retrieves the number of performance counters supported by the implementation.

Return value

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.

Error codes

To be defined.

5.2. kdGetCounterInformationKHR

Retrieve information on a performance counter.

Synopsis

typedef const KDCounterInfoKHR *(*PFNKDGETCOUNTERINFORMATIONKHR)(KDint index);

Description

This function retrieves information on counter number index. The index is 0-based.

Return value

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.

Error codes

To be defined.

5.3. kdActivateCountersKHR

Make counters active.

Synopsis

typedef KDint (*PFNKDACTIVATECOUNTERSKHR)(const KDint *indexes, KDint numindexes);

Description

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.

Return value

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.

Error codes

To be defined.

5.4. kdDeactivateCountersKHR

Makes counters inactive.

Synopsis

typedef KDint (*PFNKDDEACTIVATECOUNTERSKHR)(const KDint *indexes, KDint numindexes);

Description

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.

Return value

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.

Error codes

To be defined.

5.5. kdStartSamplingKHR

Start the performance counters sampling.

Synopsis

typedef KDint (*PFNKDSTARTSAMPLINGKHR)(void);

Description

This function initializes all performance counter values to 0 and starts the active ones sampling.

Return value

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.

Error codes

To be defined.

5.6. kdStopSamplingKHR

Stop the performance counters sampling.

Synopsis

typedef KDint (*PFNKDSTOPSAMPLINGKHR)(void);

Description

This function stops the active performance counters sampling.

Return value

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.

Error codes

To be defined.

5.7. kdGetCounterValuesKHR

Retrieves list of counter values.

Synopsis

typedef KDint (*PFNKDGETCOUNTERVALUESKHR)(const KDint *indexes, KDint numindexes, KDint64 *values);

Description

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.

Return value

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.

Error codes

To be defined.

6. Revision history

6.1. Version 2, 2007-03-23

Added contributor list and revision history. Added list of recommended counter names.

6.2. Version 1, 2007-01-31

Initial version.