Chapter 5. The Table Reports: Function, File, Class, and Call Chain

5.1 Table report basics
5.1.1 Opening a table report
5.1.2 Table report column headers
5.1.3 The totals panel
5.1.4 The statistical type drop-down menu
5.1.5 Selecting columns to display
5.1.6 Sorting data
5.1.7 Exporting table data
5.1.8 The outline view
5.2 Navigating to other reports
5.2.1 Contextual menus
5.2.2 Toolbar navigation options
5.3 The function report
5.4 The class report
5.5 The file report
5.6 The call chain
5.6.1 Navigating the call chain's hierarchical table
5.6.2 Call Chain Link Notes

This chapter provides an in-depth look at the function report, the file report, the class report, and the call chain. It includes an overview, a section that explains some table report basics, including how to navigate to them and sort by the various report fields, and a discussion of each of the reports in detail, including their navigation behavior and report fields.

5.1 Table report basics

The data contained in an analysis file's summary report is just the beginning. All of the reports listed in the summary report's navigation section provide a more thorough look at your code's interaction with the hardware. This chapter focuses on the four reports that are laid out in tables:

Each of these report types are broken up by the unit type indicated in the report's title. Though statistical fields presented in the columns differ from report to report, there is a shared functionality in these report types that this section will explore before going to each of them in more detail. The toolbar, for example, contains a set of icons that, for the most part, are common to all report types and right-clicking on a row in any table report will open a contextual menu that allows you to navigate to the other report types. Exporting data from any of the table report types into a .txt, .tab, or .csv format is the same basic process for all table reports.

This is not to say the report types are identical in their layout and behavior. The call chain, for example, is hierarchical and includes controls that enable you to expand and collapse branches of the call chain. The toolbars vary slightly from report to report, as none of the report types include a button to open itself.

But before delving into the differences between the table reports, this chapter will explore the commonality.

5.1.1 Opening a table report

To open any of the table reports, click on its corresponding link in the summary report's navigation section, located in the upper left corner, above the code coverage pie charts. The function report link is at the top of the report list next to the icon, followed by the class report when C++ code is present, and the file report. The call chain appears third to last in the list of navigation links, just below the call graph.

Figure 5.1. The Navigation Section of the Summary Report

Note

As classes are only present in C++ code and not in C code, analysis files generated using standard C code will not contain a class report, thus the class report will not appear in the navigation section of the summary report.

Once open, you will see that all of these report types are filled with data displayed in rows and columns, like a spreadsheet.

5.1.2 Table report column headers

As data's relevance is dependent on whether the data is broken down by function, file, or class, the column headers will vary by report type. Here is a list of all of the column headers contained in the table reports:

5.1.3 The totals panel

At the bottom of any table report is a panel that presents the totals of all the selected rows in various statistical fields. This panel can be useful to quickly see how big an impact a range of items had on the performance of your source code. Select a range of rows by holding down the shift or control key and the totals panel will immediately update to show you the updated total based on the new selection. The totals panel can feature the following fields:

5.1.4 The statistical type drop-down menu

Located to the right of the export table icon in every table report's toolbar, the statistical type drop-down menu enables you to set the type of data used to populate the table. By default, a table report presents the aggregate for fields like self time, total time and delay, but this menu can be used to toggle between the three following options:

5.1.5 Selecting columns to display

By default, the column headers in the table report types are comprehensive. Every available report field is shown and the table scrolls from left to right if there is too much data to fit horizontally. If you wish to remove any of the columns, right-click on the header row in any report type to bring up the column selection contextual menu, as pictured in Figure 5.2:

Figure 5.2. Choosing Report Columns

RealView Profiler will display all of the checked report fields. To remove a report field and its associated column, select it in the contextual menu. To un-hide the column, re-open the contextual menu and select the report field again. Any number of columns can be hidden in this manner so that function, class, file and call chain reports display only the information that you find valuable.

5.1.6 Sorting data

The sort order varies from report to report, but it can be changed by clicking once on any of the column headers. The data in the table will be reordered based on the data contained in that column. To reverse the sort order, click in the same column header again. The default numerical and alphabetical sorting behavior varies from column to column, but an upwards arrow in the column header always indicates an ascending sort, while a downward arrow indicates a descending sort.

You are not limited to a simple one-level sort, either. You can specify as many subordinate sort criteria as there are columns. To specify more levels in the sort hierarchy, hold down the shift key and click on other columns until you have achieved your desired sequence. Such a sort is best illustrated in an example. To first sort by code coverage and then by the function name, click twice on the 'Coverage' column header, and then shift-click on the 'Function Name' header. When you are finished, the table's headers should resemble those in Figure 5.3:

