JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Studio 12.3: Discover and Uncover User's Guide     Oracle Solaris Studio 12.3 Information Library
search filter icon
search icon

Document Information

Preface

1.  Introduction

2.  Memory Error Discovery Tool (Discover)

3.  Code Coverage Tool (Uncover)

Requirements for Using Uncover

Using Uncover

Instrumenting the Binary

Running the Instrumented Binary

Generating and Viewing the Coverage Report

Examples

Understanding the Coverage Report in the Performance Analyzer

The Functions Tab

The Uncoverage Counter

The Function Count Counter

The Instr Exec Counter

The Block Covered % Counter

The Instr Covered % Counter

The Source Tab

The Disassembly Tab

The Inst-Freq Tab

Understanding the ASCII Coverage Report

Understanding the HTML Coverage Report

Limitations When Using Uncover

Only Annotated Code Can Be Instrumented

Machine Instructions Might Differ From Source Code

Example 1

Example 2

Example 3

Index

Understanding the Coverage Report in the Performance Analyzer

By default, when you run the uncover command on the coverage directory, the coverage report is opened as an experiment in the Oracle Solaris Studio Performance Analyzer. The Analyzer uses the Functions, Source, Disassembly, and Inst-Freq tabs to display the coverage data.

The Functions Tab

When you open the coverage report in the Analyzer, the Functions tab is selected. The tab displays columns listing the Uncoverage, Function Count, Instr Exec, Block Covered %, and Instr Covered % counters for each function. You can make any column the sort key for the data by clicking on the column header. Clicking the arrow on the column header reverses the sort order.

image:Functions tab of Uncover report for Performance Analyzer

The Uncoverage Counter

The Uncoverage metric is a very powerful feature of Uncover. If you use this column as the sort key, in decreasing order, the top functions in the display are the functions that offer the greatest potential to increase coverage. In the example, the main() function is at the top of the list because it has the largest number in the Uncoverage column. (The sigprof() and sigprofh() functions all have the same number, so they are listed in alphabetical order.)

The Uncoverage number for the main() function is number of bytes of code that could potentially be covered if a test is added to the suite that causes the function to be called. The amount that coverage would actually increase varies according to the structure of the function. If there are no branches in the function, and all the functions it calls are also straight line functions, then coverage will indeed increase by the stated number of bytes. But in general, the coverage increase is less than the potential, perhaps much less.

The uncovered functions with non-zero values in the Uncoverage column are called root uncovered functions, meaning that they are all called by covered functions. Functions that are called only by non-root uncovered functions do not have their own uncoverage numbers. It is presumed that these functions will be either covered, or revealed as uncovered, in subsequent runs, as the test suite is improved to cover the high-potential uncovered functions.

The coverage numbers are non-exclusive.

The Function Count Counter

The Function Count reports the covered functions and uncovered functions. All that matters is whether the count is zero or non-zero. If the count is zero, the function is not covered. If the count is non-zero, the function is covered. If any instruction in the function is executed, the function is considered to be covered.

You can detect non-top-level uncovered functions in this column. If the Function Count for a function is zero and the Uncoverage number is also zero, the function is not a top-level covered function.

The Instr Exec Counter

The Instr Exec counter displays the covered instructions and uncovered instructions. A zero count means that the instruction is not executed; a non-zero count means that the instruction is executed.

In the Functions tab, this counter shows the total number of instructions executed for each function. This counter also appears in the Source tab (see The Source Tab) and the Disassembly tab (see The Disassembly Tab).

The Block Covered % Counter

For each function, the Block Covered % counter displays the percentage of basic blocks in the function that are covered. This number gives you an idea of how well the function is covered. Disregard this number in the <Total> row; it is the sum of percentages in the column and is meaningless.

The Instr Covered % Counter

For each function, the Instr Covered % counter displays the percentage of instructions in the function that are covered. This number also gives you an idea of how well the function is covered. Disregard this number in the <Total> row; it is the sum of percentages in the column and is meaningless.

The Source Tab

If you compiled your binary with the -g option, the Source tab displays the source code of your program. Because Uncover instruments your program at the binary level, and you have compiled the program with optimization, the coverage information in this tab can be puzzling to interpret.

The Instr Exec counter in the Source tab shows the total number of instructions executed for each source line, which is essentially the statement level code coverage information. A non-zero value implies that the statement is covered; a zero value means that the statement is not covered. Variable declarations and comments have no Instr Exec counts.

image:Source Tab of Uncover report for Performance Analyzer

Some source code lines might not have any coverage information associated with them. In these cases, the rows are blank and have no numbers in any of the fields. These rows occur because:

For more information, see Limitations When Using Uncover.

The Disassembly Tab

If you select a line in the Source tab, and then select the Disassembly tab, the Analyzer tries to find the selected line in the binary and display its disassembly.

The Instr Exec counter in this tab shows the number of times each instruction was executed.

image:Disassembly tab of Uncover report for Performance Analyzer

The Inst-Freq Tab

The Inst-Freq tab displays the overall coverage summary.

image:Inst-Freq tab of Uncover report for Performance Analyzer