Merge branch 'main' into rp2040-rtc-alarm

15 files changed, 82 insertions, 35 deletions

diff --git a/docs/examples/basic/Cargo.toml b/docs/examples/basic/Cargo.toml
index 705c334a7..b6dbeda2a 100644
--- a/docs/examples/basic/Cargo.toml
+++ b/docs/examples/basic/Cargo.toml
@@ -5,14 +5,20 @@ name = "embassy-basic-example"
 version = "0.1.0"
 license = "MIT OR Apache-2.0"
 
+publish = false
 [dependencies]
-embassy-executor = { version = "0.7.0", path = "../../../embassy-executor", features = ["defmt", "arch-cortex-m", "executor-thread"] }
-embassy-time = { version = "0.4.0", path = "../../../embassy-time", features = ["defmt"] }
-embassy-nrf = { version = "0.3.1", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] }
+embassy-executor = { version = "0.9.0", path = "../../../embassy-executor", features = ["defmt", "arch-cortex-m", "executor-thread"] }
+embassy-time = { version = "0.5.0", path = "../../../embassy-time", features = ["defmt"] }
+embassy-nrf = { version = "0.7.0", path = "../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] }
 
-defmt = "0.3"
-defmt-rtt = "0.3"
+defmt = "1.0.1"
+defmt-rtt = "1.0.0"
 
 cortex-m = { version = "0.7.6", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7.0"
-panic-probe = { version = "0.3", features = ["print-defmt"] }
+panic-probe = { version = "1.0.0", features = ["print-defmt"] }
+
+[package.metadata.embassy]
+build = [
+  { target = "thumbv7em-none-eabi" }
+]
diff --git a/docs/examples/basic/src/main.rs b/docs/examples/basic/src/main.rs
index 4412712c8..6e274bacb 100644
--- a/docs/examples/basic/src/main.rs
+++ b/docs/examples/basic/src/main.rs
@@ -22,5 +22,5 @@ async fn main(spawner: Spawner) {
     let p = embassy_nrf::init(Default::default());
 
     let led = Output::new(p.P0_13, Level::Low, OutputDrive::Standard);
-    unwrap!(spawner.spawn(blinker(led, Duration::from_millis(300))));
+    spawner.spawn(unwrap!(blinker(led, Duration::from_millis(300))));
 }
diff --git a/docs/examples/layer-by-layer/blinky-async/Cargo.toml b/docs/examples/layer-by-layer/blinky-async/Cargo.toml
index 541eb6edf..ec718022c 100644
--- a/docs/examples/layer-by-layer/blinky-async/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-async/Cargo.toml
@@ -4,12 +4,18 @@ version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 
+publish = false
 [dependencies]
 cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
-embassy-stm32 = { version = "0.2.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x", "exti"]  }
-embassy-executor = { version = "0.7.0", path = "../../../../embassy-executor", features = ["arch-cortex-m", "executor-thread"] }
+embassy-stm32 = { version = "0.4.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x", "exti"]  }
+embassy-executor = { version = "0.9.0", path = "../../../../embassy-executor", features = ["arch-cortex-m", "executor-thread"] }
 
-defmt = "0.3"
-defmt-rtt = "0.4"
-panic-probe = { version = "0.3.0", features = ["print-defmt"] }
+defmt = "1.0.1"
+defmt-rtt = "1.0.0"
+panic-probe = { version = "1.0.0", features = ["print-defmt"] }
+
+[package.metadata.embassy]
+build = [
+  { target = "thumbv7em-none-eabi" }
+]
diff --git a/docs/examples/layer-by-layer/blinky-hal/Cargo.toml b/docs/examples/layer-by-layer/blinky-hal/Cargo.toml
index dd574c3e7..4a0b03a83 100644
--- a/docs/examples/layer-by-layer/blinky-hal/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-hal/Cargo.toml
@@ -4,11 +4,17 @@ version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 
+publish = false
 [dependencies]
 cortex-m-rt = "0.7"
 cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
-embassy-stm32 = { version = "0.2.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x"] }
+embassy-stm32 = { version = "0.4.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x"] }
 
