PACs and svd2rust

# PACs and svd2rust

---
## Introduction

The *Peripheral Access Crate* crate sits near the bottom of the 'stack'. It
provides access to the memory-mapped peripherals in your MCU.

---
## Memory Mapped Peripherals

* e.g. a UART peripheral
* Has registers, represented by a memory address
* Registers are usually consecutive in memory (not always)
* Peripherals can have instances (same layout of registers, different start address)
  * UART0, UART1, etc

Note:

The *Universal Asynchronous Receiver Transmitter* is an IP block implementing a
logic-level RS-232 interface, and one is fitted to basically every
microcontroller. Also known as a *serial port*.

Nordic calls their peripheral *UARTE*, with the E standing for *Easy DMA*.

---
## Registers

* *Registers* are comprised of one or more *bitfields*.
* Each bitfield is at least 1 bit in length.
* Sometimes bitfields can only take from a limited set of values
* This is all in your datasheet!

---
## C Code

Embedded Code in C often uses shifts and bitwise-AND to extract bitfields from
registers.

```c []
#define UARTE_INTEN_CTS_SHIFT (0)
#define UARTE_INTEN_CTS_MASK (0x00000001)
#define UARTE_INTEN_RXRDY_SHIFT (2)
#define UARTE_INTEN_RXRDY_MASK (0x00000001)

// The other nine fields are skipped for brevity
uint32_t cts = 0;
uint32_t rxrdy = 1;

uint32_t inten_value = ((cts & UARTE_INTEN_CTS_MASK) << UARTE_INTEN_CTS_SHIFT)
    | ((rxrdy & UARTE_INTEN_RXRDY_MASK) << UARTE_INTEN_RXRDY_SHIFT);

*((volatile uint32_t*) 0x40002300) = inten_value;
```

---
## Rust Code

You *could* do this in Rust if you wanted...

```rust ignore
const UARTE0_INTEN: *mut u32 = 0x4000_2300 as *mut u32;
unsafe { UARTE0_INTEN.write_volatile(0x0000_0003); }
```

But this still seems very error-prone. Nothing stops you putting the wrong value
at the wrong address.

---
## Adding structure

In C, the various registers for a peripheral can also be grouped into a `struct`:

```c []
typedef volatile struct uart0_reg_t {
    uint32_t tasks_startrx; // @ 0x000
    uint32_t tasks_stoprx; // @ 0x004
    // ...
    uint32_t inten; // @ 0x300
    uint32_t _padding[79]; 
    uint32_t baudrate; // @ 0x500
} uart0_reg_t

uart0_reg_t* const p_uart = (uart0_reg_t*) 0x40002000;
```

---
## Structures in Rust

```rust ignore []
#[repr(C)]
pub struct Uart0 {
    pub tasks_startrx: VolatileCell<u32>, // @ 0x000
    pub tasks_stoprx: VolatileCell<u32>, // @ 0x004
    // ...
    pub inten: VolatileCell<u32>, // @ 0x300
    _reserved12: [u32; 79],
    pub baudrate: VolatileCell<u32>, // @ 0x500
}

let p_uart: &Uart0 = unsafe { &*(0x40002000 as *const Uart0) };    
```

