Skip to content

Commit 2b24abb

Browse files
jreineckearmjreineckearm
authored
Merge branch 'main' into cbuild-run-reader
2 parents ae70dd6 + ae8da45 commit 2b24abb

33 files changed

+726
-3
lines changed

‎docs/configure.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# Create a launch configuration
2+
3+
In Visual Studio Code, the `launch.json` configuration file connects a debug session to the target hardware via a debug
4+
adapter. The following explains how to create the file for single- and multi-core devices using different debug adapters.
5+
6+
The pseudo debugger types `cmsis-debug-pyocd` and `cmsis-debug-jlink` are available to set up the debug connection in the
7+
`launch.json` configuration file. However, these are not full debug adapters but generate debug configurations of type
8+
`gdbtarget` which comes with the
9+
[CDT GDB Debug Adapter Extension](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.cdt-gdb-vscode) that is
10+
part of the Arm CMSIS Debugger extension pack.
11+
12+
!!! Note
13+
Using pyOCD, you can connect to the target via CMSIS-DAP and ST-LINK debug probes.
14+
15+
## Prerequisites
16+
17+
Make sure you have made the [required changes](./setup.md#project-setup) to your CMSIS Solution-based project.
18+
19+
If your project does not yet contain a `launch.json` file, create it as follows:
20+
21+
- Go to the **Rund and Debug view**.
22+
23+
![Run and Debug view](./images/create-launch-json.png)
24+
25+
- Click **create a launch.json file** link in the text. A quick-pick shows:
26+
27+
![Debugger quick pick](./images/select-debugger.png)
28+
29+
- Select **CMSIS Debugger (pyOCD)** or **CMSIS Debugger (J-LINK)**.
30+
31+
- This creates a new `launch.json` file under `.vscode` pre-filled with the selected default configuration.
32+
33+
## Debugging with pyOCD
34+
35+
For debugging with pyOCD, the following is added to the `launch.json` file:
36+
37+
```yml
38+
{
39+
"configurations": [
40+
{
41+
"name": "CMSIS Debugger: pyOCD",
42+
"type": "gdbtarget",
43+
"request": "launch",
44+
"cwd": "${workspaceFolder}",
45+
"program": "${command:cmsis-csolution.getBinaryFile}",
46+
"gdb": "arm-none-eabi-gdb",
47+
"initCommands": [
48+
"load",
49+
"break main"
50+
],
51+
"target": {
52+
"server": "pyocd",
53+
"port": "3333"
54+
},
55+
"cmsis": {
56+
"cbuildRunFile": "${command:cmsis-csolution.getCbuildRunFile}"
57+
}
58+
}
59+
]
60+
}
61+
```
62+
63+
### Single-core (pyOCD)
64+
65+
For a single-core device, you need to add:
66+
67+
- the relative path to the HEX file to `"initCommands"` - `"load"`.
68+
69+
- an absolute `"definitionPath"` to the device's SVD file to be able to use the [Periperals view](./debug.md).
70+
71+
**Example**
72+
73+
```yml
74+
{
75+
"configurations": [
76+
{
77+
"name": "CMSIS Debugger: pyOCD",
78+
"type": "gdbtarget",
79+
"request": "launch",
80+
"cwd": "${workspaceFolder}",
81+
"program": "${command:cmsis-csolution.getBinaryFile}",
82+
"gdb": "arm-none-eabi-gdb",
83+
"initCommands": [
84+
"load ./out/Blinky/B-U585I-IOT02A/Debug/Blinky.hex",
85+
"break main"
86+
],
87+
"target": {
88+
"server": "pyocd",
89+
"port": "3333"
90+
},
91+
"cmsis": {
92+
"cbuildRunFile": "${command:cmsis-csolution.getCbuildRunFile}"
93+
}
94+
"definitionPath": "/Users/user/.cache/arm/packs/Keil/STM32U5xx_DFP/3.0.0/CMSIS/SVD/STM32U585.svd"
95+
}
96+
]
97+
}
98+
```
99+
100+
### Multi-core (pyOCD)
101+
102+
For a multi-core device, you need to:
103+
104+
- for the boot core: add the relative path to the HEX files for both cores to `"initCommands"` - `"load"`.
105+
106+
- for the secondary core: comment out the `"initCommands"`.
107+
108+
- for each core:
109+
110+
- add an absolute `"definitionPath"` to the device's SVD file to be able to use the
111+
[Periperals view](./debug.md).
112+
113+
- add the relative path to the AXF (ELF) files for each core to `"program"`.
114+
115+
116+
**Example**
117+
118+
```yml
119+
{
120+
"configurations": [
121+
{
122+
"name": "CM4: CMSIS Debugger: pyOCD",
123+
"type": "gdbtarget",
124+
"request": "launch",
125+
"cwd": "${workspaceFolder}",
126+
"program": "out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.axf",
127+
"gdb": "arm-none-eabi-gdb",
128+
"initCommands": [
129+
"load out/HelloWorld_cm4/FRDM-K32L3A6/Debug/HelloWorld_cm4.hex",
130+
"load out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug/HelloWorld_cm0plus.hex",
131+
"set $pc = Reset_Handler",
132+
"break main"
133+
],
134+
"target": {
135+
"server": "pyocd",
136+
"port": "3333"
137+
},
138+
"cmsis": {
139+
"cbuildRunFile": "FRDM-K32L3A6.cbuild-run.yml"
140+
},
141+
"definitionPath": "/Users/user/.cache/arm/packs/NXP/K32L3A60_DFP/19.0.0/devices/K32L3A60/K32L3A60_cm4.xml"
142+
},
143+
{
144+
"name": "CM0+: CMSIS Debugger: pyOCD",
145+
"type": "gdbtarget",
146+
"request": "attach",
147+
"cwd": "${workspaceFolder}",
148+
"program": "out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug/HelloWorld_cm0plus.axf",
149+
"gdb": "arm-none-eabi-gdb",
150+
// "initCommands": [
151+
// "load",
152+
// "break main"
153+
// ],
154+
"target": {
155+
"server": "pyocd",
156+
"port": "3334"
157+
},
158+
"definitionPath": "/Users/user/.cache/arm/packs/NXP/K32L3A60_DFP/19.0.0/devices/K32L3A60/K32L3A60_cm0plus.xml"
159+
}
160+
]
161+
}
162+
```
163+
164+
!!! Note
165+
In this example, the `"set $pc = Reset_Handler",` is required to set the program counter to the correct value.
166+
167+
## Debugging with J-Link
168+
169+
For debugging with Segger J-Link (using the [J-Link GDB Server](https://kb.segger.com/J-Link_GDB_Server)), the following is
170+
added to the `launch.json` file:
171+
172+
```yml
173+
{
174+
"configurations": [
175+
{
176+
"name": "CMSIS Debugger: J-LINK",
177+
"type": "gdbtarget",
178+
"request": "launch",
179+
"cwd": "${workspaceFolder}",
180+
"program": "${command:cmsis-csolution.getBinaryFile}",
181+
"gdb": "arm-none-eabi-gdb",
182+
"initCommands": [
183+
"load",
184+
"break main"
185+
],
186+
"target": {
187+
"server": "JLinkGDBServer",
188+
"serverParameters": [
189+
"-device",
190+
"${command:cmsis-csolution.getDeviceName}",
191+
"-endian",
192+
"little",
193+
"-if",
194+
"SWD",
195+
"-speed",
196+
"auto",
197+
"-noir",
198+
"-vd",
199+
"-nogui",
200+
"-localhostonly"
201+
],
202+
"port": "3333"
203+
}
204+
}
205+
]
206+
}
207+
```
208+
209+
### Single-core (J-Link)
210+
211+
For a single-core device, the configuration template contains all the information that is requires to start debugging.
212+
213+
!!! Attention
214+
**Check if the above statement is true!**
215+
216+
### Multi-core (J-Link)
217+
218+
For a multi-core device, you need to:
219+
220+
- change the `"-device"` entry to add processor names.
221+
222+
- create a `JLinkDevices.xml` file containing entries for all cores (refer to the
223+
[J-Link Device Support Kit documentation](https://kb.segger.com/J-Link_Device_Support_Kit) on how to do that).
224+
225+
- add the XML file to the `"serverParameters"` so that the Segger GDB server can pick them up.
226+
227+
**Example**
228+
229+
```yml
230+
{
231+
"version": "0.2.0",
232+
"configurations": [
233+
{
234+
"name": "CMSIS Debugger: J-LINK",
235+
"type": "gdbtarget",
236+
"request": "launch",
237+
"cwd": "${workspaceFolder}",
238+
"program": "${command:cmsis-csolution.getBinaryFile}",
239+
"gdb": "arm-none-eabi-gdb",
240+
"initCommands": [
241+
"load",
242+
"break main"
243+
],
244+
"target": {
245+
"server": "JLinkGDBServer",
246+
"serverParameters": [
247+
"-device",
248+
"${command:cmsis-csolution.getDeviceName}_${command:cmsis-csolution.getProcessorName}",
249+
"-JLinkDevicesXmlPath",
250+
".alif/JLinkDevices.xml",
251+
"-endian",
252+
"little",
253+
"-if",
254+
"SWD",
255+
"-speed",
256+
"auto",
257+
"-noir",
258+
"-vd",
259+
"-nogui",
260+
"-localhostonly"
261+
],
262+
"port": "3333"
263+
}
264+
}
265+
266+
]
267+
}
268+
```
269+
270+
For this example, the content of the `JLinkDevices.xml` file is as follows:
271+
272+
```xml
273+
<DataBase>
274+
<Device>
275+
<ChipInfo Vendor="AlifSemiconductor" Name="AE722F80F55D5_HP" Aliases="AE722F80F55D5LS_M55_HP; AE722F80F55D5AS_M55_HP" />
276+
</Device>
277+
<Device>
278+
<ChipInfo Vendor="AlifSemiconductor" Name="AE722F80F55D5_HE" Aliases="AE722F80F55D5LS_M55_HE; AE722F80F55D5AS_M55_HE" />
279+
</Device>
280+
</DataBase>
281+
```

‎docs/css/extra.css‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.wy-table-responsive table td, .wy-table-responsive table th {
2+
white-space: normal !important;
3+
}
4+
5+
.wy-table-responsive {
6+
overflow : visible !important;
7+
}
8+
9+
.wy-nav-content {
10+
max-width: 900px;
11+
}
12+
13+
.rst-content .section ul li p:last-child {
14+
padding: 0px 0px 8px 0px;
15+
}

‎docs/debug.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Start debugging
2+
3+
There are two ways to start a debug session:
4+
5+
1. In the **CMSIS view** ![CMSIS view](./images/cmsis-view-icon.png), click on the **Debug** icon
6+
![Debug icon in the CMSIS view](./images/debug-icon.png). Depending on the number of configurations in your `launch.json`
7+
file, you will be asked to select a configuration for the debug session.
8+
9+
2. In the **Run and debug view** ![Run and debug view](./images/run-debug-view-icon.png), click the **Play** icon
10+
next to the selected debug connection ![Play button](./images/play-debug-button.png). The debug starts with the selected
11+
configuration.
12+
13+
The debugger loads the application program and executes the startup code. When program execution stops (by default at `main`),
14+
the source code opens at the next executable statement which is marked with a yellow arrow in the editor:
15+
16+
![Execution stopped at main](./images/stop-at-main.png)
17+
18+
Most editor features are available in debug mode. For example, developers can use the Find command and can correct program
19+
errors.
20+
21+
## Flash and run
22+
23+
If you do not wish to enter a debug session, you can issue a flash download only, followed by a reset of the device.
24+
25+
In the **CMSIS view** ![CMSIS view](./images/cmsis-view-icon.png), click on the **Run** icon
26+
![Run icon in the CMSIS view](./images/run-icon.png).

0 commit comments

Comments
 (0)