extensions/AMD/AMD_performance_monitor.txt

Name

    AMD_performance_monitor

Name Strings

    GL_AMD_performance_monitor

Contributors

    Dan Ginsburg
    Aaftab Munshi
    Dave Oldcorn
    Maurice Ribble
    Jonathan Zarge

Contact

    Dan Ginsburg (dan.ginsburg 'at' amd.com)

Status

    ???

Version

    Last Modified Date: 11/29/2007

Number

    OpenGL Extension #360
    OpenGL ES Extension #50

Dependencies

    None

Overview

    This extension enables the capture and reporting of performance monitors.
    Performance monitors contain groups of counters which hold arbitrary counted
    data.  Typically, the counters hold information on performance-related
    counters in the underlying hardware.  The extension is general enough to
    allow the implementation to choose which counters to expose and pick the
    data type and range of the counters.  The extension also allows counting to
    start and end on arbitrary boundaries during rendering.

Issues

    1.  Should this be an EGL or OpenGL/OpenGL ES extension?

        Decision - Make this an OpenGL/OpenGL ES extension

        Reason - We would like to expose this extension in both OpenGL and
        OpenGL ES which makes EGL an unsuitable choice.  Further, support for
        EGL is not a requirement and there are platforms that support OpenGL ES
        but not EGL, making it difficult to make this an EGL extension.

    2.  Should the API support multipassing?

        Decision - No.

        Reason - Multipassing should really be left to the application to do.
        This makes the API unnecessarily complicated.  A major issue is that
        depending on which counters are to be sampled, the # of passes and which
        counters get selected in each pass can be difficult to determine.  It is
        much easier to give a list of counters categorized by groups with
        specific information on the number of counters that can be selected from
        each group.

    3.  Should we define a 64-bit data type for UNSIGNED_INT64_AMD?

        Decision - No.

        Reason - While counters can be returned as 64-bit unsigned integers, the
        data is passed back to the application inside of a void*.  Therefore,
        there is no need in this extension to define a 64-bit data type (e.g.,
        GLuint64).  It will be up the application to declare a native 64-bit
        unsigned integer and cast the returned data to that type.


New Procedures and Functions

    void GetPerfMonitorGroupsAMD(int *numGroups, sizei groupsSize,
                                 uint *groups)

    void GetPerfMonitorCountersAMD(uint group, int *numCounters,
                                   int *maxActiveCounters, sizei countersSize,
                                   uint *counters)

    void GetPerfMonitorGroupStringAMD(uint group, sizei bufSize, sizei *length,
                                      char *groupString)

    void GetPerfMonitorCounterStringAMD(uint group, uint counter, sizei bufSize,
                                        sizei *length, char *counterString)

    void GetPerfMonitorCounterInfoAMD(uint group, uint counter,
                                      enum pname, void *data)

    void GenPerfMonitorsAMD(sizei n, uint *monitors)

    void DeletePerfMonitorsAMD(sizei n, uint *monitors)

    void SelectPerfMonitorCountersAMD(uint monitor, boolean enable,
                                      uint group, int numCounters,
                                      uint *counterList)

    void BeginPerfMonitorAMD(uint monitor)

    void EndPerfMonitorAMD(uint monitor)

    void GetPerfMonitorCounterDataAMD(uint monitor, enum pname, sizei dataSize,
                                      uint *data, int *bytesWritten)


New Tokens

    Accepted by the <pame> parameter of GetPerfMonitorCounterInfoAMD

        COUNTER_TYPE_AMD                           0x8BC0
        COUNTER_RANGE_AMD                          0x8BC1

    Returned as a valid value in <data> parameter of
    GetPerfMonitorCounterInfoAMD if <pname> = COUNTER_TYPE_AMD

        UNSIGNED_INT                               0x1405
        FLOAT                                      0x1406
        UNSIGNED_INT64_AMD                         0x8BC2
        PERCENTAGE_AMD                             0x8BC3

    Accepted by the <pname> parameter of GetPerfMonitorCounterDataAMD

        PERFMON_RESULT_AVAILABLE_AMD               0x8BC4
        PERFMON_RESULT_SIZE_AMD                    0x8BC5
        PERFMON_RESULT_AMD                         0x8BC6

