1 /*!*********************************************************************** 2 3 @file PVRScopeStats.h 4 @copyright Copyright (c) Imagination Technologies Ltd. All Rights Reserved. 5 @brief PVRScopeStats header file. @copybrief ScopeStats 6 7 **************************************************************************/ 8 9 /*! @mainpage PVRScope 10 11 @section overview Library Overview 12 ***************************** 13 PVRScope is a utility library which has two functionalities: 14 \li @ref ScopeStats is used to access the hardware performance counters in 15 PowerVR hardware via a driver library called PVRScopeServices. 16 \li @ref ScopeComms allows an application to send user defined information to 17 PVRTune via PVRPerfServer, both as counters and marks, or as editable data that can be 18 passed back to the application. 19 20 PVRScope is supplied in the PVRScope.h header file. Your application also needs to link to the PVRScope 21 library file, either a <tt>.lib</tt>, <tt>.so</tt>, or <tt>.dy</tt> file, depending on your platform. 22 23 For more information on PVRScope, see the <em>PVRScope User Manual</em>. 24 25 @subsection limitStats PVRScopeStats Limitations 26 ***************************** 27 @copydetails ScopeStats 28 29 @subsection limitComms PVRScopeComms Limitations 30 ***************************** 31 @copydetails ScopeComms 32 */ 33 34 #ifndef _PVRSCOPE_H_ 35 #define _PVRSCOPE_H_ 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /*! 42 @addtogroup ScopeStats PVRScopeStats 43 @brief The PVRScopeStats functionality of PVRScope is used to access the hardware performance counters in 44 PowerVR hardware via a driver library called PVRScopeServices. 45 @details PVRScopeStats has the following limitations: 46 \li Only one instance of @ref ScopeStats may communicate with PVRScopeServices at any 47 given time. If a PVRScope enabled application attempts to communicate with 48 PVRScopeServices at the same time as another such application, or at the same time as 49 PVRPerfServer, conflicts can occur that may make performance data unreliable. 50 \li Performance counters can only be read on devices whose drivers have been built with 51 hardware profiling enabled. This configuration is the default in most production drivers due to negligible overhead. 52 \li Performance counters contain the average value of that counter since the last time the counter was interrogated. 53 @{ 54 */ 55 56 57 /**************************************************************************** 58 ** Enums 59 ****************************************************************************/ 60 /*!************************************************************************** 61 @enum EPVRScopeInitCode 62 @brief PVRScope initialisation return codes. 63 ****************************************************************************/ 64 enum EPVRScopeInitCode 65 { 66 ePVRScopeInitCodeOk, ///< Initialisation OK 67 ePVRScopeInitCodeOutOfMem, ///< Out of memory 68 ePVRScopeInitCodeDriverSupportNotFound, ///< Driver support not found 69 ePVRScopeInitCodeDriverSupportInsufficient, ///< Driver support insufficient 70 ePVRScopeInitCodeDriverSupportInitFailed, ///< Driver support initialisation failed 71 ePVRScopeInitCodeDriverSupportQueryInfoFailed, ///< Driver support information query failed 72 ePVRScopeInitCodeUnrecognisedHW ///< Unrecognised hardware 73 }; 74 75 /**************************************************************************** 76 ** Structures 77 ****************************************************************************/ 78 79 // Internal implementation data 80 struct SPVRScopeImplData; 81 82 /*!************************************************************************** 83 @struct SPVRScopeCounterDef 84 @brief Definition of a counter that PVRScope calculates. 85 ****************************************************************************/ 86 struct SPVRScopeCounterDef 87 { 88 const char *pszName; ///< Counter name, null terminated 89 bool bPercentage; ///< true if the counter is a percentage 90 unsigned int nGroup; ///< The counter group that the counter is in. 91 }; 92 93 /*!************************************************************************** 94 @struct SPVRScopeCounterReading 95 @brief A set of return values resulting from querying the counter values. 96 ****************************************************************************/ 97 struct SPVRScopeCounterReading 98 { 99 float *pfValueBuf; ///< Array of returned values 100 unsigned int nValueCnt; ///< Number of values set in the above array 101 unsigned int nReadingActiveGroup; ///< Group that was active when counters were sampled 102 }; 103 104 /*!************************************************************************** 105 @struct SPVRScopeGetInfo 106 @brief A set of return values holding miscellaneous PVRScope information. 107 ****************************************************************************/ 108 struct SPVRScopeGetInfo 109 { 110 unsigned int nGroupMax; ///< Highest group number of any counter 111 }; 112 113 /**************************************************************************** 114 ** Declarations 115 ****************************************************************************/ 116 117 const char *PVRScopeGetDescription(); ///< Query the PVRScope library description 118 119 120 /*!************************************************************************** 121 @brief Initialise @ref ScopeStats, to access the HW performance counters in PowerVR. 122 @return EPVRScopeInitCodeOk on success. 123 ****************************************************************************/ 124 EPVRScopeInitCode PVRScopeInitialise( 125 SPVRScopeImplData **ppsData ///< Context data 126 ); 127 128 /*!************************************************************************** 129 @brief Shutdown or de-initalise @ref ScopeStats and free the allocated memory. 130 ***************************************************************************/ 131 void PVRScopeDeInitialise( 132 SPVRScopeImplData **ppsData, ///< Context data 133 SPVRScopeCounterDef **ppsCounters, ///< Array of counters 134 SPVRScopeCounterReading * const psReading ///< Results memory area 135 ); 136 137 /*!************************************************************************** 138 @brief Query for @ref ScopeStats information. This function should only be called during initialisation. 139 ****************************************************************************/ 140 void PVRScopeGetInfo( 141 SPVRScopeImplData * const psData, ///< Context data 142 SPVRScopeGetInfo * const psInfo ///< Returned information 143 ); 144 145 /*!************************************************************************** 146 @brief Query for the list of @ref ScopeStats HW performance counters, and 147 allocate memory in which the counter values will be received. This function 148 should only be called during initialisation. 149 ****************************************************************************/ 150 bool PVRScopeGetCounters( 151 SPVRScopeImplData * const psData, ///< Context data 152 unsigned int * const pnCount, ///< Returned number of counters 153 SPVRScopeCounterDef **ppsCounters, ///< Returned counter array 154 SPVRScopeCounterReading * const psReading ///< Pass a pointer to the structure to be initialised 155 ); 156 157 /*!************************************************************************** 158 @brief This function should be called regularly, such as once per frame. psReading 159 may be NULL until a new reading is required, in order to smooth out values 160 across longer time periods, perhaps a number of frames. 161 @details As and when desired, call this function to fill the counter-value array with 162 the current counter values then change the active performance counter 163 group. In a 3D application, you might call this once per frame or every N 164 frames. Typically the group ID should be 0xffffffff in order to leave the 165 active group unchanged; if it is desired to change it then pass the new 166 group ID. 167 ****************************************************************************/ 168 bool PVRScopeReadCountersThenSetGroup( 169 SPVRScopeImplData * const psData, ///< Context data 170 SPVRScopeCounterReading * const psReading, ///< Returned data will be filled into the pointed-to structure 171 const unsigned int nTimeUS, ///< Current time, in microseconds. Ignored if psReading is NULL. 172 const unsigned int nGroup ///< New group; 0xffffffff to leave it unchanged 173 ); 174 175 /*! @} */ 176 177 #ifdef __cplusplus 178 } 179 #endif 180 181 #endif /* _PVRSCOPE_H_ */ 182 183 /***************************************************************************** 184 End of file (PVRScopeStats.h) 185 *****************************************************************************/ 186
