Merge pull request #100 from rubberduck203/master

Fixes #99: Disambiguates VSCode Tasks

.cargo/config

@@ -10,6 +10,10 @@
 # runner = "gdb -q -x openocd.gdb"
 
 rustflags = [
+  # This is needed if your flash or ram addresses are not aligned to 0x10000 in memory.x
+  # See https://github.com/rust-embedded/cortex-m-quickstart/pull/95
+  "-C", "link-arg=--nmagic",
+
   # LLD (shipped with the Rust toolchain) is used as the default linker
   "-C", "link-arg=-Tlink.x",
 
@@ -27,7 +31,10 @@ rustflags = [
 
 [build]
 # Pick ONE of these compilation targets
-# target = "thumbv6m-none-eabi"    # Cortex-M0 and Cortex-M0+
+# target = "thumbv6m-none-eabi"        # Cortex-M0 and Cortex-M0+
-target = "thumbv7m-none-eabi"    # Cortex-M3
+target = "thumbv7m-none-eabi"        # Cortex-M3
-# target = "thumbv7em-none-eabi"   # Cortex-M4 and Cortex-M7 (no FPU)
+# target = "thumbv7em-none-eabi"       # Cortex-M4 and Cortex-M7 (no FPU)
-# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)
+# target = "thumbv7em-none-eabihf"     # Cortex-M4F and Cortex-M7F (with FPU)
+# target = "thumbv8m.base-none-eabi"   # Cortex-M23
+# target = "thumbv8m.main-none-eabi"   # Cortex-M33 (no FPU)
+# target = "thumbv8m.main-none-eabihf" # Cortex-M33 (with FPU)

.gitignore

@@ -3,3 +3,11 @@
 .gdb_history
 Cargo.lock
 target/
+
+# editor files
+.vscode/*
+!.vscode/*.md
+!.vscode/*.svd
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/extensions.json

.vscode/README.md

@@ -0,0 +1,109 @@
+# VS Code Configuration
+
+Example configurations for debugging programs in-editor with VS Code.  
+This directory contains configurations for two platforms:
+
+ - `LM3S6965EVB` on QEMU
+ - `STM32F303x` via OpenOCD
+
+## Required Extensions
+
+If you have the `code` command in your path, you can run the following commands to install the necessary extensions.
+
+```sh
+code --install-extension rust-lang.rust
+code --install-extension marus25.cortex-debug
+```
+
+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.
+
+- [Rust Language Server (RLS)](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust)
+- [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)
+
+## Use
+
+The quickstart comes with two debug configurations.
+Both are configured to build the project, using the default settings from `.cargo/config`, prior to starting a debug session.
+
+1. QEMU: Starts a debug session using an emulation of the `LM3S6965EVB` mcu.
+   - This works on a fresh `cargo generate` without modification of any of the settings described above.
+   - Semihosting output will be written to the Output view `Adapter Output`.
+   - `ITM` logging does not work with QEMU emulation.
+
+2. OpenOCD: Starts a debug session for a `STM32F3DISCOVERY` board (or any `STM32F303x` running at 8MHz).
+   - Follow the instructions above for configuring the build with `.cargo/config` and the `memory.x` linker script.
+   - `ITM` output will be written to the Output view `SWO: ITM [port: 0, type: console]` output.
+
+### Git
+
+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.  
+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.
+
+```sh
+git add -f .vscode/launch.json
+git add -f .vscode/tasks.json
+git add -f .vscode/*.svd
+```
+
+## Customizing for other targets
+
+For full documentation, see the [Cortex-Debug][cortex-debug] repository.
+
+### Device
+
+Some configurations use this to automatically find the SVD file.  
+Replace this with the part number for your device.
+
+```json
+"device": "STM32F303VCT6",
+```
+
+### OpenOCD Config Files
+
+The `configFiles` property specifies a list of files to pass to OpenOCD.
+
+```json
+"configFiles": [
+    "interface/stlink-v2-1.cfg",
+    "target/stm32f3x.cfg"
+],
+```
+
+See the [OpenOCD config docs][openocd-config] for more information and the [OpenOCD repository for available configuration files][openocd-repo].
+
+### SVD
+
+The SVD file is a standard way of describing all registers and peripherals of an ARM Cortex-M mCU.  
+Cortex-Debug needs this file to display the current register values for the peripherals on the device.  
+
+You can probably find the SVD for your device on the vendor's website.  
+
+
+For example, the STM32F3DISCOVERY board uses an mcu from the `STM32F303x` line of processors.  
+All the SVD files for the STM32F3 series are available on [ST's Website][stm32f3].  
+Download the [stm32f3 SVD pack][stm32f3-svd], and copy the `STM32F303.svd` file into `.vscode/`.  
+This line of the config tells the Cortex-Debug plug in where to find the file.
+
+```json
+"svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
+```
+
+For other processors, simply copy the correct `*.svd` file into the project and update the config accordingly.
+
+### CPU Frequency
+
+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.
+
+```json
+"cpuFrequency": 8000000,
+```
+
+### Other GDB Servers
+
+For information on setting up GDB servers other than OpenOCD, see the [Cortex-Debug repository][cortex-debug].
+
+[cortex-debug]: https://github.com/Marus/cortex-debug
+[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
+[stm32f3-svd]: https://www.st.com/resource/en/svd/stm32f3_svd.zip
+[openocd-config]: http://openocd.org/doc/html/Config-File-Guidelines.html
+[openocd-repo]: https://sourceforge.net/p/openocd/code/ci/master/tree/tcl/

.vscode/extensions.json

@@ -0,0 +1,14 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"rust-lang.rust",
+		"marus25.cortex-debug",
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": [
+		
+	]
+}

.vscode/launch.json

@@ -0,0 +1,52 @@
+{
+    /* 
+     * Requires the Rust Language Server (RLS) and Cortex-Debug extensions
+     * https://marketplace.visualstudio.com/items?itemName=rust-lang.rust
+     * https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug
+     */
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "cortex-debug",
+            "request": "launch",
+            "name": "Debug (QEMU)",
+            "servertype": "qemu",
+            "cwd": "${workspaceRoot}",
+            "preLaunchTask": "Cargo Build (debug)",
+            "runToMain": true,
+            "executable": "./target/thumbv7m-none-eabi/debug/{{project-name}}",
+            /* Run `cargo build --example hello` and uncomment this line to run semi-hosting example */
+            //"executable": "./target/thumbv7m-none-eabi/debug/examples/hello",
+            "cpu": "cortex-m3",
+            "machine": "lm3s6965evb",
+        },
+        {
+            /* Configuration for the STM32F303 Discovery board */
+            "type": "cortex-debug",
+            "request": "launch",
+            "name": "Debug (OpenOCD)",
+            "servertype": "openocd",
+            "cwd": "${workspaceRoot}",
+            "preLaunchTask": "Cargo Build (debug)",
+            "runToMain": true,
+            "executable": "./target/thumbv7em-none-eabihf/debug/{{project-name}}",
+            /* Run `cargo build --example itm` and uncomment this line to run itm example */
+            // "executable": "./target/thumbv7em-none-eabihf/debug/examples/itm",
+            "device": "STM32F303VCT6",
+            "configFiles": [
+                "interface/stlink-v2-1.cfg",
+                "target/stm32f3x.cfg"
+            ],
+            "svdFile": "${workspaceRoot}/.vscode/STM32F303.svd",
+            "swoConfig": {
+                "enabled": true,
+                "cpuFrequency": 8000000,
+                "swoFrequency": 2000000,
+                "source": "probe",
+                "decoders": [
+                    { "type": "console", "label": "ITM", "port": 0 }
+                ]
+            }
+        }
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,63 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558 
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            /*
+             * This is the default cargo build task,
+             * but we need to provide a label for it,
+             * so we can invoke it from the debug launcher.
+             */
+            "label": "Cargo Build (debug)",
+            "type": "process",
+            "command": "cargo",
+            "args": ["build"],
+            "problemMatcher": [
+                "$rustc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "Cargo Build (release)",
+            "type": "process",
+            "command": "cargo",
+            "args": ["build", "--release"],
+            "problemMatcher": [
+                "$rustc"
+            ],
+            "group": "build"
+        },
+        {
+            "label": "Cargo Build Examples (debug)",
+            "type": "process",
+            "command": "cargo",
+            "args": ["build","--examples"],
+            "problemMatcher": [
+                "$rustc"
+            ],
+            "group": "build"
+        },
+        {
+            "label": "Cargo Build Examples (release)",
+            "type": "process",
+            "command": "cargo",
+            "args": ["build","--examples", "--release"],
+            "problemMatcher": [
+                "$rustc"
+            ],
+            "group": "build"
+        },
+        {
+            "label": "Cargo Clean",
+            "type": "process",
+            "command": "cargo",
+            "args": ["clean"],
+            "problemMatcher": [],
+            "group": "build"
+        },
+    ]
+}

