merge new embassy changes

12 files changed, 165 insertions, 61 deletions

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..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.
@@ -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]
@@ -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..620794c31 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]!
 
+* 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! 
 ** Targets STM32, RP2040, nRF52 and ESP32 MCUs
diff --git a/docs/pages/faq.adoc b/docs/pages/faq.adoc
index 4ab04e2a1..b21be9a30 100644
--- a/docs/pages/faq.adoc
+++ b/docs/pages/faq.adoc
@@ -4,7 +4,7 @@ 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.
 
@@ -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].
@@ -230,7 +212,7 @@ _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. 
 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.
@@ -361,4 +343,73 @@ Practically, there's not a LOT of difference either way - so go with what makes
 
 == 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]
\ No newline at end of file
+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 7852d27b7..7dba11b5e 100644
--- a/docs/pages/layer_by_layer.adoc
+++ b/docs/pages/layer_by_layer.adoc
@@ -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 `ExtiInput`), 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 821bcbd27..cd943b4f6 100644
--- a/docs/pages/new_project.adoc
+++ b/docs/pages/new_project.adoc
@@ -73,22 +73,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 +109,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 +150,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/overview.adoc b/docs/pages/overview.adoc
index 7d59d5521..acd757795 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://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/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.
@@ -52,7 +55,7 @@ link:https://github.com/embassy-rs/embassy/tree/main/embassy-boot[embassy-boot]
 
 == 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/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]