info-process

Copyright (c) 2025 Antmicro

info-process is a tool processing LCOV's .info format. Such files can be used in, e.g., Coverview which is a tool for generating coverage dashboards. The overview of the .info format is available in LCOV's geninfo manual page (man geninfo) in the FILES section and online. Tool is aimed at working with coverage reports generated by running hardware simulations, for example in Verilator.

Installation

The tool can be installed using pip:

pip install git+https://github.com/antmicro/info-process.git

The minimum supported Python version is 3.9

Transforming .info files

Various transformations can be made to the provided .info files. By default files are modified in place. Multiple transformations can be made to the input file by specifying multiple options, described further.

Adding missing BRDA entries

BRDA entries can be added for lines that only contain DA entries using the --add-missing-brda-entries option.

For example:

info-process transform --add-missing-brda-entries coverage-toggles.info

will modify the coverage-toggles.info file in-place like so:

 DA:30,1
 DA:31,0
 BRDA:30,0,toggle,1
+BRDA:31,0,toggle,0

Duplicating BRDA entries

BRDA entries can be duplicated using the --add-two-way-toggles option. Old entries will be replaced by two entries with _0->1 and _1->0 suffixes added to their names.

For example:

info-process transform --add-two-way-toggles coverage-toggles.info

will modify the coverage-toggles.info file in-place like so:

-BRDA:30,0,toggle[0],1
+BRDA:30,0,toggle[0]_0->1,1
+BRDA:30,0,toggle[0]_1->0,1
-BRDA:31,0,toggle[1],6
+BRDA:31,0,toggle[1]_0->1,6
+BRDA:31,0,toggle[1]_1->0,6

Note that this option will not check if the file already contains duplicated entries.

Modifying SF entries

Source file paths in SF entries (SF:<PATH>) can be stripped based on a regular expression provided with the --strip-file-prefix <REGEX> option. Additionally, records for specific source files can be filtered out based on their paths matching a regular expression provided with the --filter <REGEX> option. For non-matching paths you can use --filter-out <REGEX>. Please note that filtering is performed on stripped paths when these two options are used together.

For example, to strip /root/designs/ prefixes from SF entries in a coverage-toggles.info file and only keep records for files from the /root/designs/unit-tests directory, one can run:

info-process transform --filter 'unit-tests' --strip-file-prefix '.*/designs/' coverage-toggles.info

Normalizing toggle hit counts

Hit counts greater than 1 in BRDA and DA entries can be replaced with 1 with the --normalize-hit-counts option.

For example:

info-process transform --normalize-hit-counts coverage-toggles.info

will modify the coverage-toggles.info file in-place like so:

 BRDA:30,0,toggle_0,1
-BRDA:30,0,toggle_1,27
+BRDA:30,0,toggle_1,1
 DA:48,0
-DA:49,159
+DA:49,1

Setting block IDs

Block IDs in BRDA entries (numbers that are between line number and name) for the same line can be replaced with consecutive numbers.

For example:

info-process transform --set-block-ids coverage-toggles.info

will override the block IDs like so:

 BRDA:30,0,toggle[0],0
-BRDA:30,0,toggle[1],12
+BRDA:30,1,toggle[1],12
 BRDA:31,0,toggle[2],1
-BRDA:31,0,toggle[3],35
-BRDA:31,0,toggle[4],0
+BRDA:31,1,toggle[3],35
+BRDA:31,2,toggle[4],0

Assigned block IDs can be incremented after encountering a configurable amount of matching BRDA entries, by additionally using the --set-block-ids-step <NUMBER> flag. For example using --set-block-ids-step 2 will increment the assigned block ID on every other matching BRDA entry like so:

 BRDA:30,0,toggle[0]_0->1,1
 BRDA:30,0,toggle[0]_1->0,1
-BRDA:30,0,toggle[1]_0->1,1
-BRDA:30,0,toggle[1]_1->0,1
-BRDA:30,0,toggle[2]_0->1,1
-BRDA:30,0,toggle[2]_1->0,1
+BRDA:30,1,toggle[1]_0->1,1
+BRDA:30,1,toggle[1]_1->0,1
+BRDA:30,2,toggle[2]_0->1,1
+BRDA:30,2,toggle[2]_1->0,1

Merging .info files

Multiple .info files can be merged using the merge subcommand, e.g.

info-process merge --output coverage-merged.info coverage-test1.info coverage-test2.info coverage-test3.info

which will merge coverage-test1.info, coverage-test2.info, coverage-test3.info files and save the result to coverage-merged.info.

The output file will contain information merged for matching files based on SF paths with:

• recalculated BRF, BRH, LF and LH entries,
• DA entries with total hits for the given line from the input files,
• BRDA entries with total hits for the given line and name from the input files and the highest block ID found for the given name in the input files.

BRDA entries for the given line will be sorted lexicographically with proper number handling, i.e., id[0], ..., id[9], id[10]... This might cause block IDs to be out of order in the output file if they were sorted differently in the input files.

To apply this new order to the block IDs of the merged file, one can use --set-block-ids option of the transform subcommand:

info-process transform --set-block-ids coverage-merged.info

Test-list file

An additional file with names of tests which provided hits for each line can be optionally created with a --test-list option during merging, e.g.:

info-process merge --test-list test-list.desc --output coverage-merged.info coverage-test1.info coverage-test2.info coverage-test3.info

The output file is structured similarly to the .info files with the following entries for every source file:

• SN:<SOURCE_FILE_PATH>
• TEST:<LINE>,<TEST_PATH_1>[;<TEST_PATH_2>...] for each line if there were any hits
• end_of_record

Test names customization

Test names are constructed from paths of input files with common path prefixes and .info suffixes removed by default, e.g., test1 and test2 will be used for input files /ci/test1.info and /ci/test2.info. Additional strings which should be removed from test names can be provided with a --test-list-strip <STRING1>[,<STRING2>...] option.

For example, coverage- and -all.info can be removed from paths before using them as test names with:

info-process merge --test-list test-list.desc --test-list-strip coverage-,-all.info --output coverage-merged.info /ci/tests/coverage-*-all.info

A common path prefix (/ci/tests/ in this case) is removed by default and shouldn't be included in the --test-list-strip option. This behavior can be disabled with a --test-list-full-path option.

Creating Coverview archives

Archives viewable in Coverview can be created using the pack subcommand, e.g.

info-process pack --output data.zip --config config.json --coverage-files *.info --description-files *.desc --extra-files logo.svg

which will create a zip archive containing files provided in the --config, --coverage-files, --description-files and --extra-files. The created archive can be directly used in Coverview. If path provided in --output has .zip extension then a zip archive containing all needed files will be created. If this extension is not present then the results will be placed in a directory.

Generating the "datasets" property

Coverview requires a config.json file with datasets property, which stores information how the coverage data should be displayed. This property can be automatically generated by info-process pack from files provided in --coverage-files and --description-files switches, if it is not present in the configuration provided in --config. Automatic datasets generation is only possible if all provided coverage file names match a coverage_{TYPE}_{DATASET}.info pattern and all description file names match a tests_{TYPE}_{DATASET}.desc pattern. Where TYPE is the type of the coverage (e.g. branch, line) and DATASET is the name of the dataset, which is used for grouping coverage files together (e.g. grouping coverage files generated from different simulators).

Generation source information

info-process pack will automatically generate the sources.txt file, used by Coverview to display file sources, based on SF entries in the provided .info files. By default source files are assumed to be available in the current working directory, which can be changed using the --sources-root <SOURCES_ROOT> option which makes info-process look for source files in the provided directory.