RustConf 2018

James Munns

@bitshiftmask

james.munns@ferrous-systems.com

Rust? for Embedded?

embedded rust isn’t a new idea

Rust in 2018

stabilizing things behind the scenes

LLVM

if they can do it, so can we!

#![no_std]

where we’re going, we don’t need operating systems

$ rustup default stable
$ cargo build --target thumbv7em-none-eabihf

building firmware doesn’t have to be complex

batteries included

Embedded Systems

computers you don’t sit in front of

Microcontrollers

phenomenal hardware powers

itty bitty living space

Peripherals

connecting your CPU to the physical world

Hardware API

herding bits

Memory Mapped Peripherals

0x2000_0000 is a real place

0x0000_0000 is too

Now what?

write code!

use core::ptr;
const SER_PORT_SPEED_REG: *mut u32 = 0x4000_1000 as _;

fn read_serial_port_speed() -> u32 {
    unsafe { // <-- :(
        ptr::read_volatile(SER_PORT_SPEED_REG)
    }
}
fn write_serial_port_speed(val: u32) {
    unsafe { // <-- :(
        ptr::write_volatile(SER_PORT_SPEED_REG, val);
    }
}

use core::ptr;

struct SerialPort;

impl SerialPort {
    const SER_PORT_SPEED_REG: *mut u32 = 0x4000_1000 as _;
    pub const SER_PORT_SPEED_HI: u32 = 0x8000_0000;
    pub const SER_PORT_SPEED_LO: u32 = 0x0800_0000;

    fn new() -> SerialPort {
        SerialPort
    }

fn read_speed(&self) -> u32 {
    unsafe {
        ptr::read_volatile(Self::SER_PORT_SPEED_REG)
    }
}

fn write_speed(&mut self, val: u32) {
    unsafe {
        ptr::write_volatile(Self::SER_PORT_SPEED_REG, val);
    }
}

fn do_something() {
    let mut serial = SerialPort::new();

    let speed = serial.read_speed();
    // Do some work
    serial.write_speed(speed * 2);
}

fn do_something() {
    let mut serial = SerialPort::new();
    let speed = serial.read_speed();

    // Be careful, we have to go slow!
    if speed != SerialPort::SER_PORT_SPEED_LO {
        serial.write_speed(SerialPort::SER_PORT_SPEED_LO)
    }
    // First, send some pre-data
    something_else();
    // Okay, lets send some slow data
    // ...
}

fn something_else() {
    let mut serial = SerialPort::new();
    // We gotta go fast for this!
    serial.write_speed(SerialPort::SER_PORT_SPEED_HI);
    // send some data...
}

This smells like mutable global state

hardware is basically nothing but mutable global state

What are our rules?

We should be able to share any number of read-only accesses to these peripherals

If something has read-write access to a peripheral, it should be the only reference

Part I: The Borrow Checker

ownership and borrows

Singletons

In software engineering, the singleton pattern is a software design pattern that restricts the instantiation of a class to one object.

https://en.wikipedia.org/wiki/Singleton_pattern

static mut THE_SERIAL_PORT: SerialPort = SerialPort;

fn main() {
    let _ = unsafe {
        THE_SERIAL_PORT.read_speed();
    }
}

close, but not quite there

struct Peripherals {
    serial: Option<SerialPort>,
}
impl Peripherals {
    fn take_serial(&mut self) -> SerialPort {
        let p = replace(&mut self.serial, None);
        p.unwrap()
    }
}
static mut PERIPHERALS: Peripherals = Peripherals {
    serial: Some(SerialPort),
};

take what you need, but only once

fn main() {
    let serial_1 = unsafe { PERIPHERALS.take_serial() };
    // This panics!
    // let serial_2 = unsafe { PERIPHERALS.take_serial() };
}

small runtime overhead, big impact

#[macro_use(singleton)]
extern crate cortex_m;

fn main() {
    // OK if `main` is executed only once
    let x: &'static mut bool =
        singleton!(: bool = false).unwrap();
}

cortex_m docs

// cortex-m-rtfm v0.3.x
app! {
    resources: {
        static RX: Rx<USART1>;
        static TX: Tx<USART1>;
    }
}
fn init(p: init::Peripherals) -> init::LateResources {
    // Note that this is now an owned value, not a reference
    let usart1: USART1 = p.device.USART1;
}

japaric.io rtfm v3

But why?

how do singletons make a difference?

impl SerialPort {
    const SER_PORT_SPEED_REG: *mut u32 = 0x4000_1000 as _;

