Crate cortex_m_rt[−][src]

Expand description

Startup code and minimal runtime for Cortex-M microcontrollers

This crate contains all the required parts to build a no_std application (binary crate) that targets a Cortex-M microcontroller.

Features

This crates takes care of:

  • The memory layout of the program. In particular, it populates the vector table so the device can boot correctly, and properly dispatch exceptions and interrupts.

  • Initializing static variables before the program entry point.

  • Enabling the FPU before the program entry point if the target is thumbv7em-none-eabihf.

This crate also provides the following attributes:

  • #[entry] to declare the entry point of the program
  • #[exception] to override an exception handler. If not overridden all exception handlers default to an infinite loop.
  • #[pre_init] to run code before static variables are initialized

This crate also implements a related attribute called #[interrupt], which allows you to define interrupt handlers. However, since which interrupts are available depends on the microcontroller in use, this attribute should be re-exported and used from a device crate.

The documentation for these attributes can be found in the Attribute Macros section.

Requirements

memory.x

This crate expects the user, or some other crate, to provide the memory layout of the target device via a linker script named memory.x. This section covers the contents of memory.x The memory.x file is used by during linking by the link.x script provided by this crate.

MEMORY

The linker script must specify the memory available in the device as, at least, two MEMORY regions: one named FLASH and one named RAM. The .text and .rodata sections of the program will be placed in the FLASH region, whereas the .bss and .data sections, as well as the heap,will be placed in the RAM region.

/* Linker script for the STM32F103C8T6 */
MEMORY
{
  FLASH : ORIGIN = 0x08000000, LENGTH = 64K
  RAM : ORIGIN = 0x20000000, LENGTH = 20K
}

_stack_start

This optional symbol can be used to indicate where the call stack of the program should be placed. If this symbol is not used then the stack will be placed at the end of the RAM region – the stack grows downwards towards smaller address. This symbol can be used to place the stack in a different memory region, for example:

/* Linker script for the STM32F303VCT6 */
MEMORY
{
    FLASH : ORIGIN = 0x08000000, LENGTH = 256K

    /* .bss, .data and the heap go in this region */
    RAM : ORIGIN = 0x20000000, LENGTH = 40K

    /* Core coupled (faster) RAM dedicated to hold the stack */
    CCRAM : ORIGIN = 0x10000000, LENGTH = 8K
}

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

_stext

This optional symbol can be used to control where the .text section is placed. If omitted the .text section will be placed right after the vector table, which is placed at the beginning of FLASH. Some devices store settings like Flash configuration right after the vector table; for these devices one must place the .text section after this configuration section – _stext can be used for this purpose.

MEMORY
{
  /* .. */
}

/* The device stores Flash configuration in 0x400-0x40C so we place .text after that */
_stext = ORIGIN(FLASH) + 0x40C

An example

