View figure.
With Xprofiler, you can get performance data for your application on a number of levels, and in a number of ways. You can easily view data pertaining to a single function, or you can use the reports provided to get information on your application as a whole.
Xprofiler makes it easy to get data on specific items in the function call tree. Once you've located the item you are interested in, you can get data a number of ways. If you are having trouble locating a function in the function call tree, see Locating specific objects in the function call tree.
Below each function box in the function call tree is a label that contains basic performance data. The example below shows the function box for the function sub1, and its label.
Figure 23. Example of a Function Box Label
View figure.
The label contains the name of the function, its associated cycle, if any, and its index. In the example above, the name of the function is sub1. It is associated with cycle 1, and its index is 5. Also, depending on whether the function call tree is viewed in summary mode or average mode, the label will contain the information listed below. See Controlling the representation of the function call tree for more about summary mode and average mode.
Since labels are not always visible in the Xprofiler window when it is fully zoomed out, you may need to zoom in on it in order to see the labels. See Zooming in on the function call tree for information on how to do this.
Call arc labels appear over each call arc. The label shows you the number of calls that were made between the two functions (from caller to callee). For example:
Figure 24. Example of a call arc label
View figure.
In order to see a call arc label, you will probably need to zoom in on it. See Zooming in on the function call tree for information on how to do this.
Cluster box labels tell you the name of the library that is represented by that cluster. If it is a shared library, the label shows its full pathname.
For each function box, call arc, and cluster box, there is a corresponding information box that you can access with your mouse. It gives you the same basic data that appears on the label. This is useful when the Xprofiler display is fully zoomed out and the labels are not visible. To access the information box, click on the function box, call arc, or cluster box (place it over the edge of the box) with the left mouse button. The information box appears.
For a function, the information box contains:
For a call, the information box contains:
For cluster, the information box contains:
You can get performance statistics for a single function via the Statistics Report option of the Function menu. It lets you see data on the CPU usage and call counts of the selected function. If you are using more than one gmon.out file, this option breaks down the statistics per each gmon.out file you use.
When you select the Statistics Report menu option, the Function Level Statistics Report window appears, as in the example below.
Figure 25. Function Level Statistics Report window
View figure.
The Function Level Statistics Report window provides the following information:
The name of the function you selected. In Figure 25, the function name is main.
The total amount of CPU used by this function. If you used multiple gmon.out files, the value shown here represents their sum.
The CPU Usage field shows you:
In Figure 25, CPU usage is listed as 0.10 seconds (self+desc) x 0.10 seconds (self)
The Call Counts field shows you:
In Figure 25, the value in the Call Counts field is 1 times.
The CPU usage and calls made to or by this function, broken down by gmon.out file.
The CPU Usage field shows you:
The average CPU time used by the data in each gmon.out file. In Figure 25, the Average is listed as 0.0100 seconds.
Standard deviation. A value that represents the difference in CPU usage samplings, per function, from one gmon.out file to another. The smaller the standard deviation, the more balanced the workload. In Figure 25, the Std Dev is listed as 0.0000 seconds.
Of all the gmon.out files, the maximum amount of CPU time used. The corresponding gmon.out file appears to the right. In Figure 25, the Maximum is listed as 0.01 seconds.
Of all the gmon.out files, the minimum amount of CPU time used. The corresponding gmon.out file appears to the right. In Figure 25, the Minimum is listed as 0.01 seconds.
The Call Counts field shows you:
The average number of calls made to this function or by this function, per gmon.out file. In Figure 25, the Average is 1.00 times.
Standard deviation. A value that represents the difference in call count sampling, per function, from one gmon.out file to another. A small standard deviation value in this field means that the function was almost always called the same number of times in each gmon.out file. In Figure 25, the Std Dev is 0.00 times.
The maximum number of calls made to this function or by this function in a single gmon.out file. The corresponding gmon.out file appears to the right. In Figure 25, the Maximum is 1 times.
The minimum number of calls made to this function or by this function in a single gmon.out file. The corresponding gmon.out file appears to the right. In Figure 25, the Minimum is 1 times.
Xprofiler provides performance data in textual and tabular format. This data is provided in various tables called reports. If you are a gprof user, you are familiar with the Flat Profile, Call Graph Profile, and Function Index reports. Xprofiler generates these same reports, in the same format, plus two others.
You can access the Xprofiler reports from the Report menu. The Report menu lets you see the following reports:
Each report window includes a File menu. Under the File menu is the Save As option which allows you to save the report to a file. For information on using the Save File Dialog window to save a report to a file, see Using the save dialog windows.
Each report window also includes a Search Engine field, which is located at the bottom of the window. The Search Engine lets you search for a specific string in the report. For information on using the Search Engine field, see Using the search engine.
Each of the Xprofiler reports are explained below.
When you select the Flat Profile menu option, the Flat Profile window appears. The Flat Profile report shows you the total execution times and call counts for each function (including shared library calls) within your application. The entries for the functions that use the greatest percentage of the total CPU usage appear at the top of the list, while the remaining functions appear in descending order, based on the amount of time used.
Unless you specified the -z command line option, the Flat Profile report does not include functions whose CPU usage is 0 (zero) and have no call counts.
Note that the data presented in the Flat Profile window is the same data that is generated with the UNIX gprof command.
The Flat Profile report looks similar to this:
Figure 26. Flat Profile Report
View figure.
The Flat Profile window fields are explained below.
The percentage of the program's total CPU usage that is consumed by this function.
A running sum of the number of seconds used by this function and those listed above it.
The number of seconds used by this function alone. The self seconds values are what Xprofiler uses to sort the functions of the Flat Profile report.
The number of times this function was called (if this function is profiled). Otherwise, it is blank.
The average number of milliseconds spent in this function per call (if this function is profiled). Otherwise, it is blank.
The average number of milliseconds spent in this function and its descendants per call (if this function is profiled). Otherwise, it is blank.
The name of the function. The index appears in brackets [] to the right of the function name. The index serves as the function's identifier within Xprofiler. It also appears below the corresponding function in the function call tree.
The Call Graph Profile menu option lets you view the functions of your application, sorted by the percentage of total CPU usage that each function, and its descendants, consumed. When you select this option, the Call Graph Profile window appears.
Unless you specified the -z command line option, the Call Graph Profile report does not include functions whose CPU usage is 0 (zero) and have no call counts.
Note that the data presented in the Call Graph Profile window is the same data that is generated with the UNIX gprof command.
The Call Graph Profile report looks similar to this:
Figure 27. Call Graph Profile Report
View figure.
The fields of the Call Graph Profile are explained below.
The index of the function in the Call Graph Profile. Each function in the Call Graph Profile has an associated index number which serves as the function's identifier. The same index also appears with each function box label in the function call tree, as well as other Xprofiler reports.
The percentage of the program's total CPU usage that was consumed by this function and its descendants.
The number of seconds this function spends within itself.
The number of seconds spent in the descendants of this function, on behalf of this function.
The heading of this column refers to the three different kinds of calls that take place within your program. The values in this field correspond to the functions listed in the name, index, parents, children field to its right. Depending on whether the function is a parent, child, or the function of interest (the function who's index is listed in the index field of this row), this value can stand for one of the following:
In the example below, sub2 is the function of interest, sub1 and main are its parents, and printf and sub1 are its children.
Figure 28. called/total, call/self, called/total field
View figure.
For a parent function, this refers to the number of calls made to the function of interest, as well as the total number of calls it made to all functions. In the example above, one of the parent functions, main, made two calls; one to the function of interest, sub2, and one to another function.
This refers to the number of times the function of interest called itself, recursively. In the example above, the function of interest, sub2, called itself two times. For a child function, this refers to the number of times the function of interest called this child. In the example above, one of the child functions, printf, was called eleven times; four times by the function of interest, sub2, and seven times by other functions.
The layout of the heading of this column is indicative of the information that is provided. To the left is the name of the function, and to its right is the function's index number. Appearing above the function are its parents, and below are its children.
Figure 29. name/index/parents/children field
View figure.
The name of the function, with an indication of its membership in a cycle, if any. Note that the function of interest appears to the left, while its parent and child functions are indented above and below it. In the example above, the name of the function is sub2.
The index of the function in the Call Graph Profile. This number corresponds to the index that appears in the index column of the Call Graph Profile and the on the function box labels in the function call tree. In the example above, the index of sub2 is [2].
The parents of the function. A parent is any function that directly calls the function in which you are interested. In the example above, the parents are sub1 and main.
If any portion of your application was not compiled with the -pg option, Xprofiler will not be able to identify the parents for the functions within those portions. As a result, these parents will be listed as spontaneous in the Call Graph Profile report.
The children of the function. A child is any function that is directly called by the function in which you are interested. In the example above, the children are printf and sub1.
The Function Index menu option lets you view a list of the function names included in the function call tree. When you select this option, the Function Index window appears, and displays the function names in alphabetical order. To the left of each function name is its index, enclosed in brackets []. The index is the function's identifier, which is assigned by Xprofiler. An index also appears on the label of each corresponding function box in the function call tree as well as other reports.
Unless you specified the -z command line option, the Function Index report does not include functions whose CPU usage is 0 (zero) and have no call counts.
The Function Index menu option includes a Code Display menu, like the Flat Profile menu option, allowing you to view source code or disassembler code. For more information on viewing code, see Viewing source code and Viewing disassembler code.
The Function Index report looks similar to this:
Figure 30. Sample Function Index Report
View figure.
The Function Call Summary menu option lets you display all the functions in your application that call other functions. They appear as caller-callee pairs (call arcs, in the function call tree), and are sorted by the number of calls in descending order. When you select this option, the Function Call Summary window appears.
The Function Call Summary report looks similar to this:
Figure 31. Sample Function Call Summary Report
View figure.
The fields of the Function Call Summary window are explained below.
The percentage of the total number of calls generated by this caller-callee pair.
The number of calls attributed to this caller-callee pair.
The name of the caller function and callee function.
The Library Statistics menu option lets you display the CPU time consumed and call counts of each library within your application. When you select this option, the Library Statistics window appears.
The Library Statistics report looks similar to this:
Figure 32. Sample Library Statistics Report
View figure.
The fields of the Library Statistics window are explained below.
The total CPU usage of the library, in seconds.
The percentage of the total CPU usage that was consumed by this library.
Total number of calls generated by this library.
The percentage of the total calls that were generated by this library.
The percentage of the total number of calls made from this library to other libraries.
The percentage of the total number of calls made from other libraries into this library.
The percentage of the total number of calls made between the functions within this library.
The library's full path name.
Xprofiler lets you save any of the reports you generate with the Report menu to a file. You can do this via the File and Report menus of the Xprofiler GUI.
To save a single report, go to the Report menu, on the Xprofiler main window, and select the report you would like to save. Each report window includes a File menu. Select the File menu and then the Save As option to save the report. A Save dialog window appears, which is named according to the report from which you selected the Save As option. For instance, if you chose Save As from the Flat Profile window, the dialog window is named Save Flat Profile Dialog.
You can save the Call Graph Profile, Function Index, and Flat Profile reports to a single file with the File menu of the Xprofiler main window. The information you generate here is identical to the output of the UNIX gprof command. From the File menu, select the Save As option. The Save File Dialog window appears.
To save the report(s):
The File Selection field of the Save File Dialog window follows Motif standards.
If you are profiling a parallel program, you could specify more than one profile data (gmon.out) file when you started Xprofiler. The Save gmon.sum As option of the File menu lets you save a summary of the data in each of these files to a single file.
The Xprofiler Save gmon.sum As option produces the same result as the Xprofiler and gprof -s command line option. If you run Xprofiler later, you can use the file you create here as input with the -s option. In this way, you can accumulate summary data over several runs of your application.
To create a summary file:
The Save Configuration menu option lets you save the names of the functions that are displayed currently to a file. Later, in the same Xprofiler session or a different session, you can read in this configuration file using the Load Configuration option. See the following section, "Loading a Configuration File", for more information.
To save a configuration file:
You can use the default file name, enter a file name in the Selection field, or select a file from the dialog's files list.
If you select the Forced File Overwriting option in the Runtime Options Dialog window, the Overwrite File Dialog does not open and the specified file is overwritten without warning.
The Load Configuration menu option lets you read in a configuration file that you saved. See the previous section, "Saving a Configuration File", for more information. The Load Configuration option automatically reconstructs the function call tree according to the function names recorded in the configuration file.
To load a configuration file:
You can also load the file with the -c command line option. See Specifying command line options (from the GUI) for more information.
If the a.out name, that is, the program name in the configuration file, is different from the a.out name in the current display, a confirmation dialog appears to allow you to decide whether or not you still wish to load the file.
Xprofiler provides several ways for you to view your source code. You can view the source or disassembler code for your application on a per-function basis. This also applies to any included function code your application may use.
When you view source or included function code, you use the Source Code window. When you view disassembler code, you use the Disassembler Code window. You can access these windows through the Report menu of the Xprofiler GUI or the Function menu of the function in which you are interested.
Both the Function menu and Report menu provide the means for you to access the Source Code window, from which you will view your code.
To access the Source Code window via the Function menu:
To access the Source Code window via the Report menu:
The Source Code window shows you only the source code file for the function you specified from the Flat Profile window or the Function menu. The Source Code Window looks similar to this:
Figure 33. Sample Source Code Window
View figure.
The Source Code Window contains information in the following fields:
The source code line number.
Each tick represents .01 seconds of CPU time used. The number that appears in this field represents the number of ticks used by the corresponding line of code. For instance, if the number 3 appeared in this field, for a source statement, this source statement would have used .03 seconds of CPU time. Note that the CPU usage data only appears in this field if you used the -g option when you compiled your application. Otherwise, this field is blank.
The application's source code.
The Search Engine field, at the bottom of the Source Code window, lets you search for a specific string in your source code. For information on using the Search Engine field, see Using the search engine
The Source Code window contains the following menus:
The Save As option lets you save the annotated source code to a file. When you select this option, the Save File Dialog window appears. For more information on using the Save File Dialog window, see Using the save dialog windows
Select Close if you wish to close the Source Code window.
The Utility menu contains only one option; Show Included Functions.
For C++ users, the Show Included Functions option lets you view the source code of included function files that are included by the application's source code.
If a selected function does not have an included function file associated with it or does not have the function file information available because the -g option was not used for compiling, the Utility menu will be greyed out. The availability of the Utility menu serves as an indication of whether or not there is any included function file information associated with the selected function.
When you select the Show Included Functions option, the Included Functions Dialog window appears, which lists all of the included function files. Specify a file by either clicking on one of the entries in the list with the left mouse button, or by typing the file name in the Selection field. Then click on the OK or Apply button. After selecting a file from the Included Functions Dialog window, the Included Function File window appears, displaying the source code for the file that you specified.
Both the Function menu and Report menu provide the means for you to access the Disassembler Code window, from which you can view your code.
To access the Disassembler Code window via the Function menu:
To access the Disassembler Code window via the Report menu:
The Disassembler Code window shows you only the disassembler code for the function you specified from the Flat Profile window. The Disassembler Code Window looks similar to this:
Figure 34. Sample Disassembler Code Window
View figure.
The Disassembler Code window contains information in the following fields:
The address of each instruction in the function you selected (from either the Flat Profile window or the function call tree).
Each tick represents .01 seconds of CPU time used. The number that appears in this field represents the number of ticks used by the corresponding instruction. For instance, if the number 3 appeared in this field, this instruction would have used .03 seconds of CPU time.
The execution instruction.
The execution instruction's corresponding assembler code.
The line in your application's source code that corresponds to the execution instruction and assembler code. In order for information to appear in this field, you must have compiled your application with the -g compile option.
The Search Engine field, at the bottom of the Disassembler Code window, lets you search for a specific string in your disassembler code. For information on using the Search Engine field, see Using the search engine.
The Disassembler Code window contains only one menu:
Select Save As to save the annotated disassembler code to a file. When you select this option, the Save File Dialog window appears. For information on using the Save File Dialog window, see Using the save dialog windows.
Select Close if you wish to close the Disassembler window.