Profiler
Configuring if you initialize the profiler and then exit the program without terminating the profiler, timers may be left running that could crash the machine.
The call to terminate the profiler stops the profiler and deallocates memory. It does not dump any information. Any collected data that has not been dumped is lost when you call the function to terminate the profiler.
Having performed these quick steps, you simply compile your program and run it. The
IDE automatically opens this file in the Profiler window when the dump is complete.
You can later re-open the file in the IDE to view the info again.
In summary, the process of using the CodeWarrior profiler is quite easy. You add the requisite library, turn on profiling, include the header file, initialize the profiler, dump the results, and exit. It is a remarkably painless and simple process that quickly gets you all the data you need to perform a professional-level analysis of your application’s runtime behavior.
Configuring
This reference section discusses how to use the profiler libraries, APIs, and compiler options.
The sections in this section are:
•
Profiler Libraries and Interface Files —the libraries and interface files that you add to
your code in order to use the profiler
•
Profiling Special Cases —special cases to consider when profiling code
Profiler Libraries and Interface Files
You can find all of the profiler libraries and interface files in the Profiler folder. The profiling code that actually keeps track of the time spent in a routine exists in a series of libraries. Depending upon the nature of your project and the platform for which you are writing code, you link in one or another of these libraries as appropriate. The libraries you use must match your settings in the Target settings panel.
The profiler.h file is the header file for the profiler API for C and C++. Include this file to make calls to control the profiler
Profiling Special Cases
The profiler handles recursive and mutually recursive calls transparently. The profiler also warns you when profiling information was lost because of insufficient memory. (The profiler uses memory buffers to store profiling data.)
IDE 5.7 User’s Guide 303
Profiler
Configuring
For leading-edge programmers, the profiler transparently handles and reliably reports the times for abnormally terminated routines exited through the C++ exception handling model (try, throw, catch) or the ANSI C library setjmp() and longjmp() routines.
This section describes special cases you may encounter while profiling your code:
•
Profiling Code with #pragma Statements
•
Initializing Profiler with ProfilerInit()
•
Terminating Profiler with ProfilerDump()
•
Profiling Abnormally Terminated Functions
•
Debugging Profiled Code
Profiling Code with #pragma Statements
You can substitute #pragma statements for profiler API function calls to profile your C/
C++ code on the function level. However, this is not as useful as the profiler calls. See
Routine-Level Profiling for more information.
Setting the “Generate Profiler Calls” Processor preference option sets a preprocessor variable named __profile__ to 1. If profiling is off, the value is zero. You can use this value at compile time to test whether profiling is on.
Instead of, or in addition to, setting the option in the Processor preferences, you can turn on profiling at compile time. The C/C++ compiler supports three preprocessor directives that you can use to turn compiling on and off at will.
#pragma profile on
#pragma profile off
#pragma profile reset enables calls to the profiler in functions that are declared following the pragma disables calls to the profiler in functions that are declared following the pragma sets the profile setting to the value selected in the preferences panel
You can use these directives to turn profiling on for any functions you want to profile, regardless of the settings in the Processor preferences. You can also turn off profiling for any function you do not want to profile.
Initializing Profiler with ProfilerInit()
At the beginning of your code, you call ProfilerInit() to initialize the profiler.
Table 23.1
shows the prototypes for ProfilerInit() for C/C++.
304 IDE 5.7 User’s Guide
Profiler
Configuring
Table 23.1 ProfilerInit() Prototypes
C/C++ long ProfilerInit(
ProfilerCollectionMethod method,
ProfilerTimeBase timeBase,
short numFunctions, short
stackDepth);
The parameters tell the profiler how this collection run is going to operate, and how much memory the profiler should allocate for its data buffers. Each parameter and its purpose is given in
Table 23.2
.
Table 23.2 ProfilerInit() Parameters
Parameter
method timeBase numFunctions stackDepth
Purpose
collect detailed or summary data time scale to use in measurements maximum number of routines to profile approximate maximum depth of deepest calling tree
The collection method may be either collectDetailed or collectSummary. If you collect detailed data, you get information for the calling tree—the time in each routine and each of its children in the calling hierarchy. Summary data collects data for the time spent in each routine without regard to the calling chain. Collecting detailed data requires more memory.
The timeBase may be one of the following values:
• ticksTimeBase
• microsecondsTimeBase
• timeMgrTimeBase
• PPCTimeBase
• win32TimeBase
• bestTimeBase
The bestTimeBase option automatically selects the most precise timing mechanism available on the computer running the profiled software. Not all of these values are
IDE 5.7 User’s Guide 305
Profiler
Configuring supported on all target platforms. Refer to the Targeting Manual for your product to determine which time bases are available for use.
The numFunctions parameter is the approximate number of routines to be profiled.
The stackDepth parameter is the approximate maximum depth of your calling chain.
You do not need to know the precise values ahead of time. If the profiler runs out of memory to hold data in its buffers, the profiler loses some data but notifies you of this in the results. You can then modify the parameters in the call to ProfilerInit() to increase the buffers and preserve all your data.
The profiler allocates buffers in the profiled application’s heap based on the method of collection, the number of routines, and the depth of the calling tree. On platforms where it is possible, the profiler will allocate memory outside of the application’s heap, which helps reduce the profiler’s effect on the application.
The call to ProfilerInit() returns a non-zero error value if the call fails for any reason. Use the return value to ensure that memory was allocated successfully before continuing with the profiler. Typically you would add this call as conditionally compiled code so that it compiles and runs only if profiling is on and the call to
ProfilerInit()
was successful.
You call ProfilerInit() before any profiling occurs. Typically you make the call at the beginning of your code.
See also Time and Timebases and Memory Usage
Calling ProfilerInit() in C/C++
In C/C++, the call would be at the beginning of your main() function.
The call might look like this: if (!ProfilerInit(collectDetailed, bestTimeBase, 20, 5))
{
// your profiled code
}
Of course, your parameters may vary depending upon how many routines you have and the depth of your calling chains.
Terminating Profiler with ProfilerDump()
The profiler dumps its data to a file when you call ProfilerDump(). The file appears in the current default directory, usually the project directory.
You provide a file name when you call ProfilerDump(). You may dump results as often as you like. You can provide a different file name for intermediate results (if you have multiple calls to ProfilerDump()), or use the same name. If the specified file
306 IDE 5.7 User’s Guide
Profiler
Configuring already exists, a new file is created with an incrementing number appended to the file name for each new file. This allows the dump to be called inside a loop with a constant file name. This can be useful for dumping intermediate results on a long task.
ProfilerDump()
does not clear accumulating results. If you want to clear results you can call ProfilerClear().
A typical call to ProfilerDump() would be placed just before you exit your program, or at the end of the code you are profiling. The prototypes for ProfilerDump() are listed in
Table 23.3
.
Table 23.3 ProfilerDump() Prototypes
C/C++ long ProfilerDump(
unsigned char *filename);
Calling ProfilerDump()
There is only one parameter: char*. The parameter points to a C-style string for filename. The IDE automatically adds a .cwp extension to the file name.
Profiling Abnormally Terminated Functions
The profiler correctly reports data for abnormally terminated functions that exited through the C++ exception handling model (try, throw, catch) or the ANSI C library setjmp() and longjmp() routines. You do not have to do anything to get this feature, it is automatic and part of the profiler’s design.
However, there is a possibility of some errors in the reported results for an abnormally terminated function.
First, the profiler does not detect the abnormal termination until the next profiling call after the abnormal termination. Therefore, some additional time will be reported as belonging to the terminated function.
Second, if the next profiler event is a profiler entry, and the new stack frame for that function is larger than the frames that were abnormally exited, the profiler will not immediately detect that the original function was abnormally terminated. In that case the profiler will treat the function just entered as a child of the function abnormally terminated. The profiler will correct itself on the next profiling event without this property—that is, when the stack returns to a point smaller than it was when the abnormally terminated function exited.
Finally, remember that the profiler is not closed properly and the output file is not dumped when exit() is called. If you need to call exit() in the middle of your program and want the profiler output, call ProfilerDump().
If you are using the profiler, you should always call ProfilerTerm() before exit().
IDE 5.7 User’s Guide 307
