Merge branch 'main' into u0-lcd

17 files changed, 211 insertions, 85 deletions

diff --git a/docs/pages/basic_application.adoc b/docs/pages/basic_application.adoc
index 7b4ebda4f..5c4e3e8b3 100644
--- a/docs/pages/basic_application.adoc
+++ b/docs/pages/basic_application.adoc
@@ -4,7 +4,7 @@ So you've got one of the examples running, but what now? Let's go through a simp
 
 == Main
 
-The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/examples/basic[here].
+The full example can be found link:https://github.com/embassy-rs/embassy/tree/main/docs/examples/basic[here].
 
 NOTE: If you’re using VS Code and rust-analyzer to view and edit the examples, you may need to make some changes to `.vscode/settings.json` to tell it which project we’re working on. Follow the instructions commented in that file to get rust-analyzer working correctly.
 
diff --git a/docs/pages/best_practices.adoc b/docs/pages/best_practices.adoc
index bfcedec06..eabaa9eb9 100644
--- a/docs/pages/best_practices.adoc
+++ b/docs/pages/best_practices.adoc
@@ -35,7 +35,7 @@ After the processing, another 1024 byte buffer will be placed on the stack to be
 
 Pass the data by reference and not by value on both, the way in and the way out.
 For example, you could return a slice of the input buffer as the output.
-Requiring the lifetime of the input slice and the output slice to be the same, the memory safetly of this procedure will be enforced by the compiler.
+Requiring the lifetime of the input slice and the output slice to be the same, the memory safety of this procedure will be enforced by the compiler.
 
 [,rust]
 ----
diff --git a/docs/pages/bootloader.adoc b/docs/pages/bootloader.adoc
index 3b0cdb182..c010b0622 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.
@@ -19,6 +26,8 @@ The bootloader supports
 
 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.
 
+STM32L0x1 devices require the `flash-erase-zero` feature to be enabled.
+
 == Design
 
 image::bootloader_flash.png[Bootloader flash layout]
@@ -34,14 +43,14 @@ 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:
+* 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 is given by:
 +
-Partition Size~state~ = Write Size~state~ + (2 × Partition Size~active~ / Page Size~active~)
+Partition Size~state~ = (2 × Write Size~state~) + (4 × Write Size~state~ × 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_STATE partition must be big enough to store two words, plus four words per page in the ACTIVE partition.
 
 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.
 
@@ -86,8 +95,7 @@ Then, to sign your firmware given a declaration of `FIRMWARE_DIR` and a firmware
 
 [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
+shasum -a 512 -b $FIRMWARE_DIR/myfirmware | head -c128 | 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
diff --git a/docs/pages/embassy_in_the_wild.adoc b/docs/pages/embassy_in_the_wild.adoc
index 76b1169bd..0792130eb 100644
--- a/docs/pages/embassy_in_the_wild.adoc
+++ b/docs/pages/embassy_in_the_wild.adoc
@@ -2,8 +2,22 @@
 
 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/thataquarel/protovolt[ProtoV MINI: A USB-C mini lab power supply]
+** A dual-channel USB PD powered breadboard power supply based on the RP2040, running embedded graphics. Open-source schematics and firmware.
+* link:https://github.com/Dawson-HEP/opentrig/[Opentrig: A particle physics trigger and data acquisition system]
+** Digital event trigger with threshold, data acquisition system designed to interface with AIDA-2020 TLU systems, tested at the DESY II Test Beam Facility. Based on the RP2040, and Embassy's async event handling.
+* link:https://github.com/1-rafael-1/air-quality-monitor[Air Quality Monitor]
+** Air Quality Monitor based on rp2350 board, ens160 and aht21 sensors and ssd1306 display. Code and 3D printable enclosure included.
+* 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]
+** A hobbyist project building an alarm clock around a Pi Pico W complete with code, components list and enclosure design files.
 * link:https://github.com/haobogu/rmk/[RMK: A feature-rich Rust keyboard firmware]
-** RMK has built-in layer support, wireless(BLE) support, real-time key editing support using vial, and more! 
+** RMK has built-in layer support, wireless(BLE) support, real-time key editing support using vial, and more!
 ** Targets STM32, RP2040, nRF52 and ESP32 MCUs
 * link:https://github.com/cbruiz/printhor/[Printhor: The highly reliable but not necessarily functional 3D printer firmware]
 ** Targets some STM32 MCUs
@@ -13,10 +27,9 @@ Here are known examples of real-world projects which make use of Embassy. Feel f
 * link:https://github.com/matoushybl/air-force-one[Air force one: A simple air quality monitoring system]
 ** Targets nRF52 and uses nrf-softdevice
 
-* link:https://github.com/schmettow/ylab-edge-go[YLab Edge Go] and link:https://github.com/schmettow/ylab-edge-pro[YLab Edge Pro] projects develop 
+* link:https://github.com/schmettow/ylab-edge-go[YLab Edge Go] and link:https://github.com/schmettow/ylab-edge-pro[YLab Edge Pro] projects develop
 firmware (RP2040, STM32) for capturing physiological data in behavioural science research. Included so far are:
 ** biopotentials (analog ports)
 ** motion capture (6-axis accelerometers)
 ** air quality (CO2, Temp, Humidity)
 ** comes with an app for capturing and visualizing data [link:https://github.com/schmettow/ystudio-zero[Ystudio]]
-
diff --git a/docs/pages/faq.adoc b/docs/pages/faq.adoc
index a2f56a539..8098e12ac 100644
--- a/docs/pages/faq.adoc
+++ b/docs/pages/faq.adoc
@@ -4,18 +4,18 @@ These are a list of unsorted, commonly asked questions and answers.
 
 Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit/main/docs/pages/faq.adoc[this page], especially if someone in the chat answered a question for you!
 
-== How to deploy to RP2040 without a debugging probe.
+== 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
 
@@ -92,17 +92,9 @@ If you see linker error like this:
           >>> referenced by driver.rs:127 (src/driver.rs:127)
           >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::now::hefb1f99d6e069842) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib
 
-          rust-lld: error: undefined symbol: _embassy_time_allocate_alarm
-          >>> referenced by driver.rs:134 (src/driver.rs:134)
-          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::allocate_alarm::hf5145b6bd46706b2) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib
-
-          rust-lld: error: undefined symbol: _embassy_time_set_alarm_callback
-          >>> referenced by driver.rs:139 (src/driver.rs:139)
-          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::set_alarm_callback::h24f92388d96eafd2) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib
-
-          rust-lld: error: undefined symbol: _embassy_time_set_alarm
+          rust-lld: error: undefined symbol: _embassy_time_schedule_wake
           >>> referenced by driver.rs:144 (src/driver.rs:144)