Addition to the GL specification

    Add a new section called Performance Monitoring

    A performance monitor consists of a number of hardware and software counters
    that can be sampled by the GPU and reported back to the application.
    Performance counters are organized as a single hierarchy where counters are
    categorized into groups.  Each group has a list of counters that belong to
    the counter and can be sampled, and a maximum number of counters that can be
    sampled.

    The command

        void GetPerfMonitorGroupsAMD(int *numGroups, sizei groupsSize,
                                     uint *groups);

    returns the number of available groups in <numGroups>, if <numGroups> is
    not NULL.  If <groupsSize> is not 0 and <groups> is not NULL, then the list
    of available groups is returned.  The number of entries that will be
    returned in <groups> is determined by <groupsSize>.  If <groupsSize> is 0,
    no information is copied.  Each group is identified by a unique unsigned int
    identifier.

    The command

        void GetPerfMonitorCountersAMD(uint group, int *numCounters,
                                       int *maxActiveCounters,
                                       sizei countersSize,
                                       uint *counters);

    returns the following information.  For each group, it returns the number of
    available counters in <numCounters>, the max number of counters that can be
    active at any time in <maxActiveCounters>, and the list of counters in
    <counters>.  The number of entries that can be returned in <counters> is
    determined by <countersSize>.  If <countersSize> is 0, no information is
    copied. Each counter in a group is identified by a unique unsigned int
    identifier.  If <group> does not reference a valid group ID, an
    INVALID_VALUE error is generated.


    The command

        void GetPerfMonitorGroupStringAMD(uint group, sizei bufSize,
                                          sizei *length, char *groupString)


    returns the string that describes the group name identified by <group> in
    <groupString>.  The actual number of characters written to <groupString>,
    excluding the null terminator, is returned in <length>.  If <length> is
    NULL, then no length is returned.  The maximum number of characters that
    may be written into <groupString>, including the null terminator, is
    specified by <bufSize>.  If <bufSize> is 0 and <groupString> is NULL, the
    number of characters that would be required to hold the group string,
    excluding the null terminator, is returned in <length>.  If <group>
    does not reference a valid group ID, an INVALID_VALUE error is generated.


    The command

        void GetPerfMonitorCounterStringAMD(uint group, uint counter,
                                            sizei bufSize, sizei *length,
                                            char *counterString);


    returns the string that describes the counter name identified by <group>
    and <counter> in <counterString>.  The actual number of characters written
    to <counterString>, excluding the null terminator, is returned in <length>.
    If <length> is NULL, then no length is returned.  The maximum number of
    characters that may be written into <counterString>, including the null
    terminator, is specified by <bufSize>.  If <bufSize> is 0 and
    <counterString> is NULL, the number of characters that would be required to
    hold the counter string, excluding the null terminator, is returned in
    <length>.  If <group> does not reference a valid group ID, or <counter>
    does not reference a valid counter within the group ID, an INVALID_VALUE
    error is generated.

    The command

        void GetPerfMonitorCounterInfoAMD(uint group, uint counter,
                                          enum pname, void *data);

    returns the following information about a counter.  For a <counter>
    belonging to <group>, we can query the counter type and counter range.  If
    <pname> is COUNTER_TYPE_AMD, then <data> returns the type.  Valid type
    values returned are UNSIGNED_INT, UNSIGNED_INT64_AMD, PERCENTAGE_AMD, FLOAT.
    If type value returned is PERCENTAGE_AMD, then this describes a float
    value that is in the range [0.0 .. 100.0].  If <pname> is COUNTER_RANGE_AMD,
    <data> returns two values representing a minimum and a maximum. The
    counter's type is used to determine the format in which the range values
    are returned.  If <group> does not reference a valid group ID, or <counter>
    does not reference a valid counter within the group ID, an INVALID_VALUE
    error is generated.


    The command

        void GenPerfMonitorsAMD(sizei n, uint *monitors)

    returns a list of monitors.  These monitors can then be used to select
    groups/counters to be sampled, to start multiple monitoring sessions and to
    return counter information sampled by the GPU.  At creation time, the
    performance monitor object has all counters disabled.  The value of the
    PERFMON_RESULT_AVAILABLE_AMD, PERFMON_RESULT_AMD, and
    PERFMON_RESULT_SIZE_AMD queries will all initially be 0.

    The command

        void DeletePerfMonitorsAMD(sizei n, uint *monitors)

    is used to delete the list of monitors created by a previous call to
    GenPerfMonitors.  If a monitor ID in the list <monitors> does not
    reference a previously generated performance monitor, an INVALID_VALUE
    error is generated.

    The command

        void SelectPerfMonitorCountersAMD(uint monitor, boolean enable,
                                          uint group, int numCounters,
                                          uint *counterList);

    is used to enable or disable a list of counters from a group to be monitored
    as identified by <monitor>.  The <enable> argument determines whether the
    counters should be enabled or disabled.  <group> specifies the group
    ID under which counters will be enabled or disabled.  The <numCounters>
    argument gives the number of counters to be selected from the list
    <counterList>.  If <monitor> is not a valid monitor created by
    GenPerfMonitorsAMD, then INVALID_VALUE error will be generated.  If <group>
    is not a valid group, the INVALID_VALUE error will be generated.  If
    <numCounters> is less than 0, an INVALID_VALUE error will be generated.

    When SelectPerfMonitorCountersAMD is called on a monitor, any outstanding
    results for that monitor become invalidated and the result queries
    PERFMON_RESULT_SIZE_AMD and PERFMON_RESULT_AVAILABLE_AMD are reset to 0.

    The command

        void BeginPerfMonitorAMD(uint monitor);

    is used to start a monitor session.  Note that BeginPerfMonitor calls cannot
    be nested.  In addition, it is quite possible that given the list of groups
    and counters/group enabled for a monitor, it may not be able to sample the
    necessary counters and so the monitor session will fail.  In such a case,
    an INVALID_OPERATION error will be generated.

    While BeginPerfMonitorAMD does mark the beginning of performance counter
    collection, the counters do not begin collecting immediately.  Rather, the
    counters begin collection when BeginPerfMonitorAMD is processed by
    the hardware.  That is, the API is asynchronous, and performance counter
    collection does not begin until the graphics hardware processes the
    BeginPerfMonitorAMD command.

    The command

        void EndPerfMonitorAMD(uint monitor);

    ends a monitor session started by BeginPerfMonitorAMD.  If a performance
    monitor is not currently started, an INVALID_OPERATION error will be
    generated.

    Note that there is an implied overhead to collecting performance counters
    that may or may not distort performance depending on the implementation.
    For example, some counters may require a pipeline flush thereby causing a
    change in the performance of the application.  Further, the frequency at
    which an application samples may distort the accuracy of counters which are
    variant (e.g., non-deterministic based on the input).  While the effects
    of sampling frequency are implementation dependent, general guidance can
    be given that sampling at a high frequency may distort both performance
    of the application and the accuracy of variant counters.

    The command

        void GetPerfMonitorCounterDataAMD(uint monitor, enum pname,
                                          sizei dataSize,
                                          uint *data, sizei *bytesWritten);

    is used to return counter values that have been sampled for a monitor
    session.  If <pname> is PERFMON_RESULT_AVAILABLE_AMD, then <data> will
    indicate whether the result is available or not.  If <pname> is
    PERFMON_RESULT_SIZE_AMD, <data> will contain actual size of all counter
    results being sampled.  If <pname> is PERFMON_RESULT_AMD, <data> will
    contain results.  For each counter of a group that was selected to be
    sampled, the information is returned as group ID, followed by counter ID,
    followed by counter value.  The size of counter value returned will depend
    on the counter value type.  The argument <dataSize> specifies the number of
    bytes available in the <data> buffer for writing.  If <bytesWritten> is not
    NULL, it gives the number of bytes written into the <data> buffer.  It is an
    INVALID_OPERATION error for <data> to be NULL.  If <pname> is
    PERFMON_RESULT_AMD and <dataSize> is less than the number of bytes required
    to store the results as reported by a PERFMON_RESULT_SIZE_AMD query, then
    results will be written only up to the number of bytes specified by
    <dataSize>.

    If no BeginPerfMonitorAMD/EndPerfMonitorAMD has been issued for a monitor,
    then the result of querying for PERFMON_RESULT_AVAILABLE and
    PERFMON_RESULT_SIZE will be 0.  When SelectPerfMonitorCountersAMD is called
    on a monitor, the results stored for the monitor become invalidated and
    the value of PERFMON_RESULT_AVAILABLE and PERFMON_RESULT_SIZE queries should
    behave as if no BeginPerfMonitorAMD/EndPerfMonitorAMD has been issued for
    the monitor.

