This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Profiling an Application

You can select a topic from this diagram:

This chapter shows you how to use the application profiler.

In this chapter...

• Introducing the Application Profiler
• Profiling your program
• Controlling your profiling sessions
• Understanding your profiling data

Introducing the Application Profiler

The QNX Application Profiler perspective lets you examine the overall performance of programs, no matter how large or complex, without following the source one line at a time. Whereas a debugger helps you find errors in your code, the Application Profiler helps you pinpoint "sluggish" areas of your code that could run more efficiently.

The QNX Application Profiler perspective.

Types of profiling

The Application Profiler lets you perform:

• statistical profiling
• instrumented profiling
• postmortem profiling (on standard gmon.out files).

Statistical profiling

The Application Profiler takes "snapshots" of your program's execution position every millisecond and records the current address being executed. By sampling the execution position at regular intervals, the tool quickly builds a summary of where the system is spending its time in your code.

With statistical profiling, you don't need to use instrumentation, change your code, or do any special compilation. The tool profiles your programs nonintrusively, so it doesn't bias the information it's collecting.

Note, however, that the results are subject to statistical inaccuracy because the tool works by sampling. Therefore, the longer a program runs, the more accurate the results.

Instrumented profiling

If you build your executables with profiling enabled, the Application Profiler can provide call-pair information (i.e. which functions called which). When you build a program with profiling enabled, the compiler inserts snippets of code into your functions in order to report the addresses of the called and calling functions. As your program runs, the tool produces an exact count for every call pair.

Postmortem profiling

The IDE lets you examine profiling information from a gmon.out file produced by an instrumented application. The tool gives you all the information you'd get from the traditional gprof tool, but in graphical form. You can examine gmon.out files created by your programs, whether you built them using the IDE or the qcc -p command. For more on the gprof utility, go to www.gnu.org; for qcc, see the Utilities Reference.

Profiling your programs

Whether you plan to do your profiling in real time or postmortem (using a gmon.out file), you should build your programs with profiling enabled before you start a profiling session.

This section includes these topics

• Building a program for profiling
• Running and profiling a process
• Profiling a running process
• Postmortem profiling

If you already have a gmon.out file, you're ready to start a postmortem profiling session.

Building a program for profiling

Although you can profile any program, you'll get the most useful results by profiling executables built for debugging and profiling. The debug information lets the IDE correlate executable code and individual lines of source; the profiling information reports call-pair data.

This tables shows the application profiling features that are possible with the various build variants:

To build executables with debug information and profiling enabled:

1. In the C/C++ Projects view, right-click your project and select Properties.
2. In the left pane, select QNX C/C++ Project.
3. In the right pane, select the Options tab.
4. Check the Build with Profiling option:

   

5. Select the Build Variants tab and check the Debug variant for your targets.

   ---

   The Application Profiler uses the information in the debuggable executables to correlate lines of code in your executable and the source code. To maximize the information you get while profiling, use executables with debug information for both running and debugging.

   ---

6. Click Apply.
7. Click OK.
8. Rebuild your project.

To build a Standard Make project for profiling, compile and link using the -p option. For example, your Makefile might have a line like this: CFLAGS=-p CXXFLAGS=-p LDFLAGS=-p

Running and profiling a process

To run and profile a process, with qconn on the target:

1. Create a QNX Application launch configuration for an executable with debug information as you normally would, but don't click OK. You may choose either a Run or a Debug session.
2. On the launcher, click the Tools tab.
3. Click Add/Delete Tool. The Select tools to support dialog appears.
4. Enable the QNX Application Profiler tool.
5. Click OK.
6. On the launcher, click the QNX Application Profiler tab:

   

7. Fill in these fields:

   Profiler update interval (ms)

   Use this option to control how often the Profiler polls for data. A low setting causes continuous (but low) network traffic and fast refresh rates. A high setting causes larger network data bursts and may cause higher memory usage on the target because the target must buffer the data. The default setting of 1000 should suffice.

   Shared library paths

   The IDE doesn't know the location of your shared library paths, so you must specify the directory containing any libraries that you wish to profile. For a list of the library paths that are automatically included in the search path, see the appendix, Where Files Are Stored.

   Switch to this tool's perspective on launch.

   Check this option to automatically switch to the QNX Application Profiler perspective when this launch configuration is used.

8. If you want the IDE to automatically change to the QNX Application Profiler perspective when you run or debug, check the Switch to this tool's perspective on launch. box.
9. Click Apply.
10. Click Run or Debug. The IDE starts your program and profiles it.

To produce full profiling information with function timing data, the application needs to be run as root. This is the case when running through qconn. If the application is run as a normal user, the profiler can only generate call chain information.

