View configurations control the content and formatting of CodeAnalyst views. The CodeAnalyst GUI offers predefined view configurations which be selected by a user.
View Configurations are stored in .XML formatted files. A new customized view can be created by writing an .XML file for the view. Only the most advanced CodeAnalyst users should ever need to create views at the XML level.
This section describes the format and semantics of a view configuration in XML format.
A view configuration file contains a single, non-empty <view_configuration> element. This element, in turn, contains a single, non-empty <view> element. This format allows the possibility of representing multiple views within a single configuration file. The current implementation assumes that only one <view> will be defined in a configuration file.
The <view> element describes a view and has the following attributes:
name: Displayable symbolic name given to the view (string)
separate_cpus: Controls aggregation/separation by CPU (Boolean)
separate_processes: Controls aggregation/separation by process (Boolean)
separate_threads: Controls aggregation/separation by thread (Boolean)
default_view: Identifies this view as a candidate default view (Boolean)
Boolean attributes are restricted to the string values "T" and "F".
The view's name will appear in a list of available views and should suggest the purpose of the view to the user. The separation/aggregation attributes are optional and default to false. CodeAnalyst shows a view after data collection, a so-called "default view." The default_view attribute is a hint to CodeAnalyst that the view could (or should) be selected as a default view. Please use this attribute sparingly. The default_view attribute is optional and it's default value is false.
A <view> element contains one each of the following elements:
<data> | Describes the event data needed to show the view |
<output> | Describes how the event data will be shown |
<tool_tip> | Tool tip to be shown for the view |
<description> | Short description to be shown for the view |
Combining these elements, a view configuration file has the overall structure shown here:
<view_configuration>
<view name="View name"
separate_cpus="T" separate_processes="F" separate_threads="F">
<data>
<!-- List of event data needed -->
</data>
<output>
<!-- List of "columns" to be shown -->
</output>
<tool_tip>
Tool tip text
</tool_tip>
<description>
Short descriptive text
</description>
</view>
</view_configuration>
The <data> element specifies the event data that is needed to produce the view. CodeAnalyst uses this information to determine if a view is producable from a data set and will not offer the view to the user if it cannot be produced from available event data in the session. The <data> element must appear before the <output> element since the <output> element makes use of identifiers which are defined in the <data> element.
The <data> element contains one or more <event> elements. An <event> element:
An <event> element has three attributes:
id: Symbolic name given to the event data
select: Event selection value (hexadecimal integer)
mask: Event selection unit mask (hexadecimal integer)
The select and mask attributes take values as specified by the definition of performance events in the BIOS and Kernel Developers Guide (BKDG.) CodeAnalyst may choose to ignore the mask attribute when selecting event data.
With respect to future expansion and enhancement, new elements like the <event> element may be defined to accomodate new hardware performance measurement features.
The <output> element specifies how event data will be shown. The <output> element contains one or more <column> elements. Each <column> element specifies a column of event data in a table. (The notion of column may be extended to a dimension in a graphical chart.) A <column> element has the following attributes:
title: Title or legend to be displayed along with the data (string)
sort: Controls sorting of data in the column (string)
visible: Controls column visibility (Boolean)
The title attribute is a descriptive string that is used to label the data in a table or graph. The sort attribute specifies whether the data should be sorted or not. The sort attribute has only three permitted values: "ascending", "descending" and "none". At most one column should have a sort attribute of "ascending" or "descending"; all other columns should be "none". The visible attribute is optional and has the default value true. A column may be hidden by setting the visible attribute to false. Generally, you should not need to define a hidden column.
A <column> element is non-empty and contains exactly one of the following empty elements:
<value> | Show the selected event data as a simple value |
<sum> | Show the sum of two selected event data |
<difference> | Show the difference of two selected event data |
<product> | Show the product of two selected event data |
<ratio> | Show the ratio of two selected event data |
These elements select and combine the event data to be shown in the column. A <value> element has a single attribute:
id: Data identifier to select event data
The <sum>, <difference>, <product> and <ratio> elements take two attributes:
left: Data identifier to select data for the left operand
right: Data identifier to select data for the right operand
In the case of <ratio>, for example, the left identifier specifies event data for the numerator and the right identifier specifies event data for the denominator.
Note: Simple <value> elements using an event must appear before any <sum>, <ratio>, ... elements in the <output> section that use the same event. This ordering is required by the CodeAnalyst user interface.
With respect to future enhancement, additional elements like <sum>, etc. can be defined to combine event data. One such addition may be a <formula> element that defines a formula to be evaluated using event data. The formula may use identifiers to refer to event data.
A <tool_tip> element is a non-empty XML element that contains the text of a tool tip to be displayed for the view. A <description> element is a non-empty XML element that contains the text of a short description to be displayed for the view. Leading and trailing space is trimmed from tool tip and description text. Spaces are compressed and new line characters are replaced by a single space.
Here is an example view configuration file. Note that several optional attributes are not used in the example and they take on the appropriate default values.
<!--
Show instructions per cycle
View configuration
Date: 17 May 2006
Version: 0.1
-->
<view_configuration>
<view name="IPC"
separate_cpus="F"
separate_processes="F"
separate_threads="F"
>
<data>
<event id="CPU_clocks" select="76" mask="00" />
<event id="Ret_instructions" select="c0" mask="00" />
</data>
<output>
<column title="Instructions" sort="none">
<value id="Ret_instructions" />
</column>
<column title="Cycles" sort="none">
<value id="CPU_clocks" />
</column>
<column title="IPC" sort="descending">
<ratio left="Ret_instructions" right="CPU_clocks" />
</column>
<column title="CPI" sort="none">
<ratio left="CPU_clocks" right="Ret_instructions" />
</column>
</output>
<tool_tip>
Show instructions per cycle
</tool_tip>
<description>
Use this view to find hot-spots with low instruction level paralellism.
</description>
</view>
</view_configuration>