Initial commit

examples/crash.rs

+//! 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 <exception macros>: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<T>(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 <core::ptr::read_volatile+20>
+//!
+//! 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 cortex_m;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate panic_semihosting;
+extern crate stm32f40x;
+
+use core::ptr;
+
+use rt::ExceptionFrame;
+
+entry!(main);
+
+fn main() -> ! {
+    unsafe {
+        // read an address outside of the RAM region; causes a HardFault exception
+        ptr::read_volatile(0x2FFF_FFFF as *const u32);
+    }
+
+    loop {}
+}
+
+// define the hard fault handler
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/device.rs_no

+//! 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
+//!
+//! Device crates also provide an `interrupt!` macro (behind the "rt" feature) to register interrupt
+//! handlers.
+//!
+//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
+//!
+//! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
+//!
+//! ```
+//! $ edit Cargo.toml && tail $_
+//! [dependencies.stm32f103xx]
+//! features = ["rt"]
+//! version = "0.10.0"
+//! ```
+//!
+//! ---
+
+#![no_main]
+#![no_std]
+
+extern crate cortex_m;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+#[macro_use]
+extern crate stm32f103xx;
+extern crate panic_semihosting;
+
+use core::fmt::Write;
+
+use cortex_m::peripheral::syst::SystClkSource;
+use rt::ExceptionFrame;
+use sh::hio::{self, HStdout};
+use stm32f103xx::Interrupt;
+
+entry!(main);
+
+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.set_pending(Interrupt::EXTI0);
+    }
+}
+
+// try commenting out this line: you'll end in `default_handler` instead of in `exti0`
+interrupt!(EXTI0, exti0, state: Option<HStdout> = None);
+
+fn exti0(state: &mut Option<HStdout>) {
+    if state.is_none() {
+        *state = Some(hio::hstdout().unwrap());
+    }
+
+    if let Some(hstdout) = state.as_mut() {
+        hstdout.write_str(".").unwrap();
+    }
+}
+
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/exception.rs

+//! Overriding an exception handler
+//!
+//! You can override an exception handler using the [`exception!`][1] macro.
+//!
+//! [1]: https://docs.rs/cortex-m-rt/0.5.0/cortex_m_rt/macro.exception.html
+//!
+//! ---
+
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+extern crate cortex_m;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+extern crate panic_semihosting;
+extern crate stm32f40x;
+
+use core::fmt::Write;
+
+use cortex_m::peripheral::syst::SystClkSource;
+use cortex_m::Peripherals;
+use rt::ExceptionFrame;
+use sh::hio::{self, HStdout};
+
+entry!(main);
+
+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 {}
+}
+
+// try commenting out this line: you'll end in `default_handler` instead of in `sys_tick`
+exception!(SysTick, sys_tick, state: Option<HStdout> = None);
+
+fn sys_tick(state: &mut Option<HStdout>) {
+    if state.is_none() {
+        *state = Some(hio::hstdout().unwrap());
+    }
+
+    if let Some(hstdout) = state.as_mut() {
+        hstdout.write_str(".").unwrap();
+    }
+}
+
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/hello.rs

+//! Prints "Hello, world!" on the OpenOCD console using semihosting
+//!
+//! ---
+
+#![no_main]
+#![no_std]
+
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+extern crate panic_semihosting;
+// extern crate panic_abort;
+extern crate stm32f40x;
+
+use core::fmt::Write;
+
+use rt::ExceptionFrame;
+use sh::hio;
+
+entry!(main);
+
+fn main() -> ! {
+    let mut stdout = hio::hstdout().unwrap();
+    writeln!(stdout, "Hello, world!").unwrap();
+
+    panic!("panic");
+    loop {}
+
+    // panic!("panic");
+}
+
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/itm.rs

+//! 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]
+
+#[macro_use]
+extern crate cortex_m;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate panic_semihosting;
+extern crate stm32f40x;
+
+use cortex_m::{asm, Peripherals};
+use rt::ExceptionFrame;
+
+entry!(main);
+
+fn main() -> ! {
+    let mut p = Peripherals::take().unwrap();
+    let stim = &mut p.ITM.stim[0];
+
+    iprintln!(stim, "Hello, world!");
+
+    loop {
+        asm::bkpt();
+    }
+}
+
+// define the hard fault handler
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/minimal.rs

