Profile Configuration File Format

A data collection configuration file describes how CodeAnalyst is to be configured for data collection. Through the CodeAnalyst GUI, the user chooses one several data collection configurations. The GUI configures data collection according to the selected configuration.

The user may also modify a data collection configuration to fit their needs using the CodeAnalyst GUI. The modified data collection configuration can be saved to a file.

A data collection configuration file contains a single configuration. The file representation of a data collection configuration is in XML.

XML file format

Collection configuration

The and tags mark the beginning and end of configuration information within a data collection configuration file.


  <dc_configuration>
    ...
  </dc_configuration>

A collection configuration element contains one <tbp>, <ebp> or <sim> element. Each element describes a data collection configuration of the type indicated by its element name. Each such element describes how to configure CodeAnalyst to collect data.

TBP collection configuration

The <tbp> and </tbp> tags mark the beginning and end of a time-based profiling data collection configuration.

A <tbp> element has the following attributes:

name: Configuration name (string)
interval: Sampling interval given in milliseconds (float)

A TBP collection configuration element contains exactly one of the following elements: <tool_tip> and <description>. The <tool_tip> and <description> elements have a common form and are described below.

A time-based profiling configuration has the form:


  <dc_configuration>
    <tbp name="..." interval="10.0">
      <tool_tip> ... </tool_tip>
      <description> ... </description>
    </tbp>
  </dc_configuration>

EBP collection configuration

The <ebp> and </ebp> tags mark the beginning and end of a event-based profiling data collection configuration.

An <ebp> element has the following attributes:

name: Configuration name (string)
mux_period: Event multiplexing period in milliseconds (integer)

The mux_period attribute specified the event multiplexing period. If the mux_period is zero, event multiplexing is disabled. Event multiplexing should not be used when there is only one event group.

An EBP collection configuration element contains exactly one of the following elements: <tool_tip> and <description>.

An EBP collection configuration element contains one or more event group elements. The tags <group> and </group> mark the beginning and end of an event group element. An event group element describes how a group of event counters will be configured. An event group does not have attributes.

An event <group> element contains one or more event elements. The tags <event> and </event> mark the beginning and end of an event element. An event element describes how an individual event counter is configured for data collection.

The maximum number of event elements per group depends upon the number of counters supported by the platform on which measurements are to be taken. For example, AMD Athlon64 and Opteron processors have four performance counters and thus, the number of <event> elements is limited to a maximum of four. Information from extra <event> elements may be discarded.

An <event> element has the following attributes:

select: Event select value (integer)
mask: Unit mask value (integer)
os: Enables OS sampling (Boolean)
user: Enabled user-level sampling (Boolean)
count: Sampling period (integer)
edge_detect: Enable edge detect when counting events (Boolean)
host: Enable host mode event counting Boolean)
guest: Enable guest mode event counting (Boolean)

The values must be validated against the events and specific capabilities supported by the measurement platform.

An event-based profiling data collection configuration has the form:


  <dc_configuration>
    <ebp name ="..."  mux_period="10">
      <tool_tip> ... </tool_tip>
      <description> ... </description>
      <group>
        <event select="0x00" mask="0x00" os="T" user="T"
           host="F" guest="F" edge_detect="F" count="50000"></event>
        ...
      </group>
    </ebp>
  </dc_configuration>

SIM collection configuration

The <sim> and </sim> tags mark the beginning and end of a simulation data collection configuration.

A sim element has the following attributes:

name: Configuration name (string)
warmup_caches: Warm up caches during simulation (Boolean)
run_sim_after: Run simulation after collecting the trace (Boolean)
save_trace: Save trace after generating it (Boolean)
trace_file_name: Name of trace file (string)
proc_core: Processor to use during simulation (string)
multiplier: Processor clock multipler to use for simulation (integer)
max_to_trace: Maximum instructions to trace times 1000 (integer)

A SIM collection configuration element contains exactly one of the following elements: <tool_tip> and <description>.

Valid values for the proc_core attribute are: "AMD Athlon", "AMD Athlon64", "AMD Opteron".

A pipeline simulation data collection configuration has the form:


  <dc_configuration>
    <sim name="..." warmup_caches="F" run_after_sim="T" save_trace="F"
         proc_core="AMD Opteron" multiplier="12" max_to_trace="10">
      <tool_tip> ... </tool_tip>
      <description> ... </description>
    </sim>
  </dc_configuration>

IBS collection configuration

The <ibs> and </ibs> tags mark the beginning and end of an instruction-based sampling (IBS) data collection configuration.

An ibs element has the following attributes:

