esp-idf/examples/system/gcov/README.md

Blink Example With Coverage Info (Gcov)

(See the README.md file in the upper level 'examples' directory for more information about examples.)

The following example demonstrates how to compile an ESP-IDF project to generate code coverage data, and how generate a code coverage report using Gcov or Lcov. Refer to the Gcov Guide for more details on the code coverage features supported in ESP-IDF.

This example implements a simple blink application but with code coverage enabled. The example will demonstrate the following features:

• How to compile a project with the --coverage flag
• Various methods of dumping code coverage data (e.g. Instant Run-Time Dump and Hard-coded Dump).
• How to generate a code coverage report.

How to use example

Hardware Required

To run this example, you need an ESP32 dev board connected to a JTAG adapter, which can come in the following forms:

• ESP-WROVER-KIT which integrates an on-board JTAG adapter. Ensure that the required jumpers to enable JTAG are connected on the WROVER-KIT.
• ESP32 core board (e.g. ESP32-DevKitC) can also work as long as you connect it to an external JTAG adapter (e.g. FT2232H, J-LINK).

This example will assume that that an ESP-WROVER-KIT is used.

1. Connect the JTAG interface to ESP32 board, and power up both the JTAG and ESP32. For details about how to set up JTAG interface, please see JTAG Debugging.

2. After connecting JTAG interface, you need to Run OpenOCD.

3. Open a separate terminal window and run telnet by entering the command below. The telnet terminal window is used to feed commands to OpenOCD:

telnet localhost 4444

Configure the project

idf.py menuconfig

The example will enable the following options by default:

• Enable the Application Tracing Module under Component config -> Application Level Tracing -> Data Destination by choosing Trace memory.
• Enable GCOV to host interface under Component config -> Application Level Tracing -> GCOV to Host Enable.
• Enable OpenOCD Debug Stubs under Component config -> ESP32-specific -> OpenOCD debug stubs

Build, Flash, and Run

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py -p PORT flash monitor

(Replace PORT with the name of the serial port to use.)

(To exit the serial monitor, type Ctrl-].)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

Example Output

1. Hard-coded Dump

The example will initially execute two hard-coded dumps. Therefore, when the application outputs Ready to dump GCOV data..., users should execute the esp32 gcov dump OpenOCD command. The example should output the following:

Counter = 0
Ready to dump GCOV data...
GCOV data have been dumped.
Counter = 1
Ready to dump GCOV data...
GCOV data have been dumped.

2. Instant Run-Time Dump

After the two hard-coded dumps, the example will continue looping through it's main blink function. Users can call esp32 gcov OpenOCD command to trigger an instant run-time dump. The output should resemble the following:

Counter = 2
Counter = 3
Counter = 4
Counter = 5
Counter = 6
Counter = 7
Counter = 8
Counter = 9
Counter = 10
...

Generating Lcov Report

After dumping one or more times, a coverage report can be generated by calling cmake --build build/ --target lcov-report. This should result in an HTML code coverage report being generated in the build directory.

To clean Gcov and report related data from the build directory, call cmake --build build/ --target cov-data-clean

Note: Currently, the CMake build system on Windows does not support Lcov. However, Lcov is available in MINGW (installed through package manager). Therefore, if the project is built using the legacy GNU Make build system, call make lcov-report or make cov-data-clean instead.

The following log should be output when generating the coverage report:

Generating coverage report in: /home/alexey/projects/esp/esp-idf/examples/system/gcov/build/coverage_report
Using gcov: ~/projects/esp/crosstool-NG/builds/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcov
Capturing coverage data from /home/alexey/projects/esp/esp-idf/examples/system/gcov/build
Found gcov version: 5.2.0
Scanning /home/alexey/projects/esp/esp-idf/examples/system/gcov/build for .gcda files ...
Found 2 data files in /home/alexey/projects/esp/esp-idf/examples/system/gcov/build
Processing main/gcov_example_func.gcda
Processing main/gcov_example.gcda
Finished .info-file creation
Reading data file /home/alexey/projects/esp/esp-idf/examples/system/gcov/build/coverage_report/gcov_example.info
Found 2 entries.
Found common filename prefix "/home/alexey/projects/esp/esp-idf/examples/system/gcov"
Writing .css and .png files.
Generating output.
Processing file main/gcov_example.c
Processing file main/gcov_example_func.c
Writing directory view page.
Overall coverage rate:
  lines......: 90.0% (18 of 20 lines)
  functions..: 100.0% (3 of 3 functions)

Troubleshooting

OpenOCD Out of Sync

If the following log is output when issuing an OpenOCD command via telnet, it could indicate that OpenOCD and the ESP32 are out of sync. This occurs when the ESP32 is externally reset whilst connected to OpenOCD (e.g., by pressing the EN button).

Open On-Chip Debugger
> esp32 gcov dump
Target halted. PRO_CPU: PC=0x4008AFF4 (active)    APP_CPU: PC=0x400E396E
Total trace memory: 16384 bytes
Connect targets...
Target halted. PRO_CPU: PC=0x400D5D74 (active)    APP_CPU: PC=0x400E396E
timed out while waiting for target halted / 1 - 2
Failed to wait halt on bp target (-4)!
Failed to halt targets (-4)!
Failed to connect to targets (-4)!

This issue can be resolved in the following ways:

• Reset the board by issuing the reset command via telnet
• Restart OpenOCD

Outdated Lcov

Due to lcov not being part of the GCC bundle, it is possible that the format of the GCOV binary data can change resulting in lcov failing to understand it. Therefore, it is always better to use the latest lcov version from the Lcov repo.