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_stable.sh
+./ci-nightly.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

@@ -8,9 +8,6 @@ export RUSTUP_HOME=/ci/cache/rustup
 export CARGO_HOME=/ci/cache/cargo
 export CARGO_TARGET_DIR=/ci/cache/target
 
-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
-
 cargo test --manifest-path ./embassy-sync/Cargo.toml 
 cargo test --manifest-path ./embassy-embedded-hal/Cargo.toml 
 cargo test --manifest-path ./embassy-hal-internal/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 --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 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-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 arch-cortex-m \
+    --- 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 arch-cortex-m,executor-thread \
+    --- 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 arch-cortex-m,executor-interrupt \
+    --- 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 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,integrated-timers \
+    --- 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 arch-riscv32,integrated-timers \
+    --- 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 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_util, Peripheral, PeripheralRef};
+use embassy_rp::pio::{instr, Common, Config, Direction, Instance, Irq, PioPin, ShiftDirection, StateMachine};
+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);
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::set_x(&mut self.sm, write_bits as u32);
+            instr::set_y(&mut self.sm, read_bits as u32);
+            instr::set_pindir(&mut self.sm, 0b1);
+            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);
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::set_y(&mut self.sm, read_bits as u32);
+            instr::set_x(&mut self.sm, write_bits as u32);
+            instr::set_pindir(&mut self.sm, 0b1);
+            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/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.4.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/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?
 

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 }
-signature = { version = "1.6.4", default-features = false }
+salty = { version = "0.3", optional = true }
+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"] }
-
-[dev-dependencies.ed25519-dalek]
-default_features = false
-features = ["rand", "std", "u32_backend"]
+ed25519-dalek = { version = "2", default_features = false, features = ["std", "rand_core", "digest"]  }
 
 [features]
 ed25519-dalek = ["dep:ed25519-dalek", "_verify"]

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)]
@@ -371,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)
         }

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],
-        _signature: &[u8],
+        _public_key: &[u8; 32],
+        _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 signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
+            let public_key = VerifyingKey::from_bytes(_public_key).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 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 public_key = PublicKey::try_from(_public_key).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],
-        _signature: &[u8],
+        _public_key: &[u8; 32],
+        _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 signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
+            let public_key = VerifyingKey::from_bytes(_public_key).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 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 public_key = PublicKey::try_from(_public_key).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: PublicKey = keypair.public;
+        let public_key = keypair.verifying_key();
 
         // 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");
-        Self
+        let state = boot.prepare_boot(aligned_buf.as_mut()).expect("Boot prepare error");
+        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-async = { 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.3" }
 embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
 nb = "1.0.0"

embassy-executor/Cargo.toml

@@ -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,7 +25,7 @@ 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 }

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"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+repository = "https://github.com/embassy-rs/embassy"
 
 [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-async = { version = "=1.0.0-rc.2" }
-embedded-hal-bus = { version = "=0.1.0-rc.2", features = ["async"] }
+embedded-hal-1 = { package = "embedded-hal", version = "=1.0.0-rc.3" }
+embedded-hal-async = { version = "=1.0.0-rc.3" }
+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 regs::{Config0, Config2, SpiRegisters as sr, Status0, Status1};
+pub use phy::Phy10BaseT1x;
+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-async = { version = "=1.0.0-rc.2" }
+embedded-hal = { version = "1.0.0-rc.3" }
+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-async = { version = "=1.0.0-rc.2" }
+embedded-hal = { version = "1.0.0-rc.3" }
+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 = { version = "0.1", path = "/home/dirbaio/noproto", default-features = false, features = ["derive"] }
+noproto = "0.1.0"
 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-async = { version = "=1.0.0-rc.2" }
+embedded-hal = { version = "1.0.0-rc.3" }
+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-async = { 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.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

@@ -354,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-async = { version = "=1.0.0-rc.2" }
-embedded-hal-nb = { 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.3" }
+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.4.0", 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())
     }
 }

embassy-rp/src/i2c.rs

@@ -1,3 +1,4 @@
+//! I2C driver.
 use core::future;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -22,6 +23,7 @@ pub enum AbortReason {
     ArbitrationLoss,
     /// Transmit ended with data still in fifo
     TxNotEmpty(u16),
+    /// Other reason.
     Other(u32),
 }
 
@@ -41,9 +43,11 @@ pub enum Error {
     AddressReserved(u16),
 }
 
+/// I2C config.
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
+    /// Frequency.
     pub frequency: u32,
 }
 
@@ -53,13 +57,16 @@ impl Default for Config {
     }
 }
 
+/// Size of I2C FIFO.
 pub const FIFO_SIZE: u8 = 16;
 
+/// I2C driver.
 pub struct I2c<'d, T: Instance, M: Mode> {
     phantom: PhantomData<(&'d mut T, M)>,
 }
 
 impl<'d, T: Instance> I2c<'d, T, Blocking> {
+    /// Create a new driver instance in blocking mode.
     pub fn new_blocking(
         peri: impl Peripheral<P = T> + 'd,
         scl: impl Peripheral<P = impl SclPin<T>> + 'd,
@@ -72,6 +79,7 @@ impl<'d, T: Instance> I2c<'d, T, Blocking> {
 }
 
 impl<'d, T: Instance> I2c<'d, T, Async> {
+    /// Create a new driver instance in async mode.
     pub fn new_async(
         peri: impl Peripheral<P = T> + 'd,
         scl: impl Peripheral<P = impl SclPin<T>> + 'd,
@@ -292,16 +300,19 @@ impl<'d, T: Instance> I2c<'d, T, Async> {
         }
     }
 
+    /// Read from address into buffer using DMA.
     pub async fn read_async(&mut self, addr: u16, buffer: &mut [u8]) -> Result<(), Error> {
         Self::setup(addr)?;
         self.read_async_internal(buffer, true, true).await
     }
 
+    /// Write to address from buffer using DMA.
     pub async fn write_async(&mut self, addr: u16, bytes: impl IntoIterator<Item = u8>) -> Result<(), Error> {
         Self::setup(addr)?;
         self.write_async_internal(bytes, true).await
     }
 
+    /// Write to address from bytes and read from address into buffer using DMA.
     pub async fn write_read_async(
         &mut self,
         addr: u16,
@@ -314,6 +325,7 @@ impl<'d, T: Instance> I2c<'d, T, Async> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -569,17 +581,20 @@ impl<'d, T: Instance + 'd, M: Mode> I2c<'d, T, M> {
     // Blocking public API
     // =========================
 
+    /// Read from address into buffer blocking caller until done.
     pub fn blocking_read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Error> {
         Self::setup(address.into())?;
         self.read_blocking_internal(read, true, true)
         // Automatic Stop
     }
 
+    /// Write to address from buffer blocking caller until done.
     pub fn blocking_write(&mut self, address: u8, write: &[u8]) -> Result<(), Error> {
         Self::setup(address.into())?;
         self.write_blocking_internal(write, true)
     }
 
+    /// Write to address from bytes and read from address into buffer blocking caller until done.
     pub fn blocking_write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
         Self::setup(address.into())?;
         self.write_blocking_internal(write, false)?;
@@ -742,6 +757,7 @@ where
     }
 }
 
+/// Check if address is reserved.
 pub fn i2c_reserved_addr(addr: u16) -> bool {
     ((addr & 0x78) == 0 || (addr & 0x78) == 0x78) && addr != 0
 }
@@ -768,6 +784,7 @@ mod sealed {
     pub trait SclPin<T: Instance> {}
 }
 
+/// Driver mode.
 pub trait Mode: sealed::Mode {}
 
 macro_rules! impl_mode {
@@ -777,12 +794,15 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);
 impl_mode!(Async);
 
+/// I2C instance.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -819,7 +839,9 @@ macro_rules! impl_instance {
 impl_instance!(I2C0, I2C0_IRQ, set_i2c0, 32, 33);
 impl_instance!(I2C1, I2C1_IRQ, set_i2c1, 34, 35);
 
+/// SDA pin.
 pub trait SdaPin<T: Instance>: sealed::SdaPin<T> + crate::gpio::Pin {}
+/// SCL pin.
 pub trait SclPin<T: Instance>: sealed::SclPin<T> + crate::gpio::Pin {}
 
 macro_rules! impl_pin {

embassy-rp/src/i2c_slave.rs

@@ -1,3 +1,4 @@
+//! I2C slave driver.
 use core::future;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -63,11 +64,13 @@ impl Default for Config {
     }
 }
 
+/// I2CSlave driver.
 pub struct I2cSlave<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
 }
 
 impl<'d, T: Instance> I2cSlave<'d, T> {
+    /// Create a new instance.
     pub fn new(
         _peri: impl Peripheral<P = T> + 'd,
         scl: impl Peripheral<P = impl SclPin<T>> + 'd,

embassy-rp/src/lib.rs

@@ -1,5 +1,7 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
@@ -31,9 +33,7 @@ pub mod usb;
 pub mod watchdog;
 
 // PIO
-// TODO: move `pio_instr_util` and `relocate` to inside `pio`
 pub mod pio;
-pub mod pio_instr_util;
 pub(crate) mod relocate;
 
 // Reexports
@@ -247,7 +247,6 @@ select_bootloader! {
 /// # Usage
 ///
 /// ```no_run
-/// #![feature(type_alias_impl_trait)]
 /// use embassy_rp::install_core0_stack_guard;
 /// use embassy_executor::{Executor, Spawner};
 ///
@@ -302,11 +301,14 @@ fn install_stack_guard(stack_bottom: *mut usize) -> Result<(), ()> {
     Ok(())
 }
 
+/// HAL configuration for RP.
 pub mod config {
     use crate::clocks::ClockConfig;
 
+    /// HAL configuration passed when initializing.
     #[non_exhaustive]
     pub struct Config {
+        /// Clock configuration.
         pub clocks: ClockConfig,
     }
 
@@ -319,12 +321,18 @@ pub mod config {
     }
 
     impl Config {
+        /// Create a new configuration with the provided clock config.
         pub fn new(clocks: ClockConfig) -> Self {
             Self { clocks }
         }
     }
 }
 
+/// Initialize the `embassy-rp` 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-rp/src/multicore.rs

@@ -11,7 +11,6 @@
 //! # Usage
 //!
 //! ```no_run
-//! # #![feature(type_alias_impl_trait)]
 //! use embassy_rp::multicore::Stack;
 //! use static_cell::StaticCell;
 //! use embassy_executor::Executor;

embassy-rp/src/pio/instr.rs

@@ -1,7 +1,9 @@
+//! Instructions controlling the PIO.
 use pio::{InSource, InstructionOperands, JmpCondition, OutDestination, SetDestination};
 
 use crate::pio::{Instance, StateMachine};
 
+/// Set value of scratch register X.
 pub unsafe fn set_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, value: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::X,
@@ -12,6 +14,7 @@ pub unsafe fn set_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.exec_instr(OUT);
 }
 
+/// Get value of scratch register X.
 pub unsafe fn get_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>) -> u32 {
     const IN: u16 = InstructionOperands::IN {
         source: InSource::X,
@@ -22,6 +25,7 @@ pub unsafe fn get_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.rx().pull()
 }
 
+/// Set value of scratch register Y.
 pub unsafe fn set_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, value: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::Y,
@@ -32,6 +36,7 @@ pub unsafe fn set_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.exec_instr(OUT);
 }
 
+/// Get value of scratch register Y.
 pub unsafe fn get_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>) -> u32 {
     const IN: u16 = InstructionOperands::IN {
         source: InSource::Y,
@@ -43,6 +48,7 @@ pub unsafe fn get_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.rx().pull()
 }
 
+/// Set instruction for pindir destination.
 pub unsafe fn set_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u8) {
     let set: u16 = InstructionOperands::SET {
         destination: SetDestination::PINDIRS,
@@ -52,6 +58,7 @@ pub unsafe fn set_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachine<P
     sm.exec_instr(set);
 }
 
+/// Set instruction for pin destination.
 pub unsafe fn set_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u8) {
     let set: u16 = InstructionOperands::SET {
         destination: SetDestination::PINS,
@@ -61,6 +68,7 @@ pub unsafe fn set_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO,
     sm.exec_instr(set);
 }
 
+/// Out instruction for pin destination.
 pub unsafe fn set_out_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::PINS,
@@ -70,6 +78,8 @@ pub unsafe fn set_out_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<
     sm.tx().push(data);
     sm.exec_instr(OUT);
 }
+
+/// Out instruction for pindir destination.
 pub unsafe fn set_out_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::PINDIRS,
@@ -80,6 +90,7 @@ pub unsafe fn set_out_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachi
     sm.exec_instr(OUT);
 }
 
+/// Jump instruction to address.
 pub unsafe fn exec_jmp<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, to_addr: u8) {
     let jmp: u16 = InstructionOperands::JMP {
         address: to_addr,

embassy-rp/src/pio/mod.rs

@@ -1,3 +1,4 @@
+//! PIO driver.
 use core::future::Future;
 use core::marker::PhantomData;
 use core::pin::Pin as FuturePin;
@@ -19,8 +20,11 @@ use crate::gpio::{self, AnyPin, Drive, Level, Pull, SlewRate};
 use crate::interrupt::typelevel::{Binding, Handler, Interrupt};
 use crate::pac::dma::vals::TreqSel;
 use crate::relocate::RelocatedProgram;
-use crate::{pac, peripherals, pio_instr_util, RegExt};
+use crate::{pac, peripherals, RegExt};
 
+pub mod instr;
+
+/// Wakers for interrupts and FIFOs.
 pub struct Wakers([AtomicWaker; 12]);
 
 impl Wakers {
@@ -38,6 +42,7 @@ impl Wakers {
     }
 }
 
+/// FIFO config.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -51,6 +56,8 @@ pub enum FifoJoin {
     TxOnly,
 }
 
+/// Shift direction.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -60,6 +67,8 @@ pub enum ShiftDirection {
     Left = 0,
 }
 
+/// Pin direction.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -68,12 +77,15 @@ pub enum Direction {
     Out = 1,
 }
 
