jazzpi/embedded-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

use published versions, doc up, update CHANGELOG

Browse Source
This commit is contained in:
Jorge Aparicio
2018-05-12 20:41:42 +02:00
parent 3a4a5be709
commit 0f139c386b
24 changed files with 548 additions and 555 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
examples/allocator.rs
View File

@@ -11,6 +11,7 @@
#![feature(alloc)]
#![feature(global_allocator)]
#![feature(lang_items)]
#![no_main]
#![no_std]
@@ -22,7 +23,7 @@ extern crate cortex_m;
#[macro_use]
extern crate cortex_m_rt as rt;
extern crate cortex_m_semihosting as sh;
extern crate panic_abort;
extern crate panic_semihosting;
use core::fmt::Write;
@@ -31,15 +32,16 @@ use cortex_m::asm;
use rt::ExceptionFrame;
use sh::hio;
// this is the allocator the application will use
#[global_allocator]
static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
const HEAP_SIZE: usize = 1024; // in bytes
main!(main);
entry!(main);
fn main() -> ! {
// Initialize the allocator
// Initialize the allocator BEFORE you use it
unsafe { ALLOCATOR.init(rt::heap_start() as usize, HEAP_SIZE) }
// Growable array allocated on the heap
@@ -51,20 +53,23 @@ fn main() -> ! {
loop {}
}
exception!(DefaultHandler, dh);
#[inline(always)]
fn dh(_nr: u8) {
asm::bkpt();
}
exception!(HardFault, hf);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
// define what happens in an Out Of Memory (OOM) condition
#[lang = "oom"]
#[no_mangle]
pub fn rust_oom() -> ! {
asm::bkpt();
loop {}
}
interrupts!(DefaultHandler);
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);
}

129
examples/crash.rs
View File

@@ -1,11 +1,12 @@
//! Debugging a crash (exception)
//!
//! The `cortex-m-rt` crate provides functionality for this through a default exception handler.
//! When an exception is hit, the default handler will trigger a breakpoint and in this debugging
//! context the stacked registers are accessible.
//! 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.
//!
//! In you run the example below, you'll be able to inspect the state of your program under the
//! debugger using these commands:
//! 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
@@ -13,59 +14,66 @@
//! __bkpt () at asm/bkpt.s:3
//! 3 bkpt
//!
//! (gdb) finish
//! Run till exit from #0 __bkpt () at asm/bkpt.s:3
//! Note: automatically using hardware breakpoints for read-only addresses.
//! crash::hf (_ef=0x20004fa0) at examples/crash.rs:102
//! 99 asm::bkpt();
//!
//! (gdb) # Exception frame = program state during the crash
//! (gdb) print/x *_ef
//! $1 = cortex_m_rt::ExceptionFrame {
//! r0: 0x2fffffff,
//! r1: 0x2fffffff,
//! r2: 0x80006b0,
//! r3: 0x80006b0,
//! r12: 0x20000000,
//! lr: 0x800040f,
//! pc: 0x800066a,
//! xpsr: 0x61000000
//! }
//!
//! (gdb) # Where did we come from?
//! (gdb) backtrace
//! #0 crash::hf (_ef=0x20004fa0) at examples/crash.rs:102
//! #1 0x080004ac in UserHardFault (ef=0x20004fa0) at <exception macros>:9
//! #2 <signal handler called>
//! #3 0x0800066a in core::ptr::read_volatile (src=0x2fffffff) at /checkout/src/libcore/ptr.rs:452
//! #4 0x0800040e in crash::main () at examples/crash.rs:85
//! #5 0x08000456 in main () at <main macros>:3
//! #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?)
//! ```
//!
//! (gdb) # Nail down the location of the crash
//! (gdb) disassemble/m _ef.pc
//! 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 {}
//! 0x08000662 <+0>: sub sp, #16
//! 0x08000664 <+2>: mov r1, r0
//! 0x08000666 <+4>: str r0, [sp, #8]
//! 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)
//! 0x08000668 <+6>: ldr r0, [sp, #8]
//! 0x0800066a <+8>: ldr r0, [r0, #0]
//! 0x0800066c <+10>: str r0, [sp, #12]
//! 0x0800066e <+12>: ldr r0, [sp, #12]
//! 0x08000670 <+14>: str r1, [sp, #4]
//! 0x08000672 <+16>: str r0, [sp, #0]
//! 0x08000674 <+18>: b.n 0x8000676 <core::ptr::read_volatile+20>
//! 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 }
//! 0x08000676 <+20>: ldr r0, [sp, #0]
//! 0x08000678 <+22>: add sp, #16
//! 0x0800067a <+24>: bx lr
//! 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]
@@ -74,38 +82,33 @@
extern crate cortex_m;
#[macro_use]
extern crate cortex_m_rt as rt;
extern crate panic_abort;
extern crate panic_semihosting;
use core::ptr;
use cortex_m::asm;
use rt::ExceptionFrame;
main!(main);
entry!(main);
#[inline(always)]
fn main() -> ! {
unsafe {
// read an address outside of the RAM region; causes a HardFault exception
ptr::read_volatile(0x2FFF_FFFF as *const u32);
}
loop {}
}
exception!(DefaultHandler, dh);
// define the hard fault handler
exception!(HardFault, hard_fault);
#[inline(always)]
fn dh(_nr: u8) {
asm::bkpt();
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
exception!(HardFault, hf);
// define the default exception handler
exception!(*, default_handler);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}
interrupts!(DefaultHandler);