    fn read_speed(
        &self // <------ This is really, really important
    ) -> u32 {
        unsafe {
            ptr::read_volatile(Self::SER_PORT_SPEED_REG)
        }
    }
}

fn main() {
    let serial_1 = unsafe { PERIPHERALS.take_serial() };

    // you can only read what you have access to
    let _ = serial_1.read_speed();
}

This is allowed to change hardware settings:

fn setup_spi_port(
    spi: &mut SpiPort,
    cs_pin: &mut GpioPin
) -> Result<()> {
    // ...
}

This isn’t:

fn read_button(gpio: &GpioPin) -> bool {
    // ...
}

enforce whether code should or should not make changes to hardware

at compile time^*

^*: only works across one application, but for bare metal systems, we usually only have one anyway

Before you worry

you don’t have to write all of that code

this is rust. there’s a tool for that

it’s called svd2rust, and it turns XML files into rust code. like bindgen, but for hardware

Now that peripherals are structs…

what else can we do with Rust now?

Part II: The Type System

putting those strong types to work

GPIOs

take things one bit (of input or output) at a time

struct GpioPin; struct InputGpio; struct OutputGpio;

impl GpioPin {
    fn into_input(self) -> InputGpio {
        self.set_input_mode();
        InputGpio
    }
    fn into_output(self) -> OutputGpio {
        self.set_output_mode();
        OutputGpio
    }
}

impl LedPin {
    fn new(pin: OutputGpio) -> Self { ... }
    fn toggle(&mut self) -> bool { ... }
}

fn main() {
    let gpio_1 = unsafe { PERIPHERALS.take_gpio_1() };
    // This won't work, the types are wrong!
    // let led_1 = LedPin::new(gpio_1);
    let mut led_1 = LedPin::new(gpio_1.into_output());
    let _ = led_1.toggle();
}

Enforce design contracts

entirely at compile time

no runtime cost

no room for human error

“no runtime cost”?

use core::mem::size_of;

let _ = size_of::<GpioPin>();     // == 0
let _ = size_of::<InputGpio>();   // == 0
let _ = size_of::<OutputGpio>();  // == 0
let _ = size_of::<()>();          // == 0

Zero Sized Types

struct GpioPin;

acts real at compile time

doesn’t exist in the binary

no RAM, no CPU, no space

Can we do more with types?

oh, you bet we can

What if our `OutputGpio` has multiple modes?

(it does)

pub struct PushPull;  // good for general usage
pub struct OpenDrain; // better for high power LEDs

pub struct OutputGpio<MODE> {
    _mode: MODE
}

impl<MODE> OutputGpio<MODE> {
    fn default() -> OutputGpio<OpenDrain> { ... }
    fn into_push_pull(self) -> OutputGpio<PushPull> { ... }
    fn into_open_drain(self) -> OutputGpio<OpenDrain> { ... }
}

/// This kind of LED only works with OpenDrain settings
struct DrainLed {
    pin: OutputGpio<OpenDrain>,
}

impl DrainLed {
    fn new(pin: OutputGpio<OpenDrain>) -> Self { ... }
    fn toggle(&self) -> bool { ... }
}

/// This kind of LED works with any output
struct LedDriver<MODE> {
    pin: OutputGpio<MODE>,
}

/// Generically support any OutputGpio variant!
impl<MODE> LedDriver<MODE> {
    fn new(pin: OutputGpio<MODE>) -> LedDriver<MODE> { ... }
    fn toggle(&self) -> bool { ... }
}

Part III: The Trait System

traits of a successful project

Building something bigger

drivers that work for more than one chip

/// Single digital push-pull output pin
pub trait OutputPin {
    /// Drives the pin low
    fn set_low(&mut self);

    /// Drives the pin high
    fn set_high(&mut self);
}

rust-embedded/embedded-hal

impl<MODE> OutputPin for OutputGpio<MODE> {
    fn set_low(&mut self) {
        self.set_pin_low()
    }

    fn set_high(&mut self) {
        self.set_pin_high()
    }
}

this goes in your chip crate

impl<SPI, CS, E> L3gd20<SPI, CS>
where
    SPI: Transfer<u8, Error = E> + Write<u8, Error = E>,
    CS: OutputPin,
{
    /// Creates a new driver from a SPI peripheral
    /// and a NCS pin
    pub fn new(spi: SPI, cs: CS) -> Result<Self, E> {
        // ...
    }
    // ...
}

japaric/l3gd20

N*M <<< N+M

to re-use a driver, just implement the embedded-hal interface

Outro

all good things must end

Ownership and Borrowing

treat hardware resources the way you treat any other struct. let the compiler manage who has access to what

The Type System

use types to enforce state transitions, pre-conditions, and post-conditions. stop trying to keep that all in your head or in the comments

The Trait System

enable code reuse for your embedded projects. no more copy and pasting from project to project

Rust, Cargo, Community

take advantage of modern language features, package management, tooling, and a group of people willing to work with you

Option<T>

you don’t have to use all of this…

It’s important to note that you don’t have to do any of this stuff. If you’re making a simple project where you blink an LED, or read some data off a serial port, or build a robot to brush your teeth, this could all feel like overkill!

If you are fine with wrapping your register interactions in unsafe everywhere you use them, thats fine! You will need to manually keep track of what you do with your hardware, but that doesn’t leave us any worse off than where we are in languages like C, and you still get to keep all of the rest of the Rust goodies like cargo and interators and match statements.

But, if you are a library writer, providing code for other people to use, why wouldn’t you want to give them sane defaults, or good rules (or at least suggestions) on how to use the hardware?

People pick up new hardware all of the time, and every piece of hardware is different. I’ve misremembered how things work more commonly than I’ve gotten things right the first time. If the people who know the most about a piece of hardware have the tools to make things easier and more foolproof for the people who use that hardware, I think we could make getting in to hardware a lot more accessible for developers to get things right.

Thank you!

Plugs

icon by Freepik from flaticon.com

github.com/rust-embedded/wg

The Embedded Working Group

Ferrous Systems

ferrous-systems.com

Getting Something For Nothing