-defmt = "0.3"
-defmt-rtt = "0.4"
-panic-probe = { version = "0.3.0", features = ["print-defmt"] }
+defmt = "1.0.1"
+defmt-rtt = "1.0.0"
+panic-probe = { version = "1.0.0", features = ["print-defmt"] }
+
+[package.metadata.embassy]
+build = [
+  { target = "thumbv7em-none-eabi" }
+]
diff --git a/docs/examples/layer-by-layer/blinky-irq/Cargo.toml b/docs/examples/layer-by-layer/blinky-irq/Cargo.toml
index 8733ee894..3c4bf8446 100644
--- a/docs/examples/layer-by-layer/blinky-irq/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-irq/Cargo.toml
@@ -6,11 +6,17 @@ version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 
+publish = false
 [dependencies]
 cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = { version = "0.7" }
-embassy-stm32 = { version = "0.2.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x", "unstable-pac"] }
+embassy-stm32 = { version = "0.4.0", path = "../../../../embassy-stm32", features = ["stm32l475vg", "memory-x", "unstable-pac"] }
 
-defmt = "0.3"
-defmt-rtt = "0.4"
-panic-probe = { version = "0.3.0", features = ["print-defmt"] }
+defmt = "1.0.1"
+defmt-rtt = "1.0.0"
+panic-probe = { version = "1.0.0", features = ["print-defmt"] }
+
+[package.metadata.embassy]
+build = [
+  { target = "thumbv7em-none-eabi" }
+]
diff --git a/docs/examples/layer-by-layer/blinky-pac/Cargo.toml b/docs/examples/layer-by-layer/blinky-pac/Cargo.toml
index 155c41ec6..0d4711da2 100644
--- a/docs/examples/layer-by-layer/blinky-pac/Cargo.toml
+++ b/docs/examples/layer-by-layer/blinky-pac/Cargo.toml
@@ -4,11 +4,17 @@ version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 
+publish = false
 [dependencies]
 cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
 stm32-metapac = { version = "16", features = ["stm32l475vg"] }
 
-defmt = "0.3"
-defmt-rtt = "0.4"
-panic-probe = { version = "0.3.0", features = ["print-defmt"] }
+defmt = "1.0.1"
+defmt-rtt = "1.0.0"
+panic-probe = { version = "1.0.0", features = ["print-defmt"] }
+
+[package.metadata.embassy]
+build = [
+  { target = "thumbv7em-none-eabi" }
+]
diff --git a/docs/index.adoc b/docs/index.adoc
index 9c6150196..80754d5a4 100644
--- a/docs/index.adoc
+++ b/docs/index.adoc
@@ -5,6 +5,7 @@
 :toc-placement: left
 :toclevels: 2
 :imagesdir: images
+:source-highlighter: rouge
 
 # Embassy Book
 
diff --git a/docs/pages/bootloader.adoc b/docs/pages/bootloader.adoc
index 53f85d995..b0f0331aa 100644
--- a/docs/pages/bootloader.adoc
+++ b/docs/pages/bootloader.adoc
@@ -2,6 +2,13 @@
 
 `embassy-boot` a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.
 
+The update method used is referred to as an A/B partition update scheme.
+
+With a general-purpose OS, A/B partition update is accomplished by directly booting either the A or B partition depending on the update state.
+To accomplish the same goal in a way that is portable across all microcontrollers, `embassy-boot` swaps data page by page (in both directions) between the DFU and the Active partition when a firmware update is triggered. +
+Because the original Active application is moved into the DFU partition during this update, the operation can be reversed if the update is interrupted or the new firmware does not flag that it booted successfully. +
+See the design section for more details on how this is implemented.
+
 The bootloader can be used either as a library or be flashed directly if you are happy with the default configuration and capabilities.
 
 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.
diff --git a/docs/pages/embassy_in_the_wild.adoc b/docs/pages/embassy_in_the_wild.adoc
index 620794c31..cedbedada 100644
--- a/docs/pages/embassy_in_the_wild.adoc
+++ b/docs/pages/embassy_in_the_wild.adoc
@@ -2,6 +2,10 @@
 
 Here are known examples of real-world projects which make use of Embassy. Feel free to link:https://github.com/embassy-rs/embassy/blob/main/docs/pages/embassy_in_the_wild.adoc[add more]!
 
