Crate cortex_m_rt [] [src]

Minimal startup / runtime for Cortex-M microcontrollers

Features

This crate provides

  • Before main initialization of the .bss and .data sections.

  • Before main initialization of the FPU (for targets that have a FPU).

  • A panic_fmt implementation that just calls abort that you can opt into through the "abort-on-panic" Cargo feature. If you don't use this feature you'll have to provide the panic_fmt lang item yourself. Documentation here

  • A minimal start lang item to support the standard fn main() interface. (The processor goes to sleep (loop { asm!("wfi") }) after returning from main)

  • A linker script that encodes the memory layout of a generic Cortex-M microcontroller. This linker script is missing some information that must be supplied through a memory.x file (see example below).

  • A default exception handler tailored for debugging that lets you inspect what was the state of the processor at the time of the exception. By default, all exceptions are serviced by this handler but each exception can be individually overridden using the exception! macro. The default exception handler itself can also be overridden using the default_handler! macro.

  • A _sheap symbol at whose address you can locate a heap.

  • Zero cost stack overflow protection when using the cortex-m-rt-ld linker.

Example

Creating a new bare metal project. (I recommend you use the cortex-m-quickstart template as it takes of all the boilerplate shown here)

$ cargo new --bin app && cd $_

$ # add this crate as a dependency
$ $EDITOR Cargo.toml && tail $_
[dependencies.cortex-m-rt]
features = ["abort-on-panic"]
version = "0.3.0"

$ # tell Xargo which standard crates to build
$ $EDITOR Xargo.toml && cat $_
[dependencies.core]
stage = 0

[dependencies.compiler_builtins]
features = ["mem"]
stage = 1

$ # memory layout of the device
$ $EDITOR memory.x && cat $_
MEMORY
{
  /* NOTE K = KiBi = 1024 bytes */
  FLASH : ORIGIN = 0x08000000, LENGTH = 128K
  RAM : ORIGIN = 0x20000000, LENGTH = 8K
}

$ $EDITOR src/main.rs && cat $_
Be careful when using this code, it's not being tested!
#![feature(used)]
#![no_std]

extern crate cortex_m_rt;

fn main() {
    // do something here
}

// As we are not using interrupts, we just register a dummy catch all
// handler
#[link_section = ".vector_table.interrupts"]
#[used]
static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];

extern "C" fn default_handler() {
    loop {}
}
$ cargo install xargo

$ xargo rustc --target thumbv7m-none-eabi -- \
      -C link-arg=-Tlink.x -C linker=arm-none-eabi-ld -Z linker-flavor=ld

$ arm-none-eabi-objdump -Cd $(find target -name app) | head

Disassembly of section .text:

08000400 <cortex_m_rt::reset_handler>:
 8000400:       b580            push    {r7, lr}
 8000402:       466f            mov     r7, sp
 8000404:       b084            sub     sp, #8


$ arm-none-eabi-size -Ax $(find target -name app) | head
target/thumbv7m-none-eabi/debug/app  :
section                size         addr
.vector_table         0x400    0x8000000
.text                 0x24a    0x8000400
.rodata                 0x0    0x800064c
.stack               0x2000   0x20000000
.bss                    0x0   0x20000000
.data                   0x0   0x20000000

Zero cost stack overflow protection

Consider the following variation of the previous program:

Be careful when using this code, it's not being tested!
extern crate cortex_m_rt;

const N: usize = 256;
static mut XS: [u32; N] = [0; N];

fn main() {
    #[inline(never)]
    fn fib(n: u32) -> u32 {
        unsafe { assert!(XS.iter().all(|x| *x == 0)) }

        if n < 2 {
            1
        } else {
            fib(n - 1) + fib(n - 2)
        }
    }

    let x = fib(400);
    unsafe { *XS.iter_mut().first().unwrap() = x }
}

This program allocates a 1KB array in .bss, recursively computes the 400th fibonacci number and stores the result in the head of the array. This program will hit a stack overflow at runtime because there's not enough memory to recursively call the fib function so many times.

If you inspect the program using GDB you'll see that the assertion failed after fib was nested around 300 times.

> continue
Program received signal SIGTRAP, Trace/breakpoint trap.