+/// Which fifo level to use in status check.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
 pub enum StatusSource {
     #[default]
+    /// All-ones if TX FIFO level < N, otherwise all-zeroes.
     TxFifoLevel = 0,
+    /// All-ones if RX FIFO level < N, otherwise all-zeroes.
     RxFifoLevel = 1,
 }
 
@@ -81,6 +93,7 @@ const RXNEMPTY_MASK: u32 = 1 << 0;
 const TXNFULL_MASK: u32 = 1 << 4;
 const SMIRQ_MASK: u32 = 1 << 8;
 
+/// Interrupt handler for PIO.
 pub struct InterruptHandler<PIO: Instance> {
     _pio: PhantomData<PIO>,
 }
@@ -105,6 +118,7 @@ pub struct FifoOutFuture<'a, 'd, PIO: Instance, const SM: usize> {
 }
 
 impl<'a, 'd, PIO: Instance, const SM: usize> FifoOutFuture<'a, 'd, PIO, SM> {
+    /// Create a new future waiting for TX-FIFO to become writable.
     pub fn new(sm: &'a mut StateMachineTx<'d, PIO, SM>, value: u32) -> Self {
         FifoOutFuture { sm_tx: sm, value }
     }
@@ -136,13 +150,14 @@ impl<'a, 'd, PIO: Instance, const SM: usize> Drop for FifoOutFuture<'a, 'd, PIO,
     }
 }
 
-/// Future that waits for RX-FIFO to become readable
+/// Future that waits for RX-FIFO to become readable.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct FifoInFuture<'a, 'd, PIO: Instance, const SM: usize> {
     sm_rx: &'a mut StateMachineRx<'d, PIO, SM>,
 }
 
 impl<'a, 'd, PIO: Instance, const SM: usize> FifoInFuture<'a, 'd, PIO, SM> {
+    /// Create future that waits for RX-FIFO to become readable.
     pub fn new(sm: &'a mut StateMachineRx<'d, PIO, SM>) -> Self {
         FifoInFuture { sm_rx: sm }
     }
@@ -207,6 +222,7 @@ impl<'a, 'd, PIO: Instance> Drop for IrqFuture<'a, 'd, PIO> {
     }
 }
 
+/// Type representing a PIO pin.
 pub struct Pin<'l, PIO: Instance> {
     pin: PeripheralRef<'l, AnyPin>,
     pio: PhantomData<PIO>,
@@ -226,7 +242,7 @@ impl<'l, PIO: Instance> Pin<'l, PIO> {
         });
     }
 
-    // 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| {
@@ -251,6 +267,7 @@ impl<'l, PIO: Instance> Pin<'l, PIO> {
         });
     }
 
+    /// Set the pin's input sync bypass.
     pub fn set_input_sync_bypass<'a>(&mut self, bypass: bool) {
         let mask = 1 << self.pin();
         if bypass {
@@ -260,28 +277,34 @@ impl<'l, PIO: Instance> Pin<'l, PIO> {
         }
     }
 
+    /// Get the underlying pin number.
     pub fn pin(&self) -> u8 {
         self.pin._pin()
     }
 }
 
+/// Type representing a state machine RX FIFO.
 pub struct StateMachineRx<'d, PIO: Instance, const SM: usize> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
+    /// Check if RX FIFO is empty.
     pub fn empty(&self) -> bool {
         PIO::PIO.fstat().read().rxempty() & (1u8 << SM) != 0
     }
 
+    /// Check if RX FIFO is full.
     pub fn full(&self) -> bool {
         PIO::PIO.fstat().read().rxfull() & (1u8 << SM) != 0
     }
 
+    /// Check RX FIFO level.
     pub fn level(&self) -> u8 {
         (PIO::PIO.flevel().read().0 >> (SM * 8 + 4)) as u8 & 0x0f
     }
 
+    /// Check if state machine has stalled on full RX FIFO.
     pub fn stalled(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().rxstall() & (1 << SM) != 0;
@@ -291,6 +314,7 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
         ret
     }
 
+    /// Check if RX FIFO underflow (i.e. read-on-empty by the system) has occurred.
     pub fn underflowed(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().rxunder() & (1 << SM) != 0;
@@ -300,10 +324,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
         ret
     }
 
+    /// Pull data from RX FIFO.
     pub fn pull(&mut self) -> u32 {
         PIO::PIO.rxf(SM).read()
     }
 
+    /// Attempt pulling data from RX FIFO.
     pub fn try_pull(&mut self) -> Option<u32> {
         if self.empty() {
             return None;
@@ -311,10 +337,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
         Some(self.pull())
     }
 
+    /// Wait for RX FIFO readable.
     pub fn wait_pull<'a>(&'a mut self) -> FifoInFuture<'a, 'd, PIO, SM> {
         FifoInFuture::new(self)
     }
 
+    /// Prepare DMA transfer from RX FIFO.
     pub fn dma_pull<'a, C: Channel, W: Word>(
         &'a mut self,
         ch: PeripheralRef<'a, C>,
@@ -340,22 +368,28 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
     }
 }
 
+/// Type representing a state machine TX FIFO.
 pub struct StateMachineTx<'d, PIO: Instance, const SM: usize> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
+    /// Check if TX FIFO is empty.
     pub fn empty(&self) -> bool {
         PIO::PIO.fstat().read().txempty() & (1u8 << SM) != 0
     }
+
+    /// Check if TX FIFO is full.
     pub fn full(&self) -> bool {
         PIO::PIO.fstat().read().txfull() & (1u8 << SM) != 0
     }
 
+    /// Check TX FIFO level.
     pub fn level(&self) -> u8 {
         (PIO::PIO.flevel().read().0 >> (SM * 8)) as u8 & 0x0f
     }
 
+    /// Check state machine has stalled on empty TX FIFO.
     pub fn stalled(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().txstall() & (1 << SM) != 0;
@@ -365,6 +399,7 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
         ret
     }
 
+    /// Check if FIFO overflowed.
     pub fn overflowed(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().txover() & (1 << SM) != 0;
@@ -374,10 +409,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
         ret
     }
 
+    /// Force push data to TX FIFO.
     pub fn push(&mut self, v: u32) {
         PIO::PIO.txf(SM).write_value(v);
     }
 
+    /// Attempt to push data to TX FIFO.
     pub fn try_push(&mut self, v: u32) -> bool {
         if self.full() {
             return false;
@@ -386,10 +423,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
         true
     }
 
+    /// Wait until FIFO is ready for writing.
     pub fn wait_push<'a>(&'a mut self, value: u32) -> FifoOutFuture<'a, 'd, PIO, SM> {
         FifoOutFuture::new(self, value)
     }
 
+    /// Prepare a DMA transfer to TX FIFO.
     pub fn dma_push<'a, C: Channel, W: Word>(&'a mut self, ch: PeripheralRef<'a, C>, data: &'a [W]) -> Transfer<'a, C> {
         let pio_no = PIO::PIO_NO;
         let p = ch.regs();
@@ -411,6 +450,7 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
     }
 }
 
+/// A type representing a single PIO state machine.
 pub struct StateMachine<'d, PIO: Instance, const SM: usize> {
     rx: StateMachineRx<'d, PIO, SM>,
     tx: StateMachineTx<'d, PIO, SM>,
@@ -430,52 +470,78 @@ fn assert_consecutive<'d, PIO: Instance>(pins: &[&Pin<'d, PIO>]) {
     }
 }
 
+/// PIO Execution config.
 #[derive(Clone, Copy, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub struct ExecConfig {
+    /// If true, the MSB of the Delay/Side-set instruction field is used as side-set enable, rather than a side-set data bit.
     pub side_en: bool,
+    /// If true, side-set data is asserted to pin directions, instead of pin values.
     pub side_pindir: bool,
+    /// Pin to trigger jump.
     pub jmp_pin: u8,
+    /// After reaching this address, execution is wrapped to wrap_bottom.
     pub wrap_top: u8,
+    /// After reaching wrap_top, execution is wrapped to this address.
     pub wrap_bottom: u8,
 }
 
+/// PIO shift register config for input or output.
 #[derive(Clone, Copy, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct ShiftConfig {
+    /// Number of bits shifted out of OSR before autopull.
     pub threshold: u8,
+    /// Shift direction.
     pub direction: ShiftDirection,
+    /// For output: Pull automatically output shift register is emptied.
+    /// For input: Push automatically when the input shift register is filled.
     pub auto_fill: bool,
 }
 
+/// PIO pin config.
 #[derive(Clone, Copy, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct PinConfig {
+    /// The number of MSBs of the Delay/Side-set instruction field which are used for side-set.
     pub sideset_count: u8,
+    /// The number of pins asserted by a SET. In the range 0 to 5 inclusive.
     pub set_count: u8,
+    /// The number of pins asserted by an OUT PINS, OUT PINDIRS or MOV PINS instruction. In the range 0 to 32 inclusive.
     pub out_count: u8,
+    /// The pin which is mapped to the least-significant bit of a state machine's IN data bus.
     pub in_base: u8,
+    /// The lowest-numbered pin that will be affected by a side-set operation.
     pub sideset_base: u8,
+    /// The lowest-numbered pin that will be affected by a SET PINS or SET PINDIRS instruction.
     pub set_base: u8,
+    /// The lowest-numbered pin that will be affected by an OUT PINS, OUT PINDIRS or MOV PINS instruction.
     pub out_base: u8,
 }
 
+/// PIO config.
 #[derive(Clone, Copy, Debug)]
 pub struct Config<'d, PIO: Instance> {
-    // CLKDIV
+    /// Clock divisor register for state machines.
     pub clock_divider: FixedU32<U8>,
-    // EXECCTRL
+    /// Which data bit to use for inline OUT enable.
     pub out_en_sel: u8,
+    /// Use a bit of OUT data as an auxiliary write enable When used in conjunction with OUT_STICKY.
     pub inline_out_en: bool,
+    /// Continuously assert the most recent OUT/SET to the pins.
     pub out_sticky: bool,
+    /// Which source to use for checking status.
     pub status_sel: StatusSource,
+    /// Status comparison level.
     pub status_n: u8,
     exec: ExecConfig,
     origin: Option<u8>,
-    // SHIFTCTRL
+    /// Configure FIFO allocation.
     pub fifo_join: FifoJoin,
+    /// Input shifting config.
     pub shift_in: ShiftConfig,
+    /// Output shifting config.
     pub shift_out: ShiftConfig,
     // PINCTRL
     pins: PinConfig,
@@ -505,16 +571,22 @@ impl<'d, PIO: Instance> Default for Config<'d, PIO> {
 }
 
 impl<'d, PIO: Instance> Config<'d, PIO> {
+    /// Get execution configuration.
     pub fn get_exec(&self) -> ExecConfig {
         self.exec
     }
+
+    /// Update execution configuration.
     pub unsafe fn set_exec(&mut self, e: ExecConfig) {
         self.exec = e;
     }
 
+    /// Get pin configuration.
     pub fn get_pins(&self) -> PinConfig {
         self.pins
     }
+
+    /// Update pin configuration.
     pub unsafe fn set_pins(&mut self, p: PinConfig) {
         self.pins = p;
     }
@@ -537,6 +609,7 @@ impl<'d, PIO: Instance> Config<'d, PIO> {
         self.origin = Some(prog.origin);
     }
 
+    /// Set pin used to signal jump.
     pub fn set_jmp_pin(&mut self, pin: &Pin<'d, PIO>) {
         self.exec.jmp_pin = pin.pin();
     }
@@ -571,6 +644,7 @@ impl<'d, PIO: Instance> Config<'d, PIO> {
 }
 
 impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
+    /// Set the config for a given PIO state machine.
     pub fn set_config(&mut self, config: &Config<'d, PIO>) {
         // sm expects 0 for 65536, truncation makes that happen
         assert!(config.clock_divider <= 65536, "clkdiv must be <= 65536");
@@ -617,7 +691,7 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
             w.set_out_base(config.pins.out_base);
         });
         if let Some(origin) = config.origin {
-            unsafe { pio_instr_util::exec_jmp(self, origin) }
+            unsafe { instr::exec_jmp(self, origin) }
         }
     }
 
@@ -626,10 +700,13 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         PIO::PIO.sm(SM)
     }
 
+    /// Restart this state machine.
     pub fn restart(&mut self) {
         let mask = 1u8 << SM;
         PIO::PIO.ctrl().write_set(|w| w.set_sm_restart(mask));
     }
+
+    /// Enable state machine.
     pub fn set_enable(&mut self, enable: bool) {
         let mask = 1u8 << SM;
         if enable {
@@ -639,10 +716,12 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         }
     }
 
+    /// Check if state machine is enabled.
     pub fn is_enabled(&self) -> bool {
         PIO::PIO.ctrl().read().sm_enable() & (1u8 << SM) != 0
     }
 
+    /// Restart a state machine's clock divider from an initial phase of 0.
     pub fn clkdiv_restart(&mut self) {
         let mask = 1u8 << SM;
         PIO::PIO.ctrl().write_set(|w| w.set_clkdiv_restart(mask));
@@ -690,6 +769,7 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         });
     }
 
+    /// Flush FIFOs for state machine.
     pub fn clear_fifos(&mut self) {
         // Toggle FJOIN_RX to flush FIFOs
         let shiftctrl = Self::this_sm().shiftctrl();
@@ -701,21 +781,31 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         });
     }
 
+    /// Instruct state machine to execute a given instructions
+    ///
+    /// SAFETY: The state machine must be in a state where executing
+    /// an arbitrary instruction does not crash it.
     pub unsafe fn exec_instr(&mut self, instr: u16) {
         Self::this_sm().instr().write(|w| w.set_instr(instr));
     }
 
+    /// Return a read handle for reading state machine outputs.
     pub fn rx(&mut self) -> &mut StateMachineRx<'d, PIO, SM> {
         &mut self.rx
     }
+
+    /// Return a handle for writing to inputs.
     pub fn tx(&mut self) -> &mut StateMachineTx<'d, PIO, SM> {
         &mut self.tx
     }
+
+    /// Return both read and write handles for the state machine.
     pub fn rx_tx(&mut self) -> (&mut StateMachineRx<'d, PIO, SM>, &mut StateMachineTx<'d, PIO, SM>) {
         (&mut self.rx, &mut self.tx)
     }
 }
 