name: Configuration name (string)
fetch_sampling: Enable IBS fetch sampling (Boolean)
fetch_max_count: Maximum periodic count/sampling period (integer)
op_sampling: Enable IBS op sampling (Boolean)
op_max_count: Maximum periodic count/sampling period (integer)

An IBS data collection configuration has the form:


  <dc_configuration>
    <ibs name="config name ..."
         fetch_sampling="T"
         op_sampling="F"
         fetch_max_count="500000"
         op_max_count="1000000"
         >

      <tool_tip> ...  </tool_tip>
  
      <description> ...  </description>
    </ibs>
  </dc_configuration>

Tool tip

The tags <tool_tip> and </tool_tip> mark the beginning and end of a short "tool tip" description of a configuration. The text between the tags is the tool tip description.


  <tool_tip> ... </tool_tip>

A tool tip is usually only a few key words with no line breaks.

Description

The tags <description> and </description> mark the beginning and end of a short description of a configuration. The text between the tags is the description.


  <description> ... </description>

A description is usually only a few sentences long. It may contain line breaks. Line breaks and extra space will be simplified. Line breaks will be replaced by spaces and runs of space characters will be replaced by single space characters.

Attributes

The value of a numeric attribute is returned as a string that can be converted to internal integer and floating point representation. The actual values may be further constrained for the attribute's purpose, e.g., the number of simulated instructions must be greater than 0. The default value for a numeric attribute is zero.

The value of a Boolean attribute is returned as one of the strings "T" or "F", which denote the truth values true and false, respectively. The default value of a Boolean attribute is "F".

Examples of XML Files

TBP example

Here is an example of a data collection configuration for time-based profiling.


  <dc_configuration>
    <tbp name="Time-based profile" interval="10.0">
      <tool_tip> Measure time in program regions </tool_tip>
      <description>
        Monitor the program and produce a profile showing where the program
        spends its time. Use this configuration to identify hot-spots. 
      </description>
    </tbp>
  </dc_configuration>

EBP example

Here is an example of a data collection configuration for event-based profiling.


  <dc_configuration>
    <ebp name ="Quick tune"  mux_period="100000">

      <group>
        <!-- CPU clocks unhalted -->
        <event select="0x76" mask="0x00" os="T" user="T" count="50000"></event>

        <!-- Retired instructions -->
        <event select="0xC0" mask="0x00" os="T" user="T" count="50000"></event>

        <!-- In order to detect branch mispredictions -->
        <event select="0xC2" mask="0x00" os="T" user="T" count="5000"></event>

        <!-- Mispredicted branches -->
        <event select="0xC3" mask="0x00" os="T" user="T" count="5000"></event>
      </group>

      <group>
        <!-- Data cache accesses -->
        <event select="0x40" mask="0x00" os="T" user="T" count="5000"></event>

        <!-- Data cache misses -->
        <event select="0x41" mask="0x00" os="T" user="T" count="5000"></event>

        <!-- L1 DTLB and L2 DTLB Miss -->
        <event select="0x46" mask="0x00" os="T" user="T" count="5000"></event>

        <!-- Misaligned accesses -->
        <event select="0x47" mask="0x00" os="T" user="T" count="5000"></event>
      </group>

      <tool_tip> Perform quick accessment </tool_tip>

      <description>
        Collect data needed to quickly identify possible performance issues.
        Good candidates for further investigation are frequently executed,
        time-consuming parts of the program. Use analysis configurations for
        follow-up investigations.
      </description>
    </ebp>
  </dc_configuration>

Pipeline simulation example

Here is an example of a data collection configuration for pipeline simulation.


  <dc_configuration>
    <sim name="Pipeline simulation"
         warmup_caches="F" run_after_sim="T"
         save_trace="F" trace_file_name="none"
         proc_core=""  multiplier="12" max_to_trace="5">
  
      <tool_tip> Simulate code region </tool_tip>

      <description>
         Pipeline simulation traces and then simulates the execution of a
         code region in the application. Expert knowledge of the processor
         pipeline is required.
      </description>
    </sim>
  </dc_configuration>

IBS configuration example

Here is an example of an instruction-based sampling data collection configuration.


  <dc_configuration>
    <ibs name="Instruction-based sampling"
         fetch_sampling="T"
         op_sampling="T"
         fetch_max_count="250000"
         op_max_count="250000"
         >

      <tool_tip>
        Collect data using instruction-based sampling
      </tool_tip>
  
      <description>
        Use this configuration to collect profile data using instruction-based
        sampling. Samples are attributed to instructions precisely with IBS.
      </description>
    </ibs>
  </dc_configuration>