-          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::set_alarm::h530a5b1f444a6d5b) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib
+          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::schedule_wake::h530a5b1f444a6d5b) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib
 ----
 
 You probably need to enable a time driver for your HAL (not in `embassy-time`!). For example with `embassy-stm32`, you might need to enable `time-driver-any`:
@@ -125,6 +117,20 @@ If you are in the early project setup phase and not using anything from the HAL,
 use embassy_stm32 as _;
 ----
 
+Another common error you may experience is:
+
+[source,text]
+----
+ = note: rust-lld: error: undefined symbol: __pender
+          >>> referenced by mod.rs:373 (src/raw/mod.rs:373)
+          >>>               embassy_executor-e78174e249bca7f4.embassy_executor.1e9d60fc90940543-cgu.0.rcgu.o:(embassy_executor::raw::Pender::pend::h0f19b6e01762e4cd) in archive [...]libembassy_executor-e78174e249bca7f4.rlib
+----
+
+There are two possible causes to this error:
+
+* You are using `embassy-executor` withuout enabling one of the architecture-specific features, but you are using a HAL that does not bring its own executors. For example, for Cortex-M (like the RP2040), you need to enable the `arch-cortex-m` feature of `embassy-executor`.
+* You are not using `embassy-executor`. In this case, you need to enable the one of the `generic-queue-X` features of `embassy-time`.
+
 == Error: `Only one package in the dependency graph may specify the same links value.`
 
 You have multiple versions of the same crate in your dependency tree. This means that some of your
@@ -140,9 +146,9 @@ Example:
 [source,toml]
 ----
 [patch.crates-io]
-embassy-time-queue-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
-embassy-time-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
-# embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+embassy-time-queue-utils = { git = "https://github.com/embassy-rs/embassy.git", rev = "7f8af8a" }
+embassy-time-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "7f8af8a" }
+# embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "7f8af8a" }
 ----
 
 Note that the git revision should match any other embassy patches or git dependencies that you are using!
@@ -158,35 +164,11 @@ Note that the git revision should match any other embassy patches or git depende
 * Set the following keys in the `[unstable]` section of your `.cargo/config.toml`
     ** `build-std = ["core"]`
     ** `build-std-features = ["panic_immediate_abort"]`
