6 files changed, 77 insertions, 32 deletions

diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
index 4dc4a6359..3f4f16e28 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/modules/ROOT/pages/basic_application.adoc
@@ -21,7 +21,7 @@ Then, what follows are some declarations on how to deal with panics and faults.
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="11..12"]
+include::example$basic/src/main.rs[lines="10"]
 ----
 
 === Task declaration
@@ -30,7 +30,7 @@ After a bit of import declaration, the tasks run by the application should be de
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="13..22"]
+include::example$basic/src/main.rs[lines="12..20"]
 ----
 
 An embassy task must be declared `async`, and may NOT take generic arguments. In this case, we are handed the LED that should be blinked and the interval of the blinking.
@@ -45,23 +45,10 @@ The `Spawner` is the way the main application spawns other tasks. The `Periphera
 
 [source,rust]
 ----
-include::example$basic/src/main.rs[lines="23..-1"]
+include::example$basic/src/main.rs[lines="22..-1"]
 ----
 
-`#[embassy_executor::main]` takes an optional `config` parameter specifying a function that returns an instance of HAL's `Config` struct. For example:
-
-```rust
-fn embassy_config() -> embassy_nrf::config::Config {
-    embassy_nrf::config::Config::default()
-}
-
-#[embassy_executor::main(config = "embassy_config()")]
-async fn main(_spawner: Spawner, p: embassy_nrf::Peripherals) {
-    // ...
-}
-```
-
-What happens when the `blinker` task have been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy::main]` macro. The macro does the following:
+What happens when the `blinker` task has been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy::main]` macro. The macro does the following:
 
 . Creates an Embassy Executor
 . Initializes the microcontroller HAL to get the `Peripherals`
@@ -76,7 +63,7 @@ The project definition needs to contain the embassy dependencies:
 
 [source,toml]
 ----
-include::example$basic/Cargo.toml[lines="8..9"]
+include::example$basic/Cargo.toml[lines="9..11"]
 ----
 
 Depending on your microcontroller, you may need to replace `embassy-nrf` with something else (`embassy-stm32` for STM32. Remember to update feature flags as well).
diff --git a/docs/modules/ROOT/pages/bootloader.adoc b/docs/modules/ROOT/pages/bootloader.adoc
index ae92e9d5d..b7215e52a 100644
--- a/docs/modules/ROOT/pages/bootloader.adoc
+++ b/docs/modules/ROOT/pages/bootloader.adoc
@@ -6,7 +6,7 @@ The bootloader can be used either as a library or be flashed directly if you are
 
 By design, the bootloader does not provide any network capabilities. Networking capabilities for fetching new firmware can be provided by the user application, using the bootloader as a library for updating the firmware, or by using the bootloader as a library and adding this capability yourself.
 
-The bootloader supports both internal and external flash by relying on the `embedded-storage` traits.
+The bootloader supports both internal and external flash by relying on the `embedded-storage` traits. The bootloader optionally supports the verification of firmware that has been digitally signed (recommended).
 
 
 == Hardware support
@@ -15,6 +15,7 @@ The bootloader supports
 
 * nRF52 with and without softdevice
 * STM32 L4, WB, WL, L1, L0, F3, F7 and H7
+* Raspberry Pi: RP2040
 
 In general, the bootloader works on any platform that implements the `embedded-storage` traits for its internal flash, but may require custom initialization code to work.
 
@@ -25,12 +26,69 @@ image::bootloader_flash.png[Bootloader flash layout]
 The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader
 instance or via linker scripts:
 
-* BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash.
-* ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. This partition is only written to by the bootloader.
-* DFU - Where the application-to-be-swapped is placed. This partition is written to by the application.
-* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped. When the new firmware has been written to the DFU partition, a flag is set to instruct the bootloader that the partitions should be swapped.
+* BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash, but if you need to debug it and have space available, increasing this to 24kB will allow you to run the bootloader with probe-rs.
+* ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. This partition is only written to by the bootloader. The size required for this partition depends on the size of your application.
+* DFU - Where the application-to-be-swapped is placed. This partition is written to by the application. This partition must be at least 1 page bigger than the ACTIVE partition, since the swap algorithm uses the extra space to ensure power safe copy of data:
++
+Partition Size~dfu~= Partition Size~active~+ Page Size~active~
++
+All values are specified in bytes.
+
+* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped. When the new firmware has been written to the DFU partition, a magic field is written to instruct the bootloader that the partitions should be swapped. This partition must be able to store a magic field as well as the partition swap progress. The partition size given by:
++
+Partition Size~state~ = Write Size~state~ + (2 × Partition Size~active~ / Page Size~active~)
++
+All values are specified in bytes.
 
 The partitions for ACTIVE (+BOOTLOADER), DFU and BOOTLOADER_STATE may be placed in separate flash. The page size used by the bootloader is determined by the lowest common multiple of the ACTIVE and DFU page sizes.
 The BOOTLOADER_STATE partition must be big enough to store one word per page in the ACTIVE and DFU partitions combined.
 
 The bootloader has a platform-agnostic part, which implements the power fail safe swapping algorithm given the boundaries set by the partitions. The platform-specific part is a minimal shim that provides additional functionality such as watchdogs or supporting the nRF52 softdevice.
