alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
c4654298ce
esp-idf/examples/system/gcov/README.md

165 lines
7.3 KiB
Markdown
Raw Normal View History

examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
# Blink Example With Coverage Info (Gcov)
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
(See the README.md file in the upper level 'examples' directory for more information about examples.)
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
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](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#gcov-source-code-coverage) for more details on the code coverage features supported in ESP-IDF.
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
This example implements a simple blink application but with code coverage enabled. The example will demonstrate the following features:
gcov: Fixes libgcov and libapp_trace cross dependency linking issue Closes IDF-834
2019-10-01 13:42:32 -04:00
* How to compile a project with coverage info enabled.
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
* Various methods of dumping code coverage data (e.g. Instant Run-Time Dump and Hard-coded Dump).
* How to generate a code coverage report.
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
## How to use example
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
### Hardware Required
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
To run this example, you need an ESP32 dev board connected to a JTAG adapter, which can come in the following forms:
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
* [ESP-WROVER-KIT](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#esp-wrover-kit-v4-1) which integrates an on-board JTAG adapter. Ensure that the [required jumpers to enable JTAG are connected](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/get-started-wrover-kit.html#setup-options) 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).
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
This example will assume that that an ESP-WROVER-KIT is used.
cmake: Fix some failing example builds, fix gcov
2018-09-18 00:23:56 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
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](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html).
cmake: Fix some failing example builds, fix gcov
2018-09-18 00:23:56 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
2. After connecting JTAG interface, you need to [Run OpenOCD](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html#run-openocd).
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
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:
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
```bash
telnet localhost 4444
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
### Configure the project
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
idf.py menuconfig
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
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`
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
### Build, Flash, and Run
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
Build the project and flash it to the board, then run monitor tool to view serial output:
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
idf.py -p PORT flash monitor
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type ``Ctrl-]``.)
esp32: Adds GCOV debug stubs support Adds the following functionality - Debug stubs infrastructure - Stub for retrieveing GCOV data without user source code modification
2018-02-15 12:09:03 -05:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
## Example Output
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
### 1. Hard-coded Dump
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
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:
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
```
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
blink_dummy_func: Counter = 0
some_dummy_func: Counter = 0
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
Ready to dump GCOV data...
GCOV data have been dumped.
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
blink_dummy_func: Counter = 1
some_dummy_func: Counter = 2
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
Ready to dump GCOV data...
GCOV data have been dumped.
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
### 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:
gcov_example: Adds cmake target to generate report Closes IDF-727
2019-06-28 09:24:05 -04:00
```
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
blink_dummy_func: Counter = 2
some_dummy_func: Counter = 4
blink_dummy_func: Counter = 3
some_dummy_func: Counter = 6
blink_dummy_func: Counter = 4
some_dummy_func: Counter = 8
blink_dummy_func: Counter = 5
some_dummy_func: Counter = 10
blink_dummy_func: Counter = 6
some_dummy_func: Counter = 12
blink_dummy_func: Counter = 7
some_dummy_func: Counter = 14
blink_dummy_func: Counter = 8
some_dummy_func: Counter = 16
blink_dummy_func: Counter = 9
some_dummy_func: Counter = 18
blink_dummy_func: Counter = 10
some_dummy_func: Counter = 20
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
...
gcov_example: Adds cmake target to generate report Closes IDF-727
2019-06-28 09:24:05 -04:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
### 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.
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
To clean Gcov and report related data from the build directory, call `cmake --build build/ --target cov-data-clean`
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
**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.
gcov_example: Adds cmake target to generate report Closes IDF-727
2019-06-28 09:24:05 -04:00
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
The following log should be output when generating the coverage report:
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
```
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
[1/1] Generating coverage report in: /home/user/projects/esp/tmp_idf/esp-idf/examples/system/gcov/build/coverage_report
Using gcov: xtensa-esp32-elf-gcov
Capturing coverage data from /home/user/projects/esp/tmp_idf/esp-idf/examples/system/gcov/build
Found gcov version: 8.2.0
Using intermediate gcov format
Scanning /home/user/projects/esp/tmp_idf/esp-idf/examples/system/gcov/build for .gcda files ...
Found 3 data files in /home/user/projects/esp/tmp_idf/esp-idf/examples/system/gcov/build
Processing sample/CMakeFiles/__idf_sample.dir/some_funcs.c.gcda
Processing main/CMakeFiles/__idf_main.dir/gcov_example_func.c.gcda
Processing main/CMakeFiles/__idf_main.dir/gcov_example_main.c.gcda
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
Finished .info-file creation
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
Reading data file /home/user/projects/esp/tmp_idf/esp-idf/examples/system/gcov/build/coverage_report/gcov_example.info
Found 4 entries.
Found common filename prefix "/home/user/projects/esp/tmp_idf/esp-idf/examples/system/gcov"
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
Writing .css and .png files.
Generating output.
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
Processing file /home/user/projects/esp/tmp_idf/esp-idf/components/freertos/include/freertos/task.h
Processing file components/sample/some_funcs.c
Processing file main/gcov_example_main.c
esp32: Adds gcov over JTAG feature Implements function to dump GCOV data to host via JTAG. The following functionality was added: - Host file I/O - GCOV runtime I/O stubs - GCOV example
2017-08-16 19:36:00 -04:00
Processing file main/gcov_example_func.c
Writing directory view page.
Overall coverage rate:
examples: Collects coverage info in component
2019-10-01 06:16:43 -04:00
lines......: 100.0% (28 of 28 lines)
functions..: 100.0% (4 of 4 functions)
gcov: use GCC API to control GCOV data dumps
2018-06-28 09:38:17 -04:00
```
examples: Update system examples README The following commit updates the first half of the the system example README files. Some other changes were also made: * Updated base_mac_address example * Moved contents in GCOV README to GCOV docs * Some *main.c file names updated * Updated example README template
2019-06-25 14:41:19 -04:00
## 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](https://github.com/linux-test-project/lcov).
Reference in New Issue Copy Permalink