diff --git a/.cargo-ok b/.cargo-ok new file mode 100644 index 0000000..e69de29 diff --git a/.cargo/config b/.cargo/config new file mode 100644 index 0000000..1262bad --- /dev/null +++ b/.cargo/config @@ -0,0 +1,33 @@ +[target.thumbv7m-none-eabi] +# uncomment this to make `cargo run` execute programs on QEMU +# runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel" + +[target.'cfg(all(target_arch = "arm", target_os = "none"))'] +# uncomment ONE of these three option to make `cargo run` start a GDB session +# which option to pick depends on your system +# runner = "arm-none-eabi-gdb -q -x openocd.gdb" +# runner = "gdb-multiarch -q -x openocd.gdb" +# runner = "gdb -q -x openocd.gdb" + +rustflags = [ + # LLD (shipped with the Rust toolchain) is used as the default linker + "-C", "link-arg=-Tlink.x", + + # if you run into problems with LLD switch to the GNU linker by commenting out + # this line + # "-C", "linker=arm-none-eabi-ld", + + # if you need to link to pre-compiled C libraries provided by a C toolchain + # use GCC as the linker by commenting out both lines above and then + # uncommenting the three lines below + # "-C", "linker=arm-none-eabi-gcc", + # "-C", "link-arg=-Wl,-Tlink.x", + # "-C", "link-arg=-nostartfiles", +] + +[build] +# Pick ONE of these compilation targets +target = "thumbv6m-none-eabi" # Cortex-M0 and Cortex-M0+ +# target = "thumbv7m-none-eabi" # Cortex-M3 +# target = "thumbv7em-none-eabi" # Cortex-M4 and Cortex-M7 (no FPU) +# target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU) diff --git a/.gitignore b/.gitignore index 53eaa21..cc4a880 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,12 @@ -/target **/*.rs.bk +.#* +.gdb_history +Cargo.lock +target/ + +# editor files +.vscode/* +!.vscode/*.md +!.vscode/*.svd +!.vscode/launch.json +!.vscode/tasks.json \ No newline at end of file diff --git a/.vscode/README.md b/.vscode/README.md new file mode 100644 index 0000000..a6c08b2 --- /dev/null +++ b/.vscode/README.md @@ -0,0 +1,112 @@ +# 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. + +_Note: When you open the project in the editor, you must open an `*.rs` file to trigger the Rust Language Server. +Failure to do so will cause a failure to find the `build` task._ + +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/ diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..32c643f --- /dev/null +++ b/.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": "build", + "runToMain": true, + "executable": "./target/thumbv7m-none-eabi/debug/onyx", + /* 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": "build", + "runToMain": true, + "executable": "./target/thumbv7em-none-eabihf/debug/onyx", + /* 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 } + ] + } + } + ] +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..1331bc0 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,24 @@ +{ + // 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": "build", + "type": "cargo", + "subcommand": "build", + "problemMatcher": [ + "$rustc" + ], + "group": { + "kind": "build", + "isDefault": true + } + }, + ] +} \ No newline at end of file diff --git a/Cargo.lock b/Cargo.lock index 0abb2fd..7e2a5c0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1,6 +1,199 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +[[package]] +name = "aligned" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "as-slice 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "as-slice" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)", + "generic-array 0.13.2 (registry+https://github.com/rust-lang/crates.io-index)", + "stable_deref_trait 1.1.1 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "bare-metal" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "rustc_version 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "cortex-m" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "aligned 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)", + "bare-metal 0.2.5 (registry+https://github.com/rust-lang/crates.io-index)", + "volatile-register 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "cortex-m-rt" +version = "0.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "cortex-m-rt-macros 0.1.7 (registry+https://github.com/rust-lang/crates.io-index)", + "r0 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "cortex-m-rt-macros" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "proc-macro2 1.0.8 (registry+https://github.com/rust-lang/crates.io-index)", + "quote 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.14 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "cortex-m-semihosting" +version = "0.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "cortex-m 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "generic-array" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "typenum 1.11.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "generic-array" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "typenum 1.11.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "onyx" version = "0.1.0" +dependencies = [ + "cortex-m 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)", + "cortex-m-rt 0.6.11 (registry+https://github.com/rust-lang/crates.io-index)", + "cortex-m-semihosting 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)", + "panic-halt 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] +[[package]] +name = "panic-halt" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "proc-macro2" +version = "1.0.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "quote" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "proc-macro2 1.0.8 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "r0" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "rustc_version" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "semver 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "semver" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "semver-parser 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "semver-parser" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "stable_deref_trait" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "syn" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "proc-macro2 1.0.8 (registry+https://github.com/rust-lang/crates.io-index)", + "quote 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)", + "unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "typenum" +version = "1.11.2" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "unicode-xid" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "vcell" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" + +[[package]] +name = "volatile-register" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "vcell 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[metadata] +"checksum aligned 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)" = "eb1ce8b3382016136ab1d31a1b5ce807144f8b7eb2d5f16b2108f0f07edceb94" +"checksum as-slice 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "be6b7e95ac49d753f19cab5a825dea99a1149a04e4e3230b33ae16e120954c04" +"checksum bare-metal 0.2.5 (registry+https://github.com/rust-lang/crates.io-index)" = "5deb64efa5bd81e31fcd1938615a6d98c82eafcbcd787162b6f63b91d6bac5b3" +"checksum cortex-m 0.6.2 (registry+https://github.com/rust-lang/crates.io-index)" = "2954942fbbdd49996704e6f048ce57567c3e1a4e2dc59b41ae9fde06a01fc763" +"checksum cortex-m-rt 0.6.11 (registry+https://github.com/rust-lang/crates.io-index)" = "33a716cd7d8627fae3892c2eede9249e50d2d79aedfb43ca28dad9a2b23876d9" +"checksum cortex-m-rt-macros 0.1.7 (registry+https://github.com/rust-lang/crates.io-index)" = "72b1073338d1e691b3b7aaf6bd61993e589ececce9242a02dfa5453e1b98918d" +"checksum cortex-m-semihosting 0.3.5 (registry+https://github.com/rust-lang/crates.io-index)" = "113ef0ecffee2b62b58f9380f4469099b30e9f9cbee2804771b4203ba1762cfa" +"checksum generic-array 0.12.3 (registry+https://github.com/rust-lang/crates.io-index)" = "c68f0274ae0e023facc3c97b2e00f076be70e254bc851d972503b328db79b2ec" +"checksum generic-array 0.13.2 (registry+https://github.com/rust-lang/crates.io-index)" = "0ed1e761351b56f54eb9dcd0cfaca9fd0daecf93918e1cfc01c8a3d26ee7adcd" +"checksum panic-halt 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "de96540e0ebde571dc55c73d60ef407c653844e6f9a1e2fdbd40c07b9252d812" +"checksum proc-macro2 1.0.8 (registry+https://github.com/rust-lang/crates.io-index)" = "3acb317c6ff86a4e579dfa00fc5e6cca91ecbb4e7eb2df0468805b674eb88548" +"checksum quote 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)" = "053a8c8bcc71fcce321828dc897a98ab9760bef03a4fc36693c231e5b3216cfe" +"checksum r0 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "e2a38df5b15c8d5c7e8654189744d8e396bddc18ad48041a500ce52d6948941f" +"checksum rustc_version 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "138e3e0acb6c9fb258b19b67cb8abd63c00679d2851805ea151465464fe9030a" +"checksum semver 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)" = "1d7eb9ef2c18661902cc47e535f9bc51b78acd254da71d375c2f6720d9a40403" +"checksum semver-parser 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "388a1df253eca08550bef6c72392cfe7c30914bf41df5269b68cbd6ff8f570a3" +"checksum stable_deref_trait 1.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "dba1a27d3efae4351c8051072d619e3ade2820635c3958d826bfea39d59b54c8" +"checksum syn 1.0.14 (registry+https://github.com/rust-lang/crates.io-index)" = "af6f3550d8dff9ef7dc34d384ac6f107e5d31c8f57d9f28e0081503f547ac8f5" +"checksum typenum 1.11.2 (registry+https://github.com/rust-lang/crates.io-index)" = "6d2783fe2d6b8c1101136184eb41be8b1ad379e4657050b8aaff0c79ee7575f9" +"checksum unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "826e7639553986605ec5979c7dd957c7895e93eabed50ab2ffa7f6128a75097c" +"checksum vcell 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)" = "876e32dcadfe563a4289e994f7cb391197f362b6315dc45e8ba4aa6f564a4b3c" +"checksum volatile-register 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "0d67cb4616d99b940db1d6bd28844ff97108b498a6ca850e5b6191a532063286" diff --git a/Cargo.toml b/Cargo.toml index 5f7b3e3..7e47608 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,9 +1,36 @@ [package] +authors = ["Edward Shen ", "haskal "] +edition = "2018" +readme = "README.md" name = "onyx" version = "0.1.0" -authors = ["edward ", "haskal "] -edition = "2018" - -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] +cortex-m = "0.6.0" +cortex-m-rt = "0.6.10" +cortex-m-semihosting = "0.3.3" +panic-halt = "0.2.0" + +# Uncomment for the panic example. +# panic-itm = "0.4.1" + +# Uncomment for the allocator example. +# alloc-cortex-m = "0.3.5" + +# Uncomment for the device example. +# Update `memory.x`, set target to `thumbv7em-none-eabihf` in `.cargo/config`, +# 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`! +[[bin]] +name = "onyx" +test = false +bench = false + +[profile.release] +codegen-units = 1 # better optimizations +debug = true # symbols are nice and they don't increase the size on Flash +lto = true # better optimizations diff --git a/README.md b/README.md index 5b82f07..293c092 100644 --- a/README.md +++ b/README.md @@ -1 +1,135 @@ -# Onyx Keyboard Firmware # +# `cortex-m-quickstart` + +> A template for building applications for ARM Cortex-M microcontrollers + +This project is developed and maintained by the [Cortex-M team][team]. + +## Dependencies + +To build embedded programs using this template you'll need: + +- Rust 1.31, 1.30-beta, nightly-2018-09-13 or a newer toolchain. e.g. `rustup + default beta` + +- The `cargo generate` subcommand. [Installation + instructions](https://github.com/ashleygwilliams/cargo-generate#installation). + +- `rust-std` components (pre-compiled `core` crate) for the ARM Cortex-M + targets. Run: + +``` console +$ rustup target add thumbv6m-none-eabi thumbv7m-none-eabi thumbv7em-none-eabi thumbv7em-none-eabihf +``` + +## Using this template + +**NOTE**: This is the very short version that only covers building programs. For +the long version, which additionally covers flashing, running and debugging +programs, check [the embedded Rust book][book]. + +[book]: https://rust-embedded.github.io/book + +0. Before we begin you need to identify some characteristics of the target + device as these will be used to configure the project: + +- The ARM core. e.g. Cortex-M3. + +- Does the ARM core include an FPU? Cortex-M4**F** and Cortex-M7**F** cores do. + +- How much Flash memory and RAM does the target device has? e.g. 256 KiB of + Flash and 32 KiB of RAM. + +- Where are Flash memory and RAM mapped in the address space? e.g. RAM is + commonly located at address `0x2000_0000`. + +You can find this information in the data sheet or the reference manual of your +device. + +In this example we'll be using the STM32F3DISCOVERY. This board contains an +STM32F303VCT6 microcontroller. This microcontroller has: + +- A Cortex-M4F core that includes a single precision FPU + +- 256 KiB of Flash located at address 0x0800_0000. + +- 40 KiB of RAM located at address 0x2000_0000. (There's another RAM region but + for simplicity we'll ignore it). + +1. Instantiate the template. + +``` console +$ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart + Project Name: app + Creating project called `app`... + Done! New project created /tmp/app + +$ cd app +``` + +2. Set a default compilation target. There are four options as mentioned at the + bottom of `.cargo/config`. For the STM32F303VCT6, which has a Cortex-M4F + core, we'll pick the `thumbv7em-none-eabihf` target. + +``` console +$ tail -n6 .cargo/config +``` + +``` toml +[build] +# Pick ONE of these compilation targets +# target = "thumbv6m-none-eabi" # Cortex-M0 and Cortex-M0+ +# target = "thumbv7m-none-eabi" # Cortex-M3 +# target = "thumbv7em-none-eabi" # Cortex-M4 and Cortex-M7 (no FPU) +target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU) +``` + +3. Enter the memory region information into the `memory.x` file. + +``` console +$ cat memory.x +/* Linker script for the STM32F303VCT6 */ +MEMORY +{ + /* NOTE 1 K = 1 KiBi = 1024 bytes */ + FLASH : ORIGIN = 0x08000000, LENGTH = 256K + RAM : ORIGIN = 0x20000000, LENGTH = 40K +} +``` + +4. Build the template application or one of the examples. + +``` console +$ 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 + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or + http://www.apache.org/licenses/LICENSE-2.0) + +- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +## Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be +dual licensed as above, without any additional terms or conditions. + +## Code of Conduct + +Contribution to this crate is organized under the terms of the [Rust Code of +Conduct][CoC], the maintainer of this crate, the [Cortex-M team][team], promises +to intervene to uphold that code of conduct. + +[CoC]: https://www.rust-lang.org/policies/code-of-conduct +[team]: https://github.com/rust-embedded/wg#the-cortex-m-team diff --git a/build.rs b/build.rs new file mode 100644 index 0000000..98f603e --- /dev/null +++ b/build.rs @@ -0,0 +1,18 @@ +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 + let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap()); + File::create(out.join("memory.x")) + .unwrap() + .write_all(include_bytes!("memory.x")) + .unwrap(); + println!("cargo:rustc-link-search={}", out.display()); + + // Only re-run the build script when memory.x is changed, + // instead of when any part of the source code changes. + println!("cargo:rerun-if-changed=memory.x"); +} diff --git a/examples/allocator.rs b/examples/allocator.rs new file mode 100644 index 0000000..0399ebb --- /dev/null +++ b/examples/allocator.rs @@ -0,0 +1,57 @@ +//! How to use the heap and a dynamic memory allocator +//! +//! This example depends on the alloc-cortex-m crate so you'll have to add it to your Cargo.toml: +//! +//! ``` text +//! # or edit the Cargo.toml file manually +//! $ cargo add alloc-cortex-m +//! ``` +//! +//! --- + +#![feature(alloc)] +#![feature(alloc_error_handler)] +#![no_main] +#![no_std] + +extern crate alloc; +extern crate panic_halt; + +use self::alloc::vec; +use core::alloc::Layout; + +use alloc_cortex_m::CortexMHeap; +use cortex_m::asm; +use cortex_m_rt::entry; +use cortex_m_semihosting::hprintln; + +// this is the allocator the application will use +#[global_allocator] +static ALLOCATOR: CortexMHeap = CortexMHeap::empty(); + +const HEAP_SIZE: usize = 1024; // in bytes + +#[entry] +fn main() -> ! { + // Initialize the allocator BEFORE you use it + unsafe { ALLOCATOR.init(cortex_m_rt::heap_start() as usize, HEAP_SIZE) } + + // Growable array allocated on the heap + let xs = vec![0, 1, 2]; + + hprintln!("{:?}", xs).unwrap(); + + // exit QEMU + // NOTE do not run this on hardware; it can corrupt OpenOCD state + debug::exit(debug::EXIT_SUCCESS); + + loop {} +} + +// define what happens in an Out Of Memory (OOM) condition +#[alloc_error_handler] +fn alloc_error(_layout: Layout) -> ! { + asm::bkpt(); + + loop {} +} diff --git a/examples/crash.rs b/examples/crash.rs new file mode 100644 index 0000000..fecde7a --- /dev/null +++ b/examples/crash.rs @@ -0,0 +1,96 @@ +//! Debugging a crash (exception) +//! +//! Most crash conditions trigger a hard fault exception, whose handler is defined via +//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a +//! snapshot of the CPU registers at the moment of the exception. +//! +//! This program crashes and the `HardFault` handler prints to the console the contents of the +//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace +//! that led to the exception. +//! +//! ``` text +//! (gdb) continue +//! Program received signal SIGTRAP, Trace/breakpoint trap. +//! __bkpt () at asm/bkpt.s:3 +//! 3 bkpt +//! +//! (gdb) backtrace +//! #0 __bkpt () at asm/bkpt.s:3 +//! #1 0x080030b4 in cortex_m::asm::bkpt () at $$/cortex-m-0.5.0/src/asm.rs:19 +//! #2 rust_begin_unwind (args=..., file=..., line=99, col=5) at $$/panic-semihosting-0.2.0/src/lib.rs:87 +//! #3 0x08001d06 in core::panicking::panic_fmt () at libcore/panicking.rs:71 +//! #4 0x080004a6 in crash::hard_fault (ef=0x20004fa0) at examples/crash.rs:99 +//! #5 0x08000548 in UserHardFault (ef=0x20004fa0) at :10 +//! #6 0x0800093a in HardFault () at asm.s:5 +//! Backtrace stopped: previous frame identical to this frame (corrupt stack?) +//! ``` +//! +//! In the console output one will find the state of the Program Counter (PC) register at the time +//! of the exception. +//! +//! ``` text +//! panicked at 'HardFault at ExceptionFrame { +//! r0: 0x2fffffff, +//! r1: 0x2fffffff, +//! r2: 0x080051d4, +//! r3: 0x080051d4, +//! r12: 0x20000000, +//! lr: 0x08000435, +//! pc: 0x08000ab6, +//! xpsr: 0x61000000 +//! }', examples/crash.rs:106:5 +//! ``` +//! +//! This register contains the address of the instruction that caused the exception. In GDB one can +//! disassemble the program around this address to observe the instruction that caused the +//! exception. +//! +//! ``` text +//! (gdb) disassemble/m 0x08000ab6 +//! Dump of assembler code for function core::ptr::read_volatile: +//! 451 pub unsafe fn read_volatile(src: *const T) -> T { +//! 0x08000aae <+0>: sub sp, #16 +//! 0x08000ab0 <+2>: mov r1, r0 +//! 0x08000ab2 <+4>: str r0, [sp, #8] +//! +//! 452 intrinsics::volatile_load(src) +//! 0x08000ab4 <+6>: ldr r0, [sp, #8] +//! -> 0x08000ab6 <+8>: ldr r0, [r0, #0] +//! 0x08000ab8 <+10>: str r0, [sp, #12] +//! 0x08000aba <+12>: ldr r0, [sp, #12] +//! 0x08000abc <+14>: str r1, [sp, #4] +//! 0x08000abe <+16>: str r0, [sp, #0] +//! 0x08000ac0 <+18>: b.n 0x8000ac2 +//! +//! 453 } +//! 0x08000ac2 <+20>: ldr r0, [sp, #0] +//! 0x08000ac4 <+22>: add sp, #16 +//! 0x08000ac6 <+24>: bx lr +//! +//! End of assembler dump. +//! ``` +//! +//! `ldr r0, [r0, #0]` caused the exception. This instruction tried to load (read) a 32-bit word +//! from the address stored in the register `r0`. Looking again at the contents of `ExceptionFrame` +//! we see that the `r0` contained the address `0x2FFF_FFFF` when this instruction was executed. +//! +//! --- + +#![no_main] +#![no_std] + +extern crate panic_halt; + +use core::ptr; + +use cortex_m_rt::entry; + +#[entry] +fn main() -> ! { + unsafe { + // read an address outside of the RAM region; this causes a HardFault exception + ptr::read_volatile(0x2FFF_FFFF as *const u32); + } + + loop {} +} diff --git a/examples/device.rs b/examples/device.rs new file mode 100644 index 0000000..63c21dc --- /dev/null +++ b/examples/device.rs @@ -0,0 +1,62 @@ +//! Using a device crate +//! +//! Crates generated using [`svd2rust`] are referred to as device crates. These crates provide an +//! API to access the peripherals of a device. +//! +//! [`svd2rust`]: https://crates.io/crates/svd2rust +//! +//! This example depends on the [`stm32f3`] crate so you'll have to +//! uncomment it in your Cargo.toml. +//! +//! [`stm32f3`]: https://crates.io/crates/stm32f3 +//! +//! ``` +//! $ edit Cargo.toml && tail $_ +//! [dependencies.stm32f3] +//! features = ["stm32f303", "rt"] +//! 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 cortex_m::peripheral::syst::SystClkSource; +use cortex_m_rt::entry; +use cortex_m_semihosting::hprint; +use stm32f3::stm32f303::{interrupt, Interrupt, NVIC}; + +#[entry] +fn main() -> ! { + let p = cortex_m::Peripherals::take().unwrap(); + + let mut syst = p.SYST; + let mut nvic = p.NVIC; + + nvic.enable(Interrupt::EXTI0); + + // configure the system timer to wrap around every second + syst.set_clock_source(SystClkSource::Core); + syst.set_reload(8_000_000); // 1s + syst.enable_counter(); + + loop { + // busy wait until the timer wraps around + while !syst.has_wrapped() {} + + // trigger the `EXTI0` interrupt + NVIC::pend(Interrupt::EXTI0); + } +} + +#[interrupt] +fn EXTI0() { + hprint!(".").unwrap(); +} diff --git a/examples/exception.rs b/examples/exception.rs new file mode 100644 index 0000000..756b85a --- /dev/null +++ b/examples/exception.rs @@ -0,0 +1,37 @@ +//! Overriding an exception handler +//! +//! You can override an exception handler using the [`#[exception]`][1] attribute. +//! +//! [1]: https://rust-embedded.github.io/cortex-m-rt/0.6.1/cortex_m_rt_macros/fn.exception.html +//! +//! --- + +#![deny(unsafe_code)] +#![no_main] +#![no_std] + +extern crate panic_halt; + +use cortex_m::peripheral::syst::SystClkSource; +use cortex_m::Peripherals; +use cortex_m_rt::{entry, exception}; +use cortex_m_semihosting::hprint; + +#[entry] +fn main() -> ! { + let p = Peripherals::take().unwrap(); + let mut syst = p.SYST; + + // configures the system timer to trigger a SysTick exception every second + syst.set_clock_source(SystClkSource::Core); + syst.set_reload(8_000_000); // period = 1s + syst.enable_counter(); + syst.enable_interrupt(); + + loop {} +} + +#[exception] +fn SysTick() { + hprint!(".").unwrap(); +} diff --git a/examples/hello.rs b/examples/hello.rs new file mode 100644 index 0000000..8e8586e --- /dev/null +++ b/examples/hello.rs @@ -0,0 +1,20 @@ +//! Prints "Hello, world!" on the host console using semihosting + +#![no_main] +#![no_std] + +extern crate panic_halt; + +use cortex_m_rt::entry; +use cortex_m_semihosting::{debug, hprintln}; + +#[entry] +fn main() -> ! { + hprintln!("Hello, world!").unwrap(); + + // exit QEMU + // NOTE do not run this on hardware; it can corrupt OpenOCD state + debug::exit(debug::EXIT_SUCCESS); + + loop {} +} diff --git a/examples/itm.rs b/examples/itm.rs new file mode 100644 index 0000000..f82f985 --- /dev/null +++ b/examples/itm.rs @@ -0,0 +1,33 @@ +//! Sends "Hello, world!" through the ITM port 0 +//! +//! ITM is much faster than semihosting. Like 4 orders of magnitude or so. +//! +//! **NOTE** Cortex-M0 chips don't support ITM. +//! +//! You'll have to connect the microcontroller's SWO pin to the SWD interface. Note that some +//! development boards don't provide this option. +//! +//! You'll need [`itmdump`] to receive the message on the host plus you'll need to uncomment two +//! `monitor` commands in the `.gdbinit` file. +//! +//! [`itmdump`]: https://docs.rs/itm/0.2.1/itm/ +//! +//! --- + +#![no_main] +#![no_std] + +extern crate panic_halt; + +use cortex_m::{iprintln, Peripherals}; +use cortex_m_rt::entry; + +#[entry] +fn main() -> ! { + let mut p = Peripherals::take().unwrap(); + let stim = &mut p.ITM.stim[0]; + + iprintln!(stim, "Hello, world!"); + + loop {} +} diff --git a/examples/panic.rs b/examples/panic.rs new file mode 100644 index 0000000..a323396 --- /dev/null +++ b/examples/panic.rs @@ -0,0 +1,28 @@ +//! Changing the panicking behavior +//! +//! The easiest way to change the panicking behavior is to use a different [panic handler crate][0]. +//! +//! [0]: https://crates.io/keywords/panic-impl + +#![no_main] +#![no_std] + +// Pick one of these panic handlers: + +// `panic!` halts execution; the panic message is ignored +extern crate panic_halt; + +// 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; + +// 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 cortex_m_rt::entry; + +#[entry] +fn main() -> ! { + panic!("Oops") +} diff --git a/examples/test_on_host.rs b/examples/test_on_host.rs new file mode 100644 index 0000000..1c75ed1 --- /dev/null +++ b/examples/test_on_host.rs @@ -0,0 +1,57 @@ +//! Conditionally compiling tests with std and our executable with no_std. +//! +//! Rust's built in unit testing framework requires the standard library, +//! but we need to build our final executable with no_std. +//! The testing framework also generates a `main` method, so we need to only use the `#[entry]` +//! annotation when building our final image. +//! For more information on why this example works, see this excellent blog post. +//! https://os.phil-opp.com/unit-testing/ +//! +//! Running this example: +//! +//! Ensure there are no targets specified under `[build]` in `.cargo/config` +//! In order to make this work, we lose the convenience of having a default target that isn't the +//! host. +//! +//! cargo build --example test_on_host --target thumbv7m-none-eabi +//! cargo test --example test_on_host + +#![cfg_attr(test, allow(unused_imports))] + +#![cfg_attr(not(test), no_std)] +#![cfg_attr(not(test), no_main)] + +// pick a panicking behavior +#[cfg(not(test))] +extern crate panic_halt; // you can put a breakpoint on `rust_begin_unwind` to catch panics +// extern crate panic_abort; // requires nightly +// extern crate panic_itm; // logs messages over ITM; requires ITM support +// extern crate panic_semihosting; // logs messages to the host stderr; requires a debugger + +use cortex_m::asm; +use cortex_m_rt::entry; + +#[cfg(not(test))] +#[entry] +fn main() -> ! { + asm::nop(); // To not have main optimize to abort in release mode, remove when you add code + + loop { + // your code goes here + } +} + +fn add(a: i32, b: i32) -> i32 { + a + b +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn foo() { + println!("tests work!"); + assert!(2 == add(1,1)); + } +} diff --git a/memory.x b/memory.x new file mode 100644 index 0000000..b259ddb --- /dev/null +++ b/memory.x @@ -0,0 +1,34 @@ +MEMORY +{ + /* NOTE 1 K = 1 KiBi = 1024 bytes */ + /* TODO Adjust these memory regions to match your device memory layout */ + /* These values correspond to the LM3S6965, one of the few devices QEMU can emulate */ + FLASH : ORIGIN = 0x00000000, LENGTH = 256K + RAM : ORIGIN = 0x20000000, LENGTH = 32K +} + +/* This is where the call stack will be allocated. */ +/* The stack is of the full descending type. */ +/* You may want to use this variable to locate the call stack and static + variables in different memory regions. Below is shown the default value */ +/* _stack_start = ORIGIN(RAM) + LENGTH(RAM); */ + +/* You can use this symbol to customize the location of the .text section */ +/* If omitted the .text section will be placed right after the .vector_table + section */ +/* This is required only on microcontrollers that store some configuration right + after the vector table */ +/* _stext = ORIGIN(FLASH) + 0x400; */ + +/* Example of putting non-initialized variables into custom RAM locations. */ +/* This assumes you have defined a region RAM2 above, and in the Rust + sources added the attribute `#[link_section = ".ram2bss"]` to the data + you want to place there. */ +/* Note that the section will not be zero-initialized by the runtime! */ +/* SECTIONS { + .ram2bss (NOLOAD) : ALIGN(4) { + *(.ram2bss); + . = ALIGN(4); + } > RAM2 + } INSERT AFTER .bss; +*/ diff --git a/openocd.cfg b/openocd.cfg new file mode 100644 index 0000000..81551c8 --- /dev/null +++ b/openocd.cfg @@ -0,0 +1,12 @@ +# Sample OpenOCD configuration for the STM32F3DISCOVERY development board + +# Depending on the hardware revision you got you'll have to pick ONE of these +# interfaces. At any time only one interface should be commented out. + +# Revision C (newer revision) +source [find interface/stlink-v2-1.cfg] + +# Revision A and B (older revisions) +# source [find interface/stlink-v2.cfg] + +source [find target/stm32f3x.cfg] diff --git a/openocd.gdb b/openocd.gdb new file mode 100644 index 0000000..7795319 --- /dev/null +++ b/openocd.gdb @@ -0,0 +1,40 @@ +target extended-remote :3333 + +# print demangled symbols +set print asm-demangle on + +# set backtrace limit to not have infinite backtrace loops +set backtrace limit 32 + +# detect unhandled exceptions, hard faults and panics +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 + +monitor arm semihosting enable + +# # send captured ITM to the file itm.fifo +# # (the microcontroller SWO pin must be connected to the programmer SWO pin) +# # 8000000 must match the core clock frequency +# monitor tpiu config internal itm.txt uart off 8000000 + +# # OR: make the microcontroller SWO pin output compatible with UART (8N1) +# # 8000000 must match the core clock frequency +# # 2000000 is the frequency of the SWO pin +# monitor tpiu config external uart off 8000000 2000000 + +# # enable ITM port 0 +# monitor itm port 0 on + +load + +# start the process but immediately halt the processor +stepi diff --git a/src/main.rs b/src/main.rs index e7a11a9..185b817 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,20 @@ -fn main() { - println!("Hello, world!"); +#![no_std] +#![no_main] + +// pick a panicking behavior +extern crate panic_halt; // you can put a breakpoint on `rust_begin_unwind` to catch panics +// extern crate panic_abort; // requires nightly +// extern crate panic_itm; // logs messages over ITM; requires ITM support +// extern crate panic_semihosting; // logs messages to the host stderr; requires a debugger + +use cortex_m::asm; +use cortex_m_rt::entry; + +#[entry] +fn main() -> ! { + asm::nop(); // To not have main optimize to abort in release mode, remove when you add code + + loop { + // your code goes here + } }