Text of drm.pages.freedesktop.org › igt-gpu-tools › code_coverage as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

How to get code coverage - IGT GPU Tools

Skip to content Collecting code coverage data from IGT tests ¶ Introduction ¶ Ensuring that a test plan covers all the driver code is not trivial. Also, as time goes by, changes at both the tests and drivers may badly affect the code coverage. So, some tools are needed in order to be able to verify and improve the driver test coverage. While static analyzers can help checking the driver's code, it is not as effective as runtime tests.

Thankfully gcc has a feature which allows capturing such data in realtime, called gcov. LLVM/clang also has a similar feature (llvm-cov). Such feature is available at the Linux Kernel since 2009. Building a Kernel with GCOV support ¶ Enabling GCOV at the Linux Kernel requires two steps: Enable GCOV_KERNEL: ./scripts/config -e DEBUG_FS -e GCOV_KERNEL 2. Enable per-driver or per-makefile GCOV support. In order to enable support for all DRM drivers: ``` for i in $(find drivers/gpu/drm/ -name Makefile); do sed '1 a GCOV_PROFILE := y' -i $i done ``` When gcov is enabled for a given driver or directory, GCC will generate some special object files, like: ... drivers/gpu/drm/drm_probe_helper.gcno drivers/gpu/drm/drm_dp_dual_mode_helper.gcno drivers/gpu/drm/drm_plane.gcno drivers/gpu/drm/drm_lease.gcno drivers/gpu/drm/drm_mipi_dsi.gcno drivers/gpu/drm/drm_dsc.gcno drivers/gpu/drm/drm_property.gcno drivers/gpu/drm/drm_dp_aux_dev.gcno drivers/gpu/drm/drm_blend.gcno ...

Those will be stored at the Kernel object directory, which is usually the same as the Kernel source directory, except if the Kernel was built with: make O=kernel_output_dir Such compile-time files are compiler-dependent and they're needed in order to properly decode the code coverage counters that will be produced in runtime. Collecting GCOV data in runtime ¶ Once a GCOV-enabled Kernel boots, the Kernel will keep track of the code monitored via GCOV under sysfs, at /sys/kernel/debug/gcov/ .

There is a special file there: /sys/kernel/debug/gcov/reset . When something is written to it, all counters will be cleaned. There are also driver-related counters and softlinks stored there: ls -la /basedir/linux/drivers/gpu/drm/ ... -rw------- 1 root root 0 Feb 16 07:03 drm_probe_helper.gcda lrwxrwxrwx 1 root root 0 Feb 16 07:03 drm_probe_helper.gcno -> /basedir/linux/drivers/gpu/drm/drm_probe_helper.gcno -rw------- 1 root root 0 Feb 16 07:03 drm_property.gcda lrwxrwxrwx 1 root root 0 Feb 16 07:03 drm_property.gcno -> /basedir/linux/drivers/gpu/drm/drm_property.gcno -rw------- 1 root root 0 Feb 16 07:03 drm_rect.gcda lrwxrwxrwx 1 root root 0 Feb 16 07:03 drm_rect.gcno -> /basedir/linux/drivers/gpu/drm/drm_rect.gcno ...

The actual counters are stored at the *.gcda files on a compiler-dependent format. calling igt_runner directly ¶ When code coverage support is enabled, the igt_runner tool will internally clean up the counters before starting test(s). Once test(s) finish, it will also run an external script that will be responsible for collecting the data and store on some file. Enabling code coverage data collect can be done either per test or as a hole for an entire test list, by using those command line options: --collect-code-cov Enables gcov-based collect of code coverage for tests. --coverage-per-test Stores code coverage results per each test.

This option implies --collect-code-cov . For those options to work, it is mandatory to specify what script will be used to collect the data with --collect-script file_name . calling ./scripts/run-tests.sh script ¶ The run-tests.sh script can used instead as a frontend for igt_runner. It has the following options: -c <capture_script> Capture gcov code coverage using the capture_script -P Store code coverage results per each test. -k kernel_dir Linux Kernel source code directory used to generate code coverage builds.

This is passed through the capture script via the IGT_KERNEL_TREE shell environment variable. So, for instance, if one wans to capture code coverage data from the Kernel that was built at the same machine, at the directory ~/linux , and wants to capture one file per test, it would use: ./scripts/run-tests.sh -T my.testlist -k ~/linux -c code_cov_capture -P Code Coverage Collect script ¶ While any script could in thesis be used, currently, there are two ones under the IGT's scripts/ source directory: code_cov_capture : Assumes that the Kernel was built at the same machine, and uses the lcov tool to generate GCC-independent code coverage data, in the form of *.info files.

Internally, it uses an shell environment variable ( IGT_KERNEL_TREE ), which points to the place where the Kernel source and objects are contained. Such script requires lcov tool to be installed at the test machine. code_cov_gather_on_test : Generates a gzipped tarbal with the code coverage counters in binary format. Such kind of output should then be parsed at the same machine where the Kernel as built, as its content is not only dependent on the Kernel source, but also on the Kernel output objects.

For each script, the igt_runner passes just one parameter: the results directory + the test name. For instance, if it is needed to run a test called core_debugfs (read-all-entries) using code_cov_capture parameter, e. g.: $ echo "igt@core_debugfs@read-all-entries" > my.testlist $ ./scripts/run-tests.sh -T my.testlist -k ~/linux -c code_cov_capture -P Found test list: "/basedir/igt/build/tests/test-list.txt" [31410.499969] [1/1] core_debugfs (read-all-entries) [31411.060446] Storing code coverage results... [31418.01] Code coverage wrote to /basedir/igt/results/code_cov/core_debugfs_debugfs_read_all_entries.info Done.

The script will be called as: code_cov_capture results/code_cov/core_debugfs_debugfs_read_all_entries Please notice that any character that it is not a number nor a letter at the test name will be converted into '_', as other characters are not supported as titles at the lcov files. Passing extra arguments to the script ¶ If any extra global parameters are needed by the script, those can be sent via shell's environment var.

Parsing data from code coverage *.info files ¶ The *.info files generated by lcov are plain text files that list the tests that were executed in runtime. The code_cov_parse_info script has some logic on it that allows printing the called functions stored inside the *.info file. It can also optionally apply the following filters. Its main options are: --stat or --statistics Prints code coverage statistics. It displays function, line, branch and file coverage percentage.

The statistics report is affected by the applied filters. --print-coverage , --print or -p Prints the functions that were executed in runtime and how many times they were reached. The function coverage report is affected by the applied filters. --print-unused or -u Prints the functions that were never reached. The function coverage report is affected by the applied filters. --show-lines or --show_lines When printing per-function code coverage data, always output the source file and the line number where the function is defined. --output output file or -o output file Produces an output file merging all input files.

The generated output file is affected by the applied filters. --show-files or --show_files Shows the list of files that were useed to produce the code coverage results. It also has a set of parameters that filters the code coverage results: --only-drm , --only-i915 , --func-filters , --source-filters , --ignore-unused . When used, all coverage displayed reports, and the stored output file will be affected by such filters.

More details can be seen by calling: code_cov_parse_info --help or: code_cov_parse_info --man The *.info file format ¶ The *.info files contain several fields on it, grouped into records. An info file looks like: TN:fbdev_eof ... SF:/basedir/linux/drivers/gpu/drm/i915/intel_runtime_pm.c ... FN:158,__intel_runtime_pm_get FNDA:2,__intel_runtime_pm_get ... end_of_record SF:<some other file> ... end_of_record ... The main fields

The rest of this page is on the live site.