PIX on Windows

Performance tuning and debugging for DirectX 12 games on Windows

Tracking Functions in Timing Captures

The default capture options in PIX timing captures allow you to visualize the execution times and relationships between portions of your title that have been instrumented with PIX events and PIX markers. These default options are sufficient if the portion of the title you’re profiling has been thoroughly instrumented. However, there are often scenarios where you’ll need to investigate a performance problem in a section of your title that has no, or very little, instrumentation.

The Tracked Functions feature in timing captures allows you to get detailed information about the code that is running on a thread or core at any time, not just those times that correspond with PIX events. Rather than adding more instrumentation and rebuilding, you can use the Tracked Functions feature to determine what’s going on in areas of your title that aren’t fully instrumented with PIX events.

Each call to the functions you choose to track is displayed on an additional lane per thread (or core) in the capture. As with the ability to collect CPU samples, the ability to track functions improves your iteration time by drastically reducing the need to add instrumentation to your title, then rebuild and redeploy.

Before tracking functions, PIX must be configured to find your title’s PDBs. PIX uses the information in PDBs to find the functions you’ve asked it to track. These functions are then dynamically instrumented at runtime so PIX can track all function entries and exits. See Configuring PIX to access CPU PDBs for more information.

Tracking functions is enabled by checking the Capture Tracked Functions option on the timing capture option pane. However, before turning on tracked functions, you’ll need to select which functions in your title you’d like to track.

Methods for Selecting Functions to Track

You can select which functions in your title to track in a few different ways. First, you can select functions to track while looking at CPU sample callstacks or the function tree presented in the Stack Analysis View. Alternatively, PIX provides a dialog that lets you manage which functions to track.

CPU Sample Callstacks

Selecting a CPU sample on the functions lane in the Timeline populates the Event Details view with the callstack for the sample. The row for each frame in the callstack includes a checkbox you can use to toggle tracking on and off. The functions you select will be tracked the next time you take a timing capture. Note that inlined functions, and functions for which PIX couldn’t find PDBs, cannot be tracked.

The first time you choose a function to track, PIX will prompt you to turn on the Capture Tracked Functions option so that your functions will be tracked the next time you take a timing capture.

Stack Analysis View

If you choose to collect CPU samples or callstacks for context switches when you take a timing capture, PIX will display a Stack Analysis view that contains a rollup of all samples that were collected during the capture. The Stack Analysis view helps you quickly see which functions and specific callstacks appeared most frequently in the samples.

Use the Track and Untrack buttons at the top of the view to choose which functions to track the next time a timing capture is taken.

Manage Functions dialog

The options pane for Timing Captures includes a Manage Functions button that brings up a dialog you can use to add and remove functions from the list that will be tracked during the next timing capture. If you selected functions to track using either the Stack Analysis view or CPU sample callstacks, those functions appear as tracked in the Manage Tracked Functions dialog.

The dialog has two list boxes, one that contains the list of functions that are available to be tracked and one that contains the list of functions that will be tracked. Buttons between the lists are used to move functions back and forth between the “Available” and “Tracked” lists.

The list of available functions can be populated either by loading a PDB from the file system or by querying the running title. The buttons with the single arrow will move the currently selected functions between the “Available” list and the “Tracked” list. The buttons with the double arrows move the entire contents of one list to the other.

A filter bar is provided above both lists that allows you to reduce the set of functions displayed by supplying function names or parts of function names.

The list of functions to be tracked can easily be shared between developers using the Import and Export feature. The Export button creates a text file in XML format that describes the contents of the Tracked Functions list. The Import button can be used to populate the Tracked Functions list with a previous exported, or hand generated, list of functions. Function are identified in the XML files by the combination of module name and function name.

<?xml version=”1.0″ encoding=”utf-8″?> <SymbolData xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”> <FunctionSet> <Functions ModuleName=”mockgame” FunctionName=”AppController::Process” /> <Functions ModuleName=”mockgame” FunctionName=”AppStateManager::Process” /> <Functions ModuleName=”mockgame” FunctionName=”MockGameAppController::Process” /> <Functions ModuleName=”mockgame” FunctionName=”MockGameAppController::Run” /> </FunctionSet> </SymbolData>

Initiating a Capture with Tracked Functions

After choosing a set of functions to track, check the Capture Tracked Functions option in the Timing Capture options pane. Tracked functions is supported in both Immediate and Continuous Timing Capture mode.

Viewing Tracked Functions

Tracked functions can be viewed using either the timeline or the events list in timing captures.

PIX adds one “Functions” lane to the timeline for each thread or core. This new lane is drawn immediately below the Events lane for the same thread or core. The tracked functions are drawn above CPU samples (if captured) on this new lane.

Selecting a function in the timeline populates the Event Details view with information about the function call, such as the time at which the call occurred and its duration.  The view also contains an Untrack button you can use to remove the function from the list to be tracked.

To view tracked functions in the events list, select the Function Calls (CPU Order) value from the dropdown in the upper left-hand corner of the view.

The events list contains one row for each function call that was tracked.  The caller-callee relationship is shown by indenting child calls underneath their parent.  The event list includes columns for CPU Start Time, CPU End Time, Duration, Execution time and so on.  The Counters button can be used to customize which columns are displayed in the events list.