Chapter 8. The Call Summary

8.1 Call summary breakdown
8.2 Function box statistics
8.2.1 Basic statistical fields
8.2.2 Instances: the x of y (z total) notation
8.3 Including and unincluding instances
8.3.1 Inclusion contextual menu options
8.4 Call summary navigation
8.4.1 The outline view
8.5 Navigating to other report types
8.5.1 Navigating using the toolbar
8.5.2 Navigating using the contextual menus

This chapter explores the functionality of the call summary. It includes a section that breaks down the items in the call summary window, a section that explains call summary navigation, a section on filtering, and a section that describes each of the toolbar options and contextual menu options.

8.1 Call summary breakdown

The call summary is a tool that enables you to explore your code like never before, navigating your way through the call chain and looking at data pertinent to specific instances and branches of the call tree. This section guides you through every area of the call summary and explains each of the statistics overlaid on the functions' boxes. Figure 8.1 shows you a call summary window taken from the doom sample, that you can find by selecting All Programs > ARM > RealView Profiler v1.0.x > Examples

Figure 8.1. The Call Summary

The box in the center, P_BlockThingsIterator is referred to as the primary function. The system functions on the left, P_ChangeSector, P_CheckPosition, and P_RadiusAttack are the calling functions while the functions on the right, PIT_ChangeSector, PIT_CheckPosition, and PIT_RadiusAttack are the called functions.

Like the call graph, the arrows indicate the direction of the call, but unlike the call graph, calling functions will always be on the left and called functions will always be on the right. Everything in the call summary is shown as it relates to the primary function, including the statistics shown in the function boxes. Clicking on the navigation icon in the upper right of any of the calling or called functions will make that function the new primary function, and reveal all of its calling and called functions.

8.2 Function box statistics

The statistics listed in each of the call summary's function boxes are a subset of the statistical fields provided in the table reports, and, when the call summary is first opened the primary function's numbers should match up to the data presented in the function report. One of the benefits of the call summary is that the numbers are updated based on the current filters. You can see a function's numbers as they relate to specific instances. The numbers listed in the calling and called function boxes may not equal the numbers shown for them in the function report, as these numbers for these functions only include instances relating to the primary function.

RealView Profiler also color-codes the title bar of the calling and called function boxes based on the self time value reported in the function box. The given color-coding is identical to the colors used in the summary report, with red representing the highest self time value and yellow the fifth highest. Each of the color coded boxes are also marked with stars to help differentiate between the colors. Five stars are listed below the title in the function box with the highest self time value and one star is listed in the function box with the fifth highest.

8.2.1 Basic statistical fields

Here is a brief description of each of the statistical fields listed in the call summary:

8.2.2 Instances: the x of y (z total) notation

The instance notation, listed in the bottom right of every function, gives you the complete instances picture for the function. It tells you how many total instances of the function exist in the entire call chain as well as how many instances are currently filtered out. The number listed in the primary function is different than the notation in the calling and called functions. Figure 8.2 provides a closer look at the P_BlockThingsIterator primary function:

Figure 8.2. The P_BlockThingsIterator Primary Function

In the primary function, only two numbers are listed. In the case of fputc, the notation provided is '17 (17 total)'. This tells us two things:

Now have a look at the calling function, P_ChangeSector:

Figure 8.3. The P_ChangeSector Calling Function

The notation in the bottom corner says '2 of 2 (2 total)', providing an additional number. The notation in the calling and called functions tells us:

8.3 Including and unincluding instances

The and icons in the bottom left of each of the function boxes enable you to include and uninclude instances. Press the button to filter a calling or called function path from the call summary. Functions filtered in this manner will not be removed from the call summary, but they will appear grayed out and all statistics relating to this function will be removed.

The doom code used in Figures 8.1, 8.2, and 8.3 will again serve as the example, this time to illustrate the filtering behavior of the call summary. If we click on the P_ChangeSector function's icon, the call summary will update itself to resemble the one pictured in Figure 8.4.

Figure 8.4. A Filtered Instance

You will notice that the statistics from both P_ChangeSector and PIT_ChangeSector been removed. This is because removing functions from the call summary serves to filter out the instances of the primary function we are not interested in. The calling and called functions linked to removed instances are removed as well.

If you right-click on the primary function and choose the 'Uninclude All' option, all instances would be removed from the totals and all of the calling and called function boxes would be grayed out, as pictured in Figure 8.5:

Figure 8.5. Unincluding all instances

Unincluded functions remain that way if you move to another function, so if you want to include all instances of the function you are moving to, it is good to remember to include all functions before moving on.

8.3.1 Inclusion contextual menu options

RealView Profiler provides you with a few contextual menu options that enable you to quickly and easily include only the desired functions in the call summary. The contextual menu options available when you right-click on a calling or called function are:

8.4 Call summary navigation

To explore your call chain in the call summary, click on the navigation buttons ( or ) in the upper right of any of the caller or callee functions. This will shift the call summary, making the selected function the new primary function. All filtering that has been applied to old primary functions still applies, so if you shift to a called function that had some of its instances filtered out while the previous function was the primary function, those instances will still be unincluded.

8.4.1 The outline view

You also use the outline view to navigate to a specific function. When the call summary is active, clicking on a function in the outline view will make that function the primary view. If the outline view is not already there, you can open it using the Window > Show View > Outline menu option.

8.5 Navigating to other report types

Just like in RealView Profiler's other reports, the call summary allows quick navigation to any other report in the product, both through the use of toolbar buttons and contextual menu items. Double-clicking any of the functions in the call summary opens the call chain, with every instance of the function selected and exposed.

8.5.1 Navigating using the toolbar

You can use the toolbar's buttons to open another report type based on the current selection in the call summary. Select a function and press the function report button, and RealView Profiler will open the function report with that function selected and in view. Here is a list of each of the buttons in the call summary's toolbar:

8.5.2 Navigating using the contextual menus

You can open a contextual menu option by right-clicking on any of the function boxes in the call summary. The navigation options presented here have identical behavior to their corresponding toolbar options:

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