30
examples/device.rs
View File

@@ -1,6 +1,6 @@
//! Using a device crate
//!
//! Crates generated using [`svd2rust`] are referred to as device crates. These crates provides an
//! 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
@@ -19,9 +19,6 @@
//! version = "0.10.0"
//! ```
//!
//! The `stm32f103xx` crate provides an `interrupts.x` file so you must remove the one in the root
//! of this crate.
//!
//! ---
#![no_main]
@@ -33,17 +30,16 @@ extern crate cortex_m_rt as rt;
extern crate cortex_m_semihosting as sh;
#[macro_use]
extern crate stm32f103xx;
extern crate panic_abort;
extern crate panic_semihosting;
use core::fmt::Write;
use cortex_m::asm;
use cortex_m::peripheral::syst::SystClkSource;
use rt::ExceptionFrame;
use sh::hio::{self, HStdout};
use stm32f103xx::Interrupt;
main!(main);
entry!(main);
fn main() -> ! {
let p = cortex_m::Peripherals::take().unwrap();
@@ -53,6 +49,7 @@ fn main() -> ! {
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();
@@ -66,6 +63,7 @@ fn main() -> ! {
}
}
// 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>) {
@@ -78,20 +76,14 @@ fn exti0(state: &mut Option<HStdout>) {
}
}
exception!(DefaultHandler, deh);
exception!(HardFault, hard_fault);
#[inline(always)]
fn deh(_nr: u8) {
asm::bkpt();
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
exception!(HardFault, hf);
exception!(*, default_handler);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}
interrupts!(DefaultHandler);

29
examples/exception.rs
View File

@@ -14,30 +14,31 @@ extern crate cortex_m;
#[macro_use]
extern crate cortex_m_rt as rt;
extern crate cortex_m_semihosting as sh;
extern crate panic_abort;
extern crate panic_semihosting;
use core::fmt::Write;
use cortex_m::peripheral::syst::SystClkSource;
use cortex_m::{asm, Peripherals};
use cortex_m::Peripherals;
use rt::ExceptionFrame;
use sh::hio::{self, HStdout};
main!(main);
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); // 1s
syst.set_reload(8_000_000); // period = 1s
syst.enable_counter();
syst.enable_interrupt();
loop {}
}
// try commenting out this line: you'll end in `deh` instead of in `sys_tick`
// 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>) {
@@ -50,20 +51,14 @@ fn sys_tick(state: &mut Option<HStdout>) {
}
}
exception!(DefaultHandler, deh);
exception!(HardFault, hard_fault);
#[inline(always)]
fn deh(_nr: u8) {
asm::bkpt();
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
exception!(HardFault, hf);
exception!(*, default_handler);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}
interrupts!(DefaultHandler);

25
examples/hello.rs
View File