+_newer entries at the top_
+
+* link:https://github.com/CarlKCarlK/clock[Embassy Clock: Layered, modular bare-metal clock with emulation]
+** A `no_std` Raspberry Pi Pico clock demonstrating layered Embassy tasks (Display->Blinker->Clock) for clean separation of multiplexing, blinking, and UI logic. Features single-button HH:MM/MM:SS time-set UI, heapless data structures, and a Renode emulator for hardware-free testing. See link:https://medium.com/@carlmkadie/how-rust-embassy-shine-on-embedded-devices-part-2-aad1adfccf72[this article] for details.
 * link:https://github.com/1-rafael-1/simple-robot[A simple tracked robot based on Raspberry Pi Pico 2]
 ** A hobbyist project building a tracked robot with basic autonomous and manual drive mode.
 * link:https://github.com/1-rafael-1/pi-pico-alarmclock-rust[A Raspberry Pi Pico W Alarmclock]
diff --git a/docs/pages/faq.adoc b/docs/pages/faq.adoc
index b21be9a30..8098e12ac 100644
--- a/docs/pages/faq.adoc
+++ b/docs/pages/faq.adoc
@@ -6,16 +6,16 @@ Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit
 
 == How to deploy to RP2040 or RP235x without a debugging probe.
 
-Install link:https://github.com/JoNil/elf2uf2-rs[elf2uf2-rs] for converting the generated elf binary into a uf2 file.
+Install link:https://github.com/raspberrypi/pico-sdk-tools/releases[Picotool] for uploading the binary.
 
 Configure the runner to use this tool, add this to `.cargo/config.toml`:
 [source,toml]
 ----
 [target.'cfg(all(target_arch = "arm", target_os = "none"))']
-runner = "elf2uf2-rs --deploy --serial --verbose"
+runner = "picotool load --update --verify --execute -t elf"
 ----
 
-The command-line parameters `--deploy` will detect your device and upload the binary, `--serial` starts a serial connection. See the documentation for more info.
+Picotool will detect your device and upload the binary, skipping identical flash sectors (the `--update` command-line flag), verify that the binary was written correctly (`--verify`), and then run your new code (`--execute`). Run `picotool help load` for more information.
 
 == Missing main macro
 
