Crate cortex_m_rt

Source
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 -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.

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 peripheral access crate (PAC).

A #[pre_init] macro is also provided to run a function before RAM initialisation, but its use is deprecated as it is not defined behaviour to execute Rust code before initialisation. It is still possible to create a custom pre_init function using assembly.

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, described in this section. The memory.x file is used during linking by the link.x script provided by this crate. If you are using a custom linker script, you do not need a memory.x file.

§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 / _stack_end

The _stack_start 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 is generally a sensible default and most applications will not need to specify _stack_start. The same goes for _stack_end which is automatically placed after the end of statically allocated RAM.

NOTE: If you change _stack_start, make sure to also set _stack_end correctly to match new stack area if you are using it, e.g for MSPLIM. The _stack_end is not used internally by cortex-m-rt and is only for application use.

For Cortex-M, the _stack_start must always be aligned to 8 bytes, which is enforced by the linker script. If you override it, ensure that whatever value you set is a multiple of 8 bytes. The _stack_end is aligned to 4 bytes.

This symbol can be used to place the stack in a different memory region, for example:

/* Linker script for the STM32F303VCT6 with stack in CCM */
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);
_stack_end = ORIGIN(CCRAM); /* Optional, add if used by the application */

§_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:

#![no_main]
#![no_std]

// Some panic handler needs to be included. This one halts the processor on panic.
use panic_halt as _;

use cortex_m_rt::entry;

// Use `main` as the entry point of this application, which may not 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
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 peripheral access crates, or PACs, will populate the missing part of the vector table when their "rt" feature is enabled.

§set-sp

If this feature is enabled, the stack pointer (SP) is initialised in the reset handler to the _stack_start value from the linker script. This is not usually required, but some debuggers do not initialise SP when performing a soft reset, which can lead to stack corruption.

§set-vtor

If this feature is enabled, the vector table offset register (VTOR) is initialised in the reset handler to the start of the vector table defined in the linker script. This is not usually required, but some bootloaders do not set VTOR before jumping to application code, leading to your main function executing but interrupt handlers not being used.

§zero-init-ram

If this feature is enabled, RAM is initialized with zeros during startup from the _ram_start value to the _ram_end value from the linker script. This is not usually required, but might be necessary to properly initialize memory integrity measures on some hardware.

§paint-stack

Everywhere between __sheap and _stack_start is painted with the fixed value STACK_PAINT_VALUE, which is 0xCCCC_CCCC. You can then inspect memory during debugging to determine how much of the stack has been used - where the stack has been used the ‘paint’ will have been ‘scrubbed off’ and the memory will have a value other than STACK_PAINT_VALUE.

§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.

  • HardFault and _HardFault. These function handle the hard fault handling and what they do depends on whether the hard fault is overridden and whether the trampoline is enabled (which it is by default).

    • No override: Both are the same function. The function is an infinite loop defined in the cortex-m-rt crate.
    • Trampoline enabled: HardFault is the real hard fault handler defined in assembly. This function is simply a trampoline that jumps into the rust defined _HardFault function. This second function jumps to the user-defined handler with the exception frame as parameter. This second jump is usually optimised away with inlining.
    • Trampoline disabled: HardFault is the user defined function. This means the user function is called directly from the vector table. _HardFault still exists, but is an empty function that is purely there for compiler diagnostics.

  • __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), 240 vectors (on ARMv7-M) or 496 vectors (on ARMv8-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. As this runs before RAM is initialised, it is not sound to use a Rust function for pre_init, and instead it should typically be written in assembly using global_asm or an external assembly file.

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

§Custom linker script

To use your own linker script, ensure it is placed in the linker search path (for example in the crate root or in Cargo’s OUT_DIR) and use it with -C link-arg=-Tmy_script.ld instead of the normal -C link-arg=-Tlink.x. The provided link.x may be used as a starting point for customisation.

§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 PACs 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. We use a similar solution via the PROVIDE command in the linker script: when the "device" feature is enabled, cortex-m-rt’s linker script (link.x) includes a linker script named device.x, which must be provided by whichever crate provides __INTERRUPTS.

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 a 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 with MaybeUninit types.

ⓘ
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.

§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 place variables in these sections 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: MaybeUninit<[u8; 1024]> = MaybeUninit::uninit();

However, note that these sections are not initialised by cortex-m-rt, and so must be used either with MaybeUninit types or you must otherwise arrange for them to be initialised yourself, such as in pre_init.

§Minimum Supported Rust Version (MSRV)

The MSRV of this release is Rust 1.61.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.