+//! Minimal Cortex-M program
+//!
+//! When executed this program will hit the breakpoint set in `main`.
+//!
+//! All Cortex-M programs need to:
+//!
+//! - Contain the `#![no_main]` and `#![no_std]` attributes. Embedded programs don't use the
+//! standard Rust `main` interface or the Rust standard (`std`) library.
+//!
+//! - Define their entry point using [`entry!`] macro.
+//!
+//! [`entry!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro.entry.html
+//!
+//! - Define their panicking behavior, i.e. what happens when `panic!` is called. The easiest way to
+//! define a panicking behavior is to link to a [panic handler crate][0]
+//!
+//! [0]: https://crates.io/keywords/panic-impl
+//!
+//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
+//! called when a hard fault exception is raised by the hardware.
+//!
+//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
+//!
+//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
+//! all interrupts and exceptions which have not been assigned a specific handler.
+
+#![no_main] // <- IMPORTANT!
+#![no_std]
+
+extern crate cortex_m;
+
+#[macro_use(entry, exception)]
+extern crate cortex_m_rt as rt;
+extern crate stm32f40x;
+
+// makes `panic!` print messages to the host stderr using semihosting
+// extern crate panic_semihosting;
+extern crate panic_abort;
+
+use cortex_m::asm;
+use rt::ExceptionFrame;
+
+// the program entry point is ...
+entry!(main);
+
+// ... this never ending function
+fn main() -> ! {
+    loop {
+        asm::bkpt();
+    }
+}
+
+// define the hard fault handler
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/panic.rs

+//! Changing the panic handler
+//!
+//! The easiest way to change the panic handler is to use a different [panic handler crate][0].
+//!
+//! [0]: https://crates.io/keywords/panic-impl
+//!
+//! ---
+
+#![no_main]
+#![no_std]
+
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate stm32f40x;
+
+// Pick one of these two panic handlers:
+
+// Reports panic messages to the host stderr using semihosting
+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 rt::ExceptionFrame;
+
+entry!(main);
+
+fn main() -> ! {
+    panic!("Oops")
+}
+
+// define the hard fault handler
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/standby.rs

+//! Minimal Cortex-M program
+//!
+//! When executed this program will hit the breakpoint set in `main`.
+//!
+//! All Cortex-M programs need to:
+//!
+//! - Contain the `#![no_main]` and `#![no_std]` attributes. Embedded programs don't use the
+//! standard Rust `main` interface or the Rust standard (`std`) library.
+//!
+//! - Define their entry point using [`entry!`] macro.
+//!
+//! [`entry!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro.entry.html
+//!
+//! - Define their panicking behavior, i.e. what happens when `panic!` is called. The easiest way to
+//! define a panicking behavior is to link to a [panic handler crate][0]
+//!
+//! [0]: https://crates.io/keywords/panic-impl
+//!
+//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
+//! called when a hard fault exception is raised by the hardware.
+//!
+//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
+//!
+//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
+//! all interrupts and exceptions which have not been assigned a specific handler.
+
+#![no_main] // <- IMPORTANT!
+#![no_std]
+
+extern crate cortex_m;
+extern crate stm32f40x;
+
+#[macro_use(entry, exception)]
+extern crate cortex_m_rt as rt;
+
+// makes `panic!` print messages to the host stderr using semihosting
+extern crate panic_semihosting;
+
+use cortex_m::asm;
+use rt::ExceptionFrame;
+
+// the program entry point is ...
+entry!(main);
+
+// ... this never ending function
+fn main() -> ! {
+    loop {
+        asm::wfi();
+        asm::bkpt();
+    }
+}
+
+// define the hard fault handler
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

memory.x

+MEMORY
+{
+  /* NOTE K = KiBi = 1024 bytes */
+  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
+  RAM : ORIGIN = 0x20000000, LENGTH = 40K
+}
+
+/* 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; */
+
+/* Size of the heap (in bytes) */
+/* _heap_size = 1024; */