-* Enable feature `embassy-time/generic-queue`, disable feature `embassy-executor/integrated-timers`
 * When using `InterruptExecutor`:
     ** disable `executor-thread`
-    ** make `main`` spawn everything, then enable link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html#method.set_sleeponexit[SCB.SLEEPONEXIT] and `loop { cortex_m::asm::wfi() }`
+    ** make `main` spawn everything, then enable link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html#method.set_sleeponexit[SCB.SLEEPONEXIT] and `loop { cortex_m::asm::wfi() }`
     ** *Note:*  If you need 2 priority levels, using 2 interrupt executors is better than 1 thread executor + 1 interrupt executor.
 
-== How do I set up the task arenas on stable?
-
-When you aren't using the `nightly` feature of `embassy-executor`, the executor uses a bump allocator, which may require configuration.
-
-Something like this error will occur at **compile time** if the task arena is *too large* for the target's RAM:
-
-[source,plain]
-----
-rust-lld: error: section '.bss' will not fit in region 'RAM': overflowed by _ bytes
-rust-lld: error: section '.uninit' will not fit in region 'RAM': overflowed by _ bytes
-----
-
-And this message will appear at **runtime** if the task arena is *too small* for the tasks running:
-
-[source,plain]
-----
-ERROR panicked at 'embassy-executor: task arena is full. You must increase the arena size, see the documentation for details: https://docs.embassy.dev/embassy-executor/'
-----
-
-NOTE: If all tasks are spawned at startup, this panic will occur immediately.
-
-Check out link:https://docs.embassy.dev/embassy-executor/git/cortex-m/index.html#task-arena[Task Arena Documentation] for more details.
-
 == Can I use manual ISRs alongside Embassy?
 
 Yes! This can be useful if you need to respond to an event as fast as possible, and the latency caused by the usual “ISR, wake, return from ISR, context switch to woken task” flow is too much for your application. Simply define a `#[interrupt] fn INTERRUPT_NAME() {}` handler as you would link:https://docs.rust-embedded.org/book/start/interrupts.html[in any other embedded rust project].