Errors

    INVALID_OPERATION error will be generated if BeginPerfMonitorAMD is unable
    to begin monitoring with the currently selected counters.

    INVALID_OPERATION error will be generated if BeginPerfMonitorAMD is called
    when a performance monitor is already active.

    INVALID_OPERATION error will be generated if EndPerfMonitorAMD is called
    when a performance monitor is not currently started.

    INVALID_VALUE error will be generated if the <group> parameter to
    GetPerfMonitorCountersAMD, GetPerfMonitorCounterStringAMD,
    GetPerfMonitorCounterStringAMD, GetPerfMonitorCounterInfoAMD, or
    SelectPerfMonitorCountersAMD does not reference a valid group ID.

    INVALID_VALUE error will be generated if the <counter> parameter to
    GetPerfMonitorCounterInfoAMD does not reference a valid counter ID
    in the group specified by <group>.

    INVALID_VALUE error will be generated if any of the monitor IDs
    in the <monitors> parameter to DeletePerfMonitorsAMD do not reference
    a valid generated monitor ID.

    INVALID_VALUE error will be generated if the <monitor> parameter to
    SelectPerfMonitorCountersAMD does not reference a monitor created by
    GenPerfMonitorsAMD.

    INVALID_VALUE error will be generated if the <numCounters> parameter to
    SelectPerfMonitorCountersAMD is less than 0.


