In this section:

Introduction

Asmreporter creates reports using the static data (.pail file) generated by the Asminst tool during the build process. Decoration added to the static data by other tools will also be represented in the reports.

In this section, we assume that you've already installed Parasoft ASMTools and that they are on your system path. Refer to Parasoft ASMTools for information about the full tool chain, including installation and requirements.

The expected use case is to run asmreporter after the static and dynamic data has been generated and merged with the Asminst tool and the coverage data has been correlated with the Asmcovbuf tool. You can also run the Asmdemangler and Asminfer tools to rewrite labels in the .pail file and produce information about how the assembly was constructed, respectively, prior to running asmreporter. You can, however, run asmreporter prior to processing the  .pail file with asmcovbuf, asmdemangler, or asminfer, but no coverage will be reported.

Basic Usage

Run asmreporter and specify the static data file and report format to generate:

$ asmreporter --input-file <path/to/static/data/file.pail> --report-format <format>

Use the --input-file flag to specify the static data file. This file is created by instrumenting  objects, archives, and executables using the Asminst and merged with a dynamic data file (.padd) with the Asmcovbuf to output coverage.  

Use the --report-format flag to specify the type of report you want to generate. The following formats are currently supported:

• txt - Generates a simple text coverage report
• csv -  Generates a comma-separated values coverage report
• html -  Generates an HTML coverage report

Flat-text Report Format

Specifying the txt format also generates the flat-text report, which includes specially formatted summary statistics that can be easily parsed by a machine. See Flat-text Report Format for details about this report format.

Examples

$ asmreporter --input-file C:\path\to\merged\data\example.pail --report-format txt

$ asmreporter --input-file /path/to/merged/data/example.pail --report-format txt

Generating Multiple Report Formats

You can specify multiple report formats by using additional --report-format flags. An HTML and text report will be generated in the following examples:

$ asmreporter --input-file C:\path\to\merged\data\example.pail --report-format txt --report-format html 

$ asmreporter --input-file /path/to/merged/data/example.pail --report-format txt --report-format html

Options

The following options are supported. See the Release Notes for deprecated and ignored options.

Reviewing Coverage Information

Asmreporter reports the following types of coverage:

• Instruction: Indicates which assembly instructions were executed within the instrumented program. Decoration produced by Asmcovbuf.
• Branch: Indicates how branch instructions were covered within the instrumented program. Decoration produced by Asmcovbuf. Branch coverage is reported for paths taken and not taken:
  • Taken: The branch condition was satisfied, causing the program execution to branch to a separate location. If the branch is unconditional, it will be considered taken if it was executed at some point in the program.
  • Not taken: The branch condition was not satisfied, resulting in the next sequential instruction (also known as “fall-through”) being executed. This concept has no bearing on unconditional branches as they will always branch if they are executed.
• Switch decision: Displays a table indicating how C/C++ switch statements are constructed in assembly. Decoration produced by Asminfer.

Text Reports

Text report have a Summary and a Detailed report section.

Summary

The summary report section contains coverage statistics for each file in the project.

!(F     Bank.cxx
---------------------------------------
Coverage totals for file [Bank.cxx]:
    Statement............................[20.9% 352/1682]
    Conditional/Unconditional Branch.....[12.3% 66/535]
        Conditional/Unconditional Taken..[12.6% 46/366]
        Conditional not taken............[11.8% 20/169]

Detailed Report

Coverage statistics are presented at the end of each function in the detailed report. The marker is either empty, a set of asterisks, a pair of Boolean characters (e.g., T/F) for conditional branches, or a single Boolean character for an unconditional branch. A conditional branch is marked, the first character indicates whether or not the branch was taken, and the second character indicates whether or not the branch fell through. The following table describes how coverage is marked: 

The following example shows a part of a detailed report:

[ T ] bctrl          	// unconditional indirect branch was taken
        ---> --------------------------------------
             Branched to following labels:
             --------------------------------------
               ExampleLabel1 (0xfded)
               ExampleLabel2 (0xabde)
             --------------------------------------
***   stw r0, 20(sp)  // covered instruction
***   mr r31, r3      // covered instruction
***   mr r30, r4      // covered instruction
***   cmpwi r31, 0    // covered instruction
[T/F] bne .L5         // branch condition evaluated to true,
                      // but never evaluated to false
      li r3, 8        // not covered instruction
[F]   bl foo.         // unconditional branch which was never executed
      mr r31, r3      // not covered instruction
      cmpwi r31, 0    // not covered instruction

Each detailed report section is called out, which can be useful for scripting custom reports:

--- Begin coverage information for <file> ---
<detailed report for file>
--- End coverage information for <file> ---

HTML Reports

If you specify html as the report format, then an HTML report will be produced in the results directory called <project_name>.html. The HTML report has two panes.

Test Execution Coverage Report

This pane shows an expandable view of coverage statistics for all analyzed files in the project. The total coverage statistics for the entire project is represented in the top node, which can be expanded into coverage statistics for each file. The file-level coverage statistics can be expanded to each function inside the file.

The report shows the following categories of coverage statistics:

• Instruction coverage
• Branch coverage - Total
• Branch coverage - Taken
• Branch coverage - Not Taken [Conditional branches only]

Click on a node to expand it and view coverage details.

Detailed Report

This pane displays assembly code for the file most recently selected in the coverage statistics menu pane. Coverage is marked using the same identifiers as described in the coverage markers table above.

HTML version of the detailed report are also color coded:

• Elements highlighted in green are covered
• Elements highlighted in red are not covered

CSV Reports

If you specify csv as the report format, then a new file <project_name>.csv will be generated. The report contains coverage statistics for the overall project, each source file in the project, and each method within each file. You can import the statics into a spreadsheet application, such as Microsoft Excel.

CSV-formatted reports use tabs to delimit the data, which is structured in the following way:

• The first row contains the header lables.
• The first column of the file contains the project’s name.
• The second column contains all the source files in the project.
• The third column contains all of the functions corresponding to the current source file that is being viewed.
• The rest of columns contain data about which statements were covered and the total number of statements corresponding to one of the first three columns.