# Code coverage

## hexagon-llvm-profdata

The hexagon-llvm-profdata tool is a tool for merging profile data files. It takes several profile data files generated by PGO instrumentation and merges them into a single indexed profile data file.

By default profile data is merged without modification. This means that the relative importance of each input file is proportional to the number of samples or counts it contains. In general, the input from a longer training run will be interpreted as relatively more important than a shorter run.

### Usage

hexagon-llvm-profdata merge [args…]
    Copy to clipboard

### Options

-h
    --help
    Copy to clipboard

Print a summary of command line options.

-o
    --output=<output>
    Copy to clipboard

Specify the output file name. Output cannot be `-`, as the resulting indexed profile data cannot be written to standard output.

### Example

This example describes merging of two data profiles.

hexagon-llvm-profdata merge a.profdata b.profdata -output code.profdata
    Copy to clipboard

## hexagon-llvm-cov

The hexagon-llvm-cov tool shows code coverage information for programs that are instrumented to emit profile data.

### Usage

hexagon-llvm-cov <command> [args…]
    Copy to clipboard

Where `command` can be:

- `show`
- `report`

### show command

hexagon-llvm-cov show [options] Covered executable or object file.
    <Source files>
    Copy to clipboard

#### Description

The `hexaon-llvm-cov show` command shows line-by-line coverage of the binaries (`BIN`), using the profile data `PROFILE`. It can optionally be filtered to only show the coverage for the files listed in `SOURCES`. `BIN` may be an executable, object file, dynamic library, or archive.

To use `hexagon-llvm-cov show`, you need a program that is compiled with instrumentation to emit profile and coverage data. To build such a program with hexagon-clang use the `-fprofile- instr-generate` and `-fcoverage-mapping` flags. If linking with the hexagon-clang driver, pass `-fprofile-instr-generate` to the driver.

The coverage information is stored in the built executable or library itself and this is what you should pass to `hexagon-llvm-cov show` as a `BIN` argument. The profile data is generated by running this instrumented program normally. When the program exits it will write out a raw profile file, typically called `default.profraw`, which can be converted to a format that is suitable for the `PROFILE` argument using `hexagon-llvm-profdata merge`.

#### Options

-format=<FORMAT>
    --format=<FORMAT>
    Copy to clipboard

Use the specified output format. The supported formats are: `text`, and `html`.

-instr-profile=<string>
    --instr-profile=<string>
    Copy to clipboard

File with the profile data obtained after an instrumented run.

-output-dir=<PATH>
    --output-dir=<PATH>
    Copy to clipboard

Specify a directory to write coverage reports into. If the directory does not exist, it is created.

-show-line-counts
    --show-line-counts
    Copy to clipboard

Show the execution counts for each line. Defaults to true, unless another `-show` option is used.

-show-regions
    --show-regions
    Copy to clipboard

Show the execution counts for each region by displaying a caret that points to the character where the region starts. Defaults to false.

-h
    -help
    --help
    Copy to clipboard

Print summary of command line options.

#### Example

This example describes generation of code coverage information in text format, given a source program `code.c`, corresponding binary object file code, and profile data of its execution.

hexagon-llvm-cov show -show-line-counts -instr-profile code.profdata code code.c -format=text -output-dir=.
    Copy to clipboard

This creates a directory, `coverage`, in the current directory containing the code coverage information in text format.

### report command

hexagon-llvm-cov report [options] Covered executable or object file.
    <Source files>
    Copy to clipboard

#### Description

The `hexagon-llvm-cov report` command displays a summary of the coverage of the binaries (`BIN`), using the profile data (`PROFILE`). It can optionally be filtered to only show the coverage for the files listed in `SOURCES`. `BIN` may be an executable, object file, dynamic library, or archive.

If no source files are provided, a summary line is printed for each file in the coverage data.

#### Options

-instr-profile=<string>
    --instr-profile=<string>
    Copy to clipboard

File with the profile data obtained after an instrumented run.

-h
    --help
    Copy to clipboard

Print summary of command line options.

#### Example

This example describes generation of code coverage summary, given a source program `code.c`, corresponding binary object file code, and profile data of its execution.

hexagon-llvm-cov report -instr-profile code.profdata code code.c
    Copy to clipboard

This displays a summary of the code coverage information.

## Code coverage information example

The hexagon-llvm-profdata and hexagon-llvm-cov utilities are used to generate code coverage information for programs that are instrumented to emit profile data.

This example describes how to generate code coverage information of a file, `code.c`, in HTML format.

1. Compile the program with the required instrumentations.

hexagon-clang -g -fprofile-instr-generate -fcoverage-mapping -c code.c -o code.o
        hexagon-clang -fprofile-instr-generate -fcoverage-mapping code.o -o code
        Copy to clipboard
2. Run the program to generate the raw profile data file.

hexagon-sim ./code
        Copy to clipboard

    Running the program generates a raw profile file with the default `default.profraw` filename.
3. Convert the `default.profraw` file to a format suitable for the PROFILE argument of the `hexagon-llvm-cov show` command using the hexagon-llvm-profdata tool.

hexagon-llvm-profdata merge default.profraw -o code.profdata
        Copy to clipboard
4. Generate the code coverage information

hexagon-llvm-cov show -show-line-counts -show-regions -instr-profile code.profdata code code.c -format=html -output-dir=.
        Copy to clipboard

    Running this command creates a folder named `coverage` in the current directory with the code coverage information in HTML format.
5. (Optional) Display a summary of the generated code coverage information.

hexagon-llvm-cov report -instr-profile code.profdata code code.c
        Copy to clipboard

Last Published: Oct 06, 2026

[Previous Topic
Other options](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/dwarf-dump.md)