New State

Sample Usage

    typedef struct
    {
            GLuint       *counterList;
            int         numCounters;
            int         maxActiveCounters;
    } CounterInfo;

    void
    getGroupAndCounterList(GLuint **groupsList, int *numGroups,
                           CounterInfo **counterInfo)
    {
        GLint          n;
        GLuint        *groups;
        CounterInfo   *counters;

        glGetPerfMonitorGroupsAMD(&n, 0, NULL);
        groups = (GLuint*) malloc(n * sizeof(GLuint));
        glGetPerfMonitorGroupsAMD(NULL, n, groups);
        *numGroups = n;

        *groupsList = groups;
        counters = (CounterInfo*) malloc(sizeof(CounterInfo) * n);
        for (int i = 0 ; i < n; i++ )
        {
            glGetPerfMonitorCountersAMD(groups[i], &counters[i].numCounters,
                                     &counters[i].maxActiveCounters, 0, NULL);

            counters[i].counterList = (GLuint*)malloc(counters[i].numCounters *
                                                      sizeof(int));

            glGetPerfMonitorCountersAMD(groups[i], NULL, NULL,
                                        counters[i].numCounters,
                                        counters[i].counterList);
        }

        *counterInfo = counters;
    }

    static int  countersInitialized = 0;

    int
    getCounterByName(char *groupName, char *counterName, GLuint *groupID,
                     GLuint *counterID)
    {
        int          numGroups;
        GLuint       *groups;
        CounterInfo  *counters;
        int          i = 0;

        if (!countersInitialized)
        {
            getGroupAndCounterList(&groups, &numGroups, &counters);
            countersInitialized = 1;
        }

        for ( i = 0; i < numGroups; i++ )
        {
           char curGroupName[256];
           glGetPerfMonitorGroupStringAMD(groups[i], 256, NULL, curGroupName);
           if (strcmp(groupName, curGroupName) == 0)
           {
               *groupID = groups[i];
               break;
           }
        }

        if ( i == numGroups )
            return -1;           // error - could not find the group name

        for ( int j = 0; j < counters[i].numCounters; j++ )
        {
            char curCounterName[256];

            glGetPerfMonitorCounterStringAMD(groups[i],
                                             counters[i].counterList[j],
                                             256, NULL, curCounterName);
            if (strcmp(counterName, curCounterName) == 0)
            {
                *counterID = counters[i].counterList[j];
                return 0;
            }
        }

        return -1;           // error - could not find the counter name
    }

    void
    drawFrameWithCounters(void)
    {
        GLuint group[2];
        GLuint counter[2];
        GLuint monitor;
        GLuint *counterData;

        // Get group/counter IDs by name.  Note that normally the
        // counter and group names need to be queried for because
        // each implementation of this extension on different hardware
        // could define different names and groups.  This is just provided
        // to demonstrate the API.
        getCounterByName("HW", "Hardware Busy", &group[0],
                         &counter[0]);
        getCounterByName("API", "Draw Calls", &group[1],
                         &counter[1]);

        // create perf monitor ID
        glGenPerfMonitorsAMD(1, &monitor);

        // enable the counters
        glSelectPerfMonitorCountersAMD(monitor, GL_TRUE, group[0], 1,
                                       &counter[0]);
        glSelectPerfMonitorCountersAMD(monitor, GL_TRUE, group[1], 1,
                                       &counter[1]);

        glBeginPerfMonitorAMD(monitor);

        // RENDER FRAME HERE
        // ...

        glEndPerfMonitorAMD(monitor);

        // read the counters
        GLint resultSize;
        glGetPerfMonitorCounterDataAMD(monitor, GL_PERFMON_RESULT_SIZE_AMD,
                                       sizeof(GLint), &resultSize, NULL);

        counterData = (GLuint*) malloc(resultSize);

        GLsizei bytesWritten;
        glGetPerfMonitorCounterDataAMD(monitor, GL_PERFMON_RESULT_AMD,
                                       resultSize, counterData, &bytesWritten);

        // display or log counter info
        GLsizei wordCount = 0;

        while ( (4 * wordCount) < bytesWritten )
        {
            GLuint groupId = counterData[wordCount];
            GLuint counterId = counterData[wordCount + 1];

            // Determine the counter type
            GLuint counterType;
            glGetPerfMonitorCounterInfoAMD(groupId, counterId,
                                           GL_COUNTER_TYPE_AMD, &counterType);

            if ( counterType == GL_UNSIGNED_INT64_AMD )
            {
                unsigned __int64 counterResult =
                           *(unsigned __int64*)(&counterData[wordCount + 2]);

                // Print counter result

                wordCount += 4;
            }
            else if ( counterType == GL_FLOAT )
            {
                float counterResult = *(float*)(&counterData[wordCount + 2]);

                // Print counter result

                wordCount += 3;
            }
            // else if ( ... ) check for other counter types
            //   (GL_UNSIGNED_INT and GL_PERCENTAGE_AMD)
        }
    }

