Skip to content

Commit a546d1b

Browse files
thejpsterthejpster
authored
Merge pull request #78 from rubberduck203/vscode
VS Code Support
2 parents 3ca2bb9 + 57de818 commit a546d1b

File tree

5 files changed

+197
-0
lines changed

5 files changed

+197
-0
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
.gdb_history
44
Cargo.lock
55
target/
6+
7+
# editor files
8+
.vscode/

‎.vscode/README.md

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# VS Code Configuration
2+
3+
Example configurations for debugging programs in-editor with VS Code.
4+
This directory contains configurations for two platforms:
5+
6+
- `LM3S6965EVB` on QEMU
7+
- `STM32F303x` via OpenOCD
8+
9+
## Required Extensions
10+
11+
If you have the `code` command in your path, you can run the following commands to install the necessary extensions.
12+
13+
```sh
14+
code --install-extension rust-lang.rust
15+
code --install-extension marus25.cortex-debug
16+
```
17+
18+
Otherwise, you can use the Extensions view to search for and install them, or go directly to their marketplace pages and click the "Install" button.
19+
20+
- [Rust Language Server (RLS)](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust)
21+
- [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)
22+
23+
## Use
24+
25+
The quickstart comes with two debug configurations.
26+
Both are configured to build the project, using the default settings from `.cargo/config`, prior to starting a debug session.
27+
28+
_Note: When you open the project in the editor, you must open an `*.rs` file to trigger the Rust Language Server.
29+
Failure to do so will cause a failure to find the `build` task._
30+
31+
1. QEMU: Starts a debug session using an emulation of the `LM3S6965EVB` mcu.
32+
- This works on a fresh `cargo generate` without modification of any of the settings described above.
33+
- Semihosting output will be written to the Output view `Adapter Output`.
34+
- `ITM` logging does not work with QEMU emulation.
35+
36+
2. OpenOCD: Starts a debug session for a `STM32F3DISCOVERY` board (or any `STM32F303x` running at 8MHz).
37+
- Follow the instructions above for configuring the build with `.cargo/config` and the `memory.x` linker script.
38+
- `ITM` output will be written to the Output view `SWO: ITM [port: 0, type: console]` output.
39+
40+
### Git
41+
42+
Files in the `.vscode/` directory are `.gitignore`d by default because many files that may end up in the `.vscode/` directory should not be committed and shared.
43+
If you would like to save this debug configuration to your repository and share it with your team, you'll need to explicitly `git add` the files to your repository.
44+
45+
```sh
46+
git add -f .vscode/launch.json
47+
git add -f .vscode/tasks.json
48+
git add -f .vscode/*.svd
49+
```
50+
51+
## Customizing for other targets
52+
53+
For full documentation, see the [Cortex-Debug][cortex-debug] repository.
54+
55+
### Device
56+
57+
Some configurations use this to automatically find the SVD file.
58+
Replace this with the part number for your device.
59+
60+
```json
61+
"device": "STM32F303VCT6",
62+
```
63+
64+
### OpenOCD Config Files
65+
66+
The `configFiles` property specifies a list of files to pass to OpenOCD.
67+
68+
```json
69+
"configFiles": [
70+
"interface/stlink-v2-1.cfg",
71+
"target/stm32f3x.cfg"
72+
],
73+
```
74+
75+
See the [OpenOCD config docs][openocd-config] for more information and the [OpenOCD repository for available configuration files][openocd-repo].
76+
77+
### SVD
78+
79+
The SVD file is a standard way of describing all registers and peripherals of an ARM Cortex-M mCU.
80+
Cortex-Debug needs this file to display the current register values for the peripherals on the device.
81+
82+
You can probably find the SVD for your device on the vendor's website.
83+
84+
85+
For example, the STM32F3DISCOVERY board uses an mcu from the `STM32F303x` line of processors.
86+
All the SVD files for the STM32F3 series are available on [ST's Website][stm32f3].
87+
Download the [stm32f3 SVD pack][stm32f3-svd], and copy the `STM32F303.svd` file into `.vscode/`.
88+
This line of the config tells the Cortex-Debug plug in where to find the file.
89+
90+
```json
91+
"svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
92+
```
93+
94+
For other processors, simply copy the correct `*.svd` file into the project and update the config accordingly.
95+
96+
### CPU Frequency
97+
98+
If your device is running at a frequency other than 8MHz, you'll need to modify this line of `launch.json` for the `ITM` output to work correctly.
99+
100+
```json
101+
"cpuFrequency": 8000000,
102+
```
103+
104+
### Other GDB Servers
105+
106+
For information on setting up GDB servers other than OpenOCD, see the [Cortex-Debug repository][cortex-debug].
107+
108+
[cortex-debug]: https://github.com/Marus/cortex-debug
109+
[stm32f3]: https://www.st.com/content/st_com/en/products/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus/stm32-mainstream-mcus/stm32f3-series.html#resource
110+
[stm32f3-svd]: https://www.st.com/resource/en/svd/stm32f3_svd.zip
111+
[openocd-config]: http://openocd.org/doc/html/Config-File-Guidelines.html
112+
[openocd-repo]: https://sourceforge.net/p/openocd/code/ci/master/tree/tcl/

‎.vscode/launch.json

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
{
2+
/*
3+
* Requires the Rust Language Server (RLS) and Cortex-Debug extensions
4+
* https://marketplace.visualstudio.com/items?itemName=rust-lang.rust
5+
* https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug
6+
*/
7+
"version": "0.2.0",
8+
"configurations": [
9+
{
10+
"type": "cortex-debug",
11+
"request": "launch",
12+
"name": "Debug (QEMU)",
13+
"servertype": "qemu",
14+
"cwd": "${workspaceRoot}",
15+
"preLaunchTask": "build",
16+
"runToMain": true,
17+
"executable": "./target/thumbv7m-none-eabi/debug/{{project-name}}",
18+
/* Run `cargo build --example hello` and uncomment this line to run semi-hosting example */
19+
//"executable": "./target/thumbv7m-none-eabi/debug/examples/hello",
20+
"cpu": "cortex-m3",
21+
"machine": "lm3s6965evb",
22+
},
23+
{
24+
/* Configuration for the STM32F303 Discovery board */
25+
"type": "cortex-debug",
26+
"request": "launch",
27+
"name": "Debug (OpenOCD)",
28+
"servertype": "openocd",
29+
"cwd": "${workspaceRoot}",
30+
"preLaunchTask": "build",
31+
"runToMain": true,
32+
"executable": "./target/thumbv7em-none-eabihf/debug/{{project-name}}",
33+
/* Run `cargo build --example itm` and uncomment this line to run itm example */
34+
// "executable": "./target/thumbv7em-none-eabihf/debug/examples/itm",
35+
"device": "STM32F303VCT6",
36+
"configFiles": [
37+
"interface/stlink-v2-1.cfg",
38+
"target/stm32f3x.cfg"
39+
],
40+
"svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
41+
"swoConfig": {
42+
"enabled": true,
43+
"cpuFrequency": 8000000,
44+
"swoFrequency": 2000000,
45+
"source": "probe",
46+
"decoders": [
47+
{ "type": "console", "label": "ITM", "port": 0 }
48+
]
49+
}
50+
}
51+
]
52+
}

‎.vscode/tasks.json

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
// See https://go.microsoft.com/fwlink/?LinkId=733558
3+
// for the documentation about the tasks.json format
4+
"version": "2.0.0",
5+
"tasks": [
6+
{
7+
/*
8+
* This is the default cargo build task,
9+
* but we need to provide a label for it,
10+
* so we can invoke it from the debug launcher.
11+
*/
12+
"label": "build",
13+
"type": "cargo",
14+
"subcommand": "build",
15+
"problemMatcher": [
16+
"$rustc"
17+
],
18+
"group": {
19+
"kind": "build",
20+
"isDefault": true
21+
}
22+
},
23+
]
24+
}

‎README.md

+6
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,12 @@ MEMORY
102102
$ cargo build
103103
```
104104

105+
## VS Code
106+
107+
This template includes launch configurations for debugging CortexM programs with Visual Studio Code located in the `.vscode/` directory.
108+
See [.vscode/README.md](./.vscode/README.md) for more information.
109+
If you're not using VS Code, you can safely delete the directory from the generated project.
110+
105111
# License
106112

107113
This template is licensed under either of

0 commit comments

Comments
 (0)