283 lines
13 KiB
C
Executable File
283 lines
13 KiB
C
Executable File
/*!***********************************************************************
|
|
|
|
@file PVRScopeStats.h
|
|
@copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved.
|
|
@brief PVRScopeStats header file. @copybrief ScopeStats
|
|
|
|
**************************************************************************/
|
|
|
|
/*! @mainpage PVRScope
|
|
|
|
@section overview Library Overview
|
|
*****************************
|
|
PVRScope is a utility library which has two functionalities:
|
|
\li @ref ScopeStats is used to access the hardware performance counters in
|
|
PowerVR hardware via a driver library called PVRScopeServices.
|
|
\li @ref ScopeComms allows an application to send user defined information to
|
|
PVRTune via PVRPerfServer, both as counters and marks, or as editable data that can be
|
|
passed back to the application.
|
|
|
|
PVRScope is supplied in the PVRScope.h header file. Your application also needs to link to the PVRScope
|
|
library file, either a <tt>.lib</tt>, <tt>.so</tt>, or <tt>.dy</tt> file, depending on your platform.
|
|
|
|
For more information on PVRScope, see the <em>PVRScope User Manual</em>.
|
|
|
|
@subsection limitStats PVRScopeStats Limitations
|
|
*****************************
|
|
@copydetails ScopeStats
|
|
|
|
@subsection limitComms PVRScopeComms Limitations
|
|
*****************************
|
|
@copydetails ScopeComms
|
|
*/
|
|
|
|
#ifndef _PVRSCOPESTATS_H_
|
|
#define _PVRSCOPESTATS_H_
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*!
|
|
@addtogroup ScopeStats PVRScopeStats
|
|
@brief The PVRScopeStats functionality of PVRScope is used to access the hardware performance counters in
|
|
PowerVR hardware via a driver library called PVRScopeServices.
|
|
@details PVRScopeStats has the following limitations:
|
|
\li Only one instance of @ref ScopeStats may communicate with PVRScopeServices at any
|
|
given time. If a PVRScope enabled application attempts to communicate with
|
|
PVRScopeServices at the same time as another such application, or at the same time as
|
|
PVRPerfServer, conflicts can occur that may make performance data unreliable.
|
|
\li Performance counters can only be read on devices whose drivers have been built with
|
|
hardware profiling enabled. This configuration is the default in most production drivers due to negligible overhead.
|
|
\li Performance counters contain the average value of that counter since the last time the counter was interrogated.
|
|
@{
|
|
*/
|
|
|
|
/****************************************************************************
|
|
** Includes
|
|
****************************************************************************/
|
|
|
|
/****************************************************************************
|
|
** Enums
|
|
****************************************************************************/
|
|
|
|
/*!**************************************************************************
|
|
@enum EPVRScopeInitCode
|
|
@brief PVRScope initialisation return codes.
|
|
****************************************************************************/
|
|
enum EPVRScopeInitCode
|
|
{
|
|
ePVRScopeInitCodeOk, ///< Initialisation OK
|
|
ePVRScopeInitCodeOutOfMem, ///< Out of memory
|
|
ePVRScopeInitCodeDriverSupportNotFound, ///< Driver support not found
|
|
ePVRScopeInitCodeDriverSupportInsufficient, ///< Driver support insufficient
|
|
ePVRScopeInitCodeDriverSupportInitFailed, ///< Driver support initialisation failed
|
|
ePVRScopeInitCodeDriverSupportQueryInfoFailed ///< Driver support information query failed
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@enum EPVRScopeStandardCounter
|
|
@brief Set of "standard" counters, just a few of the total list of
|
|
counters.
|
|
****************************************************************************/
|
|
enum EPVRScopeStandardCounter
|
|
{
|
|
ePVRScopeStandardCounter_FPS, ///< Total device FPS
|
|
ePVRScopeStandardCounter_Load_2D, ///< 2D core load
|
|
ePVRScopeStandardCounter_Load_Renderer, ///< Renderer core load
|
|
ePVRScopeStandardCounter_Load_Tiler, ///< Tiler core load
|
|
ePVRScopeStandardCounter_Load_Compute, ///< Compute core load
|
|
ePVRScopeStandardCounter_Load_Shader_Pixel, ///< Shader core load due to pixels
|
|
ePVRScopeStandardCounter_Load_Shader_Vertex, ///< Shader core load due to vertices
|
|
ePVRScopeStandardCounter_Load_Shader_Compute, ///< Shader core load due to compute
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@enum EPVRScopeEvent
|
|
@brief Set of PVRScope event types.
|
|
****************************************************************************/
|
|
enum EPVRScopeEvent
|
|
{
|
|
ePVRScopeEventComputeBegin, ///< Compute begin
|
|
ePVRScopeEventComputeEnd, ///< Compute end
|
|
ePVRScopeEventTABegin, ///< TA begin
|
|
ePVRScopeEventTAEnd, ///< TA end
|
|
ePVRScopeEvent3DBegin, ///< 3D begin
|
|
ePVRScopeEvent3DEnd, ///< 3D end
|
|
ePVRScopeEvent2DBegin, ///< 2D begin
|
|
ePVRScopeEvent2DEnd, ///< 2D end
|
|
ePVRScopeEventRTUBegin, ///< RTU begin
|
|
ePVRScopeEventRTUEnd, ///< RTU end
|
|
ePVRScopeEventSHGBegin, ///< SHG begin
|
|
ePVRScopeEventSHGEnd, ///< SHG end
|
|
};
|
|
|
|
/****************************************************************************
|
|
** Structures
|
|
****************************************************************************/
|
|
|
|
// Internal implementation data
|
|
struct SPVRScopeImplData;
|
|
|
|
/*!**************************************************************************
|
|
@struct SPVRScopeCounterDef
|
|
@brief Definition of a counter that PVRScope calculates.
|
|
****************************************************************************/
|
|
struct SPVRScopeCounterDef
|
|
{
|
|
const char *pszName; ///< Counter name, null terminated
|
|
int nBoolPercentage; ///< true if the counter is a percentage
|
|
unsigned int nGroup; ///< The counter group that the counter is in.
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SPVRScopeCounterReading
|
|
@brief A set of return values resulting from querying the counter values.
|
|
****************************************************************************/
|
|
struct SPVRScopeCounterReading
|
|
{
|
|
float *pfValueBuf; ///< Array of returned values
|
|
unsigned int nValueCnt; ///< Number of values set in the above array
|
|
unsigned int nReadingActiveGroup; ///< Group that was active when counters were sampled
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SPVRScopeGetInfo
|
|
@brief A set of return values holding miscellaneous PVRScope information.
|
|
****************************************************************************/
|
|
struct SPVRScopeGetInfo
|
|
{
|
|
unsigned int nGroupMax; ///< Highest group number of any counter
|
|
};
|
|
|
|
/*!**************************************************************************
|
|
@struct SPVRScopeTimingPacket
|
|
@brief A start or end time.
|
|
****************************************************************************/
|
|
struct SPVRScopeTimingPacket
|
|
{
|
|
enum EPVRScopeEvent eEventType; ///< Event type
|
|
double dTime; ///< Event time (seconds)
|
|
unsigned int nPID; ///< Event PID
|
|
};
|
|
|
|
/****************************************************************************
|
|
** Declarations
|
|
****************************************************************************/
|
|
|
|
const char *PVRScopeGetDescription(); ///< Query the PVRScope library description
|
|
|
|
|
|
/*!**************************************************************************
|
|
@brief Initialise @ref ScopeStats, to access the HW performance counters in PowerVR.
|
|
@return EPVRScopeInitCodeOk on success.
|
|
****************************************************************************/
|
|
enum EPVRScopeInitCode PVRScopeInitialise(
|
|
struct SPVRScopeImplData **ppsData ///< Context data
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Shutdown or de-initalise @ref ScopeStats and free the allocated memory.
|
|
***************************************************************************/
|
|
void PVRScopeDeInitialise(
|
|
struct SPVRScopeImplData **ppsData, ///< Context data
|
|
struct SPVRScopeCounterDef **ppsCounters, ///< Array of counters
|
|
struct SPVRScopeCounterReading * const psReading ///< Results memory area
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Query for @ref ScopeStats information. This function should only be called during initialisation.
|
|
****************************************************************************/
|
|
void PVRScopeGetInfo(
|
|
struct SPVRScopeImplData * const psData, ///< Context data
|
|
struct SPVRScopeGetInfo * const psInfo ///< Returned information
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Query for the list of @ref ScopeStats HW performance counters, and
|
|
allocate memory in which the counter values will be received. This function
|
|
should only be called during initialisation.
|
|
****************************************************************************/
|
|
int PVRScopeGetCounters(
|
|
struct SPVRScopeImplData * const psData, ///< Context data
|
|
unsigned int * const pnCount, ///< Returned number of counters
|
|
struct SPVRScopeCounterDef **ppsCounters, ///< Returned counter array
|
|
struct SPVRScopeCounterReading * const psReading ///< Pass a pointer to the structure to be initialised
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Helper function to query for the counter index of one of a set
|
|
of "standard" counters. The index will be into the results array
|
|
(from PVRScopeReadCounters) not into the counter array (from
|
|
PVRScopeGetCounters)
|
|
****************************************************************************/
|
|
unsigned int PVRScopeFindStandardCounter(
|
|
const unsigned int nCount, ///< Returned number of counters, from PVRScopeGetCounters
|
|
const struct SPVRScopeCounterDef * const psCounters, ///< Returned counter array, from PVRScopeGetCounters
|
|
const unsigned int nGroup, ///< Group that will be active
|
|
enum EPVRScopeStandardCounter eCounter ///< Counter to be found
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Call regularly to allow PVRScope to track the latest hardware
|
|
performance data. If psReading is not NULL, PVRScope will also
|
|
calculate and return counter values to the application.
|
|
@details Returns 0 if no data is currently available; psReading will
|
|
not be filled with valid data. Try again later.
|
|
This function should be called "regularly"; two use cases are
|
|
considered:
|
|
1) A 3D application rendering a performance HUD (e.g. the on-
|
|
screen graphs in PVRScopeExample). Such an application should
|
|
call this function at least once per frame in order to gather
|
|
new counter values. If slower HUD updates are desired,
|
|
psReading may be NULL until a new reading is required, in
|
|
order to smooth out values across longer time periods, perhaps
|
|
a number of frames.
|
|
2) A standalone performance monitor (e.g. PVRMonitor) or
|
|
logging application. Such an application should idle and
|
|
regularly wake up to call this function; suggested rates are
|
|
100Hz (10ms delays) or 200Hz (5ms delays). If counter updates
|
|
are required at a lower rate, set psReading to NULL on all
|
|
calls except when new counter values are desired.
|
|
****************************************************************************/
|
|
int PVRScopeReadCounters(
|
|
struct SPVRScopeImplData * const psData, ///< Context data
|
|
struct SPVRScopeCounterReading * const psReading ///< Returned data will be filled into the pointed-to structure
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Request a new HW counter group.
|
|
@details Changing the Active HW Group: the API is designed to allow the
|
|
HW group to be changed immediately after gathering a reading.
|
|
****************************************************************************/
|
|
void PVRScopeSetGroup(
|
|
struct SPVRScopeImplData * const psData, ///< Context data
|
|
const unsigned int nGroup ///< New group
|
|
);
|
|
|
|
/*!**************************************************************************
|
|
@brief Retrieve the timing data packets.
|
|
@details This function can be called periodically if you wish to access
|
|
the start and end times of tasks running on the GPU.
|
|
The first time this function is called will enable the feature;
|
|
from then on data will be stored. If you wish to call this
|
|
function once only at the end of a test run, call it once also
|
|
prior to the test run.
|
|
****************************************************************************/
|
|
const struct SPVRScopeTimingPacket *PVRScopeReadTimingData(
|
|
struct SPVRScopeImplData * const psData, ///< Context data
|
|
unsigned int * const pnCount ///< Returned number of packets
|
|
);
|
|
|
|
/*! @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _PVRSCOPESTATS_H_ */
|
|
|
|
/*****************************************************************************
|
|
End of file (PVRScopeStats.h)
|
|
*****************************************************************************/
|