> backtrace
#0  0x08000516 in cortex_m_rt::default_handler ()
#1  <signal handler called>
#2  0x0800050a in rust_begin_unwind ()
#3  0x08000586 in core::panicking::panic_fmt ()
#4  0x0800055c in core::panicking::panic ()
#5  0x080004f6 in app::main::fib ()
#6  0x080004a0 in app::main::fib ()
(..)
#301 0x080004a0 in app::main::fib ()
#302 0x080004a0 in app::main::fib ()
#303 0x08000472 in app::main ()
#304 0x08000512 in cortex_m_rt::lang_items::start ()
#305 0x08000460 in cortex_m_rt::reset_handler ()

What this means is that the stack grew so much that it crashed into the .bss section and overwrote the memory in there. Continuing the GDB session you can confirm that the XS variable has been modified:

> x/4 0x20000000 # start of .bss
0x20000000 <app::XS>:   0x00000000      0x00000000      0x00000000      0x00000000

> x/4 0x200003f0 # end of .bss
0x200003f0 <app::XS+1008>:      0x20000400      0x080004f5      0x00000000      0x00000001

The problem is that the stack is growing towards the .bss section and both sections overlap as shown below:

$ arm-none-eabi-size -Ax $(find target -name app)
section             size         addr
.vector_table      0x400    0x8000000
.text              0x186    0x8000400
.rodata             0x50    0x8000590
.stack            0x2000   0x20000000
.bss               0x400   0x20000000
.data                0x0   0x20000400

Graphically the RAM sections look like this:

Stack overflow

To prevent memory corruption due to stack overflows in this scenario it suffices to switch the sections so that the .bss section is near the end of the RAM region and the .stack comes before .bss, at a lower address.

To swap the sections you can use the cortex-m-rt-ld linker to link the program.

$ cargo install cortex-m-rt-ld

$ xargo rustc --target thumbv7m-none-eabi -- \
      -C link-arg=-Tlink.x -C linker=cortex-m-rt-ld -Z linker-flavor=ld

Now you get non overlapping linker sections:

section             size         addr
.vector_table      0x400    0x8000000
.text              0x186    0x8000400
.rodata             0x50    0x8000590
.stack            0x1c00   0x20000000
.bss               0x400   0x20001c00
.data                0x0   0x20002000

Note that the .stack section is smaller now. Graphically, the memory layout now looks like this:

Swapped sections

On stack overflows .stack will hit the lower boundary of the RAM region raising a hard fault exception, instead of silently corrupting the .bss section.

You can confirm this by inspecting the program in GDB.

> continue
Program received signal SIGTRAP, Trace/breakpoint trap.

> p $sp
$1 = (void *) 0x1ffffff0

The failure mode this time was the .stack crashing into the RAM boundary. The variable XS is unaffected this time:

> x/4x app::XS
0x20001c00 <app::XS>:   0x00000000      0x00000000      0x00000000      0x00000000

> x/4x app::XS+252
0x20001ff0 <app::XS+1008>:      0x00000000      0x00000000      0x00000000      0x00000000

.heap

If your program makes use of a .heap section a similar problem can occur:

Memory layout when `.heap` exists

The .stack can crash into the .heap, or vice versa, and you'll also get memory corruption.

cortex-m-rt-ld can also be used in this case but the size of the .heap section must be specified via the _heap_size symbol in memory.x, or in any other linker script.

$ $EDITOR memory.x && tail -n1 $_
_heap_size = 0x400;
$ xargo rustc --target thumbv7m-none-eabi -- \
      -C link-arg=-Tlink.x -C linker=cortex-m-rt-ld -Z linker-flavor=ld

$ arm-none-eabi-size -Ax $(find target -name app) | head
section                 size         addr
.vector_table          0x400    0x8000000
.text                  0x1a8    0x8000400
.rodata                 0x50    0x80005b0
.stack                0x1800   0x20000000
.bss                   0x400   0x20001800
.data                    0x0   0x20001c00
.heap                  0x400   0x20001c00

Graphically the memory layout looks like this:

Swapped sections when `.heap` exists

Now both stack overflows and dynamic memory over-allocations (OOM) will generate hard fault exceptions, instead of running into each other.

Symbol interfaces

This crate makes heavy use of symbols, linker sections and linker scripts to provide most of its functionality. Below are described the main symbol interfaces.

DEFAULT_HANDLER

