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
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
//! A template for building applications for ARM Cortex-M microcontrollers
//!
//! # Dependencies
//!
//! - Nightly Rust toolchain from 2018-08-28 or newer: `rustup default nightly`
//! - Cargo `clone` subcommand: `cargo install cargo-clone`
//! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
//! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
//! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
//!
//! # Usage
//!
//! 0) Figure out the cross compilation *target* to use.
//!
//! - Use `thumbv6m-none-eabi` for ARM Cortex-M0 and Cortex-M0+
//! - Use `thumbv7m-none-eabi` for ARM Cortex-M3
//! - Use `thumbv7em-none-eabi` for ARM Cortex-M4 and Cortex-M7 (*no* FPU support)
//! - Use `thumbv7em-none-eabihf` for ARM Cortex-M4**F** and Cortex-M7**F** (*with* FPU support)
//!
//! 1) Install the `rust-std` component for your target, if you haven't done so already
//!
//! ``` console
//! $ rustup target add thumbv7em-none-eabihf
//! ```
//!
//! 2) Clone this crate
//!
//! ``` text
//! $ cargo clone cortex-m-quickstart --vers 0.3.4
//! ```
//!
//! 3) 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"
//! ```
//!
//! 4) Specify the memory layout of the target device
//!
//! **NOTE** board support crates sometimes provide this file for you (check the crate
//! documentation). If you are using one that does then remove *both* `memory.x` and `build.rs` from
//! the root of this crate.
//!
//! ``` text
//! $ cat >memory.x <<'EOF'
//! MEMORY
//! {
//!   /* NOTE K = KiBi = 1024 bytes */
//!   FLASH : ORIGIN = 0x08000000, LENGTH = 256K
//!   RAM : ORIGIN = 0x20000000, LENGTH = 40K
//! }
//! EOF
//! ```
//!
//! 5) Optionally, set a default build target. This way you don't have to pass `--target` to each
//! Cargo invocation.
//!
//! ``` text
//! $ cat >>.cargo/config <<'EOF'
//! [build]
//! target = "thumbv7em-none-eabihf"
//! EOF
//! ```
//!
//! 6) Optionally, depend on a device, HAL implementation or a board support crate.
//!
//! ``` text
//! $ # add a device crate, OR
//! $ cargo add stm32f30x
//!
//! $ # add a HAL implementation crate, OR
//! $ cargo add stm32f30x-hal
//!
//! $ # add a board support crate
//! $ cargo add f3
//! ```
//!
//! 7) Write the application or start from one of the examples
//!
//! ``` text
//! $ rm -r src/* && cp examples/hello.rs src/main.rs
//! ```
//!
//! 8) Build the application
//!
//! ``` text
//! $ cargo build --release
//!
//! $ # sanity check
//! $ 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
//! ```
//!
//! 9) Flash and debug the program
//!
//! ``` text
//! $ # Launch OpenOCD on a terminal
//! $ openocd -f (..)
//! ```
//!
//! ``` text
//! $ # Start a debug session in another terminal
//! $ arm-none-eabi-gdb target/thumbv7em-none-eabihf/release/demo
//! ```
//!
//! Alternatively, you can use `cargo run` to build, flash and debug the program in a single step.
//!
//! ``` text
//! $ cargo run --example hello
//! > # drops you into a GDB session
//! ```
//!
//! # Examples
//!
//! Check the [examples module][examples]
//!
//! [examples]: ./examples/index.html
//!
//! # Troubleshooting
//!
//! This section contains fixes for common errors encountered when the
//! `cortex-m-quickstart` template is misused.
//!
//! ## Used the standard `main` interface
//!
//! Error message:
//!
//! ``` text
//! $ cargo build
//!    Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
//!
//! error: requires `start` lang_item
//! ```
//!
//! Solution: Use `#![no_main]` and `entry!` as shown in the [examples].
//!
//! ## 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
//! $ cargo build
//! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
//! error: linking with `rust-lld` failed: exit code: 1
//! |
//! = note: "rust-lld" "-flavor" "gnu" "-L" (..)
//! (..)
//!  = note: rust-lld: error: section '.vector_table' will not fit in region 'FLASH': overflowed by X bytes
//!          rust-lld: error: section '.vector_table' will not fit in region 'FLASH': overflowed by Y bytes
//! (..)
//! ```
//!
//! Solution: Specify your device memory layout in the `memory.x` linker script. See [Usage]
//! section.
//!
//! ## Didn't set a default build target and forgot to pass `--target` to Cargo
//!
//! Error message:
//!
//! ``` text
//! $ cargo build
//! (..)
//! error: language item required, but not found: `eh_personality`
//!
//! error: aborting due to previous error
//! ```
//!
//! Solution: Set a default build target in the `.cargo/config` file (see [Usage] section), or call
//! Cargo with `--target` flag: `cargo build --target thumbv7em-none-eabi`.
//!
//! ## Overwrote the original `.cargo/config` file
//!
//! You won't get an error message but the output binary will be empty
//!
//! ``` text
//! $ cargo build && echo OK
//! OK
//!
//! $ size target/thumbv7m-none-eabi/debug/app
//!    text    data     bss     dec     hex filename
//!       0       0       0       0       0 target/thumbv7m-none-eabi/debug/app
//! ```
//!
//! 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.
//!
//! ## Forgot to install the `rust-std` component
//!
//! Error message:
//!
//! ``` text
//! $ cargo build
//! error[E0463]: can't find crate for `core`
//!   |
//!   = note: the `thumbv7m-none-eabi` target may not be installed
//! ```
//!
//! Solution: call `rustup target add thumbv7m-none-eabi` but with the name of your target
//!
//! ## Used an old nightly
//!
//! 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 a more recent nightly
//!
//! ## Used the stable toolchain
//!
//! Error message:
//!
//! ``` text
//! $ cargo build
//! error[E0463]: can't find crate for `core`
//!   |
//!   = note: the `thumbv7em-none-eabihf` target may not be installed
//! ```
//!
//! Solution: We are not there yet! Switch to the nightly toolchain with `rustup default nightly`.
//!
//! ## 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/..`
//!
//! # Used a named piped for `itm.fifo`
//!
//! Error message:
//!
//! ``` text
//! $ cargo run [--example ..]
//!
//! Reading symbols from target/thumbv7em-none-eabihf/debug/cortex-m-quickstart...done.
//! cortex_m_rt::reset_handler ()
//!     at $REGISTRY/cortex-m-rt-0.3.12/src/lib.rs:330
//! 330     unsafe extern "C" fn reset_handler() -> ! {
//! semihosting is enabled
//! Ignoring packet error, continuing...
//! Ignoring packet error, continuing...
//! ```
//!
//! Note that when you reach this point OpenOCD will become unresponsive and you'll have to kill it
//! and start a new OpenOCD process before you can invoke `cargo run` / start GDB.
//!
//! Cause: You uncommented the `monitor tpiu ..` line in `.gdbinit` and are using a named pipe to
//! receive the ITM data (i.e. you ran `mkfifo itm.fifo`). This error occurs when `itmdump -f
//! itm.fifo` (or equivalent, e.g. `cat itm.fifo`) is not running.
//!
//! Solution: Run `itmdump -f itm.fifo` (or equivalently `cat itm.fifo`) *before* invoking `cargo
//! run` / starting GDB. Note that sometimes `itmdump` will exit when the GDB session ends. In that
//! case you'll have to run `itmdump` before you start the next GDB session.
//!
//! Alternative solution: Use a plain text file instead of a named pipe. In this scenario you omit
//! the `mkfifo itm.dump` command. You can use `itmdump`'s *follow* mode (-F) to get named pipe like
//! output.

#![no_std]

pub mod examples;