The Embedded Rust Book

The Registers

Let's look at the 'SysTick' peripheral - a simple timer which comes with every Cortex-M processor core. Typically you'll be looking these up in the chip manufacturer's data sheet or Technical Reference Manual, but this example is common to all ARM Cortex-M cores, let's look in the ARM reference manual. We see there are four registers:

The C Approach

In Rust, we can represent a collection of registers in exactly the same way as we do in C - with a struct.

#[repr(C)]

struct SysTick {

pub csr: u32,

pub rvr: u32,

pub cvr: u32,

pub calib: u32,

}

The qualifier #[repr(C)] tells the Rust compiler to lay this structure out like a C compiler would. That's very important, as Rust allows structure fields to be re-ordered, while C does not. You can imagine the debugging we'd have to do if these fields were silently re-arranged by the compiler! With this qualifier in place, we have our four 32-bit fields which correspond to the table above. But of course, this struct is of no use by itself - we need a variable.

let systick = 0xE000_E010 as *mut SysTick;

let time = unsafe { (*systick).cvr };

Volatile Accesses

Now, there are a couple of problems with the approach above.

1. We have to use unsafe every time we want to access our Peripheral.

2. We've got no way of specifying which registers are read-only or read-write.

3. Any piece of code anywhere in your program could access the hardware through this structure.

4. Most importantly, it doesn't actually work...

Now, the problem is that compilers are clever. If you make two writes to the same piece of RAM, one after the other, the compiler can notice this and just skip the first write entirely. In C, we can mark variables as volatile to ensure that every read or write occurs as intended. In Rust, we instead mark the accesses as volatile, not the variable.

let systick = unsafe { &mut *(0xE000_E010 as *mut SysTick) };

let time = unsafe { core::ptr::read_volatile(&mut systick.cvr) };

So, we've fixed one of our four problems, but now we have even more unsafe code! Fortunately, there's a third party crate which can help - volatile_register.

use volatile_register::{RW, RO};

#[repr(C)]

struct SysTick {

pub csr: RW,

pub rvr: RW,

pub cvr: RW,

pub calib: RO,

}

fn get_systick() -> &'static mut SysTick {

unsafe { &mut *(0xE000_E010 as *mut SysTick) }

}

fn get_time() -> u32 {

let systick = get_systick();

systick.cvr.read()

}

Now, the volatile accesses are performed automatically through the read and write methods. It's still unsafe to perform writes, but to be fair, hardware is a bunch of mutable state and there's no way for the compiler to know whether these writes are actually safe, so this is a good default position.

The Rusty Wrapper

We need to wrap this struct up into a higher-layer API that is safe for our users to call. As the driver author, we manually verify the unsafe code is correct, and then present a safe API for our users so they don't have to worry about it (provided they trust us to get it right!).

One example might be:

use volatile_register::{RW, RO};

pub struct SystemTimer {

p: &'static mut RegisterBlock

}

#[repr(C)]

struct RegisterBlock {

pub csr: RW,

pub rvr: RW,

pub cvr: RW,

pub calib: RO,

}

impl SystemTimer {

pub fn new() -> SystemTimer {

SystemTimer {

p: unsafe { &mut *(0xE000_E010 as *mut RegisterBlock) }

}

}

pub fn get_time(&self) -> u32 {

self.p.cvr.read()

}

pub fn set_reload(&mut self, reload_value: u32) {

unsafe { self.p.rvr.write(reload_value) }

}

}

pub fn example_usage() -> String {

let mut st = SystemTimer::new();

st.set_reload(0x00FF_FFFF);

format!("Time is now 0x{:08x}", st.get_time())

}

Now, the problem with this approach is that the following code is perfectly acceptable to the compiler:

fn thread1() {

let mut st = SystemTimer::new();

st.set_reload(2000);

}

fn thread2() {

let mut st = SystemTimer::new();

st.set_reload(1000);

}

Our &mut self argument to the set_reload function checks that there are no other references to that particular SystemTimer struct, but they don't stop the user creating a second SystemTimer which points to the exact same peripheral! Code written in this fashion will work if the author is diligent enough to spot all of these 'duplicate' driver instances, but once the code is spread out over multiple modules, drivers, developers, and days, it gets easier and easier to make these kinds of mistakes.

Mutable Global State

Unfortunately, hardware is basically nothing but mutable global state, which can feel very frightening for a Rust developer. Hardware exists independently from the structures of the code we write, and can be modified at any time by the real world.

What should our rules be?

How can we reliably interact with these peripherals?

1. Always use volatile methods to read or write to peripheral memory, as it can change at any time

2. In software, we should be able to share any number of read-only accesses to these peripherals

3. If some software should have read-write access to a peripheral, it should hold the only reference to that peripheral

The Borrow Checker

The last two of these rules sound suspiciously similar to what the Borrow Checker does already!

Imagine if we could pass around ownership of these peripherals, or offer immutable or mutable references to them?

Well, we can, but for the Borrow Checker, we need to have exactly one instance of each peripheral, so Rust can handle this correctly. Well, luckliy in the hardware, there is only one instance of any given peripheral, but how can we expose that in the structure of our code?