+/// PIO handle.
 pub struct Common<'d, PIO: Instance> {
     instructions_used: u32,
     pio: PhantomData<&'d mut PIO>,
@@ -727,18 +817,25 @@ impl<'d, PIO: Instance> Drop for Common<'d, PIO> {
     }
 }
 
+/// Memory of PIO instance.
 pub struct InstanceMemory<'d, PIO: Instance> {
     used_mask: u32,
     pio: PhantomData<&'d mut PIO>,
 }
 
+/// A loaded PIO program.
 pub struct LoadedProgram<'d, PIO: Instance> {
+    /// Memory used by program.
     pub used_memory: InstanceMemory<'d, PIO>,
+    /// Program origin for loading.
     pub origin: u8,
+    /// Wrap controls what to do once program is done executing.
     pub wrap: Wrap,
+    /// Data for 'side' set instruction parameters.
     pub side_set: SideSet,
 }
 
+/// Errors loading a PIO program.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum LoadError {
@@ -834,6 +931,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
         self.instructions_used &= !instrs.used_mask;
     }
 
+    /// Bypass flipflop synchronizer on GPIO inputs.
     pub fn set_input_sync_bypass<'a>(&'a mut self, bypass: u32, mask: u32) {
         // this can interfere with per-pin bypass functions. splitting the
         // modification is going to be fine since nothing that relies on
@@ -842,6 +940,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
         PIO::PIO.input_sync_bypass().write_clear(|w| *w = mask & !bypass);
     }
 
+    /// Get bypass configuration.
     pub fn get_input_sync_bypass(&self) -> u32 {
         PIO::PIO.input_sync_bypass().read()
     }
@@ -861,6 +960,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
         }
     }
 
+    /// Apply changes to all state machines in a batch.
     pub fn apply_sm_batch(&mut self, f: impl FnOnce(&mut PioBatch<'d, PIO>)) {
         let mut batch = PioBatch {
             clkdiv_restart: 0,
@@ -878,6 +978,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
     }
 }
 
+/// Represents multiple state machines in a single type.
 pub struct PioBatch<'a, PIO: Instance> {
     clkdiv_restart: u8,
     sm_restart: u8,
@@ -887,25 +988,25 @@ pub struct PioBatch<'a, PIO: Instance> {
 }
 
 impl<'a, PIO: Instance> PioBatch<'a, PIO> {
-    pub fn restart_clockdiv<const SM: usize>(&mut self, _sm: &mut StateMachine<'a, PIO, SM>) {
-        self.clkdiv_restart |= 1 << SM;
-    }
-
+    /// Restart a state machine's clock divider from an initial phase of 0.
     pub fn restart<const SM: usize>(&mut self, _sm: &mut StateMachine<'a, PIO, SM>) {
         self.clkdiv_restart |= 1 << SM;
     }
 
+    /// Enable a specific state machine.
     pub fn set_enable<const SM: usize>(&mut self, _sm: &mut StateMachine<'a, PIO, SM>, enable: bool) {
         self.sm_enable_mask |= 1 << SM;
         self.sm_enable |= (enable as u8) << SM;
     }
 }
 
+/// Type representing a PIO interrupt.
 pub struct Irq<'d, PIO: Instance, const N: usize> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance, const N: usize> Irq<'d, PIO, N> {
+    /// Wait for an IRQ to fire.
     pub fn wait<'a>(&'a mut self) -> IrqFuture<'a, 'd, PIO> {
         IrqFuture {
             pio: PhantomData,
@@ -914,59 +1015,79 @@ impl<'d, PIO: Instance, const N: usize> Irq<'d, PIO, N> {
     }
 }
 
+/// Interrupt flags for a PIO instance.
 #[derive(Clone)]
 pub struct IrqFlags<'d, PIO: Instance> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance> IrqFlags<'d, PIO> {
+    /// Check if interrupt fired.
     pub fn check(&self, irq_no: u8) -> bool {
         assert!(irq_no < 8);
         self.check_any(1 << irq_no)
     }
 
+    /// Check if any of the interrupts in the bitmap fired.
     pub fn check_any(&self, irqs: u8) -> bool {
         PIO::PIO.irq().read().irq() & irqs != 0
     }
 
+    /// Check if all interrupts have fired.
     pub fn check_all(&self, irqs: u8) -> bool {
         PIO::PIO.irq().read().irq() & irqs == irqs
     }
 
+    /// Clear interrupt for interrupt number.
     pub fn clear(&self, irq_no: usize) {
         assert!(irq_no < 8);
         self.clear_all(1 << irq_no);
     }
 
+    /// Clear all interrupts set in the bitmap.
     pub fn clear_all(&self, irqs: u8) {
         PIO::PIO.irq().write(|w| w.set_irq(irqs))
     }
 
+    /// Fire a given interrupt.
     pub fn set(&self, irq_no: usize) {
         assert!(irq_no < 8);
         self.set_all(1 << irq_no);
     }
 
+    /// Fire all interrupts.
     pub fn set_all(&self, irqs: u8) {
         PIO::PIO.irq_force().write(|w| w.set_irq_force(irqs))
     }
 }
 
+/// An instance of the PIO driver.
 pub struct Pio<'d, PIO: Instance> {
+    /// PIO handle.
     pub common: Common<'d, PIO>,
+    /// PIO IRQ flags.
     pub irq_flags: IrqFlags<'d, PIO>,
+    /// IRQ0 configuration.
     pub irq0: Irq<'d, PIO, 0>,
+    /// IRQ1 configuration.
     pub irq1: Irq<'d, PIO, 1>,
+    /// IRQ2 configuration.
     pub irq2: Irq<'d, PIO, 2>,
+    /// IRQ3 configuration.
     pub irq3: Irq<'d, PIO, 3>,
+    /// State machine 0 handle.
     pub sm0: StateMachine<'d, PIO, 0>,
+    /// State machine 1 handle.
     pub sm1: StateMachine<'d, PIO, 1>,
+    /// State machine 2 handle.
     pub sm2: StateMachine<'d, PIO, 2>,
+    /// State machine 3 handle.
     pub sm3: StateMachine<'d, PIO, 3>,
     _pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance> Pio<'d, PIO> {
+    /// Create a new instance of a PIO peripheral.
     pub fn new(_pio: impl Peripheral<P = PIO> + 'd, _irq: impl Binding<PIO::Interrupt, InterruptHandler<PIO>>) -> Self {
         PIO::state().users.store(5, Ordering::Release);
         PIO::state().used_pins.store(0, Ordering::Release);
@@ -1003,9 +1124,10 @@ impl<'d, PIO: Instance> Pio<'d, PIO> {
     }
 }
 
-// we need to keep a record of which pins are assigned to each PIO. make_pio_pin
-// notionally takes ownership of the pin it is given, but the wrapped pin cannot
-// be treated as an owned resource since dropping it would have to deconfigure
+/// Representation of the PIO state keeping a record of which pins are assigned to
+/// each PIO.
+// make_pio_pin notionally takes ownership of the pin it is given, but the wrapped pin
+// cannot be treated as an owned resource since dropping it would have to deconfigure
 // the pin, breaking running state machines in the process. pins are also shared
 // between all state machines, which makes ownership even messier to track any
 // other way.
@@ -1059,6 +1181,7 @@ mod sealed {
     }
 }
 
+/// PIO instance.
 pub trait Instance: sealed::Instance + Sized + Unpin {}
 
 macro_rules! impl_pio {
@@ -1076,6 +1199,7 @@ macro_rules! impl_pio {
 impl_pio!(PIO0, 0, PIO0, PIO0_0, PIO0_IRQ_0);
 impl_pio!(PIO1, 1, PIO1, PIO1_0, PIO1_IRQ_0);
 
+/// PIO pin.
 pub trait PioPin: sealed::PioPin + gpio::Pin {}
 
 macro_rules! impl_pio_pin {

embassy-rp/src/pwm.rs

@@ -61,9 +61,13 @@ impl Default for Config {
     }
 }
 
+/// PWM input mode.
 pub enum InputMode {
+    /// Level mode.
     Level,
+    /// Rising edge mode.
     RisingEdge,
+    /// Falling edge mode.
     FallingEdge,
 }
 
@@ -77,6 +81,7 @@ impl From<InputMode> for Divmode {
     }
 }
 
+/// PWM driver.
 pub struct Pwm<'d, T: Channel> {
     inner: PeripheralRef<'d, T>,
     pin_a: Option<PeripheralRef<'d, AnyPin>>,
@@ -114,11 +119,13 @@ impl<'d, T: Channel> Pwm<'d, T> {
         }
     }
 
+    /// Create PWM driver without any configured pins.
     #[inline]
     pub fn new_free(inner: impl Peripheral<P = T> + 'd, config: Config) -> Self {
         Self::new_inner(inner, None, None, config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a single 'a' as output.
     #[inline]
     pub fn new_output_a(
         inner: impl Peripheral<P = T> + 'd,
@@ -129,6 +136,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, Some(a.map_into()), None, config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a single 'b' pin as output.
     #[inline]
     pub fn new_output_b(
         inner: impl Peripheral<P = T> + 'd,
@@ -139,6 +147,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, None, Some(b.map_into()), config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a 'a' and 'b' pins as output.
     #[inline]
     pub fn new_output_ab(
         inner: impl Peripheral<P = T> + 'd,
@@ -150,6 +159,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, Some(a.map_into()), Some(b.map_into()), config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a single 'b' as input pin.
     #[inline]
     pub fn new_input(
         inner: impl Peripheral<P = T> + 'd,
@@ -161,6 +171,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, None, Some(b.map_into()), config, mode.into())
     }
 
+    /// Create PWM driver with a 'a' and 'b' pins in the desired input mode.
     #[inline]
     pub fn new_output_input(
         inner: impl Peripheral<P = T> + 'd,
@@ -173,6 +184,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, Some(a.map_into()), Some(b.map_into()), config, mode.into())
     }
 
+    /// Set the PWM config.
     pub fn set_config(&mut self, config: &Config) {
         Self::configure(self.inner.regs(), config);
     }
@@ -216,28 +228,33 @@ impl<'d, T: Channel> Pwm<'d, T> {
         while p.csr().read().ph_ret() {}
     }
 
+    /// Read PWM counter.
     #[inline]
     pub fn counter(&self) -> u16 {
         self.inner.regs().ctr().read().ctr()
     }
 
+    /// Write PWM counter.
     #[inline]
     pub fn set_counter(&self, ctr: u16) {
         self.inner.regs().ctr().write(|w| w.set_ctr(ctr))
     }
 
+    /// Wait for channel interrupt.
     #[inline]
     pub fn wait_for_wrap(&mut self) {
         while !self.wrapped() {}
         self.clear_wrapped();
     }
 
+    /// Check if interrupt for channel is set.
     #[inline]
     pub fn wrapped(&mut self) -> bool {
         pac::PWM.intr().read().0 & self.bit() != 0
     }
 
     #[inline]
+    /// Clear interrupt flag.
     pub fn clear_wrapped(&mut self) {
         pac::PWM.intr().write_value(Intr(self.bit() as _));
     }
@@ -248,15 +265,18 @@ impl<'d, T: Channel> Pwm<'d, T> {
     }
 }
 
+/// Batch representation of PWM channels.
 pub struct PwmBatch(u32);
 
 impl PwmBatch {
     #[inline]
+    /// Enable a PWM channel in this batch.
     pub fn enable(&mut self, pwm: &Pwm<'_, impl Channel>) {
         self.0 |= pwm.bit();
     }
 
     #[inline]
+    /// Enable channels in this batch in a PWM.
     pub fn set_enabled(enabled: bool, batch: impl FnOnce(&mut PwmBatch)) {
         let mut en = PwmBatch(0);
         batch(&mut en);
@@ -284,9 +304,12 @@ mod sealed {
     pub trait Channel {}
 }
 
+/// PWM Channel.
 pub trait Channel: Peripheral<P = Self> + sealed::Channel + Sized + 'static {
+    /// Channel number.
     fn number(&self) -> u8;
 
+    /// Channel register block.
     fn regs(&self) -> pac::pwm::Channel {
         pac::PWM.ch(self.number() as _)
     }
@@ -312,7 +335,9 @@ channel!(PWM_CH5, 5);
 channel!(PWM_CH6, 6);
 channel!(PWM_CH7, 7);
 
+/// PWM Pin A.
 pub trait PwmPinA<T: Channel>: GpioPin {}
+/// PWM Pin B.
 pub trait PwmPinB<T: Channel>: GpioPin {}
 
 macro_rules! impl_pin {

embassy-rp/src/rtc/mod.rs

@@ -1,3 +1,4 @@
+//! RTC driver.
 mod filter;
 
 use embassy_hal_internal::{into_ref, Peripheral, PeripheralRef};
@@ -194,6 +195,7 @@ mod sealed {
     }
 }
 
+/// RTC peripheral instance.
 pub trait Instance: sealed::Instance {}
 
 impl sealed::Instance for crate::peripherals::RTC {

embassy-rp/src/spi.rs

@@ -11,6 +11,7 @@ use crate::gpio::sealed::Pin as _;
 use crate::gpio::{AnyPin, Pin as GpioPin};
 use crate::{pac, peripherals, Peripheral};
 
+/// SPI errors.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -18,11 +19,15 @@ pub enum Error {
     // No errors for now
 }
 
+/// SPI configuration.
 #[non_exhaustive]
 #[derive(Clone)]
 pub struct Config {
+    /// Frequency.
     pub frequency: u32,
+    /// Phase.
     pub phase: Phase,
+    /// Polarity.
     pub polarity: Polarity,
 }
 
@@ -36,6 +41,7 @@ impl Default for Config {
     }
 }
 
+/// SPI driver.
 pub struct Spi<'d, T: Instance, M: Mode> {
     inner: PeripheralRef<'d, T>,
     tx_dma: Option<PeripheralRef<'d, AnyChannel>>,
@@ -119,6 +125,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         }
     }
 
+    /// Write data to SPI blocking execution until done.
     pub fn blocking_write(&mut self, data: &[u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         for &b in data {
@@ -131,6 +138,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Transfer data in place to SPI blocking execution until done.
     pub fn blocking_transfer_in_place(&mut self, data: &mut [u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         for b in data {
@@ -143,6 +151,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Read data from SPI blocking execution until done.
     pub fn blocking_read(&mut self, data: &mut [u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         for b in data {
@@ -155,6 +164,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Transfer data to SPI blocking execution until done.
     pub fn blocking_transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         let len = read.len().max(write.len());
@@ -172,12 +182,14 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Block execution until SPI is done.
     pub fn flush(&mut self) -> Result<(), Error> {
         let p = self.inner.regs();
         while p.sr().read().bsy() {}
         Ok(())
     }
 
+    /// Set SPI frequency.
     pub fn set_frequency(&mut self, freq: u32) {
         let (presc, postdiv) = calc_prescs(freq);
         let p = self.inner.regs();
@@ -196,6 +208,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
 }
 
 impl<'d, T: Instance> Spi<'d, T, Blocking> {
+    /// Create an SPI driver in blocking mode.
     pub fn new_blocking(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -216,6 +229,7 @@ impl<'d, T: Instance> Spi<'d, T, Blocking> {
         )
     }
 
+    /// Create an SPI driver in blocking mode supporting writes only.
     pub fn new_blocking_txonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -235,6 +249,7 @@ impl<'d, T: Instance> Spi<'d, T, Blocking> {
         )
     }
 
+    /// Create an SPI driver in blocking mode supporting reads only.
     pub fn new_blocking_rxonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -256,6 +271,7 @@ impl<'d, T: Instance> Spi<'d, T, Blocking> {
 }
 
 impl<'d, T: Instance> Spi<'d, T, Async> {
+    /// Create an SPI driver in async mode supporting DMA operations.
     pub fn new(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -278,6 +294,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         )
     }
 
+    /// Create an SPI driver in async mode supporting DMA write operations only.
     pub fn new_txonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -298,6 +315,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         )
     }
 
+    /// Create an SPI driver in async mode supporting DMA read operations only.
     pub fn new_rxonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -318,6 +336,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         )
     }
 
+    /// Write data to SPI using DMA.
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let tx_ch = self.tx_dma.as_mut().unwrap();
         let tx_transfer = unsafe {
@@ -340,6 +359,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         Ok(())
     }
 
+    /// Read data from SPI using DMA.
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         // Start RX first. Transfer starts when TX starts, if RX
         // is not started yet we might lose bytes.
@@ -365,10 +385,12 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         Ok(())
     }
 
+    /// Transfer data to SPI using DMA.
     pub async fn transfer(&mut self, rx_buffer: &mut [u8], tx_buffer: &[u8]) -> Result<(), Error> {
         self.transfer_inner(rx_buffer, tx_buffer).await
     }
 
+    /// Transfer data in place to SPI using DMA.
     pub async fn transfer_in_place(&mut self, words: &mut [u8]) -> Result<(), Error> {
         self.transfer_inner(words, words).await
     }
@@ -434,7 +456,10 @@ mod sealed {
     }
 }
 
+/// Mode.
 pub trait Mode: sealed::Mode {}
+
+/// SPI instance trait.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -454,9 +479,13 @@ macro_rules! impl_instance {
 impl_instance!(SPI0, Spi0, 16, 17);
 impl_instance!(SPI1, Spi1, 18, 19);
 
+/// CLK pin.
 pub trait ClkPin<T: Instance>: GpioPin {}
+/// CS pin.
 pub trait CsPin<T: Instance>: GpioPin {}
+/// MOSI pin.
 pub trait MosiPin<T: Instance>: GpioPin {}
+/// MISO pin.
 pub trait MisoPin<T: Instance>: GpioPin {}
 
 macro_rules! impl_pin {
@@ -503,7 +532,9 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);

embassy-rp/src/timer.rs

@@ -1,3 +1,4 @@
+//! Timer driver.
 use core::cell::Cell;
 
 use atomic_polyfill::{AtomicU8, Ordering};

embassy-rp/src/uart/buffered.rs

@@ -1,3 +1,4 @@
+//! Buffered UART driver.
 use core::future::{poll_fn, Future};
 use core::slice;
 use core::task::Poll;
@@ -38,15 +39,18 @@ impl State {
     }
 }
 
+/// Buffered UART driver.
 pub struct BufferedUart<'d, T: Instance> {
     pub(crate) rx: BufferedUartRx<'d, T>,
     pub(crate) tx: BufferedUartTx<'d, T>,
 }
 
+/// Buffered UART RX handle.
 pub struct BufferedUartRx<'d, T: Instance> {
     pub(crate) phantom: PhantomData<&'d mut T>,
 }
 
+/// Buffered UART TX handle.
 pub struct BufferedUartTx<'d, T: Instance> {
     pub(crate) phantom: PhantomData<&'d mut T>,
 }