@@ -227,10 +209,10 @@ 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 [this Github issue](https://github.com/embassy-rs/stm32-data/issues/301) so other users are not caught by surprise.
+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.
 
 == The USB examples are not working on my board, is there anything else I need to configure?
 
@@ -286,7 +268,7 @@ General steps:
 1. Find out which memory region BDMA has access to. You can get this information from the bus matrix and the memory mapping table in the STM32 datasheet.
 2. Add the memory region to `memory.x`, you can modify the generated one from https://github.com/embassy-rs/stm32-data-generated/tree/main/data/chips.
 3. You might need to modify `build.rs` to make cargo pick up the modified `memory.x`.
-4. In your code, access the defined memory region using `#[link_section = ".xxx"]`
+4. In your code, access the defined memory region using `#[unsafe(link_section = ".xxx")]`
 5. Copy data to that region before using BDMA.
 
 See link:https://github.com/embassy-rs/embassy/blob/main/examples/stm32h7/src/bin/spi_bdma.rs[SMT32H7 SPI BDMA example] for more details.
@@ -353,7 +335,81 @@ 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.
+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.
 
 Practically, there's not a LOT of difference either way - so go with what makes it easier for you and your code first, but there will be some details that are slightly different in each case.
+
+== splitting peripherals resources between tasks
+
+There are two ways to split resources between tasks, either manually assigned or by a convenient macro. See link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/assign_resources.rs[this example]
+
+== My code/driver works in debug mode, but not release mode (or with LTO)
+
+Issues like these while implementing drivers often fall into one of the following general causes, which are a good list of common errors to check for:
+
+1. Some kind of race condition - the faster code means you miss an interrupt or something
+2. Some kind of UB, if you have unsafe code, or something like DMA with fences missing
+3. Some kind of hardware errata, or some hardware misconfiguration like wrong clock speeds
+4. Some issue with an interrupt handler, either enabling, disabling, or re-enabling of interrupts when necessary
+5. Some kind of async issue, like not registering wakers fully before checking flags, or not registering or pending wakers at the right time
+
+== How can I prevent the thread-mode executor from going to sleep? ==
+
+In some cases you might want to prevent the thread-mode executor from going to sleep, for example when doing so would result in current spikes that reduce analog performance.
+As a workaround, you can spawn a task that yields in a loop, preventing the executor from going to sleep. Note that this may increase power consumption.
+
+[source,rust]
+----
+#[embassy_executor::task]
+async fn idle() {
+    loop { embassy_futures::yield_now().await; }
+}
+----
+
+== Why is my bootloader restarting in loop?
+
+== Troubleshooting Bootloader Restart Loops
+
+If your bootloader restarts in a loop, there could be multiple reasons. Here are some things to check:
+
+=== Validate the `memory.x` File
+The bootloader performs critical checks when creating partitions using the addresses defined in `memory.x`. Ensure the following assertions hold true:
+
+[source,rust]
+----
+const {
+    core::assert!(Self::PAGE_SIZE % ACTIVE::WRITE_SIZE as u32 == 0);
+    core::assert!(Self::PAGE_SIZE % ACTIVE::ERASE_SIZE as u32 == 0);
+    core::assert!(Self::PAGE_SIZE % DFU::WRITE_SIZE as u32 == 0);
+    core::assert!(Self::PAGE_SIZE % DFU::ERASE_SIZE as u32 == 0);
+}
+
+// Ensure enough progress pages to store copy progress
+assert_eq!(0, Self::PAGE_SIZE % aligned_buf.len() as u32);
+assert!(aligned_buf.len() >= STATE::WRITE_SIZE);
+assert_eq!(0, aligned_buf.len() % ACTIVE::WRITE_SIZE);
+assert_eq!(0, aligned_buf.len() % DFU::WRITE_SIZE);
+----
+
+If any of these assertions fail, the bootloader will likely restart in a loop. This failure might not log any messages (e.g., when using `defmt`). Confirm that your `memory.x` file and flash memory align with these requirements.
+
+=== Handling Panic Logging
+Some panic errors might log messages, but certain microcontrollers reset before the message is fully printed. To ensure panic messages are logged, add a delay using no-operation (NOP) instructions before the reset:
+
+[source,rust]
+----
+#[panic_handler]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+    for _ in 0..10_000_000 {
+        cortex_m::asm::nop();
+    }
+    cortex_m::asm::udf();
+}
+----
+
+=== Feed the watchdog
+
+
+Some `embassy-boot` implementations (like `embassy-boot-nrf` and `embassy-boot-rp`) rely on a watchdog timer to detect application failure. The bootloader will restart if your application code does not properly feed the watchdog timer. Make sure to feed it correctly.
diff --git a/docs/pages/getting_started.adoc b/docs/pages/getting_started.adoc
index 017409018..d1f65a885 100644
--- a/docs/pages/getting_started.adoc
+++ b/docs/pages/getting_started.adoc
@@ -66,7 +66,7 @@ If everything worked correctly, you should see a blinking LED on your board, and
 [source]
 ----
     Finished dev [unoptimized + debuginfo] target(s) in 1m 56s
-     Running `probe-run --chip STM32F407VGTx target/thumbv7em-none-eabi/debug/blinky`
+     Running `probe-rs run --chip STM32F407VGTx target/thumbv7em-none-eabi/debug/blinky`
 (HOST) INFO  flashing program (71.36 KiB)
 (HOST) INFO  success!
 ────────────────────────────────────────────────────────────────────────────────
@@ -86,7 +86,7 @@ NOTE: How does the `+cargo run+` command know how to connect to our board and pr
 
 === It didn’t work!
 
-If you hare having issues when running `+cargo run --release+`, please check the following:
+If you are having issues when running `+cargo run --release+`, please check the following:
 
 * You are specifying the correct `+--chip+` on the command line, OR
 * You have set `+.cargo/config.toml+`’s run line to the correct chip, AND
diff --git a/docs/pages/hal.adoc b/docs/pages/hal.adoc
index 14b85e1f1..3bbe94e02 100644
--- a/docs/pages/hal.adoc
+++ b/docs/pages/hal.adoc
@@ -4,7 +4,7 @@ Embassy provides HALs for several microcontroller families:
 
 * `embassy-nrf` for the nRF microcontrollers from Nordic Semiconductor
 * `embassy-stm32` for STM32 microcontrollers from ST Microelectronics
-* `embassy-rp` for the Raspberry Pi RP2040 microcontrollers
+* `embassy-rp` for the Raspberry Pi RP2040 and RP235x microcontrollers
 
 These HALs implement async/await functionality for most peripherals while also implementing the
 async traits in `embedded-hal` and `embedded-hal-async`. You can also use these HALs with another executor.