+
+=== FirmwareUpdater
+
+The `FirmwareUpdater` is an object for conveniently flashing firmware to the DFU partition and subsequently marking it as being ready for swapping with the active partition on the next reset. Its principle methods are `write_firmware`, which is called once per the size of the flash "write block" (typically 4KiB), and `mark_updated`, which is the final call.
+
+=== Verification
+
+The bootloader supports the verification of firmware that has been flashed to the DFU partition. Verification requires that firmware has been signed digitally using link:https://ed25519.cr.yp.to/[`ed25519`] signatures. With verification enabled, the `FirmwareUpdater::verify_and_mark_updated` method is called in place of `mark_updated`. A public key and signature are required, along with the actual length of the firmware that has been flashed. If verification fails then the firmware will not be marked as updated and therefore be rejected.
+
+Signatures are normally conveyed with the firmware to be updated and not written to flash. How signatures are provided is a firmware responsibility.
+
+To enable verification use either the `ed25519-dalek` or `ed25519-salty` features when depending on the `embassy-boot` crate. We recommend `ed25519-salty` at this time due to its small size.
+
+==== Tips on keys and signing with ed25519
+
+Ed25519 is a public key signature system where you are responsible for keeping the private key secure. We recommend embedding the *public* key in your program so that it can be easily passed to `verify_and_mark_updated`. An example declaration of the public key in your firmware:
+
+[source, rust]
+----
+static PUBLIC_SIGNING_KEY: &[u8] = include_bytes!("key.pub");
+----
+
+Signatures are often conveyed along with firmware by appending them.
+
+Ed25519 keys can be generated by a variety of tools. We recommend link:https://man.openbsd.org/signify[`signify`] as it is in wide use to sign and verify OpenBSD distributions, and is straightforward to use.
+
+The following set of Bash commands can be used to generate public and private keys on Unix platforms, and also generate a local `key.pub` file with the `signify` file headers removed. Declare a `SECRETS_DIR` environment variable in a secure location.
+
+[source, bash]
+----
+signify -G -n -p $SECRETS_DIR/key.pub -s $SECRETS_DIR/key.sec
+tail -n1 $SECRETS_DIR/key.pub | base64 -d -i - | dd ibs=10 skip=1 > key.pub
+chmod 700 $SECRETS_DIR/key.sec
+export SECRET_SIGNING_KEY=$(tail -n1 $SECRETS_DIR/key.sec)
+----
+
+Then, to sign your firmware given a declaration of `FIRMWARE_DIR` and a firmware filename of `myfirmware`:
+
+[source, bash]
+----
+shasum -a 512 -b $FIRMWARE_DIR/myfirmware > $SECRETS_DIR/message.txt
+cat $SECRETS_DIR/message.txt | dd ibs=128 count=1 | xxd -p -r > $SECRETS_DIR/message.txt
+signify -S -s $SECRETS_DIR/key.sec -m $SECRETS_DIR/message.txt -x $SECRETS_DIR/message.txt.sig
+cp $FIRMWARE_DIR/myfirmware $FIRMWARE_DIR/myfirmware+signed
+tail -n1 $SECRETS_DIR/message.txt.sig | base64 -d -i - | dd ibs=10 skip=1 >> $FIRMWARE_DIR/myfirmware+signed
+----
+
+Remember, guard the `$SECRETS_DIR/key.sec` key as compromising it means that another party can sign your firmware.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index f3492a3d0..881e449b6 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -45,11 +45,11 @@ You can run an example by opening a terminal and entering the following commands
 
 [source, bash]
 ----
-cd examples/nrf
+cd examples/nrf52840
 cargo run --bin blinky --release
 ----
 
-== Whats next?
+== What's next?
 
 Congratulations, you have your first Embassy application running! Here are some alternatives on where to go from here:
 