@@ -84,6 +88,7 @@ pub(crate) fn init_buffers<'d, T: Instance + 'd>(
 }
 
 impl<'d, T: Instance> BufferedUart<'d, T> {
+    /// Create a buffered UART instance.
     pub fn new(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -104,6 +109,7 @@ impl<'d, T: Instance> BufferedUart<'d, T> {
         }
     }
 
+    /// Create a buffered UART instance with flow control.
     pub fn new_with_rtscts(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -132,32 +138,39 @@ impl<'d, T: Instance> BufferedUart<'d, T> {
         }
     }
 
+    /// Write to UART TX buffer blocking execution until done.
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<usize, Error> {
         self.tx.blocking_write(buffer)
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         self.tx.blocking_flush()
     }
 
+    /// Read from UART RX buffer blocking execution until done.
     pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<usize, Error> {
         self.rx.blocking_read(buffer)
     }
 
+    /// Check if UART is busy transmitting.
     pub fn busy(&self) -> bool {
         self.tx.busy()
     }
 
+    /// Wait until TX is empty and send break condition.
     pub async fn send_break(&mut self, bits: u32) {
         self.tx.send_break(bits).await
     }
 
+    /// Split into separate RX and TX handles.
     pub fn split(self) -> (BufferedUartRx<'d, T>, BufferedUartTx<'d, T>) {
         (self.rx, self.tx)
     }
 }
 
 impl<'d, T: Instance> BufferedUartRx<'d, T> {
+    /// Create a new buffered UART RX.
     pub fn new(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -173,6 +186,7 @@ impl<'d, T: Instance> BufferedUartRx<'d, T> {
         Self { phantom: PhantomData }
     }
 
+    /// Create a new buffered UART RX with flow control.
     pub fn new_with_rts(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -253,6 +267,7 @@ impl<'d, T: Instance> BufferedUartRx<'d, T> {
         Poll::Ready(result)
     }
 
+    /// Read from UART RX buffer blocking execution until done.
     pub fn blocking_read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
         loop {
             match Self::try_read(buf) {
@@ -303,6 +318,7 @@ impl<'d, T: Instance> BufferedUartRx<'d, T> {
 }
 
 impl<'d, T: Instance> BufferedUartTx<'d, T> {
+    /// Create a new buffered UART TX.
     pub fn new(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -318,6 +334,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         Self { phantom: PhantomData }
     }
 
+    /// Create a new buffered UART TX with flow control.
     pub fn new_with_cts(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -373,6 +390,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         })
     }
 
+    /// Write to UART TX buffer blocking execution until done.
     pub fn blocking_write(&mut self, buf: &[u8]) -> Result<usize, Error> {
         if buf.is_empty() {
             return Ok(0);
@@ -398,6 +416,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         }
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         loop {
             let state = T::buffered_state();
@@ -407,6 +426,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         }
     }
 
+    /// Check if UART is busy.
     pub fn busy(&self) -> bool {
         T::regs().uartfr().read().busy()
     }
@@ -466,6 +486,7 @@ impl<'d, T: Instance> Drop for BufferedUartTx<'d, T> {
     }
 }
 
+/// Interrupt handler.
 pub struct BufferedInterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }

embassy-rp/src/uart/mod.rs

@@ -1,3 +1,4 @@
+//! UART driver.
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -20,11 +21,16 @@ use crate::{interrupt, pac, peripherals, Peripheral, RegExt};
 mod buffered;
 pub use buffered::{BufferedInterruptHandler, BufferedUart, BufferedUartRx, BufferedUartTx};
 
+/// Word length.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum DataBits {
+    /// 5 bits.
     DataBits5,
+    /// 6 bits.
     DataBits6,
+    /// 7 bits.
     DataBits7,
+    /// 8 bits.
     DataBits8,
 }
 
@@ -39,13 +45,18 @@ impl DataBits {
     }
 }
 
+/// Parity bit.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum Parity {
+    /// No parity.
     ParityNone,
+    /// Even parity.
     ParityEven,
+    /// Odd parity.
     ParityOdd,
 }
 
+/// Stop bits.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum StopBits {
     #[doc = "1 stop bit"]
@@ -54,20 +65,25 @@ pub enum StopBits {
     STOP2,
 }
 
+/// UART config.
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Config {
+    /// Baud rate.
     pub baudrate: u32,
+    /// Word length.
     pub data_bits: DataBits,
+    /// Stop bits.
     pub stop_bits: StopBits,
+    /// Parity bit.
     pub parity: Parity,
     /// Invert the tx pin output
     pub invert_tx: bool,
     /// Invert the rx pin input
     pub invert_rx: bool,
-    // Invert the rts pin
+    /// Invert the rts pin
     pub invert_rts: bool,
-    // Invert the cts pin
+    /// Invert the cts pin
     pub invert_cts: bool,
 }
 
@@ -102,21 +118,25 @@ pub enum Error {
     Framing,
 }
 
+/// Internal DMA state of UART RX.
 pub struct DmaState {
     rx_err_waker: AtomicWaker,
     rx_errs: AtomicU16,
 }
 
+/// UART driver.
 pub struct Uart<'d, T: Instance, M: Mode> {
     tx: UartTx<'d, T, M>,
     rx: UartRx<'d, T, M>,
 }
 
+/// UART TX driver.
 pub struct UartTx<'d, T: Instance, M: Mode> {
     tx_dma: Option<PeripheralRef<'d, AnyChannel>>,
     phantom: PhantomData<(&'d mut T, M)>,
 }
 
+/// UART RX driver.
 pub struct UartRx<'d, T: Instance, M: Mode> {
     rx_dma: Option<PeripheralRef<'d, AnyChannel>>,
     phantom: PhantomData<(&'d mut T, M)>,
@@ -142,6 +162,7 @@ impl<'d, T: Instance, M: Mode> UartTx<'d, T, M> {
         }
     }
 