@@ -12,3 +12,7 @@ async traits in `embedded-hal` and `embedded-hal-async`. You can also use these
 For the ESP32 series, there is an link:https://github.com/esp-rs/esp-hal[esp-hal] which you can use.
 
 For the WCH 32-bit RISC-V series, there is an link:https://github.com/ch32-rs/ch32-hal[ch32-hal], which you can use.
+
+For the Microchip PolarFire SoC, there is link:https://github.com/AlexCharlton/mpfs-hal[mpfs-hal].
+
+For the Puya Semiconductor PY32 series, there is link:https://github.com/py32-rs/py32-hal[py32-hal].
\ No newline at end of file
diff --git a/docs/pages/imxrt.adoc b/docs/pages/imxrt.adoc
new file mode 100644
index 000000000..87867e1e0
--- /dev/null
+++ b/docs/pages/imxrt.adoc
@@ -0,0 +1,16 @@
+= Embassy iMXRT HAL
+
+The link: link:https://github.com/embassy-rs/embassy/tree/main/embassy-imxrt[Embassy iMXRT HAL] is based on the following PACs (Peripheral Access Crate):
+
+* link:https://github.com/OpenDevicePartnership/mimxrt685s-pac[mimxrt685s-pac]
+* link:https://github.com/OpenDevicePartnership/mimxrt633s-pac[mimxrt633s-pac]
+
+== Peripherals
+
+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 f87291c20..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.
 
@@ -76,7 +76,7 @@ The async version looks very similar to the HAL version, apart from a few minor
 * The peripheral initialization is done by the main macro, and is handed to the main task.
 * Before checking the button state, the application is awaiting a transition in the pin state (low -> high or high -> low).
 
-When `button.await_for_any_edge().await` is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. Internally, the Embassy HAL has configured the interrupt handler for the button (in `ExtiButton`), so that whenever an interrupt is raised, the task awaiting the button will be woken up.
+When `button.wait_for_any_edge().await` is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. Internally, the Embassy HAL has configured the interrupt handler for the button (in `ExtiInput`), so that whenever an interrupt is raised, the task awaiting the button will be woken up.
 
 The minimal overhead of the executor and the ability to run multiple tasks "concurrently" combined with the enormous simplification of the application, makes `async` a great fit for embedded.
 
diff --git a/docs/pages/new_project.adoc b/docs/pages/new_project.adoc
index 346d9f0f8..906d89f36 100644
--- a/docs/pages/new_project.adoc
+++ b/docs/pages/new_project.adoc
@@ -1,6 +1,6 @@
 = Starting a new project
 
-Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project.
+Once you’ve successfully xref:#_getting_started[run some example projects], the next step is to make a standalone Embassy project.
 
 == Tools for generating Embassy projects
 
@@ -11,6 +11,8 @@ Once you’ve successfully xref:getting_started.adoc[run some example projects],
 - 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
 