@@ -5,19 +5,17 @@
#![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_abort;
extern crate panic_semihosting;
use core::fmt::Write;
use cortex_m::asm;
use rt::ExceptionFrame;
use sh::hio;
main!(main);
entry!(main);
fn main() -> ! {
let mut stdout = hio::hstdout().unwrap();
@@ -26,21 +24,14 @@ fn main() -> ! {
loop {}
}
exception!(DefaultHandler, dh);
exception!(HardFault, hard_fault);
#[inline(always)]
fn dh(_nr: u8) {
asm::bkpt();
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
exception!(HardFault, hf);
exception!(*, default_handler);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}
// As we are not using interrupts, we just bind them all to the `DefaultHandler` exception handler
interrupts!(DefaultHandler);

39
examples/itm.rs
View File

@@ -1,11 +1,13 @@
//! Sends "Hello, world!" through the ITM port 0
//!
//! **IMPORTANT** Not all Cortex-M chips 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.
//!
//! ITM is much faster than semihosting. Like 4 orders of magnitude or so.
//!
//! You'll need [`itmdump`] to receive the message on the host plus you'll need to uncomment the
//! **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/
@@ -19,37 +21,34 @@
extern crate cortex_m;
#[macro_use]
extern crate cortex_m_rt as rt;
extern crate panic_abort; // panicking behavior
extern crate panic_semihosting;
use cortex_m::{asm, Peripherals};
use rt::ExceptionFrame;
main!(main);
entry!(main);
#[inline(always)]
fn main() -> ! {
let mut p = Peripherals::take().unwrap();
let stim = &mut p.ITM.stim[0];
iprintln!(stim, "Hello, world!");
loop {}
loop {
asm::bkpt();
}
}
exception!(DefaultHandler, dh);
// define the hard fault handler
exception!(HardFault, hard_fault);
#[inline(always)]
fn dh(_nr: u8) {
asm::bkpt();
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
exception!(HardFault, hf);
// define the default exception handler
exception!(*, default_handler);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}
interrupts!(DefaultHandler);

65
examples/minimal.rs
View File

@@ -1,66 +1,63 @@
//! 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 `main!`. The entry point doesn't need to be called `main` and
//! it doesn't need to be in the root of the crate.
//! - 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 implementation crate][0]
//! define a panicking behavior is to link to a [panic handler crate][0]
//!
//! [0]: https://crates.io/keywords/panic-impl
//!
//! - Define the `HardFault` handler. This function is called when a hard fault exception is raised
//! by the hardware.
//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
//! called when a hard fault exception is raised by the hardware.
//!
//! - Define a default handler. This function will be used to handle all interrupts and exceptions
//! which have not been assigned a specific handler.
//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
//!
//! - Define the device specific interrupt handlers. `interrupts!` can be used to create a generic
//! program that works for all Cortex-M devices by binding all the possible interrupt handlers to
//! the `DefaultHandler`.
//! - 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(main, exception, interrupts)]
#[macro_use(entry, exception)]
extern crate cortex_m_rt as rt;
extern crate panic_abort; // panicking behavior
// 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
main!(main);
// the program entry point is ...
entry!(main);
#[inline(always)]
// ... this never ending function
fn main() -> ! {
asm::bkpt();
loop {}
}
// define the default exception handler
exception!(DefaultHandler, deh);
#[inline(always)]
fn deh(_nr: u8) {
asm::bkpt();
loop {
asm::bkpt();
}
}
// define the hard fault handler
exception!(HardFault, hf);
exception!(HardFault, hard_fault);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
// bind all interrupts to the default exception handler
interrupts!(DefaultHandler);
// define the default exception handler
exception!(*, default_handler);
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}

38
examples/panic.rs
View File

@@ -1,7 +1,6 @@
//! Changing the panic handler
//!
//! The easiest way to change the panic handler is to use a different [panic implementation
//! crate][0].
//! The easiest way to change the panic handler is to use a different [panic handler crate][0].
//!
//! [0]: https://crates.io/keywords/panic-impl
//!
@@ -10,36 +9,35 @@
#![no_main]
#![no_std]
extern crate cortex_m;
#[macro_use]
extern crate cortex_m_rt as rt;
// extern crate panic_abort;
extern crate panic_semihosting; // reports panic messages to the host stderr using semihosting
use cortex_m::asm;
// 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)
// extern crate panic_itm;
use rt::ExceptionFrame;
main!(main);
entry!(main);
#[inline(always)]
fn main() -> ! {
panic!("Oops")
}
exception!(DefaultHandler, deh);
// define the hard fault handler
exception!(HardFault, hard_fault);
#[inline(always)]
fn deh(_nr: u8) {
asm::bkpt();
fn hard_fault(ef: &ExceptionFrame) -> ! {
panic!("HardFault at {:#?}", ef);
}
exception!(HardFault, hf);
// define the default exception handler
exception!(*, default_handler);
#[inline(always)]
fn hf(_ef: &ExceptionFrame) -> ! {
asm::bkpt();
loop {}
fn default_handler(irqn: i16) {
panic!("Unhandled exception (IRQn = {})", irqn);
}
interrupts!(DefaultHandler);