Chapter 4. API Guides
1. Compile the source code using GCC with the --coverage option enabled. This will cause the compiler to
generate a .gcno notes files during compilation. The notes files contain information to reconstruct execution
path block graphs and map each block to source code line numbers. Each source file compiled with the -
-coverage option should have their own .gcno file of the same name (e.g., a main.c will generate a
main.gcno when compiled).
2. Execute the program. During execution, the program should generate .gcda data files. These data files
contain the counts of the number of times an execution path was taken. The program will generate a .gcda
file for each source file compiled with the --coverage option (e.g., main.c will generate a main.gcda.
3. Gcov or Gcovr can be used generate a code coverage based on the .gcno, .gcda, and source files. Gcov
will generate a text based coverage report for each source file in the form of a .gcov file, whilst Gcovr will
generate a coverage report in HTML format.
Gcov and Gcovr in ESP-IDF Using Gcov in ESP-IDF is complicated by the fact that the program is running
remotely from the Host (i.e., on the target). The code coverage data (i.e., the .gcda files) is initially stored on the
target itself. OpenOCD is then used to dump the code coverage data from the target to the host via JTAG during
runtime. Using Gcov in ESP-IDF can be split into the following steps.
1. Setting Up a Project for Gcov
2. Dumping Code Coverage Data
3. Generating Coverage Report
Setting Up a Project for Gcov
Compiler Option In order to obtain code coverage data in a project, one or more source files within the project
must be compiled with the --coverage option. In ESP-IDF, this can be achieved at the component level or the
individual source file level:
To cause all source files in a component to be compiled with the --coverage option.
• Add target_compile_options(${COMPONENT_LIB} PRIVATE --coverage) to the
CMakeLists.txt file of the component if using CMake.
• Add CFLAGS += --coverage to the component.mk file of the component if using Make.
To cause a select number of source files (e.g. sourec1.c and source2.c) in the same component to be compiled with the --coverage option.
• Add set_source_files_properties(source1.c source2.c PROPERTIES COM-
PILE_FLAGS --coverage) to the CMakeLists.txt file of the component if using CMake.
• Add source1.o: CFLAGS += --coverage and source2.o: CFLAGS += --coverage
to the component.mk file of the component if using Make.
When a source file is compiled with the --coverage option (e.g. gcov_example.c), the compiler will generate
the gcov_example.gcno file in the project’s build directory.
Project Configuration Before building a project with source code coverage, ensure that the following project
configuration options are enabled by running idf.py menuconfig (or make menuconfig if using the legacy
Make build system).
• Enable the application tracing module by choosing Trace Memory for the CON-
FIG_APPTRACE_DESTINATION option.
• Enable Gcov to host via the CONFIG_APPTRACE_GCOV_ENABLE
Dumping Code Coverage Data Once a project has been complied with the --coverage option and flashed
onto the target, code coverage data will be stored internally on the target (i.e., in trace memory) whilst the application
runs. The process of transferring code coverage data from the target to the Host is know as dumping.
The dumping of coverage data is done via OpenOCD (see JTAG Debugging on how to setup and run OpenOCD). A
dump is triggered by issuing commands to OpenOCD, therefore a telnet session to OpenOCD must be opened to issue
such commands (run telnet localhost 4444). Note that GDB could be used instead of telnet to issue com-
mands to OpenOCD, however all commands issued from GDB will need to be prefixed as mon <oocd_command>.
Espressif Systems 1261
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General