Add half duplex support

ci: use beta, add secondary nightly ci.

.github/ci/build-nightly.sh

@@ -7,6 +7,7 @@ set -euo pipefail
 export RUSTUP_HOME=/ci/cache/rustup
 export CARGO_HOME=/ci/cache/cargo
 export CARGO_TARGET_DIR=/ci/cache/target
+mv rust-toolchain-nightly.toml rust-toolchain.toml
 
 # needed for "dumb HTTP" transport support
 # used when pointing stm32-metapac to a CI-built one.
@@ -21,9 +22,7 @@ fi
 hashtime restore /ci/cache/filetime.json || true
 hashtime save /ci/cache/filetime.json
 
-sed -i 's/channel.*/channel = "beta"/g' rust-toolchain.toml
+./ci-nightly.sh
-
-./ci_stable.sh
 
 # Save lockfiles
 echo Saving lockfiles...

.github/ci/rustfmt.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+## on push branch~=gh-readonly-queue/main/.*
+## on pull_request
+
+set -euo pipefail
+
+export RUSTUP_HOME=/ci/cache/rustup
+export CARGO_HOME=/ci/cache/cargo
+export CARGO_TARGET_DIR=/ci/cache/target
+mv rust-toolchain-nightly.toml rust-toolchain.toml
+
+find . -name '*.rs' -not -path '*target*' | xargs rustfmt --check  --skip-children --unstable-features --edition 2021

.github/ci/test-nightly.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+## on push branch~=gh-readonly-queue/main/.*
+## on pull_request
+
+set -euo pipefail
+
+export RUSTUP_HOME=/ci/cache/rustup
+export CARGO_HOME=/ci/cache/cargo
+export CARGO_TARGET_DIR=/ci/cache/target
+mv rust-toolchain-nightly.toml rust-toolchain.toml
+
+MIRIFLAGS=-Zmiri-ignore-leaks cargo miri test --manifest-path ./embassy-executor/Cargo.toml
+MIRIFLAGS=-Zmiri-ignore-leaks cargo miri test --manifest-path ./embassy-executor/Cargo.toml --features nightly

.github/ci/test.sh

@@ -4,8 +4,9 @@
 
 set -euo pipefail
 
-MIRIFLAGS=-Zmiri-ignore-leaks cargo miri test --manifest-path ./embassy-executor/Cargo.toml
+export RUSTUP_HOME=/ci/cache/rustup
-MIRIFLAGS=-Zmiri-ignore-leaks cargo miri test --manifest-path ./embassy-executor/Cargo.toml --features nightly
+export CARGO_HOME=/ci/cache/cargo
+export CARGO_TARGET_DIR=/ci/cache/target
 
 cargo test --manifest-path ./embassy-sync/Cargo.toml 
 cargo test --manifest-path ./embassy-embedded-hal/Cargo.toml 

.vscode/settings.json

@@ -15,14 +15,10 @@
   //"rust-analyzer.cargo.target": "thumbv7m-none-eabi",
   "rust-analyzer.cargo.target": "thumbv7em-none-eabi",
   //"rust-analyzer.cargo.target": "thumbv8m.main-none-eabihf",