diff --git a/docs/modules/ROOT/pages/layer_by_layer.adoc b/docs/modules/ROOT/pages/layer_by_layer.adoc
index a96dd9fe2..a78a64a97 100644
--- a/docs/modules/ROOT/pages/layer_by_layer.adoc
+++ b/docs/modules/ROOT/pages/layer_by_layer.adoc
@@ -8,7 +8,7 @@ The application we'll write is a simple 'push button, blink led' application, wh
 
 == PAC version
 
-The PAC is the lowest API for accessing peripherals and registers, if you don't count reading/writing directly to memory addresses. It provide distinct types
+The PAC is the lowest API for accessing peripherals and registers, if you don't count reading/writing directly to memory addresses. It provides distinct types
 to make accessing peripheral registers easier, but it does not prevent you from writing unsafe code.
 
 Writing an application using the PAC directly is therefore not recommended, but if the functionality you want to use is not exposed in the upper layers, that's what you need to use.
@@ -20,13 +20,13 @@ The blinky app using PAC is shown below:
 include::example$layer-by-layer/blinky-pac/src/main.rs[]
 ----
 
-As you can see, there are a lot of code needed to enable the peripheral clocks, configuring the input pins and the output pins of the application.
+As you can see, a lot of code is needed to enable the peripheral clocks and to configure the input pins and the output pins of the application.
 
 Another downside of this application is that it is busy-looping while polling the button state. This prevents the microcontroller from utilizing any sleep mode to save power.
 
 == HAL version
 
-To simplify our application, we can use the HAL instead. The HAL exposes higher level APIs that handle details such
+To simplify our application, we can use the HAL instead. The HAL exposes higher level APIs that handle details such as:
 
 * Automatically enabling the peripheral clock when you're using the peripheral
 * Deriving and applying register configuration from higher level types
@@ -39,7 +39,7 @@ The HAL example is shown below:
 include::example$layer-by-layer/blinky-hal/src/main.rs[]
 ----
 
-As you can see, the application becomes a lot simpler, even without using any async code. The `Input` and `Output` hides all the details accessing the GPIO registers, and allow you to use a much simpler API to query the state of the button and toggle the LED output accordingly.
+As you can see, the application becomes a lot simpler, even without using any async code. The `Input` and `Output` types hide all the details of accessing the GPIO registers and allow you to use a much simpler API for querying the state of the button and toggling the LED output.
 
 The same downside from the PAC example still applies though: the application is busy looping and consuming more power than necessary.
 
diff --git a/docs/modules/ROOT/pages/runtime.adoc b/docs/modules/ROOT/pages/runtime.adoc
index a7d6a8d0c..5096f5a43 100644
--- a/docs/modules/ROOT/pages/runtime.adoc
+++ b/docs/modules/ROOT/pages/runtime.adoc
@@ -20,7 +20,7 @@ IMPORTANT: The executor relies on tasks not blocking indefinitely, as this preve
 
 image::embassy_executor.png[Executor model]
 
-If you use the `#[embassy::main]` macro in your application, it creates the `Executor` for you and spawns the main entry point as the first task. You can also create the Executor manually, and you can in fact create multiple Executors.
+If you use the `#[embassy_executor::main]` macro in your application, it creates the `Executor` for you and spawns the main entry point as the first task. You can also create the Executor manually, and you can in fact create multiple Executors.
 
 
 == Interrupts
diff --git a/docs/modules/ROOT/pages/stm32.adoc b/docs/modules/ROOT/pages/stm32.adoc
index 8ed9ab04b..7bfc0592b 100644
--- a/docs/modules/ROOT/pages/stm32.adoc
+++ b/docs/modules/ROOT/pages/stm32.adoc
@@ -4,9 +4,9 @@ The link:https://github.com/embassy-rs/embassy/tree/master/embassy-stm32[Embassy
 
 == The infinite variant problem
 
-STM32 microcontrollers comes in many families and flavors, and supporting all of them is a big undertaking. Embassy has taken advantage of the fact
+STM32 microcontrollers come in many families, and flavors and supporting all of them is a big undertaking. Embassy has taken advantage of the fact
 that the STM32 peripheral versions are shared across chip families. Instead of re-implementing the SPI
-peripheral for every STM32 chip family, embassy have a single SPI implementation that depends on
+peripheral for every STM32 chip family, embassy has a single SPI implementation that depends on
 code-generated register types that are identical for STM32 families with the same version of a given peripheral.
 
 === The metapac