This weak symbol can be overridden to override the default exception handler that this crate provides. It's recommended that you use the default_handler! to do the override, but below is shown how to manually override the symbol:

Be careful when using this code, it's not being tested!
#[no_mangle]
pub extern "C" fn DEFAULT_HANDLER() {
    // do something here
}

.vector_table.interrupts

This linker section is used to register interrupt handlers in the vector table. The recommended way to use this section is to populate it, once, with an array of weak functions that just call the DEFAULT_HANDLER symbol. Then the user can override them by name.

Example

Populating the vector table

Be careful when using this code, it's not being tested!
// Number of interrupts the device has
const N: usize = 60;

// Default interrupt handler that just calls the `DEFAULT_HANDLER`
#[linkage = "weak"]
#[naked]
#[no_mangle]
extern "C" fn WWDG() {
    unsafe {
        asm!("b DEFAULT_HANDLER" :::: "volatile");
        core::intrinsics::unreachable();
    }
}

// You need one function per interrupt handler
#[linkage = "weak"]
#[naked]
#[no_mangle]
extern "C" fn WWDG() {
    unsafe {
        asm!("b DEFAULT_HANDLER" :::: "volatile");
        core::intrinsics::unreachable();
    }
}

// ..

// Use `None` for reserved spots in the vector table
#[link_section = ".vector_table.interrupts"]
#[no_mangle]
#[used]
static INTERRUPTS: [Option<extern "C" fn()>; N] = [
    Some(WWDG),
    Some(PVD),
    // ..
];

Overriding an interrupt (this can be in a different crate)

Be careful when using this code, it's not being tested!
// the name must match the name of one of the weak functions used to
// populate the vector table.
#[no_mangle]
pub extern "C" fn WWDG() {
    // do something here
}

memory.x

This file supplies the information about the device to the linker.

MEMORY

The main information that this file must provide is the memory layout of the device in the form of the MEMORY command. The command is documented here, but at a minimum you'll want to create two memory regions: one for Flash memory and another for RAM.

The program instructions (the .text section) will be stored in the memory region named FLASH, and the program static variables (the sections .bss and .data) will be allocated in the memory region named RAM.

_stack_start

This symbol provides the address at which the call stack will be allocated. The call stack grows downwards so this address is usually set to the highest valid RAM address plus one (this is an invalid address but the processor will decrement the stack pointer before using its value as an address).

If omitted this symbol value will default to ORIGIN(RAM) + LENGTH(RAM).

Example

Allocating the call stack on a different RAM region.

Be careful when using this code, it's not being tested!
MEMORY
{
  /* call stack will go here */
  CCRAM : ORIGIN = 0x10000000, LENGTH = 8K
  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
  /* static variables will go here */
  RAM : ORIGIN = 0x20000000, LENGTH = 40K
}

_stack_start = ORIGIN(CCRAM) + LENGTH(CCRAM);

_heap_size

The size of the .heap section. Only meaningful when using cortex-m-rt-ld.

_stext

This symbol indicates where the .text section will be located. If not specified in the memory.x file it will default to right after the vector table -- the vector table is always located at the start of the FLASH region.

The main use of this symbol is leaving some space between the vector table and the .text section unused. This is required on some microcontrollers that store some configuration information right after the vector table.

Example

Locate the .text section 1024 bytes after the start of the FLASH region.

Be careful when using this code, it's not being tested!
_stext = ORIGIN(FLASH) + 0x400;

_sheap

This symbol is located in RAM right after the .bss and .data sections. You can use the address of this symbol as the start address of a heap region. This symbol is 4 byte aligned so that address will be a multiple of 4.

Example

Be careful when using this code, it's not being tested!
extern crate some_allocator;

// Size of the heap in bytes
const SIZE: usize = 1024;

extern "C" {
    static mut _sheap: u8;
}

fn main() {
    unsafe {
        let start_address = &mut _sheap as *mut u8;
        some_allocator::initialize(start_address, SIZE);
    }
}

NOTE if you are using cortex-m-rt-ld and/or have defined the _heap_size symbol then you should use the address of the _eheap to compute the size of the .heap section, instead of duplicating the value that you wrote in memory.x.

Macros

default_handler

This macro lets you override the default exception handler

exception

Assigns a handler to an exception