You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This tutorial consists of 2 parts: debugging a NuttX target with GDB and OpenOCD and debugging with Visual Studio Code. The first one describes tools installation and debugging via command line. The second focuses on the description of debugging using the modern IDE.
8
+
9
+
## Debugging a NuttX target with GDB and OpenOCD
10
+
7
11
Rare is the program that works on the first try -- so you will usually need a debugger. This is even more true on an embedded device, where "printf"-style debugging is very cumbersome.
8
12
9
13
There are many tools for embedded debugging. This tutorial will show you how to debug on the command line, using the [GNU Debugger gdb](https://www.gnu.org/software/gdb/) and the [Open On-Chip Debugger, OpenOCD](http://openocd.org/). These two open source tools are readily available on Linux, and they form the basis for many more advanced tools, including graphical debuggers.
10
14
11
15
NuttX integration for OpenOCD is relatively new as of the time of writing (early 2019), so this tutorial also includes instructions on how to get and configure it.
12
16
13
-
## Pre-Requisites
17
+
###Pre-Requisites
14
18
15
-
### Hardware
19
+
####Hardware
16
20
17
21
* a [supported embedded board](/docs/overview/hardware#evaluation-boards)
18
22
* a [support debugger probe](/docs/overview/hardware#development-tools)
19
23
20
-
### Software
24
+
####Software
21
25
22
26
* a NuttX development setup, including gdb
23
27
* OpenOCD-Nuttx (but we will show to install that)
24
28
25
29
26
-
## Install OpenOCD-Nuttx
30
+
###Install OpenOCD-Nuttx
27
31
28
32
Sony has added NuttX support to OpenOCD, and most importantly, this includes thread info. Since NuttX is a real RTOS with support multiple tasks/threads, you need thread support to look at anything other than the currently active task.
29
33
30
-
### Get the code
34
+
####Get the code
31
35
32
36
The repository is on GitHub at [https://github.com/sony/openocd-nuttx](https://github.com/sony/openocd-nuttx). Check it out like this:
NuttX sometimes switches around the memory location of the necessary information, so we need to configure OpenOCD for the currently used NuttX version.
43
47
@@ -65,15 +69,15 @@ Now open `openocd-nuttx/src/nuttx_header.h` in your favor editor, locate the exi
65
69
and replace them with what you got. The result should be like this:
66
70
67
71
68
-
### Configure OpenOCD for NuttX support
72
+
####Configure OpenOCD for NuttX support
69
73
70
74
OpenOCD has a set of target configurations for the various boards. Since the boards could run one of many RTOS's, the default configuration doesn't specify any particular one -- so we have to add it.
71
75
72
76
When using the Olimex STM32-E407 board, one of our standard boards, the target configuration file is `stm32f4x.cfg` and it is normally located in `tcl/target/`. For your hardware, it might be a different file, so be sure to use the right one.
73
77
74
78
Open the target configuration and locate a line starting with `$_TARGETNAME configure`. Then add `-rtos nuttx` to this line.
75
79
76
-
### Compile OpenOCD
80
+
####Compile OpenOCD
77
81
78
82
**NOTE** The Sony OpenOCD branch has some compile issues on Ubuntu 18.04 right now, because it uses a newer compiler. The easiest "solution" is to remove the `-Werror` from your compile. We'll submit a patch soon.
79
83
@@ -85,7 +89,7 @@ make
85
89
sudo make install
86
90
```
87
91
88
-
### Test OpenOCD
92
+
####Test OpenOCD
89
93
90
94
To test OpenOCD, try the following command line:
91
95
```bash
@@ -97,7 +101,7 @@ The output should look as in the following image:
97
101
98
102
OpenOCD will then block, waiting for a debugger to attach, so lets do that in the next section.
99
103
100
-
## Running GDB with OpenOCD
104
+
###Running GDB with OpenOCD
101
105
102
106
Run gdb in your NuttX directory as follows:
103
107
```bash
@@ -109,7 +113,7 @@ This connected to the gdb server running on port 3333 (OpenOCD default) of the s
109
113
110
114
At this moment we have not defined any breakpoints, yet, so you can just press `Ctrl-C` to interrupt the running program again. This will interrupt it after NuttX had a chance to do initialization, so we will actually get to see some data.
111
115
112
-
### Inspect the program
116
+
####Inspect the program
113
117
114
118
Now, if everything worked correctly, we should get some information from the RTOS, such as thread info. To test, type `info threads` at the gdb prompt to get a thread info table. Your output will very depending on the NuttX configuration. On my bare-bones NSH-only configuration, it looks as follows:
115
119
@@ -128,7 +132,7 @@ This switches to thread 2 and then inspects the local variables, of which there
128
132
In my case, this is the NSH thread which is waiting for some input.
129
133
130
134
131
-
## Conclusion
135
+
###Conclusion
132
136
133
137
This concludes this basic tutorial on getting gdb to run with OpenOCD and NuttX support.
134
138
@@ -138,3 +142,98 @@ for the reader ;-)
138
142
139
143
There are also IDEs with microcontroller support -- stay tuned for another tutorial with more
140
144
details on that.
145
+
146
+
147
+
## Debugging with Visual Studio Code
148
+
149
+
This is a follow-up to the [tutorial above](#debugging-a-nuttx-target-with-gdb-and-openocd), because the set up done in that tutorial is a pre-requisite to debugging with Visual Studio Code.
150
+
151
+
### Motivation
152
+
153
+
Visual Studio Code is a modern IDE that is very easy to extend and popular with both the Web/Cloud and IoT communities. It is also one of the easiest IDEs to get working with embedded systems. That said, it is *not* the most powerful or featureful IDEs for this purpose, but it is easy and will do.
154
+
155
+
### Prerequisites
156
+
157
+
* All the prerequisites of [Debugging a NuttX target with GDB and OpenOCD](#debugging-a-nuttx-target-with-gdb-and-openocd)
158
+
* Cortex-M hardware (all of our standard boards are ARM based)
159
+
*[Visual Studio Code](https://code.visualstudio.com/)
160
+
161
+
162
+
### Installing Cortex-Debug
163
+
164
+
In the extensions marketplace, enter "cortex", then install "Cortex-Debug". Depending on your version of Visual Studio Code, you may need to restart after installing the extension.
165
+
166
+
### Set up your project for debugging
167
+
168
+
Open your project folder in Visual Studio Code -- this is usually the `NuttX` folder, or a subdirectory of `apps`.
169
+
170
+
#### Create a Visual Studio Code launch configuration for NuttX
171
+
172
+
From the `Debug` menu, select `Open Configurations`. This will open a `launch.json' file. See [Cortex-Debug Launch configurations](https://marcelball.ca/projects/cortex-debug/cortex-debug-launch-configurations/) for documentation.
173
+
174
+
To get started, I have prepared a working launch configuration for using our STM32-E407 board with the ARM-USB-OCD-H jtag probe. If you use a different board or probe, you only need to replace the `configFiles` section. Each entry in the section is an argument that you would normally pass as a `-f` option to OpenOCD.
175
+
```json
176
+
{
177
+
"version": "0.2.0",
178
+
"configurations": [
179
+
{
180
+
"name": "Debug (OpenOCD/NuttX)",
181
+
"cwd": "${workspaceRoot}",
182
+
"executable": "nuttx",
183
+
"request": "launch",
184
+
"type": "cortex-debug",
185
+
"servertype": "openocd",
186
+
"device": "stm32f4x",
187
+
"configFiles": [
188
+
"interface/ftdi/olimex-arm-usb-ocd-h.cfg",
189
+
"target/stm32f4x.cfg"
190
+
]
191
+
}
192
+
]
193
+
}
194
+
```
195
+
The `name` is what will appear in the status bar for running it.
196
+
197
+
#### Running the debugger
198
+
199
+
Either press `F5` or select `Debug/Start Debugging` from the menu to get started. This will take a moment, and then you should get a red status bar and the debug window, like in the following image:
200
+
201
+
202
+
As in the gdb tutorial, initially you won't see much because the program is stopped during OS initialization. Press `F5` again or click the "play" button from the debug menu at the top of the window, wait a few seconds, then press `F6` or click the pause button. The window should change to give you thread, variable, and register information, like in the following. Note that "Call Stack" window displays multiple threads.
203
+
204
+
205
+
206
+
#### Adding an SVD File
207
+
208
+
You may have noticed that on the left-hand side, there is a sub-window called "Cortex Peripherals" which simply states "No SVD File loaded". SVD means "System View Description" and is a standard format which microcontroller vendors use to describe the available features of their MCUs.
209
+
210
+
For example, in the case of our STM32-E407 board, which features an STM32F407ZGT6 MCU, we can download the SVD description from [STM's web-page for the STM32F407ZG series](https://www.st.com/en/microcontrollers-microprocessors/stm32f407zg.html). In the "HW Model, CAD Libraries & SVD", you will find a link to the [STM32F4 series SVD](https://www.st.com/resource/en/svd/stm32f4_svd.zip).
211
+
212
+
Extract the SVD and then add an `svdFile` attribute to the launch configuration. The full configuration will look like this:
213
+
214
+
```json
215
+
{
216
+
"version": "0.2.0",
217
+
"configurations": [
218
+
{
219
+
"name": "Debug (OpenOCD/SVD)",
220
+
"cwd": "${workspaceRoot}",
221
+
"executable": "nuttx",
222
+
"request": "launch",
223
+
"type": "cortex-debug",
224
+
"servertype": "openocd",
225
+
"device": "stm32f4x",
226
+
"svdFile": "STM32F407.svd",
227
+
"configFiles": [
228
+
"interface/ftdi/olimex-arm-usb-ocd-h.cfg",
229
+
"target/stm32f4x.cfg"
230
+
]
231
+
}
232
+
]
233
+
}
234
+
```
235
+
236
+
Run the debugger again, and your window should look as follows:
237
+
238
+
239
+
Voilà! The `Cortex Peripherals` is populated with everything that the STM32F407 MCU has to offer. Please note that not all of these peripherals might actually be connected on the board. However, those that are, and that are used in your application, can easily be investigated like this.
0 commit comments