Profiling a running process

To profile a process that's already running on your target:

1. While the application is running, open the Launch Configurations dialog by choosing Run-->Debug... from the menu.
2. Select C/C++ QNX Attach to Process w/QConn (IP) in the list on the left.
3. Click the New button to create a new attach-to-process configuration.
4. Configure things as you normally would for launching the application with debugging.
5. On the Tools tab, click Add/Delete Tool.... The Tools selection dialog appears.
6. Enable the Application Profiler tool, then click OK.
7. On the launcher, click the Application Profiler tab:

   

8. Fill in these fields:

   Profiler update interval (ms)

   You use this option to control how often the Profiler polls for data. A low setting causes continuous (but low) network traffic and fast refresh rates. A high setting causes larger network data bursts and may cause higher memory usage on the target because the target must buffer the data. The default setting of 1000 should suffice.

   Shared library paths

   The IDE doesn't know the location of your shared library paths, so you must specify the directory containing any libraries that you wish to profile. For a list of the library paths that are automatically included in the search path, see the appendix Where Files Are Stored.

   Switch to this tool's perspective on launch.

   Check this to automatically switch to the QNX Application Profiler perspective when using this launcher.

9. Click Apply, then click Debug. The Select Process dialog is displayed, showing all of the currently running processes:

   

10. Select the process you want to profile, then click OK.

Your running application won't generate call-pair information unless you ran it with the QCONN_PROFILER environment variable set to /dev/profiler. If you're launching the application from the IDE, add QCONN_PROFILER to the Environment tab of the launch configuration's Properties dialog. If you're running the application from the command-line, you can simply add QCONN_PROFILER to your shell environment, or the application's command-line: QCONN_PROFILER=/dev/profile ./appname

Postmortem profiling

The IDE lets you profile your program after it terminates, using the traditional gmon.out file. Postmortem profiling doesn't provide as much information as profiling a running process:

• Multithreaded processes aren't supported. Thus, the Thread Processor Usage view always shows the totals of all your program's threads combined as one thread.
• Call pair information from shared libraries and DLLs isn't shown.

Profiling a gmon.out file involves three basic steps:

• gathering profiling information into a file
• importing the file into your workspace
• starting the postmortem profiling session.

Gathering profiling information

The IDE lets you store your profiling information in the directory of your choice using the PROFDIR environment variable.

To gather profiling information:

1. Create a launch configuration for a debuggable executable as you normally would, but don't click Run or Debug.

   ---

   You must have the QNX Application Profiler tool disabled in your launch configuration.

   ---

2. Select the Environment tab.
3. Click New.
4. In the Name field, type PROFDIR.
5. In the Value field, enter a valid path to a directory on your target machine.
6. Click OK.
7. Run your program. When your program exits successfully, it creates a new file in the directory you specified. The filename format is pid.fileName (e.g. 3047466.helloworld_g). This is the gmon.out profiler data file.

Importing a gmon.out file

You can bring existing gmon.out files that you created outside the IDE into your workspace from your target system.

To import a gmon.out file into your workspace:

