\nImplementation<\/a>
\nCode Coverage Reports<\/a>
\nLive Coverage<\/a>
\nDifferential Coverage<\/a>
\nCMake\u00a0 Projects<\/a>
\nMSBuild Projects<\/a>
\nGNU Make Projects<\/a>
\nNordic nRF5x Devices<\/a>
\nLimitations<\/a><\/p>\n
<\/a>Overview<\/h1>\nEmbedded Code Coverage allows viewing the paths of the code that were executed during a debug session. E.g. the example below shows how the code managed to successfully initialize and start the USB device, but the VCP_read()<\/strong> function never returned 1 and the subsequent VCP_write()<\/strong> calls were never executed: ![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/intro-1.png\")
<\/a>Code coverage is typically used in unit tests to see what code paths were covered by the test, however for embedded projects it has two additional uses:<\/p>\n\n- Observing what parts of the program are running right now without stopping it in the debugger (Live Coverage<\/a>)<\/li>\n
- Quickly checking the path taken by a long function, or an interrupt handler without stepping through it (Differential coverage<\/a>)<\/li>\n<\/ul>\n
Code Coverage is supported by VisualGDB Custom Edition or higher and can be enabled via the Code Coverage page of VisualGDB Project Properties:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/settings-1.png\")
<\/a>Note that code coverage reports (1)<\/strong> can be enabled separately from Live Coverage (2)<\/strong>.<\/p>\nWARNING<\/strong><\/span>: After you enable code coverage via VisualGDB Project Properties, the project settings will be changed to instrument the code for coverage. Disabling code coverage here will keep the instrumentation enabled. See the project-specific sections of CMake<\/a>, MSBuild<\/a> or GNU Make<\/a> for details on disabling it.<\/p>\nEmbedded Code Coverage is supported by CMake, MSBuild and GNU Make-based projects, as well as mbed projects. It is only supported when using the GCC compiler (not Keil or IAR) and it is not supported for ESP-IDF projects, Arduino projects or other projects where VisualGDB does not fully control the build process.<\/p>\n
<\/a>Implementation<\/h1>\nThe code coverage for Embedded projects does not require any tracing hardware (live tracing with Segger J-Trace<\/a> works separately from Live Coverage). It works by instrumenting the code to keep track of every taken branch, resulting in performance overhead and a considerable memory overhead. You can assess the overhead by comparing the instrumented and non-instrumented build of your project in Embedded Memory Explorer<\/a>:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/memexp.png\")
<\/a>You can reduce the overhead by limiting the instrumentation to a select set of files. See the project-specific sections of CMake<\/a>, MSBuild<\/a> or GNU Make<\/a> for details.<\/p>\nLive Coverage is implemented by continuously reading the branch counters while the program is running, so it requires the target to support background memory reads. Most ARM Cortex devices and RISC-V devices support this functionality.<\/p>\n
<\/a>Code Coverage Reports<\/h1>\nYou can enable the generation of code coverage reports via VisualGDB Project Properties -> Code Coverage<\/strong>:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/reports.png\")
<\/a>If the report generation is enabled, each time a debug session is ended, VisualGDB will save the code coverage results in a .scovreport<\/strong> file in the specified directory. Normally, VisualGDB will only keep the 5 most recent coverage reports for each projects, deleting the older ones automatically. You can change this setting via Tools->Options->VisualGDB->General->Profiling->Max. coverage reports per project<\/span><\/strong>.<\/p>\nYou can also configure VisualGDB to keep the original .gcda<\/strong> files produced by GCOV via the Tools->Options->VisualGDB->General->Profiling->Keep raw coverage reports<\/span><\/strong> setting.<\/p>\nCoverage reports can be viewed via Test->VisualGDB Code Coverage Reports<\/strong>:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/report2.png\")
<\/a>Below is the summary of the controls in the Code Coverage window:<\/p>\n\n- Normally, the code coverage window will show the report for the last debugged project. If the solution contains multiple projects, you can select a specific one via the project selector (1)<\/strong>.<\/li>\n
- You can switch between the recent coverage reports via the report selector (2)<\/strong>.<\/li>\n
- You can delete old reports via the ‘delete’ button in the drop-down list (3)<\/strong>. VisualGDB will also delete the old reports automatically according to the Tools->Options->VisualGDB->General->Profiling->Max. coverage reports per project<\/span><\/strong> setting.<\/li>\n
- The refresh button (4)<\/strong> allows updating the list of reports for a project, in case one was produced outside Visual Studio.<\/li>\n
- The coverage highlight button (5)<\/strong> enables highlighting of source code lines based on whether they were covered or not. This only works when using Clang IntelliSense.<\/li>\n
- System Symbol Filter (6) <\/strong>allows hiding irrelevant symbols from system directories. You can right-click on any symbol in the Code Coverage window to mark its location as a system directory, and hide any other symbols from that directory as well. System directories are stored in the SystemDirectoryPrefixes<\/strong> element inside the .vgdbsettings<\/strong> file.<\/li>\n
- You can sort the functions in the Code Coverage view by name, declaring file, number of invocations and coverage by clicking on the corresponding headers in the list view (7)<\/strong>.<\/li>\n<\/ul>\n
You can read the coverage reports programmatically by referencing the VisualGDBCore.dll<\/strong> assembly from the VisualGDB directory and using the CoverageReportReader<\/strong> class. See this file<\/a> for a brief example of reading .scovreport<\/strong> files.<\/p>\n<\/a>Live Coverage<\/h1>\nLive Coverage can display the branches of code taken in real time. It can be enabled via VisualGDB Project Properties -> Code Coverage<\/strong> and works independently from the coverage reports:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/live.png\")
<\/a>Enabling Live Coverage also enables the Differential Coverage (Recent Lines).<\/p>\nOnce Live Coverage is enabled, you can view it via the Debug->Windows->Live Tracing\/Coverage<\/strong> command while the project is running:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/live2.png\")
<\/a>Below is the summary of the Live Coverage controls:<\/p>\n\n- The View switch allows selecting the Live Coverage view (1)<\/strong>, differential coverage (Recent Lines) and Statistics view.<\/li>\n
- The Highlight Mode switch allows either showing whether a particular line is covered (2)<\/strong>, or showing how recent a line was executed (3).<\/strong><\/li>\n
- If continuously sampling the branch counters interferes with other debugging functionality (e.g. makes Live Watch slower), you can suspend it using the suspend button (4)<\/strong>.<\/li>\n
- You can sort the contents of the Live Coverage window by function name, number of runs, or the last time it ran by clicking on the corresponding headers (5)<\/strong>.<\/li>\n<\/ul>\n
Highlighting the recently executed lines allows observing the code running in real time without actually stopping it in the debugger. The functions executed within the specified interval will be shown with a more intense color:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/recent.png\")
<\/a><\/p>\n<\/a>Differential Coverage<\/h1>\nDifferential Coverage is a special type of Live Coverage. It works by comparing the coverage snapshots before and after a step (or between 2 breakpoints):![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/differential.png\")
<\/a>It is enabled by switching the Live Coverage view to Recent Lines (1)<\/strong> and either stepping over a function call, or resuming and waiting for another breakpoint to hit. VisualGDB will then display all lines that changed their run counts since the last event. You can further group them by symbol or file (2)<\/strong>.<\/p>\nDifferential coverage is useful if stepping through a large failing function is impractical (e.g. due to high stepping latency) and gives a good overview of what happened since the last debug event.<\/p>\n
<\/a>Instrumentation – CMake Projects<\/h1>\nCMake projects offer the best GUI for controlling which files should be instrumented for live coverage.<\/p>\n
In order to instrument a project for coverage, you first need to enable the instrumentation of the corresponding BSP (1)<\/strong> by opening its properties on the Code Coverage page (2)<\/strong>.![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/cmake1.png\")
<\/a>Once the instrumentation is enabled, VisualGDB will show the “coverage” overlay on top of the file icon for the instrumented files (3)<\/strong>. Non-instrumented files will retain the regular icon (4)<\/strong>. You can enable or disable coverage for individual files or frameworks via a context menu in Solution Explorer (5)<\/strong>.<\/p>\nChanging any of the instrumentation settings will insert\/update the bsp_configure_code_coverage()<\/strong><\/a> statement in your CMakeLists.txt. E.g.:<\/p>\nbsp_configure_code_coverage(ENABLED 1\r\n EXCLUDE_TARGETS BSP_com.sysprogs.arm.stm32.hal\r\n EXCLUDE_FILES ${BSP_ROOT}\/STM32F4xxxx\/STM32_USB_Device_Library\/Core\/Src\/usbd_ctlreq.c)<\/pre>\nWARNING<\/strong><\/span>: <\/strong>Enabling code coverage via VisualGDB Project Properties will automatically enable code instrumentation, however disabling it will keep the code instrumentation settings unchanged. In order to disable instrumentation, simply\u00a0 comment out the bsp_configure_code_coverage()<\/strong> statement in CMakeLists.txt.<\/p>\nIf you would like to quickly switch between instrumented and non-instrumented variants of the project, consider using the if()<\/strong> statement together with the configuration\/platform GUI<\/a> to create special configurations or platforms for instrumenting the code for code coverage.<\/p>\n<\/a>Instrumentation – MSBuild Projects<\/h1>\nMSBuild projects rely on the regular Visual Studio property system, so controlling the instrumentation is slightly less straight-forward than for CMake projects. First of all, the instrumentation always<\/strong> needs to be enabled for the project globally via Configuration properties -> Embedded Project -> Instrument Code for Code Coverage<\/strong>:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/msbuild1.png\")
<\/a>Note that this setting is stored separately for each configuration\/platform. Always double-check that the edited configuration platform matches the one you intend to edit, as Visual Studio sometimes displays settings for an unexpected configuration.<\/p>\nOnce you have enabled the instrumentation globally, it will be automatically enabled on the compiler level (C\/C++ -> Instrumentation -> Generate Code Coverage Reports<\/strong>):![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/msbuild2.png\")
<\/a>Normally, you do not need to change the setting under C\/C++->Instrumentation<\/strong>, as its default value depends on the global setting. However, you can explicitly set it No<\/strong> for individual files that you do not wish to be instrumented (select these files in Solution Explorer and open Properties in context menu to edit file-specific properties).<\/p>\nThe table below summarizes the relation between the 2 settings:<\/p>\n
<\/a>Code coverage is typically used in unit tests to see what code paths were covered by the test, however for embedded projects it has two additional uses:<\/p>\n- \n
- Observing what parts of the program are running right now without stopping it in the debugger (Live Coverage<\/a>)<\/li>\n
- Quickly checking the path taken by a long function, or an interrupt handler without stepping through it (Differential coverage<\/a>)<\/li>\n<\/ul>\n
Code Coverage is supported by VisualGDB Custom Edition or higher and can be enabled via the Code Coverage page of VisualGDB Project Properties:
<\/a>Note that code coverage reports (1)<\/strong> can be enabled separately from Live Coverage (2)<\/strong>.<\/p>\nWARNING<\/strong><\/span>: After you enable code coverage via VisualGDB Project Properties, the project settings will be changed to instrument the code for coverage. Disabling code coverage here will keep the instrumentation enabled. See the project-specific sections of CMake<\/a>, MSBuild<\/a> or GNU Make<\/a> for details on disabling it.<\/p>\n
Embedded Code Coverage is supported by CMake, MSBuild and GNU Make-based projects, as well as mbed projects. It is only supported when using the GCC compiler (not Keil or IAR) and it is not supported for ESP-IDF projects, Arduino projects or other projects where VisualGDB does not fully control the build process.<\/p>\n
<\/a>Implementation<\/h1>\n
The code coverage for Embedded projects does not require any tracing hardware (live tracing with Segger J-Trace<\/a> works separately from Live Coverage). It works by instrumenting the code to keep track of every taken branch, resulting in performance overhead and a considerable memory overhead. You can assess the overhead by comparing the instrumented and non-instrumented build of your project in Embedded Memory Explorer<\/a>:
<\/a>You can reduce the overhead by limiting the instrumentation to a select set of files. See the project-specific sections of CMake<\/a>, MSBuild<\/a> or GNU Make<\/a> for details.<\/p>\nLive Coverage is implemented by continuously reading the branch counters while the program is running, so it requires the target to support background memory reads. Most ARM Cortex devices and RISC-V devices support this functionality.<\/p>\n
<\/a>Code Coverage Reports<\/h1>\n
You can enable the generation of code coverage reports via VisualGDB Project Properties -> Code Coverage<\/strong>:
<\/a>If the report generation is enabled, each time a debug session is ended, VisualGDB will save the code coverage results in a .scovreport<\/strong> file in the specified directory. Normally, VisualGDB will only keep the 5 most recent coverage reports for each projects, deleting the older ones automatically. You can change this setting via Tools->Options->VisualGDB->General->Profiling->Max. coverage reports per project<\/span><\/strong>.<\/p>\nYou can also configure VisualGDB to keep the original .gcda<\/strong> files produced by GCOV via the Tools->Options->VisualGDB->General->Profiling->Keep raw coverage reports<\/span><\/strong> setting.<\/p>\n
Coverage reports can be viewed via Test->VisualGDB Code Coverage Reports<\/strong>:
<\/a>Below is the summary of the controls in the Code Coverage window:<\/p>\n- \n
- Normally, the code coverage window will show the report for the last debugged project. If the solution contains multiple projects, you can select a specific one via the project selector (1)<\/strong>.<\/li>\n
- You can switch between the recent coverage reports via the report selector (2)<\/strong>.<\/li>\n
- You can delete old reports via the ‘delete’ button in the drop-down list (3)<\/strong>. VisualGDB will also delete the old reports automatically according to the Tools->Options->VisualGDB->General->Profiling->Max. coverage reports per project<\/span><\/strong> setting.<\/li>\n
- The refresh button (4)<\/strong> allows updating the list of reports for a project, in case one was produced outside Visual Studio.<\/li>\n
- The coverage highlight button (5)<\/strong> enables highlighting of source code lines based on whether they were covered or not. This only works when using Clang IntelliSense.<\/li>\n
- System Symbol Filter (6) <\/strong>allows hiding irrelevant symbols from system directories. You can right-click on any symbol in the Code Coverage window to mark its location as a system directory, and hide any other symbols from that directory as well. System directories are stored in the SystemDirectoryPrefixes<\/strong> element inside the .vgdbsettings<\/strong> file.<\/li>\n
- You can sort the functions in the Code Coverage view by name, declaring file, number of invocations and coverage by clicking on the corresponding headers in the list view (7)<\/strong>.<\/li>\n<\/ul>\n
You can read the coverage reports programmatically by referencing the VisualGDBCore.dll<\/strong> assembly from the VisualGDB directory and using the CoverageReportReader<\/strong> class. See this file<\/a> for a brief example of reading .scovreport<\/strong> files.<\/p>\n
<\/a>Live Coverage<\/h1>\n
Live Coverage can display the branches of code taken in real time. It can be enabled via VisualGDB Project Properties -> Code Coverage<\/strong> and works independently from the coverage reports:
<\/a>Enabling Live Coverage also enables the Differential Coverage (Recent Lines).<\/p>\nOnce Live Coverage is enabled, you can view it via the Debug->Windows->Live Tracing\/Coverage<\/strong> command while the project is running:
<\/a>Below is the summary of the Live Coverage controls:<\/p>\n- \n
- The View switch allows selecting the Live Coverage view (1)<\/strong>, differential coverage (Recent Lines) and Statistics view.<\/li>\n
- The Highlight Mode switch allows either showing whether a particular line is covered (2)<\/strong>, or showing how recent a line was executed (3).<\/strong><\/li>\n
- If continuously sampling the branch counters interferes with other debugging functionality (e.g. makes Live Watch slower), you can suspend it using the suspend button (4)<\/strong>.<\/li>\n
- You can sort the contents of the Live Coverage window by function name, number of runs, or the last time it ran by clicking on the corresponding headers (5)<\/strong>.<\/li>\n<\/ul>\n
Highlighting the recently executed lines allows observing the code running in real time without actually stopping it in the debugger. The functions executed within the specified interval will be shown with a more intense color:
<\/a><\/p>\n<\/a>Differential Coverage<\/h1>\n
Differential Coverage is a special type of Live Coverage. It works by comparing the coverage snapshots before and after a step (or between 2 breakpoints):
<\/a>It is enabled by switching the Live Coverage view to Recent Lines (1)<\/strong> and either stepping over a function call, or resuming and waiting for another breakpoint to hit. VisualGDB will then display all lines that changed their run counts since the last event. You can further group them by symbol or file (2)<\/strong>.<\/p>\nDifferential coverage is useful if stepping through a large failing function is impractical (e.g. due to high stepping latency) and gives a good overview of what happened since the last debug event.<\/p>\n
<\/a>Instrumentation – CMake Projects<\/h1>\n
CMake projects offer the best GUI for controlling which files should be instrumented for live coverage.<\/p>\n
In order to instrument a project for coverage, you first need to enable the instrumentation of the corresponding BSP (1)<\/strong> by opening its properties on the Code Coverage page (2)<\/strong>.
<\/a>Once the instrumentation is enabled, VisualGDB will show the “coverage” overlay on top of the file icon for the instrumented files (3)<\/strong>. Non-instrumented files will retain the regular icon (4)<\/strong>. You can enable or disable coverage for individual files or frameworks via a context menu in Solution Explorer (5)<\/strong>.<\/p>\nChanging any of the instrumentation settings will insert\/update the bsp_configure_code_coverage()<\/strong><\/a> statement in your CMakeLists.txt. E.g.:<\/p>\n
bsp_configure_code_coverage(ENABLED 1\r\n EXCLUDE_TARGETS BSP_com.sysprogs.arm.stm32.hal\r\n EXCLUDE_FILES ${BSP_ROOT}\/STM32F4xxxx\/STM32_USB_Device_Library\/Core\/Src\/usbd_ctlreq.c)<\/pre>\nWARNING<\/strong><\/span>: <\/strong>Enabling code coverage via VisualGDB Project Properties will automatically enable code instrumentation, however disabling it will keep the code instrumentation settings unchanged. In order to disable instrumentation, simply\u00a0 comment out the bsp_configure_code_coverage()<\/strong> statement in CMakeLists.txt.<\/p>\n
If you would like to quickly switch between instrumented and non-instrumented variants of the project, consider using the if()<\/strong> statement together with the configuration\/platform GUI<\/a> to create special configurations or platforms for instrumenting the code for code coverage.<\/p>\n
<\/a>Instrumentation – MSBuild Projects<\/h1>\n
MSBuild projects rely on the regular Visual Studio property system, so controlling the instrumentation is slightly less straight-forward than for CMake projects. First of all, the instrumentation always<\/strong> needs to be enabled for the project globally via Configuration properties -> Embedded Project -> Instrument Code for Code Coverage<\/strong>:
<\/a>Note that this setting is stored separately for each configuration\/platform. Always double-check that the edited configuration platform matches the one you intend to edit, as Visual Studio sometimes displays settings for an unexpected configuration.<\/p>\nOnce you have enabled the instrumentation globally, it will be automatically enabled on the compiler level (C\/C++ -> Instrumentation -> Generate Code Coverage Reports<\/strong>):
<\/a>Normally, you do not need to change the setting under C\/C++->Instrumentation<\/strong>, as its default value depends on the global setting. However, you can explicitly set it No<\/strong> for individual files that you do not wish to be instrumented (select these files in Solution Explorer and open Properties in context menu to edit file-specific properties).<\/p>\nThe table below summarizes the relation between the 2 settings:<\/p>\n
- The Highlight Mode switch allows either showing whether a particular line is covered (2)<\/strong>, or showing how recent a line was executed (3).<\/strong><\/li>\n
- You can switch between the recent coverage reports via the report selector (2)<\/strong>.<\/li>\n
- Quickly checking the path taken by a long function, or an interrupt handler without stepping through it (Differential coverage<\/a>)<\/li>\n<\/ul>\n
![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/make1.png\")
<\/a>The configuration-specific Makefile (e.g. debug.mak<\/strong>) should also set the DETACH_CODE_COVERAGE<\/strong> variable to 1, e.g.:<\/p>\n![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/nrf1.png\")
<\/a>Although the call stack in this case is not very informative, checking the information about the covered lines just before the crash quickly allows pinpoint the root cause:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/nrf2.png\")
<\/a>The problem is caused by instrumenting the syscall wrappers generated by the SVCALL()<\/strong> macro. In order to get coverage working, you would need to disable instrumentation for all files using the SVCALL()<\/strong> macro. Use the Find All References<\/strong> command (Shift+F12) to obtain a specific list of files:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/nrf3.png\")
<\/a>As of SDK v17.0<\/strong>, these files are located under the softdevice<\/strong> directory, so the easiest way to exclude them is to add “softdevice.*\\.h<\/strong>” to the “Skip instrumenting functions in files” setting:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/nrf4.png\")
<\/a>Now you can rebuild the project and confirm that it’s successfully running the idle loop by highlighting the recently executed lines:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/nrf5.png\")
<\/a><\/p>\n![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2021\/07\/limit-2.png\")
<\/a><\/p>\n