+    /// Transmit the provided buffer blocking execution until done.
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let r = T::regs();
         for &b in buffer {
@@ -151,12 +172,14 @@ impl<'d, T: Instance, M: Mode> UartTx<'d, T, M> {
         Ok(())
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         let r = T::regs();
         while !r.uartfr().read().txfe() {}
         Ok(())
     }
 
+    /// Check if UART is busy transmitting.
     pub fn busy(&self) -> bool {
         T::regs().uartfr().read().busy()
     }
@@ -191,6 +214,8 @@ impl<'d, T: Instance, M: Mode> UartTx<'d, T, M> {
 }
 
 impl<'d, T: Instance> UartTx<'d, T, Blocking> {
+    /// Convert this uart TX instance into a buffered uart using the provided
+    /// irq and transmit buffer.
     pub fn into_buffered(
         self,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -203,6 +228,7 @@ impl<'d, T: Instance> UartTx<'d, T, Blocking> {
 }
 
 impl<'d, T: Instance> UartTx<'d, T, Async> {
+    /// Write to UART TX from the provided buffer using DMA.
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let ch = self.tx_dma.as_mut().unwrap();
         let transfer = unsafe {
@@ -246,6 +272,7 @@ impl<'d, T: Instance, M: Mode> UartRx<'d, T, M> {
         }
     }
 
+    /// Read from UART RX blocking execution until done.
     pub fn blocking_read(&mut self, mut buffer: &mut [u8]) -> Result<(), Error> {
         while buffer.len() > 0 {
             let received = self.drain_fifo(buffer)?;
@@ -294,6 +321,7 @@ impl<'d, T: Instance, M: Mode> Drop for UartRx<'d, T, M> {
 }
 
 impl<'d, T: Instance> UartRx<'d, T, Blocking> {
+    /// Create a new UART RX instance for blocking mode operations.
     pub fn new_blocking(
         _uart: impl Peripheral<P = T> + 'd,
         rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -304,6 +332,8 @@ impl<'d, T: Instance> UartRx<'d, T, Blocking> {
         Self::new_inner(false, None)
     }
 
+    /// Convert this uart RX instance into a buffered uart using the provided
+    /// irq and receive buffer.
     pub fn into_buffered(
         self,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -315,6 +345,7 @@ impl<'d, T: Instance> UartRx<'d, T, Blocking> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -338,6 +369,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::Interrupt> for InterruptHandl
 }
 
 impl<'d, T: Instance> UartRx<'d, T, Async> {
+    /// Read from UART RX into the provided buffer.
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         // clear error flags before we drain the fifo. errors that have accumulated
         // in the flags will also be present in the fifo.
@@ -458,6 +490,8 @@ impl<'d, T: Instance> Uart<'d, T, Blocking> {
         )
     }
 
+    /// Convert this uart instance into a buffered uart using the provided
+    /// irq, transmit and receive buffers.
     pub fn into_buffered(
         self,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -667,22 +701,27 @@ impl<'d, T: Instance + 'd, M: Mode> Uart<'d, T, M> {
 }
 
 impl<'d, T: Instance, M: Mode> Uart<'d, T, M> {
+    /// Transmit the provided buffer blocking execution until done.
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         self.tx.blocking_write(buffer)
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         self.tx.blocking_flush()
     }
 
+    /// Read from UART RX blocking execution until done.
     pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         self.rx.blocking_read(buffer)
     }
 
+    /// Check if UART is busy transmitting.
     pub fn busy(&self) -> bool {
         self.tx.busy()
     }
 
+    /// Wait until TX is empty and send break condition.
     pub async fn send_break(&mut self, bits: u32) {
         self.tx.send_break(bits).await
     }
@@ -695,10 +734,12 @@ impl<'d, T: Instance, M: Mode> Uart<'d, T, M> {
 }
 
 impl<'d, T: Instance> Uart<'d, T, Async> {
+    /// Write to UART TX from the provided buffer.
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         self.tx.write(buffer).await
     }
 
+    /// Read from UART RX into the provided buffer.
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         self.rx.read(buffer).await
     }
@@ -820,6 +861,10 @@ impl<'d, T: Instance, M: Mode> embedded_hal_nb::serial::ErrorType for Uart<'d, T
 impl<'d, T: Instance, M: Mode> embedded_hal_nb::serial::Read for UartRx<'d, T, M> {
     fn read(&mut self) -> nb::Result<u8, Self::Error> {
         let r = T::regs();
+        if r.uartfr().read().rxfe() {
+            return Err(nb::Error::WouldBlock);
+        }
+
         let dr = r.uartdr().read();
 
         if dr.oe() {
@@ -830,10 +875,8 @@ impl<'d, T: Instance, M: Mode> embedded_hal_nb::serial::Read for UartRx<'d, T, M
             Err(nb::Error::Other(Error::Parity))
         } else if dr.fe() {
             Err(nb::Error::Other(Error::Framing))
-        } else if dr.fe() {
-            Ok(dr.data())
         } else {
-            Err(nb::Error::WouldBlock)
+            Ok(dr.data())
         }
     }
 }
@@ -887,6 +930,7 @@ mod sealed {
     pub trait RtsPin<T: Instance> {}
 }
 
+/// UART mode.
 pub trait Mode: sealed::Mode {}
 
 macro_rules! impl_mode {
@@ -896,12 +940,15 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);
 impl_mode!(Async);
 
+/// UART instance.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -936,9 +983,13 @@ macro_rules! impl_instance {
 impl_instance!(UART0, UART0_IRQ, 20, 21);
 impl_instance!(UART1, UART1_IRQ, 22, 23);
 
+/// Trait for TX pins.
 pub trait TxPin<T: Instance>: sealed::TxPin<T> + crate::gpio::Pin {}
+/// Trait for RX pins.
 pub trait RxPin<T: Instance>: sealed::RxPin<T> + crate::gpio::Pin {}
+/// Trait for Clear To Send (CTS) pins.
 pub trait CtsPin<T: Instance>: sealed::CtsPin<T> + crate::gpio::Pin {}
+/// Trait for Request To Send (RTS) pins.
 pub trait RtsPin<T: Instance>: sealed::RtsPin<T> + crate::gpio::Pin {}
 
 macro_rules! impl_pin {

embassy-rp/src/usb.rs

@@ -1,3 +1,4 @@
+//! USB driver.
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::slice;
@@ -20,7 +21,9 @@ pub(crate) mod sealed {
     }
 }
 
+/// USB peripheral instance.
 pub trait Instance: sealed::Instance + 'static {
+    /// Interrupt for this peripheral.
     type Interrupt: interrupt::typelevel::Interrupt;
 }
 
@@ -96,6 +99,7 @@ impl EndpointData {
     }
 }
 
+/// RP2040 USB driver handle.
 pub struct Driver<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     ep_in: [EndpointData; EP_COUNT],
@@ -104,6 +108,7 @@ pub struct Driver<'d, T: Instance> {
 }
 
 impl<'d, T: Instance> Driver<'d, T> {
+    /// Create a new USB driver.
     pub fn new(_usb: impl Peripheral<P = T> + 'd, _irq: impl Binding<T::Interrupt, InterruptHandler<T>>) -> Self {
         T::Interrupt::unpend();
         unsafe { T::Interrupt::enable() };
@@ -240,6 +245,7 @@ impl<'d, T: Instance> Driver<'d, T> {
     }
 }
 
+/// USB interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -342,6 +348,7 @@ impl<'d, T: Instance> driver::Driver<'d> for Driver<'d, T> {
     }
 }
 
+/// Type representing the RP USB bus.
 pub struct Bus<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     ep_out: [EndpointData; EP_COUNT],
@@ -363,7 +370,7 @@ impl<'d, T: Instance> driver::Bus for Bus<'d, T> {
             let siestatus = regs.sie_status().read();
             let intrstatus = regs.intr().read();
 
-            if siestatus.resume() {
+            if siestatus.resume() || intrstatus.dev_resume_from_host() {
                 regs.sie_status().write(|w| w.set_resume(true));
                 return Poll::Ready(Event::Resume);
             }
@@ -461,6 +468,7 @@ trait Dir {
     fn waker(i: usize) -> &'static AtomicWaker;
 }
 
+/// Type for In direction.
 pub enum In {}
 impl Dir for In {
     fn dir() -> Direction {
@@ -473,6 +481,7 @@ impl Dir for In {
     }
 }
 
+/// Type for Out direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -485,6 +494,7 @@ impl Dir for Out {
     }
 }
 
+/// Endpoint for RP USB driver.
 pub struct Endpoint<'d, T: Instance, D> {
     _phantom: PhantomData<(&'d mut T, D)>,
     info: EndpointInfo,
@@ -616,6 +626,7 @@ impl<'d, T: Instance> driver::EndpointIn for Endpoint<'d, T, In> {
     }
 }
 
+/// Control pipe for RP USB driver.
 pub struct ControlPipe<'d, T: Instance> {
     _phantom: PhantomData<&'d mut T>,
     max_packet_size: u16,

embassy-stm32-wpan/Cargo.toml

@@ -26,7 +26,7 @@ aligned = "0.4.1"
 
 bit_field = "0.10.2"
 stm32-device-signature = { version = "0.3.3", features = ["stm32wb5x"] }
-stm32wb-hci = { version = "0.1.4", optional = true }
+stm32wb-hci = { git = "https://github.com/Dirbaio/stm32wb-hci", rev = "0aff47e009c30c5fc5d520672625173d75f7505c", optional = true }
 futures = { version = "0.3.17", default-features = false, features = ["async-await"] }
 bitflags = { version = "2.3.3", optional = true }
 

embassy-stm32/Cargo.toml

@@ -42,9 +42,9 @@ embassy-usb-driver = {version = "0.1.0", path = "../embassy-usb-driver" }
 embassy-executor = { version = "0.4.0", path = "../embassy-executor", 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-async = { version = "=1.0.0-rc.2" }
-embedded-hal-nb = { 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.3" }
+embedded-hal-nb = { version = "=1.0.0-rc.3" }
 
 embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
@@ -56,9 +56,8 @@ cortex-m = "0.7.6"
 futures = { version = "0.3.17", default-features = false, features = ["async-await"] }
 rand_core = "0.6.3"
 sdio-host = "0.5.0"
-embedded-sdmmc = { git = "https://github.com/embassy-rs/embedded-sdmmc-rs", rev = "a4f293d3a6f72158385f79c98634cb8a14d0d2fc", optional = true }
 critical-section = "1.1"
-stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-91cee0d1fdcb4e447b65a09756b506f4af91b7e2" }
+stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-2234f380f51d16d0398b8e547088b33ea623cc7c" }
 vcell = "0.1.3"
 bxcan = "0.7.0"
 nb = "1.0.0"
@@ -76,7 +75,7 @@ critical-section = { version = "1.1", features = ["std"] }
 [build-dependencies]
 proc-macro2 = "1.0.36"
 quote = "1.0.15"
-stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-91cee0d1fdcb4e447b65a09756b506f4af91b7e2", default-features = false, features = ["metadata"]}
+stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-2234f380f51d16d0398b8e547088b33ea623cc7c", default-features = false, features = ["metadata"]}
 
 
 [features]

embassy-stm32/build.rs

@@ -672,14 +672,14 @@ fn main() {
         (("lpuart", "RTS"), quote!(crate::usart::RtsPin)),
         (("lpuart", "CK"), quote!(crate::usart::CkPin)),
         (("lpuart", "DE"), quote!(crate::usart::DePin)),
-        (("sai", "SCK_A"), quote!(crate::sai::SckAPin)),
-        (("sai", "SCK_B"), quote!(crate::sai::SckBPin)),
-        (("sai", "FS_A"), quote!(crate::sai::FsAPin)),
-        (("sai", "FS_B"), quote!(crate::sai::FsBPin)),
-        (("sai", "SD_A"), quote!(crate::sai::SdAPin)),
-        (("sai", "SD_B"), quote!(crate::sai::SdBPin)),
-        (("sai", "MCLK_A"), quote!(crate::sai::MclkAPin)),
-        (("sai", "MCLK_B"), quote!(crate::sai::MclkBPin)),
+        (("sai", "SCK_A"), quote!(crate::sai::SckPin<A>)),
+        (("sai", "SCK_B"), quote!(crate::sai::SckPin<B>)),
+        (("sai", "FS_A"), quote!(crate::sai::FsPin<A>)),
+        (("sai", "FS_B"), quote!(crate::sai::FsPin<B>)),
+        (("sai", "SD_A"), quote!(crate::sai::SdPin<A>)),
+        (("sai", "SD_B"), quote!(crate::sai::SdPin<B>)),
+        (("sai", "MCLK_A"), quote!(crate::sai::MclkPin<A>)),
+        (("sai", "MCLK_B"), quote!(crate::sai::MclkPin<B>)),
         (("sai", "WS"), quote!(crate::sai::WsPin)),
         (("spi", "SCK"), quote!(crate::spi::SckPin)),
         (("spi", "MOSI"), quote!(crate::spi::MosiPin)),
@@ -995,8 +995,8 @@ fn main() {
         (("usart", "TX"), quote!(crate::usart::TxDma)),
         (("lpuart", "RX"), quote!(crate::usart::RxDma)),
         (("lpuart", "TX"), quote!(crate::usart::TxDma)),
-        (("sai", "A"), quote!(crate::sai::DmaA)),
-        (("sai", "B"), quote!(crate::sai::DmaB)),
+        (("sai", "A"), quote!(crate::sai::Dma<A>)),
+        (("sai", "B"), quote!(crate::sai::Dma<B>)),
         (("spi", "RX"), quote!(crate::spi::RxDma)),
         (("spi", "TX"), quote!(crate::spi::TxDma)),
         (("i2c", "RX"), quote!(crate::i2c::RxDma)),

embassy-stm32/src/adc/mod.rs

@@ -1,4 +1,7 @@
+//! Analog to Digital Converter (ADC)
+
 #![macro_use]
+#![allow(missing_docs)] // TODO
 
 #[cfg(not(adc_f3_v2))]
 #[cfg_attr(adc_f1, path = "f1.rs")]
@@ -24,6 +27,7 @@ pub use sample_time::SampleTime;
 
 use crate::peripherals;
 
+/// Analog to Digital driver.
 pub struct Adc<'d, T: Instance> {
     #[allow(unused)]
     adc: crate::PeripheralRef<'d, T>,
@@ -75,12 +79,16 @@ pub(crate) mod sealed {
     }
 }
 
+/// ADC instance.
 #[cfg(not(any(adc_f1, adc_v1, adc_v2, adc_v3, adc_v4, adc_f3, adc_f3_v1_1, adc_g0)))]
 pub trait Instance: sealed::Instance + crate::Peripheral<P = Self> {}
+/// ADC instance.
 #[cfg(any(adc_f1, adc_v1, adc_v2, adc_v3, adc_v4, adc_f3, adc_f3_v1_1, adc_g0))]
 pub trait Instance: sealed::Instance + crate::Peripheral<P = Self> + crate::rcc::RccPeripheral {}
 
+/// ADC pin.
 pub trait AdcPin<T: Instance>: sealed::AdcPin<T> {}
+/// ADC internal channel.
 pub trait InternalChannel<T>: sealed::InternalChannel<T> {}
 
 foreach_adc!(

embassy-stm32/src/adc/resolution.rs

@@ -1,3 +1,5 @@
+/// ADC resolution
+#[allow(missing_docs)]
 #[cfg(any(adc_v1, adc_v2, adc_v3, adc_g0, adc_f3, adc_f3_v1_1))]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -8,6 +10,8 @@ pub enum Resolution {
     SixBit,
 }
 
+/// ADC resolution
+#[allow(missing_docs)]
 #[cfg(adc_v4)]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -49,6 +53,9 @@ impl From<Resolution> for crate::pac::adc::vals::Res {
 }
 
 impl Resolution {
+    /// Get the maximum reading value for this resolution.
+    ///
+    /// This is `2**n - 1`.
     pub fn to_max_count(&self) -> u32 {
         match self {
             #[cfg(adc_v4)]

embassy-stm32/src/adc/v4.rs

@@ -32,6 +32,7 @@ const TEMP_CHANNEL: u8 = 18;
 const VBAT_CHANNEL: u8 = 17;
 
 // NOTE: Vrefint/Temperature/Vbat are not available on all ADCs, this currently cannot be modeled with stm32-data, so these are available from the software on all ADCs
+/// Internal voltage reference channel.
 pub struct VrefInt;
 impl<T: Instance> InternalChannel<T> for VrefInt {}
 impl<T: Instance> super::sealed::InternalChannel<T> for VrefInt {
@@ -40,6 +41,7 @@ impl<T: Instance> super::sealed::InternalChannel<T> for VrefInt {
     }
 }
 
+/// Internal temperature channel.
 pub struct Temperature;
 impl<T: Instance> InternalChannel<T> for Temperature {}
 impl<T: Instance> super::sealed::InternalChannel<T> for Temperature {
@@ -48,6 +50,7 @@ impl<T: Instance> super::sealed::InternalChannel<T> for Temperature {
     }
 }
 
+/// Internal battery voltage channel.
 pub struct Vbat;
 impl<T: Instance> InternalChannel<T> for Vbat {}
 impl<T: Instance> super::sealed::InternalChannel<T> for Vbat {
@@ -125,6 +128,7 @@ impl Prescaler {
 }
 
 impl<'d, T: Instance> Adc<'d, T> {
+    /// Create a new ADC driver.
     pub fn new(adc: impl Peripheral<P = T> + 'd, delay: &mut impl DelayUs<u16>) -> Self {
         embassy_hal_internal::into_ref!(adc);
         T::enable_and_reset();
@@ -212,6 +216,7 @@ impl<'d, T: Instance> Adc<'d, T> {
         });
     }
 
+    /// Enable reading the voltage reference internal channel.
     pub fn enable_vrefint(&self) -> VrefInt {
         T::common_regs().ccr().modify(|reg| {
             reg.set_vrefen(true);
@@ -220,6 +225,7 @@ impl<'d, T: Instance> Adc<'d, T> {
         VrefInt {}
     }
 
+    /// Enable reading the temperature internal channel.
     pub fn enable_temperature(&self) -> Temperature {
         T::common_regs().ccr().modify(|reg| {
             reg.set_vsenseen(true);
@@ -228,6 +234,7 @@ impl<'d, T: Instance> Adc<'d, T> {
         Temperature {}
     }
 
+    /// Enable reading the vbat internal channel.
     pub fn enable_vbat(&self) -> Vbat {
         T::common_regs().ccr().modify(|reg| {
             reg.set_vbaten(true);
@@ -236,10 +243,12 @@ impl<'d, T: Instance> Adc<'d, T> {
         Vbat {}
     }
 
+    /// Set the ADC sample time.
     pub fn set_sample_time(&mut self, sample_time: SampleTime) {
         self.sample_time = sample_time;
     }
 
+    /// Set the ADC resolution.
     pub fn set_resolution(&mut self, resolution: Resolution) {
         T::regs().cfgr().modify(|reg| reg.set_res(resolution.into()));
     }
@@ -263,6 +272,7 @@ impl<'d, T: Instance> Adc<'d, T> {
         T::regs().dr().read().0 as u16
     }
 
+    /// Read an ADC pin.
     pub fn read<P>(&mut self, pin: &mut P) -> u16
     where
         P: AdcPin<T>,
@@ -273,6 +283,7 @@ impl<'d, T: Instance> Adc<'d, T> {
         self.read_channel(pin.channel())
     }
 
+    /// Read an ADC internal channel.
     pub fn read_internal(&mut self, channel: &mut impl InternalChannel<T>) -> u16 {
         self.read_channel(channel.channel())
     }

embassy-stm32/src/can/bxcan.rs

@@ -21,8 +21,10 @@ use crate::{interrupt, peripherals, Peripheral};
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Envelope {
+    /// Reception time.
     #[cfg(feature = "time")]
     pub ts: embassy_time::Instant,
+    /// The actual CAN frame.
     pub frame: bxcan::Frame,
 }
 
@@ -43,6 +45,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::TXInterrupt> for TxInterruptH
     }
 }
 
+/// RX0 interrupt handler.
 pub struct Rx0InterruptHandler<T: Instance> {
     _phantom: PhantomData<T>,
 }
@@ -54,6 +57,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::RX0Interrupt> for Rx0Interrup
     }
 }
 
+/// RX1 interrupt handler.
 pub struct Rx1InterruptHandler<T: Instance> {
     _phantom: PhantomData<T>,
 }
@@ -65,6 +69,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::RX1Interrupt> for Rx1Interrup
     }
 }
 
+/// SCE interrupt handler.
 pub struct SceInterruptHandler<T: Instance> {
     _phantom: PhantomData<T>,
 }
@@ -82,10 +87,13 @@ impl<T: Instance> interrupt::typelevel::Handler<T::SCEInterrupt> for SceInterrup
     }
 }
 
+/// CAN driver
 pub struct Can<'d, T: Instance> {
-    pub can: bxcan::Can<BxcanInstance<'d, T>>,
+    can: bxcan::Can<BxcanInstance<'d, T>>,
 }
 
+/// CAN bus error
+#[allow(missing_docs)]
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum BusError {
@@ -101,6 +109,7 @@ pub enum BusError {
     BusWarning,
 }
 
+/// Error returned by `try_read`
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum TryReadError {
@@ -110,6 +119,7 @@ pub enum TryReadError {
     Empty,
 }
 
+/// Error returned by `try_write`
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum TryWriteError {
@@ -177,6 +187,7 @@ impl<'d, T: Instance> Can<'d, T> {
         Self { can }
     }
 
+    /// Set CAN bit rate.
     pub fn set_bitrate(&mut self, bitrate: u32) {
         let bit_timing = Self::calc_bxcan_timings(T::frequency(), bitrate).unwrap();
         self.can.modify_config().set_bit_timing(bit_timing).leave_disabled();
@@ -194,7 +205,9 @@ impl<'d, T: Instance> Can<'d, T> {
         }
     }
 
-    /// Queues the message to be sent but exerts backpressure
+    /// Queues the message to be sent.
+    ///
+    /// If the TX queue is full, this will wait until there is space, therefore exerting backpressure.
     pub async fn write(&mut self, frame: &Frame) -> bxcan::TransmitStatus {
         self.split().0.write(frame).await
     }
@@ -221,12 +234,16 @@ impl<'d, T: Instance> Can<'d, T> {
         CanTx::<T>::flush_all_inner().await
     }
 
+    /// Read a CAN frame.
+    ///
+    /// If no CAN frame is in the RX buffer, this will wait until there is one.
+    ///
     /// Returns a tuple of the time the message was received and the message frame
     pub async fn read(&mut self) -> Result<Envelope, BusError> {
         self.split().1.read().await
     }
 
-    /// Attempts to read a can frame without blocking.
+    /// Attempts to read a CAN frame without blocking.
     ///
     /// Returns [Err(TryReadError::Empty)] if there are no frames in the rx queue.
     pub fn try_read(&mut self) -> Result<Envelope, TryReadError> {
@@ -288,7 +305,7 @@ impl<'d, T: Instance> Can<'d, T> {
         }
     }
 
-    pub const fn calc_bxcan_timings(periph_clock: Hertz, can_bitrate: u32) -> Option<u32> {
+    const fn calc_bxcan_timings(periph_clock: Hertz, can_bitrate: u32) -> Option<u32> {
         const BS1_MAX: u8 = 16;
         const BS2_MAX: u8 = 8;
         const MAX_SAMPLE_POINT_PERMILL: u16 = 900;
@@ -379,21 +396,29 @@ impl<'d, T: Instance> Can<'d, T> {
         Some((sjw - 1) << 24 | (bs1 as u32 - 1) << 16 | (bs2 as u32 - 1) << 20 | (prescaler - 1))
     }
 
+    /// Split the CAN driver into transmit and receive halves.
+    ///
+    /// Useful for doing separate transmit/receive tasks.
     pub fn split<'c>(&'c mut self) -> (CanTx<'c, 'd, T>, CanRx<'c, 'd, T>) {
         let (tx, rx0, rx1) = self.can.split_by_ref();
         (CanTx { tx }, CanRx { rx0, rx1 })
     }
 
+    /// Get mutable access to the lower-level driver from the `bxcan` crate.
     pub fn as_mut(&mut self) -> &mut bxcan::Can<BxcanInstance<'d, T>> {
         &mut self.can
     }
 }
 
+/// CAN driver, transmit half.
 pub struct CanTx<'c, 'd, T: Instance> {
     tx: &'c mut bxcan::Tx<BxcanInstance<'d, T>>,
 }
 
 impl<'c, 'd, T: Instance> CanTx<'c, 'd, T> {
+    /// Queues the message to be sent.
+    ///
+    /// If the TX queue is full, this will wait until there is space, therefore exerting backpressure.
     pub async fn write(&mut self, frame: &Frame) -> bxcan::TransmitStatus {
         poll_fn(|cx| {
             T::state().tx_waker.register(cx.waker());
@@ -475,6 +500,7 @@ impl<'c, 'd, T: Instance> CanTx<'c, 'd, T> {
     }
 }
 
+/// CAN driver, receive half.
 #[allow(dead_code)]
 pub struct CanRx<'c, 'd, T: Instance> {
     rx0: &'c mut bxcan::Rx0<BxcanInstance<'d, T>>,
@@ -482,6 +508,11 @@ pub struct CanRx<'c, 'd, T: Instance> {
 }
 
 impl<'c, 'd, T: Instance> CanRx<'c, 'd, T> {
+    /// Read a CAN frame.
+    ///
+    /// If no CAN frame is in the RX buffer, this will wait until there is one.
+    ///
+    /// Returns a tuple of the time the message was received and the message frame
     pub async fn read(&mut self) -> Result<Envelope, BusError> {
         poll_fn(|cx| {
             T::state().err_waker.register(cx.waker());
@@ -585,30 +616,24 @@ pub(crate) mod sealed {
     pub trait Instance {
         const REGISTERS: *mut bxcan::RegisterBlock;
 
-        fn regs() -> &'static crate::pac::can::Can;
+        fn regs() -> crate::pac::can::Can;
         fn state() -> &'static State;
     }
 }
 
-pub trait TXInstance {
+/// CAN instance trait.
+pub trait Instance: sealed::Instance + RccPeripheral + 'static {
+    /// TX interrupt for this instance.
     type TXInterrupt: crate::interrupt::typelevel::Interrupt;
-}
-
-pub trait RX0Instance {
+    /// RX0 interrupt for this instance.
     type RX0Interrupt: crate::interrupt::typelevel::Interrupt;
-}
-
-pub trait RX1Instance {
+    /// RX1 interrupt for this instance.
     type RX1Interrupt: crate::interrupt::typelevel::Interrupt;
-}
-
-pub trait SCEInstance {
+    /// SCE interrupt for this instance.
     type SCEInterrupt: crate::interrupt::typelevel::Interrupt;
 }
 
-pub trait InterruptableInstance: TXInstance + RX0Instance + RX1Instance + SCEInstance {}
-pub trait Instance: sealed::Instance + RccPeripheral + InterruptableInstance + 'static {}
-
+/// BXCAN instance newtype.
 pub struct BxcanInstance<'a, T>(PeripheralRef<'a, T>);
 
 unsafe impl<'d, T: Instance> bxcan::Instance for BxcanInstance<'d, T> {
@@ -620,8 +645,8 @@ foreach_peripheral!(
         impl sealed::Instance for peripherals::$inst {
             const REGISTERS: *mut bxcan::RegisterBlock = crate::pac::$inst.as_ptr() as *mut _;
 
-            fn regs() -> &'static crate::pac::can::Can {
-                &crate::pac::$inst
+            fn regs() -> crate::pac::can::Can {
+                crate::pac::$inst
             }
 
             fn state() -> &'static sealed::State {
@@ -630,32 +655,12 @@ foreach_peripheral!(
             }
         }
 
-        impl Instance for peripherals::$inst {}
-
-        foreach_interrupt!(
-            ($inst,can,CAN,TX,$irq:ident) => {
-                impl TXInstance for peripherals::$inst {
-                    type TXInterrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-            ($inst,can,CAN,RX0,$irq:ident) => {
-                impl RX0Instance for peripherals::$inst {
-                    type RX0Interrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-            ($inst,can,CAN,RX1,$irq:ident) => {
-                impl RX1Instance for peripherals::$inst {
-                    type RX1Interrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-            ($inst,can,CAN,SCE,$irq:ident) => {
-                impl SCEInstance for peripherals::$inst {
-                    type SCEInterrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-        );
-
-        impl InterruptableInstance for peripherals::$inst {}
+        impl Instance for peripherals::$inst {
+            type TXInterrupt = crate::_generated::peripheral_interrupts::$inst::TX;
+            type RX0Interrupt = crate::_generated::peripheral_interrupts::$inst::RX0;
+            type RX1Interrupt = crate::_generated::peripheral_interrupts::$inst::RX1;
+            type SCEInterrupt = crate::_generated::peripheral_interrupts::$inst::SCE;
+        }
     };
 );
 

embassy-stm32/src/can/fdcan.rs

@@ -1,6 +1,3 @@
-pub use bxcan;
-use embassy_hal_internal::PeripheralRef;
-
 use crate::peripherals;
 
 pub(crate) mod sealed {
@@ -25,27 +22,19 @@ pub(crate) mod sealed {
     }
 
     pub trait Instance {
-        const REGISTERS: *mut bxcan::RegisterBlock;
-
         fn regs() -> &'static crate::pac::can::Fdcan;
         fn state() -> &'static State;
     }
 }
 
+/// Interruptable FDCAN instance.
 pub trait InterruptableInstance {}
+/// FDCAN instance.
 pub trait Instance: sealed::Instance + InterruptableInstance + 'static {}
 
-pub struct BxcanInstance<'a, T>(PeripheralRef<'a, T>);
-
-unsafe impl<'d, T: Instance> bxcan::Instance for BxcanInstance<'d, T> {
-    const REGISTERS: *mut bxcan::RegisterBlock = T::REGISTERS;
-}
-
 foreach_peripheral!(
     (can, $inst:ident) => {
         impl sealed::Instance for peripherals::$inst {
-            const REGISTERS: *mut bxcan::RegisterBlock = crate::pac::$inst.as_ptr() as *mut _;
-
             fn regs() -> &'static crate::pac::can::Fdcan {
                 &crate::pac::$inst
             }

embassy-stm32/src/can/mod.rs

@@ -1,3 +1,4 @@
+//! Controller Area Network (CAN)
 #![macro_use]
 
 #[cfg_attr(can_bxcan, path = "bxcan.rs")]

embassy-stm32/src/crc/mod.rs

@@ -1,3 +1,4 @@
+//! Cyclic Redundancy Check (CRC)
 #[cfg_attr(crc_v1, path = "v1.rs")]
 #[cfg_attr(crc_v2, path = "v2v3.rs")]
 #[cfg_attr(crc_v3, path = "v2v3.rs")]

embassy-stm32/src/crc/v1.rs

@@ -5,6 +5,7 @@ use crate::peripherals::CRC;
 use crate::rcc::sealed::RccPeripheral;
 use crate::Peripheral;
 
+/// CRC driver.
 pub struct Crc<'d> {
     _peri: PeripheralRef<'d, CRC>,
 }
@@ -34,6 +35,7 @@ impl<'d> Crc<'d> {
         PAC_CRC.dr().write_value(word);
         self.read()
     }
+
     /// Feed a slice of words to the peripheral and return the result.
     pub fn feed_words(&mut self, words: &[u32]) -> u32 {
         for word in words {
@@ -42,6 +44,8 @@ impl<'d> Crc<'d> {
 
         self.read()
     }
+
+    /// Read the CRC result value.
     pub fn read(&self) -> u32 {
         PAC_CRC.dr().read()
     }

embassy-stm32/src/crc/v2v3.rs

@@ -6,15 +6,19 @@ use crate::peripherals::CRC;
 use crate::rcc::sealed::RccPeripheral;
 use crate::Peripheral;
 
+/// CRC driver.
 pub struct Crc<'d> {
     _peripheral: PeripheralRef<'d, CRC>,
     _config: Config,
 }
 
+/// CRC configuration errlr
 pub enum ConfigError {
+    /// The selected polynomial is invalid.
     InvalidPolynomial,
 }
 
+/// CRC configuration
 pub struct Config {
     reverse_in: InputReverseConfig,
     reverse_out: bool,
@@ -25,14 +29,20 @@ pub struct Config {
     crc_poly: u32,
 }
 
+/// Input reverse configuration.
 pub enum InputReverseConfig {
+    /// Don't reverse anything
     None,
+    /// Reverse bytes
     Byte,
+    /// Reverse 16-bit halfwords.
     Halfword,
+    /// Reverse 32-bit words.
     Word,
 }
 
 impl Config {
+    /// Create a new CRC config.
     pub fn new(
         reverse_in: InputReverseConfig,
         reverse_out: bool,
@@ -57,7 +67,9 @@ impl Config {
     }
 }
 
+/// Polynomial size
 #[cfg(crc_v3)]
+#[allow(missing_docs)]
 pub enum PolySize {
     Width7,
     Width8,
@@ -81,6 +93,7 @@ impl<'d> Crc<'d> {
         instance
     }
 
+    /// Reset the CRC engine.
     pub fn reset(&mut self) {
         PAC_CRC.cr().modify(|w| w.set_reset(true));
     }

embassy-stm32/src/dac/mod.rs

@@ -1,4 +1,4 @@
-//! Provide access to the STM32 digital-to-analog converter (DAC).
+//! Digital to Analog Converter (DAC)
 #![macro_use]
 
 use core::marker::PhantomData;
@@ -62,11 +62,11 @@ impl Mode {
 ///
 /// 12-bit values outside the permitted range are silently truncated.
 pub enum Value {
-    // 8 bit value
+    /// 8 bit value
     Bit8(u8),
-    // 12 bit value stored in a u16, left-aligned
+    /// 12 bit value stored in a u16, left-aligned
     Bit12Left(u16),
-    // 12 bit value stored in a u16, right-aligned
+    /// 12 bit value stored in a u16, right-aligned
     Bit12Right(u16),
 }
 
@@ -76,11 +76,11 @@ pub enum Value {
 ///
 /// 12-bit values outside the permitted range are silently truncated.
 pub enum DualValue {
-    // 8 bit value
+    /// 8 bit value
     Bit8(u8, u8),
-    // 12 bit value stored in a u16, left-aligned
+    /// 12 bit value stored in a u16, left-aligned
     Bit12Left(u16, u16),
-    // 12 bit value stored in a u16, right-aligned
+    /// 12 bit value stored in a u16, right-aligned
     Bit12Right(u16, u16),
 }
 
@@ -88,11 +88,11 @@ pub enum DualValue {
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 /// Array variant of [`Value`].
 pub enum ValueArray<'a> {
-    // 8 bit values
+    /// 8 bit values
     Bit8(&'a [u8]),
-    // 12 bit value stored in a u16, left-aligned
+    /// 12 bit value stored in a u16, left-aligned
     Bit12Left(&'a [u16]),
-    // 12 bit values stored in a u16, right-aligned
+    /// 12 bit values stored in a u16, right-aligned
     Bit12Right(&'a [u16]),
 }
 
@@ -106,7 +106,9 @@ pub struct DacChannel<'d, T: Instance, const N: u8, DMA = NoDma> {
     dma: PeripheralRef<'d, DMA>,
 }
 
+/// DAC channel 1 type alias.
 pub type DacCh1<'d, T, DMA = NoDma> = DacChannel<'d, T, 1, DMA>;
+/// DAC channel 2 type alias.
 pub type DacCh2<'d, T, DMA = NoDma> = DacChannel<'d, T, 2, DMA>;
 
 impl<'d, T: Instance, const N: u8, DMA> DacChannel<'d, T, N, DMA> {
@@ -492,6 +494,7 @@ pub(crate) mod sealed {
     }
 }
 
+/// DAC instance.
 pub trait Instance: sealed::Instance + RccPeripheral + 'static {}
 dma_trait!(DacDma1, Instance);
 dma_trait!(DacDma2, Instance);

embassy-stm32/src/dac/tsel.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 /// Trigger selection for STM32F0.
 #[cfg(stm32f0)]
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]

embassy-stm32/src/dcmi.rs

@@ -1,3 +1,4 @@
+//! Digital Camera Interface (DCMI)
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -36,6 +37,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::Interrupt> for InterruptHandl
 }
 
 /// The level on the VSync pin when the data is not valid on the parallel interface.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq)]
 pub enum VSyncDataInvalidLevel {
     Low,
@@ -43,6 +45,7 @@ pub enum VSyncDataInvalidLevel {
 }
 
 /// The level on the VSync pin when the data is not valid on the parallel interface.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq)]
 pub enum HSyncDataInvalidLevel {
     Low,
@@ -50,14 +53,16 @@ pub enum HSyncDataInvalidLevel {
 }
 
 #[derive(Clone, Copy, PartialEq)]
+#[allow(missing_docs)]
 pub enum PixelClockPolarity {
     RisingEdge,
     FallingEdge,
 }
 
-pub struct State {
+struct State {
     waker: AtomicWaker,
 }
+
 impl State {
     const fn new() -> State {
         State {
@@ -68,18 +73,25 @@ impl State {
 
 static STATE: State = State::new();
 
+/// DCMI error.
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub enum Error {
+    /// Overrun error: the hardware generated data faster than we could read it.
     Overrun,
+    /// Internal peripheral error.
     PeripheralError,
 }
 
+/// DCMI configuration.
 #[non_exhaustive]
 pub struct Config {
+    /// VSYNC level.
     pub vsync_level: VSyncDataInvalidLevel,
+    /// HSYNC level.
     pub hsync_level: HSyncDataInvalidLevel,
+    /// PIXCLK polarity.
     pub pixclk_polarity: PixelClockPolarity,
 }
 
@@ -105,6 +117,7 @@ macro_rules! config_pins {
     };
 }
 
+/// DCMI driver.
 pub struct Dcmi<'d, T: Instance, Dma: FrameDma<T>> {
     inner: PeripheralRef<'d, T>,
     dma: PeripheralRef<'d, Dma>,
@@ -115,6 +128,7 @@ where
     T: Instance,
     Dma: FrameDma<T>,
 {
+    /// Create a new DCMI driver with 8 data bits.
     pub fn new_8bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -139,6 +153,7 @@ where
         Self::new_inner(peri, dma, config, false, 0b00)
     }
 
+    /// Create a new DCMI driver with 10 data bits.
     pub fn new_10bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -165,6 +180,7 @@ where
         Self::new_inner(peri, dma, config, false, 0b01)
     }
 
+    /// Create a new DCMI driver with 12 data bits.
     pub fn new_12bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -193,6 +209,7 @@ where
         Self::new_inner(peri, dma, config, false, 0b10)
     }
 
+    /// Create a new DCMI driver with 14 data bits.
     pub fn new_14bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -223,6 +240,7 @@ where
         Self::new_inner(peri, dma, config, false, 0b11)
     }
 
+    /// Create a new DCMI driver with 8 data bits, with embedded synchronization.
     pub fn new_es_8bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -245,6 +263,7 @@ where
         Self::new_inner(peri, dma, config, true, 0b00)
     }
 
+    /// Create a new DCMI driver with 10 data bits, with embedded synchronization.
     pub fn new_es_10bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -269,6 +288,7 @@ where
         Self::new_inner(peri, dma, config, true, 0b01)
     }
 
+    /// Create a new DCMI driver with 12 data bits, with embedded synchronization.
     pub fn new_es_12bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -295,6 +315,7 @@ where
         Self::new_inner(peri, dma, config, true, 0b10)
     }
 
+    /// Create a new DCMI driver with 14 data bits, with embedded synchronization.
     pub fn new_es_14bit(
         peri: impl Peripheral<P = T> + 'd,
         dma: impl Peripheral<P = Dma> + 'd,
@@ -538,7 +559,9 @@ mod sealed {
     }
 }
 
+/// DCMI instance.
 pub trait Instance: sealed::Instance + 'static {
+    /// Interrupt for this instance.
     type Interrupt: interrupt::typelevel::Interrupt;
 }
 

embassy-stm32/src/dma/bdma.rs

@@ -1,4 +1,4 @@
-#![macro_use]
+//! Basic Direct Memory Acccess (BDMA)
 
 use core::future::Future;
 use core::pin::Pin;
@@ -17,11 +17,16 @@ use crate::interrupt::Priority;
 use crate::pac;
 use crate::pac::bdma::{regs, vals};
 
+/// BDMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub struct TransferOptions {
     /// Enable circular DMA
+    ///
+    /// Note:
+    /// If you enable circular mode manually, you may want to build and `.await` the `Transfer` in a separate task.
+    /// Since DMA in circular mode need manually stop, `.await` in current task would block the task forever.
     pub circular: bool,
     /// Enable half transfer interrupt
     pub half_transfer_ir: bool,
@@ -140,13 +145,17 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::bdma::Dma, channel_num: usize, index
     STATE.ch_wakers[index].wake();
 }
 
+/// DMA request type alias.
 #[cfg(any(bdma_v2, dmamux))]
 pub type Request = u8;
+/// DMA request type alias.
 #[cfg(not(any(bdma_v2, dmamux)))]
 pub type Request = ();
 
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
 
@@ -161,12 +170,14 @@ pub(crate) mod sealed {
     }
 }
 
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
     channel: PeripheralRef<'a, C>,
 }
 
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
     pub unsafe fn new_read<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -177,6 +188,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_read_raw(channel, request, peri_addr, buf, options)
     }
 
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
     pub unsafe fn new_read_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -202,6 +214,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral).
     pub unsafe fn new_write<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -212,6 +225,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_write_raw(channel, request, buf, peri_addr, options)
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
     pub unsafe fn new_write_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -237,6 +251,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
     pub unsafe fn new_write_repeated<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -292,20 +307,14 @@ impl<'a, C: Channel> Transfer<'a, C> {
         ch.cr().write(|w| {
             w.set_psize(data_size.into());
             w.set_msize(data_size.into());
-            if incr_mem {
-                w.set_minc(vals::Inc::ENABLED);
-            } else {
-                w.set_minc(vals::Inc::DISABLED);
-            }
+            w.set_minc(incr_mem);
             w.set_dir(dir.into());
             w.set_teie(true);
             w.set_tcie(options.complete_transfer_ir);
             w.set_htie(options.half_transfer_ir);
+            w.set_circ(options.circular);
             if options.circular {
-                w.set_circ(vals::Circ::ENABLED);
                 debug!("Setting circular mode");
-            } else {
-                w.set_circ(vals::Circ::DISABLED);
             }
             w.set_pl(vals::Pl::VERYHIGH);
             w.set_en(true);
@@ -321,6 +330,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
         });
     }
 
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
 
@@ -331,21 +343,27 @@ impl<'a, C: Channel> Transfer<'a, C> {
         });
     }
 
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().ch(self.channel.num());
         let en = ch.cr().read().en();
-        let circular = ch.cr().read().circ() == vals::Circ::ENABLED;
+        let circular = ch.cr().read().circ();
         let tcif = STATE.complete_count[self.channel.index()].load(Ordering::Acquire) != 0;
         en && (circular || !tcif)
     }
 
-    /// Gets the total remaining transfers for the channel
-    /// Note: this will be zero for transfers that completed without cancellation.
+    /// Get the total remaining transfers for the channel.
+    ///
+    /// This will be zero for transfers that completed instead of being canceled with [`request_stop`](Self::request_stop).
     pub fn get_remaining_transfers(&self) -> u16 {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.ndtr().read().ndt()
     }
 
+    /// Blocking wait until the transfer finishes.
     pub fn blocking_wait(mut self) {
         while self.is_running() {}
         self.request_stop();
@@ -411,6 +429,7 @@ impl<'a, C: Channel> DmaCtrl for DmaCtrlImpl<'a, C> {
     }
 }
 
+/// Ringbuffer for reading data using DMA circular mode.
 pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
     cr: regs::Cr,
     channel: PeripheralRef<'a, C>,
@@ -418,7 +437,8 @@ pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
 }
 
 impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
-    pub unsafe fn new_read(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
         channel: impl Peripheral<P = C> + 'a,
         _request: Request,
         peri_addr: *mut W,
@@ -445,12 +465,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         let mut w = regs::Cr(0);
         w.set_psize(data_size.into());
         w.set_msize(data_size.into());
-        w.set_minc(vals::Inc::ENABLED);
+        w.set_minc(true);
         w.set_dir(dir.into());
         w.set_teie(true);
         w.set_htie(true);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         w.set_pl(vals::Pl::VERYHIGH);
         w.set_en(true);
 
@@ -473,11 +493,15 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         this
     }
 
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
     pub fn start(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.cr().write_value(self.cr)
     }
 
+    /// Clear all data in the ring buffer.
     pub fn clear(&mut self) {
         self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
     }
@@ -509,10 +533,11 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
     }
 
     /// The capacity of the ringbuffer.
-    pub const fn cap(&self) -> usize {
+    pub const fn capacity(&self) -> usize {
         self.ringbuf.cap()
     }
 
+    /// Set a waker to be woken when at least one byte is received.
     pub fn set_waker(&mut self, waker: &Waker) {
         DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
     }
@@ -526,6 +551,9 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
 
@@ -539,6 +567,10 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.cr().read().en()
@@ -555,6 +587,7 @@ impl<'a, C: Channel, W: Word> Drop for ReadableRingBuffer<'a, C, W> {
     }
 }
 
+/// Ringbuffer for writing data using DMA circular mode.
 pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
     cr: regs::Cr,
     channel: PeripheralRef<'a, C>,
@@ -562,7 +595,8 @@ pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
 }
 
 impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
-    pub unsafe fn new_write(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
         channel: impl Peripheral<P = C> + 'a,
         _request: Request,
         peri_addr: *mut W,
@@ -589,12 +623,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         let mut w = regs::Cr(0);
         w.set_psize(data_size.into());
         w.set_msize(data_size.into());
-        w.set_minc(vals::Inc::ENABLED);
+        w.set_minc(true);
         w.set_dir(dir.into());
         w.set_teie(true);
         w.set_htie(true);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         w.set_pl(vals::Pl::VERYHIGH);
         w.set_en(true);
 
@@ -617,11 +651,15 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         this
     }
 
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
     pub fn start(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.cr().write_value(self.cr)
     }
 
+    /// Clear all data in the ring buffer.
     pub fn clear(&mut self) {
         self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
     }
@@ -640,10 +678,11 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
     }
 
     /// The capacity of the ringbuffer.
-    pub const fn cap(&self) -> usize {
+    pub const fn capacity(&self) -> usize {
         self.ringbuf.cap()
     }
 
+    /// Set a waker to be woken when at least one byte is sent.
     pub fn set_waker(&mut self, waker: &Waker) {
         DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
     }
@@ -657,6 +696,9 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
 
@@ -670,6 +712,10 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.cr().read().en()

embassy-stm32/src/dma/dma.rs

@@ -16,6 +16,7 @@ use crate::interrupt::Priority;
 use crate::pac::dma::{regs, vals};
 use crate::{interrupt, pac};
 
+/// DMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -29,6 +30,10 @@ pub struct TransferOptions {
     /// FIFO threshold for DMA FIFO mode. If none, direct mode is used.
     pub fifo_threshold: Option<FifoThreshold>,
     /// Enable circular DMA
+    ///
+    /// Note:
+    /// If you enable circular mode manually, you may want to build and `.await` the `Transfer` in a separate task.
+    /// Since DMA in circular mode need manually stop, `.await` in current task would block the task forever.
     pub circular: bool,
     /// Enable half transfer interrupt
     pub half_transfer_ir: bool,
@@ -69,6 +74,7 @@ impl From<Dir> for vals::Dir {
     }
 }
 
+/// DMA transfer burst setting.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Burst {
@@ -93,6 +99,7 @@ impl From<Burst> for vals::Burst {
     }
 }
 
+/// DMA flow control setting.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum FlowControl {
@@ -111,6 +118,7 @@ impl From<FlowControl> for vals::Pfctrl {
     }
 }
 
+/// DMA FIFO threshold.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum FifoThreshold {
@@ -208,13 +216,17 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::dma::Dma, channel_num: usize, index:
     STATE.ch_wakers[index].wake();
 }
 
+/// DMA request type alias. (also known as DMA channel number in some chips)
 #[cfg(any(dma_v2, dmamux))]
 pub type Request = u8;
+/// DMA request type alias. (also known as DMA channel number in some chips)
 #[cfg(not(any(dma_v2, dmamux)))]
 pub type Request = ();
 
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
 
@@ -229,12 +241,14 @@ pub(crate) mod sealed {
     }
 }
 
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
     channel: PeripheralRef<'a, C>,
 }
 
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
     pub unsafe fn new_read<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -245,6 +259,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_read_raw(channel, request, peri_addr, buf, options)
     }
 
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
     pub unsafe fn new_read_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -270,6 +285,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral).
     pub unsafe fn new_write<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -280,6 +296,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_write_raw(channel, request, buf, peri_addr, options)
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
     pub unsafe fn new_write_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -305,6 +322,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
     pub unsafe fn new_write_repeated<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -368,18 +386,13 @@ impl<'a, C: Channel> Transfer<'a, C> {
             w.set_msize(data_size.into());
             w.set_psize(data_size.into());
             w.set_pl(vals::Pl::VERYHIGH);
-            w.set_minc(match incr_mem {
-                true => vals::Inc::INCREMENTED,
-                false => vals::Inc::FIXED,
-            });
-            w.set_pinc(vals::Inc::FIXED);
+            w.set_minc(incr_mem);
+            w.set_pinc(false);
             w.set_teie(true);
             w.set_tcie(options.complete_transfer_ir);
+            w.set_circ(options.circular);
             if options.circular {
-                w.set_circ(vals::Circ::ENABLED);
                 debug!("Setting circular mode");
-            } else {
-                w.set_circ(vals::Circ::DISABLED);
             }
             #[cfg(dma_v1)]
             w.set_trbuff(true);
@@ -407,6 +420,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
         });
     }
 
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().st(self.channel.num());
 
@@ -417,6 +433,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
         });
     }
 
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().read().en()
@@ -429,6 +449,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         ch.ndtr().read().ndt()
     }
 
+    /// Blocking wait until the transfer finishes.
     pub fn blocking_wait(mut self) {
         while self.is_running() {}
 
@@ -465,12 +486,14 @@ impl<'a, C: Channel> Future for Transfer<'a, C> {
 
 // ==================================
 
+/// Double-buffered DMA transfer.
 pub struct DoubleBuffered<'a, C: Channel, W: Word> {
     channel: PeripheralRef<'a, C>,
     _phantom: PhantomData<W>,
 }
 
 impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
+    /// Create a new read DMA transfer (peripheral to memory).
     pub unsafe fn new_read(
         channel: impl Peripheral<P = C> + 'a,
         _request: Request,
@@ -521,8 +544,8 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
             w.set_msize(data_size.into());
             w.set_psize(data_size.into());
             w.set_pl(vals::Pl::VERYHIGH);
-            w.set_minc(vals::Inc::INCREMENTED);
-            w.set_pinc(vals::Inc::FIXED);
+            w.set_minc(true);
+            w.set_pinc(false);
             w.set_teie(true);
             w.set_tcie(true);
             #[cfg(dma_v1)]
@@ -554,25 +577,36 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
         });
     }
 
+    /// Set the first buffer address.
+    ///
+    /// You may call this while DMA is transferring the other buffer.
     pub unsafe fn set_buffer0(&mut self, buffer: *mut W) {
         let ch = self.channel.regs().st(self.channel.num());
         ch.m0ar().write_value(buffer as _);
     }
 
+    /// Set the second buffer address.
+    ///
+    /// You may call this while DMA is transferring the other buffer.
     pub unsafe fn set_buffer1(&mut self, buffer: *mut W) {
         let ch = self.channel.regs().st(self.channel.num());
         ch.m1ar().write_value(buffer as _);
     }
 
+    /// Returh whether buffer0 is accessible (i.e. whether DMA is transferring buffer1 now)
     pub fn is_buffer0_accessible(&mut self) -> bool {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().read().ct() == vals::Ct::MEMORY1
     }
 
+    /// Set a waker to be woken when one of the buffers is being transferred.
     pub fn set_waker(&mut self, waker: &Waker) {
         STATE.ch_wakers[self.channel.index()].register(waker);
     }
 
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().st(self.channel.num());
 
@@ -583,6 +617,10 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
         });
     }
 
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().read().en()
@@ -629,6 +667,7 @@ impl<'a, C: Channel> DmaCtrl for DmaCtrlImpl<'a, C> {
     }
 }
 
+/// Ringbuffer for receiving data using DMA circular mode.
 pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
     cr: regs::Cr,
     channel: PeripheralRef<'a, C>,
@@ -636,7 +675,8 @@ pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
 }
 
 impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
