1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316
//! A template for building applications for ARM Cortex-M microcontrollers //! //! # Dependencies //! //! - Nightly Rust toolchain: `rustup default nightly` //! - ARM linker: `sudo apt-get install binutils-arm-none-eabi` //! - Cargo `clone` subcommand: `cargo install cargo-clone` //! - GDB: `sudo apt-get install gdb-arm-none-eabi` //! - OpenOCD: `sudo apt-get install OpenOCD` //! - Xargo: `cargo install xargo` //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit` //! //! # Usage //! //! - Clone this crate //! //! ``` text //! $ cargo clone cortex-m-quickstart && cd $_ //! ``` //! //! - Change the crate name, author and version //! //! ``` text //! $ edit Cargo.toml && head $_ //! [package] //! authors = ["Jorge Aparicio <jorge@japaric.io>"] //! name = "demo" //! version = "0.1.0" //! ``` //! //! - Specify the memory layout of the target device //! //! (Note that some board support crates may provide this file for you (check //! the crate documentation). If you are using one that does that then remove //! *both* the `memory.x` and `build.rs` files.) //! //! ``` text //! $ edit memory.x && cat $_ //! MEMORY //! { //! /* NOTE K = KiBi = 1024 bytes */ //! FLASH : ORIGIN = 0x08000000, LENGTH = 256K //! RAM : ORIGIN = 0x20000000, LENGTH = 40K //! } //! ``` //! //! - Optionally, set a default build target //! //! ``` text //! $ cat >>.cargo/config <<'EOF' //! [build] //! target = "thumbv7em-none-eabihf" //! EOF //! ``` //! //! - Very likely, depend on a device or a BSP (Board Support Package) crate. //! //! ``` text //! # add a device crate, or //! $ cargo add stm32f103xx //! //! # add a board support crate //! $ cargo add blue-pill --git https://github.com/japaric/blue-pill //! ``` //! //! - Write the application or start from one of the examples //! //! ``` text //! $ rm -r src/* && cp examples/hello.rs src/main.rs //! ``` //! //! - Disable incremental compilation. It doesn't work for embedded development. //! You'll hit nonsensical linker errors if you use it. //! //! ``` text //! $ unset CARGO_INCREMENTAL //! ``` //! //! - Build the application //! //! ``` text //! # NOTE this command requires `arm-none-eabi-ld` to be in $PATH //! $ xargo build --release //! //! $ arm-none-eabi-readelf -A target/thumbv7em-none-eabihf/release/demo //! Attribute Section: aeabi //! File Attributes //! Tag_conformance: "2.09" //! Tag_CPU_arch: v7E-M //! Tag_CPU_arch_profile: Microcontroller //! Tag_THUMB_ISA_use: Thumb-2 //! Tag_FP_arch: VFPv4-D16 //! Tag_ABI_PCS_GOT_use: direct //! Tag_ABI_FP_denormal: Needed //! Tag_ABI_FP_exceptions: Needed //! Tag_ABI_FP_number_model: IEEE 754 //! Tag_ABI_align_needed: 8-byte //! Tag_ABI_align_preserved: 8-byte, except leaf SP //! Tag_ABI_HardFP_use: SP only //! Tag_ABI_VFP_args: VFP registers //! Tag_ABI_optimization_goals: Aggressive Speed //! Tag_CPU_unaligned_access: v6 //! Tag_FP_HP_extension: Allowed //! Tag_ABI_FP_16bit_format: IEEE 754 //! ``` //! //! - Flash the program //! //! ``` text //! # Launch OpenOCD on a terminal //! $ openocd -f (..) //! ``` //! //! ``` text //! # Start a debug session in another terminal //! $ arm-none-eabi-gdb target/.. //! ``` //! //! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you //! can simply run `cargo run` or `cargo run --example $example` to build the //! program, and immediately start a debug session. IOW, it lets you omit the //! `arm-none-eabi-gdb` command. //! //! ``` text //! $ cargo run --example hello //! > # drops you into a GDB session //! ``` //! //! # Examples //! //! Check the [examples module](./examples/index.html) //! //! # Troubleshooting //! //! This section contains fixes for common errors encountered when the //! `cortex-m-quickstart` template is misused. //! //! ## Forgot to launch an OpenOCD instance //! //! Error message: //! //! ``` text //! $ arm-none-eabi-gdb target/.. //! Reading symbols from hello...done. //! .gdbinit:1: Error in sourced command file: //! :3333: Connection timed out. //! ``` //! //! Solution: Launch OpenOCD on other terminal. See [Usage] section. //! //! [Usage]: ./index.html#usage //! //! ## Didn't modify the `memory.x` linker script //! //! Error message: //! //! ``` text //! $ xargo build //! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo) //! error: linking with `arm-none-eabi-ld` failed: exit code: 1 //! | //! = note: "arm-none-eabi-ld" "-L" (..) //! = note: arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is .. //! arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is .. //! arm-none-eabi-ld: //! Invalid '.rodata.exceptions' section. //! Make sure to place a static with type `cortex_m::exception::Handlers` //! in that section (cf. #[link_section]) ONLY ONCE. //! ``` //! //! Solution: Specify your device memory layout in the `memory.x` linker script. //! See [Usage] section. //! //! ## Forgot to set a default build target //! //! Error message: //! //! ``` text //! $ xargo build //! (..) //! Compiling cortex-m-semihosting v0.1.3 //! error[E0463]: can't find crate for `std` //! //! error: aborting due to previous error //! ``` //! //! Solution: Set a default build target in the `.cargo/config` file //! (see [Usage] section), or call Xargo with `--target` flag: //! `xargo build --target thumbv7em-none-eabi`. //! //! ## Overwrote the original `.cargo/config` file //! //! Error message: //! //! ``` text //! error: linking with `arm-none-eabi-gcc` failed: exit code: 1 //! | //! = note: (..) //! (..) //! (..)/crt0.o: In function `_start': //! (.text+0x90): undefined reference to `memset' //! (..)/crt0.o: In function `_start': //! (.text+0xd0): undefined reference to `atexit' //! (..)/crt0.o: In function `_start': //! (.text+0xd4): undefined reference to `__libc_init_array' //! (..)/crt0.o: In function `_start': //! (.text+0xe4): undefined reference to `exit' //! (..)/crt0.o: In function `_start': //! (.text+0x100): undefined reference to `__libc_fini_array' //! collect2: error: ld returned 1 exit status //! ``` //! //! Solution: You probably overwrote the original `.cargo/config` instead of //! appending the default build target (e.g. `cat >` instead of `cat >>`). The //! less error prone way to fix this is to remove the `.cargo` directory, clone //! a new copy of the template and then copy the `.cargo` directory from that //! fresh template into your current project. Don't forget to *append* the //! default build target to `.cargo/config`. //! //! ## Called OpenOCD with wrong arguments //! //! Error message: //! //! ``` text //! $ openocd -f .. //! (..) //! Error: open failed //! in procedure 'init' //! in procedure 'ocd_bouncer' //! ``` //! //! Solution: Correct the OpenOCD arguments. Check the //! `/usr/share/openocd/scripts` directory (exact location varies per //! distribution / OS) for a list of scripts that can be used. //! //! ## Used Cargo instead of Xargo //! //! Error message: //! //! ``` text //! $ cargo build //! Compiling cortex-m-rt v0.2.0 //! error[E0463]: can't find crate for `core` //! | //! = note: the `thumbv7em-none-eabihf` target may not be installed //! //! error: aborting due to previous error //! ``` //! //! Solution: Use `xargo build`. //! //! ## Used the stable toolchain //! //! Error message: //! //! ``` text //! $ xargo build //! error: failed to run `rustc` to learn about target-specific information //! //! To learn more, run the command again with --verbose. //! ``` //! //! Solution: Switch to the nightly toolchain with `rustup default nightly`. //! //! ## Used `CARGO_INCREMENTAL=1` //! //! Error message: //! //! ``` text //! $ xargo build //! error: linking with `arm-none-eabi-ld` failed: exit code: 1 //! | //! = note: "arm-none-eabi-ld" (..) //! = note: arm-none-eabi-ld: //! You must specify the exception handlers. //! Create a non `pub` static variable with type //! `cortex_m::exception::Handlers` and place it in the //! '.rodata.exceptions' section. (cf. #[link_section]). Apply the //! `#[used]` attribute to the variable to make it reach the linker. //! arm-none-eabi-ld: //! Invalid '.rodata.exceptions' section. //! Make sure to place a static with type `cortex_m::exception::Handlers` //! in that section (cf. #[link_section]) ONLY ONCE. //! ``` //! //! Solution: `$ unset CARGO_INCREMENAL`. And to be on the safe side, call //! `cargo clean` and thrash the Xargo sysroot: `$ rm -rf ~/.xargo` //! //! ## Used `gdb` instead of `arm-none-eabi-gdb` //! //! Error message: //! //! ``` text //! $ gdb target/.. //! Reading symbols from hello...done. //! warning: Architecture rejected target-supplied description //! warning: Cannot convert floating-point register value to .. //! value has been optimized out //! Cannot write the dashboard //! Traceback (most recent call last): //! File "<string>", line 353, in render //! File "<string>", line 846, in lines //! gdb.error: Frame is invalid. //! 0x00000000 in ?? () //! semihosting is enabled //! Loading section .text, size 0xd88 lma 0x8000000 //! Start address 0x8000000, load size 3464 //! .gdbinit:6: Error in sourced command file: //! Remote connection closed //! ``` //! //! Solution: Use `arm-none-eabi-gdb target/..` #![no_std] pub mod examples;