• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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