-    pub unsafe fn new_read(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
         channel: impl Peripheral<P = C> + 'a,
         _request: Request,
         peri_addr: *mut W,
@@ -662,12 +702,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         w.set_msize(data_size.into());
         w.set_psize(data_size.into());
         w.set_pl(vals::Pl::VERYHIGH);
-        w.set_minc(vals::Inc::INCREMENTED);
-        w.set_pinc(vals::Inc::FIXED);
+        w.set_minc(true);
+        w.set_pinc(false);
         w.set_teie(true);
         w.set_htie(options.half_transfer_ir);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         #[cfg(dma_v1)]
         w.set_trbuff(true);
         #[cfg(dma_v2)]
@@ -706,11 +746,15 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         this
     }
 
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
     pub fn start(&mut self) {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().write_value(self.cr);
     }
 
+    /// Clear all data in the ring buffer.
     pub fn clear(&mut self) {
         self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
     }
@@ -741,11 +785,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
             .await
     }
 
-    // The capacity of the ringbuffer
-    pub const fn cap(&self) -> usize {
+    /// The capacity of the ringbuffer
+    pub const fn capacity(&self) -> usize {
         self.ringbuf.cap()
     }
 
+    /// Set a waker to be woken when at least one byte is received.
     pub fn set_waker(&mut self, waker: &Waker) {
         DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
     }
@@ -763,6 +808,9 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().st(self.channel.num());
 
@@ -774,6 +822,10 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().read().en()
@@ -790,6 +842,7 @@ impl<'a, C: Channel, W: Word> Drop for ReadableRingBuffer<'a, C, W> {
     }
 }
 