@@ -73,22 +75,34 @@ Now that cargo knows what target to compile for (and probe-rs knows what chip to
 
 Looking in `examples/stm32g4/Cargo.toml`, we can see that the examples require a number of embassy crates. For blinky, we’ll only need three of them: `embassy-stm32`, `embassy-executor` and `embassy-time`.
 
-At the time of writing, the latest version of embassy isn‘t available on crates.io, so we need to install it straight from the git repository. The recommended way of doing so is as follows:
+
+At the time of writing, embassy is already published to crates.io. Therefore, dependencies can easily added via Cargo.toml.
+
+[source,toml]
+----
+[dependencies]
+embassy-stm32 = { version = "0.1.0", features =  ["defmt", "time-driver-any", "stm32g474re", "memory-x", "unstable-pac", "exti"] }
+embassy-executor = { version = "0.6.3", features = ["nightly", "arch-cortex-m", "executor-thread", "defmt"] }
+embassy-time = { version = "0.3.2", features = ["defmt", "defmt-timestamp-uptime", "tick-hz-32_768"] }
+----
+
+Prior, embassy needed to be installed straight from the git repository. Installing from git is still useful, if you want to checkout a specic revision of an embassy crate which is not yet published.
+The recommended way of doing so is as follows:
 
 * Copy the required `embassy-*` lines from the example `Cargo.toml`
 * Make any necessary changes to `features`, e.g. requiring the `stm32g474re` feature of `embassy-stm32`
 * Remove the `path = ""` keys in the `embassy-*` entries
 * Create a `[patch.crates-io]` section, with entries for each embassy crate we need. These should all contain identical values: a link to the git repository, and a reference to the commit we’re checking out. Assuming you want the latest commit, you can find it by running `git ls-remote https://github.com/embassy-rs/embassy.git HEAD`
 
-NOTE: When using this method, it’s necessary that the `version` keys in `[dependencies]` match up with the versions defined in each crate’s `Cargo.toml` in the specificed `rev` under `[patch.crates.io]`. This means that when updating, you have to a pick a new revision, change everything in `[patch.crates.io]` to match it, and then correct any versions under `[dependencies]` which have changed. Hopefully this will no longer be necessary once embassy is released on crates.io!
+NOTE: When using this method, it’s necessary that the `version` keys in `[dependencies]` match up with the versions defined in each crate’s `Cargo.toml` in the specificed `rev` under `[patch.crates.io]`. This means that when updating, you have to a pick a new revision, change everything in `[patch.crates.io]` to match it, and then correct any versions under `[dependencies]` which have changed.
 
-At the time of writing, this method produces the following results:
+An example Cargo.toml file might look as follows:
 
 [source,toml]
 ----
 [dependencies]
 embassy-stm32 = {version = "0.1.0", features =  ["defmt", "time-driver-any", "stm32g474re", "memory-x", "unstable-pac", "exti"]}
-embassy-executor = { version = "0.3.3", features = ["nightly", "arch-cortex-m", "executor-thread", "defmt", "integrated-timers"] }
+embassy-executor = { version = "0.3.3", features = ["nightly", "arch-cortex-m", "executor-thread", "defmt"] }
 embassy-time = { version = "0.2", features = ["defmt", "defmt-timestamp-uptime", "tick-hz-32_768"] }
 
 [patch.crates-io]
@@ -97,7 +111,7 @@ embassy-executor = { git = "https://github.com/embassy-rs/embassy", rev = "7703f
 embassy-stm32 = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" }
 ----
 
-There are a few other dependencies we need to build the project, but fortunately they’re much simpler to install. Copy their lines from the example `Cargo.toml` to the the `[dependencies]` section in the new `Cargo.toml`:
+There are a few other dependencies we need to build the project, but fortunately they’re much simpler to install. Copy their lines from the example `Cargo.toml` to the `[dependencies]` section in the new `Cargo.toml`:
 
 [source,toml]
 ----
@@ -138,7 +152,7 @@ stm32g474-example
 # Before upgrading check that everything is available on all tier1 targets here:
 # https://rust-lang.github.io/rustup-components-history
 [toolchain]
-channel = "nightly-2023-11-01"
+channel = "1.85"
 components = [ "rust-src", "rustfmt", "llvm-tools", "miri" ]
 targets = ["thumbv7em-none-eabi"]
 ----
diff --git a/docs/pages/nrf.adoc b/docs/pages/nrf.adoc
index 1706087ae..de052b63f 100644
--- a/docs/pages/nrf.adoc
+++ b/docs/pages/nrf.adoc
@@ -1,6 +1,6 @@
 = Embassy nRF HAL
 
-The link:https://github.com/embassy-rs/embassy/tree/master/embassy-nrf[Embassy nRF HAL] is based on the PACs (Peripheral Access Crate) from link:https://github.com/nrf-rs/[nrf-rs].
+The link:https://github.com/embassy-rs/embassy/tree/main/embassy-nrf[Embassy nRF HAL] is based on the PACs (Peripheral Access Crate) from link:https://github.com/nrf-rs/[nrf-rs].
 
 == Timer driver
 
diff --git a/docs/pages/overview.adoc b/docs/pages/overview.adoc
index 1b9381bfe..18eaaeb75 100644
--- a/docs/pages/overview.adoc
+++ b/docs/pages/overview.adoc
@@ -6,7 +6,7 @@ Embassy is a project to make async/await a first-class option for embedded devel
 
 When handling I/O, software must call functions that block program execution until the I/O operation completes. When running inside of an OS such as Linux, such functions generally transfer control to the kernel so that another task (known as a “thread”) can be executed if available, or the CPU can be put to sleep until another task is ready.
 
-Because an OS cannot presume that threads will behave cooperatively, threads are relatively resource-intensive, and may be forcibly interrupted they do not transfer control back to the kernel within an allotted time. If tasks could be presumed to behave cooperatively, or at least not maliciously, it would be possible to create tasks that appear to be almost free when compared to a traditional OS thread.
+Because an OS cannot presume that threads will behave cooperatively, threads are relatively resource-intensive, and may be forcibly interrupted if they do not transfer control back to the kernel within an allotted time. If tasks could be presumed to behave cooperatively, or at least not maliciously, it would be possible to create tasks that appear to be almost free when compared to a traditional OS thread.
 
 In other programming languages, these lightweight tasks are known as “coroutines” or ”goroutines”. In Rust, they are implemented with async. Async-await works by transforming each async function into an object called a future. When a future blocks on I/O the future yields, and the scheduler, called an executor, can select a different future to execute.
 
@@ -28,9 +28,12 @@ The Embassy project maintains HALs for select hardware, but you can still use HA
 
 * link:https://docs.embassy.dev/embassy-stm32/[embassy-stm32], for all STM32 microcontroller families.
 * 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 microcontroller.
-* link:https://github.com/esp-rs[esp-rs], for the Espressif Systems ESP32 series of chips.
+* 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-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.
 
 NOTE: A common question is if one can use the Embassy HALs standalone. Yes, it is possible! There are no dependency on the executor within the HALs. You can even use them without async,
 as they implement both the link:https://github.com/rust-embedded/embedded-hal[Embedded HAL] blocking and async traits.
@@ -48,11 +51,11 @@ link:https://github.com/lora-rs/lora-rs[lora-rs] supports LoRa networking on a w
 link:https://docs.embassy.dev/embassy-usb/[embassy-usb] implements a device-side USB stack. Implementations for common classes such as USB serial (CDC ACM) and USB HID are available, and a rich builder API allows building your own.
 
 === Bootloader and DFU
-link:https://github.com/embassy-rs/embassy/tree/master/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.
+link:https://github.com/embassy-rs/embassy/tree/main/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.
 
 == What is DMA?
 
-For most I/O in embedded devices, the peripheral doesn't directly support the transmission of multiple bits at once, with CAN being a notable exception. Instead, the MCU must write each byte, one at a time, and then wait until the peripheral is ready to send the next. For high I/O rates, this can pose a problem if the MCU must devote an increasing portion of its time handling each byte. The solution to this problem is to use the Direct Memory Access controller.
+For most I/O in embedded devices, the peripheral doesn't directly support the transmission of multiple bytes at once, with CAN being a notable exception. Instead, the MCU must write each byte, one at a time, and then wait until the peripheral is ready to send the next. For high I/O rates, this can pose a problem if the MCU must devote an increasing portion of its time handling each byte. The solution to this problem is to use the Direct Memory Access controller.
 
 The Direct Memory Access controller (DMA) is a controller that is present in MCUs that Embassy supports, including stm32 and nrf. The DMA allows the MCU to set up a transfer, either send or receive, and then wait for the transfer to complete. With DMA, once started, no MCU intervention is required until the transfer is complete, meaning that the MCU can perform other computation, or set up other I/O while the transfer is in progress. For high I/O rates, DMA can cut the time that the MCU spends handling I/O by over half. However, because DMA is more complex to set-up, it is less widely used in the embedded community. Embassy aims to change that by making DMA the first choice rather than the last. Using Embassy, there's no additional tuning required once I/O rates increase because your application is already set-up to handle them.
 
@@ -74,6 +77,11 @@ include::embassy_in_the_wild.adoc[leveloffset = 2]
 
 For more reading material on async Rust and Embassy:
 
-* link:https://tweedegolf.nl/en/blog/65/async-rust-vs-rtos-showdown[Comparsion of FreeRTOS and Embassy]
+* link:https://tweedegolf.nl/en/blog/65/async-rust-vs-rtos-showdown[Comparison of FreeRTOS and Embassy]
 * link:https://dev.to/apollolabsbin/series/20707[Tutorials]
 * link:https://blog.drogue.io/firmware-updates-part-1/[Firmware Updates with Embassy]
+
+Videos:
+
+* link:https://www.youtube.com/watch?v=pDd5mXBF4tY[Intro to Embassy]
+* link:https://www.youtube.com/watch?v=wni5h5vIPhU[From Zero to Async in Embedded Rust]
diff --git a/docs/pages/project_structure.adoc b/docs/pages/project_structure.adoc
index 722ec8d9d..227508b97 100644
--- a/docs/pages/project_structure.adoc
+++ b/docs/pages/project_structure.adoc
@@ -85,9 +85,9 @@ A minimal example:
 [source,toml]
 ----
 [toolchain]
-channel = "nightly-2023-08-19" # <- as of writing, this is the exact rust version embassy uses
+channel = "1.85" # <- as of writing, this is the exact rust version embassy uses
 components = [ "rust-src", "rustfmt" ] # <- optionally add "llvm-tools-preview" for some extra features like "cargo size"
 targets = [
-    "thumbv6m-none-eabi" # <-change for your platform
+    "thumbv6m-none-eabi" # <- change for your platform
 ]
 ----
diff --git a/docs/pages/sharing_peripherals.adoc b/docs/pages/sharing_peripherals.adoc
index 6bcd56b01..70b4210e6 100644
--- a/docs/pages/sharing_peripherals.adoc
+++ b/docs/pages/sharing_peripherals.adoc
@@ -8,7 +8,7 @@ The following examples shows different ways to use the on-board LED on a Raspber
 
 Using mutual exclusion is the simplest way to share a peripheral.
 
-TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here].
+TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here].
 [,rust]
 ----
 use defmt::*;