-  "rust-analyzer.cargo.features": [
-    // Uncomment if the example has a "nightly" feature.
-    "nightly",
-  ],
   "rust-analyzer.linkedProjects": [
     // Uncomment ONE line for the chip you want to work on.
     // This makes rust-analyzer work on the example crate and all its dependencies.
-    "examples/nrf52840/Cargo.toml",
+    "examples/stm32l4/Cargo.toml",
     // "examples/nrf52840-rtic/Cargo.toml",
     // "examples/nrf5340/Cargo.toml",
     // "examples/nrf-rtos-trace/Cargo.toml",

ci-nightly.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+set -eo pipefail
+
+export RUSTFLAGS=-Dwarnings
+export DEFMT_LOG=trace,embassy_hal_internal=debug,embassy_net_esp_hosted=debug,cyw43=info,cyw43_pio=info,smoltcp=info
+if [[ -z "${CARGO_TARGET_DIR}" ]]; then
+    export CARGO_TARGET_DIR=target_ci
+fi
+
+cargo batch  \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,log \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,defmt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features nightly,defmt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features nightly,defmt,arch-cortex-m,executor-thread,executor-interrupt,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-interrupt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-interrupt,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread,executor-interrupt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread,executor-interrupt,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32 \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32,executor-thread \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32,executor-thread,integrated-timers \
+    --- build --release --manifest-path examples/nrf52840-rtic/Cargo.toml --target thumbv7em-none-eabi --out-dir out/examples/nrf52840-rtic \
+

ci.sh

@@ -15,26 +15,24 @@ if [ $TARGET = "x86_64-unknown-linux-gnu" ]; then
     BUILD_EXTRA="--- build --release --manifest-path examples/std/Cargo.toml --target $TARGET --out-dir out/examples/std"
 fi
 
-find . -name '*.rs' -not -path '*target*' | xargs rustfmt --check  --skip-children --unstable-features --edition 2021
-
 cargo batch  \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,log \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features log \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,defmt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features defmt \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features nightly,defmt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features defmt \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features nightly,defmt,arch-cortex-m,executor-thread,executor-interrupt,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features defmt,arch-cortex-m,executor-thread,executor-interrupt,integrated-timers \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,integrated-timers \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,executor-thread \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,executor-thread,integrated-timers \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-interrupt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,executor-interrupt \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-interrupt,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,executor-interrupt,integrated-timers \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread,executor-interrupt \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,executor-thread,executor-interrupt \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features nightly,arch-cortex-m,executor-thread,executor-interrupt,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features arch-cortex-m,executor-thread,executor-interrupt,integrated-timers \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32 \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features arch-riscv32 \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features arch-riscv32,integrated-timers \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32,executor-thread \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features arch-riscv32,executor-thread \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features nightly,arch-riscv32,executor-thread,integrated-timers \
+    --- build --release --manifest-path embassy-executor/Cargo.toml --target riscv32imac-unknown-none-elf --features arch-riscv32,executor-thread,integrated-timers \
     --- build --release --manifest-path embassy-sync/Cargo.toml --target thumbv6m-none-eabi --features defmt \
     --- build --release --manifest-path embassy-time/Cargo.toml --target thumbv6m-none-eabi --features defmt,defmt-timestamp-uptime,tick-hz-32_768,generic-queue-8 \
     --- build --release --manifest-path embassy-net/Cargo.toml --target thumbv7em-none-eabi --features defmt,tcp,udp,dns,proto-ipv4,medium-ethernet \
@@ -91,12 +89,12 @@ cargo batch  \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f417zg,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f423zh,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f427zi,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,exti,time-driver-any,embedded-sdmmc,time \
+    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f437zi,log,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f439zi,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f446ze,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f469zi,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f479zi,defmt,exti,time-driver-any,embedded-sdmmc,time \
+    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f479zi,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f730i8,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h753zi,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h735zg,defmt,exti,time-driver-any,time \
@@ -140,7 +138,6 @@ cargo batch  \
     --- build --release --manifest-path docs/modules/ROOT/examples/layer-by-layer/blinky-irq/Cargo.toml --target thumbv7em-none-eabi \
     --- build --release --manifest-path docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml --target thumbv7em-none-eabi \
     --- build --release --manifest-path examples/nrf52840/Cargo.toml --target thumbv7em-none-eabi --out-dir out/examples/nrf52840 \
-    --- build --release --manifest-path examples/nrf52840-rtic/Cargo.toml --target thumbv7em-none-eabi --out-dir out/examples/nrf52840-rtic \
     --- build --release --manifest-path examples/nrf5340/Cargo.toml --target thumbv8m.main-none-eabihf --out-dir out/examples/nrf5340 \
     --- build --release --manifest-path examples/rp/Cargo.toml --target thumbv6m-none-eabi --out-dir out/examples/rp \
     --- build --release --manifest-path examples/stm32f0/Cargo.toml --target thumbv6m-none-eabi --out-dir out/examples/stm32f0 \
@@ -173,10 +170,12 @@ cargo batch  \
     --- build --release --manifest-path examples/boot/application/stm32l1/Cargo.toml --target thumbv7m-none-eabi --features skip-include --out-dir out/examples/boot/stm32l1 \
     --- build --release --manifest-path examples/boot/application/stm32l4/Cargo.toml --target thumbv7em-none-eabi --features skip-include --out-dir out/examples/boot/stm32l4 \
     --- build --release --manifest-path examples/boot/application/stm32wl/Cargo.toml --target thumbv7em-none-eabihf --features skip-include --out-dir out/examples/boot/stm32wl \
+    --- build --release --manifest-path examples/boot/application/stm32wb-dfu/Cargo.toml --target thumbv7em-none-eabihf --out-dir out/examples/boot/stm32wb-dfu \
     --- build --release --manifest-path examples/boot/bootloader/nrf/Cargo.toml --target thumbv7em-none-eabi --features embassy-nrf/nrf52840 \
     --- build --release --manifest-path examples/boot/bootloader/nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features embassy-nrf/nrf9160-ns \
     --- build --release --manifest-path examples/boot/bootloader/rp/Cargo.toml --target thumbv6m-none-eabi \
     --- build --release --manifest-path examples/boot/bootloader/stm32/Cargo.toml --target thumbv7em-none-eabi --features embassy-stm32/stm32wl55jc-cm4 \
+    --- build --release --manifest-path examples/boot/bootloader/stm32wb-dfu/Cargo.toml --target thumbv7em-none-eabihf \
     --- build --release --manifest-path examples/wasm/Cargo.toml --target wasm32-unknown-unknown --out-dir out/examples/wasm \
     --- build --release --manifest-path tests/stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32f103c8 --out-dir out/tests/stm32f103c8 \
     --- build --release --manifest-path tests/stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi --out-dir out/tests/stm32f429zi \

ci_stable.sh

@@ -1,77 +0,0 @@
-#!/bin/bash
-
-set -euo pipefail
-
-export RUSTFLAGS=-Dwarnings
-export DEFMT_LOG=trace
-
-cargo batch  \
-    --- build --release --manifest-path embassy-boot/nrf/Cargo.toml --target thumbv7em-none-eabi --features embassy-nrf/nrf52840 \
-    --- build --release --manifest-path embassy-boot/nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features embassy-nrf/nrf9160-ns \
-    --- build --release --manifest-path embassy-boot/rp/Cargo.toml --target thumbv6m-none-eabi \
-    --- build --release --manifest-path embassy-boot/stm32/Cargo.toml --target thumbv7em-none-eabi --features embassy-stm32/stm32wl55jc-cm4 \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features log \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv7em-none-eabi --features defmt \
-    --- build --release --manifest-path embassy-executor/Cargo.toml --target thumbv6m-none-eabi --features defmt \
-    --- build --release --manifest-path embassy-net/Cargo.toml --target thumbv7em-none-eabi --features defmt,tcp,udp,dns,proto-ipv4,medium-ethernet \
-    --- build --release --manifest-path embassy-net/Cargo.toml --target thumbv7em-none-eabi --features defmt,tcp,udp,dns,dhcpv4,medium-ethernet \
-    --- build --release --manifest-path embassy-net/Cargo.toml --target thumbv7em-none-eabi --features defmt,tcp,udp,dns,proto-ipv6,medium-ethernet \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52805,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52810,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52811,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52820,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52832,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52833,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features nrf9160-s,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features nrf9160-ns,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features nrf5340-app-s,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features nrf5340-app-ns,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv8m.main-none-eabihf --features nrf5340-net,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52840,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52840,log,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-nrf/Cargo.toml --target thumbv7em-none-eabi --features nrf52840,defmt,gpiote,time-driver-rtc1 \
-    --- build --release --manifest-path embassy-rp/Cargo.toml --target thumbv6m-none-eabi --features defmt \
-    --- build --release --manifest-path embassy-rp/Cargo.toml --target thumbv6m-none-eabi --features log \
-    --- build --release --manifest-path embassy-rp/Cargo.toml --target thumbv6m-none-eabi \
-    --- build --release --manifest-path embassy-rp/Cargo.toml --target thumbv6m-none-eabi --features qspi-as-gpio \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32g473cc,defmt,exti,time-driver-any \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32g491re,defmt,exti,time-driver-any \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32u585zi,defmt,exti,time-driver-any \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32wb55vy,defmt,exti,time-driver-any \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32wl55cc-cm4,defmt,exti,time-driver-any \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32g473cc,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32g491re,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32u585zi,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32wb55vy,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32wl55cc-cm4,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32l4r9zi,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f303vc,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f411ce,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f411ce,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h755zi-cm7,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h755zi-cm7,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32l476vg,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32l476vg,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv6m-none-eabi --features stm32l072cz,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv6m-none-eabi --features stm32l072cz,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32l151cb-a,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32l151cb-a,defmt,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f410tb,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f410tb,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h755zi-cm7,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h755zi-cm7,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32l476vg,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32l476vg,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv6m-none-eabi --features stm32l072cz,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv6m-none-eabi --features stm32l072cz,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32l151cb-a,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32l151cb-a,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32f217zg,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7m-none-eabi --features stm32f217zg,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path examples/nrf52840/Cargo.toml --target thumbv7em-none-eabi --no-default-features --out-dir out/examples/nrf52840 --bin raw_spawn \
-    --- build --release --manifest-path examples/stm32l0/Cargo.toml --target thumbv6m-none-eabi --no-default-features --out-dir out/examples/stm32l0 --bin raw_spawn \

cyw43-pio/README.md

@@ -0,0 +1,17 @@
+# cyw43-pio
+
+RP2040 PIO driver for the nonstandard half-duplex SPI used in the Pico W. The PIO driver offloads SPI communication with the WiFi chip and improves throughput.
+
+## Minimum supported Rust version (MSRV)
+
+Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.

cyw43-pio/src/lib.rs

@@ -1,16 +1,19 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 use core::slice;
 
 use cyw43::SpiBusCyw43;
 use embassy_rp::dma::Channel;
 use embassy_rp::gpio::{Drive, Level, Output, Pin, Pull, SlewRate};
-use embassy_rp::pio::{Common, Config, Direction, Instance, Irq, PioPin, ShiftDirection, StateMachine};
+use embassy_rp::pio::{instr, Common, Config, Direction, Instance, Irq, PioPin, ShiftDirection, StateMachine};
-use embassy_rp::{pio_instr_util, Peripheral, PeripheralRef};
+use embassy_rp::{Peripheral, PeripheralRef};
 use fixed::FixedU32;
 use pio_proc::pio_asm;
 
+/// SPI comms driven by PIO.
 pub struct PioSpi<'d, CS: Pin, PIO: Instance, const SM: usize, DMA> {
     cs: Output<'d, CS>,
     sm: StateMachine<'d, PIO, SM>,
@@ -25,6 +28,7 @@ where
     CS: Pin,
     PIO: Instance,
 {
+    /// Create a new instance of PioSpi.
     pub fn new<DIO, CLK>(
         common: &mut Common<'d, PIO>,
         mut sm: StateMachine<'d, PIO, SM>,
@@ -143,6 +147,7 @@ where
         }
     }
 
+    /// Write data to peripheral and return status.
     pub async fn write(&mut self, write: &[u32]) -> u32 {
         self.sm.set_enable(false);
         let write_bits = write.len() * 32 - 1;
@@ -152,10 +157,10 @@ where
         defmt::trace!("write={} read={}", write_bits, read_bits);
 
         unsafe {
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
+            instr::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
+            instr::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
+            instr::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::exec_jmp(&mut self.sm, self.wrap_target);
         }
 
         self.sm.set_enable(true);
@@ -170,6 +175,7 @@ where
         status
     }
 
+    /// Send command and read response into buffer.
     pub async fn cmd_read(&mut self, cmd: u32, read: &mut [u32]) -> u32 {
         self.sm.set_enable(false);
         let write_bits = 31;
@@ -179,10 +185,10 @@ where
         defmt::trace!("write={} read={}", write_bits, read_bits);
 
         unsafe {
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
+            instr::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
+            instr::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
+            instr::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::exec_jmp(&mut self.sm, self.wrap_target);
         }
 
         // self.cs.set_low();

cyw43/Cargo.toml

@@ -23,7 +23,7 @@ cortex-m = "0.7.6"
 cortex-m-rt = "0.7.0"
 futures = { version = "0.3.17", default-features = false, features = ["async-await", "cfg-target-has-atomic", "unstable"] }
 
-embedded-hal-1 = { package = "embedded-hal", version = "1.0.0-rc.2" }
+embedded-hal-1 = { package = "embedded-hal", version = "1.0.0-rc.3" }
 num_enum = { version = "0.5.7", default-features = false }
 
 [package.metadata.embassy_docs]

cyw43/README.md

@@ -45,6 +45,10 @@ nc 192.168.0.250 1234
 ```
 Send it some data, you should see it echoed back and printed in the firmware's logs.
 
+## Minimum supported Rust version (MSRV)
+
+Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
+
 ## License
 
 This work is licensed under either of

cyw43/src/control.rs

@@ -12,17 +12,23 @@ use crate::ioctl::{IoctlState, IoctlType};
 use crate::structs::*;
 use crate::{countries, events, PowerManagementMode};
 
+/// Control errors.
 #[derive(Debug)]
 pub struct Error {
+    /// Status code.
     pub status: u32,
 }
 
+/// Multicast errors.
 #[derive(Debug)]
 pub enum AddMulticastAddressError {
+    /// Not a multicast address.
     NotMulticast,
+    /// No free address slots.
     NoFreeSlots,
 }
 
+/// Control driver.
 pub struct Control<'a> {
     state_ch: ch::StateRunner<'a>,
     events: &'a Events,
@@ -38,6 +44,7 @@ impl<'a> Control<'a> {
         }
     }
 
+    /// Initialize WiFi controller.
     pub async fn init(&mut self, clm: &[u8]) {
         const CHUNK_SIZE: usize = 1024;
 
@@ -154,6 +161,7 @@ impl<'a> Control<'a> {
         self.ioctl(IoctlType::Set, IOCTL_CMD_DOWN, 0, &mut []).await;
     }
 
+    /// Set power management mode.
     pub async fn set_power_management(&mut self, mode: PowerManagementMode) {
         // power save mode
         let mode_num = mode.mode();
@@ -166,6 +174,7 @@ impl<'a> Control<'a> {
         self.ioctl_set_u32(86, 0, mode_num).await;
     }
 
+    /// Join an unprotected network with the provided ssid.
     pub async fn join_open(&mut self, ssid: &str) -> Result<(), Error> {
         self.set_iovar_u32("ampdu_ba_wsize", 8).await;
 
@@ -183,6 +192,7 @@ impl<'a> Control<'a> {
         self.wait_for_join(i).await
     }
 
+    /// Join an protected network with the provided ssid and passphrase.
     pub async fn join_wpa2(&mut self, ssid: &str, passphrase: &str) -> Result<(), Error> {
         self.set_iovar_u32("ampdu_ba_wsize", 8).await;
 
@@ -250,16 +260,19 @@ impl<'a> Control<'a> {
         }
     }
 
+    /// Set GPIO pin on WiFi chip.
     pub async fn gpio_set(&mut self, gpio_n: u8, gpio_en: bool) {
         assert!(gpio_n < 3);
         self.set_iovar_u32x2("gpioout", 1 << gpio_n, if gpio_en { 1 << gpio_n } else { 0 })
             .await
     }
 
+    /// Start open access point.
     pub async fn start_ap_open(&mut self, ssid: &str, channel: u8) {
         self.start_ap(ssid, "", Security::OPEN, channel).await;
     }
 
+    /// Start WPA2 protected access point.
     pub async fn start_ap_wpa2(&mut self, ssid: &str, passphrase: &str, channel: u8) {
         self.start_ap(ssid, passphrase, Security::WPA2_AES_PSK, channel).await;
     }
@@ -494,13 +507,14 @@ impl<'a> Control<'a> {
     }
 }
 
+/// WiFi network scanner.
 pub struct Scanner<'a> {
     subscriber: EventSubscriber<'a>,
     events: &'a Events,
 }
 
 impl Scanner<'_> {
-    /// wait for the next found network
+    /// Wait for the next found network.
     pub async fn next(&mut self) -> Option<BssInfo> {
         let event = self.subscriber.next_message_pure().await;
         if event.header.status != EStatus::PARTIAL {

cyw43/src/lib.rs

@@ -2,6 +2,8 @@
 #![no_main]
 #![allow(async_fn_in_trait)]
 #![deny(unused_must_use)]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
@@ -102,6 +104,7 @@ const CHIP: Chip = Chip {
     chanspec_ctl_sb_mask: 0x0700,
 };
 
+/// Driver state.
 pub struct State {
     ioctl_state: IoctlState,
     ch: ch::State<MTU, 4, 4>,
@@ -109,6 +112,7 @@ pub struct State {
 }
 
 impl State {
+    /// Create new driver state holder.
     pub fn new() -> Self {
         Self {
             ioctl_state: IoctlState::new(),
@@ -118,6 +122,7 @@ impl State {
     }
 }
 
+/// Power management modes.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PowerManagementMode {
     /// Custom, officially unsupported mode. Use at your own risk.
@@ -203,8 +208,13 @@ impl PowerManagementMode {
     }
 }
 
+/// Embassy-net driver.
 pub type NetDriver<'a> = ch::Device<'a, MTU>;
 
+/// Create a new instance of the CYW43 driver.
+///
+/// Returns a handle to the network device, control handle and a runner for driving the low level
+/// stack.
 pub async fn new<'a, PWR, SPI>(
     state: &'a mut State,
     pwr: PWR,

cyw43/src/runner.rs

@@ -34,6 +34,7 @@ impl Default for LogState {
     }
 }
 
+/// Driver communicating with the WiFi chip.
 pub struct Runner<'a, PWR, SPI> {
     ch: ch::Runner<'a, MTU>,
     bus: Bus<PWR, SPI>,
@@ -222,6 +223,7 @@ where
         }
     }
 
+    /// Run the
     pub async fn run(mut self) -> ! {
         let mut buf = [0; 512];
         loop {

cyw43/src/structs.rs

@@ -4,13 +4,16 @@ use crate::fmt::Bytes;
 macro_rules! impl_bytes {
     ($t:ident) => {
         impl $t {
+            /// Bytes consumed by this type.
             pub const SIZE: usize = core::mem::size_of::<Self>();
 
+            /// Convert to byte array.
             #[allow(unused)]
             pub fn to_bytes(&self) -> [u8; Self::SIZE] {
                 unsafe { core::mem::transmute(*self) }
             }
 
+            /// Create from byte array.
             #[allow(unused)]
             pub fn from_bytes(bytes: &[u8; Self::SIZE]) -> &Self {
                 let alignment = core::mem::align_of::<Self>();
@@ -23,6 +26,7 @@ macro_rules! impl_bytes {
                 unsafe { core::mem::transmute(bytes) }
             }
 
+            /// Create from mutable byte array.
             #[allow(unused)]
             pub fn from_bytes_mut(bytes: &mut [u8; Self::SIZE]) -> &mut Self {
                 let alignment = core::mem::align_of::<Self>();
@@ -204,6 +208,7 @@ pub struct EthernetHeader {
 }
 
 impl EthernetHeader {
+    /// Swap endianness.
     pub fn byteswap(&mut self) {
         self.ether_type = self.ether_type.to_be();
     }
@@ -472,19 +477,26 @@ impl ScanResults {
 #[repr(C, packed(2))]
 #[non_exhaustive]
 pub struct BssInfo {
+    /// Version.
     pub version: u32,
+    /// Length.
     pub length: u32,
+    /// BSSID.
     pub bssid: [u8; 6],
+    /// Beacon period.
     pub beacon_period: u16,
+    /// Capability.
     pub capability: u16,
+    /// SSID length.
     pub ssid_len: u8,
+    /// SSID.
     pub ssid: [u8; 32],
     // there will be more stuff here
 }
 impl_bytes!(BssInfo);
 
 impl BssInfo {
-    pub fn parse(packet: &mut [u8]) -> Option<&mut Self> {
+    pub(crate) fn parse(packet: &mut [u8]) -> Option<&mut Self> {
         if packet.len() < BssInfo::SIZE {
             return None;
         }

docs/modules/ROOT/examples/basic/Cargo.toml

@@ -6,7 +6,7 @@ version = "0.1.0"
 license = "MIT OR Apache-2.0"
 
 [dependencies]
-embassy-executor = { version = "0.3.0", path = "../../../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] }
+embassy-executor = { version = "0.4.0", path = "../../../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] }
 embassy-time = { version = "0.2.0", path = "../../../../../embassy-time", features = ["defmt"] }
 embassy-nrf = { version = "0.1.0", path = "../../../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] }
 

docs/modules/ROOT/examples/basic/src/main.rs

@@ -1,6 +1,5 @@
 #![no_std]
 #![no_main]
-#![feature(type_alias_impl_trait)]
 
 use defmt::*;
 use embassy_executor::Spawner;

docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml

@@ -8,7 +8,7 @@ license = "MIT OR Apache-2.0"
 cortex-m = "0.7"
 cortex-m-rt = "0.7"
 embassy-stm32 = { version = "0.1.0", features = ["stm32l475vg", "memory-x", "exti"]  }
-embassy-executor = { version = "0.3.0", features = ["nightly", "arch-cortex-m", "executor-thread"] }
+embassy-executor = { version = "0.4.0", features = ["arch-cortex-m", "executor-thread"] }
 
 defmt = "0.3.0"
 defmt-rtt = "0.3.0"

docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs

@@ -1,6 +1,5 @@
 #![no_std]
 #![no_main]
-#![feature(type_alias_impl_trait)]
 
 use embassy_executor::Spawner;
 use embassy_stm32::exti::ExtiInput;

docs/modules/ROOT/examples/layer-by-layer/blinky-hal/src/main.rs

@@ -9,7 +9,7 @@ use {defmt_rtt as _, panic_probe as _};
 fn main() -> ! {
     let p = embassy_stm32::init(Default::default());
     let mut led = Output::new(p.PB14, Level::High, Speed::VeryHigh);
-    let button = Input::new(p.PC13, Pull::Up);
+    let mut button = Input::new(p.PC13, Pull::Up);
 
     loop {
         if button.is_low() {

docs/modules/ROOT/nav.adoc

@@ -1,14 +1,18 @@
 * xref:getting_started.adoc[Getting started]
 ** xref:basic_application.adoc[Basic application]
 ** xref:project_structure.adoc[Project Structure]
+** xref:new_project.adoc[Starting a new Embassy project]
+** xref:best_practices.adoc[Best Practices]
 * xref:layer_by_layer.adoc[Bare metal to async]
 * xref:runtime.adoc[Executor]
+* xref:delaying_a_task.adoc[Delaying a Task]
 * xref:hal.adoc[HAL]
 ** xref:nrf.adoc[nRF]
 ** xref:stm32.adoc[STM32]
 * xref:bootloader.adoc[Bootloader]
 
 * xref:examples.adoc[Examples]
-* xref:developer.adoc[Developer]
+* xref:developer.adoc[Developer Docs]
-** xref:developer_stm32.adoc[Developer: STM32]
+** xref:developer_stm32.adoc[Developer Docs: STM32]
+* xref:embassy_in_the_wild.adoc[Embassy in the wild]
 * xref:faq.adoc[Frequently Asked Questions]

docs/modules/ROOT/pages/basic_application.adoc

@@ -6,9 +6,11 @@ So you've got one of the xref:examples.adoc[examples] running, but what now? Let
 
 The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/modules/ROOT/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.
+
 === Bare metal
 
-The first thing you'll notice is a few declarations, two of which indicate that Embassy is suitable for bare metal development:
+The first thing you’ll notice are two attributes at the top of the file. These tells the compiler that program has no access to std, and that there is no main function (because it is not run by an OS).
 
 [source,rust]
 ----
@@ -48,9 +50,9 @@ NOTE: Notice that there is no busy waiting going on in this task. It is using th
 
 === Main
 
-The main entry point of an Embassy application is defined using the `#[embassy_executor::main]` macro. The entry point is also required to take a `Spawner` and a `Peripherals` argument.
+The main entry point of an Embassy application is defined using the `#[embassy_executor::main]` macro. The entry point is passed a `Spawner`, which it can use to spawn other tasks.
 
-The `Spawner` is the way the main application spawns other tasks. The `Peripherals` type comes from the HAL and holds all peripherals that the application may use. In this case, we want to configure one of the pins as a GPIO output driving the LED:
+We then initialize the HAL with a default config, which gives us a `Peripherals` struct we can use to access the MCU’s various peripherals. In this case, we want to configure one of the pins as a GPIO output driving the LED:
 
 [source,rust]
 ----
@@ -60,7 +62,6 @@ include::example$basic/src/main.rs[lines="22..-1"]
 What happens when the `blinker` task has been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy_executor::main]` macro. The macro does the following:
 
 . Creates an Embassy Executor
-. Initializes the microcontroller HAL to get the `Peripherals`
 . Defines a main task for the entry point
 . Runs the executor spawning the main task
 

docs/modules/ROOT/pages/best_practices.adoc

@@ -0,0 +1,53 @@
+= Best Practices
+
+Over time, a couple of best practices have emerged. The following list should serve as a guideline for developers writing embedded software in _Rust_, especially in the context of the _Embassy_ framework.
+
+== Passing Buffers by Reference
+It may be tempting to pass arrays or wrappers, like link:https://docs.rs/heapless/latest/heapless/[`heapless::Vec`], to a function or return one just like you would with a `std::Vec`. However, in most embedded applications you don't want to spend ressources on an allocator and end up placing buffers on the stack.
+This, however, can easily blow up your stack if you are not careful.
+
+Consider the following example:
+[,rust]
+----
+fn process_buffer(mut buf: [u8; 1024]) -> [u8; 1024] {
+    // do stuff and return new buffer
+    for elem in buf.iter_mut() {
+        *elem = 0;
+    }
+    buf
+}
+
+pub fn main() -> () {
+    let buf = [1u8; 1024];
+    let buf_new = process_buffer(buf);
+    // do stuff with buf_new
+    ()
+}
+----
+When calling `process_buffer` in your program, a copy of the buffer you pass to the function will be created,
+consuming another 1024 bytes.
+After the processing, another 1024 byte buffer will be placed on the stack to be returned to the caller.
+(You can check the assembly, there will be two memcopy operations, e.g., `bl __aeabi_memcpy` when compiling for a Cortex-M processor.)
+
+*Possible Solution:*
+
+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.
+
+[,rust]
+----
+fn process_buffer<'a>(buf: &'a mut [u8]) -> &'a mut[u8] {
+    for elem in buf.iter_mut() {
+        *elem = 0;
+    }
+    buf
+}
+
+pub fn main() -> () {
+    let mut buf = [1u8; 1024];
+    let buf_new = process_buffer(&mut buf);
+    // do stuff with buf_new
+    ()
+}
+----

docs/modules/ROOT/pages/bootloader.adoc

@@ -45,6 +45,8 @@ The BOOTLOADER_STATE partition must be big enough to store one word per page in
 
 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.
 
+NOTE: The linker scripts for the application and bootloader look similar, but the FLASH region must point to the BOOTLOADER partition for the bootloader, and the ACTIVE partition for the application.
+
 === FirmwareUpdater
 
 The `FirmwareUpdater` is an object for conveniently flashing firmware to the DFU partition and subsequently marking it as being ready for swapping with the active partition on the next reset. Its principle methods are `write_firmware`, which is called once per the size of the flash "write block" (typically 4KiB), and `mark_updated`, which is the final call.

docs/modules/ROOT/pages/delaying_a_task.adoc

@@ -0,0 +1,28 @@
+= Delaying a Task
+
+In an embedded program, delaying a task is one of the most common actions taken. In an event loop, delays will need to be inserted to ensure
+that other tasks have a chance to run before the next iteration of the loop is called, if no other I/O is performed. Embassy provides an abstraction
+to delay the current task for a specified interval of time.
+
+Timing is serviced by the `embassy::time::Timer` struct, which provides two timing methods.
+
+`Timer::at` creates a future that completes at the specified `Instant`, relative to the system boot time.
+`Timer::after` creates a future that completes after the specified `Duration`, relative to when the future was created.
+
+An example of a delay is provided as follows:
+
+[,rust]
+----
+use embassy::executor::{task, Executor};
+use embassy::time::{Duration, Timer};
+
+#[task]
+/// Task that ticks periodically
+async fn tick_periodic() -> ! {
+    loop {
+        rprintln!("tick!");
+        // async sleep primitive, suspends the task for 500ms.
+        Timer::after(Duration::from_millis(500)).await;
+    }
+}
+----

docs/modules/ROOT/pages/embassy_in_the_wild.adoc

@@ -0,0 +1,9 @@
+= Embassy in the wild!
+
+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/modules/ROOT/pages/embassy_in_the_wild.adoc[add more]!
+
+* link:https://github.com/cbruiz/printhor/[Printhor: The highly reliable but not necessarily functional 3D printer firmware]
+** Targets some STM32 MCUs
+* link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device
+** Targets the ESP32-S3 or ESP32-C6 MCU
+* The link:https://github.com/lora-rs/lora-rs[lora-rs] project includes link:https://github.com/lora-rs/lora-rs/tree/main/examples/stm32l0/src/bin[various standalone examples] for NRF52840, RP2040, STM32L0 and STM32WL

docs/modules/ROOT/pages/faq.adoc

@@ -35,7 +35,7 @@ For Cortex-M targets, consider making sure that ALL of the following features ar
 * `executor-thread`
 * `nightly`
 
-For Xtensa ESP32, consider using the executors and `#[main]` macro provided by your appropriate link:https://crates.io/crates/esp-hal-common[HAL crate].
+For ESP32, consider using the executors and `#[main]` macro provided by your appropriate link:https://crates.io/crates/esp-hal-common[HAL crate].
 
 == Why is my binary so big?
 
@@ -47,7 +47,8 @@ The first step to managing your binary size is to set up your link:https://doc.r
 debug = false
 lto = true
 opt-level = "s"
-incremental = true
+incremental = false
+codegen-units = 1
 ----
 
 All of these flags are elaborated on in the Rust Book page linked above.
@@ -135,3 +136,20 @@ embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd
 ----
 
 Note that the git revision should match any other embassy patches or git dependencies that you are using!
+
+== How can I optimize the speed of my embassy-stm32 program?
+
+* Make sure RCC is set up to go as fast as possible
+* Make sure link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html[flash cache] is enabled
+* build with `--release`
+* Set the following keys for the release profile in your `Cargo.toml`:
+    ** `opt-level = "s"`
+    ** `lto = "fat"`
+* 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() }`
+    ** *Note:*  If you need 2 priority levels, using 2 interrupt executors is better than 1 thread executor + 1 interrupt executor.

docs/modules/ROOT/pages/getting_started.adoc

@@ -9,7 +9,9 @@ If you don't have any supported board, don't worry: you can also run embassy on
 
 == Getting a board with examples
 
-Embassy supports many microcontroller families, but the easiest ways to get started is if you have one of the more common development kits.
+Embassy supports many microcontroller families, but the quickest way to get started is by using a board which Embassy has existing example code for.
+
+This list is non-exhaustive. If your board isn’t included here, check the link:https://github.com/embassy-rs/embassy/tree/main/examples[examples folder] to see if example code has been written for it.
 
 === nRF kits
 
@@ -36,7 +38,7 @@ Embassy supports many microcontroller families, but the easiest ways to get star
 
 == Running an example
 
-First you need to clone the [github repository];
+First you need to clone the link:https://github.com/embassy-rs/embassy[github repository];
 
 [source, bash]
 ----
@@ -44,17 +46,80 @@ git clone https://github.com/embassy-rs/embassy.git
 cd embassy
 ----
 
-You can run an example by opening a terminal and entering the following commands:
+Once you have a copy of the repository, find examples folder for your board and, and build an example program. `blinky` is a good choice as all it does is blink an LED – the embedded world’s equivalent of “Hello World”.
 
 [source, bash]
 ----
 cd examples/nrf52840
+cargo build --bin blinky --release
+----
+
+Once you’ve confirmed you can build the example, connect your computer to your board with a debug probe and run it on hardware:
+
+[source, bash]
+----
 cargo run --bin blinky --release
 ----
 
+If everything worked correctly, you should see a blinking LED on your board, and debug output similar to this on your computer:
+
+[source]
+----
+    Finished dev [unoptimized + debuginfo] target(s) in 1m 56s
+     Running `probe-run --chip STM32F407VGTx target/thumbv7em-none-eabi/debug/blinky`
+(HOST) INFO  flashing program (71.36 KiB)
+(HOST) INFO  success!
+────────────────────────────────────────────────────────────────────────────────
+0 INFO  Hello World!
+└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:18
+1 INFO  high
+└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:23
+2 INFO  low
+└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
+3 INFO  high
+└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:23
+4 INFO  low
+└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
+----
+
+NOTE: How does the `cargo run` command know how to connect to our board and program it? In each `examples` folder, there’s a `.cargo/config.toml` file which tells cargo to use link:https://probe.rs/[probe-rs] as the runner for ARM binaries in that folder. probe-rs handles communication with the debug probe and MCU. In order for this to work, probe-rs needs to know which chip it’s programming, so you’ll have to edit this file if you want to run examples on other chips.
+
+=== It didn’t work!
+
+If you hare 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
+* You have changed `examples/Cargo.toml`'s HAL (e.g. embassy-stm32) dependency's feature to use the correct chip (replace the existing stm32xxxx feature)
+
+At this point the project should run. If you do not see a blinky LED for blinky, for example, be sure to check the code is toggling your board's LED pin.
+
+If you are trying to run an example with `cargo run --release` and you see the following output:
+[source]
+----
+0.000000 INFO Hello World!
+└─ <invalid location: defmt frame-index: 14>
+0.000000 DEBUG rcc: Clocks { sys: Hertz(80000000), apb1: Hertz(80000000), apb1_tim: Hertz(80000000), apb2: Hertz(80000000), apb2_tim: Hertz(80000000), ahb1: Hertz(80000000), ahb2: Hertz(80000000), ahb3: Hertz(80000000) }
+└─ <invalid location: defmt frame-index: 124>
+0.000061 TRACE allocating type=Interrupt mps=8 interval_ms=255, dir=In
+└─ <invalid location: defmt frame-index: 68>
+0.000091 TRACE   index=1
+└─ <invalid location: defmt frame-index: 72>
+----
+
+To get rid of the frame-index error add the following to your `Cargo.toml`:
+
+[source,toml]
+----
+[profile.release]
+debug = 2
+----
+
+If you’re still having problems, check the link:https://embassy.dev/book/dev/faq.html[FAQ], or ask for help in the link:https://matrix.to/#/#embassy-rs:matrix.org[Embassy Chat Room].
+
 == What's next?
 
-Congratulations, you have your first Embassy application running! Here are some alternatives on where to go from here:
+Congratulations, you have your first Embassy application running! Here are some suggestions for where to go from here:
 
 * Read more about the xref:runtime.adoc[executor].
 * Read more about the xref:hal.adoc[HAL].

docs/modules/ROOT/pages/index.adoc

@@ -4,34 +4,56 @@ Embassy is a project to make async/await a first-class option for embedded devel
 
 == What is async?
 
-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 such task is ready to perform more work. 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. But 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 Rust, these lightweight tasks, known as 'coroutines' or 'goroutines' in other languages, are implemented with async.
+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.
 
-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. Compared to alternatives such as an RTOS, async can yield better performance and lower power consumption because the executor doesn't have to guess when a future is ready to execute. However, program size may be higher than other alternatives, which may be a problem for certain space-constrained devices with very low memory. On the devices Embassy supports, such as stm32 and nrf, memory is generally large enough to accommodate the modestly-increased program size.
+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.
+
+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.
+
+Compared to alternatives such as an RTOS, async can yield better performance and lower power consumption because the executor doesn't have to guess when a future is ready to execute. However, program size may be higher than other alternatives, which may be a problem for certain space-constrained devices with very low memory. On the devices Embassy supports, such as stm32 and nrf, memory is generally large enough to accommodate the modestly-increased program size.
 
 == What is Embassy?
 
 The Embassy project consists of several crates that you can use together or independently:
 
-* **Executor** - The link:https://docs.embassy.dev/embassy-executor/[embassy-executor] is an async/await executor that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The HAL is an API that you can use to access peripherals, such as USART, UART, I2C, SPI, CAN, and USB. Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API. The executor may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
+=== Executor
+The link:https://docs.embassy.dev/embassy-executor/[embassy-executor] is an async/await executor that generally executes a fixed number of tasks, allocated at startup, though more can be added later.  The executor may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
+
+=== Hardware Abstraction Layers
+HALs implement safe Rust API which let you use peripherals such as USART, UART, I2C, SPI, CAN, and USB without having to directly manipulate registers.
+
+Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API.
+
+The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy.
+
+* 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.
 
-* **Hardware Abstraction Layers** - HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed. The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy.
-** 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.
-+
 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.
 
-* **Networking** - The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently. Several drivers for WiFi and Ethernet chips can be found.
+=== Networking
+The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently. Several drivers for WiFi and Ethernet chips can be found.
 
-* **Bluetooth** - The link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.
+=== Bluetooth
+The link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.
 
-* **LoRa** - link:https://github.com/embassy-rs/lora-phy[lora-phy] and link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on a wide range of LoRa radios, fully integrated with a Rust link:https://github.com/ivajloip/rust-lorawan[LoRaWAN] implementation.
+=== LoRa
+link:https://github.com/embassy-rs/lora-phy[lora-phy] and link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on a wide range of LoRa radios, fully integrated with a Rust link:https://github.com/ivajloip/rust-lorawan[LoRaWAN] implementation.
 
-* **USB** - 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.
+=== USB
+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.
+=== 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.
+
+== 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.
+
+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.
 
 == Resources
 

docs/modules/ROOT/pages/new_project.adoc

@@ -0,0 +1,178 @@
+= Starting a new Embassy project
+
+Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project. The easiest way to do this is to adapt an example for a similar chip to the one you’re targeting.
+
+As an example, let’s create a new embassy project from scratch for a STM32G474. The same instructions are applicable for any supported chip with some minor changes.
+
+Run:
+
+[source,bash]
+----
+cargo new stm32g474-example
+cd stm32g474-example
+----
+
+to create an empty rust project:
+
+[source]
+----
+stm32g474-example
+├── Cargo.toml
+└── src
+    └── main.rs
+----
+
+Looking in link:https://github.com/embassy-rs/embassy/tree/main/examples[the Embassy examples], we can see there’s a `stm32g4` folder. Find `src/blinky.rs` and copy its contents into our `src/main.rs`.
+
+== .cargo/config.toml
+
+Currently, we’d need to provide cargo with a target triple every time we run `cargo build` or `cargo run`. Let’s spare ourselves that work by copying `.cargo/config.toml` from `examples/stm32g4` into our project.
+
+[source]
+----
+stm32g474-example
+├── .cargo
+│   └── config.toml
+├── Cargo.toml
+└── src
+    └── main.rs
+----
+
+In addition to a target triple, `.cargo/config.toml` contains a `runner` key which allows us to conveniently run our project on hardware with `cargo run` via probe-rs. In order for this to work, we need to provide the correct chip ID. We can do this by checking `probe-rs chip list`:
+
+[source,bash]
+----
+$ probe-rs chip list | grep -i stm32g474re
+        STM32G474RETx
+----
+
+and copying `STM32G474RETx` into `.cargo/config.toml` as so:
+
+[source,toml]
+----
+[target.'cfg(all(target_arch = "arm", target_os = "none"))']
+# replace STM32G071C8Rx with your chip as listed in `probe-rs chip list`
+runner = "probe-rs run --chip STM32G474RETx"
+----
+
+== Cargo.toml
+
+Now that cargo knows what target to compile for (and probe-rs knows what chip to run it on), we’re ready to add some dependencies.
+
+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:
+
+* 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!
+
+At the time of writing, this method produces the following results:
+
+[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-time = { version = "0.2", features = ["defmt", "defmt-timestamp-uptime", "tick-hz-32_768"] }
+
+[patch.crates-io]
+embassy-time = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" }
+embassy-executor = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" }
+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`:
+
+[source,toml]
+----
+defmt = "0.3.5"
+defmt-rtt = "0.4.0"
+cortex-m = {version = "0.7.7", features = ["critical-section-single-core"]}
+cortex-m-rt = "0.7.3"
+panic-probe = "0.3.1"
+----
+
+These are the bare minimum dependencies required to run `blinky.rs`, but it’s worth taking a look at the other dependencies specified in the example `Cargo.toml`, and noting what features are required for use with embassy – for example `futures = { version = "0.3.17", default-features = false, features = ["async-await"] }`.
+
+Finally, copy the `[profile.release]` section from the example `Cargo.toml` into ours.
+
+[source,toml]
+----
+[profile.release]
+debug = 2
+----
+
+== rust-toolchain.toml
+
+Before we can build our project, we need to add an additional file to tell cargo to use the nightly toolchain. Copy the `rust-toolchain.toml` from the embassy repo to ours, and trim the list of targets down to only the target triple relevent for our project — in this case, `thumbv7em-none-eabi`:
+
+[source]
+----
+stm32g474-example
+├── .cargo
+│   └── config.toml
+├── Cargo.toml
+├── rust-toolchain.toml
+└── src
+    └── main.rs
+----
+
+[source,toml]
+----
+# 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"
+components = [ "rust-src", "rustfmt", "llvm-tools", "miri" ]
+targets = ["thumbv7em-none-eabi"]
+----
+
+== build.rs
+
+In order to produce a working binary for our target, cargo requires a custom build script. Copy `build.rs` from the example to our project:
+
+[source]
+----
+stm32g474-example
+├── build.rs
+├── .cargo
+│   └── config.toml
+├── Cargo.toml
+├── rust-toolchain.toml
+└── src
+    └── main.rs
+----
+
+== Building and running
+
+At this point, we‘re finally ready to build and run our project! Connect your board via a debug probe and run:
+
+[source,bash]
+----
+cargo run --release
+----
+
+should result in a blinking LED (if there’s one attached to the pin in `src/main.rs` – change it if not!) and the following output:
+
+[source]
+----
+   Compiling stm32g474-example v0.1.0 (/home/you/stm32g474-example)
+    Finished release [optimized + debuginfo] target(s) in 0.22s
+     Running `probe-rs run --chip STM32G474RETx target/thumbv7em-none-eabi/release/stm32g474-example`
+     Erasing sectors ✔ [00:00:00] [#########################################################] 18.00 KiB/18.00 KiB @ 54.09 KiB/s (eta 0s )
+ Programming pages   ✔ [00:00:00] [#########################################################] 17.00 KiB/17.00 KiB @ 35.91 KiB/s (eta 0s )    Finished in 0.817s
+0.000000 TRACE BDCR configured: 00008200
+└─ embassy_stm32::rcc::bd::{impl#3}::init::{closure#4} @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:117 
+0.000000 DEBUG rcc: Clocks { sys: Hertz(16000000), pclk1: Hertz(16000000), pclk1_tim: Hertz(16000000), pclk2: Hertz(16000000), pclk2_tim: Hertz(16000000), hclk1: Hertz(16000000), hclk2: Hertz(16000000), pll1_p: None, adc: None, adc34: None, rtc: Some(Hertz(32000)) }
+└─ embassy_stm32::rcc::set_freqs @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:130 
+0.000000 INFO  Hello World!
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:14  
+0.000091 INFO  high
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:19  
+0.300201 INFO  low
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:23  
+----

embassy-boot/boot/Cargo.toml

@@ -26,25 +26,22 @@ features = ["defmt"]
 defmt = { version = "0.3", optional = true }
 digest = "0.10"
 log = { version = "0.4", optional = true }
-ed25519-dalek = { version = "1.0.1", default_features = false, features = ["u32_backend"], optional = true }
+ed25519-dalek = { version = "2", default_features = false, features = ["digest"], optional = true }
 embassy-embedded-hal = { version = "0.1.0", path = "../../embassy-embedded-hal" }
 embassy-sync = { version = "0.5.0", path = "../../embassy-sync" }
 embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
-salty = { git = "https://github.com/ycrypto/salty.git", rev = "a9f17911a5024698406b75c0fac56ab5ccf6a8c7", optional = true }
+salty = { version = "0.3", optional = true }
-signature = { version = "1.6.4", default-features = false }
+signature = { version = "2.0", default-features = false }
 
 [dev-dependencies]
 log = "0.4"
 env_logger = "0.9"
-rand = "0.7" # ed25519-dalek v1.0.1 depends on this exact version
+rand = "0.8"
 futures = { version = "0.3", features = ["executor"] }
 sha1 = "0.10.5"
 critical-section = { version = "1.1.1", features = ["std"] }
-
+ed25519-dalek = { version = "2", default_features = false, features = ["std", "rand_core", "digest"]  }
-[dev-dependencies.ed25519-dalek]
-default_features = false
-features = ["rand", "std", "u32_backend"]
 
 [features]
 ed25519-dalek = ["dep:ed25519-dalek", "_verify"]

embassy-boot/boot/README.md

@@ -8,6 +8,24 @@ The bootloader can be used either as a library or be flashed directly with the d
 
 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.
 
+## Overview
+
+The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader instance or via linker scripts:
+
+* BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash, but if you need to debug it and have space available, increasing this to 24kB will allow you to run the bootloader with probe-rs.
+* ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. The minimum size required for this partition is the size of your application.
+* DFU - Where the application-to-be-swapped is placed. This partition is written to by the application. This partition must be at least 1 page bigger than the ACTIVE partition.
+* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped. 
+
+For any partition, the following preconditions are required:
+
+* Partitions must be aligned on the page size.
+* Partitions must be a multiple of the page size.
+
+The linker scripts for the application and bootloader look similar, but the FLASH region must point to the BOOTLOADER partition for the bootloader, and the ACTIVE partition for the application.
+
+For more details on the bootloader, see [the documentation](https://embassy.dev/book/dev/bootloader.html).
+
 ## Hardware support
 
 The bootloader supports different hardware in separate crates:
@@ -16,6 +34,7 @@ The bootloader supports different hardware in separate crates:
 * `embassy-boot-rp` - for the RP2040 microcontrollers.
 * `embassy-boot-stm32` - for the STM32 microcontrollers.
 
+
 ## Minimum supported Rust version (MSRV)
 
 `embassy-boot` is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.

embassy-boot/boot/src/boot_loader.rs

@@ -5,7 +5,7 @@ use embassy_sync::blocking_mutex::raw::NoopRawMutex;
 use embassy_sync::blocking_mutex::Mutex;
 use embedded_storage::nor_flash::{NorFlash, NorFlashError, NorFlashErrorKind};
 
-use crate::{State, BOOT_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
+use crate::{State, BOOT_MAGIC, DFU_DETACH_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
 
 /// Errors returned by bootloader
 #[derive(PartialEq, Eq, Debug)]
@@ -135,51 +135,44 @@ impl<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash> BootLoader<ACTIVE, DFU, S
     /// The provided aligned_buf argument must satisfy any alignment requirements
     /// given by the partition flashes. All flash operations will use this buffer.
     ///
-    /// SWAPPING
+    /// ## SWAPPING
     ///
     /// Assume a flash size of 3 pages for the active partition, and 4 pages for the DFU partition.
     /// The swap index contains the copy progress, as to allow continuation of the copy process on
     /// power failure. The index counter is represented within 1 or more pages (depending on total
-    /// flash size), where a page X is considered swapped if index at location (X + WRITE_SIZE)
+    /// flash size), where a page X is considered swapped if index at location (`X + WRITE_SIZE`)
     /// contains a zero value. This ensures that index updates can be performed atomically and
     /// avoid a situation where the wrong index value is set (page write size is "atomic").
     ///
-    /// +-----------+------------+--------+--------+--------+--------+
+    ///
     /// | Partition | Swap Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    /// +-----------+------------+--------+--------+--------+--------+
+    /// |-----------|------------|--------|--------|--------|--------|
     /// |    Active |          0 |      1 |      2 |      3 |      - |
     /// |       DFU |          0 |      3 |      2 |      1 |      X |
-    /// +-----------+------------+--------+--------+--------+--------+
     ///
     /// The algorithm starts by copying 'backwards', and after the first step, the layout is
     /// as follows:
     ///
-    /// +-----------+------------+--------+--------+--------+--------+
     /// | Partition | Swap Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    /// +-----------+------------+--------+--------+--------+--------+
+    /// |-----------|------------|--------|--------|--------|--------|
     /// |    Active |          1 |      1 |      2 |      1 |      - |
     /// |       DFU |          1 |      3 |      2 |      1 |      3 |
-    /// +-----------+------------+--------+--------+--------+--------+
     ///
     /// The next iteration performs the same steps
     ///
-    /// +-----------+------------+--------+--------+--------+--------+
     /// | Partition | Swap Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    /// +-----------+------------+--------+--------+--------+--------+
+    /// |-----------|------------|--------|--------|--------|--------|
     /// |    Active |          2 |      1 |      2 |      1 |      - |
     /// |       DFU |          2 |      3 |      2 |      2 |      3 |
-    /// +-----------+------------+--------+--------+--------+--------+
     ///
     /// And again until we're done
     ///
-    /// +-----------+------------+--------+--------+--------+--------+
     /// | Partition | Swap Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    /// +-----------+------------+--------+--------+--------+--------+
+    /// |-----------|------------|--------|--------|--------|--------|
     /// |    Active |          3 |      3 |      2 |      1 |      - |
     /// |       DFU |          3 |      3 |      1 |      2 |      3 |
-    /// +-----------+------------+--------+--------+--------+--------+
     ///
-    /// REVERTING
+    /// ## REVERTING
     ///
     /// The reverting algorithm uses the swap index to discover that images were swapped, but that
     /// the application failed to mark the boot successful. In this case, the revert algorithm will
@@ -190,28 +183,21 @@ impl<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash> BootLoader<ACTIVE, DFU, S
     ///
     /// The revert algorithm works forwards, by starting copying into the 'unused' DFU page at the start.
     ///
-    /// +-----------+--------------+--------+--------+--------+--------+
     /// | Partition | Revert Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    //*/
+    /// |-----------|--------------|--------|--------|--------|--------|
-    /// +-----------+--------------+--------+--------+--------+--------+
     /// |    Active |            3 |      1 |      2 |      1 |      - |
     /// |       DFU |            3 |      3 |      1 |      2 |      3 |
-    /// +-----------+--------------+--------+--------+--------+--------+
     ///
     ///
-    /// +-----------+--------------+--------+--------+--------+--------+
     /// | Partition | Revert Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    /// +-----------+--------------+--------+--------+--------+--------+
+    /// |-----------|--------------|--------|--------|--------|--------|
     /// |    Active |            3 |      1 |      2 |      1 |      - |
     /// |       DFU |            3 |      3 |      2 |      2 |      3 |
-    /// +-----------+--------------+--------+--------+--------+--------+
     ///
-    /// +-----------+--------------+--------+--------+--------+--------+
     /// | Partition | Revert Index | Page 0 | Page 1 | Page 3 | Page 4 |
-    /// +-----------+--------------+--------+--------+--------+--------+
+    /// |-----------|--------------|--------|--------|--------|--------|
     /// |    Active |            3 |      1 |      2 |      3 |      - |
     /// |       DFU |            3 |      3 |      2 |      1 |      3 |
-    /// +-----------+--------------+--------+--------+--------+--------+
     ///
     pub fn prepare_boot(&mut self, aligned_buf: &mut [u8]) -> Result<State, BootError> {
         // Ensure we have enough progress pages to store copy progress
@@ -224,6 +210,7 @@ impl<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash> BootLoader<ACTIVE, DFU, S
         assert_eq!(0, aligned_buf.len() % ACTIVE::WRITE_SIZE);
         assert_eq!(0, aligned_buf.len() % DFU::WRITE_SIZE);
 
+        // Ensure our partitions are able to handle boot operations
         assert_partitions(&self.active, &self.dfu, &self.state, Self::PAGE_SIZE);
 
         // Copy contents from partition N to active
@@ -384,6 +371,8 @@ impl<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash> BootLoader<ACTIVE, DFU, S
 
         if !state_word.iter().any(|&b| b != SWAP_MAGIC) {
             Ok(State::Swap)
+        } else if !state_word.iter().any(|&b| b != DFU_DETACH_MAGIC) {
+            Ok(State::DfuDetach)
         } else {
             Ok(State::Boot)
         }
@@ -398,6 +387,7 @@ fn assert_partitions<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash>(
 ) {
     assert_eq!(active.capacity() as u32 % page_size, 0);
     assert_eq!(dfu.capacity() as u32 % page_size, 0);
+    // DFU partition has to be bigger than ACTIVE partition to handle swap algorithm
     assert!(dfu.capacity() as u32 - active.capacity() as u32 >= page_size);
     assert!(2 + 2 * (active.capacity() as u32 / page_size) <= state.capacity() as u32 / STATE::WRITE_SIZE as u32);
 }

embassy-boot/boot/src/digest_adapters/ed25519_dalek.rs

@@ -1,6 +1,6 @@
 use digest::typenum::U64;
 use digest::{FixedOutput, HashMarker, OutputSizeUser, Update};
-use ed25519_dalek::Digest as _;
+use ed25519_dalek::Digest;
 
 pub struct Sha512(ed25519_dalek::Sha512);
 
@@ -12,7 +12,7 @@ impl Default for Sha512 {
 
 impl Update for Sha512 {
     fn update(&mut self, data: &[u8]) {
-        self.0.update(data)
+        Digest::update(&mut self.0, data)
     }
 }
 

embassy-boot/boot/src/firmware_updater/asynch.rs

@@ -6,7 +6,7 @@ use embassy_sync::blocking_mutex::raw::NoopRawMutex;
 use embedded_storage_async::nor_flash::NorFlash;
 
 use super::FirmwareUpdaterConfig;
-use crate::{FirmwareUpdaterError, State, BOOT_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
+use crate::{FirmwareUpdaterError, State, BOOT_MAGIC, DFU_DETACH_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
 
 /// FirmwareUpdater is an application API for interacting with the BootLoader without the ability to
 /// 'mess up' the internal bootloader state
@@ -79,8 +79,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
     #[cfg(feature = "_verify")]
     pub async fn verify_and_mark_updated(
         &mut self,
-        _public_key: &[u8],
+        _public_key: &[u8; 32],
-        _signature: &[u8],
+        _signature: &[u8; 64],
         _update_len: u32,
     ) -> Result<(), FirmwareUpdaterError> {
         assert!(_update_len <= self.dfu.capacity() as u32);
@@ -89,14 +89,14 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
 
         #[cfg(feature = "ed25519-dalek")]
         {
-            use ed25519_dalek::{PublicKey, Signature, SignatureError, Verifier};
+            use ed25519_dalek::{Signature, SignatureError, Verifier, VerifyingKey};
 
             use crate::digest_adapters::ed25519_dalek::Sha512;
 
             let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
 
-            let public_key = PublicKey::from_bytes(_public_key).map_err(into_signature_error)?;
+            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
-            let signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
+            let signature = Signature::from_bytes(_signature);
 
             let mut chunk_buf = [0; 2];
             let mut message = [0; 64];
@@ -106,7 +106,6 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
         }
         #[cfg(feature = "ed25519-salty")]
         {
-            use salty::constants::{PUBLICKEY_SERIALIZED_LENGTH, SIGNATURE_SERIALIZED_LENGTH};
             use salty::{PublicKey, Signature};
 
             use crate::digest_adapters::salty::Sha512;
@@ -115,10 +114,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
                 FirmwareUpdaterError::Signature(signature::Error::default())
             }
 
-            let public_key: [u8; PUBLICKEY_SERIALIZED_LENGTH] = _public_key.try_into().map_err(into_signature_error)?;
+            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
-            let public_key = PublicKey::try_from(&public_key).map_err(into_signature_error)?;
+            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
-            let signature: [u8; SIGNATURE_SERIALIZED_LENGTH] = _signature.try_into().map_err(into_signature_error)?;
-            let signature = Signature::try_from(&signature).map_err(into_signature_error)?;
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];
@@ -161,6 +158,12 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
         self.state.mark_updated().await
     }
 
+    /// Mark to trigger USB DFU on next boot.
+    pub async fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError> {
+        self.state.verify_booted().await?;
+        self.state.mark_dfu().await
+    }
+
     /// Mark firmware boot successful and stop rollback on reset.
     pub async fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
         self.state.mark_booted().await
@@ -207,6 +210,16 @@ pub struct FirmwareState<'d, STATE> {
 }
 
 impl<'d, STATE: NorFlash> FirmwareState<'d, STATE> {
+    /// Create a firmware state instance from a FirmwareUpdaterConfig with a buffer for magic content and state partition.
+    ///
+    /// # Safety
+    ///
+    /// The `aligned` buffer must have a size of STATE::WRITE_SIZE, and follow the alignment rules for the flash being read from
+    /// and written to.
+    pub fn from_config<DFU: NorFlash>(config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8]) -> Self {
+        Self::new(config.state, aligned)
+    }
+
     /// Create a firmware state instance with a buffer for magic content and state partition.
     ///
     /// # Safety
@@ -247,6 +260,11 @@ impl<'d, STATE: NorFlash> FirmwareState<'d, STATE> {
         self.set_magic(SWAP_MAGIC).await
     }
 
+    /// Mark to trigger USB DFU on next boot.
+    pub async fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError> {
+        self.set_magic(DFU_DETACH_MAGIC).await
+    }
+
     /// Mark firmware boot successful and stop rollback on reset.
     pub async fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
         self.set_magic(BOOT_MAGIC).await

embassy-boot/boot/src/firmware_updater/blocking.rs

@@ -6,7 +6,7 @@ use embassy_sync::blocking_mutex::raw::NoopRawMutex;
 use embedded_storage::nor_flash::NorFlash;
 
 use super::FirmwareUpdaterConfig;
-use crate::{FirmwareUpdaterError, State, BOOT_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
+use crate::{FirmwareUpdaterError, State, BOOT_MAGIC, DFU_DETACH_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
 
 /// Blocking FirmwareUpdater is an application API for interacting with the BootLoader without the ability to
 /// 'mess up' the internal bootloader state
@@ -86,8 +86,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
     #[cfg(feature = "_verify")]
     pub fn verify_and_mark_updated(
         &mut self,
-        _public_key: &[u8],
+        _public_key: &[u8; 32],
-        _signature: &[u8],
+        _signature: &[u8; 64],
         _update_len: u32,
     ) -> Result<(), FirmwareUpdaterError> {
         assert!(_update_len <= self.dfu.capacity() as u32);
@@ -96,14 +96,14 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
 
         #[cfg(feature = "ed25519-dalek")]
         {
-            use ed25519_dalek::{PublicKey, Signature, SignatureError, Verifier};
+            use ed25519_dalek::{Signature, SignatureError, Verifier, VerifyingKey};
 
             use crate::digest_adapters::ed25519_dalek::Sha512;
 
             let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
 
-            let public_key = PublicKey::from_bytes(_public_key).map_err(into_signature_error)?;
+            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
-            let signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
+            let signature = Signature::from_bytes(_signature);
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];
@@ -113,7 +113,6 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
         }
         #[cfg(feature = "ed25519-salty")]
         {
-            use salty::constants::{PUBLICKEY_SERIALIZED_LENGTH, SIGNATURE_SERIALIZED_LENGTH};
             use salty::{PublicKey, Signature};
 
             use crate::digest_adapters::salty::Sha512;
@@ -122,10 +121,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
                 FirmwareUpdaterError::Signature(signature::Error::default())
             }
 
-            let public_key: [u8; PUBLICKEY_SERIALIZED_LENGTH] = _public_key.try_into().map_err(into_signature_error)?;
+            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
-            let public_key = PublicKey::try_from(&public_key).map_err(into_signature_error)?;
+            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
-            let signature: [u8; SIGNATURE_SERIALIZED_LENGTH] = _signature.try_into().map_err(into_signature_error)?;
-            let signature = Signature::try_from(&signature).map_err(into_signature_error)?;
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];
@@ -168,6 +165,12 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
         self.state.mark_updated()
     }
 
+    /// Mark to trigger USB DFU device on next boot.
+    pub fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError> {
+        self.state.verify_booted()?;
+        self.state.mark_dfu()
+    }
+
     /// Mark firmware boot successful and stop rollback on reset.
     pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
         self.state.mark_booted()
@@ -181,10 +184,12 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
     ///
     /// Failing to meet alignment and size requirements may result in a panic.
     pub fn write_firmware(&mut self, offset: usize, data: &[u8]) -> Result<(), FirmwareUpdaterError> {
-        assert!(data.len() >= DFU::ERASE_SIZE);
+        //assert!(data.len() >= DFU::ERASE_SIZE);
         self.state.verify_booted()?;
 
-        self.dfu.erase(offset as u32, (offset + data.len()) as u32)?;
+        if offset == 0 {
+            self.dfu.erase(0, self.dfu.capacity() as u32)?;
+        }
 
         self.dfu.write(offset as u32, data)?;
 
@@ -213,6 +218,16 @@ pub struct BlockingFirmwareState<'d, STATE> {
 }
 
 impl<'d, STATE: NorFlash> BlockingFirmwareState<'d, STATE> {
+    /// Creates a firmware state instance from a FirmwareUpdaterConfig, with a buffer for magic content and state partition.
+    ///
+    /// # Safety
+    ///
+    /// The `aligned` buffer must have a size of STATE::WRITE_SIZE, and follow the alignment rules for the flash being read from
+    /// and written to.
+    pub fn from_config<DFU: NorFlash>(config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8]) -> Self {
+        Self::new(config.state, aligned)
+    }
+
     /// Create a firmware state instance with a buffer for magic content and state partition.
     ///
     /// # Safety
@@ -226,7 +241,7 @@ impl<'d, STATE: NorFlash> BlockingFirmwareState<'d, STATE> {
 
     // Make sure we are running a booted firmware to avoid reverting to a bad state.
     fn verify_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
-        if self.get_state()? == State::Boot {
+        if self.get_state()? == State::Boot || self.get_state()? == State::DfuDetach {
             Ok(())
         } else {
             Err(FirmwareUpdaterError::BadState)
@@ -243,6 +258,8 @@ impl<'d, STATE: NorFlash> BlockingFirmwareState<'d, STATE> {
 
         if !self.aligned.iter().any(|&b| b != SWAP_MAGIC) {
             Ok(State::Swap)
+        } else if !self.aligned.iter().any(|&b| b != DFU_DETACH_MAGIC) {
+            Ok(State::DfuDetach)
         } else {
             Ok(State::Boot)
         }
@@ -253,6 +270,11 @@ impl<'d, STATE: NorFlash> BlockingFirmwareState<'d, STATE> {
         self.set_magic(SWAP_MAGIC)
     }
 
+    /// Mark to trigger USB DFU on next boot.
+    pub fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError> {
+        self.set_magic(DFU_DETACH_MAGIC)
+    }
+
     /// Mark firmware boot successful and stop rollback on reset.
     pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
         self.set_magic(BOOT_MAGIC)

embassy-boot/boot/src/lib.rs

@@ -23,6 +23,7 @@ pub use firmware_updater::{
 
 pub(crate) const BOOT_MAGIC: u8 = 0xD0;
 pub(crate) const SWAP_MAGIC: u8 = 0xF0;
+pub(crate) const DFU_DETACH_MAGIC: u8 = 0xE0;
 
 /// The state of the bootloader after running prepare.
 #[derive(PartialEq, Eq, Debug)]
@@ -32,6 +33,8 @@ pub enum State {
     Boot,
     /// Bootloader has swapped the active partition with the dfu partition and will attempt boot.
     Swap,
+    /// Application has received a request to reboot into DFU mode to apply an update.
+    DfuDetach,
 }
 
 /// Buffer aligned to 32 byte boundary, largest known alignment requirement for embassy-boot.
@@ -272,21 +275,19 @@ mod tests {
         // The following key setup is based on:
         // https://docs.rs/ed25519-dalek/latest/ed25519_dalek/#example
 
-        use ed25519_dalek::Keypair;
+        use ed25519_dalek::{Digest, Sha512, Signature, Signer, SigningKey, VerifyingKey};
         use rand::rngs::OsRng;
 
         let mut csprng = OsRng {};
-        let keypair: Keypair = Keypair::generate(&mut csprng);
+        let keypair = SigningKey::generate(&mut csprng);
 
-        use ed25519_dalek::{Digest, Sha512, Signature, Signer};
         let firmware: &[u8] = b"This are bytes that would otherwise be firmware bytes for DFU.";
         let mut digest = Sha512::new();
         digest.update(&firmware);
         let message = digest.finalize();
         let signature: Signature = keypair.sign(&message);
 
-        use ed25519_dalek::PublicKey;
+        let public_key = keypair.verifying_key();
-        let public_key: PublicKey = keypair.public;
 
         // Setup flash
         let flash = BlockingTestFlash::new(BootLoaderConfig {

embassy-boot/nrf/Cargo.toml

@@ -4,6 +4,12 @@ name = "embassy-boot-nrf"
 version = "0.1.0"
 description = "Bootloader lib for nRF chips"
 license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-nrf-v$VERSION/embassy-boot/nrf/src/"
@@ -25,7 +31,7 @@ embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
 cfg-if = "1.0.0"
 
-nrf-softdevice-mbr = { version = "0.1.0", git = "https://github.com/embassy-rs/nrf-softdevice.git", branch = "master", optional = true }
+nrf-softdevice-mbr = { version = "0.2.0", optional = true }
 
 [features]
 defmt = [

embassy-boot/rp/Cargo.toml

@@ -4,6 +4,12 @@ name = "embassy-boot-rp"
 version = "0.1.0"
 description = "Bootloader lib for RP2040 chips"
 license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-rp-v$VERSION/src/"

embassy-boot/stm32/Cargo.toml

@@ -4,6 +4,12 @@ name = "embassy-boot-stm32"
 version = "0.1.0"
 description = "Bootloader lib for STM32 chips"
 license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-nrf-v$VERSION/embassy-boot/stm32/src/"

embassy-boot/stm32/src/lib.rs

@@ -10,7 +10,10 @@ pub use embassy_boot::{
 use embedded_storage::nor_flash::NorFlash;
 
 /// A bootloader for STM32 devices.
-pub struct BootLoader;
+pub struct BootLoader {
+    /// The reported state of the bootloader after preparing for boot
+    pub state: State,
+}
 
 impl BootLoader {
     /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware
@@ -19,8 +22,8 @@ impl BootLoader {
     ) -> Self {
         let mut aligned_buf = AlignedBuffer([0; BUFFER_SIZE]);
         let mut boot = embassy_boot::BootLoader::new(config);
-        boot.prepare_boot(aligned_buf.as_mut()).expect("Boot prepare error");
+        let state = boot.prepare_boot(aligned_buf.as_mut()).expect("Boot prepare error");
-        Self
+        Self { state }
     }
 
     /// Boots the application.

embassy-embedded-hal/Cargo.toml

@@ -23,8 +23,8 @@ embassy-time = { version = "0.2", path = "../embassy-time", optional = true }
 embedded-hal-02 = { package = "embedded-hal", version = "0.2.6", features = [
     "unproven",
 ] }
-embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.2" }
+embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
 embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
 nb = "1.0.0"

embassy-executor-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
-name = "embassy-macros"
+name = "embassy-executor-macros"
-version = "0.2.1"
+version = "0.4.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "macros for creating the entry point and tasks for embassy-executor"

embassy-executor-macros/README.md

@@ -0,0 +1,15 @@
+# embassy-executor-macros
+
+An [Embassy](https://embassy.dev) project.
+
+NOTE: Do not use this crate directly. The macros are re-exported by `embassy-executor`.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.

embassy-executor/CHANGELOG.md

@@ -7,7 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 0.4.0 - 2023-12-05
+
 - Removed `arch-xtensa`. Use the executor provided by the HAL crate (`esp-hal`, `esp32s3-hal`, etc...) instead.
+- Added an arena allocator for tasks, allowing using the `main` and `task` macros on Rust 1.75 stable. (it is only used if the `nightly` feature is not enabled. When `nightly` is enabled, `type_alias_impl_trait` is used to statically allocate tasks, as before).
 
 ## 0.3.3 - 2023-11-15
 

embassy-executor/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "embassy-executor"
-version = "0.3.3"
+version = "0.4.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "async/await executor designed for embedded usage"
@@ -14,7 +14,7 @@ categories = [
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-executor-v$VERSION/embassy-executor/src/"
 src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-executor/src/"
-features = ["nightly", "defmt"]
+features = ["defmt"]
 flavors = [
     { name = "std",             target = "x86_64-unknown-linux-gnu",     features = ["arch-std", "executor-thread"] },
     { name = "wasm",            target = "wasm32-unknown-unknown",       features = ["arch-wasm", "executor-thread"] },
@@ -25,14 +25,14 @@ flavors = [
 [package.metadata.docs.rs]
 default-target = "thumbv7em-none-eabi"
 targets = ["thumbv7em-none-eabi"]
-features = ["nightly", "defmt", "arch-cortex-m", "executor-thread", "executor-interrupt"]
+features = ["defmt", "arch-cortex-m", "executor-thread", "executor-interrupt"]
 
 [dependencies]
 defmt = { version = "0.3", optional = true }
 log = { version = "0.4.14", optional = true }
 rtos-trace = { version = "0.1.2", optional = true }
 
-embassy-macros = { version = "0.2.1", path = "../embassy-macros" }
+embassy-executor-macros = { version = "0.4.0", path = "../embassy-executor-macros" }
 embassy-time = { version = "0.2", path = "../embassy-time", optional = true}
 critical-section = "1.1"
 
@@ -66,7 +66,7 @@ executor-thread = []
 executor-interrupt = []
 
 # Enable nightly-only features
-nightly = ["embassy-macros/nightly"]
+nightly = ["embassy-executor-macros/nightly"]
 
 turbowakers = []
 

embassy-executor/src/arch/cortex_m.rs

@@ -51,7 +51,7 @@ mod thread {
     use core::arch::asm;
     use core::marker::PhantomData;
 
-    pub use embassy_macros::main_cortex_m as main;
+    pub use embassy_executor_macros::main_cortex_m as main;
 
     use crate::{raw, Spawner};
 

embassy-executor/src/arch/riscv32.rs

@@ -7,7 +7,7 @@ pub use thread::*;
 mod thread {
     use core::marker::PhantomData;
 
-    pub use embassy_macros::main_riscv as main;
+    pub use embassy_executor_macros::main_riscv as main;
     use portable_atomic::{AtomicBool, Ordering};
 
     use crate::{raw, Spawner};

embassy-executor/src/arch/std.rs

@@ -8,7 +8,7 @@ mod thread {
     use std::marker::PhantomData;
     use std::sync::{Condvar, Mutex};
 
-    pub use embassy_macros::main_std as main;
+    pub use embassy_executor_macros::main_std as main;
 
     use crate::{raw, Spawner};
 

embassy-executor/src/arch/wasm.rs

@@ -8,7 +8,7 @@ mod thread {
 
     use core::marker::PhantomData;
 
-    pub use embassy_macros::main_wasm as main;
+    pub use embassy_executor_macros::main_wasm as main;
     use js_sys::Promise;
     use wasm_bindgen::prelude::*;
 

embassy-executor/src/lib.rs

@@ -6,7 +6,7 @@
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
 
-pub use embassy_macros::task;
+pub use embassy_executor_macros::task;
 
 macro_rules! check_at_most_one {
     (@amo [$($feats:literal)*] [] [$($res:tt)*]) => {

embassy-executor/src/raw/mod.rs

@@ -5,7 +5,7 @@
 //! ## WARNING: here be dragons!
 //!
 //! Using this module requires respecting subtle safety contracts. If you can, prefer using the safe
-//! [executor wrappers](crate::Executor) and the [`embassy_executor::task`](embassy_macros::task) macro, which are fully safe.
+//! [executor wrappers](crate::Executor) and the [`embassy_executor::task`](embassy_executor_macros::task) macro, which are fully safe.
 
 #[cfg_attr(target_has_atomic = "ptr", path = "run_queue_atomics.rs")]
 #[cfg_attr(not(target_has_atomic = "ptr"), path = "run_queue_critical_section.rs")]
@@ -97,7 +97,7 @@ impl TaskRef {
 /// A `TaskStorage` must live forever, it may not be deallocated even after the task has finished
 /// running. Hence the relevant methods require `&'static self`. It may be reused, however.
 ///
-/// Internally, the [embassy_executor::task](embassy_macros::task) macro allocates an array of `TaskStorage`s
+/// Internally, the [embassy_executor::task](embassy_executor_macros::task) macro allocates an array of `TaskStorage`s
 /// in a `static`. The most common reason to use the raw `Task` is to have control of where
 /// the memory for the task is allocated: on the stack, or on the heap with e.g. `Box::leak`, etc.
 

embassy-executor/src/spawner.rs

@@ -115,9 +115,9 @@ impl Spawner {
         }
     }
 
-    // Used by the `embassy_macros::main!` macro to throw an error when spawn
+    // Used by the `embassy_executor_macros::main!` macro to throw an error when spawn
     // fails. This is here to allow conditional use of `defmt::unwrap!`
-    // without introducing a `defmt` feature in the `embassy_macros` package,
+    // without introducing a `defmt` feature in the `embassy_executor_macros` package,
     // which would require use of `-Z namespaced-features`.
     /// Spawn a task into an executor, panicking on failure.
     ///

embassy-hal-internal/src/atomic_ring_buffer.rs

@@ -1,3 +1,4 @@
+//! Atomic reusable ringbuffer.
 use core::slice;
 use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering};
 
@@ -14,8 +15,9 @@ use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering};
 /// One concurrent writer and one concurrent reader are supported, even at
 /// different execution priorities (like main and irq).
 pub struct RingBuffer {
+    #[doc(hidden)]
     pub buf: AtomicPtr<u8>,
-    pub len: AtomicUsize,
+    len: AtomicUsize,
 
     // start and end wrap at len*2, not at len.
     // This allows distinguishing "full" and "empty".
@@ -24,11 +26,16 @@ pub struct RingBuffer {
     //
     // This avoids having to consider the ringbuffer "full" at len-1 instead of len.
     // The usual solution is adding a "full" flag, but that can't be made atomic
+    #[doc(hidden)]
     pub start: AtomicUsize,
+    #[doc(hidden)]
     pub end: AtomicUsize,
 }
 
+/// A type which can only read from a ring buffer.
 pub struct Reader<'a>(&'a RingBuffer);
+
+/// A type which can only write to a ring buffer.
 pub struct Writer<'a>(&'a RingBuffer);
 
 impl RingBuffer {
@@ -89,10 +96,12 @@ impl RingBuffer {
         Writer(self)
     }
 
+    /// Return length of buffer.
     pub fn len(&self) -> usize {
         self.len.load(Ordering::Relaxed)
     }
 
+    /// Check if buffer is full.
     pub fn is_full(&self) -> bool {
         let len = self.len.load(Ordering::Relaxed);
         let start = self.start.load(Ordering::Relaxed);
@@ -101,6 +110,7 @@ impl RingBuffer {
         self.wrap(start + len) == end
     }
 
+    /// Check if buffer is empty.
     pub fn is_empty(&self) -> bool {
         let start = self.start.load(Ordering::Relaxed);
         let end = self.end.load(Ordering::Relaxed);
@@ -238,6 +248,7 @@ impl<'a> Writer<'a> {
         [(unsafe { buf.add(end) }, n0), (buf, n1)]
     }
 
+    /// Mark n bytes as written and advance the write index.
     pub fn push_done(&mut self, n: usize) {
         trace!("  ringbuf: push {:?}", n);
         let end = self.0.end.load(Ordering::Relaxed);
@@ -323,6 +334,7 @@ impl<'a> Reader<'a> {
         (unsafe { buf.add(start) }, n)
     }
 
+    /// Mark n bytes as read and allow advance the read index.
     pub fn pop_done(&mut self, n: usize) {
         trace!("  ringbuf: pop {:?}", n);
 

embassy-hal-internal/src/drop.rs

@@ -1,16 +1,20 @@
+//! Types for controlling when drop is invoked.
 use core::mem;
 use core::mem::MaybeUninit;
 
-#[must_use = "to delay the drop handler invokation to the end of the scope"]
+/// A type to delay the drop handler invocation.
+#[must_use = "to delay the drop handler invocation to the end of the scope"]
 pub struct OnDrop<F: FnOnce()> {
     f: MaybeUninit<F>,
 }
 
 impl<F: FnOnce()> OnDrop<F> {
+    /// Create a new instance.
     pub fn new(f: F) -> Self {
         Self { f: MaybeUninit::new(f) }
     }
 
+    /// Prevent drop handler from running.
     pub fn defuse(self) {
         mem::forget(self)
     }
@@ -34,6 +38,7 @@ pub struct DropBomb {
 }
 
 impl DropBomb {
+    /// Create a new instance.
     pub fn new() -> Self {
         Self { _private: () }
     }

embassy-hal-internal/src/lib.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![allow(clippy::new_without_default)]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;

embassy-hal-internal/src/macros.rs

@@ -1,3 +1,4 @@
+/// Types for the peripheral singletons.
 #[macro_export]
 macro_rules! peripherals_definition {
     ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
@@ -29,6 +30,7 @@ macro_rules! peripherals_definition {
     };
 }
 
+/// Define the peripherals struct.
 #[macro_export]
 macro_rules! peripherals_struct {
     ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
@@ -87,6 +89,7 @@ macro_rules! peripherals_struct {
     };
 }
 
+/// Defining peripheral type.
 #[macro_export]
 macro_rules! peripherals {
     ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
@@ -105,6 +108,7 @@ macro_rules! peripherals {
     };
 }
 
+/// Convenience converting into reference.
 #[macro_export]
 macro_rules! into_ref {
     ($($name:ident),*) => {
@@ -114,6 +118,7 @@ macro_rules! into_ref {
     }
 }
 
+/// Implement the peripheral trait.
 #[macro_export]
 macro_rules! impl_peripheral {
     ($type:ident) => {

embassy-hal-internal/src/peripheral.rs

@@ -20,6 +20,7 @@ pub struct PeripheralRef<'a, T> {
 }
 
 impl<'a, T> PeripheralRef<'a, T> {
+    /// Create a new reference to a peripheral.
     #[inline]
     pub fn new(inner: T) -> Self {
         Self {

embassy-hal-internal/src/ratio.rs

@@ -1,3 +1,4 @@
+//! Types for dealing with rational numbers.
 use core::ops::{Add, Div, Mul};
 
 use num_traits::{CheckedAdd, CheckedDiv, CheckedMul};

embassy-macros/README.md

@@ -1,21 +0,0 @@
-# embassy-macros
-
-An [Embassy](https://embassy.dev) project.
-
-Macros for creating the main entry point and tasks that can be spawned by `embassy-executor`. 
-
-NOTE: The macros are re-exported by the `embassy-executor` crate which should be used instead of adding a direct dependency on the `embassy-macros` crate.
-
-## Minimum supported Rust version (MSRV)
-
-The `task` and `main` macros require the type alias impl trait (TAIT) nightly feature in order to compile.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-  <http://www.apache.org/licenses/LICENSE-2.0>)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
-
-at your option.

embassy-net-adin1110/Cargo.toml

@@ -6,23 +6,22 @@ keywords = ["embedded", "ADIN1110", "embassy-net", "embedded-hal-async", "ethern
 categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
-
+repository = "https://github.com/embassy-rs/embassy"
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 heapless = "0.8"
 defmt = { version = "0.3", optional = true }
 log = { version = "0.4", default-features = false, optional = true }
-embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.2" }
+embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
-embedded-hal-bus = { version = "=0.1.0-rc.2", features = ["async"] }
+embedded-hal-bus = { version = "=0.1.0-rc.3", features = ["async"] }
 embassy-net-driver-channel = { version = "0.2.0", path = "../embassy-net-driver-channel" }
 embassy-time = { version = "0.2", path = "../embassy-time" }
 embassy-futures = { version = "0.1.0", path = "../embassy-futures" }
 bitfield = "0.14.0"
 
 [dev-dependencies]
-embedded-hal-mock = { git = "https://github.com/Dirbaio/embedded-hal-mock", rev = "c5c4dca18e043e6386aee02173f61a65fea3981e", features = ["embedded-hal-async", "eh1"] }
+embedded-hal-mock = { version = "0.10.0-rc.4", features = ["embedded-hal-async", "eh1"] }
 crc = "3.0.1"
 env_logger = "0.10"
 critical-section = { version = "1.1.2", features = ["std"] }

embassy-net-adin1110/src/crc32.rs

@@ -1,3 +1,4 @@
+/// CRC32 lookup table.
 pub const CRC32R_LOOKUP_TABLE: [u32; 256] = [
     0x0000_0000,
     0x7707_3096,
@@ -263,8 +264,9 @@ pub const CRC32R_LOOKUP_TABLE: [u32; 256] = [
 pub struct ETH_FCS(pub u32);
 
 impl ETH_FCS {
-    pub const CRC32_OK: u32 = 0x2144_df1c;
+    const CRC32_OK: u32 = 0x2144_df1c;
 
+    /// Create a new frame check sequence from `data`.
     #[must_use]
     pub fn new(data: &[u8]) -> Self {
         let fcs = data.iter().fold(u32::MAX, |crc, byte| {
@@ -274,6 +276,7 @@ impl ETH_FCS {
         Self(fcs)
     }
 
+    /// Update the frame check sequence with `data`.
     #[must_use]
     pub fn update(self, data: &[u8]) -> Self {
         let fcs = data.iter().fold(self.0 ^ u32::MAX, |crc, byte| {
@@ -283,16 +286,19 @@ impl ETH_FCS {
         Self(fcs)
     }
 
+    /// Check if the frame check sequence is correct.
     #[must_use]
     pub fn crc_ok(&self) -> bool {
         self.0 == Self::CRC32_OK
     }
 
+    /// Switch byte order.
     #[must_use]
     pub fn hton_bytes(&self) -> [u8; 4] {
         self.0.to_le_bytes()
     }
 
+    /// Switch byte order as a u32.
     #[must_use]
     pub fn hton(&self) -> u32 {
         self.0.to_le()

embassy-net-adin1110/src/lib.rs

@@ -5,6 +5,7 @@
 #![allow(clippy::missing_errors_doc)]
 #![allow(clippy::missing_panics_doc)]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // must go first!
 mod fmt;
@@ -26,8 +27,9 @@ use embedded_hal_async::digital::Wait;
 use embedded_hal_async::spi::{Error, Operation, SpiDevice};
 use heapless::Vec;
 pub use mdio::MdioBus;
-pub use phy::{Phy10BaseT1x, RegsC22, RegsC45};
+pub use phy::Phy10BaseT1x;
-pub use regs::{Config0, Config2, SpiRegisters as sr, Status0, Status1};
+use phy::{RegsC22, RegsC45};
+use regs::{Config0, Config2, SpiRegisters as sr, Status0, Status1};
 
 use crate::fmt::Bytes;
 use crate::regs::{LedCntrl, LedFunc, LedPol, LedPolarity, SpiHeader};
@@ -446,6 +448,7 @@ pub struct Runner<'d, SPI, INT, RST> {
 }
 
 impl<'d, SPI: SpiDevice, INT: Wait, RST: OutputPin> Runner<'d, SPI, INT, RST> {
+    /// Run the driver.
     #[allow(clippy::too_many_lines)]
     pub async fn run(mut self) -> ! {
         loop {

embassy-net-adin1110/src/mdio.rs

@@ -39,6 +39,7 @@ enum Reg13Op {
 ///
 /// Clause 45 methodes are bases on <https://www.ieee802.org/3/efm/public/nov02/oam/pannell_oam_1_1102.pdf>
 pub trait MdioBus {
+    /// Error type.
     type Error;
 
     /// Read, Clause 22

embassy-net-adin1110/src/regs.rs

@@ -2,6 +2,7 @@ use core::fmt::{Debug, Display};
 
 use bitfield::{bitfield, bitfield_bitrange, bitfield_fields};
 
+#[allow(missing_docs)]
 #[allow(non_camel_case_types)]
 #[derive(Debug, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]

embassy-net-driver-channel/src/lib.rs

@@ -1,5 +1,6 @@
 #![no_std]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // must go first!
 mod fmt;
@@ -15,6 +16,9 @@ use embassy_sync::blocking_mutex::Mutex;
 use embassy_sync::waitqueue::WakerRegistration;
 use embassy_sync::zerocopy_channel;
 
+/// Channel state.
+///
+/// Holds a buffer of packets with size MTU, for both TX and RX.
 pub struct State<const MTU: usize, const N_RX: usize, const N_TX: usize> {
     rx: [PacketBuf<MTU>; N_RX],
     tx: [PacketBuf<MTU>; N_TX],
@@ -24,6 +28,7 @@ pub struct State<const MTU: usize, const N_RX: usize, const N_TX: usize> {
 impl<const MTU: usize, const N_RX: usize, const N_TX: usize> State<MTU, N_RX, N_TX> {
     const NEW_PACKET: PacketBuf<MTU> = PacketBuf::new();
 
+    /// Create a new channel state.
     pub const fn new() -> Self {
         Self {
             rx: [Self::NEW_PACKET; N_RX],
@@ -39,33 +44,45 @@ struct StateInner<'d, const MTU: usize> {
     shared: Mutex<NoopRawMutex, RefCell<Shared>>,
 }
 
-/// State of the LinkState
 struct Shared {
     link_state: LinkState,
     waker: WakerRegistration,
     hardware_address: driver::HardwareAddress,
 }
 
+/// Channel runner.
+///
+/// Holds the shared state and the lower end of channels for inbound and outbound packets.
 pub struct Runner<'d, const MTU: usize> {
     tx_chan: zerocopy_channel::Receiver<'d, NoopRawMutex, PacketBuf<MTU>>,
     rx_chan: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf<MTU>>,
     shared: &'d Mutex<NoopRawMutex, RefCell<Shared>>,
 }
 
+/// State runner.
+///
+/// Holds the shared state of the channel such as link state.
 #[derive(Clone, Copy)]
 pub struct StateRunner<'d> {
     shared: &'d Mutex<NoopRawMutex, RefCell<Shared>>,
 }
 
+/// RX runner.
+///
+/// Holds the lower end of the channel for passing inbound packets up the stack.
 pub struct RxRunner<'d, const MTU: usize> {
     rx_chan: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf<MTU>>,
 }
 
+/// TX runner.
+///
+/// Holds the lower end of the channel for passing outbound packets down the stack.
 pub struct TxRunner<'d, const MTU: usize> {
     tx_chan: zerocopy_channel::Receiver<'d, NoopRawMutex, PacketBuf<MTU>>,
 }
 
 impl<'d, const MTU: usize> Runner<'d, MTU> {
+    /// Split the runner into separate runners for controlling state, rx and tx.
     pub fn split(self) -> (StateRunner<'d>, RxRunner<'d, MTU>, TxRunner<'d, MTU>) {
         (
             StateRunner { shared: self.shared },
@@ -74,6 +91,7 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         )
     }
 
+    /// Split the runner into separate runners for controlling state, rx and tx borrowing the underlying state.
     pub fn borrow_split(&mut self) -> (StateRunner<'_>, RxRunner<'_, MTU>, TxRunner<'_, MTU>) {
         (
             StateRunner { shared: self.shared },
@@ -86,10 +104,12 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         )
     }
 
+    /// Create a state runner sharing the state channel.
     pub fn state_runner(&self) -> StateRunner<'d> {
         StateRunner { shared: self.shared }
     }
 
+    /// Set the link state.
     pub fn set_link_state(&mut self, state: LinkState) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -98,6 +118,7 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         });
     }
 
+    /// Set the hardware address.
     pub fn set_hardware_address(&mut self, address: driver::HardwareAddress) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -106,16 +127,19 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         });
     }
 
+    /// Wait until there is space for more inbound packets and return a slice they can be copied into.
     pub async fn rx_buf(&mut self) -> &mut [u8] {
         let p = self.rx_chan.send().await;
         &mut p.buf
     }
 
+    /// Check if there is space for more inbound packets right now.
     pub fn try_rx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.rx_chan.try_send()?;
         Some(&mut p.buf)
     }
 
+    /// Polling the inbound channel if there is space for packets.
     pub fn poll_rx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.rx_chan.poll_send(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf),
@@ -123,22 +147,26 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         }
     }
 
+    /// Mark packet of len bytes as pushed to the inbound channel.
     pub fn rx_done(&mut self, len: usize) {
         let p = self.rx_chan.try_send().unwrap();
         p.len = len;
         self.rx_chan.send_done();
     }
 
+    /// Wait until there is space for more outbound packets and return a slice they can be copied into.
     pub async fn tx_buf(&mut self) -> &mut [u8] {
         let p = self.tx_chan.receive().await;
         &mut p.buf[..p.len]
     }
 
+    /// Check if there is space for more outbound packets right now.
     pub fn try_tx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.tx_chan.try_receive()?;
         Some(&mut p.buf[..p.len])
     }
 
+    /// Polling the outbound channel if there is space for packets.
     pub fn poll_tx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.tx_chan.poll_receive(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf[..p.len]),
@@ -146,12 +174,14 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         }
     }
 
+    /// Mark outbound packet as copied.
     pub fn tx_done(&mut self) {
         self.tx_chan.receive_done();
     }
 }
 
 impl<'d> StateRunner<'d> {
+    /// Set link state.
     pub fn set_link_state(&self, state: LinkState) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -160,6 +190,7 @@ impl<'d> StateRunner<'d> {
         });
     }
 
+    /// Set the hardware address.
     pub fn set_hardware_address(&self, address: driver::HardwareAddress) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -170,16 +201,19 @@ impl<'d> StateRunner<'d> {
 }
 
 impl<'d, const MTU: usize> RxRunner<'d, MTU> {
+    /// Wait until there is space for more inbound packets and return a slice they can be copied into.
     pub async fn rx_buf(&mut self) -> &mut [u8] {
         let p = self.rx_chan.send().await;
         &mut p.buf
     }
 
+    /// Check if there is space for more inbound packets right now.
     pub fn try_rx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.rx_chan.try_send()?;
         Some(&mut p.buf)
     }
 
+    /// Polling the inbound channel if there is space for packets.
     pub fn poll_rx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.rx_chan.poll_send(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf),
@@ -187,6 +221,7 @@ impl<'d, const MTU: usize> RxRunner<'d, MTU> {
         }
     }
 
+    /// Mark packet of len bytes as pushed to the inbound channel.
     pub fn rx_done(&mut self, len: usize) {
         let p = self.rx_chan.try_send().unwrap();
         p.len = len;
@@ -195,16 +230,19 @@ impl<'d, const MTU: usize> RxRunner<'d, MTU> {
 }
 
 impl<'d, const MTU: usize> TxRunner<'d, MTU> {
+    /// Wait until there is space for more outbound packets and return a slice they can be copied into.
     pub async fn tx_buf(&mut self) -> &mut [u8] {
         let p = self.tx_chan.receive().await;
         &mut p.buf[..p.len]
     }
 
+    /// Check if there is space for more outbound packets right now.
     pub fn try_tx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.tx_chan.try_receive()?;
         Some(&mut p.buf[..p.len])
     }
 
+    /// Polling the outbound channel if there is space for packets.
     pub fn poll_tx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.tx_chan.poll_receive(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf[..p.len]),
@@ -212,11 +250,18 @@ impl<'d, const MTU: usize> TxRunner<'d, MTU> {
         }
     }
 
+    /// Mark outbound packet as copied.
     pub fn tx_done(&mut self) {
         self.tx_chan.receive_done();
     }
 }
 
+/// Create a channel.
+///
+/// Returns a pair of handles for interfacing with the peripheral and the networking stack.
+///
+/// The runner is interfacing with the peripheral at the lower part of the stack.
+/// The device is interfacing with the networking stack on the layer above.
 pub fn new<'d, const MTU: usize, const N_RX: usize, const N_TX: usize>(
     state: &'d mut State<MTU, N_RX, N_TX>,
     hardware_address: driver::HardwareAddress,
@@ -257,17 +302,22 @@ pub fn new<'d, const MTU: usize, const N_RX: usize, const N_TX: usize>(
     )
 }
 
+/// Represents a packet of size MTU.
 pub struct PacketBuf<const MTU: usize> {
     len: usize,
     buf: [u8; MTU],
 }
 
 impl<const MTU: usize> PacketBuf<MTU> {
+    /// Create a new packet buffer.
     pub const fn new() -> Self {
         Self { len: 0, buf: [0; MTU] }
     }
 }
 
+/// Channel device.
+///
+/// Holds the shared state and upper end of channels for inbound and outbound packets.
 pub struct Device<'d, const MTU: usize> {
     rx: zerocopy_channel::Receiver<'d, NoopRawMutex, PacketBuf<MTU>>,
     tx: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf<MTU>>,
@@ -314,6 +364,9 @@ impl<'d, const MTU: usize> embassy_net_driver::Driver for Device<'d, MTU> {
     }
 }
 
+/// A rx token.
+///
+/// Holds inbound receive channel and interfaces with embassy-net-driver.
 pub struct RxToken<'a, const MTU: usize> {
     rx: zerocopy_channel::Receiver<'a, NoopRawMutex, PacketBuf<MTU>>,
 }
@@ -331,6 +384,9 @@ impl<'a, const MTU: usize> embassy_net_driver::RxToken for RxToken<'a, MTU> {
     }
 }
 
+/// A tx token.
+///
+/// Holds outbound transmit channel and interfaces with embassy-net-driver.
 pub struct TxToken<'a, const MTU: usize> {
     tx: zerocopy_channel::Sender<'a, NoopRawMutex, PacketBuf<MTU>>,
 }

embassy-net-enc28j60/Cargo.toml

@@ -8,8 +8,8 @@ license = "MIT OR Apache-2.0"
 edition = "2021"
 
 [dependencies]
-embedded-hal = { version = "1.0.0-rc.2" }
+embedded-hal = { version = "1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
 embassy-net-driver = { version = "0.2.0", path = "../embassy-net-driver" }
 embassy-time = { version = "0.2", path = "../embassy-time" }
 embassy-futures = { version = "0.1.0", path = "../embassy-futures" }

embassy-net-esp-hosted/Cargo.toml

@@ -2,6 +2,10 @@
 name = "embassy-net-esp-hosted"
 version = "0.1.0"
 edition = "2021"
+description = "embassy-net driver for ESP-Hosted"
+keywords = ["embedded", "esp-hosted", "embassy-net", "embedded-hal-async", "wifi", "async"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+license = "MIT OR Apache-2.0"
 
 [dependencies]
 defmt = { version = "0.3", optional = true }
@@ -12,11 +16,10 @@ embassy-sync = { version = "0.5.0", path = "../embassy-sync"}
 embassy-futures = { version = "0.1.0", path = "../embassy-futures"}
 embassy-net-driver-channel = { version = "0.2.0", path = "../embassy-net-driver-channel"}
 
-embedded-hal = { version = "1.0.0-rc.2" }
+embedded-hal = { version = "1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
 
-noproto = { git="https://github.com/embassy-rs/noproto", rev = "f5e6d1f325b6ad4e344f60452b09576e24671f62", default-features = false, features = ["derive"] }
+noproto = "0.1.0"
-#noproto = { version = "0.1", path = "/home/dirbaio/noproto", default-features = false, features = ["derive"] }
 heapless = "0.8"
 
 [package.metadata.embassy_docs]

embassy-net-esp-hosted/README.md

@@ -0,0 +1,27 @@
+# ESP-Hosted `embassy-net` integration
+
+[`embassy-net`](https://crates.io/crates/embassy-net) integration for Espressif SoCs running the the ESP-Hosted stack.
+
+See [`examples`](https://github.com/embassy-rs/embassy/tree/main/examples/nrf52840) directory for usage examples with the nRF52840.
+
+## Supported chips
+
+- W5500
+- W5100S
+
+## Interoperability
+
+This crate can run on any executor.
+
+It supports any SPI driver implementing [`embedded-hal-async`](https://crates.io/crates/embedded-hal-async).
+
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.

embassy-net-esp-hosted/src/control.rs

@@ -5,38 +5,54 @@ use heapless::String;
 use crate::ioctl::Shared;
 use crate::proto::{self, CtrlMsg};
 
+/// Errors reported by control.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// The operation failed with the given error code.
     Failed(u32),
+    /// The operation timed out.
     Timeout,
+    /// Internal error.
     Internal,
 }
 
+/// Handle for managing the network and WiFI state.
 pub struct Control<'a> {
     state_ch: ch::StateRunner<'a>,
     shared: &'a Shared,
 }
 
+/// WiFi mode.
 #[allow(unused)]
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 enum WifiMode {
+    /// No mode.
     None = 0,
+    /// Client station.
     Sta = 1,
+    /// Access point mode.
     Ap = 2,
+    /// Repeater mode.
     ApSta = 3,
 }
 
 pub use proto::CtrlWifiSecProt as Security;
 
+/// WiFi status.
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Status {
+    /// Service Set Identifier.
     pub ssid: String<32>,
+    /// Basic Service Set Identifier.
     pub bssid: [u8; 6],
+    /// Received Signal Strength Indicator.
     pub rssi: i32,
+    /// WiFi channel.
     pub channel: u32,
+    /// Security mode.
     pub security: Security,
 }
 
@@ -65,6 +81,7 @@ impl<'a> Control<'a> {
         Self { state_ch, shared }
     }
 
+    /// Initialize device.
     pub async fn init(&mut self) -> Result<(), Error> {
         debug!("wait for init event...");
         self.shared.init_wait().await;
@@ -82,6 +99,7 @@ impl<'a> Control<'a> {
         Ok(())
     }
 
+    /// Get the current status.
     pub async fn get_status(&mut self) -> Result<Status, Error> {
         let req = proto::CtrlMsgReqGetApConfig {};
         ioctl!(self, ReqGetApConfig, RespGetApConfig, req, resp);
@@ -95,6 +113,7 @@ impl<'a> Control<'a> {
         })
     }
 
+    /// Connect to the network identified by ssid using the provided password.
     pub async fn connect(&mut self, ssid: &str, password: &str) -> Result<(), Error> {
         let req = proto::CtrlMsgReqConnectAp {
             ssid: unwrap!(String::try_from(ssid)),
@@ -108,6 +127,7 @@ impl<'a> Control<'a> {
         Ok(())
     }
 
+    /// Disconnect from any currently connected network.
     pub async fn disconnect(&mut self) -> Result<(), Error> {
         let req = proto::CtrlMsgReqGetStatus {};
         ioctl!(self, ReqDisconnectAp, RespDisconnectAp, req, resp);

embassy-net-esp-hosted/src/lib.rs

@@ -1,4 +1,6 @@
 #![no_std]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 use embassy_futures::select::{select4, Either4};
 use embassy_net_driver_channel as ch;
@@ -97,12 +99,14 @@ enum InterfaceType {
 const MAX_SPI_BUFFER_SIZE: usize = 1600;
 const HEARTBEAT_MAX_GAP: Duration = Duration::from_secs(20);
 
+/// State for the esp-hosted driver.
 pub struct State {
     shared: Shared,
     ch: ch::State<MTU, 4, 4>,
 }
 
 impl State {
+    /// Create a new state.
     pub fn new() -> Self {
         Self {
             shared: Shared::new(),
@@ -111,8 +115,13 @@ impl State {
     }
 }
 
+/// Type alias for network driver.
 pub type NetDriver<'a> = ch::Device<'a, MTU>;
 
+/// Create a new esp-hosted driver using the provided state, SPI peripheral and pins.
+///
+/// Returns a device handle for interfacing with embassy-net, a control handle for
+/// interacting with the driver, and a runner for communicating with the WiFi device.
 pub async fn new<'a, SPI, IN, OUT>(
     state: &'a mut State,
     spi: SPI,
@@ -144,6 +153,7 @@ where
     (device, Control::new(state_ch, &state.shared), runner)
 }
 
+/// Runner for communicating with the WiFi device.
 pub struct Runner<'a, SPI, IN, OUT> {
     ch: ch::Runner<'a, MTU>,
     state_ch: ch::StateRunner<'a>,
@@ -166,6 +176,7 @@ where
 {
     async fn init(&mut self) {}
 
+    /// Run the packet processing.
     pub async fn run(mut self) -> ! {
         debug!("resetting...");
         self.reset.set_low().unwrap();

embassy-net-esp-hosted/src/proto.rs

@@ -4,7 +4,7 @@ use heapless::{String, Vec};
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct ScanResult {
+pub(crate) struct ScanResult {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -19,7 +19,7 @@ pub struct ScanResult {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct ConnectedStaList {
+pub(crate) struct ConnectedStaList {
     #[noproto(tag = "1")]
     pub mac: String<32>,
     #[noproto(tag = "2")]
@@ -29,14 +29,14 @@ pub struct ConnectedStaList {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetMacAddress {
+pub(crate) struct CtrlMsgReqGetMacAddress {
     #[noproto(tag = "1")]
     pub mode: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetMacAddress {
+pub(crate) struct CtrlMsgRespGetMacAddress {
     #[noproto(tag = "1")]
     pub mac: String<32>,
     #[noproto(tag = "2")]
@@ -45,11 +45,11 @@ pub struct CtrlMsgRespGetMacAddress {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetMode {}
+pub(crate) struct CtrlMsgReqGetMode {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetMode {
+pub(crate) struct CtrlMsgRespGetMode {
     #[noproto(tag = "1")]
     pub mode: u32,
     #[noproto(tag = "2")]
@@ -58,32 +58,32 @@ pub struct CtrlMsgRespGetMode {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetMode {
+pub(crate) struct CtrlMsgReqSetMode {
     #[noproto(tag = "1")]
     pub mode: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetMode {
+pub(crate) struct CtrlMsgRespSetMode {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetStatus {}
+pub(crate) struct CtrlMsgReqGetStatus {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetStatus {
+pub(crate) struct CtrlMsgRespGetStatus {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetMacAddress {
+pub(crate) struct CtrlMsgReqSetMacAddress {
     #[noproto(tag = "1")]
     pub mac: String<32>,
     #[noproto(tag = "2")]
@@ -92,18 +92,18 @@ pub struct CtrlMsgReqSetMacAddress {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetMacAddress {
+pub(crate) struct CtrlMsgRespSetMacAddress {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetApConfig {}
+pub(crate) struct CtrlMsgReqGetApConfig {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetApConfig {
+pub(crate) struct CtrlMsgRespGetApConfig {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -120,7 +120,7 @@ pub struct CtrlMsgRespGetApConfig {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqConnectAp {
+pub(crate) struct CtrlMsgReqConnectAp {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -135,7 +135,7 @@ pub struct CtrlMsgReqConnectAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespConnectAp {
+pub(crate) struct CtrlMsgRespConnectAp {
     #[noproto(tag = "1")]
     pub resp: u32,
     #[noproto(tag = "2")]
@@ -144,11 +144,11 @@ pub struct CtrlMsgRespConnectAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetSoftApConfig {}
+pub(crate) struct CtrlMsgReqGetSoftApConfig {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetSoftApConfig {
+pub(crate) struct CtrlMsgRespGetSoftApConfig {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -169,7 +169,7 @@ pub struct CtrlMsgRespGetSoftApConfig {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqStartSoftAp {
+pub(crate) struct CtrlMsgReqStartSoftAp {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -188,7 +188,7 @@ pub struct CtrlMsgReqStartSoftAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespStartSoftAp {
+pub(crate) struct CtrlMsgRespStartSoftAp {
     #[noproto(tag = "1")]
     pub resp: u32,
     #[noproto(tag = "2")]
@@ -197,11 +197,11 @@ pub struct CtrlMsgRespStartSoftAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqScanResult {}
+pub(crate) struct CtrlMsgReqScanResult {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespScanResult {
+pub(crate) struct CtrlMsgRespScanResult {
     #[noproto(tag = "1")]
     pub count: u32,
     #[noproto(repeated, tag = "2")]
@@ -212,11 +212,11 @@ pub struct CtrlMsgRespScanResult {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSoftApConnectedSta {}
+pub(crate) struct CtrlMsgReqSoftApConnectedSta {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSoftApConnectedSta {
+pub(crate) struct CtrlMsgRespSoftApConnectedSta {
     #[noproto(tag = "1")]
     pub num: u32,
     #[noproto(repeated, tag = "2")]
@@ -227,43 +227,43 @@ pub struct CtrlMsgRespSoftApConnectedSta {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqOtaBegin {}
+pub(crate) struct CtrlMsgReqOtaBegin {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespOtaBegin {
+pub(crate) struct CtrlMsgRespOtaBegin {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqOtaWrite {
+pub(crate) struct CtrlMsgReqOtaWrite {
     #[noproto(tag = "1")]
     pub ota_data: Vec<u8, 1024>,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespOtaWrite {
+pub(crate) struct CtrlMsgRespOtaWrite {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqOtaEnd {}
+pub(crate) struct CtrlMsgReqOtaEnd {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespOtaEnd {
+pub(crate) struct CtrlMsgRespOtaEnd {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqVendorIeData {
+pub(crate) struct CtrlMsgReqVendorIeData {
     #[noproto(tag = "1")]
     pub element_id: u32,
     #[noproto(tag = "2")]
@@ -278,7 +278,7 @@ pub struct CtrlMsgReqVendorIeData {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetSoftApVendorSpecificIe {
+pub(crate) struct CtrlMsgReqSetSoftApVendorSpecificIe {
     #[noproto(tag = "1")]
     pub enable: bool,
     #[noproto(tag = "2")]
@@ -291,32 +291,32 @@ pub struct CtrlMsgReqSetSoftApVendorSpecificIe {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetSoftApVendorSpecificIe {
+pub(crate) struct CtrlMsgRespSetSoftApVendorSpecificIe {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetWifiMaxTxPower {
+pub(crate) struct CtrlMsgReqSetWifiMaxTxPower {
     #[noproto(tag = "1")]
     pub wifi_max_tx_power: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetWifiMaxTxPower {
+pub(crate) struct CtrlMsgRespSetWifiMaxTxPower {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetWifiCurrTxPower {}
+pub(crate) struct CtrlMsgReqGetWifiCurrTxPower {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetWifiCurrTxPower {
+pub(crate) struct CtrlMsgRespGetWifiCurrTxPower {
     #[noproto(tag = "1")]
     pub wifi_curr_tx_power: u32,
     #[noproto(tag = "2")]
@@ -325,7 +325,7 @@ pub struct CtrlMsgRespGetWifiCurrTxPower {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqConfigHeartbeat {
+pub(crate) struct CtrlMsgReqConfigHeartbeat {
     #[noproto(tag = "1")]
     pub enable: bool,
     #[noproto(tag = "2")]
@@ -334,7 +334,7 @@ pub struct CtrlMsgReqConfigHeartbeat {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespConfigHeartbeat {
+pub(crate) struct CtrlMsgRespConfigHeartbeat {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
@@ -342,28 +342,28 @@ pub struct CtrlMsgRespConfigHeartbeat {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventEspInit {
+pub(crate) struct CtrlMsgEventEspInit {
     #[noproto(tag = "1")]
     pub init_data: Vec<u8, 64>,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventHeartbeat {
+pub(crate) struct CtrlMsgEventHeartbeat {
     #[noproto(tag = "1")]
     pub hb_num: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventStationDisconnectFromAp {
+pub(crate) struct CtrlMsgEventStationDisconnectFromAp {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventStationDisconnectFromEspSoftAp {
+pub(crate) struct CtrlMsgEventStationDisconnectFromEspSoftAp {
     #[noproto(tag = "1")]
     pub resp: u32,
     #[noproto(tag = "2")]
@@ -372,7 +372,7 @@ pub struct CtrlMsgEventStationDisconnectFromEspSoftAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsg {
+pub(crate) struct CtrlMsg {
     /// msg_type could be req, resp or Event
     #[noproto(tag = "1")]
     pub msg_type: CtrlMsgType,
@@ -390,7 +390,7 @@ pub struct CtrlMsg {
 /// union of all msg ids
 #[derive(Debug, Clone, Eq, PartialEq, noproto::Oneof)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlMsgPayload {
+pub(crate) enum CtrlMsgPayload {
     /// * Requests *
     #[noproto(tag = "101")]
     ReqGetMacAddress(CtrlMsgReqGetMacAddress),
@@ -492,7 +492,7 @@ pub enum CtrlMsgPayload {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlVendorIeType {
+pub(crate) enum CtrlVendorIeType {
     #[default]
     Beacon = 0,
     ProbeReq = 1,
@@ -504,7 +504,7 @@ pub enum CtrlVendorIeType {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlVendorIeid {
+pub(crate) enum CtrlVendorIeid {
     #[default]
     Id0 = 0,
     Id1 = 1,
@@ -513,7 +513,7 @@ pub enum CtrlVendorIeid {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlWifiMode {
+pub(crate) enum CtrlWifiMode {
     #[default]
     None = 0,
     Sta = 1,
@@ -524,7 +524,7 @@ pub enum CtrlWifiMode {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlWifiBw {
+pub(crate) enum CtrlWifiBw {
     #[default]
     BwInvalid = 0,
     Ht20 = 1,
@@ -534,13 +534,15 @@ pub enum CtrlWifiBw {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlWifiPowerSave {
+pub(crate) enum CtrlWifiPowerSave {
     #[default]
     PsInvalid = 0,
     MinModem = 1,
     MaxModem = 2,
 }
 
+/// Wifi Security Settings
+#[allow(missing_docs)]
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -560,7 +562,7 @@ pub enum CtrlWifiSecProt {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlStatus {
+pub(crate) enum CtrlStatus {
     #[default]
     Connected = 0,
     NotConnected = 1,
@@ -573,7 +575,7 @@ pub enum CtrlStatus {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlMsgType {
+pub(crate) enum CtrlMsgType {
     #[default]
     MsgTypeInvalid = 0,
     Req = 1,
@@ -585,7 +587,7 @@ pub enum CtrlMsgType {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlMsgId {
+pub(crate) enum CtrlMsgId {
     #[default]
     MsgIdInvalid = 0,
     /// * Request Msgs *

embassy-net-tuntap/Cargo.toml

@@ -6,6 +6,7 @@ keywords = ["embedded", "tuntap", "embassy-net", "embedded-hal-async", "ethernet
 categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
 
 [dependencies]
 embassy-net-driver = { version = "0.2.0", path = "../embassy-net-driver" }

embassy-net-tuntap/src/lib.rs

@@ -1,3 +1,5 @@
+#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
 use std::io;
 use std::io::{Read, Write};
 use std::os::unix::io::{AsRawFd, RawFd};
@@ -7,12 +9,19 @@ use async_io::Async;
 use embassy_net_driver::{self, Capabilities, Driver, HardwareAddress, LinkState};
 use log::*;
 
+/// Get the MTU of the given interface.
 pub const SIOCGIFMTU: libc::c_ulong = 0x8921;
+/// Get the index of the given interface.
 pub const _SIOCGIFINDEX: libc::c_ulong = 0x8933;
+/// Capture all packages.
 pub const _ETH_P_ALL: libc::c_short = 0x0003;
+/// Set the interface flags.
 pub const TUNSETIFF: libc::c_ulong = 0x400454CA;
+/// TUN device.
 pub const _IFF_TUN: libc::c_int = 0x0001;
+/// TAP device.
 pub const IFF_TAP: libc::c_int = 0x0002;
+/// No packet information.
 pub const IFF_NO_PI: libc::c_int = 0x1000;
 
 const ETHERNET_HEADER_LEN: usize = 14;
@@ -47,6 +56,7 @@ fn ifreq_ioctl(lower: libc::c_int, ifreq: &mut ifreq, cmd: libc::c_ulong) -> io:
     Ok(ifreq.ifr_data)
 }
 
+/// A TUN/TAP device.
 #[derive(Debug)]
 pub struct TunTap {
     fd: libc::c_int,
@@ -60,6 +70,7 @@ impl AsRawFd for TunTap {
 }
 
 impl TunTap {
+    /// Create a new TUN/TAP device.
     pub fn new(name: &str) -> io::Result<TunTap> {
         unsafe {
             let fd = libc::open(
@@ -126,11 +137,13 @@ impl io::Write for TunTap {
     }
 }
 
+/// A TUN/TAP device, wrapped in an async interface.
 pub struct TunTapDevice {
     device: Async<TunTap>,
 }
 
 impl TunTapDevice {
+    /// Create a new TUN/TAP device.
     pub fn new(name: &str) -> io::Result<TunTapDevice> {
         Ok(Self {
             device: Async::new(TunTap::new(name)?)?,

embassy-net-wiznet/Cargo.toml

@@ -6,10 +6,11 @@ keywords = ["embedded", "wiznet", "embassy-net", "embedded-hal-async", "ethernet
 categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
 
 [dependencies]
-embedded-hal = { version = "1.0.0-rc.2" }
+embedded-hal = { version = "1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
 embassy-net-driver-channel = { version = "0.2.0", path = "../embassy-net-driver-channel" }
 embassy-time = { version = "0.2", path = "../embassy-time" }
 embassy-futures = { version = "0.1.0", path = "../embassy-futures" }

embassy-net-wiznet/src/chip/mod.rs

@@ -1,3 +1,4 @@
+//! Wiznet W5100s and W5500 family driver.
 mod w5500;
 pub use w5500::W5500;
 mod w5100s;
@@ -45,4 +46,5 @@ pub(crate) mod sealed {
     }
 }
 
+/// Trait for Wiznet chips.
 pub trait Chip: sealed::Chip {}

embassy-net-wiznet/src/chip/w5100s.rs

@@ -4,6 +4,7 @@ const SOCKET_BASE: u16 = 0x400;
 const TX_BASE: u16 = 0x4000;
 const RX_BASE: u16 = 0x6000;
 
+/// Wizard W5100S chip.
 pub enum W5100S {}
 
 impl super::Chip for W5100S {}

embassy-net-wiznet/src/chip/w5500.rs

@@ -8,6 +8,7 @@ pub enum RegisterBlock {
     RxBuf = 0x03,
 }
 
+/// Wiznet W5500 chip.
 pub enum W5500 {}
 
 impl super::Chip for W5500 {}

embassy-net-wiznet/src/lib.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 pub mod chip;
 mod device;
@@ -47,6 +48,7 @@ pub struct Runner<'d, C: Chip, SPI: SpiDevice, INT: Wait, RST: OutputPin> {
 
 /// You must call this in a background task for the driver to operate.
 impl<'d, C: Chip, SPI: SpiDevice, INT: Wait, RST: OutputPin> Runner<'d, C, SPI, INT, RST> {
+    /// Run the driver.
     pub async fn run(mut self) -> ! {
         let (state_chan, mut rx_chan, mut tx_chan) = self.ch.split();
         let mut tick = Ticker::every(Duration::from_millis(500));

embassy-net/src/lib.rs

@@ -411,10 +411,12 @@ impl<D: Driver> Stack<D> {
     /// ```ignore
     /// let config = embassy_net::Config::dhcpv4(Default::default());
     ///// Init network stack
-    /// let stack = &*make_static!(embassy_net::Stack::new(
+    /// static RESOURCES: StaticCell<embassy_net::StackResources<2> = StaticCell::new();
+    /// static STACK: StaticCell<embassy_net::Stack> = StaticCell::new();
+    /// let stack = &*STACK.init(embassy_net::Stack::new(
     ///    device,
     ///    config,
-    ///    make_static!(embassy_net::StackResources::<2>::new()),
+    ///    RESOURCES.init(embassy_net::StackResources::new()),
     ///    seed
     /// ));
     /// // Launch network task that runs `stack.run().await`

embassy-nrf/Cargo.toml

@@ -64,6 +64,11 @@ nfc-pins-as-gpio = []
 # nrf52820, nrf52833, nrf52840: P0_18
 reset-pin-as-gpio = []
 
+# Implements the MultiwriteNorFlash trait for QSPI. Should only be enabled if your external
+# flash supports the semantics described in
+# https://docs.rs/embedded-storage/0.3.1/embedded_storage/nor_flash/trait.MultiwriteNorFlash.html
+qspi-multiwrite-flash = []
+
 # Features starting with `_` are for internal use only. They're not intended
 # to be enabled by other crates, and are not covered by semver guarantees.
 
@@ -94,8 +99,8 @@ embassy-embedded-hal = {version = "0.1.0", path = "../embassy-embedded-hal" }
 embassy-usb-driver = {version = "0.1.0", path = "../embassy-usb-driver" }
 
 embedded-hal-02 = { package = "embedded-hal", version = "0.2.6", features = ["unproven"] }
-embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.2" }
+embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
 embedded-io = { version = "0.6.0" }
 embedded-io-async = { version = "0.6.1" }
 
@@ -120,4 +125,3 @@ nrf52840-pac = { version = "0.12.0", optional = true }
 nrf5340-app-pac = { version = "0.12.0", optional = true }
 nrf5340-net-pac = { version = "0.12.0", optional = true }
 nrf9160-pac = { version = "0.12.0", optional = true }
-

embassy-nrf/README.md

@@ -6,6 +6,8 @@ The Embassy nRF HAL targets the Nordic Semiconductor nRF family of hardware. The
 for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to
 complete operations in low power mod and handling interrupts, so that applications can focus on more important matters.
 
+NOTE: The Embassy HALs can be used both for non-async and async operations. For async, you can choose which runtime you want to use.
+
 ## EasyDMA considerations
 
 On nRF chips, peripherals can use the so called EasyDMA feature to offload the task of interacting

embassy-nrf/src/gpio.rs

@@ -50,21 +50,21 @@ impl<'d, T: Pin> Input<'d, T> {
         Self { pin }
     }
 
-    /// Test if current pin level is high.
+    /// Get whether the pin input level is high.
     #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
         self.pin.is_high()
     }
 
-    /// Test if current pin level is low.
+    /// Get whether the pin input level is low.
     #[inline]
-    pub fn is_low(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
         self.pin.is_low()
     }
 
-    /// Returns current pin level
+    /// Get the pin input level.
     #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
         self.pin.get_level()
     }
 }
@@ -158,21 +158,21 @@ impl<'d, T: Pin> Output<'d, T> {
         self.pin.set_level(level)
     }
 
-    /// Is the output pin set as high?
+    /// Get whether the output level is set to high.
     #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
         self.pin.is_set_high()
     }
 
-    /// Is the output pin set as low?
+    /// Get whether the output level is set to low.
     #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
         self.pin.is_set_low()
     }
 
-    /// What level output is set to
+    /// Get the current output level.
     #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
         self.pin.get_output_level()
     }
 }
@@ -275,21 +275,26 @@ impl<'d, T: Pin> Flex<'d, T> {
         self.pin.conf().reset();
     }
 
-    /// Test if current pin level is high.
+    /// Get whether the pin input level is high.
     #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
         !self.is_low()
     }
 
-    /// Test if current pin level is low.
+    /// Get whether the pin input level is low.
     #[inline]
-    pub fn is_low(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
+        self.ref_is_low()
+    }
+
+    #[inline]
+    pub(crate) fn ref_is_low(&self) -> bool {
         self.pin.block().in_.read().bits() & (1 << self.pin.pin()) == 0
     }
 
-    /// Returns current pin level
+    /// Get the pin input level.
     #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
         self.is_high().into()
     }
 
@@ -314,21 +319,26 @@ impl<'d, T: Pin> Flex<'d, T> {
         }
     }
 
-    /// Is the output pin set as high?
+    /// Get whether the output level is set to high.
     #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
         !self.is_set_low()
     }
 
-    /// Is the output pin set as low?
+    /// Get whether the output level is set to low.
     #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
+        self.ref_is_set_low()
+    }
+
+    #[inline]
+    pub(crate) fn ref_is_set_low(&self) -> bool {
         self.pin.block().out.read().bits() & (1 << self.pin.pin()) == 0
     }
 
-    /// What level output is set to
+    /// Get the current output level.
     #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
         self.is_set_high().into()
     }
 }
@@ -498,11 +508,11 @@ mod eh02 {
         type Error = Infallible;
 
         fn is_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_high())
+            Ok(!self.pin.ref_is_low())
         }
 
         fn is_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_low())
+            Ok(self.pin.ref_is_low())
         }
     }
 
@@ -520,11 +530,11 @@ mod eh02 {
 
     impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for Output<'d, T> {
         fn is_set_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_high())
+            Ok(!self.pin.ref_is_set_low())
         }
 
         fn is_set_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_low())
+            Ok(self.pin.ref_is_set_low())
         }
     }
 
@@ -535,11 +545,11 @@ mod eh02 {
         type Error = Infallible;
 
         fn is_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_high())
+            Ok(!self.ref_is_low())
         }
 
         fn is_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_low())
+            Ok(self.ref_is_low())
         }
     }
 
@@ -557,11 +567,11 @@ mod eh02 {
 
     impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for Flex<'d, T> {
         fn is_set_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_high())
+            Ok(!self.ref_is_set_low())
         }
 
         fn is_set_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_low())
+            Ok(self.ref_is_set_low())
         }
     }
 }
@@ -571,11 +581,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for Input<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for Input<'d, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_high())
     }
 
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_low())
     }
 }
@@ -595,11 +605,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for Output<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for Output<'d, T> {
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_high())
     }
 
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_low())
     }
 }
@@ -612,11 +622,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for Flex<'d, T> {
 ///
 /// If the pin is not in input mode the result is unspecified.
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for Flex<'d, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_high())
     }
 
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_low())
     }
 }
@@ -632,11 +642,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for Flex<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for Flex<'d, T> {
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_high())
     }
 
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_low())
     }
 }

embassy-nrf/src/gpiote.rs

@@ -243,7 +243,7 @@ impl<'d, C: Channel, T: GpioPin> Drop for OutputChannel<'d, C, T> {
 
 impl<'d, C: Channel, T: GpioPin> OutputChannel<'d, C, T> {
     /// Create a new GPIOTE output channel driver.
-    pub fn new(ch: impl Peripheral<P = C> + 'd, pin: Output<'d, T>, polarity: OutputChannelPolarity) -> Self {
+    pub fn new(ch: impl Peripheral<P = C> + 'd, mut pin: Output<'d, T>, polarity: OutputChannelPolarity) -> Self {
         into_ref!(ch);
         let g = regs();
         let num = ch.number();
@@ -481,11 +481,11 @@ mod eh02 {
         type Error = Infallible;
 
         fn is_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.pin.is_high())
+            Ok(!self.pin.pin.ref_is_low())
         }
 
         fn is_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.pin.is_low())
+            Ok(self.pin.pin.ref_is_low())
         }
     }
 }
@@ -495,11 +495,11 @@ impl<'d, C: Channel, T: GpioPin> embedded_hal_1::digital::ErrorType for InputCha
 }
 
 impl<'d, C: Channel, T: GpioPin> embedded_hal_1::digital::InputPin for InputChannel<'d, C, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.pin.is_high())
     }
 
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.pin.is_low())
     }
 }

embassy-nrf/src/lib.rs

@@ -97,6 +97,28 @@ mod chip;
 /// This defines the right interrupt handlers, and creates a unit struct (like `struct Irqs;`)
 /// and implements the right [`Binding`]s for it. You can pass this struct to drivers to
 /// prove at compile-time that the right interrupts have been bound.
+///
+/// Example of how to bind one interrupt:
+///
+/// ```rust,ignore
+/// use embassy_nrf::{bind_interrupts, spim, peripherals};
+///
+/// bind_interrupts!(struct Irqs {
+///     SPIM3 => spim::InterruptHandler<peripherals::SPI3>;
+/// });
+/// ```
+///
+/// Example of how to bind multiple interrupts in a single macro invocation:
+///
+/// ```rust,ignore
+/// use embassy_nrf::{bind_interrupts, spim, twim, peripherals};
+///
+/// bind_interrupts!(struct Irqs {
+///     SPIM3 => spim::InterruptHandler<peripherals::SPI3>;
+///     SPIM0_SPIS0_TWIM0_TWIS0_SPI0_TWI0 => twim::InterruptHandler<peripherals::TWISPI0>;
+/// });
+/// ```
+
 // developer note: this macro can't be in `embassy-hal-internal` due to the use of `$crate`.
 #[macro_export]
 macro_rules! bind_interrupts {
@@ -332,7 +354,11 @@ unsafe fn uicr_write_masked(address: *mut u32, value: u32, mask: u32) -> WriteRe
     WriteResult::Written
 }
 
-/// Initialize peripherals with the provided configuration. This should only be called once at startup.
+/// Initialize the `embassy-nrf` HAL with the provided configuration.
+///
+/// This returns the peripheral singletons that can be used for creating drivers.
+///
+/// This should only be called once at startup, otherwise it panics.
 pub fn init(config: config::Config) -> Peripherals {
     // Do this first, so that it panics if user is calling `init` a second time
     // before doing anything important.

embassy-nrf/src/qspi.rs

@@ -605,6 +605,9 @@ impl<'d, T: Instance> NorFlash for Qspi<'d, T> {
     }
 }
 
+#[cfg(feature = "qspi-multiwrite-flash")]
+impl<'d, T: Instance> embedded_storage::nor_flash::MultiwriteNorFlash for Qspi<'d, T> {}
+
 mod _eh1 {
     use embedded_storage_async::nor_flash::{NorFlash as AsyncNorFlash, ReadNorFlash as AsyncReadNorFlash};
 

embassy-rp/Cargo.toml

@@ -78,14 +78,14 @@ fixed = "1.23.1"
 rp-pac = { version = "6" }
 
 embedded-hal-02 = { package = "embedded-hal", version = "0.2.6", features = ["unproven"] }
-embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.2" }
+embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.3" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
-embedded-hal-nb = { version = "=1.0.0-rc.2" }
+embedded-hal-nb = { version = "=1.0.0-rc.3" }
 
 pio-proc = {version= "0.2" }
 pio = {version= "0.2.1" }
 rp2040-boot2 = "0.3"
 
 [dev-dependencies]
-embassy-executor = { version = "0.3.3", path = "../embassy-executor", features = ["nightly", "arch-std", "executor-thread"] }
+embassy-executor = { version = "0.4.0", path = "../embassy-executor", features = ["arch-std", "executor-thread"] }
 static_cell = { version = "2" }

embassy-rp/README.md

@@ -0,0 +1,23 @@
+# Embassy RP HAL
+
+HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed.
+
+The Embassy RP HAL targets the Raspberry Pi 2040 family of hardware. The HAL implements both blocking and async APIs
+for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to
+complete operations in low power mod and handling interrupts, so that applications can focus on more important matters.
+
+NOTE: The Embassy HALs can be used both for non-async and async operations. For async, you can choose which runtime you want to use.
+
+## Minimum supported Rust version (MSRV)
+
+Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.

embassy-rp/src/adc.rs

@@ -1,3 +1,4 @@
+//! ADC driver.
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::mem;
@@ -16,6 +17,7 @@ use crate::{dma, interrupt, pac, peripherals, Peripheral, RegExt};
 
 static WAKER: AtomicWaker = AtomicWaker::new();
 
+/// ADC config.
 #[non_exhaustive]
 pub struct Config {}
 
@@ -30,9 +32,11 @@ enum Source<'p> {
     TempSensor(PeripheralRef<'p, ADC_TEMP_SENSOR>),
 }
 
+/// ADC channel.
 pub struct Channel<'p>(Source<'p>);
 
 impl<'p> Channel<'p> {
+    /// Create a new ADC channel from pin with the provided [Pull] configuration.
     pub fn new_pin(pin: impl Peripheral<P = impl AdcPin + 'p> + 'p, pull: Pull) -> Self {
         into_ref!(pin);
         pin.pad_ctrl().modify(|w| {
@@ -49,6 +53,7 @@ impl<'p> Channel<'p> {
         Self(Source::Pin(pin.map_into()))
     }
 
+    /// Create a new ADC channel for the internal temperature sensor.
     pub fn new_temp_sensor(s: impl Peripheral<P = ADC_TEMP_SENSOR> + 'p) -> Self {
         let r = pac::ADC;
         r.cs().write_set(|w| w.set_ts_en(true));
@@ -83,35 +88,44 @@ impl<'p> Drop for Source<'p> {
     }
 }
 
+/// ADC sample.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Default)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(transparent)]
 pub struct Sample(u16);
 
 impl Sample {
+    /// Sample is valid.
     pub fn good(&self) -> bool {
         self.0 < 0x8000
     }
 
+    /// Sample value.
     pub fn value(&self) -> u16 {
         self.0 & !0x8000
     }
 }
 
+/// ADC error.
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Error converting value.
     ConversionFailed,
 }
 
+/// ADC mode.
 pub trait Mode {}
 
+/// ADC async mode.
 pub struct Async;
 impl Mode for Async {}
 
+/// ADC blocking mode.
 pub struct Blocking;
 impl Mode for Blocking {}
 
+/// ADC driver.
 pub struct Adc<'d, M: Mode> {
     phantom: PhantomData<(&'d ADC, M)>,
 }
@@ -150,6 +164,7 @@ impl<'d, M: Mode> Adc<'d, M> {
         while !r.cs().read().ready() {}
     }
 
+    /// Sample a value from a channel in blocking mode.
     pub fn blocking_read(&mut self, ch: &mut Channel) -> Result<u16, Error> {
         let r = Self::regs();
         r.cs().modify(|w| {
@@ -166,6 +181,7 @@ impl<'d, M: Mode> Adc<'d, M> {
 }
 
 impl<'d> Adc<'d, Async> {
+    /// Create ADC driver in async mode.
     pub fn new(
         _inner: impl Peripheral<P = ADC> + 'd,
         _irq: impl Binding<interrupt::typelevel::ADC_IRQ_FIFO, InterruptHandler>,
@@ -194,6 +210,7 @@ impl<'d> Adc<'d, Async> {
         .await;
     }
 
+    /// Sample a value from a channel until completed.
     pub async fn read(&mut self, ch: &mut Channel<'_>) -> Result<u16, Error> {
         let r = Self::regs();
         r.cs().modify(|w| {
@@ -272,6 +289,7 @@ impl<'d> Adc<'d, Async> {
         }
     }
 
+    /// Sample multiple values from a channel using DMA.
     #[inline]
     pub async fn read_many<S: AdcSample>(
         &mut self,
@@ -283,6 +301,7 @@ impl<'d> Adc<'d, Async> {
         self.read_many_inner(ch, buf, false, div, dma).await
     }
 
+    /// Sample multiple values from a channel using DMA with errors inlined in samples.
     #[inline]
     pub async fn read_many_raw(
         &mut self,
@@ -299,6 +318,7 @@ impl<'d> Adc<'d, Async> {
 }
 
 impl<'d> Adc<'d, Blocking> {
+    /// Create ADC driver in blocking mode.
     pub fn new_blocking(_inner: impl Peripheral<P = ADC> + 'd, _config: Config) -> Self {
         Self::setup();
 
@@ -306,6 +326,7 @@ impl<'d> Adc<'d, Blocking> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler {
     _empty: (),
 }
@@ -324,6 +345,7 @@ mod sealed {
     pub trait AdcChannel {}
 }
 
+/// ADC sample.
 pub trait AdcSample: sealed::AdcSample {}
 
 impl sealed::AdcSample for u16 {}
@@ -332,7 +354,9 @@ impl AdcSample for u16 {}
 impl sealed::AdcSample for u8 {}
 impl AdcSample for u8 {}
 
+/// ADC channel.
 pub trait AdcChannel: sealed::AdcChannel {}
+/// ADC pin.
 pub trait AdcPin: AdcChannel + gpio::Pin {}
 
 macro_rules! impl_pin {

embassy-rp/src/clocks.rs

@@ -1,3 +1,4 @@
+//! Clock configuration for the RP2040
 use core::arch::asm;
 use core::marker::PhantomData;
 use core::sync::atomic::{AtomicU16, AtomicU32, Ordering};
@@ -44,34 +45,50 @@ static CLOCKS: Clocks = Clocks {
     rtc: AtomicU16::new(0),
 };
 
+/// Peripheral clock sources.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum PeriClkSrc {
+    /// SYS.
     Sys = ClkPeriCtrlAuxsrc::CLK_SYS as _,
+    /// PLL SYS.
     PllSys = ClkPeriCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// PLL USB.
     PllUsb = ClkPeriCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// ROSC.
     Rosc = ClkPeriCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkPeriCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkPeriCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkPeriCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// CLock configuration.
 #[non_exhaustive]
 pub struct ClockConfig {
+    /// Ring oscillator configuration.
     pub rosc: Option<RoscConfig>,
+    /// External oscillator configuration.
     pub xosc: Option<XoscConfig>,
+    /// Reference clock configuration.
     pub ref_clk: RefClkConfig,
+    /// System clock configuration.
     pub sys_clk: SysClkConfig,
+    /// Peripheral clock source configuration.
     pub peri_clk_src: Option<PeriClkSrc>,
+    /// USB clock configuration.
     pub usb_clk: Option<UsbClkConfig>,
+    /// ADC clock configuration.
     pub adc_clk: Option<AdcClkConfig>,
+    /// RTC clock configuration.
     pub rtc_clk: Option<RtcClkConfig>,
     // gpin0: Option<(u32, Gpin<'static, AnyPin>)>,
     // gpin1: Option<(u32, Gpin<'static, AnyPin>)>,
 }
 
 impl ClockConfig {
+    /// Clock configuration derived from external crystal.
     pub fn crystal(crystal_hz: u32) -> Self {
         Self {
             rosc: Some(RoscConfig {
@@ -130,6 +147,7 @@ impl ClockConfig {
         }
     }
 
+    /// Clock configuration from internal oscillator.
     pub fn rosc() -> Self {
         Self {
             rosc: Some(RoscConfig {
@@ -179,130 +197,190 @@ impl ClockConfig {
     // }
 }
 
+/// ROSC freq range.
 #[repr(u16)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RoscRange {
+    /// Low range.
     Low = pac::rosc::vals::FreqRange::LOW.0,
+    /// Medium range (1.33x low)
     Medium = pac::rosc::vals::FreqRange::MEDIUM.0,
+    /// High range (2x low)
     High = pac::rosc::vals::FreqRange::HIGH.0,
+    /// Too high. Should not be used.
     TooHigh = pac::rosc::vals::FreqRange::TOOHIGH.0,
 }
 
+/// On-chip ring oscillator configuration.
 pub struct RoscConfig {
     /// Final frequency of the oscillator, after the divider has been applied.
     /// The oscillator has a nominal frequency of 6.5MHz at medium range with
     /// divider 16 and all drive strengths set to 0, other values should be
     /// measured in situ.
     pub hz: u32,
+    /// Oscillator range.
     pub range: RoscRange,
+    /// Drive strength for oscillator.
     pub drive_strength: [u8; 8],
+    /// Output divider.
     pub div: u16,
 }
 
+/// Crystal oscillator configuration.
 pub struct XoscConfig {
+    /// Final frequency of the oscillator.
     pub hz: u32,
+    /// Configuring PLL for the system clock.
     pub sys_pll: Option<PllConfig>,
+    /// Configuring PLL for the USB clock.
     pub usb_pll: Option<PllConfig>,
+    /// Multiplier for the startup delay.
     pub delay_multiplier: u32,
 }
 
+/// PLL configuration.
 pub struct PllConfig {
+    /// Reference divisor.
     pub refdiv: u8,
+    /// Feedback divisor.
     pub fbdiv: u16,
+    /// Output divisor 1.
     pub post_div1: u8,
+    /// Output divisor 2.
     pub post_div2: u8,
 }
 
+/// Reference clock config.
 pub struct RefClkConfig {
+    /// Reference clock source.
     pub src: RefClkSrc,
+    /// Reference clock divider.
     pub div: u8,
 }
 
+/// Reference clock source.
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RefClkSrc {
-    // main sources
+    /// XOSC.
     Xosc,
+    /// ROSC.
     Rosc,
-    // aux sources
+    /// PLL USB.
     PllUsb,
     // Gpin0,
     // Gpin1,
 }
 
+/// SYS clock source.
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum SysClkSrc {
-    // main sources
+    /// REF.
     Ref,
-    // aux sources
+    /// PLL SYS.
     PllSys,
+    /// PLL USB.
     PllUsb,
+    /// ROSC.
     Rosc,
+    /// XOSC.
     Xosc,
     // Gpin0,
     // Gpin1,
 }
 
+/// SYS clock config.
 pub struct SysClkConfig {
+    /// SYS clock source.
     pub src: SysClkSrc,
+    /// SYS clock divider.
     pub div_int: u32,
+    /// SYS clock fraction.
     pub div_frac: u8,
 }
 
+/// USB clock source.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum UsbClkSrc {
+    /// PLL USB.
     PllUsb = ClkUsbCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// PLL SYS.
     PllSys = ClkUsbCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// ROSC.
     Rosc = ClkUsbCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkUsbCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkUsbCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkUsbCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// USB clock config.
 pub struct UsbClkConfig {
+    /// USB clock source.
     pub src: UsbClkSrc,
+    /// USB clock divider.
     pub div: u8,
+    /// USB clock phase.
     pub phase: u8,
 }
 
+/// ADC clock source.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum AdcClkSrc {
+    /// PLL USB.
     PllUsb = ClkAdcCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// PLL SYS.
     PllSys = ClkAdcCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// ROSC.
     Rosc = ClkAdcCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkAdcCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkAdcCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkAdcCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// ADC clock config.
 pub struct AdcClkConfig {
+    /// ADC clock source.
     pub src: AdcClkSrc,
+    /// ADC clock divider.
     pub div: u8,
+    /// ADC clock phase.
     pub phase: u8,
 }
 
+/// RTC clock source.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RtcClkSrc {
+    /// PLL USB.
     PllUsb = ClkRtcCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// PLL SYS.
     PllSys = ClkRtcCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// ROSC.
     Rosc = ClkRtcCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkRtcCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkRtcCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkRtcCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// RTC clock config.
 pub struct RtcClkConfig {
+    /// RTC clock source.
     pub src: RtcClkSrc,
+    /// RTC clock divider.
     pub div_int: u32,
+    /// RTC clock divider fraction.
     pub div_frac: u8,
+    /// RTC clock phase.
     pub phase: u8,
 }
 
@@ -579,10 +657,12 @@ fn configure_rosc(config: RoscConfig) -> u32 {
     config.hz
 }
 
+/// ROSC clock frequency.
 pub fn rosc_freq() -> u32 {
     CLOCKS.rosc.load(Ordering::Relaxed)
 }
 
+/// XOSC clock frequency.
 pub fn xosc_freq() -> u32 {
     CLOCKS.xosc.load(Ordering::Relaxed)
 }
@@ -594,34 +674,42 @@ pub fn xosc_freq() -> u32 {
 //     CLOCKS.gpin1.load(Ordering::Relaxed)
 // }
 
+/// PLL SYS clock frequency.
 pub fn pll_sys_freq() -> u32 {
     CLOCKS.pll_sys.load(Ordering::Relaxed)
 }
 
+/// PLL USB clock frequency.
 pub fn pll_usb_freq() -> u32 {
     CLOCKS.pll_usb.load(Ordering::Relaxed)
 }
 
+/// SYS clock frequency.
 pub fn clk_sys_freq() -> u32 {
     CLOCKS.sys.load(Ordering::Relaxed)
 }
 
+/// REF clock frequency.
 pub fn clk_ref_freq() -> u32 {
     CLOCKS.reference.load(Ordering::Relaxed)
 }
 
+/// Peripheral clock frequency.
 pub fn clk_peri_freq() -> u32 {
     CLOCKS.peri.load(Ordering::Relaxed)
 }
 
+/// USB clock frequency.
 pub fn clk_usb_freq() -> u32 {
     CLOCKS.usb.load(Ordering::Relaxed)
 }
 
+/// ADC clock frequency.
 pub fn clk_adc_freq() -> u32 {
     CLOCKS.adc.load(Ordering::Relaxed)
 }
 
+/// RTC clock frequency.
 pub fn clk_rtc_freq() -> u16 {
     CLOCKS.rtc.load(Ordering::Relaxed)
 }
@@ -682,7 +770,9 @@ fn configure_pll(p: pac::pll::Pll, input_freq: u32, config: PllConfig) -> u32 {
     vco_freq / ((config.post_div1 * config.post_div2) as u32)
 }
 
+/// General purpose input clock pin.
 pub trait GpinPin: crate::gpio::Pin {
+    /// Pin number.
     const NR: usize;
 }
 
@@ -697,12 +787,14 @@ macro_rules! impl_gpinpin {
 impl_gpinpin!(PIN_20, 20, 0);
 impl_gpinpin!(PIN_22, 22, 1);
 
+/// General purpose clock input driver.
 pub struct Gpin<'d, T: Pin> {
     gpin: PeripheralRef<'d, AnyPin>,
     _phantom: PhantomData<T>,
 }
 
 impl<'d, T: Pin> Gpin<'d, T> {
+    /// Create new gpin driver.
     pub fn new<P: GpinPin>(gpin: impl Peripheral<P = P> + 'd) -> Gpin<'d, P> {
         into_ref!(gpin);
 
@@ -728,7 +820,9 @@ impl<'d, T: Pin> Drop for Gpin<'d, T> {
     }
 }
 
+/// General purpose clock output pin.
 pub trait GpoutPin: crate::gpio::Pin {
+    /// Pin number.
     fn number(&self) -> usize;
 }
 
@@ -747,26 +841,38 @@ impl_gpoutpin!(PIN_23, 1);
 impl_gpoutpin!(PIN_24, 2);
 impl_gpoutpin!(PIN_25, 3);
 
+/// Gpout clock source.
 #[repr(u8)]
 pub enum GpoutSrc {
+    /// Sys PLL.
     PllSys = ClkGpoutCtrlAuxsrc::CLKSRC_PLL_SYS as _,
     // Gpin0 = ClkGpoutCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkGpoutCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
+    /// USB PLL.
     PllUsb = ClkGpoutCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// ROSC.
     Rosc = ClkGpoutCtrlAuxsrc::ROSC_CLKSRC as _,
+    /// XOSC.
     Xosc = ClkGpoutCtrlAuxsrc::XOSC_CLKSRC as _,
+    /// SYS.
     Sys = ClkGpoutCtrlAuxsrc::CLK_SYS as _,
+    /// USB.
     Usb = ClkGpoutCtrlAuxsrc::CLK_USB as _,
+    /// ADC.
     Adc = ClkGpoutCtrlAuxsrc::CLK_ADC as _,
+    /// RTC.
     Rtc = ClkGpoutCtrlAuxsrc::CLK_RTC as _,
+    /// REF.
     Ref = ClkGpoutCtrlAuxsrc::CLK_REF as _,
 }
 
+/// General purpose clock output driver.
 pub struct Gpout<'d, T: GpoutPin> {
     gpout: PeripheralRef<'d, T>,
 }
 
 impl<'d, T: GpoutPin> Gpout<'d, T> {
+    /// Create new general purpose cloud output.
     pub fn new(gpout: impl Peripheral<P = T> + 'd) -> Self {
         into_ref!(gpout);
 
@@ -775,6 +881,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         Self { gpout }
     }
 
+    /// Set clock divider.
     pub fn set_div(&self, int: u32, frac: u8) {
         let c = pac::CLOCKS;
         c.clk_gpout_div(self.gpout.number()).write(|w| {
@@ -783,6 +890,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Set clock source.
     pub fn set_src(&self, src: GpoutSrc) {
         let c = pac::CLOCKS;
         c.clk_gpout_ctrl(self.gpout.number()).modify(|w| {
@@ -790,6 +898,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Enable clock.
     pub fn enable(&self) {
         let c = pac::CLOCKS;
         c.clk_gpout_ctrl(self.gpout.number()).modify(|w| {
@@ -797,6 +906,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Disable clock.
     pub fn disable(&self) {
         let c = pac::CLOCKS;
         c.clk_gpout_ctrl(self.gpout.number()).modify(|w| {
@@ -804,6 +914,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Clock frequency.
     pub fn get_freq(&self) -> u32 {
         let c = pac::CLOCKS;
         let src = c.clk_gpout_ctrl(self.gpout.number()).read().auxsrc();

embassy-rp/src/dma.rs

@@ -38,6 +38,9 @@ pub(crate) unsafe fn init() {
     interrupt::DMA_IRQ_0.enable();
 }
 
+/// DMA read.
+///
+/// SAFETY: Slice must point to a valid location reachable by DMA.
 pub unsafe fn read<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     from: *const W,
@@ -57,6 +60,9 @@ pub unsafe fn read<'a, C: Channel, W: Word>(
     )
 }
 
+/// DMA write.
+///
+/// SAFETY: Slice must point to a valid location reachable by DMA.
 pub unsafe fn write<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     from: *const [W],
@@ -79,6 +85,9 @@ pub unsafe fn write<'a, C: Channel, W: Word>(
 // static mut so that this is allocated in RAM.
 static mut DUMMY: u32 = 0;
 
+/// DMA repeated write.
+///
+/// SAFETY: Slice must point to a valid location reachable by DMA.
 pub unsafe fn write_repeated<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     to: *mut W,
@@ -97,6 +106,9 @@ pub unsafe fn write_repeated<'a, C: Channel, W: Word>(
     )
 }
 
+/// DMA copy between slices.
+///
+/// SAFETY: Slices must point to locations reachable by DMA.
 pub unsafe fn copy<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     from: &[W],
@@ -152,6 +164,7 @@ fn copy_inner<'a, C: Channel>(
     Transfer::new(ch)
 }
 
+/// DMA transfer driver.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
     channel: PeripheralRef<'a, C>,
@@ -201,19 +214,25 @@ mod sealed {
     pub trait Word {}
 }
 
+/// DMA channel interface.
 pub trait Channel: Peripheral<P = Self> + sealed::Channel + Into<AnyChannel> + Sized + 'static {
+    /// Channel number.
     fn number(&self) -> u8;
 
+    /// Channel registry block.
     fn regs(&self) -> pac::dma::Channel {
         pac::DMA.ch(self.number() as _)
     }
 
+    /// Convert into type-erased [AnyChannel].
     fn degrade(self) -> AnyChannel {
         AnyChannel { number: self.number() }
     }
 }
 
+/// DMA word.
 pub trait Word: sealed::Word {
+    /// Word size.
     fn size() -> vals::DataSize;
 }
 
@@ -238,6 +257,7 @@ impl Word for u32 {
     }
 }
 
+/// Type erased DMA channel.
 pub struct AnyChannel {
     number: u8,
 }

embassy-rp/src/flash.rs

@@ -1,3 +1,4 @@
+//! Flash driver.
 use core::future::Future;
 use core::marker::PhantomData;
 use core::pin::Pin;
@@ -13,9 +14,10 @@ use crate::dma::{AnyChannel, Channel, Transfer};
 use crate::pac;
 use crate::peripherals::FLASH;
 
+/// Flash base address.
 pub const FLASH_BASE: *const u32 = 0x10000000 as _;
 
-// If running from RAM, we might have no boot2. Use bootrom `flash_enter_cmd_xip` instead.
+/// If running from RAM, we might have no boot2. Use bootrom `flash_enter_cmd_xip` instead.
 // TODO: when run-from-ram is set, completely skip the "pause cores and jumpp to RAM" dance.
 pub const USE_BOOT2: bool = !cfg!(feature = "run-from-ram");
 
@@ -24,10 +26,15 @@ pub const USE_BOOT2: bool = !cfg!(feature = "run-from-ram");
 // These limitations are currently enforced because of using the
 // RP2040 boot-rom flash functions, that are optimized for flash compatibility
 // rather than performance.
+/// Flash page size.
 pub const PAGE_SIZE: usize = 256;
+/// Flash write size.
 pub const WRITE_SIZE: usize = 1;
+/// Flash read size.
 pub const READ_SIZE: usize = 1;
+/// Flash erase size.
 pub const ERASE_SIZE: usize = 4096;
+/// Flash DMA read size.
 pub const ASYNC_READ_SIZE: usize = 4;
 
 /// Error type for NVMC operations.
@@ -38,7 +45,9 @@ pub enum Error {
     OutOfBounds,
     /// Unaligned operation or using unaligned buffers.
     Unaligned,
+    /// Accessed from the wrong core.
     InvalidCore,
+    /// Other error
     Other,
 }
 
@@ -96,12 +105,18 @@ impl<'a, 'd, T: Instance, const FLASH_SIZE: usize> Drop for BackgroundRead<'a, '
     }
 }
 
+/// Flash driver.
 pub struct Flash<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> {
     dma: Option<PeripheralRef<'d, AnyChannel>>,
     phantom: PhantomData<(&'d mut T, M)>,
 }
 
 impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SIZE> {
+    /// Blocking read.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn blocking_read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
         trace!(
             "Reading from 0x{:x} to 0x{:x}",
@@ -116,10 +131,14 @@ impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SI
         Ok(())
     }
 
+    /// Flash capacity.
     pub fn capacity(&self) -> usize {
         FLASH_SIZE
     }
 
+    /// Blocking erase.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn blocking_erase(&mut self, from: u32, to: u32) -> Result<(), Error> {
         check_erase(self, from, to)?;
 
@@ -136,6 +155,11 @@ impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SI
         Ok(())
     }
 
+    /// Blocking write.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn blocking_write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Error> {
         check_write(self, offset, bytes.len())?;
 
@@ -219,6 +243,7 @@ impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SI
 }
 
 impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Blocking, FLASH_SIZE> {
+    /// Create a new flash driver in blocking mode.
     pub fn new_blocking(_flash: impl Peripheral<P = T> + 'd) -> Self {
         Self {
             dma: None,
@@ -228,6 +253,7 @@ impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Blocking, FLASH_SIZE
 }
 
 impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Async, FLASH_SIZE> {
+    /// Create a new flash driver in async mode.
     pub fn new(_flash: impl Peripheral<P = T> + 'd, dma: impl Peripheral<P = impl Channel> + 'd) -> Self {
         into_ref!(dma);
         Self {
@@ -236,6 +262,11 @@ impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Async, FLASH_SIZE> {
         }
     }
 
+    /// Start a background read operation.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn background_read<'a>(
         &'a mut self,
         offset: u32,
@@ -279,6 +310,11 @@ impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Async, FLASH_SIZE> {
         })
     }
 
+    /// Async read.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub async fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
         use core::mem::MaybeUninit;
 
@@ -874,7 +910,9 @@ mod sealed {
     pub trait Mode {}
 }
 
+/// Flash instance.
 pub trait Instance: sealed::Instance {}
+/// Flash mode.
 pub trait Mode: sealed::Mode {}
 
 impl sealed::Instance for FLASH {}
@@ -887,7 +925,9 @@ macro_rules! impl_mode {
     };
 }
 
+/// Flash blocking mode.
 pub struct Blocking;
+/// Flash async mode.
 pub struct Async;
 
 impl_mode!(Blocking);

embassy-rp/src/gpio.rs

@@ -1,3 +1,4 @@
+//! GPIO driver.
 #![macro_use]
 use core::convert::Infallible;
 use core::future::Future;
@@ -23,7 +24,9 @@ static QSPI_WAKERS: [AtomicWaker; QSPI_PIN_COUNT] = [NEW_AW; QSPI_PIN_COUNT];
 /// Represents a digital input or output level.
 #[derive(Debug, Eq, PartialEq, Clone, Copy)]
 pub enum Level {
+    /// Logical low.
     Low,
+    /// Logical high.
     High,
 }
 
@@ -48,48 +51,66 @@ impl From<Level> for bool {
 /// Represents a pull setting for an input.
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum Pull {
+    /// No pull.
     None,
+    /// Internal pull-up resistor.
     Up,
+    /// Internal pull-down resistor.
     Down,
 }
 
 /// Drive strength of an output
 #[derive(Debug, Eq, PartialEq)]
 pub enum Drive {
+    /// 2 mA drive.
     _2mA,
+    /// 4 mA drive.
     _4mA,
+    /// 8 mA drive.
     _8mA,
+    /// 1 2mA drive.
     _12mA,
 }
 /// Slew rate of an output
 #[derive(Debug, Eq, PartialEq)]
 pub enum SlewRate {
+    /// Fast slew rate.
     Fast,
+    /// Slow slew rate.
     Slow,
 }
 
 /// A GPIO bank with up to 32 pins.
 #[derive(Debug, Eq, PartialEq)]
 pub enum Bank {
+    /// Bank 0.
     Bank0 = 0,
+    /// QSPI.
     #[cfg(feature = "qspi-as-gpio")]
     Qspi = 1,
 }
 
+/// Dormant mode config.
 #[derive(Debug, Eq, PartialEq, Copy, Clone, Default)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct DormantWakeConfig {
+    /// Wake on edge high.
     pub edge_high: bool,
+    /// Wake on edge low.
     pub edge_low: bool,
+    /// Wake on level high.
     pub level_high: bool,
+    /// Wake on level low.
     pub level_low: bool,
 }
 
+/// GPIO input driver.
 pub struct Input<'d, T: Pin> {
     pin: Flex<'d, T>,
 }
 
 impl<'d, T: Pin> Input<'d, T> {
+    /// Create GPIO input driver for a [Pin] with the provided [Pull] configuration.
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, pull: Pull) -> Self {
         let mut pin = Flex::new(pin);
@@ -104,47 +125,55 @@ impl<'d, T: Pin> Input<'d, T> {
         self.pin.set_schmitt(enable)
     }
 
+    /// Get whether the pin input level is high.
     #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
         self.pin.is_high()
     }
 
+    /// Get whether the pin input level is low.
     #[inline]
-    pub fn is_low(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
         self.pin.is_low()
     }
 
     /// Returns current pin level
     #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
         self.pin.get_level()
     }
 
+    /// Wait until the pin is high. If it is already high, return immediately.
     #[inline]
     pub async fn wait_for_high(&mut self) {
         self.pin.wait_for_high().await;
     }
 
+    /// Wait until the pin is low. If it is already low, return immediately.
     #[inline]
     pub async fn wait_for_low(&mut self) {
         self.pin.wait_for_low().await;
     }
 
+    /// Wait for the pin to undergo a transition from low to high.
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         self.pin.wait_for_rising_edge().await;
     }
 
+    /// Wait for the pin to undergo a transition from high to low.
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         self.pin.wait_for_falling_edge().await;
     }
 
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         self.pin.wait_for_any_edge().await;
     }
 
+    /// Configure dormant wake.
     #[inline]
     pub fn dormant_wake(&mut self, cfg: DormantWakeConfig) -> DormantWake<T> {
         self.pin.dormant_wake(cfg)
@@ -155,10 +184,15 @@ impl<'d, T: Pin> Input<'d, T> {
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum InterruptTrigger {
+    /// Trigger on pin low.
     LevelLow,
+    /// Trigger on pin high.
     LevelHigh,
+    /// Trigger on high to low transition.
     EdgeLow,
+    /// Trigger on low to high transition.
     EdgeHigh,
+    /// Trigger on any transition.
     AnyEdge,
 }
 
@@ -226,6 +260,7 @@ struct InputFuture<'a, T: Pin> {
 }
 
 impl<'d, T: Pin> InputFuture<'d, T> {
+    /// Create a new future wiating for input trigger.
     pub fn new(pin: impl Peripheral<P = T> + 'd, level: InterruptTrigger) -> Self {
         into_ref!(pin);
         let pin_group = (pin.pin() % 8) as usize;
@@ -308,11 +343,13 @@ impl<'d, T: Pin> Future for InputFuture<'d, T> {
     }
 }
 
+/// GPIO output driver.
 pub struct Output<'d, T: Pin> {
     pin: Flex<'d, T>,
 }
 
 impl<'d, T: Pin> Output<'d, T> {
+    /// Create GPIO output driver for a [Pin] with the provided [Level].
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level) -> Self {
         let mut pin = Flex::new(pin);
@@ -331,7 +368,7 @@ impl<'d, T: Pin> Output<'d, T> {
         self.pin.set_drive_strength(strength)
     }
 
-    // Set the pin's slew rate.
+    /// Set the pin's slew rate.
     #[inline]
     pub fn set_slew_rate(&mut self, slew_rate: SlewRate) {
         self.pin.set_slew_rate(slew_rate)
@@ -357,19 +394,19 @@ impl<'d, T: Pin> Output<'d, T> {
 
     /// Is the output pin set as high?
     #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
         self.pin.is_set_high()
     }
 
     /// Is the output pin set as low?
     #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
         self.pin.is_set_low()
     }
 
     /// What level output is set to
     #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
         self.pin.get_output_level()
     }
 
@@ -386,6 +423,7 @@ pub struct OutputOpenDrain<'d, T: Pin> {
 }
 
 impl<'d, T: Pin> OutputOpenDrain<'d, T> {
+    /// Create GPIO output driver for a [Pin] in open drain mode with the provided [Level].
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level) -> Self {
         let mut pin = Flex::new(pin);
@@ -403,7 +441,7 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
         self.pin.set_drive_strength(strength)
     }
 
-    // Set the pin's slew rate.
+    /// Set the pin's slew rate.
     #[inline]
     pub fn set_slew_rate(&mut self, slew_rate: SlewRate) {
         self.pin.set_slew_rate(slew_rate)
@@ -434,19 +472,19 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
 
     /// Is the output level high?
     #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
         !self.is_set_low()
     }
 
     /// Is the output level low?
     #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
         self.pin.is_set_as_output()
     }
 
     /// What level output is set to
     #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
         self.is_set_high().into()
     }
 
@@ -456,42 +494,49 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
         self.pin.toggle_set_as_output()
     }
 
+    /// Get whether the pin input level is high.
     #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
         self.pin.is_high()
     }
 
+    /// Get whether the pin input level is low.
     #[inline]
-    pub fn is_low(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
         self.pin.is_low()
     }
 
     /// Returns current pin level
     #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
         self.is_high().into()
     }
 
+    /// Wait until the pin is high. If it is already high, return immediately.
     #[inline]
     pub async fn wait_for_high(&mut self) {
         self.pin.wait_for_high().await;
     }
 
+    /// Wait until the pin is low. If it is already low, return immediately.
     #[inline]
     pub async fn wait_for_low(&mut self) {
         self.pin.wait_for_low().await;
     }
 
+    /// Wait for the pin to undergo a transition from low to high.
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         self.pin.wait_for_rising_edge().await;
     }
 
+    /// Wait for the pin to undergo a transition from high to low.
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         self.pin.wait_for_falling_edge().await;
     }
 
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         self.pin.wait_for_any_edge().await;
@@ -508,6 +553,10 @@ pub struct Flex<'d, T: Pin> {
 }
 
 impl<'d, T: Pin> Flex<'d, T> {
+    /// Wrap the pin in a `Flex`.
+    ///
+    /// The pin remains disconnected. The initial output level is unspecified, but can be changed
+    /// before the pin is put into output mode.
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd) -> Self {
         into_ref!(pin);
@@ -556,7 +605,7 @@ impl<'d, T: Pin> Flex<'d, T> {
         });
     }
 
-    // Set the pin's slew rate.
+    /// Set the pin's slew rate.
     #[inline]
     pub fn set_slew_rate(&mut self, slew_rate: SlewRate) {
         self.pin.pad_ctrl().modify(|w| {
@@ -589,29 +638,43 @@ impl<'d, T: Pin> Flex<'d, T> {
         self.pin.sio_oe().value_set().write_value(self.bit())
     }
 
+    /// Set as output pin.
     #[inline]
-    fn is_set_as_output(&self) -> bool {
+    pub fn is_set_as_output(&mut self) -> bool {
+        self.ref_is_set_as_output()
+    }
+
+    #[inline]
+    pub(crate) fn ref_is_set_as_output(&self) -> bool {
         (self.pin.sio_oe().value().read() & self.bit()) != 0
     }
 
+    /// Toggle output pin.
     #[inline]
     pub fn toggle_set_as_output(&mut self) {
         self.pin.sio_oe().value_xor().write_value(self.bit())
     }
 
+    /// Get whether the pin input level is high.
     #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
         !self.is_low()
     }
+    /// Get whether the pin input level is low.
+
+    #[inline]
+    pub fn is_low(&mut self) -> bool {
+        self.ref_is_low()
+    }
 
     #[inline]
-    pub fn is_low(&self) -> bool {
+    pub(crate) fn ref_is_low(&self) -> bool {
         self.pin.sio_in().read() & self.bit() == 0
     }
 
     /// Returns current pin level
     #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
         self.is_high().into()
     }
 
@@ -638,19 +701,24 @@ impl<'d, T: Pin> Flex<'d, T> {
 
     /// Is the output level high?
     #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
         !self.is_set_low()
     }
 
     /// Is the output level low?
     #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
+        self.ref_is_set_low()
+    }
+
+    #[inline]
+    pub(crate) fn ref_is_set_low(&self) -> bool {
         (self.pin.sio_out().value().read() & self.bit()) == 0
     }
 
     /// What level output is set to
     #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
         self.is_set_high().into()
     }
 
@@ -660,31 +728,37 @@ impl<'d, T: Pin> Flex<'d, T> {
         self.pin.sio_out().value_xor().write_value(self.bit())
     }
 
+    /// Wait until the pin is high. If it is already high, return immediately.
     #[inline]
     pub async fn wait_for_high(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::LevelHigh).await;
     }
 
+    /// Wait until the pin is low. If it is already low, return immediately.
     #[inline]
     pub async fn wait_for_low(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::LevelLow).await;
     }
 
+    /// Wait for the pin to undergo a transition from low to high.
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::EdgeHigh).await;
     }
 
+    /// Wait for the pin to undergo a transition from high to low.
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::EdgeLow).await;
     }
 
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::AnyEdge).await;
     }
 
+    /// Configure dormant wake.
     #[inline]
     pub fn dormant_wake(&mut self, cfg: DormantWakeConfig) -> DormantWake<T> {
         let idx = self.pin._pin() as usize;
@@ -722,6 +796,7 @@ impl<'d, T: Pin> Drop for Flex<'d, T> {
     }
 }
 
+/// Dormant wake driver.
 pub struct DormantWake<'w, T: Pin> {
     pin: PeripheralRef<'w, T>,
     cfg: DormantWakeConfig,
@@ -803,6 +878,7 @@ pub(crate) mod sealed {
     }
 }
 
+/// Interface for a Pin that can be configured by an [Input] or [Output] driver, or converted to an [AnyPin].
 pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'static {
     /// Degrade to a generic pin struct
     fn degrade(self) -> AnyPin {
@@ -824,6 +900,7 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
     }
 }
 
+/// Type-erased GPIO pin
 pub struct AnyPin {
     pin_bank: u8,
 }
@@ -912,11 +989,11 @@ mod eh02 {
         type Error = Infallible;
 
         fn is_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_high())
+            Ok(!self.pin.ref_is_low())
         }
 
         fn is_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_low())
+            Ok(self.pin.ref_is_low())
         }
     }
 
@@ -934,11 +1011,11 @@ mod eh02 {
 
     impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for Output<'d, T> {
         fn is_set_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_high())
+            Ok(!self.pin.ref_is_set_low())
         }
 
         fn is_set_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_low())
+            Ok(self.pin.ref_is_set_low())
         }
     }
 
@@ -954,11 +1031,11 @@ mod eh02 {
         type Error = Infallible;
 
         fn is_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_high())
+            Ok(!self.pin.ref_is_low())
         }
 
         fn is_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_low())
+            Ok(self.pin.ref_is_low())
         }
     }
 
@@ -978,11 +1055,11 @@ mod eh02 {
 
     impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for OutputOpenDrain<'d, T> {
         fn is_set_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_high())
+            Ok(!self.pin.ref_is_set_as_output())
         }
 
         fn is_set_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_low())
+            Ok(self.pin.ref_is_set_as_output())
         }
     }
 
@@ -998,11 +1075,11 @@ mod eh02 {
         type Error = Infallible;
 
         fn is_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_high())
+            Ok(!self.ref_is_low())
         }
 
         fn is_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_low())
+            Ok(self.ref_is_low())
         }
     }
 
@@ -1020,11 +1097,11 @@ mod eh02 {
 
     impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for Flex<'d, T> {
         fn is_set_high(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_high())
+            Ok(!self.ref_is_set_low())
         }
 
         fn is_set_low(&self) -> Result<bool, Self::Error> {
-            Ok(self.is_set_low())
+            Ok(self.ref_is_set_low())
         }
     }
 
@@ -1042,11 +1119,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for Input<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for Input<'d, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_high())
     }
 
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_low())
     }
 }
@@ -1066,11 +1143,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for Output<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for Output<'d, T> {
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_high())
     }
 
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_low())
     }
 }
@@ -1096,11 +1173,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for OutputOpenDrain<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for OutputOpenDrain<'d, T> {
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_high())
     }
 
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_low())
     }
 }
@@ -1112,11 +1189,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::ToggleableOutputPin for OutputOpenDrai
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for OutputOpenDrain<'d, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_high())
     }
 
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_low())
     }
 }
@@ -1126,11 +1203,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for Flex<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for Flex<'d, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_high())
     }
 
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_low())
     }
 }
@@ -1146,11 +1223,11 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for Flex<'d, T> {
 }
 
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for Flex<'d, T> {
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_high())
     }
 
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
         Ok(self.is_set_low())
     }
 }