Debugging an application¶
VS Code comes with a built-in debugger to help troubleshoot problems. The main recommended tool for debugging with the nRF Connect SDK is our own nRF Debug debugging tool which uses Microsoft's debug adaptor.
To enable debugging, check Enable debug options when you are setting up a build configuration.
When you add a build configuration with this option checked, the following options are set:
CONFIG_DEBUG_OPTIMIZATIONS- This option limits the optimizations made by the compiler to only those that do not impact debugging.
CONFIG_DEBUG_THREAD_INFO- This option adds additional information to the thread object, so that the debugger can discover the threads. This will work for any debugger. Additional threads appear in the Call Stack View.
Enabling the debugging options will affect the application's memory usage.
If you forgot to enable debugging during the build configuration step, complete the following steps:
- Right-click the build configuration. The drop-down menu appears.
- Click Edit Build Configuration.
- On the Edit Build Configuration screen, check Enable debug options.
- Click Build Configuration. The build configuration is rebuilt with the debug options enabled.
The are two options listed in the Actions View for debugging with the extension:
Debug, which uses the recommended nRF Debug tool.
Debug with Ozonefor J-Link.
Ubuntu users with nRF Connect SDK 1.7.0 need to install the libcurses5 package for debugging to work properly. Run the following command:
sudo apt install libncurses5
To use debugging with nRF Debug:
- Click on Debug in the Actions View.
The debugging control bar appears at the top of the screen to let you control the debugging process.
Starts or continues the debugging process
Steps over a function
Steps into a function
Steps out of a function
Restarts the debugging process
Stops the debugging process
Click on the left side of any line of code to set or remove a breaking point.
See the the VS Code debugging documentation for additional information.
Change the default debugger¶
If you want to use Cortex-Debug, you can change the debugging settings in the Extension Settings. When the Cortex-Debug option is selected, the Debug button in the Actions View will use this to debug applications.
To enable Cortex-Debug:
Click on the Extensions icon from the Activity Bar.
Find the nRF Connect for VS Code and click on the Settings icon on the bottom right corner of the extension.
Click on Extension Settings.
Scroll down to Nrf-connect > Debugging: Backend.
In the dropdown menu, click on Cortex-Debug.
There are several debugging Views available in the Sidebar to help you examine the debugging process.
The following are Views found in the Sidebar while debugging.
The Variables View shows variables in the current scope and organizes them into local, global, and static sections.
The Watch View shows the output of variables you have selected to watch.
To start watching a variable:
- Click and drag the mouse cursor to highlight the variable in your code.
- Right-click and choose Add to Watch.
- Click the Start/Continue button in the debugging control bar to watch the debugger go through the code until it stops at a variable breakpoint. The output of the code displays in the Watch View.
The Call Stack lists all of the available threads and indicates which ones are running. It also includes the call stack for each individual thread that is running.
All breakpoints that you have set in the code are listed in the Breakpoints View.
The Peripherals View shows a memory map of peripherals from your device's SVD file and displays the values of their registers and fields.
The following are Panel Views found exclusively when debugging the nRF Debugger Panel View:
The Thread Viewer shows information about specific threads in your application. The threads are listed in rows by Address, in the order in which they were started. Hover your mouse over the items in the State or User Options column to reveal a tooltip that describes the indicated binary value.
The Memory Viewer shows the memory content on your device. You can review different Regions of memory data by clicking on the different buttons in the first row.
Check the following troubleshooting topics if you have problems with running the debugger.
Debugging does not work¶
There is a known issue where debugging may not work when you enable debug options when generating the build configuration. This seems to happen with simple sample applications, such as Blinky. Samples that use threads still seem to work with Enable debug options checked.
To work around this issue, generate the build configuration with Enable debug options unchecked. If this does not resolve the issue, instead of starting debugging by clicking the Debug Application icon, start debugging by using Run -> Start Debugging or by pressing F5.
Debugging times out¶
When attempting to debug a device that has readback protection enabled, the debugger may time out with no explanation. The solution is to recover the device, either by running the
nRF Connect: Recover Board command or by clicking the Recover icon in the Connected Devices View. Once the device has been reset, restart the debugger.