@@ -209,7 +209,7 @@ MEMORY
 _stack_start = ORIGIN(RAM) + LENGTH(RAM);
 ```
 
-Please refer to the STM32 documentation for the specific values suitable for your board and setup. The STM32 Cube examples often contain a linker script `.ld` file. 
+Please refer to the STM32 documentation for the specific values suitable for your board and setup. The STM32 Cube examples often contain a linker script `.ld` file.
 Look for the `MEMORY` section and try to determine the FLASH and RAM sizes and section start.
 
 If you find a case where the memory.x is wrong, please report it on link:https://github.com/embassy-rs/stm32-data/issues/301[this Github issue] so other users are not caught by surprise.
@@ -334,7 +334,7 @@ There are two main ways to handle concurrency in Embassy:
 
 In general, either of these approaches will work. The main differences of these approaches are:
 
-When using **separate tasks**, each task needs its own RAM allocation, so there's a little overhead for each task, so one task that does three things will likely be a little bit smaller than three tasks that do one thing (not a lot, probably a couple dozen bytes). In contrast, with **multiple futures in one task**, you don't need multiple task allocations, and it will generally be easier to share data, or use borrowed resources, inside of a single task. 
+When using **separate tasks**, each task needs its own RAM allocation, so there's a little overhead for each task, so one task that does three things will likely be a little bit smaller than three tasks that do one thing (not a lot, probably a couple dozen bytes). In contrast, with **multiple futures in one task**, you don't need multiple task allocations, and it will generally be easier to share data, or use borrowed resources, inside of a single task.
 An example showcasing some methods for sharing things between tasks link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here].
 
 But when it comes to "waking" tasks, for example when a data transfer is complete or a button is pressed, it's faster to wake a dedicated task, because that task does not need to check which future is actually ready. `join` and `select` must check ALL of the futures they are managing to see which one (or which ones) are ready to do more work. This is because all Rust executors (like Embassy or Tokio) only have the ability to wake tasks, not specific futures. This means you will use slightly less CPU time juggling futures when using dedicated tasks.
diff --git a/docs/pages/imxrt.adoc b/docs/pages/imxrt.adoc
index adf5218e8..87867e1e0 100644
--- a/docs/pages/imxrt.adoc
+++ b/docs/pages/imxrt.adoc
@@ -9,5 +9,8 @@ The link: link:https://github.com/embassy-rs/embassy/tree/main/embassy-imxrt[Emb
 
 The following peripherals have a HAL implementation at present
 
+* CRC
+* DMA
 * GPIO
-
+* RNG
+* UART
diff --git a/docs/pages/layer_by_layer.adoc b/docs/pages/layer_by_layer.adoc
index 7dba11b5e..0692ee4fa 100644
--- a/docs/pages/layer_by_layer.adoc
+++ b/docs/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 provides distinct types to make accessing peripheral registers easier, but it does not prevent you from writing unsafe code.
+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 little to prevent you from configuring or coordinating those registers incorrectly.
 
 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.
 
diff --git a/docs/pages/new_project.adoc b/docs/pages/new_project.adoc
index cd943b4f6..906d89f36 100644
--- a/docs/pages/new_project.adoc
+++ b/docs/pages/new_project.adoc
@@ -11,6 +11,8 @@ Once you’ve successfully xref:#_getting_started[run some example projects], th
 - link:https://github.com/lulf/embassy-template[embassy-template] (STM32, NRF, and RP)
 - link:https://github.com/bentwire/embassy-rp2040-template[embassy-rp2040-template] (RP)
 
+=== esp-generate
+- link:https://github.com/esp-rs/esp-generate[esp-generate] (ESP32 using esp-hal)
 
 == Starting a project from scratch
 
diff --git a/docs/pages/overview.adoc b/docs/pages/overview.adoc
index acd757795..18eaaeb75 100644
--- a/docs/pages/overview.adoc
+++ b/docs/pages/overview.adoc
@@ -30,7 +30,7 @@ The Embassy project maintains HALs for select hardware, but you can still use HA
 * link:https://docs.embassy.dev/embassy-nrf/[embassy-nrf], for the Nordic Semiconductor nRF52, nRF53, nRF91 series.
 * link:https://docs.embassy.dev/embassy-rp/[embassy-rp], for the Raspberry Pi RP2040 as well as RP235x microcontroller.
 * link:https://docs.embassy.dev/embassy-mspm0/[embassy-mspm0], for the Texas Instruments MSPM0 microcontrollers.
-* link:https://github.com/esp-rs[esp-rs], for the Espressif Systems ESP32 series of chips.
+* link:https://github.com/esp-rs/esp-hal[esp-hal], for the Espressif Systems ESP32 series of chips.
 * link:https://github.com/ch32-rs/ch32-hal[ch32-hal], for the WCH 32-bit RISC-V(CH32V) series of chips.
 * link:https://github.com/AlexCharlton/mpfs-hal[mpfs-hal], for the Microchip PolarFire SoC.
 * link:https://github.com/py32-rs/py32-hal[py32-hal], for the Puya Semiconductor PY32 series of chips.
diff --git a/docs/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc
index dfb8c1ffe..70b4210e6 100644
--- a/docs/pages/sharing_peripherals.adoc
+++ b/docs/pages/sharing_peripherals.adoc
@@ -36,8 +36,8 @@ async fn main(spawner: Spawner) {
     let dt = 100 * 1_000_000;
     let k = 1.003;
 
-    unwrap!(spawner.spawn(toggle_led(&LED, Duration::from_nanos(dt))));
-    unwrap!(spawner.spawn(toggle_led(&LED, Duration::from_nanos((dt as f64 * k) as u64))));
+    spawner.spawn(unwrap!(toggle_led(&LED, Duration::from_nanos(dt))));
+    spawner.spawn(unwrap!(toggle_led(&LED, Duration::from_nanos((dt as f64 * k) as u64))));
 }
 
 // A pool size of 2 means you can spawn two instances of this task.
@@ -103,8 +103,8 @@ async fn main(spawner: Spawner) {
     let dt = 100 * 1_000_000;
     let k = 1.003;
 
-    unwrap!(spawner.spawn(toggle_led(CHANNEL.sender(), Duration::from_nanos(dt))));
-    unwrap!(spawner.spawn(toggle_led(CHANNEL.sender(), Duration::from_nanos((dt as f64 * k) as u64))));
+    spawner.spawn(unwrap!(toggle_led(CHANNEL.sender(), Duration::from_nanos(dt))));
+    spawner.spawn(unwrap!(toggle_led(CHANNEL.sender(), Duration::from_nanos((dt as f64 * k) as u64))));
 
     loop {
         match CHANNEL.receive().await {