Revision History
    11/29/2007 - dginsburg
       + Clarified the default state of a performance monitor object on creation

    11/09/2007 - dginsbur
       + Clarify what happens if SelectPerfMonitorCountersAMD is called on
         a monitor with outstanding query results.
       + Rename counterSize to countersSize
       + Remove some ';' typos

    06/13/2007 - dginsbur
       + Add language on the asynchronous nature of the API and
         counter accuracy/performance distortion.
       + Add myself as the contact
       + Remove INVALID_OPERATION error when countersList is NULL
       + Clarify 64-bit issue
       + Make PERCENTAGE_AMD counters float rather than uint
       + Clarify accuracy distortion on variant counters only
       + Tweak to overview language

    06/09/2007 - dginsbur
       + Fill in errors section and make many more errors explicit
       + Fix the example code so it compiles

    06/08/2007 - dginsbur
       + Modified GetPerfMonitorGroupString and GetPerfMonitorCounterString to
         be more client/server friendly.
       + Modified example.
       + Renamed parameters/variables to follow GL conventions.
       + Modified several 'int' param types to 'sizei'
       + Modifid counters type from 'int' to 'uint'
       + Renamed argument 'cb' and 'cbret'
       + Better documented GetPerfMonitorCounterData
       + Add AMD adornment in many places that were missing it

    06/07/2007 - dginsbur
       + Cleanup formatting, remove tabs, make fit in proper page width
       + Add FLOAT and UNSIGNED_INT to list of COUNTER_TYPEs
       + Fix some bugs in the example code
       + Rewrite introduction
       + Clarified Issue 1 reasoning
       + Added Issue 3 regarding use of 64-bit data types
       + Added revision history

    03/21/2007 - Initial version written.  Written by amunshi.