@@ -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.
@@ -78,7 +78,7 @@ To indicate that the pin will be set to an Output. The `AnyPin` could have been
 
 A channel is another way to ensure exclusive access to a resource. Using a channel is great in the cases where the access can happen at a later point in time, allowing you to enqueue operations and do other things.
 
-TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here].
+TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here].
 [,rust]
 ----
 use defmt::*;
@@ -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 {
@@ -126,3 +126,9 @@ async fn toggle_led(control: Sender<'static, ThreadModeRawMutex, LedState, 64>,
 
 This example replaces the Mutex with a Channel, and uses another task (the main loop) to drive the LED. The advantage of this approach is that only a single task references the peripheral, separating concerns. However, using a Mutex has a lower overhead and might be necessary if you need to ensure
 that the operation is completed before continuing to do other work in your task.
+
+An example showcasing more methods for sharing link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/sharing.rs[can be found here].
+
+== Sharing an I2C or SPI bus between multiple devices
+
+An example of how to deal with multiple devices sharing a common I2C or SPI bus link:https://github.com/embassy-rs/embassy/blob/main/examples/rp/src/bin/shared_bus.rs[can be found here].
diff --git a/docs/pages/stm32.adoc b/docs/pages/stm32.adoc
index 7bfc0592b..df139a420 100644
--- a/docs/pages/stm32.adoc
+++ b/docs/pages/stm32.adoc
@@ -1,6 +1,6 @@
 = Embassy STM32 HAL
 
-The link:https://github.com/embassy-rs/embassy/tree/master/embassy-stm32[Embassy STM32 HAL] is based on the `stm32-metapac` project.
+The link:https://github.com/embassy-rs/embassy/tree/main/embassy-stm32[Embassy STM32 HAL] is based on the `stm32-metapac` project.
 
 == The infinite variant problem
 
diff --git a/docs/pages/system.adoc b/docs/pages/system.adoc
index 985f92b18..09241a8df 100644
--- a/docs/pages/system.adoc
+++ b/docs/pages/system.adoc
@@ -6,6 +6,7 @@ include::runtime.adoc[leveloffset = 2]
 include::bootloader.adoc[leveloffset = 2]
 include::time_keeping.adoc[leveloffset = 2]
 include::hal.adoc[leveloffset = 2]
+include::imxrt.adoc[leveloffset = 2]
 include::nrf.adoc[leveloffset = 2]
 include::stm32.adoc[leveloffset = 2]
 include::sharing_peripherals.adoc[leveloffset = 2]
diff --git a/docs/pages/time_keeping.adoc b/docs/pages/time_keeping.adoc
index 17492a884..11ddb2b2b 100644
--- a/docs/pages/time_keeping.adoc
+++ b/docs/pages/time_keeping.adoc
@@ -16,7 +16,7 @@ The `embassy::time::Timer` type provides two timing methods.
 
 An example of a delay is provided as follows:
 
-TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here].
+TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here].
 [,rust]
 ----
 use embassy::executor::{task, Executor};
@@ -41,7 +41,7 @@ that expect a generic delay implementation to be provided.
 
 An example of how this can be used:
 
-TIP: Dependencies needed to run this example link:/book/dev/basic_application.html#_the_cargo_toml[can be found here].
+TIP: Dependencies needed to run this example link:#_the_cargo_toml[can be found here].
 [,rust]
 ----
 use embassy::executor::{task, Executor};