Figure 5.3. A Multi-level Sort

The sort triangles show the direction of sort for each field, and the dots in the lower right of the column headers indicate ordering. In this case, 'Coverage' has one dot, indicating that it is the primary sort criteria, and 'Function Name' has two dots because it is the secondary sort criteria. There is no limit to the number of sort criteria you can specify.

If an element is selected in the table, the table will scroll to keep the selected element in view after a re-sort.

Note

Sorting in the call chain works somewhat differently than in the other report types. You can still click various columns to add sort criteria and change the direction of the sorts, but the sort criteria will not break the integrity of the call chain so the hierarchy call chain itself will not be rearranged. The order in which the children of a particular function appear are subject to the sort criteria.

5.1.7 Exporting table data

If you want to save the data displayed in the function report to disk in a format easily read by other applications, use the export data icon, located to the right of the navigation options in the toolbar. The export command can be used to create a text, tab-delimited, or comma-delimited file on disk which contains data from the selected table. The amount of data exported is up to you.

Once you have selected the export command, RealView Profiler will present you with an export table dialog similar to the one pictured in Figure 5.4:

Figure 5.4. The Export File Dialog

If you have something currently selected in the table report, you can use the two radio buttons at the top of the export table dialog to set the row parameters of the exported data. Use the 'Export all rows' button to export the entire contents of the table or choose the 'Export only selected rows' button to export only the range of rows that are currently selected in the table. The number in parentheses next to the 'Export only selected rows button' indicates the number of rows that are currently selected. If nothing is currently selected in the table report, these export row options will not appear.

Once you have chosen which rows you would like to export, you can use the next set of radio buttons to set the same options for columns. The first option exports all of the columns, while selecting the second option enables the column header check boxes to manually choose which columns you would like to export.

The three radio buttons near the bottom of the export dialog enable you to save the exported data in different formats. Choose the 'Format with spaces' option and the resulting data file will be formatted with spaces so that it is legible in a monospaced font. Selecting the 'Use tabs as delimiters' button will generate a row where the values are separated by tabs, making the file more easily interpreted by common spreadsheet applications, but harder on the eyes in a text file. Choosing the final option, 'Output comma-separated values', will output a file with the values separated by commas, another format easily understood by spreadsheet applications.

Enter a valid file location in the 'To file' field. RealView Profiler will automatically assign a file extension based on the output type chosen using the above buttons. The 'Format with spaces' option will yield a .txt file, a tab-delimited file will be saved as .tab file, and the comma-separated values option will produce a .csv file.

Once you have chosen all of your preferred options and entered a file name, push the 'Export' button. A new file will appear in the specified location.

5.1.8 The outline view

In the default layout of the RealView Profiler Eclipse perspective, the outline view appears on the far right side of the Eclipse window. The outline view can be opened and closed independently via the Window > Show View menu option.

Figure 5.5. The outline view

When any report besides the summary report is active, the outline view will contain an alphabetical list of every function, class or file, depending on the active report type.

You can use the outline view to easily find a specific function without changing the sort options you currently have set in the data table. For example, if you want to know where a particular function is in relation to call count, but do not want to re-sort by name in the report, use the alphabetically sorted outline view to find the function you are looking for. Clicking on a function in the outline view will bring the function to view in the report and highlight it.

The outline view in the call chain lists every function in alphabetical order, but here the single function icon from the function report has been replaced by the multiple function icon. Clicking on any function in the outline view while the call chain is active in Eclipse's editor will select every call chain link of the selected function and expand the necessary functions to show them. The number in parentheses next to the function name indicates the number of call chain links where the function is present.

5.2 Navigating to other reports

RealView Profiler provides two avenues to access other report types from within a table report. You can open a new report using that report's corresponding icon in the toolbar, or open a contextual menu by right-clicking on a row in the table and selecting one of the report types. In both cases, context is important. The newly opened report will select and highlight data based on which rows are selected in the table report.

5.2.1 Contextual menus

To open a contextual menu, right-click on a row in any of the table reports. Although the exact list of options is dependent on the current selection and table report type, the table reports' contextual menu options include:

5.2.2 Toolbar navigation options

On the left side of the toolbar of every one of the report types, there is a group of icons, each representing a different report type that enables you to open a new report in the Editor. The buttons are context sensitive and the selections in the new report are dependent on the selections in the report in which you chose the toolbar command. With no rows selected in the currently active report, the 'Edit Source' option will be disabled. In order to open the source code based on the context of the current selection, you will first need to select one or more items.