Cargo.toml

@@ -6,20 +6,22 @@ name = "{{project-name}}"
 version = "0.1.0"
 
 [dependencies]
-cortex-m = "0.5.8"
+cortex-m = "0.6.0"
-cortex-m-rt = "0.6.5"
+cortex-m-rt = "0.6.10"
-cortex-m-semihosting = "0.3.2"
+cortex-m-semihosting = "0.3.3"
 panic-halt = "0.2.0"
 
 # Uncomment for the panic example.
-# panic-itm = "0.4.0"
+# panic-itm = "0.4.1"
 
 # Uncomment for the allocator example.
-# alloc-cortex-m = "0.3.5"
+# alloc-cortex-m = "0.4.0"
 
 # Uncomment for the device example.
-# [dependencies.stm32f30x]
+# Update `memory.x`, set target to `thumbv7em-none-eabihf` in `.cargo/config`,
-# features = ["rt"]
+# and then use `cargo build --examples device` to build it.
+# [dependencies.stm32f3]
+# features = ["stm32f303", "rt"]
 # version = "0.7.1"
 
 # this lets you use `cargo fix`!

README.md

@@ -102,6 +102,12 @@ MEMORY
 $ cargo build
 ```
 
+## VS Code
+
+This template includes launch configurations for debugging CortexM programs with Visual Studio Code located in the `.vscode/` directory.  
+See [.vscode/README.md](./.vscode/README.md) for more information.  
+If you're not using VS Code, you can safely delete the directory from the generated project.
+
 # License
 
 This template is licensed under either of

build.rs

@@ -1,10 +1,21 @@
+//! This build script copies the `memory.x` file from the crate root into
+//! a directory where the linker can always find it at build time.
+//! For many projects this is optional, as the linker always searches the
+//! project root directory -- wherever `Cargo.toml` is. However, if you
+//! are using a workspace or have a more complicated build setup, this
+//! build script becomes required. Additionally, by requesting that
+//! Cargo re-run the build script whenever `memory.x` is changed,
+//! updating `memory.x` ensures a rebuild of the application with the
+//! new memory settings.
+
 use std::env;
 use std::fs::File;
 use std::io::Write;
 use std::path::PathBuf;
 
 fn main() {
-    // Put the linker script somewhere the linker can find it
+    // Put `memory.x` in our output directory and ensure it's
+    // on the linker search path.
     let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
     File::create(out.join("memory.x"))
         .unwrap()
@@ -12,7 +23,9 @@ fn main() {
         .unwrap();
     println!("cargo:rustc-link-search={}", out.display());
 
-    // Only re-run the build script when memory.x is changed,
+    // By default, Cargo will re-run a build script whenever
-    // instead of when any part of the source code changes.
+    // any file in the project changes. By specifying `memory.x`
+    // here, we ensure the build script is only re-run when
+    // `memory.x` is changed.
     println!("cargo:rerun-if-changed=memory.x");
 }

examples/allocator.rs

@@ -9,13 +9,12 @@
 //!
 //! ---
 
-#![feature(alloc)]
 #![feature(alloc_error_handler)]
 #![no_main]
 #![no_std]
 
 extern crate alloc;
-extern crate panic_halt;
+use panic_halt as _;
 
 use self::alloc::vec;
 use core::alloc::Layout;
@@ -23,7 +22,7 @@ use core::alloc::Layout;
 use alloc_cortex_m::CortexMHeap;
 use cortex_m::asm;
 use cortex_m_rt::entry;
-use cortex_m_semihosting::hprintln;
+use cortex_m_semihosting::{hprintln, debug};
 
 // this is the allocator the application will use
 #[global_allocator]

examples/crash.rs

@@ -79,7 +79,7 @@
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use core::ptr;
 

examples/device.rs

@@ -5,29 +5,33 @@
 //!
 //! [`svd2rust`]: https://crates.io/crates/svd2rust
 //!
-//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
+//! This example depends on the [`stm32f3`] crate so you'll have to
+//! uncomment it in your Cargo.toml.
 //!
-//! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
+//! [`stm32f3`]: https://crates.io/crates/stm32f3
 //!
 //! ```
 //! $ edit Cargo.toml && tail $_
