osProfileInit, osProfileStart, osProfileStop, osProfileFlush

Run time profile for text spaces without shared sources

Syntax

#include <ultra64.h>     /* ultra64.h */
void osProfileInit(OSProf *profp, u32 profcnt);
void osProfileStart(u32 microseconds);
void osProfileStop(void);
void osProfileFlush(void);

Description

Profiling provides CPU-use statistics by profiling the amount of CPU time expended by a program in disjoint text spaces.

Profiling generates the statistics by creating an execution histogram for a current process. The histogram is defined for a list of regions of program code to be profiled specified by members of the profp array: profp[0], profp[1], ..., profp[profcnt-1]. The host-side application gperf copies the histogram data to the host and prints a report detailing the relative time spent processing each function.

The OSProf data structure has the following elements:

u16 *histo_base

Pointer to an array of u16 counters.

u32 histo_size

Number of counters in the histo_base buffer. Profiling requires one counter for each 32-bit word in the segment.

u32 *text_start

Pointer to the first instruction in the segment to be profiled.

u32 *text_end

Pointer to the last instruction in the segment to be profiled.

Each OSprof entry specifies a region of text space that needs to be profiled. If an instruction falls outside the bounds specified by the profp array, an internal 32-bit overflow counter is incremented.

The osProfileInit function initializes the profiled segment count buffers and starts an IO thread that communicates profile data to the host when requested by the gperf tool. To use it, pass a pointer to an array of OSProf structures (profp) each element of which describes a segment to be profiled. The profcnt argument indicates the number of profiled segments. The osProfileInit function clears the counters for each profiled segment. A thread is started to service requests for profile data from the gperf tool. Profiling data can be dumped to the host any time after osProfileInit is called. Call osProfileInit before calling any other profiler function.

The osProfileStart function is called to start the profiler's interval counter. The microseconds argument sets the period of this timer; A typical value is 10000 microseconds (10 milliseconds). The minimum timer period is defined by PROF_MIN_INTERVAL. Each time an interrupt is generated by the counter, the profiler determines which profiled segment the PC belongs to and then increments the proper counter in the counter buffer for that segment. If the PC does not lie within any profiled segment, an internal overflow register is incremented. There is no protection for counter overflow.

The osProfileStop function is called to turn off profiling. Profiling data remains in memory but is not incremented further. The thread started by osProfileInit to send profile data to the host continues to run. You can call it again to resume profiling.

The osProfileFlush function can be used to programmatically transfer profile data to the gperf program assuming the gperf program is running in server mode. gperf program can also send requests to the profiler's IO thread at any time while the program is executing in non-server mode.

The following errors are reported when you are using the debug library:

ERR_OSPROFILEINIT_STR

Profile counter is running, call osProfileStop before initializing.

ERR_OSPROFILEINIT_CNT

The profcnt argument is an illegal value.

ERR_OSPROFILEINIT_ALN

The histo_base pointer must be 32-bit aligned.

ERR_OSPROFILEINIT_ORD

The text_start element of the OSProf structure is greater than or equal to the text_end element.

ERR_OSPROFILEINIT_SIZ

The histo_size element of the OSProf structure is an illegal size.

ERR_OSPROFILESTART_TIME

The microseconds argument is less than PROF_MIN_INTERVAL.

ERR_OSPROFILESTART_FLAG

Profiling has already been started.

ERR_OSPROFILESTOP_FLAG

Profiling has already been stopped.

ERR_OSPROFILESTOP_TIMER

No profile timer to stop.

Note

• Call the osProfileFlush function when gperf results an unexpected error or is too slow to be executed.
  
  
• The gperf tool (and thus profiling) does not work with programs that have functions that have been rearranged in the executable objects for optimization.
  
  
• Currently, profiling only supports 16-bit counters.
  
  
• Profiling is not available in the libultra_rom library.
  
  
• There is no check for overlapping text segments in the OSProf array.
  
  

See Also

osProfileInit, osProfileFlush, gperf, and makerom

Revision History

1999/04/30 Changed format