+/// Ringbuffer for writing data using DMA circular mode.
 pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
     cr: regs::Cr,
     channel: PeripheralRef<'a, C>,
@@ -797,7 +850,8 @@ pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
 }
 
 impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
-    pub unsafe fn new_write(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
         channel: impl Peripheral<P = C> + 'a,
         _request: Request,
         peri_addr: *mut W,
@@ -823,12 +877,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         w.set_msize(data_size.into());
         w.set_psize(data_size.into());
         w.set_pl(vals::Pl::VERYHIGH);
-        w.set_minc(vals::Inc::INCREMENTED);
-        w.set_pinc(vals::Inc::FIXED);
+        w.set_minc(true);
+        w.set_pinc(false);
         w.set_teie(true);
         w.set_htie(options.half_transfer_ir);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         #[cfg(dma_v1)]
         w.set_trbuff(true);
         #[cfg(dma_v2)]
@@ -867,11 +921,15 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         this
     }
 
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
     pub fn start(&mut self) {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().write_value(self.cr);
     }
 
+    /// Clear all data in the ring buffer.
     pub fn clear(&mut self) {
         self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
     }
@@ -889,11 +947,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
             .await
     }
 
-    // The capacity of the ringbuffer
-    pub const fn cap(&self) -> usize {
+    /// The capacity of the ringbuffer
+    pub const fn capacity(&self) -> usize {
         self.ringbuf.cap()
     }
 
+    /// Set a waker to be woken when at least one byte is received.
     pub fn set_waker(&mut self, waker: &Waker) {
         DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
     }
@@ -911,6 +970,9 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().st(self.channel.num());
 
@@ -922,6 +984,10 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         });
     }
 
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().st(self.channel.num());
         ch.cr().read().en()

