1 /*---------------------------------------------------------------------------* 2 Project: Dolphin Performance Spy 3 File: perf.h 4 5 Copyright 2000 Nintendo. All rights reserved. 6 7 These coded instructions, statements, and computer programs contain 8 proprietary information of Nintendo of America Inc. and/or Nintendo 9 Company Ltd., and are protected by Federal copyright law. They may 10 not be disclosed to third parties or copied or duplicated in any form, 11 in whole or in part, without the prior written consent of Nintendo. 12 13 $Log: perf.h,v $ 14 Revision 1.2 2006/02/04 11:56:44 hashida 15 (none) 16 17 Revision 1.1.1.1 2005/05/12 02:41:07 yasuh-to 18 Ported from dolphin source tree. 19 20 21 11 2002/06/02 3:59p Tian 22 Added PERFSetDrawFrames 23 24 10 2002/01/25 4:58p Tian 25 Added PERFShutDown 26 27 9 2000/07/24 4:26p Tian 28 Added PERFSetDrawSyncCallback 29 30 8 2000/7/18 3:49p Tian 31 Draw options for graphs. Added pre- and post- draw functions 32 33 7 2000/07/05 2:07p Tian 34 Added event coloring 35 36 6 2000/6/30 6:17p Tian 37 Comments, CPU IPC/cachemiss graph 38 39 5 2000/6/29 8:54p Tian 40 Sampling interval now in floating point for higher resolution. 41 42 4 2000/06/29 5:56p Tian 43 Cache miss cycle counting 44 45 3 2000/06/29 11:59a Tian 46 Cleanup. Token accessors. 47 48 2 2000/06/28 4:08p Tian 49 Cleanup. Added color bar key. 50 51 1 2000/06/27 8:51p Tian 52 Initial check-in. 53 $NoKeywords: $ 54 *---------------------------------------------------------------------------*/ 55 56 57 #ifndef __PERF_H__ 58 #define __PERF_H__ 59 60 #include <revolution/types.h> 61 #include <revolution/os.h> 62 63 #ifdef __cplusplus 64 extern "C" { 65 #endif 66 67 /*---------------------------------------------------------------------------* 68 Do not install your own token callback if you are using this API. 69 Token ids range from 0xE000 - 0xFFFF. You may use any other token 70 ids. However, note that the more tokens you use, the more likely 71 that tokens will be missed by the PERF library. 72 *---------------------------------------------------------------------------*/ 73 /*===========================================================================* 74 Types 75 *===========================================================================*/ 76 typedef u8 PERFId; 77 78 79 // CPU events show up as red bars 80 // CPU-GP events show up as red bars for the CPU component. The corresponding 81 // GP time is indicated as a blue bar at the top. There are connecting lines 82 // between the CPU bar and the corresponding GP sub-bar. 83 // GP events show up only as blue bars 84 typedef enum 85 { 86 PERF_CPU_EVENT, 87 PERF_CPU_GP_EVENT, 88 PERF_GP_EVENT 89 } PerfType; 90 91 92 // Access to the memory allocator of choice 93 typedef void*(*PERFAllocator) ( u32 size ); 94 typedef void (*PERFDeallocator) ( void* block ); 95 96 // Use this callback to restore GP draw state to whatever is needed 97 // The PERF API only uses VTXFMT0. It changes Zmode, 98 // texgens, texcoord gen, blend mode. It restores projection matrix 99 typedef void (*PERFDrawCallback)( void ); 100 101 /*===========================================================================* 102 Initialization 103 *===========================================================================*/ 104 105 /*---------------------------------------------------------------------------* 106 Name: PERFInit 107 108 Description: Initializes performance spy. 109 110 Arguments: numSamples: total number of samples per "frame" 111 If PERF runs out of samples, the very last one 112 will be used over and over 113 numFrames: total number frames worth of data to remember 114 numTypes: maximum number of types of events 115 allocator: pointer to your allocator of choice 116 deallocator: pointer to your deallocator of choice 117 initDraw: pointer to function that re-initializes gp 118 for your program to render. If NULL, 119 performance graphs won't render. 120 121 Returns: returns heap footprint size 122 *----------------------------------------------------------------------------*/ 123 u32 PERFInit( u32 numSamples, 124 u32 numFramesHistory, 125 u32 numTypes, 126 PERFAllocator allocator, 127 PERFDeallocator deallocator, 128 PERFDrawCallback initDraw); 129 130 /*---------------------------------------------------------------------------* 131 Name: PERFShutDown 132 133 Description: Disables PERF autosampling, frees all memory, and sets 134 the GXDrawSync callback to the user defined one (set 135 via PERFSetDrawSyncCallback). If there is no 136 user-defined callback, the token callback will be set 137 to NULL (i.e. no token callbacks will be processed). 138 139 Arguments: None. 140 141 Returns: None. 142 *---------------------------------------------------------------------------*/ 143 void PERFShutDown( void ); 144 145 146 /*---------------------------------------------------------------------------* 147 Name: PERFSetDrawSyncCallback 148 149 Description: allows the program to have their own callback called for their 150 tokens. Note that program tokens must be less than 0xE000, 151 otherwise they will interfere with profiling. 152 153 Arguments: cb: token callback 154 155 Returns: None. 156 *---------------------------------------------------------------------------*/ 157 void PERFSetDrawSyncCallback(GXDrawSyncCallback cb); 158 159 160 /*---------------------------------------------------------------------------* 161 Name: PERFSetEvent 162 163 Description: Initializes an event type 164 165 Arguments: id: the index into the event array 166 name: constant string describing the event 167 type: CPU, GP, CPU-GP event 168 169 Returns: None. 170 *---------------------------------------------------------------------------*/ 171 void PERFSetEvent ( PERFId id, 172 char* name, 173 PerfType type ); 174 175 // color only affects CPU events 176 void PERFSetEventColor ( PERFId id, 177 GXColor color ); 178 179 /*===========================================================================* 180 Measurement 181 *===========================================================================*/ 182 183 // if sampling is used, do not use the decrementer on the CPU 184 void PERFStartAutoSampling ( f32 msInterval ); 185 void PERFStopAutoSampling ( void ); 186 187 /*---------------------------------------------------------------------------* 188 Name: PERFStartFrame 189 190 Description: Call at the beginning of every measurement frame. A 191 measurement frame can encompass multiple video frames. 192 Be careful not to call PERFDumpScreen until you have 193 called PERFEndFrame. 194 195 Resets sample counts and counters. 196 197 Arguments: None. 198 199 Returns: None. 200 *---------------------------------------------------------------------------*/ 201 void PERFStartFrame ( void ); 202 203 /*---------------------------------------------------------------------------* 204 Name: PERFEndFrame 205 206 Description: Call at the end of every measurement frame. A 207 measurement frame can encompass multiple video frames. 208 Be careful not to call PERFDumpScreen until you have 209 called PERFEndFrame. 210 211 Closes any outstanding samples, and takes some last 212 measurements. 213 214 Arguments: None. 215 216 Returns: None. 217 *---------------------------------------------------------------------------*/ 218 void PERFEndFrame ( void ); 219 220 /*---------------------------------------------------------------------------* 221 Name: PERFEventStart 222 223 Description: Indicates an event has begun, and starts measuring. 224 This event will not be rendered until PERFEventEnd has 225 been called on this event. If this event is a CPU-GP or GP 226 event, then a token will be written to the pipe. 227 228 You cannot call PERFEventStart on an event until 229 PERFEventEnd has been called on it. You may make multiple 230 measurements per frame. 231 232 CPU events can overlap one another, but CPU-GP and GP events 233 cannot 234 235 Arguments: id: index into event table. 236 237 Returns: None. 238 *---------------------------------------------------------------------------*/ 239 void PERFEventStart ( PERFId id ); 240 241 /*---------------------------------------------------------------------------* 242 Name: PERFEventEnd 243 244 Description: Stops measurements for the current event. 245 246 Arguments: id: index into event table. 247 248 Returns: None. 249 *---------------------------------------------------------------------------*/ 250 void PERFEventEnd ( PERFId id ); 251 252 253 /*===========================================================================* 254 Display 255 *===========================================================================*/ 256 257 /*---------------------------------------------------------------------------* 258 Name: PERFDumpScreen 259 260 Description: Draws fancy graphs on the screen: 261 1. Saves projection matrix. 262 Sets blend mode, z compare location, numchans = 1, 263 chanctrl, tevorder, tevop, texgens, tevstages, z mode. 264 Invalidates all vertex descriptors. 265 266 2. Renders graphs 267 268 3. Restores projection matrix 269 270 4. Calls application-specified draw init function 271 272 Arguments: None. 273 274 Returns: None. 275 *---------------------------------------------------------------------------*/ 276 void PERFDumpScreen ( void ); 277 void PERFPreDraw ( void ); 278 void PERFPostDraw ( void ); 279 280 void PERFSetDrawBWBarKey ( BOOL tf ); // enable drawing of on-screen color key 281 void PERFSetDrawBWBar ( BOOL tf ); 282 void PERFSetDrawCPUBar ( BOOL tf ); 283 void PERFSetDrawXFBars ( BOOL tf ); 284 void PERFSetDrawRASBar ( BOOL tf ); 285 286 void PERFSetDrawFrames ( u32 frames ); // zero means auto scale 287 288 289 void PERFToggleDrawBWBarKey ( void ); 290 void PERFToggleDrawBWBar ( void ); 291 void PERFToggleDrawCPUBar ( void ); 292 void PERFToggleDrawXFBars ( void ); 293 void PERFToggleDrawRASBar ( void ); 294 295 // to be implemented/TBD 296 //void PERFInitHostIO ( void ); 297 //void PERFDumpHost ( void ); 298 //void PERFQueryHost ( void ); // pull settings from host 299 300 301 //void PERFMenu ( void ); 302 303 304 #ifdef __cplusplus 305 } 306 #endif 307 308 #endif // __PERF_H__ 309