In this section:

Introduction

The flat-text report has specially formatted summary statistics that can be easily parsed by a machine. This does not apply to the entire file as it is still up to a human to actually read the output if there is an issue. Each annotated line represents a different set of data, which is intended to be read line by line.

Format of Annotated Lines

Annotated lines have eight characters attached to the beginning. The characters are referred to as the "tag," which indicates that the line is annotated. The first character of the tag will always be an exclamation point (!). Tags that begin with any other character indicate that the line does not have annotations associated with ASMTools.

Identifying Hash Value Mismatches

You can identify hash value mismatches by the sequence of the second, third, and fourth characters in the tag:

• The second character of a hash is M, which stands for metric.

• The third character is H, which stands for hash.

• The fourth character will either be T or F, which stands for true and false, respectively.

The following table describes legal annotation combinations:

To assist parsing efforts, the path to the executable used and corresponding computed hash value are provided on the same line following the tag. The format is:

tag path-to-executable md5hash

Identifying Project Names

Tags that begin with !P indicate that the line describes the project name. The format is:

!P  <project-name>

Identifying the Report Timestamp

Tags that begin with !D indicate that the line describes the time and date that the report was generated. The format is:

!D   <date-and-time>

Example:

!D   03/31/15 18:02:10

Extracting Statistics from Different Project Levels

You can extract statistics at the project, translation unit, and function levels. Statistics at each level are wrapped with beginning and ending tag lines that describe what kind of statistics the data represents. The basic format is:

!xMy <name> 

• The second character (represented by x above)is either ( or ). The opening paren indicates the beginning of the line. The closing paren indicates the end of the line.
• The third character is M, which stands for metric. This is the only value allowed in this position. 
• The fourth character (represented by y above) indicates the level associated with the data and can have one of the following values:
  • A P indicates project-level statistics 
  • A T indicates translation-level statistics
  • An F indicates function-level statistics
• The name field following the tag corresponds to the unit type.

The following table describes possible combinations:

A name after a tag identifying project-level statistics specifies the name of the project. For example, the following tags mark the statistics for a project called "simulator":

!(MP    simulator
...
!)MP    simulator

The name of the translation unit includes the path. The tags in the following example mark the statistics associated with the src/libsim/decode.cpp translation unit:

!(MT    src/libsim/decode.cpp
...
!)MT    src/libsim/decode.cpp

The tags in the following example mark the statistics associated with the fused_multiply_add function:

!(MF    fused_multiply_add
...
!)MF    fused_multiply_add

Parsing Instruction Coverage Statistics

Tags that begin with !I indicate lines that include instruction coverage information. The format is:

!Ix <value>

• The second character is I, which stands for instruction. 
• The third character (represented by x above) is either C or T. 
  • A C indicates that the value refers to the number of covered instructions 
  • A T indicates that the value refers to the total number of instructions for the given project, translation unit, or function.

The tags in the following example indicate that for a project called "simulator" has 6561 total instructions, but only 5007 instructions are covered:

!(MP    simulator
!IC     5007
!IT     6561
...
<additional stats>
...
!)MP    simulator

You could calculate the coverage percentage by dividing the value associated with the covered tag by the value of the total tag (i.e., 5007/6561=76.3%).

Parsing Branch Coverage Statistics

Tags that begin with !B indicate lines that include instruction coverage information. The format is:

!Bxy <value>

• The second character is B, which stands for branch coverage. 
• The third character (represented by x above) is either A, T, or N. 
  • An A indicates that the value refers to all branch forms, including conditional taken, conditional not taken, and unconditional executed branches.
  • A T indicates that the value refers to conditional taken and unconditional executed branches.
  • An N indicates that the value refers to conditional not taken and unconditional executed branches.
• The fourth character (represented by the y above) is either C or T. 
  • A C indicates that the value refers to the number of covered branch execution aspects. 
  • A T indicates that the value refers to the total number of branch execution aspects for the given project, translation unit, or function.

The following table describes possible combinations:

All branch and conditional taken/unconditional executed forms represent specific branch execution aspects. There is only one aspect to an unconditional branch's execution. If the unconditional branch is executed, then the flow of execution will change.

There are two execution aspects in the case of a conditional branches: 

1. The first is if the condition of the branch is true and the flow of execution changes.
2. The second is if the condition of the branch is false and the flow of execution continues to the next instruction following the branch.

In the case of all branch forms (A), the total branches represent the total number of branch execution aspects and not the total number of branches. The total number of branch execution aspects is generally unconditional branch count plus two times the conditional branch count.

An unconditional branch execution and conditional taken execution are both viewed as control of the program being transfered to another point in the program. Conditional not-taken execution, however, represents control continuing onto the next instruction in the current linear sequence of instructions.

Human-readable Section of the Report

The report also includes tags that mark the beginning and end of translation units in the human readable portion. The format is:

!xF <file>

The second character (represented by x above) is either ( or ), marking the beginning or end of a give file. The name of the translation unit follows the tag and the lines between the tags represent the contents of the translation unit at the assembly level.