-//! [dependencies.stm32f103xx]
+//! [dependencies.stm32f3]
-//! features = ["rt"]
+//! features = ["stm32f303", "rt"]
-//! version = "0.10.0"
+//! version = "0.7.1"
 //! ```
 //!
+//! You also need to set the build target to thumbv7em-none-eabihf,
+//! typically by editing `.cargo/config` and uncommenting the relevant target line.
+//!
 //! ---
 
 #![no_main]
 #![no_std]
 
 #[allow(unused_extern_crates)]
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m::peripheral::syst::SystClkSource;
 use cortex_m_rt::entry;
 use cortex_m_semihosting::hprint;
-use stm32f30x::{interrupt, Interrupt};
+use stm32f3::stm32f303::{interrupt, Interrupt, NVIC};
 
 #[entry]
 fn main() -> ! {

examples/exception.rs

@@ -10,7 +10,7 @@
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m::peripheral::syst::SystClkSource;
 use cortex_m::Peripherals;

examples/hello.rs

@@ -3,7 +3,7 @@
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m_rt::entry;
 use cortex_m_semihosting::{debug, hprintln};

examples/itm.rs

@@ -17,7 +17,7 @@
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m::{iprintln, Peripherals};
 use cortex_m_rt::entry;

examples/panic.rs

@@ -10,15 +10,15 @@
 // Pick one of these panic handlers:
 
 // `panic!` halts execution; the panic message is ignored
-extern crate panic_halt;
+use panic_halt as _;
 
 // Reports panic messages to the host stderr using semihosting
 // NOTE to use this you need to uncomment the `panic-semihosting` dependency in Cargo.toml
-// extern crate panic_semihosting;
+// use panic_semihosting as _;
 
 // Logs panic messages using the ITM (Instrumentation Trace Macrocell)
 // NOTE to use this you need to uncomment the `panic-itm` dependency in Cargo.toml
-// extern crate panic_itm;
+// use panic_itm as _;
 
 use cortex_m_rt::entry;
 

examples/test_on_host.rs

@@ -23,10 +23,10 @@
 
 // pick a panicking behavior
 #[cfg(not(test))]
-extern crate panic_halt; // you can put a breakpoint on `rust_begin_unwind` to catch panics
+use panic_halt as _; // you can put a breakpoint on `rust_begin_unwind` to catch panics
-// extern crate panic_abort; // requires nightly
+// use panic_abort as _; // requires nightly
-// extern crate panic_itm; // logs messages over ITM; requires ITM support
+// use panic_itm as _; // logs messages over ITM; requires ITM support
-// extern crate panic_semihosting; // logs messages to the host stderr; requires a debugger
+// use panic_semihosting as _; // logs messages to the host stderr; requires a debugger
 
 use cortex_m::asm;
 use cortex_m_rt::entry;

openocd.gdb

@@ -10,6 +10,11 @@ set backtrace limit 32
 break DefaultHandler
 break HardFault
 break rust_begin_unwind
+# # run the next few lines so the panic message is printed immediately
+# # the number needs to be adjusted for your panic handler
+# commands $bpnum
+# next 4
+# end
 
 # *try* to stop at the user entry point (it might be gone due to inlining)
 break main

src/main.rs

@@ -2,10 +2,10 @@
 #![no_main]
 
 // pick a panicking behavior
-extern crate panic_halt; // you can put a breakpoint on `rust_begin_unwind` to catch panics
+use panic_halt as _; // you can put a breakpoint on `rust_begin_unwind` to catch panics
-// extern crate panic_abort; // requires nightly
+// use panic_abort as _; // requires nightly
-// extern crate panic_itm; // logs messages over ITM; requires ITM support
+// use panic_itm as _; // logs messages over ITM; requires ITM support
-// extern crate panic_semihosting; // logs messages to the host stderr; requires a debugger
+// use panic_semihosting as _; // logs messages to the host stderr; requires a debugger
 
 use cortex_m::asm;
 use cortex_m_rt::entry;