![]() |
||
---|---|---|
.. | ||
main | ||
CMakeLists.txt | ||
Makefile | ||
README.md | ||
sdkconfig.defaults |
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.
-
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.
-
After connecting JTAG interface, you need to Run OpenOCD.
-
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 choosingTrace 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.