embassy-stm32/src/dma/dmamux.rs

@@ -22,11 +22,15 @@ pub(crate) mod dmamux_sealed {
     }
 }
 
+/// DMAMUX1 instance.
 pub struct DMAMUX1;
+/// DMAMUX2 instance.
 #[cfg(stm32h7)]
 pub struct DMAMUX2;
 
+/// DMAMUX channel trait.
 pub trait MuxChannel: dmamux_sealed::MuxChannel {
+    /// DMAMUX instance this channel is on.
     type Mux;
 }
 

embassy-stm32/src/dma/gpdma.rs

@@ -16,6 +16,7 @@ use crate::interrupt::Priority;
 use crate::pac;
 use crate::pac::gpdma::vals;
 
+/// GPDMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -113,10 +114,13 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::gpdma::Gpdma, channel_num: usize, in
     }
 }
 
+/// DMA request type alias. (also known as DMA channel number in some chips)
 pub type Request = u8;
 
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
 
@@ -131,12 +135,14 @@ pub(crate) mod sealed {
     }
 }
 
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
     channel: PeripheralRef<'a, C>,
 }
 
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
     pub unsafe fn new_read<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -147,6 +153,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_read_raw(channel, request, peri_addr, buf, options)
     }
 
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
     pub unsafe fn new_read_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -172,6 +179,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral).
     pub unsafe fn new_write<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -182,6 +190,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_write_raw(channel, request, buf, peri_addr, options)
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
     pub unsafe fn new_write_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -207,6 +216,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
     pub unsafe fn new_write_repeated<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -297,6 +307,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
         this
     }
 
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.cr().modify(|w| {
@@ -304,6 +317,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
         })
     }
 
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().ch(self.channel.num());
         let sr = ch.sr().read();
@@ -317,6 +334,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         ch.br1().read().bndt()
     }
 
+    /// Blocking wait until the transfer finishes.
     pub fn blocking_wait(mut self) {
         while self.is_running() {}
 

embassy-stm32/src/dma/mod.rs

@@ -1,3 +1,5 @@
+//! Direct Memory Access (DMA)
+
 #[cfg(dma)]
 pub(crate) mod dma;
 #[cfg(dma)]
@@ -39,6 +41,13 @@ enum Dir {
     PeripheralToMemory,
 }
 
+/// "No DMA" placeholder.
+///
+/// You may pass this in place of a real DMA channel when creating a driver
+/// to indicate it should not use DMA.
+///
+/// This often causes async functionality to not be available on the instance,
+/// leaving only blocking functionality.
 pub struct NoDma;
 
 impl_peripheral!(NoDma);

embassy-stm32/src/dma/word.rs

@@ -1,3 +1,6 @@
+//! DMA word sizes.
+
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum WordSize {
@@ -7,6 +10,7 @@ pub enum WordSize {
 }
 
 impl WordSize {
+    /// Amount of bytes of this word size.
     pub fn bytes(&self) -> usize {
         match self {
             Self::OneByte => 1,
@@ -20,8 +24,13 @@ mod sealed {
     pub trait Word {}
 }
 
+/// DMA word trait.
+///
+/// This is implemented for u8, u16, u32, etc.
 pub trait Word: sealed::Word + Default + Copy + 'static {
+    /// Word size
     fn size() -> WordSize;
+    /// Amount of bits of this word size.
     fn bits() -> usize;
 }
 
@@ -40,6 +49,7 @@ macro_rules! impl_word {
     ($T:ident, $uX:ident, $bits:literal, $size:ident) => {
         #[repr(transparent)]
         #[derive(Copy, Clone, Default)]
+        #[doc = concat!(stringify!($T), " word size")]
         pub struct $T(pub $uX);
         impl_word!(_, $T, $bits, $size);
     };