Figure 5.6. A Function Report's Toolbar Navigation Options

Just like the context sensitive menu options, the menu buttons are dependent on the currently open report. For example, no navigation option will appear for the function report, if that is the report you currently have open.

Each report type is represented by its corresponding icon, listed in the order that they appear:

Selecting any one of these options has the same effect as choosing the contextual menu option that matches the report type. For a description of each of these navigation options, see Contextual menus.

Note

The class report icon will only appear in a toolbar if the associated source file contains C++. If the code you are using is written in C, the class report icon will not appear in the toolbar at all.

In addition to the report type buttons, the toolbar also contains an export table and a help button. The export table button opens the export dialog while the help button opens the help view and displays a list of topics specific to the currently active table report. Using this toolbar button has the same effect as pressing F1 in Windows or Shift + F1 in Linux.

5.3 The function report

The function report shows every function defined in your source files alongside the following performance statistics:

For a description of each of these column headers, see Section 5.1.2 Table report column headers

Double-clicking on any item in the function report will open the code view with every line of source and every disassembly instruction pertinent to that function selected.

5.4 The class report

Classes only appear in C++, not in C code, so this report type will only be present in analysis reports generated using this object-oriented language. Because it could be valuable to see statistics broken down by classes in addition to function, RealView Profiler provides the following statistical categories in this table report to provide a better understanding of how and how often your classes are being called and how they are affecting performance.

For a description of each of these column headers, see Section 5.1.2 Table report column headers

Double-clicking on any item in the class report will open the function report, with each one of that class' function selected.

5.5 The file report

The file report breaks data down by the source files used to build the image file. Compiler and language libraries and other instructions with no direct or obvious link to source code are included in this report under the name of the executable file name itself. It contains the following column headers:

For a description of each of these column headers, see Section 5.1.2 Table report column headers

Double-clicking on a file in this table report will open the code view for the file, with all of the pertinent code lines and disassembly instructions selected.

5.6 The call chain

The call chain is laid out in a table format like the other reports discussed in this chapter, but here the data is presented hierarchically. The call chain is intended to show you the exact code hierarchy as captured during execution. If a function is called in multiple places in the hierarchy, each instance will appear as an individual 'link' in the call chain. The call chain's set of column headers is similar to those in the function report:

For a description of each of these column headers, see Section 5.1.2 Table report column headers

In the call chain, the data is broken down by instance, so that you can get a clear view of how different functions performed at every place they occur in the call chain.

Double-clicking on a row in the call chain will open up that function in the call summary, a graphical view of a function's callee and caller relationships, overlaid with statistics. The newly opened call summary will be pre-filtered, so that the statistics that it shows are applicable only to the chosen link. All other instances of the function will be filtered out when the call summary is opened in this manner. To show all instances of the function once the call summary has been opened, click the plus sign in the lower left of the function's box.

5.6.1 Navigating the call chain's hierarchical table

The call chain's data is categorized hierarchically, meaning that, in order to see a function's subordinate functions, you will have to expand it by clicking on the disclosure controls to the left of the function name, or pressing the right arrow key on your keyboard. To hide a link's subordinate functions, click the disclosure button again or press the left arrow key.

Figure 5.7. The Hierarchical Call Chain Display

If you take a look at the call chain pictured in the figure above, you can see that the link R_Init has been expanded to show three of its child functions. Exploring the links in the call chain in this manner is a good way to pinpoint exactly where the accesses are occurring in your code.

Note

Due to memory constraints, the call chain's maximum depth is 511. If a call chain would exceed this depth, it is trimmed to keep within this number.

The call chain's toolbar contains all of the standard table report buttons, but it includes two buttons that enable you to expand or collapse every child of all call chain links. The button, located just to the right of the standard toolbar options, hides all the children of all links, while the button to its right, expands it to show every subordinate branch of all links.

The call chain also contains a unique contextual menu item, 'Expand Selection To All Matching Call Chain Links'. Use this option, only present if the function appears in the call chain more than once, to select all of this function's call chain links. The hierarchical table will expand to show each of the newly selected links.

5.6.2 Call Chain Link Notes

In certain cases, a note icon will appear to the right of the link in the 'Function Name' field. Hover over the note and a tooltip will appear that lists every special consideration that is applicable to this link. Here is a list of all of the possible notes that can be found in a call chain report:

Copyright © 2007 ARM Limited. All rights reserved. ARM DUI 0412A