This section presents a minimal application built on top of cortex-m-rt. Apart from the mandatory memory.x linker script describing the memory layout of the device, the hard fault handler and the default exception handler must also be defined somewhere in the dependency graph (see [#[exception]]). In this example we define them in the binary crate:

// IMPORTANT the standard `main` interface is not used because it requires nightly
#![no_main]
#![no_std]

// Some panic handler needs to be included. This one halts the processor on panic.
extern crate panic_halt;

use cortex_m_rt::entry;

// use `main` as the entry point of this application
// `main` is not allowed to return
#[entry]
fn main() -> ! {
    // initialization

    loop {
        // application logic
    }
}

To actually build this program you need to place a memory.x linker script somewhere the linker can find it, e.g. in the current directory; and then link the program using cortex-m-rt’s linker script: link.x. The required steps are shown below:

$ cat > memory.x <<EOF
/* Linker script for the STM32F103C8T6 */
MEMORY
{
  FLASH : ORIGIN = 0x08000000, LENGTH = 64K
  RAM : ORIGIN = 0x20000000, LENGTH = 20K
}
EOF

$ cargo rustc --target thumbv7m-none-eabi -- \
      -C link-arg=-nostartfiles -C link-arg=-Tlink.x

$ file target/thumbv7m-none-eabi/debug/app
app: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, (..)

Optional features

device

If this feature is disabled then this crate populates the whole vector table. All the interrupts in the vector table, even the ones unused by the target device, will be bound to the default exception handler. This makes the final application device agnostic: you will be able to run it on any Cortex-M device – provided that you correctly specified its memory layout in memory.x – without hitting undefined behavior.

If this feature is enabled then the interrupts section of the vector table is left unpopulated and some other crate, or the user, will have to populate it. This mode is meant to be used in conjunction with crates generated using svd2rust. Those device crates will populate the missing part of the vector table when their "rt" feature is enabled.

Inspection

This section covers how to inspect a binary that builds on top of cortex-m-rt.

Sections (size)

cortex-m-rt uses standard sections like .text, .rodata, .bss and .data as one would expect. cortex-m-rt separates the vector table in its own section, named .vector_table. This lets you distinguish how much space is taking the vector table in Flash vs how much is being used by actual instructions (.text) and constants (.rodata).

$ size -Ax target/thumbv7m-none-eabi/examples/app
target/thumbv7m-none-eabi/release/examples/app  :
section             size         addr
.vector_table      0x400    0x8000000
.text               0x88    0x8000400
.rodata              0x0    0x8000488
.data                0x0   0x20000000
.bss                 0x0   0x20000000

Without the -A argument size reports the sum of the sizes of .text, .rodata and .vector_table under “text”.

$ size target/thumbv7m-none-eabi/examples/app
  text    data     bss     dec     hex filename
  1160       0       0    1660     67c target/thumbv7m-none-eabi/release/app

Symbols (objdump, nm)

One will always find the following (unmangled) symbols in cortex-m-rt applications:

  • Reset. This is the reset handler. The microcontroller will execute this function upon booting. This function will call the user program entry point (cf. #[entry]) using the main symbol so you will also find that symbol in your program.

  • DefaultHandler. This is the default handler. If not overridden using #[exception] fn DefaultHandler(.. this will be an infinite loop.

  • HardFaultTrampoline. This is the real hard fault handler. This function is simply a trampoline that jumps into the user defined hard fault handler named HardFault. The trampoline is required to set up the pointer to the stacked exception frame.

  • HardFault. This is the user defined hard fault handler. If not overridden using #[exception] fn HardFault(.. it will default to an infinite loop.

  • __STACK_START. This is the first entry in the .vector_table section. This symbol contains the initial value of the stack pointer; this is where the stack will be located – the stack grows downwards towards smaller addresses.

  • __RESET_VECTOR. This is the reset vector, a pointer to the Reset function. This vector is located in the .vector_table section after __STACK_START.

  • __EXCEPTIONS. This is the core exceptions portion of the vector table; it’s an array of 14 exception vectors, which includes exceptions like HardFault and SysTick. This array is located after __RESET_VECTOR in the .vector_table section.

  • __INTERRUPTS. This is the device specific interrupt portion of the vector table; its exact size depends on the target device but if the "device" feature has not been enabled it will have a size of 32 vectors (on ARMv6-M) or 240 vectors (on ARMv7-M). This array is located after __EXCEPTIONS in the .vector_table section.

  • __pre_init. This is a function to be run before RAM is initialized. It defaults to an empty function. The function called can be changed by applying the #[pre_init] attribute to a function.

If you override any exception handler you’ll find it as an unmangled symbol, e.g. SysTick or SVCall, in the output of objdump,

Advanced usage

Setting the program entry point

This section describes how #[entry] is implemented. This information is useful to developers who want to provide an alternative to #[entry] that provides extra guarantees.

The Reset handler will call a symbol named main (unmangled) after initializing .bss and .data, and enabling the FPU (if the target has an FPU). A function with the entry attribute will be set to have the export name “main”; in addition, its mutable statics are turned into safe mutable references (see #[entry] for details).

The unmangled main symbol must have signature extern "C" fn() -> ! or its invocation from Reset will result in undefined behavior.

Incorporating device specific interrupts

This section covers how an external crate can insert device specific interrupt handlers into the vector table. Most users don’t need to concern themselves with these details, but if you are interested in how device crates generated using svd2rust integrate with cortex-m-rt read on.

The information in this section applies when the "device" feature has been enabled.

__INTERRUPTS

The external crate must provide the interrupts portion of the vector table via a static variable named__INTERRUPTS (unmangled) that must be placed in the .vector_table.interrupts section of its object file.

This static variable will be placed at ORIGIN(FLASH) + 0x40. This address corresponds to the spot where IRQ0 (IRQ number 0) is located.

To conform to the Cortex-M ABI __INTERRUPTS must be an array of function pointers; some spots in this array may need to be set to 0 if they are marked as reserved in the data sheet / reference manual. We recommend using a union to set the reserved spots to 0; None (Option<fn()>) may also work but it’s not guaranteed that the None variant will always be represented by the value 0.

Let’s illustrate with an artificial example where a device only has two interrupt: Foo, with IRQ number = 2, and Bar, with IRQ number = 4.

pub union Vector {
    handler: unsafe extern "C" fn(),
    reserved: usize,
}

extern "C" {
    fn Foo();
    fn Bar();
}

#[link_section = ".vector_table.interrupts"]
#[no_mangle]
pub static __INTERRUPTS: [Vector; 5] = [
    // 0-1: Reserved
    Vector { reserved: 0 },
    Vector { reserved: 0 },

    // 2: Foo
    Vector { handler: Foo },

    // 3: Reserved
    Vector { reserved: 0 },

    // 4: Bar
    Vector { handler: Bar },
];

device.x

Linking in __INTERRUPTS creates a bunch of undefined references. If the user doesn’t set a handler for all the device specific interrupts then linking will fail with "undefined reference" errors.

We want to provide a default handler for all the interrupts while still letting the user individually override each interrupt handler. In C projects, this is usually accomplished using weak aliases declared in external assembly files. In Rust, we could achieve something similar using global_asm!, but that’s an unstable feature.

A solution that doesn’t require global_asm! or external assembly files is to use the PROVIDE command in a linker script to create the weak aliases. This is the approach that cortex-m-rt uses; when the "device" feature is enabled cortex-m-rt’s linker script (link.x) depends on a linker script named device.x. The crate that provides __INTERRUPTS must also provide this file.

For our running example the device.x linker script looks like this:

/* device.x */
PROVIDE(Foo = DefaultHandler);
PROVIDE(Bar = DefaultHandler);

This weakly aliases both Foo and Bar. DefaultHandler is the default exception handler and that the core exceptions use unless overridden.

Because this linker script is provided by a dependency of the final application the dependency must contain build script that puts device.x somewhere the linker can find. An example of such build script is shown below:

ⓘ
use std::env;
use std::fs::File;
use std::io::Write;
use std::path::PathBuf;

fn main() {
    // Put the linker script somewhere the linker can find it
    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
    File::create(out.join("device.x"))
        .unwrap()
        .write_all(include_bytes!("device.x"))
        .unwrap();
    println!("cargo:rustc-link-search={}", out.display());
}

Uninitialized static variables

The .uninit linker section can be used to leave static mut variables uninitialized. One use case of unitialized static variables is to avoid zeroing large statically allocated buffers (say to be used as thread stacks) – this can considerably reduce initialization time on devices that operate at low frequencies.

The only correct way to use this section is by placing static mut variables with type MaybeUninit in it.

ⓘ
use core::mem::MaybeUninit;

const STACK_SIZE: usize = 8 * 1024;
const NTHREADS: usize = 4;

#[link_section = ".uninit.STACKS"]
static mut STACKS: MaybeUninit<[[u8; STACK_SIZE]; NTHREADS]> = MaybeUninit::uninit();

Be very careful with the link_section attribute because it’s easy to misuse in ways that cause undefined behavior. At some point in the future we may add an attribute to safely place static variables in this section.

Extra Sections

Some microcontrollers provide additional memory regions beyond RAM and FLASH. For example, some STM32 devices provide “CCM” or core-coupled RAM that is only accessible from the core. In order to access these using link_section attributes from your code, you need to modify memory.x to declare the additional sections:

MEMORY
{
    FLASH  (rx) : ORIGIN = 0x08000000, LENGTH = 1024K
    RAM    (rw) : ORIGIN = 0x20000000, LENGTH = 128K
    CCMRAM (rw) : ORIGIN = 0x10000000, LENGTH = 64K
}

SECTIONS
{
    .ccmram (NOLOAD) : ALIGN(4)
    {
        *(.ccmram .ccmram.*);
        . = ALIGN(4);
    } > CCMRAM
}

You can then use something like this to place a variable into this specific section of memory:

ⓘ
#[link_section=".ccmram.BUFFERS"]
static mut BUF: [u8; 1024] = [0u8; 1024];

Minimum Supported Rust Version (MSRV)

The MSRV of this release is Rust 1.39.0.

Structs

ExceptionFrame

Registers stacked (pushed onto the stack) during an exception.

Functions

heap_start

Returns a pointer to the start of the heap

Attribute Macros

entry

Attribute to declare the entry point of the program

exception

Attribute to declare an exception handler

interrupt

Attribute to declare an interrupt (AKA device-specific exception) handler

pre_init

Attribute to mark which function will be called at the beginning of the reset handler.