draft of exercise text

embedded-workshop-book/src/pac_exercise.md

@@ -1,20 +1,100 @@
 # PAC Exercise
 
-In this exercise you will generate a PAC (Peripheral Access Crate) from an svd file. 
+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
+[todo!]
+
+## 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
+
 
-Install `svd2rust` via cargo 
-Download https://github.com/NordicSemiconductor/nrfx/blob/master/mdk/nrf52.svd (or some tagged version)
 
-Run svd2rust with the SVD file to generate a PAC using the `cortex-m` flag
-Notice how it's one long line of text in the source file. (mine is clean?!)
-Look at the PAC docs with cargo doc --open. (this needs a cargo.toml, make one yourself??, what do we want folks to see?)
-cargo fmt the crate. No change to the docs, but a bit more readable.
-cargo install form, use form to process the one-big-file into one-file-per-module. 
-form -i src/lib.rs -o src/  Re-run cargo fmt. 
-Find the definition of the ENABLE register for UARTE0, in the PDF datasheet and in the SVD file, and in the svd2rust generated code.
 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 PAC
+
+find the "board" struct in docs und take()
+
+take() assures, that only one instance of this can exist. hence, it's safe. 
+
+Find the definition of the ENABLE register for UARTE0, in the PDF datasheet and in the SVD file, and in the svd2rust generated code.
+
+✅ uarte0.rs/enable
+
+read().bits
+write(closure)
+
+
+
+✅ Import the PAC
+
+cargo.toml
+
+```
+dk_pac = { path = "../dk_pac", features = ["critical-section"]}
+```
+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
+
+✅ Write a helper function that prints the status of the uarte peripheral. Check if the enable is not 0
+
+
 base address Uarte0 0x40002000
 enable UARTE 0x500 
+✅ Enable the peripheral
+✅ Disable the peropheral with an unsafe write
 
-add pac to cargo.toml