1. Open the Target File System Navigator view (Window-->Show View-->Other...-->QNX Targets-->Target File System Navigator.
2. In the Target File System Navigator view, right-click your file and select Copy to...-->Workspace. The Select target folder dialog appears.
3. Select the project related to your program.
4. Click OK.
5. In the C/C++ Projects view, right-click the file you imported into your workspace and select Rename.
6. Enter gmon.out (or gmon.out.n, where n is any numeric character). The IDE renames your file.

Starting a postmortem profiling session

To start the postmortem profiling session:

1. In the C/C++ Projects view, right-click your gmon.out file and select Open in QNX Application Profiler. The Program Selection dialog appears.
2. Select the program that generated the gmon.out file.
3. Click OK. You can now profile your program in the QNX Application Profiler perspective.

Controlling your profiling sessions

The Application Profiler view (Window-->Show View-->Other...-->QNX Application Profiler-->Application Profiler) lets you control multiple profiling sessions simultaneously. You can:

• terminate applications
• choose the executable or library to show profiling information for in the Sampling Information, Call Information, and Thread Processor Usage views.

The Application Profiler view displays the following as a hierarchical tree for each profiling session:

Session item	Description	Possible icons
Launch instance	Launch configuration name and launch type (e.g. prof201 [C/C++ QNX QConn (IP)])
Profiled program	Project name and start time (e.g. prof201 on localhost pid 4468773 (3/4/03 12:41 PM))
Application Profiler instance	Program name and target computer (e.g. Application Profiler Attached to: prof201 <4468773> on 10.12.3.200)
Executable
Shared libraries
DLLs
Unknown

To choose which executable or library to display information for in the QNX Application Profiler perspective:

In the Application Profiler view, click one of the following: the QNX Application Profiler instance an executable a shared library a DLL

To terminate an application running on a target:

1. In the Application Profiler view, select a launch configuration.
2. Click the Terminate button () in the view's title bar.

   ---

   To clear old launch listings from this view, click the Remove All Terminated Launches button ().

   ---

To disconnect from an application running on a target:

1. In the Application Profiler view, select a running profiler.
2. Click the Disconnect button () in the view's title bar.

   ---

   To clear old launch listings from this view, click the Remove All Terminated Launches button ().

   ---

Understanding your profiling data

For each item you select in the Application Profiler view, other views within the QNX Application Profiler perspective display the profiling information for that item:

Usage by line

The Application Profiler editor lets you see the amount of time your program spends on each line of code and in each function.

To open the editor:

1. Launch a profile session for a debuggable (i.e. _g) executable.
2. In the Application Profiler view, select your program by selecting an Application Profiler instance () or an executable ().
3. In the Sampling Information or Call Information view, double-click a function that you have the source for. The IDE opens the corresponding source file in the Application Profiler editor:

   

You may get incorrect profiling information if you change your source after compiling because the Application Profiler editor relies on the line information provided by the debuggable version of your code.

The Application Profiler editor displays a bar graph on the left side. The bars are color coded:

Green

CPU time spent within the function as a percentage of the program's total CPU time. The green bar appears on the first line of executable code in the function.

Orange

CPU time spent on a line of code as a percentage of the program's total CPU time. Within a function, the lengths of the orange bars add up to the length of the green bar.

Blue

CPU time spent on a line of code as a percentage of the function's total CPU time. Within a function, the sum of all the blue bars spans the width of the editor's margin.

To view quantitative profiling values:

In the Application Profiler editor, hover the pointer over a colored bar. The CPU usage appears, displayed as a percentage and a time:

Usage by function

The Sampling Information view shows a flat profile of the item that's currently selected in the Application Profiler view. You can examine profiling information for programs, shared libraries, and DLLs:

The view lists all the functions called in the selected item. For each function, this view displays:

• the total CPU time spent in the function
• the CPU time spent in the function since you last reset the counters.

If you select a program compiled for profiling, the view also displays:

• the number of times the function has been called
• the average CPU time per call.

To see your function usage:

1. Launch a profile session for a profiling-enabled (i.e. _g) executable.
2. In the Application Profiler view, select your program by selecting an Application Profiler instance () or any subordinate line. The Sampling Information view displays profiling information for your selection.

To reset the counters in the Time since last reset(s) column:

Click the Reset Sample counts button () in the Sampling Information view's title bar.

Usage by thread

The Thread Processor Usage view displays the CPU usage (in seconds and as a percentage of your program's total time) for each thread of the item that's currently selected in the Application Profiler view:

You can use this information to:

• identify which threads are the most and least active
• determine the appropriate size of your application's thread pool. (If there are idle threads, you might want to reduce the size of the pool.)

To see your thread usage:

1. Launch a profile session for a profiling-enabled (i.e. _g) executable.
2. In the Application Profiler view, select your program by selecting an Application Profiler instance () or any subordinate line. The Thread Processor Usage view displays profiling information for your selection.

Call counts

For the item that's currently selected in the Application Profiler view, the Call Information view shows your call counts in three panes:

• Call Pairs
• Call Graph
• Call Pair Details.

To display your call counts:

1. Launch a profile session for a profiling-enabled (i.e. _g) executable.
2. In the Application Profiler view, select your program by selecting an Application Profiler instance () or any subordinate line. The Call Information view displays profiling information for your selection:

   

Call Pairs pane

The Call Pairs pane shows you where every function was called from as well as the call-pair count, i.e. the number of times each function called every other function.

Call Graph pane

The Call Graph pane shows you a graph of the function calls. Your selected function appears in the middle, in blue. On the left, in yellow, are all the functions that called your function. On the right, also in yellow, are all the functions that your function called.

To see the calls to and from a function:

Click a function in: the Function column in the Call Pairs pane or: the Call Graph pane.

You can display the call graph only for functions that were compiled with profiling enabled.

Call Pair Details pane

The Call Pair Details pane shows the information about the function you've selected in the Call Graph pane. The Caller and Call Count columns show the number of times each function called the function you've selected.

The Called and Called Count columns show the number of times your selected function called other functions. This pane shows only the functions that were compiled with profiling. For example, it doesn't show calls to functions, such as printf(), in the C library.