The
[`vcell::VolatileCell`](https://docs.rs/vcell/0.1.3/vcell/struct.VolatileCell.html)
type ensures the compiler emits volatile pointer read/writes.

Note:

There is some discussion about whether `VolatileCell` technically breaks Rust's
rules around references. It works in practice, but it might be technically
unsound.

---
## Other approaches

```rust []
pub struct Uart { base: *mut u32 } // now has no fields

impl Uart {
    fn write_tasks_stoprx(&mut self, value: u32) {
        unsafe {
            let ptr = self.base.offset(1);
            ptr.write_volatile(value)
        }
    }

fn read_baudrate(&self) -> u32 {
        unsafe {
            let ptr = self.base.offset(0x140);
            ptr.read_volatile()
        }
    }
}

let uart = Uart { base: unsafe { 0x40002000 as *mut u32 } };
```

Note:

The pointer is a `*mut u32` so the offsets are all in 32-bit words, not bytes.

---
## Zero Sized Types

We could handle the address as part of the type instead...

```rust []
pub struct Uart<const ADDR: usize> {}

impl<const ADDR: usize> Uart<ADDR> {
    fn write_tasks_stoprx(&mut self, value: u32) {
        unsafe {
            let ptr = (ADDR as *mut u32).offset(1);
            ptr.write_volatile(value)
        }
    }

fn read_baudrate(&self) -> u32 {
        unsafe {
            let ptr = (ADDR as *mut u32).offset(0x140);
            ptr.read_volatile()
        }
    }
}

let uart: Uart::<0x40002000> = Uart {};
```

Note:

By itself this seems a small change, but imagine a struct which represents 75
individual peripherals. That's not impossible for a modern microcontroller.
Holding one word for each now takes up valuable RAM!

---
## CMSIS-SVD Files

A CMSIS-SVD (or just SVD) file is an XML description of all the peripherals,
registers and fields on an MCU.

We can use `svd2rust` to turn this into a Peripheral Access Crate.

<br>

Note:

Although it is an Arm standard, there are examples of RISC-V based
microcontrollers which use the same format SVD files and hence can use svd2rust.

Also be aware that manufacturers often assume you will only use the SVD file to
inspect the microcontrollers state whilst debugging, and so accuracy has been
known to vary somewhat. Rust groups often have to maintain a set of patches to
fix known bugs in the SVD files.

---
## The `svd2rust` generated API

<figure>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">


<svg width="566pt" height="191pt"
 viewBox="0.00 0.00 565.98 191.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 187)">
<title>%3</title>
<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-187 561.9769,-187 561.9769,4 -4,4"/>

<g id="node1" class="node">
<title>Peripherals</title>
<polygon fill="#add8e6" stroke="#000000" points="232.9769,-146.5 232.9769,-182.5 340.9769,-182.5 340.9769,-146.5 232.9769,-146.5"/>
<text text-anchor="middle" x="286.9636" y="-160.3" font-family="Times,serif" font-size="14.00" fill="#000000">Peripherals</text>
</g>

<g id="node2" class="node">
<title>uarte1</title>
<polygon fill="#add8e6" stroke="#000000" points="143.8766,-73.5 143.8766,-109.5 278.0772,-109.5 278.0772,-73.5 143.8766,-73.5"/>
<text text-anchor="middle" x="210.9769" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">.UARTE1: UARTE1</text>
</g>

<g id="edge1" class="edge">
<title>Peripherals->uarte1</title>
<path fill="none" stroke="#000000" d="M268.1904,-146.4551C258.873,-137.5054 247.4642,-126.547 237.2926,-116.7769"/>
<polygon fill="#000000" stroke="#000000" points="239.4473,-113.9935 229.8107,-109.5904 234.5981,-119.0419 239.4473,-113.9935"/>
</g>

<g id="node5" class="node">
<title>uarte2</title>
<polygon fill="#add8e6" stroke="#000000" points="295.8766,-73.5 295.8766,-109.5 430.0772,-109.5 430.0772,-73.5 295.8766,-73.5"/>
<text text-anchor="middle" x="362.9769" y="-87.3" font-family="Times,serif" font-size="14.00" fill="#000000">.UARTE2: UARTE2</text>
</g>

<g id="edge4" class="edge">
<title>Peripherals->uarte2</title>
<path fill="none" stroke="#000000" d="M305.7634,-146.4551C315.0808,-137.5054 326.4896,-126.547 336.6612,-116.7769"/>
<polygon fill="#000000" stroke="#000000" points="339.3557,-119.0419 344.1431,-109.5904 334.5065,-113.9935 339.3557,-119.0419"/>
</g>

<g id="node3" class="node">
<title>uarte1_baudrate</title>
<polygon fill="#add8e6" stroke="#000000" points="0,-.5 0,-36.5 141.9538,-36.5 141.9538,-.5 0,-.5"/>
<text text-anchor="middle" x="70.9769" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">.baudrate: BAUDATE</text>
</g>

<g id="edge2" class="edge">
<title>uarte1->uarte1_baudrate</title>
<path fill="none" stroke="#000000" d="M176.3701,-73.4551C157.692,-63.7157 134.4515,-51.5975 114.5509,-41.2207"/>
<polygon fill="#000000" stroke="#000000" points="116.156,-38.1105 105.6707,-36.5904 112.9195,-44.3174 116.156,-38.1105"/>
</g>

<g id="node4" class="node">
<title>uarte1_inten</title>
<polygon fill="#add8e6" stroke="#000000" points="159.9769,-.5 159.9769,-36.5 267.9769,-36.5 267.9769,-.5 159.9769,-.5"/>
<text text-anchor="middle" x="213.9096" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">.inten: INTEN</text>
</g>

<g id="edge3" class="edge">
<title>uarte1->uarte1_inten</title>
<path fill="none" stroke="#000000" d="M211.7185,-73.4551C212.0502,-65.3828 212.4491,-55.6764 212.8187,-46.6817"/>
<polygon fill="#000000" stroke="#000000" points="216.3198,-46.7257 213.2335,-36.5904 209.3257,-46.4382 216.3198,-46.7257"/>
</g>

<g id="node6" class="node">
<title>uarte2_baudrate</title>
<polygon fill="#add8e6" stroke="#000000" points="290,-.5 290,-36.5 431.9538,-36.5 431.9538,-.5 290,-.5"/>
<text text-anchor="middle" x="360.9769" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">.baudrate: BAUDATE</text>
</g>

<g id="edge5" class="edge">
<title>uarte2->uarte2_baudrate</title>
<path fill="none" stroke="#000000" d="M362.4825,-73.4551C362.2614,-65.3828 361.9954,-55.6764 361.749,-46.6817"/>
<polygon fill="#000000" stroke="#000000" points="365.2452,-46.4907 361.4725,-36.5904 358.2478,-46.6825 365.2452,-46.4907"/>
</g>

<g id="node7" class="node">
<title>uarte2_inten</title>
<polygon fill="#add8e6" stroke="#000000" points="449.9769,-.5 449.9769,-36.5 557.9769,-36.5 557.9769,-.5 449.9769,-.5"/>
<text text-anchor="middle" x="503.9096" y="-14.3" font-family="Times,serif" font-size="14.00" fill="#000000">.inten: INTEN</text>
</g>

<g id="edge6" class="edge">
<title>uarte2->uarte2_inten</title>
<path fill="none" stroke="#000000" d="M397.8308,-73.4551C416.6424,-63.7157 440.0489,-51.5975 460.0917,-41.2207"/>
<polygon fill="#000000" stroke="#000000" points="461.764,-44.2962 469.0352,-36.5904 458.5456,-38.0799 461.764,-44.2962"/>
</g>
</g>
</svg>
</figure>

---

* The crate has a top-level `struct Peripherals` with members for each *Peripheral*
* Each *Peripheral* gets a `struct`, like `UARTE0`, `SPI1`, etc.
* Each *Peripheral* `struct` has members for each *Register*
* Each *Register* gets a `struct`, like `BAUDRATE`, `INTEN`, etc.
* Each *Register* `struct` has `read()`, `write()` and `modify()` methods
* Each *Register* also has a Read Type (`R`) and a Write Type (`W`)
  * Those Read/Write Types give you access to the *Bitfields*

---
## The `svd2rust` generated API (2)

* The `read()` method returns a special proxy object, with methods for each *Field*
* The `write()` method takes a closure, which is given a special 'proxy' object, with methods for each *Field*
  * All the *Field* changes are batched together and written in one go
  * Any un-written *Fields* are set to a default value
* The `modify()` method gives you both
  * Any un-written *Fields* are left alone

---
## Using a PAC

```rust ignore []
let p = nrf52840_pac::Peripherals::take().unwrap();
// Reading the 'baudrate' field
let contents = p.UARTE1.baudrate.read();
let current_baud_rate = contents.baudrate();
// Modifying multiple fields in one go
p.UARTE1.inten.modify(|_r, w| {
    w.cts().enabled();
    w.ncts().enabled();
    w.rxrdy().enabled();
    w    
});
```

---
## Wait, what's a closure?

* It's an anonymous function, declared in-line with your other code
* It can 'capture' local variables (although we don't use that feature here)
* It enables a very powerful Rust idiom, that you can't easily do in C...

---
## Let's take it in turns

* I, the callee, need to set some stuff up
* You, the caller, need to do a bit of work
* I, the callee, need to clean everything up

We can use a closure to insert the caller-provided code in the middle of our
function. We see this used [all
(1)](https://doc.rust-lang.org/core/iter/trait.Iterator.html#method.map) [over
(2)](https://doc.rust-lang.org/core/primitive.str.html#method.matches) [the
(3)](https://doc.rust-lang.org/std/thread/fn.spawn.html) Rust standard library!

---
## Quiz time

What are the three steps here?

```rust ignore []
p.UARTE1.inten.modify(|_r, w| {
    w.cts().enabled();
    w.ncts().enabled();
    w.rxrdy().enabled();
    w    
});
```

Note:

1. Read the peripheral MMIO register contents as an integer
2. Call the closure to modify the integer
3. Write the integer back to the peripheral MMIO register

---
## Documentation

Docs can be generated from the source code.

See <https://docs.rs/nrf52840-pac>

Note that `uarte0` is a *module* and `UARTE0` could mean either a `struct` type,
or a field on the `Peripherals` struct.

---
## UPPER_CASE and TitleCase

* Is it weird that it produces `UPPER_CASE` fields and types?
* There's now [a config file for that](https://github.com/rust-embedded/svd2rust/pull/794)