embedded-trainings-2020/embedded-workshop-book/src/pac-exercise.md

PAC Exercise

In this exercise you will generate a PAC (Peripheral Access Crate) from an svd file, and write a small program that enables the UARTE0 register.

In this exercise you will learn how to

• Generate a Peripheral Access Crate from an svd file
• Two ways to write into a register to enable and disable it

Prerequisites

• basic use of closures
• read/write/modify api

Tasks

Generating the PAC

✅ Install svd2rust using the following command:

cargo install svd2rust

✅ Download https://github.com/NordicSemiconductor/nrfx/blob/master/mdk/nrf52.svd (This version has an error: writeonce needs to be changed to writeOnce) Place the file into down-the-stack/dk-pac. Note how we provide a Cargo.toml file, as it will not be generated by svd2rust.

✅ In the terminal, go to the file's location. Run svd2rust with the SVD file to generate a PAC using the cortex-m flag.

svd2rust --target cortex-m -i nrf52.svd

If you check the folder down-the-stack/dk-pac now, you see three new files:

• lib.rs - the file that contains the generated code for the pac
• device.x - linker sections(?)
• build.rs - linker script

✅ Open the generated lib.rs with an editor. Notice how it's one long line of text in the source file.

✅ Look at the PAC docs with cargo doc --open.

✅ cargo fmt the crate. No change to the docs, but a bit more readable.

✅ Install form with the following command:

cargo install form

✅ use form to process the one-big-file into one-file-per-module with the following command:

form -i src/lib.rs -o src/

✅  Re-run `cargo fmt`. 


## Enabling the UARTE0 peripheral



Write a simple program which uses the PAC to enable the UART. See how writing arbitrary values to the ENABLE field in the ENABLE register is unsafe, because only values 0 or 8 should be used.

✅ Finding your way through the docs:
(This better be a lecture)

* In the `Structs` section look for the `struct Peripherals`. Taking ownerhip of it will be the first step later on. Note that only the method `steal()` is documented. It is an unsafe method, and to be avoided. `Peripherals` has a field named `UARTE0`
* In the `modules` section, look for the `uarte0` module. It is divided into submodules. `enable` is important for us. Clicking on it shows the associated type definitions.  


* `W` - the register ENABLE writer with the following methods:
    * `enable()` returns the field ENABLE writer `ENABLE_W`. 
    * `unsafe bits()` writes raw bits into the register.
* `R` - the register ENABLE reader writer with the following methods:
    * `enable()` returns the field ENABLE reader `ENABLE_R`. 
    * `bits()` reads raw bits from the register. 
The types `ENABLE_R` and `ENABLE_W` have useful methods themselves, check them out. 

Usage: if you want to write or read something from the uarte register and you want to avoid dealing with raw bits, you first have to call a method that gives you access to the respective reader or writer, and then call the method that does what you want. 

Example:

uarte.enable.read().

Note the difference between the struct field `UARTE0` in `Peripherals` and the module `uarte0`.

✅ Finding your way through the PAC

* `dk_pac/src/lib.rs` defines the single peripherals with their register block addresses and contains a struct defintion for the `struct Peripherals`. There are two methods for this struct: `take()` and `steal()`. `take()` assures, that only one instance of this can exist. Hence, it's safe. Note that `take()` is only available with the `critical-section` feature enabled.

* `dk_pac/src/uarte0.rs` defines a struct that contains all the registers of the `UARTE0` register block. The `enable` field represents the register of the same name. 

* `dk_pac/src/uarte0/enable.rs` defines the types associated with this register that you already saw in the docs. 

* Find the definition of the ENABLE register for UARTE0, in the PDF datasheet and in the SVD file

* 


✅ Import the PAC

down-the-stack/apps/Cargo.toml

dk_pac = { path = "../dk_pac", features = ["critical-section"]}

apps/bin/uarte_enable.rs

```rust 
use dk_pac::UARTE0;

✅ Take ownership of the peripherals with take() and bind the UARTE0 peripheral to it's own variable

let periph = dk_pac::Peripherals::take().unwrap();
let uarte = periph.UARTE0;

✅ Write a helper function that reads the bits of the enable register. It prints "Uarte0 is enabled", when the value is not 0. If it is 0, it prints "Uarte0 is disabled". Add a function call to fn main()

Run the code. The terminal output should read: "Uarte0 is disabled".

fn is_uarte_enabled(uarte: &UARTE0) {
    if uarte.enable.read().enable().is_enabled() {
        defmt::println!("Uarte0 is enabled");
    } else {
        defmt::println!("Uarte0 is disabled");
    }
}

✅ Enable the peripheral safely by passing w.enable().enabled() in the closure. Call the helper function after this new line and run your code.

It should print: "Uarte0 is disabled" "Uarte0 is ensabled"

uarte.enable.write(|w| w.enable().enabled());

✅ Disable the peripheral with unsafely by writing raw bits into the register.

unsafe {
        uarte.enable.write(|w| w.bits(0x00 as u32));
    }