(
common: &mut Common<'d, PIO>,
mut sm: StateMachine<'d, PIO, SM>,
irq: Irq<'d, PIO, 0>,
- cs: Output<'d, CS>,
+ cs: Output<'d>,
dio: DIO,
clk: CLK,
dma: impl Peripheral + 'd,
@@ -143,6 +146,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 +156,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 +174,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 +184,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();
@@ -200,9 +205,8 @@ where
}
}
-impl<'d, CS, PIO, const SM: usize, DMA> SpiBusCyw43 for PioSpi<'d, CS, PIO, SM, DMA>
+impl<'d, PIO, const SM: usize, DMA> SpiBusCyw43 for PioSpi<'d, PIO, SM, DMA>
where
- CS: Pin,
PIO: Instance,
DMA: Channel,
{
diff --git a/cyw43/Cargo.toml b/cyw43/Cargo.toml
index 293c00982..f279739e4 100644
--- a/cyw43/Cargo.toml
+++ b/cyw43/Cargo.toml
@@ -2,16 +2,22 @@
name = "cyw43"
version = "0.1.0"
edition = "2021"
+description = "Rust driver for the CYW43439 WiFi chip, used in the Raspberry Pi Pico W."
+keywords = ["embedded", "cyw43", "embassy-net", "embedded-hal-async", "wifi"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "asynchronous"]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/cyw43"
[features]
-defmt = ["dep:defmt"]
+defmt = ["dep:defmt", "heapless/defmt-03", "embassy-time/defmt"]
log = ["dep:log"]
# Fetch console logs from the WiFi firmware and forward them to `log` or `defmt`.
firmware-logs = []
[dependencies]
-embassy-time = { version = "0.2", path = "../embassy-time"}
+embassy-time = { version = "0.3.0", path = "../embassy-time"}
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"}
@@ -23,11 +29,16 @@ 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" }
num_enum = { version = "0.5.7", default-features = false }
+heapless = "0.8.0"
+
[package.metadata.embassy_docs]
src_base = "https://github.com/embassy-rs/embassy/blob/cyw43-v$VERSION/cyw43/src/"
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/cyw43/src/"
target = "thumbv6m-none-eabi"
features = ["defmt", "firmware-logs"]
+
+[package.metadata.docs.rs]
+features = ["defmt", "firmware-logs"]
diff --git a/cyw43/README.md b/cyw43/README.md
index 5b8f3cf40..dabdf0471 100644
--- a/cyw43/README.md
+++ b/cyw43/README.md
@@ -44,14 +44,3 @@ This example implements a TCP echo server on port 1234. You can try connecting t
nc 192.168.0.250 1234
```
Send it some data, you should see it echoed back and printed in the firmware's logs.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
-
diff --git a/cyw43/src/control.rs b/cyw43/src/control.rs
index 826edfe1a..135b8c245 100644
--- a/cyw43/src/control.rs
+++ b/cyw43/src/control.rs
@@ -3,7 +3,7 @@ use core::iter::zip;
use embassy_net_driver_channel as ch;
use embassy_net_driver_channel::driver::{HardwareAddress, LinkState};
-use embassy_time::Timer;
+use embassy_time::{Duration, Timer};
use crate::consts::*;
use crate::events::{Event, EventSubscriber, Events};
@@ -12,23 +12,66 @@ 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,
ioctl_state: &'a IoctlState,
}
+#[derive(Copy, Clone)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum ScanType {
+ Active,
+ Passive,
+}
+
+#[derive(Clone)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct ScanOptions {
+ pub ssid: Option>,
+ /// If set to `None`, all APs will be returned. If set to `Some`, only APs
+ /// with the specified BSSID will be returned.
+ pub bssid: Option<[u8; 6]>,
+ /// Number of probes to send on each channel.
+ pub nprobes: Option,
+ /// Time to spend waiting on the home channel.
+ pub home_time: Option,
+ /// Scan type: active or passive.
+ pub scan_type: ScanType,
+ /// Period of time to wait on each channel when passive scanning.
+ pub dwell_time: Option,
+}
+
+impl Default for ScanOptions {
+ fn default() -> Self {
+ Self {
+ ssid: None,
+ bssid: None,
+ nprobes: None,
+ home_time: None,
+ scan_type: ScanType::Passive,
+ dwell_time: None,
+ }
+ }
+}
+
impl<'a> Control<'a> {
pub(crate) fn new(state_ch: ch::StateRunner<'a>, event_sub: &'a Events, ioctl_state: &'a IoctlState) -> Self {
Self {
@@ -38,6 +81,7 @@ impl<'a> Control<'a> {
}
}
+ /// Initialize WiFi controller.
pub async fn init(&mut self, clm: &[u8]) {
const CHUNK_SIZE: usize = 1024;
@@ -154,6 +198,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 +211,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 +229,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 +297,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;
}
@@ -458,22 +508,54 @@ impl<'a> Control<'a> {
/// # Note
/// Device events are currently implemented using a bounded queue.
/// To not miss any events, you should make sure to always await the stream.
- pub async fn scan(&mut self) -> Scanner<'_> {
+ pub async fn scan(&mut self, scan_opts: ScanOptions) -> Scanner<'_> {
+ const SCANTYPE_ACTIVE: u8 = 0;
const SCANTYPE_PASSIVE: u8 = 1;
+ let dwell_time = match scan_opts.dwell_time {
+ None => !0,
+ Some(t) => {
+ let mut t = t.as_millis() as u32;
+ if t == !0 {
+ t = !0 - 1;
+ }
+ t
+ }
+ };
+
+ let mut active_time = !0;
+ let mut passive_time = !0;
+ let scan_type = match scan_opts.scan_type {
+ ScanType::Active => {
+ active_time = dwell_time;
+ SCANTYPE_ACTIVE
+ }
+ ScanType::Passive => {
+ passive_time = dwell_time;
+ SCANTYPE_PASSIVE
+ }
+ };
+
let scan_params = ScanParams {
version: 1,
action: 1,
sync_id: 1,
- ssid_len: 0,
- ssid: [0; 32],
- bssid: [0xff; 6],
+ ssid_len: scan_opts.ssid.as_ref().map(|e| e.as_bytes().len() as u32).unwrap_or(0),
+ ssid: scan_opts
+ .ssid
+ .map(|e| {
+ let mut ssid = [0; 32];
+ ssid[..e.as_bytes().len()].copy_from_slice(e.as_bytes());
+ ssid
+ })
+ .unwrap_or([0; 32]),
+ bssid: scan_opts.bssid.unwrap_or([0xff; 6]),
bss_type: 2,
- scan_type: SCANTYPE_PASSIVE,
- nprobes: !0,
- active_time: !0,
- passive_time: !0,
- home_time: !0,
+ scan_type,
+ nprobes: scan_opts.nprobes.unwrap_or(!0).into(),
+ active_time,
+ passive_time,
+ home_time: scan_opts.home_time.map(|e| e.as_millis() as u32).unwrap_or(!0),
channel_num: 0,
channel_list: [0; 1],
};
@@ -494,13 +576,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 {
let event = self.subscriber.next_message_pure().await;
if event.header.status != EStatus::PARTIAL {
diff --git a/cyw43/src/events.rs b/cyw43/src/events.rs
index a94c49a0c..44bfa98e9 100644
--- a/cyw43/src/events.rs
+++ b/cyw43/src/events.rs
@@ -311,13 +311,13 @@ pub struct Status {
pub status: u32,
}
-#[derive(Clone, Copy)]
+#[derive(Copy, Clone)]
pub enum Payload {
None,
BssInfo(BssInfo),
}
-#[derive(Clone, Copy)]
+#[derive(Copy, Clone)]
pub struct Message {
pub header: Status,
diff --git a/cyw43/src/fmt.rs b/cyw43/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/cyw43/src/fmt.rs
+++ b/cyw43/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/cyw43/src/lib.rs b/cyw43/src/lib.rs
index 300465e36..19b0cb194 100644
--- a/cyw43/src/lib.rs
+++ b/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,
@@ -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,
diff --git a/cyw43/src/runner.rs b/cyw43/src/runner.rs
index 83aee6b40..c72cf0def 100644
--- a/cyw43/src/runner.rs
+++ b/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,
@@ -222,6 +223,7 @@ where
}
}
+ /// Run the
pub async fn run(mut self) -> ! {
let mut buf = [0; 512];
loop {
@@ -240,13 +242,12 @@ where
cmd,
iface,
}) => {
- self.send_ioctl(kind, cmd, iface, unsafe { &*iobuf }).await;
+ self.send_ioctl(kind, cmd, iface, unsafe { &*iobuf }, &mut buf).await;
self.check_status(&mut buf).await;
}
Either3::Second(packet) => {
trace!("tx pkt {:02x}", Bytes(&packet[..packet.len().min(48)]));
- let mut buf = [0; 512];
let buf8 = slice8_mut(&mut buf);
// There MUST be 2 bytes of padding between the SDPCM and BDC headers.
@@ -478,9 +479,8 @@ where
self.sdpcm_seq != self.sdpcm_seq_max && self.sdpcm_seq_max.wrapping_sub(self.sdpcm_seq) & 0x80 == 0
}
- async fn send_ioctl(&mut self, kind: IoctlType, cmd: u32, iface: u32, data: &[u8]) {
- let mut buf = [0; 512];
- let buf8 = slice8_mut(&mut buf);
+ async fn send_ioctl(&mut self, kind: IoctlType, cmd: u32, iface: u32, data: &[u8], buf: &mut [u32; 512]) {
+ let buf8 = slice8_mut(buf);
let total_len = SdpcmHeader::SIZE + CdcHeader::SIZE + data.len();
diff --git a/cyw43/src/structs.rs b/cyw43/src/structs.rs
index 5ba633c74..ae7ef6038 100644
--- a/cyw43/src/structs.rs
+++ b/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::();
+ /// 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::();
@@ -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::();
@@ -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,64 @@ 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],
+ reserved1: [u8; 1],
+ /// Number of rates in the rates field.
+ pub rateset_count: u32,
+ /// Rates in 500kpbs units.
+ pub rates: [u8; 16],
+ /// Channel specification.
+ pub chanspec: u16,
+ /// Announcement traffic indication message.
+ pub atim_window: u16,
+ /// Delivery traffic indication message.
+ pub dtim_period: u8,
+ reserved2: [u8; 1],
+ /// Receive signal strength (in dbM).
+ pub rssi: i16,
+ /// Received noise (in dbM).
+ pub phy_noise: i8,
+ /// 802.11n capability.
+ pub n_cap: u8,
+ reserved3: [u8; 2],
+ /// 802.11n BSS capabilities.
+ pub nbss_cap: u32,
+ /// 802.11n control channel number.
+ pub ctl_ch: u8,
+ reserved4: [u8; 3],
+ reserved32: [u32; 1],
+ /// Flags.
+ pub flags: u8,
+ /// VHT capability.
+ pub vht_cap: u8,
+ reserved5: [u8; 2],
+ /// 802.11n BSS required MCS.
+ pub basic_mcs: [u8; 16],
+ /// Information Elements (IE) offset.
+ pub ie_offset: u16,
+ /// Length of Information Elements (IE) in bytes.
+ pub ie_length: u32,
+ /// Average signal-to-noise (SNR) ratio during frame reception.
+ pub snr: i16,
// 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;
}
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..0bf3a6c89
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,4 @@
+# embassy docs
+
+The documentation hosted at [https://embassy.dev/book](https://embassy.dev/book). Building the documentation requires
+cloning the [embassy-book](https://github.com/embassy-rs/embassy-book) repository and following the instructions.
diff --git a/docs/modules/ROOT/examples/basic/Cargo.toml b/docs/modules/ROOT/examples/basic/Cargo.toml
index 8f6e05fae..2c282145d 100644
--- a/docs/modules/ROOT/examples/basic/Cargo.toml
+++ b/docs/modules/ROOT/examples/basic/Cargo.toml
@@ -6,8 +6,8 @@ version = "0.1.0"
license = "MIT OR Apache-2.0"
[dependencies]
-embassy-executor = { version = "0.4.0", path = "../../../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] }
-embassy-time = { version = "0.2.0", path = "../../../../../embassy-time", features = ["defmt"] }
+embassy-executor = { version = "0.5.0", path = "../../../../../embassy-executor", features = ["defmt", "integrated-timers", "arch-cortex-m", "executor-thread"] }
+embassy-time = { version = "0.3.0", path = "../../../../../embassy-time", features = ["defmt"] }
embassy-nrf = { version = "0.1.0", path = "../../../../../embassy-nrf", features = ["defmt", "nrf52840", "time-driver-rtc1", "gpiote"] }
defmt = "0.3"
diff --git a/docs/modules/ROOT/examples/basic/src/main.rs b/docs/modules/ROOT/examples/basic/src/main.rs
index 04170db55..4412712c8 100644
--- a/docs/modules/ROOT/examples/basic/src/main.rs
+++ b/docs/modules/ROOT/examples/basic/src/main.rs
@@ -1,16 +1,14 @@
#![no_std]
#![no_main]
-#![feature(type_alias_impl_trait)]
use defmt::*;
use embassy_executor::Spawner;
use embassy_nrf::gpio::{Level, Output, OutputDrive};
-use embassy_nrf::peripherals::P0_13;
use embassy_time::{Duration, Timer};
use {defmt_rtt as _, panic_probe as _}; // global logger
#[embassy_executor::task]
-async fn blinker(mut led: Output<'static, P0_13>, interval: Duration) {
+async fn blinker(mut led: Output<'static>, interval: Duration) {
loop {
led.set_high();
Timer::after(interval).await;
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml
index dcdb71e7b..64f7e8403 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/Cargo.toml
+++ b/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.5.0", features = ["arch-cortex-m", "executor-thread"] }
defmt = "0.3.0"
defmt-rtt = "0.3.0"
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
index 8df632240..004602816 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
+++ b/docs/modules/ROOT/examples/layer-by-layer/blinky-async/src/main.rs
@@ -1,17 +1,16 @@
#![no_std]
#![no_main]
-#![feature(type_alias_impl_trait)]
use embassy_executor::Spawner;
use embassy_stm32::exti::ExtiInput;
-use embassy_stm32::gpio::{Input, Level, Output, Pull, Speed};
+use embassy_stm32::gpio::{Level, Output, Pull, Speed};
use {defmt_rtt as _, panic_probe as _};
#[embassy_executor::main]
async fn main(_spawner: Spawner) {
let p = embassy_stm32::init(Default::default());
let mut led = Output::new(p.PB14, Level::Low, Speed::VeryHigh);
- let mut button = ExtiInput::new(Input::new(p.PC13, Pull::Up), p.EXTI13);
+ let mut button = ExtiInput::new(p.PC13, p.EXTI13, Pull::Up);
loop {
button.wait_for_any_edge().await;
diff --git a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs b/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
index aecba0755..743c9d99b 100644
--- a/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
+++ b/docs/modules/ROOT/examples/layer-by-layer/blinky-irq/src/main.rs
@@ -6,13 +6,12 @@ use core::cell::RefCell;
use cortex_m::interrupt::Mutex;
use cortex_m::peripheral::NVIC;
use cortex_m_rt::entry;
-use embassy_stm32::gpio::{Input, Level, Output, Pin, Pull, Speed};
-use embassy_stm32::peripherals::{PB14, PC13};
+use embassy_stm32::gpio::{Input, Level, Output, Pull, Speed};
use embassy_stm32::{interrupt, pac};
use {defmt_rtt as _, panic_probe as _};
-static BUTTON: Mutex>>> = Mutex::new(RefCell::new(None));
-static LED: Mutex>>> = Mutex::new(RefCell::new(None));
+static BUTTON: Mutex>>> = Mutex::new(RefCell::new(None));
+static LED: Mutex>>> = Mutex::new(RefCell::new(None));
#[entry]
fn main() -> ! {
@@ -62,14 +61,14 @@ fn EXTI15_10() {
const PORT: u8 = 2;
const PIN: usize = 13;
-fn check_interrupt(_pin: &mut Input<'static, P>) -> bool {
+fn check_interrupt(_pin: &mut Input<'static>) -> bool {
let exti = pac::EXTI;
let pin = PIN;
let lines = exti.pr(0).read();
lines.line(pin)
}
-fn clear_interrupt(_pin: &mut Input<'static, P>) {
+fn clear_interrupt(_pin: &mut Input<'static>) {
let exti = pac::EXTI;
let pin = PIN;
let mut lines = exti.pr(0).read();
@@ -77,7 +76,7 @@ fn clear_interrupt(_pin: &mut Input<'static, P>) {
exti.pr(0).write_value(lines);
}
-fn enable_interrupt(_pin: &mut Input<'static, P>) {
+fn enable_interrupt(_pin: &mut Input<'static>) {
cortex_m::interrupt::free(|_| {
let rcc = pac::RCC;
rcc.apb2enr().modify(|w| w.set_syscfgen(true));
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index fabb80e31..44b0eddb9 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -3,10 +3,11 @@
** xref:project_structure.adoc[Project Structure]
** xref:new_project.adoc[Starting a new Embassy project]
** xref:best_practices.adoc[Best Practices]
-* xref:layer_by_layer.adoc[Bare metal to async]
* xref:runtime.adoc[Executor]
-* xref:delaying_a_task.adoc[Delaying a Task]
+* xref::time_keeping.adoc[Time-keeping]
+* xref:sharing_peripherals.adoc[Sharing peripherals]
* xref:hal.adoc[HAL]
+** xref:layer_by_layer.adoc[Anatomy of an async HAL]
** xref:nrf.adoc[nRF]
** xref:stm32.adoc[STM32]
* xref:bootloader.adoc[Bootloader]
diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
index 95792d5a0..d5aad806d 100644
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ b/docs/modules/ROOT/pages/basic_application.adoc
@@ -17,22 +17,13 @@ The first thing you’ll notice are two attributes at the top of the file. These
include::example$basic/src/main.rs[lines="1..2"]
----
-=== Rust Nightly
-
-The next declaration is a Rust Unstable feature, which means that Embassy requires Rust Nightly:
-
-[source,rust]
-----
-include::example$basic/src/main.rs[lines="3"]
-----
-
=== Dealing with errors
Then, what follows are some declarations on how to deal with panics and faults. During development, a good practice is to rely on `defmt-rtt` and `panic-probe` to print diagnostics to the terminal:
[source,rust]
----
-include::example$basic/src/main.rs[lines="10"]
+include::example$basic/src/main.rs[lines="8"]
----
=== Task declaration
@@ -41,7 +32,7 @@ After a bit of import declaration, the tasks run by the application should be de
[source,rust]
----
-include::example$basic/src/main.rs[lines="12..20"]
+include::example$basic/src/main.rs[lines="10..18"]
----
An embassy task must be declared `async`, and may NOT take generic arguments. In this case, we are handed the LED that should be blinked and the interval of the blinking.
@@ -56,7 +47,7 @@ We then initialize the HAL with a default config, which gives us a `Peripherals`
[source,rust]
----
-include::example$basic/src/main.rs[lines="22..-1"]
+include::example$basic/src/main.rs[lines="20..-1"]
----
What happens when the `blinker` task has been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy_executor::main]` macro. The macro does the following:
diff --git a/docs/modules/ROOT/pages/best_practices.adoc b/docs/modules/ROOT/pages/best_practices.adoc
index 1e02f9ba9..bfcedec06 100644
--- a/docs/modules/ROOT/pages/best_practices.adoc
+++ b/docs/modules/ROOT/pages/best_practices.adoc
@@ -3,8 +3,10 @@
Over time, a couple of best practices have emerged. The following list should serve as a guideline for developers writing embedded software in _Rust_, especially in the context of the _Embassy_ framework.
== Passing Buffers by Reference
-It may be tempting to pass arrays or wrappers, like link:https://docs.rs/heapless/latest/heapless/[`heapless::Vec`], to a function or return one just like you would with a `std::Vec`. However, in most embedded applications you don't want to spend ressources on an allocator and end up placing buffers on the stack.
-This, however, can easily blow up your stack if you are not careful.
+It may be tempting to pass arrays or wrappers, like link:https://docs.rs/heapless/latest/heapless/[`heapless::Vec`],
+to a function or return one just like you would with a `std::Vec`. However, in most embedded applications you don't
+want to spend resources on an allocator and end up placing buffers on the stack. This, however, can easily blow up
+your stack if you are not careful.
Consider the following example:
[,rust]
diff --git a/docs/modules/ROOT/pages/bootloader.adoc b/docs/modules/ROOT/pages/bootloader.adoc
index b7215e52a..3b0cdb182 100644
--- a/docs/modules/ROOT/pages/bootloader.adoc
+++ b/docs/modules/ROOT/pages/bootloader.adoc
@@ -45,6 +45,8 @@ The BOOTLOADER_STATE partition must be big enough to store one word per page in
The bootloader has a platform-agnostic part, which implements the power fail safe swapping algorithm given the boundaries set by the partitions. The platform-specific part is a minimal shim that provides additional functionality such as watchdogs or supporting the nRF52 softdevice.
+NOTE: The linker scripts for the application and bootloader look similar, but the FLASH region must point to the BOOTLOADER partition for the bootloader, and the ACTIVE partition for the application.
+
=== FirmwareUpdater
The `FirmwareUpdater` is an object for conveniently flashing firmware to the DFU partition and subsequently marking it as being ready for swapping with the active partition on the next reset. Its principle methods are `write_firmware`, which is called once per the size of the flash "write block" (typically 4KiB), and `mark_updated`, which is the final call.
@@ -91,4 +93,4 @@ cp $FIRMWARE_DIR/myfirmware $FIRMWARE_DIR/myfirmware+signed
tail -n1 $SECRETS_DIR/message.txt.sig | base64 -d -i - | dd ibs=10 skip=1 >> $FIRMWARE_DIR/myfirmware+signed
----
-Remember, guard the `$SECRETS_DIR/key.sec` key as compromising it means that another party can sign your firmware.
\ No newline at end of file
+Remember, guard the `$SECRETS_DIR/key.sec` key as compromising it means that another party can sign your firmware.
diff --git a/docs/modules/ROOT/pages/delaying_a_task.adoc b/docs/modules/ROOT/pages/delaying_a_task.adoc
deleted file mode 100644
index 3171e3515..000000000
--- a/docs/modules/ROOT/pages/delaying_a_task.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-= Delaying a Task
-
-In an embedded program, delaying a task is one of the most common actions taken. In an event loop, delays will need to be inserted to ensure
-that other tasks have a chance to run before the next iteration of the loop is called, if no other I/O is performed. Embassy provides an abstraction
-to delay the current task for a specified interval of time.
-
-Timing is serviced by the `embassy::time::Timer` struct, which provides two timing methods.
-
-`Timer::at` creates a future that completes at the specified `Instant`, relative to the system boot time.
-`Timer::after` creates a future that completes after the specified `Duration`, relative to when the future was created.
-
-An example of a delay is provided as follows:
-
-[,rust]
-----
-use embassy::executor::{task, Executor};
-use embassy::time::{Duration, Timer};
-
-#[task]
-/// Task that ticks periodically
-async fn tick_periodic() -> ! {
- loop {
- rprintln!("tick!");
- // async sleep primitive, suspends the task for 500ms.
- Timer::after(Duration::from_millis(500)).await;
- }
-}
-----
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
index a1c31bfc7..85ad7f4a2 100644
--- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
+++ b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc
@@ -7,3 +7,5 @@ Here are known examples of real-world projects which make use of Embassy. Feel f
* link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device
** Targets the ESP32-S3 or ESP32-C6 MCU
* The link:https://github.com/lora-rs/lora-rs[lora-rs] project includes link:https://github.com/lora-rs/lora-rs/tree/main/examples/stm32l0/src/bin[various standalone examples] for NRF52840, RP2040, STM32L0 and STM32WL
+** link:https://github.com/matoushybl/air-force-one[Air force one: A simple air quality monitoring system]
+*** Targets nRF52 and uses nrf-softdevice
diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc
index d1a012978..6b5e6d009 100644
--- a/docs/modules/ROOT/pages/faq.adoc
+++ b/docs/modules/ROOT/pages/faq.adoc
@@ -29,13 +29,12 @@ If you see an error like this:
You are likely missing some features of the `embassy-executor` crate.
-For Cortex-M targets, consider making sure that ALL of the following features are active in your `Cargo.toml` for the `embassy-executor` crate:
+For Cortex-M targets, check whether ALL of the following features are enabled in your `Cargo.toml` for the `embassy-executor` crate:
* `arch-cortex-m`
* `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?
@@ -44,11 +43,12 @@ The first step to managing your binary size is to set up your link:https://doc.r
[source,toml]
----
[profile.release]
-debug = false
lto = true
opt-level = "s"
incremental = false
codegen-units = 1
+# note: debug = true is okay - debuginfo isn't flashed to the device!
+debug = true
----
All of these flags are elaborated on in the Rust Book page linked above.
@@ -118,21 +118,31 @@ features = [
]
----
+If you are in the early project setup phase and not using anything from the HAL, make sure the HAL is explicitly used to prevent the linker removing it as dead code by adding this line to your source:
+
+[source,rust]
+----
+use embassy_stm32 as _;
+----
+
== Error: `Only one package in the dependency graph may specify the same links value.`
You have multiple versions of the same crate in your dependency tree. This means that some of your
embassy crates are coming from crates.io, and some from git, each of them pulling in a different set
of dependencies.
-To resolve this issue, make sure to only use a single source for all your embassy crates! To do this,
-you should patch your dependencies to use git sources using `[patch.crates.io]` and maybe `[patch.'https://github.com/embassy-rs/embassy.git']`.
+To resolve this issue, make sure to only use a single source for all your embassy crates!
+To do this, you should patch your dependencies to use git sources using `[patch.crates.io]`
+and maybe `[patch.'https://github.com/embassy-rs/embassy.git']`.
Example:
[source,toml]
----
[patch.crates-io]
-embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+embassy-time-queue-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+embassy-time-driver = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
+# embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
----
Note that the git revision should match any other embassy patches or git dependencies that you are using!
@@ -152,4 +162,49 @@ Note that the git revision should match any other embassy patches or git depende
* When using `InterruptExecutor`:
** disable `executor-thread`
** make `main`` spawn everything, then enable link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html#method.set_sleeponexit[SCB.SLEEPONEXIT] and `loop { cortex_m::asm::wfi() }`
- ** *Note:* If you need 2 priority levels, using 2 interrupt executors is better than 1 thread executor + 1 interrupt executor.
\ No newline at end of file
+ ** *Note:* If you need 2 priority levels, using 2 interrupt executors is better than 1 thread executor + 1 interrupt executor.
+
+== How do I set up the task arenas on stable?
+
+When you aren't using the `nightly` feature of `embassy-executor`, the executor uses a bump allocator, which may require configuration.
+
+Something like this error will occur at **compile time** if the task arena is *too large* for the target's RAM:
+
+[source,plain]
+----
+rust-lld: error: section '.bss' will not fit in region 'RAM': overflowed by _ bytes
+rust-lld: error: section '.uninit' will not fit in region 'RAM': overflowed by _ bytes
+----
+
+And this message will appear at **runtime** if the task arena is *too small* for the tasks running:
+
+[source,plain]
+----
+ERROR panicked at 'embassy-executor: task arena is full. You must increase the arena size, see the documentation for details: https://docs.embassy.dev/embassy-executor/'
+----
+
+NOTE: If all tasks are spawned at startup, this panic will occur immediately.
+
+Check out link:https://docs.embassy.dev/embassy-executor/git/cortex-m/index.html#task-arena[Task Arena Documentation] for more details.
+
+== Can I use manual ISRs alongside Embassy?
+
+Yes! This can be useful if you need to respond to an event as fast as possible, and the latency caused by the usual “ISR, wake, return from ISR, context switch to woken task” flow is too much for your application. Simply define a `#[interrupt] fn INTERRUPT_NAME() {}` handler as you would link:https://docs.rust-embedded.org/book/start/interrupts.html[in any other embedded rust project].
+
+== How can I measure resource usage (CPU, RAM, etc.)?
+
+=== For CPU Usage:
+
+There are a couple techniques that have been documented, generally you want to measure how long you are spending in the idle or low priority loop.
+
+We need to document specifically how to do this in embassy, but link:https://blog.japaric.io/cpu-monitor/[this older post] describes the general process.
+
+If you end up doing this, please update this section with more specific examples!
+
+=== For Static Memory Usage
+
+Tools like `cargo size` and `cargo nm` can tell you the size of any globals or other static usage. Specifically you will want to see the size of the `.data` and `.bss` sections, which together make up the total global/static memory usage.
+
+=== For Max Stack Usage
+
+Check out link:https://github.com/Dirbaio/cargo-call-stack/[`cargo-call-stack`] for statically calculating worst-case stack usage. There are some caveats and inaccuracies possible with this, but this is a good way to get the general idea. See link:https://github.com/dirbaio/cargo-call-stack#known-limitations[the README] for more details.
diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index ab819ac2a..73cb5530d 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -3,7 +3,7 @@
So you want to try Embassy, great! To get started, there are a few tools you need to install:
* link:https://rustup.rs/[rustup] - the Rust toolchain is needed to compile Rust code.
-* link:https://crates.io/crates/probe-rs[probe-rs] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well.
+* link:https://probe.rs/[probe-rs] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well.
If you don't have any supported board, don't worry: you can also run embassy on your PC using the `std` examples.
@@ -82,19 +82,19 @@ If everything worked correctly, you should see a blinking LED on your board, and
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
----
-NOTE: How does the `cargo run` command know how to connect to our board and program it? In each `examples` folder, there’s a `.cargo/config.toml` file which tells cargo to use link:https://probe.rs/[probe-rs] as the runner for ARM binaries in that folder. probe-rs handles communication with the debug probe and MCU. In order for this to work, probe-rs needs to know which chip it’s programming, so you’ll have to edit this file if you want to run examples on other chips.
+NOTE: How does the `+cargo run+` command know how to connect to our board and program it? In each `examples` folder, there’s a `.cargo/config.toml` file which tells cargo to use link:https://probe.rs/[probe-rs] as the runner for ARM binaries in that folder. probe-rs handles communication with the debug probe and MCU. In order for this to work, probe-rs needs to know which chip it’s programming, so you’ll have to edit this file if you want to run examples on other chips.
=== It didn’t work!
-If you hare having issues when running `cargo run --release`, please check the following:
+If you hare having issues when running `+cargo run --release+`, please check the following:
-* You are specifying the correct `--chip on the command line``, OR
-* You have set `.cargo/config.toml`'s run line to the correct chip, AND
-* You have changed `examples/Cargo.toml`'s HAL (e.g. embassy-stm32) dependency's feature to use the correct chip (replace the existing stm32xxxx feature)
+* You are specifying the correct `+--chip+` on the command line, OR
+* You have set `+.cargo/config.toml+`’s run line to the correct chip, AND
+* You have changed `+examples/Cargo.toml+`’s HAL (e.g. embassy-stm32) dependency's feature to use the correct chip (replace the existing stm32xxxx feature)
At this point the project should run. If you do not see a blinky LED for blinky, for example, be sure to check the code is toggling your board's LED pin.
-If you are trying to run an example with `cargo run --release` and you see the following output:
+If you are trying to run an example with `+cargo run --release+` and you see the following output:
[source]
----
0.000000 INFO Hello World!
@@ -115,6 +115,22 @@ To get rid of the frame-index error add the following to your `Cargo.toml`:
debug = 2
----
+If you’re getting an extremely long error message containing something like the following:
+
+[source]
+----
+error[E0463]: can't find crate for `std`
+ |
+ = note: the `thumbv6m-none-eabi` target may not support the standard library
+ = note: `std` is required by `stable_deref_trait` because it does not declare `#![no_std]`
+----
+
+Make sure that you didn’t accidentally run `+cargo add probe-rs+` (which adds it as a dependency) instead of link:https://probe.rs/docs/getting-started/installation/[correctly installing probe-rs].
+
+If you’re using a raspberry pi pico-w, make sure you’re running `+cargo run --bin wifi_blinky --release+` rather than the regular blinky. The pico-w’s on-board LED is connected to the WiFi chip, which needs to be initialized before the LED can be blinked.
+
+If you’re using an rp2040 debug probe (e.g. the pico probe) and are having issues after running `probe-rs info`, unplug and reconnect the probe, letting it power cycle. Running `probe-rs info` is link:https://github.com/probe-rs/probe-rs/issues/1849[known to put the pico probe into an unusable state].
+
If you’re still having problems, check the link:https://embassy.dev/book/dev/faq.html[FAQ], or ask for help in the link:https://matrix.to/#/#embassy-rs:matrix.org[Embassy Chat Room].
== What's next?
@@ -124,3 +140,4 @@ Congratulations, you have your first Embassy application running! Here are some
* Read more about the xref:runtime.adoc[executor].
* Read more about the xref:hal.adoc[HAL].
* Start xref:basic_application.adoc[writing your application].
+* Learn how to xref:new_project.adoc[start a new embassy project by adapting an example].
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 6fba80eda..e17adbbd7 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -41,7 +41,7 @@ The link:https://docs.embassy.dev/embassy-net/[embassy-net] network stack implem
The link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.
=== LoRa
-link:https://github.com/embassy-rs/lora-phy[lora-phy] and link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on a wide range of LoRa radios, fully integrated with a Rust link:https://github.com/ivajloip/rust-lorawan[LoRaWAN] implementation.
+link:https://github.com/lora-rs/lora-rs[lora-rs] supports LoRa networking on a wide range of LoRa radios, fully integrated with a Rust LoRaWAN implementation. It provides four crates — lora-phy, lora-modulation, lorawan-encoding, and lorawan-device — and basic examples for various development boards. It has support for STM32WL wireless microcontrollers or Semtech SX127x transceivers, among others.
=== USB
link:https://docs.embassy.dev/embassy-usb/[embassy-usb] implements a device-side USB stack. Implementations for common classes such as USB serial (CDC ACM) and USB HID are available, and a rich builder API allows building your own.
diff --git a/docs/modules/ROOT/pages/new_project.adoc b/docs/modules/ROOT/pages/new_project.adoc
index ce139ed8d..320966bb6 100644
--- a/docs/modules/ROOT/pages/new_project.adoc
+++ b/docs/modules/ROOT/pages/new_project.adoc
@@ -1,6 +1,17 @@
= Starting a new Embassy project
-Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project. The easiest way to do this is to adapt an example for a similar chip to the one you’re targeting.
+Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project.
+
+There are some tools for generating Embassy projects: (WIP)
+
+==== CLI
+- link:https://github.com/adinack/cargo-embassy[cargo-embassy] (STM32 and NRF)
+
+==== cargo-generate
+- link:https://github.com/lulf/embassy-template[embassy-template] (STM32, NRF, and RP)
+- link:https://github.com/bentwire/embassy-rp2040-template[embassy-rp2040-template] (RP)
+
+But if you want to start from scratch:
As an example, let’s create a new embassy project from scratch for a STM32G474. The same instructions are applicable for any supported chip with some minor changes.
@@ -166,13 +177,13 @@ should result in a blinking LED (if there’s one attached to the pin in `src/ma
Erasing sectors ✔ [00:00:00] [#########################################################] 18.00 KiB/18.00 KiB @ 54.09 KiB/s (eta 0s )
Programming pages ✔ [00:00:00] [#########################################################] 17.00 KiB/17.00 KiB @ 35.91 KiB/s (eta 0s ) Finished in 0.817s
0.000000 TRACE BDCR configured: 00008200
-└─ embassy_stm32::rcc::bd::{impl#3}::init::{closure#4} @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:117
+└─ embassy_stm32::rcc::bd::{impl#3}::init::{closure#4} @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:117
0.000000 DEBUG rcc: Clocks { sys: Hertz(16000000), pclk1: Hertz(16000000), pclk1_tim: Hertz(16000000), pclk2: Hertz(16000000), pclk2_tim: Hertz(16000000), hclk1: Hertz(16000000), hclk2: Hertz(16000000), pll1_p: None, adc: None, adc34: None, rtc: Some(Hertz(32000)) }
-└─ embassy_stm32::rcc::set_freqs @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:130
+└─ embassy_stm32::rcc::set_freqs @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:130
0.000000 INFO Hello World!
-└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:14
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:14
0.000091 INFO high
-└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:19
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:19
0.300201 INFO low
-└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:23
-----
\ No newline at end of file
+└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:23
+----
diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/modules/ROOT/pages/project_structure.adoc
index 3e6008ec4..2adfcc1df 100644
--- a/docs/modules/ROOT/pages/project_structure.adoc
+++ b/docs/modules/ROOT/pages/project_structure.adoc
@@ -18,7 +18,7 @@ my-project
|- rust-toolchain.toml
----
-=== .cargo/config.toml
+== .cargo/config.toml
This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device.
@@ -36,17 +36,22 @@ target = "thumbv6m-none-eabi" # <-change for your platform
DEFMT_LOG = "trace" # <- can change to info, warn, or error
----
-=== build.rs
+== build.rs
-This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if needed. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example].
+This is the build script for your project. It links defmt (what is link:https://defmt.ferrous-systems.com[defmt]?) and the `memory.x` file if needed. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example].
-=== Cargo.toml
+== Cargo.toml
This is your manifest file, where you can configure all of the embassy components to use the features you need.
-TODO: someone should exhaustively describe every feature for every component!
+==== Features
+===== Time
+- tick-hz-x: Configures the tick rate of `embassy-time`. Higher tick rate means higher precision, and higher CPU wakes.
+- defmt-timestamp-uptime: defmt log entries will display the uptime in seconds.
-=== memory.x
+...more to come
+
+== memory.x
This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x.
@@ -63,7 +68,7 @@ MEMORY
}
----
-=== rust-toolchain.toml
+== rust-toolchain.toml
This file configures the rust version and configuration to use.
diff --git a/docs/modules/ROOT/pages/sharing_peripherals.adoc b/docs/modules/ROOT/pages/sharing_peripherals.adoc
new file mode 100644
index 000000000..fcba0e27b
--- /dev/null
+++ b/docs/modules/ROOT/pages/sharing_peripherals.adoc
@@ -0,0 +1,126 @@
+= Sharing peripherals between tasks
+
+Often times, more than one task needs access to the same resource (pin, communication interface, etc.). Embassy provides many different synchronization primitives in the link:https://crates.io/crates/embassy-sync[embassy-sync] crate.
+
+The following examples shows different ways to use the on-board LED on a Raspberry Pi Pico board by two tasks simultaneously.
+
+== Sharing using a Mutex
+
+Using mutual exclusion is the simplest way to share a peripheral.
+
+[,rust]
+----
+use defmt::*;
+use embassy_executor::Spawner;
+use embassy_rp::gpio;
+use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex;
+use embassy_sync::mutex::Mutex;
+use embassy_time::{Duration, Ticker};
+use gpio::{AnyPin, Level, Output};
+use {defmt_rtt as _, panic_probe as _};
+
+type LedType = Mutex>>;
+static LED: LedType = Mutex::new(None);
+
+#[embassy_executor::main]
+async fn main(spawner: Spawner) {
+ let p = embassy_rp::init(Default::default());
+ // set the content of the global LED reference to the real LED pin
+ let led = Output::new(AnyPin::from(p.PIN_25), Level::High);
+ // inner scope is so that once the mutex is written to, the MutexGuard is dropped, thus the
+ // Mutex is released
+ {
+ *(LED.lock().await) = Some(led);
+ }
+ let dt = 100 * 1_000_000;
+ let k = 1.003;
+
+ unwrap!(spawner.spawn(toggle_led(&LED, Duration::from_nanos(dt))));
+ unwrap!(spawner.spawn(toggle_led(&LED, Duration::from_nanos((dt as f64 * k) as u64))));
+}
+
+// A pool size of 2 means you can spawn two instances of this task.
+#[embassy_executor::task(pool_size = 2)]
+async fn toggle_led(led: &'static LedType, delay: Duration) {
+ let mut ticker = Ticker::every(delay);
+ loop {
+ {
+ let mut led_unlocked = led.lock().await;
+ if let Some(pin_ref) = led_unlocked.as_mut() {
+ pin_ref.toggle();
+ }
+ }
+ ticker.next().await;
+ }
+}
+----
+
+The structure facilitating access to the resource is the defined `LedType`.
+
+=== Why so complicated
+
+Unwrapping the layers gives insight into why each one is needed.
+
+==== `Mutex`
+
+The mutex is there so if one task gets the resource first and begins modifying it, all other tasks wanting to write will have to wait (the `led.lock().await` will return immediately if no task has locked the mutex, and will block if it is accessed somewhere else).
+
+==== `Option`
+
+The `LED` variable needs to be defined outside the main task as references accepted by tasks need to be `'static`. However, if it is outside the main task, it cannot be initialised to point to any pin, as the pins themselves are not initialised. Thus, it is set to `None`.
+
+==== `Output`
+
+To indicate that the pin will be set to an Output. The `AnyPin` could have been `embassy_rp::peripherals::PIN_25`, however this option lets the `toggle_led` function be more generic.
+
+== Sharing using a Channel
+
+A channel is another way to ensure exclusive access to a resource. Using a channel is great in the cases where the access can happen at a later point in time, allowing you to enqueue operations and do other things.
+
+[,rust]
+----
+use defmt::*;
+use embassy_executor::Spawner;
+use embassy_rp::gpio;
+use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex;
+use embassy_sync::channel::{Channel, Sender};
+use embassy_time::{Duration, Ticker};
+use gpio::{AnyPin, Level, Output};
+use {defmt_rtt as _, panic_probe as _};
+
+enum LedState {
+ Toggle,
+}
+static CHANNEL: Channel = Channel::new();
+
+#[embassy_executor::main]
+async fn main(spawner: Spawner) {
+ let p = embassy_rp::init(Default::default());
+ let mut led = Output::new(AnyPin::from(p.PIN_25), Level::High);
+
+ let dt = 100 * 1_000_000;
+ let k = 1.003;
+
+ unwrap!(spawner.spawn(toggle_led(CHANNEL.sender(), Duration::from_nanos(dt))));
+ unwrap!(spawner.spawn(toggle_led(CHANNEL.sender(), Duration::from_nanos((dt as f64 * k) as u64))));
+
+ loop {
+ match CHANNEL.receive().await {
+ LedState::Toggle => led.toggle(),
+ }
+ }
+}
+
+// A pool size of 2 means you can spawn two instances of this task.
+#[embassy_executor::task(pool_size = 2)]
+async fn toggle_led(control: Sender<'static, ThreadModeRawMutex, LedState, 64>, delay: Duration) {
+ let mut ticker = Ticker::every(delay);
+ loop {
+ control.send(LedState::Toggle).await;
+ ticker.next().await;
+ }
+}
+----
+
+This example replaces the Mutex with a Channel, and uses another task (the main loop) to drive the LED. The advantage of this approach is that only a single task references the peripheral, separating concerns. However, using a Mutex has a lower overhead and might be necessary if you need to ensure
+that the operation is ecompleted before continuing to do other work in your task.
diff --git a/docs/modules/ROOT/pages/time_keeping.adoc b/docs/modules/ROOT/pages/time_keeping.adoc
new file mode 100644
index 000000000..5068216ed
--- /dev/null
+++ b/docs/modules/ROOT/pages/time_keeping.adoc
@@ -0,0 +1,60 @@
+= Time-keeping
+
+In an embedded program, delaying a task is one of the most common actions taken. In an event loop, delays will need to be inserted to ensure
+that other tasks have a chance to run before the next iteration of the loop is called, if no other I/O is performed. Embassy provides abstractions
+to delay the current task for a specified interval of time.
+
+The interface for time-keeping in Embassy is handled by the link:https://crates.io/crates/embassy-time[embassy-time] crate. The types can be used with the internal
+timer queue in link:https://crates.io/crates/embassy-executor[embassy-executor] or a custom timer queue implementation.
+
+== Timer
+
+The `embassy::time::Timer` type provides two timing methods.
+
+`Timer::at` creates a future that completes at the specified `Instant`, relative to the system boot time.
+`Timer::after` creates a future that completes after the specified `Duration`, relative to when the future was created.
+
+An example of a delay is provided as follows:
+
+[,rust]
+----
+use embassy::executor::{task, Executor};
+use embassy::time::{Duration, Timer};
+
+#[task]
+/// Task that ticks periodically
+async fn tick_periodic() -> ! {
+ loop {
+ rprintln!("tick!");
+ // async sleep primitive, suspends the task for 500ms.
+ Timer::after(Duration::from_millis(500)).await;
+ }
+}
+----
+
+== Delay
+
+The `embassy::time::Delay` type provides an implementation of the link:https://docs.rs/embedded-hal/1.0.0/embedded_hal/delay/index.html[embedded-hal] and
+link:https://docs.rs/embedded-hal-async/latest/embedded_hal_async/delay/index.html[embedded-hal-async] traits. This can be used for drivers
+that expect a generic delay implementation to be provided.
+
+An example of how this can be used:
+
+[,rust]
+----
+use embassy::executor::{task, Executor};
+
+#[task]
+/// Task that ticks periodically
+async fn tick_periodic() -> ! {
+ loop {
+ rprintln!("tick!");
+ // async sleep primitive, suspends the task for 500ms.
+ generic_delay(embassy::time::Delay).await
+ }
+}
+
+async fn generic_delay(delay: D) {
+ delay.delay_ms(500).await;
+}
+----
diff --git a/embassy-boot/nrf/Cargo.toml b/embassy-boot-nrf/Cargo.toml
similarity index 57%
rename from embassy-boot/nrf/Cargo.toml
rename to embassy-boot-nrf/Cargo.toml
index eea29cf2e..c056dc66a 100644
--- a/embassy-boot/nrf/Cargo.toml
+++ b/embassy-boot-nrf/Cargo.toml
@@ -1,13 +1,20 @@
[package]
edition = "2021"
name = "embassy-boot-nrf"
-version = "0.1.0"
+version = "0.2.0"
description = "Bootloader lib for nRF chips"
license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-boot-nrf"
+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/"
-src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot/nrf/src/"
+src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-nrf-v$VERSION/embassy-boot-nrf/src/"
+src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot-nrf/src/"
features = ["embassy-nrf/nrf52840"]
target = "thumbv7em-none-eabi"
@@ -16,16 +23,16 @@ target = "thumbv7em-none-eabi"
[dependencies]
defmt = { version = "0.3", optional = true }
-embassy-sync = { version = "0.5.0", path = "../../embassy-sync" }
-embassy-nrf = { path = "../../embassy-nrf" }
-embassy-boot = { path = "../boot", default-features = false }
+embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
+embassy-nrf = { version = "0.1.0", path = "../embassy-nrf", default-features = false }
+embassy-boot = { version = "0.2.0", path = "../embassy-boot" }
cortex-m = { version = "0.7.6" }
cortex-m-rt = { version = "0.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 = [
diff --git a/embassy-boot-nrf/README.md b/embassy-boot-nrf/README.md
new file mode 100644
index 000000000..9dc5b0eb9
--- /dev/null
+++ b/embassy-boot-nrf/README.md
@@ -0,0 +1,11 @@
+# embassy-boot-nrf
+
+An [Embassy](https://embassy.dev) project.
+
+An adaptation of `embassy-boot` for nRF.
+
+## Features
+
+* Load applications with or without the softdevice.
+* Configure bootloader partitions based on linker script.
+* Using watchdog timer to detect application failure.
diff --git a/embassy-boot/stm32/src/fmt.rs b/embassy-boot-nrf/src/fmt.rs
similarity index 99%
rename from embassy-boot/stm32/src/fmt.rs
rename to embassy-boot-nrf/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-boot/stm32/src/fmt.rs
+++ b/embassy-boot-nrf/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-boot/nrf/src/lib.rs b/embassy-boot-nrf/src/lib.rs
similarity index 89%
rename from embassy-boot/nrf/src/lib.rs
rename to embassy-boot-nrf/src/lib.rs
index 5b20a93c6..d53e78895 100644
--- a/embassy-boot/nrf/src/lib.rs
+++ b/embassy-boot-nrf/src/lib.rs
@@ -4,8 +4,8 @@
mod fmt;
pub use embassy_boot::{
- AlignedBuffer, BlockingFirmwareState, BlockingFirmwareUpdater, BootLoaderConfig, FirmwareState, FirmwareUpdater,
- FirmwareUpdaterConfig,
+ AlignedBuffer, BlockingFirmwareState, BlockingFirmwareUpdater, BootError, BootLoaderConfig, FirmwareState,
+ FirmwareUpdater, FirmwareUpdaterConfig,
};
use embassy_nrf::nvmc::PAGE_SIZE;
use embassy_nrf::peripherals::WDT;
@@ -16,14 +16,21 @@ use embedded_storage::nor_flash::{ErrorType, NorFlash, ReadNorFlash};
pub struct BootLoader;
impl BootLoader {
- /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware.
+ /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware
pub fn prepare(
config: BootLoaderConfig,
) -> Self {
+ Self::try_prepare::(config).expect("Boot prepare error")
+ }
+
+ /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware
+ pub fn try_prepare(
+ config: BootLoaderConfig,
+ ) -> Result {
let mut aligned_buf = AlignedBuffer([0; BUFFER_SIZE]);
let mut boot = embassy_boot::BootLoader::new(config);
- boot.prepare_boot(&mut aligned_buf.0).expect("Boot prepare error");
- Self
+ let _state = boot.prepare_boot(aligned_buf.as_mut())?;
+ Ok(Self)
}
/// Boots the application without softdevice mechanisms.
diff --git a/embassy-boot/rp/Cargo.toml b/embassy-boot-rp/Cargo.toml
similarity index 74%
rename from embassy-boot/rp/Cargo.toml
rename to embassy-boot-rp/Cargo.toml
index 0f2dc4628..305bc5995 100644
--- a/embassy-boot/rp/Cargo.toml
+++ b/embassy-boot-rp/Cargo.toml
@@ -1,13 +1,20 @@
[package]
edition = "2021"
name = "embassy-boot-rp"
-version = "0.1.0"
+version = "0.2.0"
description = "Bootloader lib for RP2040 chips"
license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-boot-rp"
+categories = [
+ "embedded",
+ "no-std",
+ "asynchronous",
+]
[package.metadata.embassy_docs]
src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-rp-v$VERSION/src/"
-src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot/rp/src/"
+src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot-rp/src/"
target = "thumbv6m-none-eabi"
[lib]
@@ -17,10 +24,10 @@ defmt = { version = "0.3", optional = true }
defmt-rtt = { version = "0.4", optional = true }
log = { version = "0.4", optional = true }
-embassy-sync = { version = "0.5.0", path = "../../embassy-sync" }
-embassy-rp = { path = "../../embassy-rp", default-features = false }
-embassy-boot = { path = "../boot", default-features = false }
-embassy-time = { path = "../../embassy-time" }
+embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
+embassy-rp = { version = "0.1.0", path = "../embassy-rp", default-features = false }
+embassy-boot = { version = "0.2.0", path = "../embassy-boot" }
+embassy-time = { version = "0.3.0", path = "../embassy-time" }
cortex-m = { version = "0.7.6" }
cortex-m-rt = { version = "0.7" }
diff --git a/embassy-boot-rp/README.md b/embassy-boot-rp/README.md
new file mode 100644
index 000000000..b664145a9
--- /dev/null
+++ b/embassy-boot-rp/README.md
@@ -0,0 +1,12 @@
+# embassy-boot-rp
+
+An [Embassy](https://embassy.dev) project.
+
+An adaptation of `embassy-boot` for RP2040.
+
+NOTE: The applications using this bootloader should not link with the `link-rp.x` linker script.
+
+## Features
+
+* Configure bootloader partitions based on linker script.
+* Load applications from active partition.
diff --git a/embassy-boot/rp/build.rs b/embassy-boot-rp/build.rs
similarity index 100%
rename from embassy-boot/rp/build.rs
rename to embassy-boot-rp/build.rs
diff --git a/embassy-boot/nrf/src/fmt.rs b/embassy-boot-rp/src/fmt.rs
similarity index 99%
rename from embassy-boot/nrf/src/fmt.rs
rename to embassy-boot-rp/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-boot/nrf/src/fmt.rs
+++ b/embassy-boot-rp/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-boot/rp/src/lib.rs b/embassy-boot-rp/src/lib.rs
similarity index 85%
rename from embassy-boot/rp/src/lib.rs
rename to embassy-boot-rp/src/lib.rs
index 07a5b3f4d..d0a393bed 100644
--- a/embassy-boot/rp/src/lib.rs
+++ b/embassy-boot-rp/src/lib.rs
@@ -4,8 +4,8 @@
mod fmt;
pub use embassy_boot::{
- AlignedBuffer, BlockingFirmwareState, BlockingFirmwareUpdater, BootLoaderConfig, FirmwareState, FirmwareUpdater,
- FirmwareUpdaterConfig, State,
+ AlignedBuffer, BlockingFirmwareState, BlockingFirmwareUpdater, BootError, BootLoaderConfig, FirmwareState,
+ FirmwareUpdater, FirmwareUpdaterConfig, State,
};
use embassy_rp::flash::{Blocking, Flash, ERASE_SIZE};
use embassy_rp::peripherals::{FLASH, WATCHDOG};
@@ -21,10 +21,17 @@ impl BootLoader {
pub fn prepare(
config: BootLoaderConfig,
) -> Self {
+ Self::try_prepare::(config).expect("Boot prepare error")
+ }
+
+ /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware
+ pub fn try_prepare(
+ config: BootLoaderConfig,
+ ) -> Result {
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())?;
+ Ok(Self)
}
/// Boots the application.
diff --git a/embassy-boot/stm32/Cargo.toml b/embassy-boot-stm32/Cargo.toml
similarity index 74%
rename from embassy-boot/stm32/Cargo.toml
rename to embassy-boot-stm32/Cargo.toml
index bc8da6738..6f8fbe355 100644
--- a/embassy-boot/stm32/Cargo.toml
+++ b/embassy-boot-stm32/Cargo.toml
@@ -1,13 +1,20 @@
[package]
edition = "2021"
name = "embassy-boot-stm32"
-version = "0.1.0"
+version = "0.2.0"
description = "Bootloader lib for STM32 chips"
license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-boot-stm32"
+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/"
-src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot/stm32/src/"
+src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-nrf-v$VERSION/embassy-boot-stm32/src/"
+src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot-stm32/src/"
features = ["embassy-stm32/stm32f429zi"]
target = "thumbv7em-none-eabi"
@@ -18,9 +25,9 @@ defmt = { version = "0.3", optional = true }
defmt-rtt = { version = "0.4", optional = true }
log = { version = "0.4", optional = true }
-embassy-sync = { version = "0.5.0", path = "../../embassy-sync" }
-embassy-stm32 = { path = "../../embassy-stm32", default-features = false }
-embassy-boot = { path = "../boot", default-features = false }
+embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
+embassy-stm32 = { version = "0.1.0", path = "../embassy-stm32", default-features = false }
+embassy-boot = { version = "0.2.0", path = "../embassy-boot" }
cortex-m = { version = "0.7.6" }
cortex-m-rt = { version = "0.7" }
embedded-storage = "0.3.1"
diff --git a/embassy-boot-stm32/README.md b/embassy-boot-stm32/README.md
new file mode 100644
index 000000000..f6dadc8e7
--- /dev/null
+++ b/embassy-boot-stm32/README.md
@@ -0,0 +1,10 @@
+# embassy-boot-stm32
+
+An [Embassy](https://embassy.dev) project.
+
+An adaptation of `embassy-boot` for STM32.
+
+## Features
+
+* Configure bootloader partitions based on linker script.
+* Load applications from active partition.
diff --git a/embassy-boot/stm32/build.rs b/embassy-boot-stm32/build.rs
similarity index 100%
rename from embassy-boot/stm32/build.rs
rename to embassy-boot-stm32/build.rs
diff --git a/embassy-boot/rp/src/fmt.rs b/embassy-boot-stm32/src/fmt.rs
similarity index 99%
rename from embassy-boot/rp/src/fmt.rs
rename to embassy-boot-stm32/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-boot/rp/src/fmt.rs
+++ b/embassy-boot-stm32/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-boot/stm32/src/lib.rs b/embassy-boot-stm32/src/lib.rs
similarity index 62%
rename from embassy-boot/stm32/src/lib.rs
rename to embassy-boot-stm32/src/lib.rs
index c418cb262..708441835 100644
--- a/embassy-boot/stm32/src/lib.rs
+++ b/embassy-boot-stm32/src/lib.rs
@@ -4,23 +4,33 @@
mod fmt;
pub use embassy_boot::{
- AlignedBuffer, BlockingFirmwareState, BlockingFirmwareUpdater, BootLoaderConfig, FirmwareState, FirmwareUpdater,
- FirmwareUpdaterConfig, State,
+ AlignedBuffer, BlockingFirmwareState, BlockingFirmwareUpdater, BootError, BootLoaderConfig, FirmwareState,
+ FirmwareUpdater, FirmwareUpdaterConfig, State,
};
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
pub fn prepare(
config: BootLoaderConfig,
) -> Self {
+ Self::try_prepare::(config).expect("Boot prepare error")
+ }
+
+ /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware
+ pub fn try_prepare(
+ config: BootLoaderConfig,
+ ) -> Result {
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())?;
+ Ok(Self { state })
}
/// Boots the application.
diff --git a/embassy-boot/boot/Cargo.toml b/embassy-boot/Cargo.toml
similarity index 61%
rename from embassy-boot/boot/Cargo.toml
rename to embassy-boot/Cargo.toml
index dd2ff8158..242caa229 100644
--- a/embassy-boot/boot/Cargo.toml
+++ b/embassy-boot/Cargo.toml
@@ -1,10 +1,11 @@
[package]
edition = "2021"
name = "embassy-boot"
-version = "0.1.1"
+version = "0.2.0"
description = "A lightweight bootloader supporting firmware updates in a power-fail-safe way, with trial boots and rollbacks."
license = "MIT OR Apache-2.0"
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-boot"
categories = [
"embedded",
"no-std",
@@ -12,8 +13,8 @@ categories = [
]
[package.metadata.embassy_docs]
-src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-v$VERSION/embassy-boot/boot/src/"
-src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot/boot/src/"
+src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-v$VERSION/embassy-boot/src/"
+src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-boot/src/"
target = "thumbv7em-none-eabi"
features = ["defmt"]
@@ -26,25 +27,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 }
-embassy-embedded-hal = { version = "0.1.0", path = "../../embassy-embedded-hal" }
-embassy-sync = { version = "0.5.0", path = "../../embassy-sync" }
+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"]
diff --git a/embassy-boot/README.md b/embassy-boot/README.md
new file mode 100644
index 000000000..3c2d45e96
--- /dev/null
+++ b/embassy-boot/README.md
@@ -0,0 +1,35 @@
+# embassy-boot
+
+An [Embassy](https://embassy.dev) project.
+
+A lightweight bootloader supporting firmware updates in a power-fail-safe way, with trial boots and rollbacks.
+
+The bootloader can be used either as a library or be flashed directly with the default configuration derived from linker scripts.
+
+By design, the bootloader does not provide any network capabilities. Networking capabilities for fetching new firmware can be provided by the user application, using the bootloader as a library for updating the firmware, or by using the bootloader as a library and adding this capability yourself.
+
+## Overview
+
+The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader instance or via linker scripts:
+
+* BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash, but if you need to debug it and have space available, increasing this to 24kB will allow you to run the bootloader with probe-rs.
+* ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. The minimum size required for this partition is the size of your application.
+* DFU - Where the application-to-be-swapped is placed. This partition is written to by the application. This partition must be at least 1 page bigger than the ACTIVE partition.
+* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped.
+
+For any partition, the following preconditions are required:
+
+* Partitions must be aligned on the page size.
+* Partitions must be a multiple of the page size.
+
+The linker scripts for the application and bootloader look similar, but the FLASH region must point to the BOOTLOADER partition for the bootloader, and the ACTIVE partition for the application.
+
+For more details on the bootloader, see [the documentation](https://embassy.dev/book/dev/bootloader.html).
+
+## Hardware support
+
+The bootloader supports different hardware in separate crates:
+
+* `embassy-boot-nrf` - for the nRF microcontrollers.
+* `embassy-boot-rp` - for the RP2040 microcontrollers.
+* `embassy-boot-stm32` - for the STM32 microcontrollers.
diff --git a/embassy-boot/boot/README.md b/embassy-boot/boot/README.md
deleted file mode 100644
index 07755bc6c..000000000
--- a/embassy-boot/boot/README.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# embassy-boot
-
-An [Embassy](https://embassy.dev) project.
-
-A lightweight bootloader supporting firmware updates in a power-fail-safe way, with trial boots and rollbacks.
-
-The bootloader can be used either as a library or be flashed directly with the default configuration derived from linker scripts.
-
-By design, the bootloader does not provide any network capabilities. Networking capabilities for fetching new firmware can be provided by the user application, using the bootloader as a library for updating the firmware, or by using the bootloader as a library and adding this capability yourself.
-
-## Hardware support
-
-The bootloader supports different hardware in separate crates:
-
-* `embassy-boot-nrf` - for the nRF microcontrollers.
-* `embassy-boot-rp` - for the RP2040 microcontrollers.
-* `embassy-boot-stm32` - for the STM32 microcontrollers.
-
-## Minimum supported Rust version (MSRV)
-
-`embassy-boot` is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
diff --git a/embassy-boot/nrf/README.md b/embassy-boot/nrf/README.md
deleted file mode 100644
index fe581823d..000000000
--- a/embassy-boot/nrf/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# embassy-boot-nrf
-
-An [Embassy](https://embassy.dev) project.
-
-An adaptation of `embassy-boot` for nRF.
-
-## Features
-
-* Load applications with or without the softdevice.
-* Configure bootloader partitions based on linker script.
-* Using watchdog timer to detect application failure.
-
-
-## Minimum supported Rust version (MSRV)
-
-`embassy-boot-nrf` 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
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
diff --git a/embassy-boot/rp/README.md b/embassy-boot/rp/README.md
deleted file mode 100644
index 315d655e3..000000000
--- a/embassy-boot/rp/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# embassy-boot-rp
-
-An [Embassy](https://embassy.dev) project.
-
-An adaptation of `embassy-boot` for RP2040.
-
-NOTE: The applications using this bootloader should not link with the `link-rp.x` linker script.
-
-## Features
-
-* Configure bootloader partitions based on linker script.
-* Load applications from active partition.
-
-## Minimum supported Rust version (MSRV)
-
-`embassy-boot-rp` 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
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
diff --git a/embassy-boot/boot/src/boot_loader.rs b/embassy-boot/src/boot_loader.rs
similarity index 77%
rename from embassy-boot/boot/src/boot_loader.rs
rename to embassy-boot/src/boot_loader.rs
index a8c19197b..a38558056 100644
--- a/embassy-boot/boot/src/boot_loader.rs
+++ b/embassy-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)]
@@ -49,16 +49,51 @@ pub struct BootLoaderConfig {
pub state: STATE,
}
-impl<'a, FLASH: NorFlash>
+impl<'a, ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash>
BootLoaderConfig<
- BlockingPartition<'a, NoopRawMutex, FLASH>,
- BlockingPartition<'a, NoopRawMutex, FLASH>,
- BlockingPartition<'a, NoopRawMutex, FLASH>,
+ BlockingPartition<'a, NoopRawMutex, ACTIVE>,
+ BlockingPartition<'a, NoopRawMutex, DFU>,
+ BlockingPartition<'a, NoopRawMutex, STATE>,
>
{
- /// Create a bootloader config from the flash and address symbols defined in the linkerfile
+ /// Constructs a `BootLoaderConfig` instance from flash memory and address symbols defined in the linker file.
+ ///
+ /// This method initializes `BlockingPartition` instances for the active, DFU (Device Firmware Update),
+ /// and state partitions, leveraging start and end addresses specified by the linker. These partitions
+ /// are critical for managing firmware updates, application state, and boot operations within the bootloader.
+ ///
+ /// # Parameters
+ /// - `active_flash`: A reference to a mutex-protected `RefCell` for the active partition's flash interface.
+ /// - `dfu_flash`: A reference to a mutex-protected `RefCell` for the DFU partition's flash interface.
+ /// - `state_flash`: A reference to a mutex-protected `RefCell` for the state partition's flash interface.
+ ///
+ /// # Safety
+ /// The method contains `unsafe` blocks for dereferencing raw pointers that represent the start and end addresses
+ /// of the bootloader's partitions in flash memory. It is crucial that these addresses are accurately defined
+ /// in the memory.x file to prevent undefined behavior.
+ ///
+ /// The caller must ensure that the memory regions defined by these symbols are valid and that the flash memory
+ /// interfaces provided are compatible with these regions.
+ ///
+ /// # Returns
+ /// A `BootLoaderConfig` instance with `BlockingPartition` instances for the active, DFU, and state partitions.
+ ///
+ /// # Example
+ /// ```ignore
+ /// // Assume `active_flash`, `dfu_flash`, and `state_flash` all share the same flash memory interface.
+ /// let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
+ /// let flash = Mutex::new(RefCell::new(layout.bank1_region));
+ ///
+ /// let config = BootLoaderConfig::from_linkerfile_blocking(&flash, &flash, &flash);
+ /// // `config` can now be used to create a `BootLoader` instance for managing boot operations.
+ /// ```
+ /// Working examples can be found in the bootloader examples folder.
// #[cfg(target_os = "none")]
- pub fn from_linkerfile_blocking(flash: &'a Mutex>) -> Self {
+ pub fn from_linkerfile_blocking(
+ active_flash: &'a Mutex>,
+ dfu_flash: &'a Mutex>,
+ state_flash: &'a Mutex>,
+ ) -> Self {
extern "C" {
static __bootloader_state_start: u32;
static __bootloader_state_end: u32;
@@ -73,21 +108,21 @@ impl<'a, FLASH: NorFlash>
let end = &__bootloader_active_end as *const u32 as u32;
trace!("ACTIVE: 0x{:x} - 0x{:x}", start, end);
- BlockingPartition::new(flash, start, end - start)
+ BlockingPartition::new(active_flash, start, end - start)
};
let dfu = unsafe {
let start = &__bootloader_dfu_start as *const u32 as u32;
let end = &__bootloader_dfu_end as *const u32 as u32;
trace!("DFU: 0x{:x} - 0x{:x}", start, end);
- BlockingPartition::new(flash, start, end - start)
+ BlockingPartition::new(dfu_flash, start, end - start)
};
let state = unsafe {
let start = &__bootloader_state_start as *const u32 as u32;
let end = &__bootloader_state_end as *const u32 as u32;
trace!("STATE: 0x{:x} - 0x{:x}", start, end);
- BlockingPartition::new(flash, start, end - start)
+ BlockingPartition::new(state_flash, start, end - start)
};
Self { active, dfu, state }
@@ -135,51 +170,44 @@ impl BootLoader BootLoader Result {
// Ensure we have enough progress pages to store copy progress
@@ -224,6 +245,7 @@ impl BootLoader BootLoader(
) {
assert_eq!(active.capacity() as u32 % page_size, 0);
assert_eq!(dfu.capacity() as u32 % page_size, 0);
+ // DFU partition has to be bigger than ACTIVE partition to handle swap algorithm
assert!(dfu.capacity() as u32 - active.capacity() as u32 >= page_size);
assert!(2 + 2 * (active.capacity() as u32 / page_size) <= state.capacity() as u32 / STATE::WRITE_SIZE as u32);
}
diff --git a/embassy-boot/boot/src/digest_adapters/ed25519_dalek.rs b/embassy-boot/src/digest_adapters/ed25519_dalek.rs
similarity index 89%
rename from embassy-boot/boot/src/digest_adapters/ed25519_dalek.rs
rename to embassy-boot/src/digest_adapters/ed25519_dalek.rs
index a184d1c51..2e4e03da3 100644
--- a/embassy-boot/boot/src/digest_adapters/ed25519_dalek.rs
+++ b/embassy-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)
}
}
diff --git a/embassy-boot/boot/src/digest_adapters/mod.rs b/embassy-boot/src/digest_adapters/mod.rs
similarity index 100%
rename from embassy-boot/boot/src/digest_adapters/mod.rs
rename to embassy-boot/src/digest_adapters/mod.rs
diff --git a/embassy-boot/boot/src/digest_adapters/salty.rs b/embassy-boot/src/digest_adapters/salty.rs
similarity index 100%
rename from embassy-boot/boot/src/digest_adapters/salty.rs
rename to embassy-boot/src/digest_adapters/salty.rs
diff --git a/embassy-boot/boot/src/firmware_updater/asynch.rs b/embassy-boot/src/firmware_updater/asynch.rs
similarity index 53%
rename from embassy-boot/boot/src/firmware_updater/asynch.rs
rename to embassy-boot/src/firmware_updater/asynch.rs
index ae713bb6f..26f65f295 100644
--- a/embassy-boot/boot/src/firmware_updater/asynch.rs
+++ b/embassy-boot/src/firmware_updater/asynch.rs
@@ -6,21 +6,25 @@ 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
pub struct FirmwareUpdater<'d, DFU: NorFlash, STATE: NorFlash> {
dfu: DFU,
state: FirmwareState<'d, STATE>,
+ last_erased_dfu_sector_index: Option,
}
#[cfg(target_os = "none")]
-impl<'a, FLASH: NorFlash>
- FirmwareUpdaterConfig, Partition<'a, NoopRawMutex, FLASH>>
+impl<'a, DFU: NorFlash, STATE: NorFlash>
+ FirmwareUpdaterConfig, Partition<'a, NoopRawMutex, STATE>>
{
/// Create a firmware updater config from the flash and address symbols defined in the linkerfile
- pub fn from_linkerfile(flash: &'a embassy_sync::mutex::Mutex) -> Self {
+ pub fn from_linkerfile(
+ dfu_flash: &'a embassy_sync::mutex::Mutex,
+ state_flash: &'a embassy_sync::mutex::Mutex,
+ ) -> Self {
extern "C" {
static __bootloader_state_start: u32;
static __bootloader_state_end: u32;
@@ -33,14 +37,14 @@ impl<'a, FLASH: NorFlash>
let end = &__bootloader_dfu_end as *const u32 as u32;
trace!("DFU: 0x{:x} - 0x{:x}", start, end);
- Partition::new(flash, start, end - start)
+ Partition::new(dfu_flash, start, end - start)
};
let state = unsafe {
let start = &__bootloader_state_start as *const u32 as u32;
let end = &__bootloader_state_end as *const u32 as u32;
trace!("STATE: 0x{:x} - 0x{:x}", start, end);
- Partition::new(flash, start, end - start)
+ Partition::new(state_flash, start, end - start)
};
Self { dfu, state }
@@ -53,6 +57,7 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
Self {
dfu: config.dfu,
state: FirmwareState::new(config.state, aligned),
+ last_erased_dfu_sector_index: None,
}
}
@@ -69,7 +74,7 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
/// proceed with updating the firmware as it must be signed with a
/// corresponding private key (otherwise it could be malicious firmware).
///
- /// Mark to trigger firmware swap on next boot if verify suceeds.
+ /// Mark to trigger firmware swap on next boot if verify succeeds.
///
/// If the "ed25519-salty" feature is set (or another similar feature) then the signature is expected to have
/// been generated from a SHA-512 digest of the firmware bytes.
@@ -79,8 +84,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 +94,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 +111,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 +119,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,26 +163,79 @@ 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
}
- /// Write data to a flash page.
+ /// Writes firmware data to the device.
///
- /// The buffer must follow alignment requirements of the target flash and a multiple of page size big.
+ /// This function writes the given data to the firmware area starting at the specified offset.
+ /// It handles sector erasures and data writes while verifying the device is in a proper state
+ /// for firmware updates. The function ensures that only unerased sectors are erased before
+ /// writing and efficiently handles the writing process across sector boundaries and in
+ /// various configurations (data size, sector size, etc.).
///
- /// # Safety
+ /// # Arguments
///
- /// Failing to meet alignment and size requirements may result in a panic.
+ /// * `offset` - The starting offset within the firmware area where data writing should begin.
+ /// * `data` - A slice of bytes representing the firmware data to be written. It must be a
+ /// multiple of NorFlash WRITE_SIZE.
+ ///
+ /// # Returns
+ ///
+ /// A `Result<(), FirmwareUpdaterError>` indicating the success or failure of the write operation.
+ ///
+ /// # Errors
+ ///
+ /// This function will return an error if:
+ ///
+ /// - The device is not in a proper state to receive firmware updates (e.g., not booted).
+ /// - There is a failure erasing a sector before writing.
+ /// - There is a failure writing data to the device.
pub async fn write_firmware(&mut self, offset: usize, data: &[u8]) -> Result<(), FirmwareUpdaterError> {
- assert!(data.len() >= DFU::ERASE_SIZE);
-
+ // Make sure we are running a booted firmware to avoid reverting to a bad state.
self.state.verify_booted().await?;
- self.dfu.erase(offset as u32, (offset + data.len()) as u32).await?;
+ // Initialize variables to keep track of the remaining data and the current offset.
+ let mut remaining_data = data;
+ let mut offset = offset;
- self.dfu.write(offset as u32, data).await?;
+ // Continue writing as long as there is data left to write.
+ while !remaining_data.is_empty() {
+ // Compute the current sector and its boundaries.
+ let current_sector = offset / DFU::ERASE_SIZE;
+ let sector_start = current_sector * DFU::ERASE_SIZE;
+ let sector_end = sector_start + DFU::ERASE_SIZE;
+ // Determine if the current sector needs to be erased before writing.
+ let need_erase = self
+ .last_erased_dfu_sector_index
+ .map_or(true, |last_erased_sector| current_sector != last_erased_sector);
+
+ // If the sector needs to be erased, erase it and update the last erased sector index.
+ if need_erase {
+ self.dfu.erase(sector_start as u32, sector_end as u32).await?;
+ self.last_erased_dfu_sector_index = Some(current_sector);
+ }
+
+ // Calculate the size of the data chunk that can be written in the current iteration.
+ let write_size = core::cmp::min(remaining_data.len(), sector_end - offset);
+ // Split the data to get the current chunk to be written and the remaining data.
+ let (data_chunk, rest) = remaining_data.split_at(write_size);
+
+ // Write the current data chunk.
+ self.dfu.write(offset as u32, data_chunk).await?;
+
+ // Update the offset and remaining data for the next iteration.
+ remaining_data = rest;
+ offset += write_size;
+ }
Ok(())
}
@@ -207,14 +262,24 @@ pub struct FirmwareState<'d, STATE> {
}
impl<'d, STATE: NorFlash> FirmwareState<'d, STATE> {
- /// Create a firmware state instance with a buffer for magic content and state partition.
+ /// 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(config: FirmwareUpdaterConfig, 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
+ ///
+ /// The `aligned` buffer must have a size of maximum of STATE::WRITE_SIZE and STATE::READ_SIZE,
+ /// and follow the alignment rules for the flash being read from and written to.
pub fn new(state: STATE, aligned: &'d mut [u8]) -> Self {
- assert_eq!(aligned.len(), STATE::WRITE_SIZE);
+ assert_eq!(aligned.len(), STATE::WRITE_SIZE.max(STATE::READ_SIZE));
Self { state, aligned }
}
@@ -247,6 +312,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
@@ -255,16 +325,25 @@ impl<'d, STATE: NorFlash> FirmwareState<'d, STATE> {
async fn set_magic(&mut self, magic: u8) -> Result<(), FirmwareUpdaterError> {
self.state.read(0, &mut self.aligned).await?;
- if self.aligned.iter().any(|&b| b != magic) {
+ if self.aligned[..STATE::WRITE_SIZE].iter().any(|&b| b != magic) {
// Read progress validity
- self.state.read(STATE::WRITE_SIZE as u32, &mut self.aligned).await?;
+ if STATE::READ_SIZE <= 2 * STATE::WRITE_SIZE {
+ self.state.read(STATE::WRITE_SIZE as u32, &mut self.aligned).await?;
+ } else {
+ self.aligned.rotate_left(STATE::WRITE_SIZE);
+ }
- if self.aligned.iter().any(|&b| b != STATE_ERASE_VALUE) {
+ if self.aligned[..STATE::WRITE_SIZE]
+ .iter()
+ .any(|&b| b != STATE_ERASE_VALUE)
+ {
// The current progress validity marker is invalid
} else {
// Invalidate progress
self.aligned.fill(!STATE_ERASE_VALUE);
- self.state.write(STATE::WRITE_SIZE as u32, &self.aligned).await?;
+ self.state
+ .write(STATE::WRITE_SIZE as u32, &self.aligned[..STATE::WRITE_SIZE])
+ .await?;
}
// Clear magic and progress
@@ -272,7 +351,7 @@ impl<'d, STATE: NorFlash> FirmwareState<'d, STATE> {
// Set magic
self.aligned.fill(magic);
- self.state.write(0, &self.aligned).await?;
+ self.state.write(0, &self.aligned[..STATE::WRITE_SIZE]).await?;
}
Ok(())
}
@@ -308,4 +387,76 @@ mod tests {
assert_eq!(Sha1::digest(update).as_slice(), hash);
}
+
+ #[test]
+ fn can_verify_sha1_sector_bigger_than_chunk() {
+ let flash = Mutex::::new(MemFlash::<131072, 4096, 8>::default());
+ let state = Partition::new(&flash, 0, 4096);
+ let dfu = Partition::new(&flash, 65536, 65536);
+ let mut aligned = [0; 8];
+
+ let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
+ let mut to_write = [0; 4096];
+ to_write[..7].copy_from_slice(update.as_slice());
+
+ let mut updater = FirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
+ let mut offset = 0;
+ for chunk in to_write.chunks(1024) {
+ block_on(updater.write_firmware(offset, chunk)).unwrap();
+ offset += chunk.len();
+ }
+ let mut chunk_buf = [0; 2];
+ let mut hash = [0; 20];
+ block_on(updater.hash::(update.len() as u32, &mut chunk_buf, &mut hash)).unwrap();
+
+ assert_eq!(Sha1::digest(update).as_slice(), hash);
+ }
+
+ #[test]
+ fn can_verify_sha1_sector_smaller_than_chunk() {
+ let flash = Mutex::::new(MemFlash::<131072, 1024, 8>::default());
+ let state = Partition::new(&flash, 0, 4096);
+ let dfu = Partition::new(&flash, 65536, 65536);
+ let mut aligned = [0; 8];
+
+ let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
+ let mut to_write = [0; 4096];
+ to_write[..7].copy_from_slice(update.as_slice());
+
+ let mut updater = FirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
+ let mut offset = 0;
+ for chunk in to_write.chunks(2048) {
+ block_on(updater.write_firmware(offset, chunk)).unwrap();
+ offset += chunk.len();
+ }
+ let mut chunk_buf = [0; 2];
+ let mut hash = [0; 20];
+ block_on(updater.hash::(update.len() as u32, &mut chunk_buf, &mut hash)).unwrap();
+
+ assert_eq!(Sha1::digest(update).as_slice(), hash);
+ }
+
+ #[test]
+ fn can_verify_sha1_cross_sector_boundary() {
+ let flash = Mutex::::new(MemFlash::<131072, 1024, 8>::default());
+ let state = Partition::new(&flash, 0, 4096);
+ let dfu = Partition::new(&flash, 65536, 65536);
+ let mut aligned = [0; 8];
+
+ let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
+ let mut to_write = [0; 4096];
+ to_write[..7].copy_from_slice(update.as_slice());
+
+ let mut updater = FirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
+ let mut offset = 0;
+ for chunk in to_write.chunks(896) {
+ block_on(updater.write_firmware(offset, chunk)).unwrap();
+ offset += chunk.len();
+ }
+ let mut chunk_buf = [0; 2];
+ let mut hash = [0; 20];
+ block_on(updater.hash::(update.len() as u32, &mut chunk_buf, &mut hash)).unwrap();
+
+ assert_eq!(Sha1::digest(update).as_slice(), hash);
+ }
}
diff --git a/embassy-boot/boot/src/firmware_updater/blocking.rs b/embassy-boot/src/firmware_updater/blocking.rs
similarity index 50%
rename from embassy-boot/boot/src/firmware_updater/blocking.rs
rename to embassy-boot/src/firmware_updater/blocking.rs
index 76e4264a0..35772a856 100644
--- a/embassy-boot/boot/src/firmware_updater/blocking.rs
+++ b/embassy-boot/src/firmware_updater/blocking.rs
@@ -6,22 +6,54 @@ 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
pub struct BlockingFirmwareUpdater<'d, DFU: NorFlash, STATE: NorFlash> {
dfu: DFU,
state: BlockingFirmwareState<'d, STATE>,
+ last_erased_dfu_sector_index: Option,
}
#[cfg(target_os = "none")]
-impl<'a, FLASH: NorFlash>
- FirmwareUpdaterConfig, BlockingPartition<'a, NoopRawMutex, FLASH>>
+impl<'a, DFU: NorFlash, STATE: NorFlash>
+ FirmwareUpdaterConfig, BlockingPartition<'a, NoopRawMutex, STATE>>
{
- /// Create a firmware updater config from the flash and address symbols defined in the linkerfile
+ /// Constructs a `FirmwareUpdaterConfig` instance from flash memory and address symbols defined in the linker file.
+ ///
+ /// This method initializes `BlockingPartition` instances for the DFU (Device Firmware Update), and state
+ /// partitions, leveraging start and end addresses specified by the linker. These partitions are critical
+ /// for managing firmware updates, application state, and boot operations within the bootloader.
+ ///
+ /// # Parameters
+ /// - `dfu_flash`: A reference to a mutex-protected `RefCell` for the DFU partition's flash interface.
+ /// - `state_flash`: A reference to a mutex-protected `RefCell` for the state partition's flash interface.
+ ///
+ /// # Safety
+ /// The method contains `unsafe` blocks for dereferencing raw pointers that represent the start and end addresses
+ /// of the bootloader's partitions in flash memory. It is crucial that these addresses are accurately defined
+ /// in the memory.x file to prevent undefined behavior.
+ ///
+ /// The caller must ensure that the memory regions defined by these symbols are valid and that the flash memory
+ /// interfaces provided are compatible with these regions.
+ ///
+ /// # Returns
+ /// A `FirmwareUpdaterConfig` instance with `BlockingPartition` instances for the DFU, and state partitions.
+ ///
+ /// # Example
+ /// ```ignore
+ /// // Assume `dfu_flash`, and `state_flash` share the same flash memory interface.
+ /// let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
+ /// let flash = Mutex::new(RefCell::new(layout.bank1_region));
+ ///
+ /// let config = FirmwareUpdaterConfig::from_linkerfile_blocking(&flash, &flash);
+ /// // `config` can now be used to create a `FirmwareUpdater` instance for managing boot operations.
+ /// ```
+ /// Working examples can be found in the bootloader examples folder.
pub fn from_linkerfile_blocking(
- flash: &'a embassy_sync::blocking_mutex::Mutex>,
+ dfu_flash: &'a embassy_sync::blocking_mutex::Mutex>,
+ state_flash: &'a embassy_sync::blocking_mutex::Mutex>,
) -> Self {
extern "C" {
static __bootloader_state_start: u32;
@@ -35,14 +67,14 @@ impl<'a, FLASH: NorFlash>
let end = &__bootloader_dfu_end as *const u32 as u32;
trace!("DFU: 0x{:x} - 0x{:x}", start, end);
- BlockingPartition::new(flash, start, end - start)
+ BlockingPartition::new(dfu_flash, start, end - start)
};
let state = unsafe {
let start = &__bootloader_state_start as *const u32 as u32;
let end = &__bootloader_state_end as *const u32 as u32;
trace!("STATE: 0x{:x} - 0x{:x}", start, end);
- BlockingPartition::new(flash, start, end - start)
+ BlockingPartition::new(state_flash, start, end - start)
};
Self { dfu, state }
@@ -60,6 +92,7 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
Self {
dfu: config.dfu,
state: BlockingFirmwareState::new(config.state, aligned),
+ last_erased_dfu_sector_index: None,
}
}
@@ -76,7 +109,7 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
/// proceed with updating the firmware as it must be signed with a
/// corresponding private key (otherwise it could be malicious firmware).
///
- /// Mark to trigger firmware swap on next boot if verify suceeds.
+ /// Mark to trigger firmware swap on next boot if verify succeeds.
///
/// If the "ed25519-salty" feature is set (or another similar feature) then the signature is expected to have
/// been generated from a SHA-512 digest of the firmware bytes.
@@ -86,8 +119,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 +129,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 +146,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 +154,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,25 +198,79 @@ 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()
}
- /// Write data to a flash page.
+ /// Writes firmware data to the device.
///
- /// The buffer must follow alignment requirements of the target flash and a multiple of page size big.
+ /// This function writes the given data to the firmware area starting at the specified offset.
+ /// It handles sector erasures and data writes while verifying the device is in a proper state
+ /// for firmware updates. The function ensures that only unerased sectors are erased before
+ /// writing and efficiently handles the writing process across sector boundaries and in
+ /// various configurations (data size, sector size, etc.).
///
- /// # Safety
+ /// # Arguments
///
- /// Failing to meet alignment and size requirements may result in a panic.
+ /// * `offset` - The starting offset within the firmware area where data writing should begin.
+ /// * `data` - A slice of bytes representing the firmware data to be written. It must be a
+ /// multiple of NorFlash WRITE_SIZE.
+ ///
+ /// # Returns
+ ///
+ /// A `Result<(), FirmwareUpdaterError>` indicating the success or failure of the write operation.
+ ///
+ /// # Errors
+ ///
+ /// This function will return an error if:
+ ///
+ /// - The device is not in a proper state to receive firmware updates (e.g., not booted).
+ /// - There is a failure erasing a sector before writing.
+ /// - There is a failure writing data to the device.
pub fn write_firmware(&mut self, offset: usize, data: &[u8]) -> Result<(), FirmwareUpdaterError> {
- assert!(data.len() >= DFU::ERASE_SIZE);
+ // Make sure we are running a booted firmware to avoid reverting to a bad state.
self.state.verify_booted()?;
- self.dfu.erase(offset as u32, (offset + data.len()) as u32)?;
+ // Initialize variables to keep track of the remaining data and the current offset.
+ let mut remaining_data = data;
+ let mut offset = offset;
- self.dfu.write(offset as u32, data)?;
+ // Continue writing as long as there is data left to write.
+ while !remaining_data.is_empty() {
+ // Compute the current sector and its boundaries.
+ let current_sector = offset / DFU::ERASE_SIZE;
+ let sector_start = current_sector * DFU::ERASE_SIZE;
+ let sector_end = sector_start + DFU::ERASE_SIZE;
+ // Determine if the current sector needs to be erased before writing.
+ let need_erase = self
+ .last_erased_dfu_sector_index
+ .map_or(true, |last_erased_sector| current_sector != last_erased_sector);
+
+ // If the sector needs to be erased, erase it and update the last erased sector index.
+ if need_erase {
+ self.dfu.erase(sector_start as u32, sector_end as u32)?;
+ self.last_erased_dfu_sector_index = Some(current_sector);
+ }
+
+ // Calculate the size of the data chunk that can be written in the current iteration.
+ let write_size = core::cmp::min(remaining_data.len(), sector_end - offset);
+ // Split the data to get the current chunk to be written and the remaining data.
+ let (data_chunk, rest) = remaining_data.split_at(write_size);
+
+ // Write the current data chunk.
+ self.dfu.write(offset as u32, data_chunk)?;
+
+ // Update the offset and remaining data for the next iteration.
+ remaining_data = rest;
+ offset += write_size;
+ }
Ok(())
}
@@ -213,6 +297,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(config: FirmwareUpdaterConfig, 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 +320,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 +337,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 +349,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)
@@ -317,4 +418,82 @@ mod tests {
assert_eq!(Sha1::digest(update).as_slice(), hash);
}
+
+ #[test]
+ fn can_verify_sha1_sector_bigger_than_chunk() {
+ let flash = Mutex::::new(RefCell::new(MemFlash::<131072, 4096, 8>::default()));
+ let state = BlockingPartition::new(&flash, 0, 4096);
+ let dfu = BlockingPartition::new(&flash, 65536, 65536);
+ let mut aligned = [0; 8];
+
+ let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
+ let mut to_write = [0; 4096];
+ to_write[..7].copy_from_slice(update.as_slice());
+
+ let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
+ let mut offset = 0;
+ for chunk in to_write.chunks(1024) {
+ updater.write_firmware(offset, chunk).unwrap();
+ offset += chunk.len();
+ }
+ let mut chunk_buf = [0; 2];
+ let mut hash = [0; 20];
+ updater
+ .hash::(update.len() as u32, &mut chunk_buf, &mut hash)
+ .unwrap();
+
+ assert_eq!(Sha1::digest(update).as_slice(), hash);
+ }
+
+ #[test]
+ fn can_verify_sha1_sector_smaller_than_chunk() {
+ let flash = Mutex::::new(RefCell::new(MemFlash::<131072, 1024, 8>::default()));
+ let state = BlockingPartition::new(&flash, 0, 4096);
+ let dfu = BlockingPartition::new(&flash, 65536, 65536);
+ let mut aligned = [0; 8];
+
+ let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
+ let mut to_write = [0; 4096];
+ to_write[..7].copy_from_slice(update.as_slice());
+
+ let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
+ let mut offset = 0;
+ for chunk in to_write.chunks(2048) {
+ updater.write_firmware(offset, chunk).unwrap();
+ offset += chunk.len();
+ }
+ let mut chunk_buf = [0; 2];
+ let mut hash = [0; 20];
+ updater
+ .hash::(update.len() as u32, &mut chunk_buf, &mut hash)
+ .unwrap();
+
+ assert_eq!(Sha1::digest(update).as_slice(), hash);
+ }
+
+ #[test]
+ fn can_verify_sha1_cross_sector_boundary() {
+ let flash = Mutex::::new(RefCell::new(MemFlash::<131072, 1024, 8>::default()));
+ let state = BlockingPartition::new(&flash, 0, 4096);
+ let dfu = BlockingPartition::new(&flash, 65536, 65536);
+ let mut aligned = [0; 8];
+
+ let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
+ let mut to_write = [0; 4096];
+ to_write[..7].copy_from_slice(update.as_slice());
+
+ let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
+ let mut offset = 0;
+ for chunk in to_write.chunks(896) {
+ updater.write_firmware(offset, chunk).unwrap();
+ offset += chunk.len();
+ }
+ let mut chunk_buf = [0; 2];
+ let mut hash = [0; 20];
+ updater
+ .hash::(update.len() as u32, &mut chunk_buf, &mut hash)
+ .unwrap();
+
+ assert_eq!(Sha1::digest(update).as_slice(), hash);
+ }
}
diff --git a/embassy-boot/boot/src/firmware_updater/mod.rs b/embassy-boot/src/firmware_updater/mod.rs
similarity index 93%
rename from embassy-boot/boot/src/firmware_updater/mod.rs
rename to embassy-boot/src/firmware_updater/mod.rs
index 4814786bf..4c4f4f10b 100644
--- a/embassy-boot/boot/src/firmware_updater/mod.rs
+++ b/embassy-boot/src/firmware_updater/mod.rs
@@ -8,7 +8,7 @@ use embedded_storage::nor_flash::{NorFlashError, NorFlashErrorKind};
/// Firmware updater flash configuration holding the two flashes used by the updater
///
/// If only a single flash is actually used, then that flash should be partitioned into two partitions before use.
-/// The easiest way to do this is to use [`FirmwareUpdaterConfig::from_linkerfile`] or [`FirmwareUpdaterConfig::from_linkerfile_blocking`] which will partition
+/// The easiest way to do this is to use [`FirmwareUpdaterConfig::from_linkerfile_blocking`] or [`FirmwareUpdaterConfig::from_linkerfile_blocking`] which will partition
/// the provided flash according to symbols defined in the linkerfile.
pub struct FirmwareUpdaterConfig {
/// The dfu flash partition
diff --git a/embassy-boot/boot/src/fmt.rs b/embassy-boot/src/fmt.rs
similarity index 99%
rename from embassy-boot/boot/src/fmt.rs
rename to embassy-boot/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-boot/boot/src/fmt.rs
+++ b/embassy-boot/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-boot/boot/src/lib.rs b/embassy-boot/src/lib.rs
similarity index 96%
rename from embassy-boot/boot/src/lib.rs
rename to embassy-boot/src/lib.rs
index 9e70a4dca..b4f03e01e 100644
--- a/embassy-boot/boot/src/lib.rs
+++ b/embassy-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 {
diff --git a/embassy-boot/boot/src/mem_flash.rs b/embassy-boot/src/mem_flash.rs
similarity index 100%
rename from embassy-boot/boot/src/mem_flash.rs
rename to embassy-boot/src/mem_flash.rs
diff --git a/embassy-boot/boot/src/test_flash/asynch.rs b/embassy-boot/src/test_flash/asynch.rs
similarity index 100%
rename from embassy-boot/boot/src/test_flash/asynch.rs
rename to embassy-boot/src/test_flash/asynch.rs
diff --git a/embassy-boot/boot/src/test_flash/blocking.rs b/embassy-boot/src/test_flash/blocking.rs
similarity index 100%
rename from embassy-boot/boot/src/test_flash/blocking.rs
rename to embassy-boot/src/test_flash/blocking.rs
diff --git a/embassy-boot/boot/src/test_flash/mod.rs b/embassy-boot/src/test_flash/mod.rs
similarity index 100%
rename from embassy-boot/boot/src/test_flash/mod.rs
rename to embassy-boot/src/test_flash/mod.rs
diff --git a/embassy-boot/stm32/README.md b/embassy-boot/stm32/README.md
deleted file mode 100644
index b4d7ba5a4..000000000
--- a/embassy-boot/stm32/README.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# embassy-boot-stm32
-
-An [Embassy](https://embassy.dev) project.
-
-An adaptation of `embassy-boot` for STM32.
-
-## Features
-
-* Configure bootloader partitions based on linker script.
-* Load applications from active partition.
-
-## Minimum supported Rust version (MSRV)
-
-`embassy-boot-stm32` 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
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
diff --git a/embassy-embedded-hal/Cargo.toml b/embassy-embedded-hal/Cargo.toml
index 2a0b25479..e89179740 100644
--- a/embassy-embedded-hal/Cargo.toml
+++ b/embassy-embedded-hal/Cargo.toml
@@ -3,7 +3,14 @@ name = "embassy-embedded-hal"
version = "0.1.0"
edition = "2021"
license = "MIT OR Apache-2.0"
-
+description = "Collection of utilities to use `embedded-hal` and `embedded-storage` traits with Embassy."
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-embedded-hal"
+categories = [
+ "embedded",
+ "no-std",
+ "asynchronous",
+]
[package.metadata.embassy_docs]
src_base = "https://github.com/embassy-rs/embassy/blob/embassy-embedded-hal-v$VERSION/embassy-embedded-hal/src/"
@@ -11,6 +18,9 @@ src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-embed
features = ["std"]
target = "x86_64-unknown-linux-gnu"
+[package.metadata.docs.rs]
+features = ["std"]
+
[features]
std = []
time = ["dep:embassy-time"]
@@ -19,12 +29,12 @@ default = ["time"]
[dependencies]
embassy-futures = { version = "0.1.0", path = "../embassy-futures" }
embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
-embassy-time = { version = "0.2", path = "../embassy-time", optional = true }
+embassy-time = { version = "0.3.0", 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" }
+embedded-hal-async = { version = "1.0" }
embedded-storage = "0.3.1"
embedded-storage-async = { version = "0.4.1" }
nb = "1.0.0"
diff --git a/embassy-embedded-hal/README.md b/embassy-embedded-hal/README.md
new file mode 100644
index 000000000..69581c788
--- /dev/null
+++ b/embassy-embedded-hal/README.md
@@ -0,0 +1,12 @@
+# embassy-embedded-hal
+
+Collection of utilities to use `embedded-hal` and `embedded-storage` traits with Embassy.
+
+- Shared SPI and I2C buses, both blocking and async, with a `SetConfig` trait allowing changing bus configuration (e.g. frequency) between devices on the same bus.
+- Async utilities
+ - Adapters to convert from blocking to (fake) async.
+ - Adapters to insert yields on trait operations.
+- Flash utilities
+ - Split a flash memory into smaller partitions.
+ - Concatenate flash memories together.
+ - Simulated in-memory flash.
diff --git a/embassy-embedded-hal/build.rs b/embassy-embedded-hal/build.rs
deleted file mode 100644
index 78bd27ec7..000000000
--- a/embassy-embedded-hal/build.rs
+++ /dev/null
@@ -1,18 +0,0 @@
-use std::env;
-use std::ffi::OsString;
-use std::process::Command;
-
-fn main() {
- println!("cargo:rerun-if-changed=build.rs");
-
- let rustc = env::var_os("RUSTC").unwrap_or_else(|| OsString::from("rustc"));
-
- let output = Command::new(rustc)
- .arg("--version")
- .output()
- .expect("failed to run `rustc --version`");
-
- if String::from_utf8_lossy(&output.stdout).contains("nightly") {
- println!("cargo:rustc-cfg=nightly");
- }
-}
diff --git a/embassy-embedded-hal/src/adapter/blocking_async.rs b/embassy-embedded-hal/src/adapter/blocking_async.rs
index ae0d0a7f9..bafc31583 100644
--- a/embassy-embedded-hal/src/adapter/blocking_async.rs
+++ b/embassy-embedded-hal/src/adapter/blocking_async.rs
@@ -104,8 +104,10 @@ where
}
/// NOR flash wrapper
-use embedded_storage::nor_flash::{ErrorType, NorFlash, ReadNorFlash};
-use embedded_storage_async::nor_flash::{NorFlash as AsyncNorFlash, ReadNorFlash as AsyncReadNorFlash};
+use embedded_storage::nor_flash::{ErrorType, MultiwriteNorFlash, NorFlash, ReadNorFlash};
+use embedded_storage_async::nor_flash::{
+ MultiwriteNorFlash as AsyncMultiwriteNorFlash, NorFlash as AsyncNorFlash, ReadNorFlash as AsyncReadNorFlash,
+};
impl ErrorType for BlockingAsync
where
@@ -143,3 +145,5 @@ where
self.wrapped.capacity()
}
}
+
+impl AsyncMultiwriteNorFlash for BlockingAsync where T: MultiwriteNorFlash {}
diff --git a/embassy-embedded-hal/src/lib.rs b/embassy-embedded-hal/src/lib.rs
index b40f892f4..99a2d93c7 100644
--- a/embassy-embedded-hal/src/lib.rs
+++ b/embassy-embedded-hal/src/lib.rs
@@ -1,10 +1,7 @@
#![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(nightly, feature(async_fn_in_trait, impl_trait_projections))]
-#![cfg_attr(nightly, allow(stable_features, unknown_lints))]
#![allow(async_fn_in_trait)]
#![warn(missing_docs)]
-
-//! Utilities to use `embedded-hal` traits with Embassy.
+#![doc = include_str!("../README.md")]
pub mod adapter;
pub mod flash;
diff --git a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
index 779c04263..71ce09def 100644
--- a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
+++ b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
@@ -106,6 +106,11 @@ impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> {
pub fn new(bus: &'a Mutex, config: BUS::Config) -> Self {
Self { bus, config }
}
+
+ /// Change the device's config at runtime
+ pub fn set_config(&mut self, config: BUS::Config) {
+ self.config = config;
+ }
}
impl<'a, M, BUS> i2c::ErrorType for I2cDeviceWithConfig<'a, M, BUS>
diff --git a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
index 62b2c92a0..9890f218d 100644
--- a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
+++ b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
@@ -122,6 +122,11 @@ impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> {
pub fn new(bus: &'a Mutex, cs: CS, config: BUS::Config) -> Self {
Self { bus, cs, config }
}
+
+ /// Change the device's config at runtime
+ pub fn set_config(&mut self, config: BUS::Config) {
+ self.config = config;
+ }
}
impl<'a, M, BUS, CS> spi::ErrorType for SpiDeviceWithConfig<'a, M, BUS, CS>
diff --git a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
index 233c9e1fd..627767c8a 100644
--- a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
+++ b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
@@ -67,9 +67,11 @@ where
}
fn transaction<'a>(&mut self, address: u8, operations: &mut [Operation<'a>]) -> Result<(), Self::Error> {
- let _ = address;
- let _ = operations;
- todo!()
+ self.bus.lock(|bus| {
+ bus.borrow_mut()
+ .transaction(address, operations)
+ .map_err(I2cDeviceError::I2c)
+ })
}
}
@@ -130,6 +132,11 @@ impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> {
pub fn new(bus: &'a Mutex>, config: BUS::Config) -> Self {
Self { bus, config }
}
+
+ /// Change the device's config at runtime
+ pub fn set_config(&mut self, config: BUS::Config) {
+ self.config = config;
+ }
}
impl<'a, M, BUS> ErrorType for I2cDeviceWithConfig<'a, M, BUS>
@@ -171,8 +178,10 @@ where
}
fn transaction<'a>(&mut self, address: u8, operations: &mut [Operation<'a>]) -> Result<(), Self::Error> {
- let _ = address;
- let _ = operations;
- todo!()
+ self.bus.lock(|bus| {
+ let mut bus = bus.borrow_mut();
+ bus.set_config(&self.config).map_err(|_| I2cDeviceError::Config)?;
+ bus.transaction(address, operations).map_err(I2cDeviceError::I2c)
+ })
}
}
diff --git a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
index 59b65bfbd..801899f9f 100644
--- a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
+++ b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
@@ -147,6 +147,11 @@ impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> {
pub fn new(bus: &'a Mutex>, cs: CS, config: BUS::Config) -> Self {
Self { bus, cs, config }
}
+
+ /// Change the device's config at runtime
+ pub fn set_config(&mut self, config: BUS::Config) {
+ self.config = config;
+ }
}
impl<'a, M, BUS, CS> spi::ErrorType for SpiDeviceWithConfig<'a, M, BUS, CS>
diff --git a/embassy-executor-macros/Cargo.toml b/embassy-executor-macros/Cargo.toml
index 6ea7ddb71..2953e7ccc 100644
--- a/embassy-executor-macros/Cargo.toml
+++ b/embassy-executor-macros/Cargo.toml
@@ -1,10 +1,11 @@
[package]
name = "embassy-executor-macros"
-version = "0.4.0"
+version = "0.4.1"
edition = "2021"
license = "MIT OR Apache-2.0"
description = "macros for creating the entry point and tasks for embassy-executor"
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-executor-macros"
categories = [
"embedded",
"no-std",
@@ -21,4 +22,4 @@ proc-macro2 = "1.0.29"
proc-macro = true
[features]
-nightly = []
\ No newline at end of file
+nightly = []
diff --git a/embassy-executor-macros/README.md b/embassy-executor-macros/README.md
index a959c85d5..3a8d49aa1 100644
--- a/embassy-executor-macros/README.md
+++ b/embassy-executor-macros/README.md
@@ -3,13 +3,3 @@
An [Embassy](https://embassy.dev) project.
NOTE: Do not use this crate directly. The macros are re-exported by `embassy-executor`.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
diff --git a/embassy-executor-macros/src/lib.rs b/embassy-executor-macros/src/lib.rs
index c9d58746a..5461fe04c 100644
--- a/embassy-executor-macros/src/lib.rs
+++ b/embassy-executor-macros/src/lib.rs
@@ -62,6 +62,13 @@ pub fn task(args: TokenStream, item: TokenStream) -> TokenStream {
task::run(&args.meta, f).unwrap_or_else(|x| x).into()
}
+#[proc_macro_attribute]
+pub fn main_avr(args: TokenStream, item: TokenStream) -> TokenStream {
+ let args = syn::parse_macro_input!(args as Args);
+ let f = syn::parse_macro_input!(item as syn::ItemFn);
+ main::run(&args.meta, f, main::avr()).unwrap_or_else(|x| x).into()
+}
+
/// Creates a new `executor` instance and declares an application entry point for Cortex-M spawning the corresponding function body as an async task.
///
/// The following restrictions apply:
diff --git a/embassy-executor-macros/src/macros/main.rs b/embassy-executor-macros/src/macros/main.rs
index 3c0d58567..088e64d1c 100644
--- a/embassy-executor-macros/src/macros/main.rs
+++ b/embassy-executor-macros/src/macros/main.rs
@@ -12,6 +12,20 @@ struct Args {
entry: Option,
}
+pub fn avr() -> TokenStream {
+ quote! {
+ #[avr_device::entry]
+ fn main() -> ! {
+ let mut executor = ::embassy_executor::Executor::new();
+ let executor = unsafe { __make_static(&mut executor) };
+
+ executor.run(|spawner| {
+ spawner.must_spawn(__embassy_main(spawner));
+ })
+ }
+ }
+}
+
pub fn riscv(args: &[NestedMeta]) -> TokenStream {
let maybe_entry = match Args::from_list(args) {
Ok(args) => args.entry,
diff --git a/embassy-executor-macros/src/macros/task.rs b/embassy-executor-macros/src/macros/task.rs
index 5161e1020..96c6267b2 100644
--- a/embassy-executor-macros/src/macros/task.rs
+++ b/embassy-executor-macros/src/macros/task.rs
@@ -49,7 +49,7 @@ pub fn run(args: &[NestedMeta], f: syn::ItemFn) -> Result Result match t.pat.as_mut() {
syn::Pat::Ident(id) => {
- arg_names.push(id.ident.clone());
id.mutability = None;
+ args.push((id.clone(), t.attrs.clone()));
}
_ => {
ctxt.error_spanned_by(arg, "pattern matching in task arguments is not yet supported");
@@ -79,13 +79,35 @@ pub fn run(args: &[NestedMeta], f: syn::ItemFn) -> Result ::embassy_executor::SpawnToken {
- type Fut = impl ::core::future::Future + 'static;
+ trait _EmbassyInternalTaskTrait {
+ type Fut: ::core::future::Future + 'static;
+ fn construct(#fargs) -> Self::Fut;
+ }
+
+ impl _EmbassyInternalTaskTrait for () {
+ type Fut = impl core::future::Future + 'static;
+ fn construct(#fargs) -> Self::Fut {
+ #task_inner_ident(#(#full_args,)*)
+ }
+ }
+
const POOL_SIZE: usize = #pool_size;
- static POOL: ::embassy_executor::raw::TaskPool = ::embassy_executor::raw::TaskPool::new();
- unsafe { POOL._spawn_async_fn(move || #task_inner_ident(#(#arg_names,)*)) }
+ static POOL: ::embassy_executor::raw::TaskPool<<() as _EmbassyInternalTaskTrait>::Fut, POOL_SIZE> = ::embassy_executor::raw::TaskPool::new();
+ unsafe { POOL._spawn_async_fn(move || <() as _EmbassyInternalTaskTrait>::construct(#(#full_args,)*)) }
}
};
#[cfg(not(feature = "nightly"))]
@@ -93,7 +115,7 @@ pub fn run(args: &[NestedMeta], f: syn::ItemFn) -> Result ::embassy_executor::SpawnToken {
const POOL_SIZE: usize = #pool_size;
static POOL: ::embassy_executor::_export::TaskPoolRef = ::embassy_executor::_export::TaskPoolRef::new();
- unsafe { POOL.get::<_, POOL_SIZE>()._spawn_async_fn(move || #task_inner_ident(#(#arg_names,)*)) }
+ unsafe { POOL.get::<_, POOL_SIZE>()._spawn_async_fn(move || #task_inner_ident(#(#full_args,)*)) }
}
};
diff --git a/embassy-executor-macros/src/util/ctxt.rs b/embassy-executor-macros/src/util/ctxt.rs
index 74c872c3c..9c78cda01 100644
--- a/embassy-executor-macros/src/util/ctxt.rs
+++ b/embassy-executor-macros/src/util/ctxt.rs
@@ -7,7 +7,6 @@ use std::thread;
use proc_macro2::TokenStream;
use quote::{quote, ToTokens};
-use syn;
/// A type to collect errors together and format them.
///
diff --git a/embassy-executor/CHANGELOG.md b/embassy-executor/CHANGELOG.md
index 5c6749230..77c64fd8e 100644
--- a/embassy-executor/CHANGELOG.md
+++ b/embassy-executor/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased
+## 0.5.0 - 2024-01-11
+
+- Updated to `embassy-time-driver 0.1`, `embassy-time-queue-driver 0.1`, compatible with `embassy-time v0.3` and higher.
+
## 0.4.0 - 2023-12-05
- Removed `arch-xtensa`. Use the executor provided by the HAL crate (`esp-hal`, `esp32s3-hal`, etc...) instead.
diff --git a/embassy-executor/Cargo.toml b/embassy-executor/Cargo.toml
index ec5aca46d..431165cee 100644
--- a/embassy-executor/Cargo.toml
+++ b/embassy-executor/Cargo.toml
@@ -1,10 +1,11 @@
[package]
name = "embassy-executor"
-version = "0.4.0"
+version = "0.5.0"
edition = "2021"
license = "MIT OR Apache-2.0"
description = "async/await executor designed for embedded usage"
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-executor"
categories = [
"embedded",
"no-std",
@@ -14,7 +15,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 +26,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 }
@@ -33,11 +34,13 @@ log = { version = "0.4.14", optional = true }
rtos-trace = { version = "0.1.2", optional = true }
embassy-executor-macros = { version = "0.4.0", path = "../embassy-executor-macros" }
-embassy-time = { version = "0.2", path = "../embassy-time", optional = true}
+embassy-time-driver = { version = "0.1.0", path = "../embassy-time-driver", optional = true }
+embassy-time-queue-driver = { version = "0.1.0", path = "../embassy-time-queue-driver", optional = true }
critical-section = "1.1"
-# needed for riscv
-# remove when https://github.com/rust-lang/rust/pull/114499 is merged
+document-features = "0.2.7"
+
+# needed for AVR
portable-atomic = { version = "1.5", optional = true }
# arch-cortex-m dependencies
@@ -47,72 +50,137 @@ cortex-m = { version = "0.7.6", optional = true }
wasm-bindgen = { version = "0.2.82", optional = true }
js-sys = { version = "0.3", optional = true }
+# arch-avr dependencies
+avr-device = { version = "0.5.3", optional = true }
+
[dev-dependencies]
critical-section = { version = "1.1", features = ["std"] }
[features]
-# Architecture
-_arch = [] # some arch was picked
-arch-std = ["_arch", "critical-section/std"]
-arch-cortex-m = ["_arch", "dep:cortex-m"]
-arch-riscv32 = ["_arch", "dep:portable-atomic"]
-arch-wasm = ["_arch", "dep:wasm-bindgen", "dep:js-sys"]
-
-# Enable the thread-mode executor (using WFE/SEV in Cortex-M, WFI in other embedded archs)
-executor-thread = []
-# Enable the interrupt-mode executor (available in Cortex-M only)
-executor-interrupt = []
-
-# Enable nightly-only features
+## Enable nightly-only features
nightly = ["embassy-executor-macros/nightly"]
+# Enables turbo wakers, which requires patching core. Not surfaced in the docs by default due to
+# being an complicated advanced and undocumented feature.
+# See: https://github.com/embassy-rs/embassy/pull/1263
turbowakers = []
-integrated-timers = ["dep:embassy-time"]
+## Use the executor-integrated `embassy-time` timer queue.
+integrated-timers = ["dep:embassy-time-driver", "dep:embassy-time-queue-driver"]
+
+#! ### Architecture
+_arch = [] # some arch was picked
+## std
+arch-std = ["_arch", "critical-section/std"]
+## Cortex-M
+arch-cortex-m = ["_arch", "dep:cortex-m"]
+## RISC-V 32
+arch-riscv32 = ["_arch"]
+## WASM
+arch-wasm = ["_arch", "dep:wasm-bindgen", "dep:js-sys"]
+## AVR
+arch-avr = ["_arch", "dep:portable-atomic", "dep:avr-device"]
+
+#! ### Executor
+
+## Enable the thread-mode executor (using WFE/SEV in Cortex-M, WFI in other embedded archs)
+executor-thread = []
+## Enable the interrupt-mode executor (available in Cortex-M only)
+executor-interrupt = []
+
+#! ### Task Arena Size
+#! Sets the [task arena](#task-arena) size. Necessary if you’re not using `nightly`.
+#!
+#!
+#! Preconfigured Task Arena Sizes:
+#!
+#!
# BEGIN AUTOGENERATED CONFIG FEATURES
# Generated by gen_config.py. DO NOT EDIT.
+## 64
task-arena-size-64 = []
+## 128
task-arena-size-128 = []
+## 192
task-arena-size-192 = []
+## 256
task-arena-size-256 = []
+## 320
task-arena-size-320 = []
+## 384
task-arena-size-384 = []
+## 512
task-arena-size-512 = []
+## 640
task-arena-size-640 = []
+## 768
task-arena-size-768 = []
+## 1024
task-arena-size-1024 = []
+## 1280
task-arena-size-1280 = []
+## 1536
task-arena-size-1536 = []
+## 2048
task-arena-size-2048 = []
+## 2560
task-arena-size-2560 = []
+## 3072
task-arena-size-3072 = []
+## 4096 (default)
task-arena-size-4096 = [] # Default
+## 5120
task-arena-size-5120 = []
+## 6144
task-arena-size-6144 = []
+## 8192
task-arena-size-8192 = []
+## 10240
task-arena-size-10240 = []
+## 12288
task-arena-size-12288 = []
+## 16384
task-arena-size-16384 = []
+## 20480
task-arena-size-20480 = []
+## 24576
task-arena-size-24576 = []
+## 32768
task-arena-size-32768 = []
+## 40960
task-arena-size-40960 = []
+## 49152
task-arena-size-49152 = []
+## 65536
task-arena-size-65536 = []
+## 81920
task-arena-size-81920 = []
+## 98304
task-arena-size-98304 = []
+## 131072
task-arena-size-131072 = []
+## 163840
task-arena-size-163840 = []
+## 196608
task-arena-size-196608 = []
+## 262144
task-arena-size-262144 = []
+## 327680
task-arena-size-327680 = []
+## 393216
task-arena-size-393216 = []
+## 524288
task-arena-size-524288 = []
+## 655360
task-arena-size-655360 = []
+## 786432
task-arena-size-786432 = []
+## 1048576
task-arena-size-1048576 = []
# END AUTOGENERATED CONFIG FEATURES
+
+#!
diff --git a/embassy-executor/README.md b/embassy-executor/README.md
index 80ecfc71a..aa9d59907 100644
--- a/embassy-executor/README.md
+++ b/embassy-executor/README.md
@@ -22,7 +22,7 @@ Tasks are allocated from the arena when spawned for the first time. If the task
The arena size can be configured in two ways:
- Via Cargo features: enable a Cargo feature like `task-arena-size-8192`. Only a selection of values
- is available, check `Cargo.toml` for the list.
+ is available, see [Task Area Sizes](#task-arena-size) for reference.
- Via environment variables at build time: set the variable named `EMBASSY_EXECUTOR_TASK_ARENA_SIZE`. For example
`EMBASSY_EXECUTOR_TASK_ARENA_SIZE=4321 cargo build`. You can also set them in the `[env]` section of `.cargo/config.toml`.
Any value can be set, unlike with Cargo features.
diff --git a/embassy-executor/gen_config.py b/embassy-executor/gen_config.py
index e427d29f4..cf32bd530 100644
--- a/embassy-executor/gen_config.py
+++ b/embassy-executor/gen_config.py
@@ -45,6 +45,12 @@ things = ""
for f in features:
name = f["name"].replace("_", "-")
for val in f["vals"]:
+ things += f"## {val}"
+ if val == f["default"]:
+ things += " (default)\n"
+ else:
+ things += "\n"
+
things += f"{name}-{val} = []"
if val == f["default"]:
things += " # Default"
diff --git a/embassy-executor/src/arch/avr.rs b/embassy-executor/src/arch/avr.rs
new file mode 100644
index 000000000..70085d04d
--- /dev/null
+++ b/embassy-executor/src/arch/avr.rs
@@ -0,0 +1,72 @@
+#[cfg(feature = "executor-interrupt")]
+compile_error!("`executor-interrupt` is not supported with `arch-avr`.");
+
+#[cfg(feature = "executor-thread")]
+pub use thread::*;
+#[cfg(feature = "executor-thread")]
+mod thread {
+ use core::marker::PhantomData;
+
+ pub use embassy_executor_macros::main_avr as main;
+ use portable_atomic::{AtomicBool, Ordering};
+
+ use crate::{raw, Spawner};
+
+ static SIGNAL_WORK_THREAD_MODE: AtomicBool = AtomicBool::new(false);
+
+ #[export_name = "__pender"]
+ fn __pender(_context: *mut ()) {
+ SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
+ }
+
+ /// avr Executor
+ pub struct Executor {
+ inner: raw::Executor,
+ not_send: PhantomData<*mut ()>,
+ }
+
+ impl Executor {
+ /// Create a new Executor.
+ pub fn new() -> Self {
+ Self {
+ inner: raw::Executor::new(core::ptr::null_mut()),
+ not_send: PhantomData,
+ }
+ }
+
+ /// Run the executor.
+ ///
+ /// The `init` closure is called with a [`Spawner`] that spawns tasks on
+ /// this executor. Use it to spawn the initial task(s). After `init` returns,
+ /// the executor starts running the tasks.
+ ///
+ /// To spawn more tasks later, you may keep copies of the [`Spawner`] (it is `Copy`),
+ /// for example by passing it as an argument to the initial tasks.
+ ///
+ /// This function requires `&'static mut self`. This means you have to store the
+ /// Executor instance in a place where it'll live forever and grants you mutable
+ /// access. There's a few ways to do this:
+ ///
+ /// - a [StaticCell](https://docs.rs/static_cell/latest/static_cell/) (safe)
+ /// - a `static mut` (unsafe)
+ /// - a local variable in a function you know never returns (like `fn main() -> !`), upgrading its lifetime with `transmute`. (unsafe)
+ ///
+ /// This function never returns.
+ pub fn run(&'static mut self, init: impl FnOnce(Spawner)) -> ! {
+ init(self.inner.spawner());
+
+ loop {
+ unsafe {
+ avr_device::interrupt::disable();
+ if !SIGNAL_WORK_THREAD_MODE.swap(false, Ordering::SeqCst) {
+ avr_device::interrupt::enable();
+ avr_device::asm::sleep();
+ } else {
+ avr_device::interrupt::enable();
+ self.inner.poll();
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/embassy-executor/src/arch/riscv32.rs b/embassy-executor/src/arch/riscv32.rs
index c56f502d3..01e63a9fd 100644
--- a/embassy-executor/src/arch/riscv32.rs
+++ b/embassy-executor/src/arch/riscv32.rs
@@ -6,9 +6,9 @@ pub use thread::*;
#[cfg(feature = "executor-thread")]
mod thread {
use core::marker::PhantomData;
+ use core::sync::atomic::{AtomicBool, Ordering};
pub use embassy_executor_macros::main_riscv as main;
- use portable_atomic::{AtomicBool, Ordering};
use crate::{raw, Spawner};
diff --git a/embassy-executor/src/fmt.rs b/embassy-executor/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-executor/src/fmt.rs
+++ b/embassy-executor/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-executor/src/lib.rs b/embassy-executor/src/lib.rs
index 4c6900a6d..6a2e493a2 100644
--- a/embassy-executor/src/lib.rs
+++ b/embassy-executor/src/lib.rs
@@ -3,6 +3,9 @@
#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
+//! ## Feature flags
+#![doc = document_features::document_features!(feature_label = r#"{feature}"#)]
+
// This mod MUST go first, so that the others see its macros.
pub(crate) mod fmt;
@@ -20,9 +23,10 @@ macro_rules! check_at_most_one {
check_at_most_one!(@amo [$($f)*] [$($f)*] []);
};
}
-check_at_most_one!("arch-cortex-m", "arch-riscv32", "arch-std", "arch-wasm",);
+check_at_most_one!("arch-avr", "arch-cortex-m", "arch-riscv32", "arch-std", "arch-wasm",);
#[cfg(feature = "_arch")]
+#[cfg_attr(feature = "arch-avr", path = "arch/avr.rs")]
#[cfg_attr(feature = "arch-cortex-m", path = "arch/cortex_m.rs")]
#[cfg_attr(feature = "arch-riscv32", path = "arch/riscv32.rs")]
#[cfg_attr(feature = "arch-std", path = "arch/std.rs")]
diff --git a/embassy-executor/src/raw/mod.rs b/embassy-executor/src/raw/mod.rs
index b16a1c7c3..d9ea5c005 100644
--- a/embassy-executor/src/raw/mod.rs
+++ b/embassy-executor/src/raw/mod.rs
@@ -30,9 +30,7 @@ use core::ptr::NonNull;
use core::task::{Context, Poll};
#[cfg(feature = "integrated-timers")]
-use embassy_time::driver::{self, AlarmHandle};
-#[cfg(feature = "integrated-timers")]
-use embassy_time::Instant;
+use embassy_time_driver::AlarmHandle;
#[cfg(feature = "rtos-trace")]
use rtos_trace::trace;
@@ -50,7 +48,7 @@ pub(crate) struct TaskHeader {
poll_fn: SyncUnsafeCell>,
#[cfg(feature = "integrated-timers")]
- pub(crate) expires_at: SyncUnsafeCell,
+ pub(crate) expires_at: SyncUnsafeCell,
#[cfg(feature = "integrated-timers")]
pub(crate) timer_queue_item: timer_queue::TimerQueueItem,
}
@@ -123,7 +121,7 @@ impl TaskStorage {
poll_fn: SyncUnsafeCell::new(None),
#[cfg(feature = "integrated-timers")]
- expires_at: SyncUnsafeCell::new(Instant::from_ticks(0)),
+ expires_at: SyncUnsafeCell::new(0),
#[cfg(feature = "integrated-timers")]
timer_queue_item: timer_queue::TimerQueueItem::new(),
},
@@ -164,7 +162,7 @@ impl TaskStorage {
this.raw.state.despawn();
#[cfg(feature = "integrated-timers")]
- this.raw.expires_at.set(Instant::MAX);
+ this.raw.expires_at.set(u64::MAX);
}
Poll::Pending => {}
}
@@ -328,7 +326,7 @@ pub(crate) struct SyncExecutor {
impl SyncExecutor {
pub(crate) fn new(pender: Pender) -> Self {
#[cfg(feature = "integrated-timers")]
- let alarm = unsafe { unwrap!(driver::allocate_alarm()) };
+ let alarm = unsafe { unwrap!(embassy_time_driver::allocate_alarm()) };
Self {
run_queue: RunQueue::new(),
@@ -377,18 +375,19 @@ impl SyncExecutor {
/// Same as [`Executor::poll`], plus you must only call this on the thread this executor was created.
pub(crate) unsafe fn poll(&'static self) {
#[cfg(feature = "integrated-timers")]
- driver::set_alarm_callback(self.alarm, Self::alarm_callback, self as *const _ as *mut ());
+ embassy_time_driver::set_alarm_callback(self.alarm, Self::alarm_callback, self as *const _ as *mut ());
#[allow(clippy::never_loop)]
loop {
#[cfg(feature = "integrated-timers")]
- self.timer_queue.dequeue_expired(Instant::now(), wake_task_no_pend);
+ self.timer_queue
+ .dequeue_expired(embassy_time_driver::now(), wake_task_no_pend);
self.run_queue.dequeue_all(|p| {
let task = p.header();
#[cfg(feature = "integrated-timers")]
- task.expires_at.set(Instant::MAX);
+ task.expires_at.set(u64::MAX);
if !task.state.run_dequeue() {
// If task is not running, ignore it. This can happen in the following scenario:
@@ -418,7 +417,7 @@ impl SyncExecutor {
// If this is already in the past, set_alarm might return false
// In that case do another poll loop iteration.
let next_expiration = self.timer_queue.next_expiration();
- if driver::set_alarm(self.alarm, next_expiration.as_ticks()) {
+ if embassy_time_driver::set_alarm(self.alarm, next_expiration) {
break;
}
}
@@ -568,8 +567,8 @@ pub fn wake_task_no_pend(task: TaskRef) {
struct TimerQueue;
#[cfg(feature = "integrated-timers")]
-impl embassy_time::queue::TimerQueue for TimerQueue {
- fn schedule_wake(&'static self, at: Instant, waker: &core::task::Waker) {
+impl embassy_time_queue_driver::TimerQueue for TimerQueue {
+ fn schedule_wake(&'static self, at: u64, waker: &core::task::Waker) {
let task = waker::task_from_waker(waker);
let task = task.header();
unsafe {
@@ -580,7 +579,16 @@ impl embassy_time::queue::TimerQueue for TimerQueue {
}
#[cfg(feature = "integrated-timers")]
-embassy_time::timer_queue_impl!(static TIMER_QUEUE: TimerQueue = TimerQueue);
+embassy_time_queue_driver::timer_queue_impl!(static TIMER_QUEUE: TimerQueue = TimerQueue);
+
+#[cfg(all(feature = "rtos-trace", feature = "integrated-timers"))]
+const fn gcd(a: u64, b: u64) -> u64 {
+ if b == 0 {
+ a
+ } else {
+ gcd(b, a % b)
+ }
+}
#[cfg(feature = "rtos-trace")]
impl rtos_trace::RtosTraceOSCallbacks for Executor {
@@ -589,7 +597,8 @@ impl rtos_trace::RtosTraceOSCallbacks for Executor {
}
#[cfg(feature = "integrated-timers")]
fn time() -> u64 {
- Instant::now().as_micros()
+ const GCD_1M: u64 = gcd(embassy_time_driver::TICK_HZ, 1_000_000);
+ embassy_time_driver::now() * (1_000_000 / GCD_1M) / (embassy_time_driver::TICK_HZ / GCD_1M)
}
#[cfg(not(feature = "integrated-timers"))]
fn time() -> u64 {
diff --git a/embassy-executor/src/raw/timer_queue.rs b/embassy-executor/src/raw/timer_queue.rs
index 59a3b43f5..94a5f340b 100644
--- a/embassy-executor/src/raw/timer_queue.rs
+++ b/embassy-executor/src/raw/timer_queue.rs
@@ -1,7 +1,5 @@
use core::cmp::min;
-use embassy_time::Instant;
-
use super::TaskRef;
use crate::raw::util::SyncUnsafeCell;
@@ -30,7 +28,7 @@ impl TimerQueue {
pub(crate) unsafe fn update(&self, p: TaskRef) {
let task = p.header();
- if task.expires_at.get() != Instant::MAX {
+ if task.expires_at.get() != u64::MAX {
if task.state.timer_enqueue() {
task.timer_queue_item.next.set(self.head.get());
self.head.set(Some(p));
@@ -38,18 +36,18 @@ impl TimerQueue {
}
}
- pub(crate) unsafe fn next_expiration(&self) -> Instant {
- let mut res = Instant::MAX;
+ pub(crate) unsafe fn next_expiration(&self) -> u64 {
+ let mut res = u64::MAX;
self.retain(|p| {
let task = p.header();
let expires = task.expires_at.get();
res = min(res, expires);
- expires != Instant::MAX
+ expires != u64::MAX
});
res
}
- pub(crate) unsafe fn dequeue_expired(&self, now: Instant, on_task: impl Fn(TaskRef)) {
+ pub(crate) unsafe fn dequeue_expired(&self, now: u64, on_task: impl Fn(TaskRef)) {
self.retain(|p| {
let task = p.header();
if task.expires_at.get() <= now {
diff --git a/embassy-executor/tests/test.rs b/embassy-executor/tests/test.rs
index 0dbd391e8..348cc7dc4 100644
--- a/embassy-executor/tests/test.rs
+++ b/embassy-executor/tests/test.rs
@@ -1,4 +1,4 @@
-#![cfg_attr(feature = "nightly", feature(type_alias_impl_trait))]
+#![cfg_attr(feature = "nightly", feature(impl_trait_in_assoc_type))]
use std::boxed::Box;
use std::future::poll_fn;
@@ -135,3 +135,17 @@ fn executor_task_self_wake_twice() {
]
)
}
+
+#[test]
+fn executor_task_cfg_args() {
+ // simulate cfg'ing away argument c
+ #[task]
+ async fn task1(a: u32, b: u32, #[cfg(any())] c: u32) {
+ let (_, _) = (a, b);
+ }
+
+ #[task]
+ async fn task2(a: u32, b: u32, #[cfg(all())] c: u32) {
+ let (_, _, _) = (a, b, c);
+ }
+}
diff --git a/embassy-futures/Cargo.toml b/embassy-futures/Cargo.toml
index ee1f4c9af..47cefa56f 100644
--- a/embassy-futures/Cargo.toml
+++ b/embassy-futures/Cargo.toml
@@ -4,6 +4,7 @@ version = "0.1.1"
edition = "2021"
description = "no-std, no-alloc utilities for working with futures"
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-futures"
readme = "README.md"
license = "MIT OR Apache-2.0"
categories = [
diff --git a/embassy-futures/README.md b/embassy-futures/README.md
index 7add22c7b..b28a8431a 100644
--- a/embassy-futures/README.md
+++ b/embassy-futures/README.md
@@ -11,18 +11,3 @@ ideal for embedded systems.
## Interoperability
Futures from this crate can run on any executor.
-
-## 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
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
-
diff --git a/embassy-futures/src/fmt.rs b/embassy-futures/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-futures/src/fmt.rs
+++ b/embassy-futures/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-hal-internal/Cargo.toml b/embassy-hal-internal/Cargo.toml
index 42e03199c..c5013f365 100644
--- a/embassy-hal-internal/Cargo.toml
+++ b/embassy-hal-internal/Cargo.toml
@@ -3,6 +3,14 @@ name = "embassy-hal-internal"
version = "0.1.0"
edition = "2021"
license = "MIT OR Apache-2.0"
+description = "Internal implementation details for Embassy HALs. DO NOT USE DIRECTLY."
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-hal-internal"
+categories = [
+ "embedded",
+ "no-std",
+ "asynchronous",
+]
[features]
@@ -26,4 +34,4 @@ log = { version = "0.4.14", optional = true }
num-traits = { version = "0.2.14", default-features = false }
cortex-m = { version = "0.7.6", optional = true }
-critical-section = { version = "1", optional = true }
\ No newline at end of file
+critical-section = { version = "1", optional = true }
diff --git a/embassy-hal-internal/README.md b/embassy-hal-internal/README.md
index 6b060d1c0..1adce5b33 100644
--- a/embassy-hal-internal/README.md
+++ b/embassy-hal-internal/README.md
@@ -4,13 +4,3 @@ An [Embassy](https://embassy.dev) project.
Internal implementation details for Embassy HALs. DO NOT USE DIRECTLY. Embassy HALs (`embassy-nrf`, `embassy-stm32`, `embassy-rp`) already reexport
everything you need to use them effectively.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
diff --git a/embassy-hal-internal/src/atomic_ring_buffer.rs b/embassy-hal-internal/src/atomic_ring_buffer.rs
index b4f2cec28..34ceac852 100644
--- a/embassy-hal-internal/src/atomic_ring_buffer.rs
+++ b/embassy-hal-internal/src/atomic_ring_buffer.rs
@@ -1,6 +1,6 @@
//! Atomic reusable ringbuffer.
-use core::slice;
use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering};
+use core::{ptr, slice};
/// Atomic reusable ringbuffer
///
@@ -73,6 +73,7 @@ impl RingBuffer {
pub unsafe fn deinit(&self) {
// Ordering: it's OK to use `Relaxed` because this is not called
// concurrently with other methods.
+ self.buf.store(ptr::null_mut(), Ordering::Relaxed);
self.len.store(0, Ordering::Relaxed);
self.start.store(0, Ordering::Relaxed);
self.end.store(0, Ordering::Relaxed);
@@ -82,20 +83,46 @@ impl RingBuffer {
///
/// # Safety
///
- /// Only one reader can exist at a time.
+ /// - Only one reader can exist at a time.
+ /// - Ringbuffer must be initialized.
pub unsafe fn reader(&self) -> Reader<'_> {
Reader(self)
}
+ /// Try creating a reader, fails if not initialized.
+ ///
+ /// # Safety
+ ///
+ /// Only one reader can exist at a time.
+ pub unsafe fn try_reader(&self) -> Option> {
+ if self.buf.load(Ordering::Relaxed).is_null() {
+ return None;
+ }
+ Some(Reader(self))
+ }
+
/// Create a writer.
///
/// # Safety
///
- /// Only one writer can exist at a time.
+ /// - Only one writer can exist at a time.
+ /// - Ringbuffer must be initialized.
pub unsafe fn writer(&self) -> Writer<'_> {
Writer(self)
}
+ /// Try creating a writer, fails if not initialized.
+ ///
+ /// # Safety
+ ///
+ /// Only one writer can exist at a time.
+ pub unsafe fn try_writer(&self) -> Option> {
+ if self.buf.load(Ordering::Relaxed).is_null() {
+ return None;
+ }
+ Some(Writer(self))
+ }
+
/// Return length of buffer.
pub fn len(&self) -> usize {
self.len.load(Ordering::Relaxed)
diff --git a/embassy-hal-internal/src/fmt.rs b/embassy-hal-internal/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-hal-internal/src/fmt.rs
+++ b/embassy-hal-internal/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-hal-internal/src/interrupt.rs b/embassy-hal-internal/src/interrupt.rs
index 19dabcf6f..5e64dce9d 100644
--- a/embassy-hal-internal/src/interrupt.rs
+++ b/embassy-hal-internal/src/interrupt.rs
@@ -30,14 +30,12 @@ macro_rules! interrupt_mod {
pub mod typelevel {
use super::InterruptExt;
- mod sealed {
- pub trait Interrupt {}
- }
+ trait SealedInterrupt {}
/// Type-level interrupt.
///
/// This trait is implemented for all typelevel interrupt types in this module.
- pub trait Interrupt: sealed::Interrupt {
+ pub trait Interrupt: SealedInterrupt {
/// Interrupt enum variant.
///
@@ -105,7 +103,7 @@ macro_rules! interrupt_mod {
#[doc=stringify!($irqs)]
#[doc=" typelevel interrupt."]
pub enum $irqs {}
- impl sealed::Interrupt for $irqs{}
+ impl SealedInterrupt for $irqs{}
impl Interrupt for $irqs {
const IRQ: super::Interrupt = super::Interrupt::$irqs;
}
diff --git a/embassy-hal-internal/src/peripheral.rs b/embassy-hal-internal/src/peripheral.rs
index 16d49edfb..f03f41507 100644
--- a/embassy-hal-internal/src/peripheral.rs
+++ b/embassy-hal-internal/src/peripheral.rs
@@ -1,5 +1,5 @@
use core::marker::PhantomData;
-use core::ops::{Deref, DerefMut};
+use core::ops::Deref;
/// An exclusive reference to a peripheral.
///
@@ -86,13 +86,6 @@ impl<'a, T> Deref for PeripheralRef<'a, T> {
}
}
-impl<'a, T> DerefMut for PeripheralRef<'a, T> {
- #[inline]
- fn deref_mut(&mut self) -> &mut Self::Target {
- &mut self.inner
- }
-}
-
/// Trait for any type that can be used as a peripheral of type `P`.
///
/// This is used in driver constructors, to allow passing either owned peripherals (e.g. `TWISPI0`),
@@ -162,7 +155,7 @@ pub trait Peripheral: Sized {
}
}
-impl<'b, T: DerefMut> Peripheral for T
+impl<'b, T: Deref> Peripheral for T
where
T::Target: Peripheral,
{
diff --git a/embassy-net-adin1110/Cargo.toml b/embassy-net-adin1110/Cargo.toml
index d95b2628c..97579a467 100644
--- a/embassy-net-adin1110/Cargo.toml
+++ b/embassy-net-adin1110/Cargo.toml
@@ -2,27 +2,27 @@
name = "embassy-net-adin1110"
version = "0.2.0"
description = "embassy-net driver for the ADIN1110 ethernet chip"
-keywords = ["embedded", "ADIN1110", "embassy-net", "embedded-hal-async", "ethernet", "async"]
-categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+keywords = ["embedded", "ADIN1110", "embassy-net", "embedded-hal-async", "ethernet"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "asynchronous"]
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"
+documentation = "https://docs.embassy.dev/embassy-net-adin1110"
[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" }
+embedded-hal-async = { version = "1.0" }
+embedded-hal-bus = { version = "0.1", features = ["async"] }
embassy-net-driver-channel = { version = "0.2.0", path = "../embassy-net-driver-channel" }
-embassy-time = { version = "0.2", path = "../embassy-time" }
+embassy-time = { version = "0.3.0", 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", features = ["embedded-hal-async", "eh1"] }
crc = "3.0.1"
env_logger = "0.10"
critical-section = { version = "1.1.2", features = ["std"] }
@@ -38,3 +38,6 @@ src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-adin1110-v$VE
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-adin1110/src/"
target = "thumbv7em-none-eabi"
features = ["defmt"]
+
+[package.metadata.docs.rs]
+features = ["defmt"]
diff --git a/embassy-net-adin1110/README.md b/embassy-net-adin1110/README.md
index 8ea10b714..39a38960d 100644
--- a/embassy-net-adin1110/README.md
+++ b/embassy-net-adin1110/README.md
@@ -76,13 +76,3 @@ Summary:
Size/request: 289 B
Size/sec: 51.11 KiB
```
-
-## 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.
diff --git a/embassy-net-adin1110/src/crc32.rs b/embassy-net-adin1110/src/crc32.rs
index ec020b70c..4b3c69f23 100644
--- a/embassy-net-adin1110/src/crc32.rs
+++ b/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()
diff --git a/embassy-net-adin1110/src/fmt.rs b/embassy-net-adin1110/src/fmt.rs
index 12737c690..2ac42c557 100644
--- a/embassy-net-adin1110/src/fmt.rs
+++ b/embassy-net-adin1110/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -83,14 +83,17 @@ macro_rules! todo {
};
}
+#[cfg(not(feature = "defmt"))]
macro_rules! unreachable {
($($x:tt)*) => {
- {
- #[cfg(not(feature = "defmt"))]
- ::core::unreachable!($($x)*);
- #[cfg(feature = "defmt")]
- ::defmt::unreachable!($($x)*);
- }
+ ::core::unreachable!($($x)*)
+ };
+}
+
+#[cfg(feature = "defmt")]
+macro_rules! unreachable {
+ ($($x:tt)*) => {
+ ::defmt::unreachable!($($x)*)
};
}
@@ -113,7 +116,7 @@ macro_rules! trace {
#[cfg(feature = "defmt")]
::defmt::trace!($s $(, $x)*);
#[cfg(not(any(feature = "log", feature="defmt")))]
- let _ignored = ($( & $x ),*);
+ let _ = ($( & $x ),*);
}
};
}
@@ -126,7 +129,7 @@ macro_rules! debug {
#[cfg(feature = "defmt")]
::defmt::debug!($s $(, $x)*);
#[cfg(not(any(feature = "log", feature="defmt")))]
- let _ignored = ($( & $x ),*);
+ let _ = ($( & $x ),*);
}
};
}
@@ -139,7 +142,7 @@ macro_rules! info {
#[cfg(feature = "defmt")]
::defmt::info!($s $(, $x)*);
#[cfg(not(any(feature = "log", feature="defmt")))]
- let _ignored = ($( & $x ),*);
+ let _ = ($( & $x ),*);
}
};
}
@@ -152,7 +155,7 @@ macro_rules! warn {
#[cfg(feature = "defmt")]
::defmt::warn!($s $(, $x)*);
#[cfg(not(any(feature = "log", feature="defmt")))]
- let _ignored = ($( & $x ),*);
+ let _ = ($( & $x ),*);
}
};
}
@@ -165,7 +168,7 @@ macro_rules! error {
#[cfg(feature = "defmt")]
::defmt::error!($s $(, $x)*);
#[cfg(not(any(feature = "log", feature="defmt")))]
- let _ignored = ($( & $x ),*);
+ let _ = ($( & $x ),*);
}
};
}
@@ -226,7 +229,7 @@ impl Try for Result {
}
}
-pub struct Bytes<'a>(pub &'a [u8]);
+pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
diff --git a/embassy-net-adin1110/src/lib.rs b/embassy-net-adin1110/src/lib.rs
index 080b3f94d..d98e98422 100644
--- a/embassy-net-adin1110/src/lib.rs
+++ b/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 {
@@ -774,19 +777,19 @@ mod tests {
}
struct TestHarnass {
- spe: ADIN1110, CsPinMock, MockDelay>>,
- spi: Generic,
+ spe: ADIN1110>, CsPinMock, MockDelay>>,
+ spi: Generic>,
}
impl TestHarnass {
- pub fn new(expectations: &[SpiTransaction], spi_crc: bool, append_fcs_on_tx: bool) -> Self {
+ pub fn new(expectations: &[SpiTransaction], spi_crc: bool, append_fcs_on_tx: bool) -> Self {
let cs = CsPinMock::default();
let delay = MockDelay {};
let spi = SpiMock::new(expectations);
- let spi_dev: ExclusiveDevice, CsPinMock, MockDelay> =
+ let spi_dev: ExclusiveDevice>, CsPinMock, MockDelay> =
ExclusiveDevice::new(spi.clone(), cs, delay);
let spe: ADIN1110<
- ExclusiveDevice, CsPinMock, MockDelay>,
+ ExclusiveDevice>, CsPinMock, MockDelay>,
> = ADIN1110::new(spi_dev, spi_crc, append_fcs_on_tx);
Self { spe, spi }
diff --git a/embassy-net-adin1110/src/mdio.rs b/embassy-net-adin1110/src/mdio.rs
index 1ae5f0043..6fea9370e 100644
--- a/embassy-net-adin1110/src/mdio.rs
+++ b/embassy-net-adin1110/src/mdio.rs
@@ -39,6 +39,7 @@ enum Reg13Op {
///
/// Clause 45 methodes are bases on
pub trait MdioBus {
+ /// Error type.
type Error;
/// Read, Clause 22
diff --git a/embassy-net-adin1110/src/regs.rs b/embassy-net-adin1110/src/regs.rs
index beaf9466e..8780c2b9d 100644
--- a/embassy-net-adin1110/src/regs.rs
+++ b/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))]
diff --git a/embassy-net-driver-channel/Cargo.toml b/embassy-net-driver-channel/Cargo.toml
index 58d3d2316..c1ad11482 100644
--- a/embassy-net-driver-channel/Cargo.toml
+++ b/embassy-net-driver-channel/Cargo.toml
@@ -5,6 +5,7 @@ edition = "2021"
license = "MIT OR Apache-2.0"
description = "High-level channel-based driver for the `embassy-net` async TCP/IP network stack."
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-driver-channel"
categories = [
"embedded",
"no-std",
diff --git a/embassy-net-driver-channel/README.md b/embassy-net-driver-channel/README.md
index 90a216388..1955624d1 100644
--- a/embassy-net-driver-channel/README.md
+++ b/embassy-net-driver-channel/README.md
@@ -84,13 +84,3 @@ These `embassy-net` drivers are implemented using this crate. You can look at th
## Interoperability
This crate can run on any executor.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
-
-at your option.
diff --git a/embassy-net-driver-channel/src/fmt.rs b/embassy-net-driver-channel/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-net-driver-channel/src/fmt.rs
+++ b/embassy-net-driver-channel/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-net-driver-channel/src/lib.rs b/embassy-net-driver-channel/src/lib.rs
index bfb2c9c03..7ad4d449e 100644
--- a/embassy-net-driver-channel/src/lib.rs
+++ b/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 {
rx: [PacketBuf; N_RX],
tx: [PacketBuf; N_TX],
@@ -24,6 +28,7 @@ pub struct State {
impl State {
const NEW_PACKET: PacketBuf = 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>,
}
-/// 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>,
rx_chan: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf>,
shared: &'d Mutex>,
}
+/// State runner.
+///
+/// Holds the shared state of the channel such as link state.
#[derive(Clone, Copy)]
pub struct StateRunner<'d> {
shared: &'d Mutex>,
}
+/// 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>,
}
+/// 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>,
}
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,
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 {
len: usize,
buf: [u8; MTU],
}
impl PacketBuf {
+ /// 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>,
tx: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf>,
@@ -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>,
}
@@ -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>,
}
diff --git a/embassy-net-driver/Cargo.toml b/embassy-net-driver/Cargo.toml
index 9cd6a2eaa..97e8a0db3 100644
--- a/embassy-net-driver/Cargo.toml
+++ b/embassy-net-driver/Cargo.toml
@@ -5,6 +5,7 @@ edition = "2021"
license = "MIT OR Apache-2.0"
description = "Driver trait for the `embassy-net` async TCP/IP network stack."
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-driver"
categories = [
"embedded",
"no-std",
diff --git a/embassy-net-driver/README.md b/embassy-net-driver/README.md
index 6a757380d..24fcaafc4 100644
--- a/embassy-net-driver/README.md
+++ b/embassy-net-driver/README.md
@@ -16,13 +16,3 @@ packet queues for RX and TX.
## Interoperability
This crate can run on any executor.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
-
-at your option.
diff --git a/embassy-net-enc28j60/Cargo.toml b/embassy-net-enc28j60/Cargo.toml
index 72e1d4e5c..23bd3da7e 100644
--- a/embassy-net-enc28j60/Cargo.toml
+++ b/embassy-net-enc28j60/Cargo.toml
@@ -2,16 +2,18 @@
name = "embassy-net-enc28j60"
version = "0.1.0"
description = "embassy-net driver for the ENC28J60 ethernet chip"
-keywords = ["embedded", "enc28j60", "embassy-net", "embedded-hal-async", "ethernet", "async"]
-categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+keywords = ["embedded", "enc28j60", "embassy-net", "embedded-hal-async", "ethernet"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "asynchronous"]
license = "MIT OR Apache-2.0"
edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-enc28j60"
[dependencies]
-embedded-hal = { version = "1.0.0-rc.2" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal = { version = "1.0" }
+embedded-hal-async = { version = "1.0" }
embassy-net-driver = { version = "0.2.0", path = "../embassy-net-driver" }
-embassy-time = { version = "0.2", path = "../embassy-time" }
+embassy-time = { version = "0.3.0", path = "../embassy-time" }
embassy-futures = { version = "0.1.0", path = "../embassy-futures" }
defmt = { version = "0.3", optional = true }
@@ -21,3 +23,7 @@ log = { version = "0.4.14", optional = true }
src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-enc28j60-v$VERSION/embassy-net-enc28j60/src/"
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-enc28j60/src/"
target = "thumbv7em-none-eabi"
+features = ["defmt"]
+
+[package.metadata.docs.rs]
+features = ["defmt"]
diff --git a/embassy-net-enc28j60/README.md b/embassy-net-enc28j60/README.md
index 39011ca13..5c663b52e 100644
--- a/embassy-net-enc28j60/README.md
+++ b/embassy-net-enc28j60/README.md
@@ -7,13 +7,3 @@ Based on [@japaric](https://github.com/japaric)'s [`enc28j60`](https://github.co
## Interoperability
This crate can run on any executor.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
-
-at your option.
diff --git a/embassy-net-enc28j60/src/fmt.rs b/embassy-net-enc28j60/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-net-enc28j60/src/fmt.rs
+++ b/embassy-net-enc28j60/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-net-enc28j60/src/lib.rs b/embassy-net-enc28j60/src/lib.rs
index f18134927..dda35f498 100644
--- a/embassy-net-enc28j60/src/lib.rs
+++ b/embassy-net-enc28j60/src/lib.rs
@@ -17,7 +17,6 @@ mod phy;
mod traits;
use core::cmp;
-use core::convert::TryInto;
use embassy_net_driver::{Capabilities, HardwareAddress, LinkState};
use embassy_time::Duration;
@@ -645,8 +644,8 @@ where
Self: 'a;
fn receive(&mut self, cx: &mut core::task::Context) -> Option<(Self::RxToken<'_>, Self::TxToken<'_>)> {
- let rx_buf = unsafe { &mut RX_BUF };
- let tx_buf = unsafe { &mut TX_BUF };
+ let rx_buf = unsafe { &mut *core::ptr::addr_of_mut!(RX_BUF) };
+ let tx_buf = unsafe { &mut *core::ptr::addr_of_mut!(TX_BUF) };
if let Some(n) = self.receive(rx_buf) {
Some((RxToken { buf: &mut rx_buf[..n] }, TxToken { buf: tx_buf, eth: self }))
} else {
@@ -656,7 +655,7 @@ where
}
fn transmit(&mut self, _cx: &mut core::task::Context) -> Option> {
- let tx_buf = unsafe { &mut TX_BUF };
+ let tx_buf = unsafe { &mut *core::ptr::addr_of_mut!(TX_BUF) };
Some(TxToken { buf: tx_buf, eth: self })
}
diff --git a/embassy-net-esp-hosted/Cargo.toml b/embassy-net-esp-hosted/Cargo.toml
index eb44a6544..dda65dbf9 100644
--- a/embassy-net-esp-hosted/Cargo.toml
+++ b/embassy-net-esp-hosted/Cargo.toml
@@ -2,21 +2,26 @@
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"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "asynchronous"]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-esp-hosted"
[dependencies]
defmt = { version = "0.3", optional = true }
log = { version = "0.4.14", optional = true }
-embassy-time = { version = "0.2", path = "../embassy-time" }
+embassy-time = { version = "0.3.0", path = "../embassy-time" }
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" }
+embedded-hal-async = { version = "1.0" }
-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]
@@ -24,3 +29,6 @@ src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-esp-hosted-v$
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-esp-hosted/src/"
target = "thumbv7em-none-eabi"
features = ["defmt"]
+
+[package.metadata.docs.rs]
+features = ["defmt"]
diff --git a/embassy-net-esp-hosted/README.md b/embassy-net-esp-hosted/README.md
new file mode 100644
index 000000000..524231e6c
--- /dev/null
+++ b/embassy-net-esp-hosted/README.md
@@ -0,0 +1,11 @@
+# ESP-Hosted `embassy-net` integration
+
+[`embassy-net`](https://crates.io/crates/embassy-net) integration for Espressif SoCs running the the [ESP-Hosted](https://github.com/espressif/esp-hosted) stack.
+
+See [`examples`](https://github.com/embassy-rs/embassy/tree/main/examples/nrf52840) directory for usage examples with the nRF52840.
+
+## Interoperability
+
+This crate can run on any executor.
+
+It supports any SPI driver implementing [`embedded-hal-async`](https://crates.io/crates/embedded-hal-async).
diff --git a/embassy-net-esp-hosted/src/control.rs b/embassy-net-esp-hosted/src/control.rs
index c86891bc3..c8cea8503 100644
--- a/embassy-net-esp-hosted/src/control.rs
+++ b/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 {
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);
diff --git a/embassy-net-esp-hosted/src/fmt.rs b/embassy-net-esp-hosted/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-net-esp-hosted/src/fmt.rs
+++ b/embassy-net-esp-hosted/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-net-esp-hosted/src/lib.rs b/embassy-net-esp-hosted/src/lib.rs
index d61eaef3a..c78578bf1 100644
--- a/embassy-net-esp-hosted/src/lib.rs
+++ b/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,
}
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();
diff --git a/embassy-net-esp-hosted/src/proto.rs b/embassy-net-esp-hosted/src/proto.rs
index 8ceb1579d..034d5bf84 100644
--- a/embassy-net-esp-hosted/src/proto.rs
+++ b/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,
}
#[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,
}
#[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 *
diff --git a/embassy-net-ppp/Cargo.toml b/embassy-net-ppp/Cargo.toml
index 33e05227d..c4bea202f 100644
--- a/embassy-net-ppp/Cargo.toml
+++ b/embassy-net-ppp/Cargo.toml
@@ -2,10 +2,12 @@
name = "embassy-net-ppp"
version = "0.1.0"
description = "embassy-net driver for PPP over Serial"
-keywords = ["embedded", "ppp", "embassy-net", "embedded-hal-async", "ethernet", "async"]
-categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+keywords = ["embedded", "ppp", "embassy-net", "embedded-hal-async", "async"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "asynchronous"]
license = "MIT OR Apache-2.0"
edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-ppp"
[features]
defmt = ["dep:defmt", "ppproto/defmt"]
@@ -26,3 +28,6 @@ src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-ppp-v$VERSION
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-ppp/src/"
target = "thumbv7em-none-eabi"
features = ["defmt"]
+
+[package.metadata.docs.rs]
+features = ["defmt"]
diff --git a/embassy-net-ppp/README.md b/embassy-net-ppp/README.md
index 58d67395a..0eb7cee87 100644
--- a/embassy-net-ppp/README.md
+++ b/embassy-net-ppp/README.md
@@ -7,13 +7,3 @@
This crate can run on any executor.
It supports any serial port implementing [`embedded-io-async`](https://crates.io/crates/embedded-io-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.
diff --git a/embassy-net-ppp/src/fmt.rs b/embassy-net-ppp/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-net-ppp/src/fmt.rs
+++ b/embassy-net-ppp/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-net-tuntap/Cargo.toml b/embassy-net-tuntap/Cargo.toml
index 4e374c365..2cd0c0f7e 100644
--- a/embassy-net-tuntap/Cargo.toml
+++ b/embassy-net-tuntap/Cargo.toml
@@ -2,10 +2,12 @@
name = "embassy-net-tuntap"
version = "0.1.0"
description = "embassy-net driver for Linux TUN/TAP interfaces."
-keywords = ["embedded", "tuntap", "embassy-net", "embedded-hal-async", "ethernet", "async"]
-categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+keywords = ["embedded", "tuntap", "embassy-net", "ethernet", "async"]
+categories = ["embedded", "hardware-support", "network-programming", "asynchronous"]
license = "MIT OR Apache-2.0"
edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-tuntap"
[dependencies]
embassy-net-driver = { version = "0.2.0", path = "../embassy-net-driver" }
@@ -16,4 +18,4 @@ libc = "0.2.101"
[package.metadata.embassy_docs]
src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-tuntap-v$VERSION/embassy-net-tuntap/src/"
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-tuntap/src/"
-target = "thumbv7em-none-eabi"
\ No newline at end of file
+target = "x86_64-unknown-linux-gnu"
diff --git a/embassy-net-tuntap/README.md b/embassy-net-tuntap/README.md
index c5d9e746c..60a4a1bd9 100644
--- a/embassy-net-tuntap/README.md
+++ b/embassy-net-tuntap/README.md
@@ -5,13 +5,3 @@
## Interoperability
This crate can run on any executor.
-
-## License
-
-This work is licensed under either of
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
- http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
-
-at your option.
diff --git a/embassy-net-tuntap/src/lib.rs b/embassy-net-tuntap/src/lib.rs
index 75c54c487..56f55fba1 100644
--- a/embassy-net-tuntap/src/lib.rs
+++ b/embassy-net-tuntap/src/lib.rs
@@ -1,18 +1,27 @@
+#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
use std::io;
use std::io::{Read, Write};
use std::os::unix::io::{AsRawFd, RawFd};
use std::task::Context;
use async_io::Async;
-use embassy_net_driver::{self, Capabilities, Driver, HardwareAddress, LinkState};
+use embassy_net_driver::{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 {
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,
}
impl TunTapDevice {
+ /// Create a new TUN/TAP device.
pub fn new(name: &str) -> io::Result {
Ok(Self {
device: Async::new(TunTap::new(name)?)?,
diff --git a/embassy-net-wiznet/Cargo.toml b/embassy-net-wiznet/Cargo.toml
index 9c103ebb1..f87bf2bd0 100644
--- a/embassy-net-wiznet/Cargo.toml
+++ b/embassy-net-wiznet/Cargo.toml
@@ -2,16 +2,18 @@
name = "embassy-net-wiznet"
version = "0.1.0"
description = "embassy-net driver for WIZnet SPI Ethernet chips"
-keywords = ["embedded", "wiznet", "embassy-net", "embedded-hal-async", "ethernet", "async"]
-categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+keywords = ["embedded", "embassy-net", "embedded-hal-async", "ethernet", "async"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "asynchronous"]
license = "MIT OR Apache-2.0"
edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net-wiznet"
[dependencies]
-embedded-hal = { version = "1.0.0-rc.2" }
-embedded-hal-async = { version = "=1.0.0-rc.2" }
+embedded-hal = { version = "1.0" }
+embedded-hal-async = { version = "1.0" }
embassy-net-driver-channel = { version = "0.2.0", path = "../embassy-net-driver-channel" }
-embassy-time = { version = "0.2", path = "../embassy-time" }
+embassy-time = { version = "0.3.0", path = "../embassy-time" }
embassy-futures = { version = "0.1.0", path = "../embassy-futures" }
defmt = { version = "0.3", optional = true }
@@ -20,3 +22,6 @@ src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-wiznet-v$VERS
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-wiznet/src/"
target = "thumbv7em-none-eabi"
features = ["defmt"]
+
+[package.metadata.docs.rs]
+features = ["defmt"]
diff --git a/embassy-net-wiznet/README.md b/embassy-net-wiznet/README.md
index b8e4bdc8e..786aab18d 100644
--- a/embassy-net-wiznet/README.md
+++ b/embassy-net-wiznet/README.md
@@ -14,14 +14,3 @@ See [`examples`](https://github.com/embassy-rs/embassy/tree/main/examples/rp) di
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.
diff --git a/embassy-net-wiznet/src/chip/mod.rs b/embassy-net-wiznet/src/chip/mod.rs
index 562db515a..e1f963d95 100644
--- a/embassy-net-wiznet/src/chip/mod.rs
+++ b/embassy-net-wiznet/src/chip/mod.rs
@@ -1,48 +1,41 @@
+//! Wiznet W5100s and W5500 family driver.
mod w5500;
pub use w5500::W5500;
mod w5100s;
+use embedded_hal_async::spi::SpiDevice;
pub use w5100s::W5100S;
-pub(crate) mod sealed {
- use embedded_hal_async::spi::SpiDevice;
+pub(crate) trait SealedChip {
+ type Address;
- pub trait Chip {
- type Address;
+ const COMMON_MODE: Self::Address;
+ const COMMON_MAC: Self::Address;
+ const COMMON_SOCKET_INTR: Self::Address;
+ const COMMON_PHY_CFG: Self::Address;
+ const SOCKET_MODE: Self::Address;
+ const SOCKET_COMMAND: Self::Address;
+ const SOCKET_RXBUF_SIZE: Self::Address;
+ const SOCKET_TXBUF_SIZE: Self::Address;
+ const SOCKET_TX_FREE_SIZE: Self::Address;
+ const SOCKET_TX_DATA_WRITE_PTR: Self::Address;
+ const SOCKET_RECVD_SIZE: Self::Address;
+ const SOCKET_RX_DATA_READ_PTR: Self::Address;
+ const SOCKET_INTR_MASK: Self::Address;
+ const SOCKET_INTR: Self::Address;
- const COMMON_MODE: Self::Address;
- const COMMON_MAC: Self::Address;
- const COMMON_SOCKET_INTR: Self::Address;
- const COMMON_PHY_CFG: Self::Address;
- const SOCKET_MODE: Self::Address;
- const SOCKET_COMMAND: Self::Address;
- const SOCKET_RXBUF_SIZE: Self::Address;
- const SOCKET_TXBUF_SIZE: Self::Address;
- const SOCKET_TX_FREE_SIZE: Self::Address;
- const SOCKET_TX_DATA_WRITE_PTR: Self::Address;
- const SOCKET_RECVD_SIZE: Self::Address;
- const SOCKET_RX_DATA_READ_PTR: Self::Address;
- const SOCKET_INTR_MASK: Self::Address;
- const SOCKET_INTR: Self::Address;
+ const SOCKET_MODE_VALUE: u8;
- const SOCKET_MODE_VALUE: u8;
+ const BUF_SIZE: u16;
+ const AUTO_WRAP: bool;
- const BUF_SIZE: u16;
- const AUTO_WRAP: bool;
+ fn rx_addr(addr: u16) -> Self::Address;
+ fn tx_addr(addr: u16) -> Self::Address;
- fn rx_addr(addr: u16) -> Self::Address;
- fn tx_addr(addr: u16) -> Self::Address;
-
- async fn bus_read(
- spi: &mut SPI,
- address: Self::Address,
- data: &mut [u8],
- ) -> Result<(), SPI::Error>;
- async fn bus_write(
- spi: &mut SPI,
- address: Self::Address,
- data: &[u8],
- ) -> Result<(), SPI::Error>;
- }
+ async fn bus_read(spi: &mut SPI, address: Self::Address, data: &mut [u8])
+ -> Result<(), SPI::Error>;
+ async fn bus_write(spi: &mut SPI, address: Self::Address, data: &[u8]) -> Result<(), SPI::Error>;
}
-pub trait Chip: sealed::Chip {}
+/// Trait for Wiznet chips.
+#[allow(private_bounds)]
+pub trait Chip: SealedChip {}
diff --git a/embassy-net-wiznet/src/chip/w5100s.rs b/embassy-net-wiznet/src/chip/w5100s.rs
index 07a840370..23ce3ed83 100644
--- a/embassy-net-wiznet/src/chip/w5100s.rs
+++ b/embassy-net-wiznet/src/chip/w5100s.rs
@@ -4,10 +4,11 @@ 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 {}
-impl super::sealed::Chip for W5100S {
+impl super::SealedChip for W5100S {
type Address = u16;
const COMMON_MODE: Self::Address = 0x00;
diff --git a/embassy-net-wiznet/src/chip/w5500.rs b/embassy-net-wiznet/src/chip/w5500.rs
index 61e512946..12e610ea2 100644
--- a/embassy-net-wiznet/src/chip/w5500.rs
+++ b/embassy-net-wiznet/src/chip/w5500.rs
@@ -8,10 +8,11 @@ pub enum RegisterBlock {
RxBuf = 0x03,
}
+/// Wiznet W5500 chip.
pub enum W5500 {}
impl super::Chip for W5500 {}
-impl super::sealed::Chip for W5500 {
+impl super::SealedChip for W5500 {
type Address = (RegisterBlock, u16);
const COMMON_MODE: Self::Address = (RegisterBlock::Common, 0x00);
diff --git a/embassy-net-wiznet/src/lib.rs b/embassy-net-wiznet/src/lib.rs
index f26f2bbb7..da70d22bd 100644
--- a/embassy-net-wiznet/src/lib.rs
+++ b/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));
diff --git a/embassy-net/CHANGELOG.md b/embassy-net/CHANGELOG.md
index 0319a5ed4..56e245b92 100644
--- a/embassy-net/CHANGELOG.md
+++ b/embassy-net/CHANGELOG.md
@@ -7,9 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## Unreleased
+## 0.4 - 2024-01-11
+
+- Update to `embassy-time` v0.3.
+
+## 0.3 - 2024-01-04
+
+- Added `ReadReady` and `WriteReady` impls on `TcpSocket`.
- Avoid never resolving `TcpIo::read` when the output buffer is empty.
-- Update to `smoltcp` git.
+- Update to `smoltcp` v0.11.
- Forward constants from `smoltcp` in DNS query results so changing DNS result size in `smoltcp` properly propagates.
+- Removed the nightly feature.
## 0.2.1 - 2023-10-31
diff --git a/embassy-net/Cargo.toml b/embassy-net/Cargo.toml
index 0c07e3651..be9f1d784 100644
--- a/embassy-net/Cargo.toml
+++ b/embassy-net/Cargo.toml
@@ -1,10 +1,11 @@
[package]
name = "embassy-net"
-version = "0.2.1"
+version = "0.4.0"
edition = "2021"
license = "MIT OR Apache-2.0"
description = "Async TCP/IP network stack for embedded systems"
repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-net"
categories = [
"embedded",
"no-std",
@@ -15,28 +16,47 @@ categories = [
[package.metadata.embassy_docs]
src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-v$VERSION/embassy-net/src/"
src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net/src/"
-features = ["defmt", "tcp", "udp", "dns", "dhcpv4", "proto-ipv6", "medium-ethernet", "medium-ip", "medium-ieee802154", "igmp"]
+features = ["defmt", "tcp", "udp", "dns", "dhcpv4", "proto-ipv6", "medium-ethernet", "medium-ip", "medium-ieee802154", "igmp", "dhcpv4-hostname"]
target = "thumbv7em-none-eabi"
[package.metadata.docs.rs]
-features = ["defmt", "tcp", "udp", "dns", "dhcpv4", "proto-ipv6", "medium-ethernet", "medium-ip", "medium-ieee802154", "igmp"]
+features = ["defmt", "tcp", "udp", "dns", "dhcpv4", "proto-ipv6", "medium-ethernet", "medium-ip", "medium-ieee802154", "igmp", "dhcpv4-hostname"]
[features]
default = []
std = []
+## Enable defmt
defmt = ["dep:defmt", "smoltcp/defmt", "embassy-net-driver/defmt", "heapless/defmt-03"]
+## Trace all raw received and transmitted packets using defmt or log.
+packet-trace = []
+
+#! Many of the following feature flags are re-exports of smoltcp feature flags. See
+#! the [smoltcp feature flag documentation](https://github.com/smoltcp-rs/smoltcp#feature-flags)
+#! for more details
+
+## Enable UDP support
udp = ["smoltcp/socket-udp"]
+## Enable TCP support
tcp = ["smoltcp/socket-tcp"]
+## Enable DNS support
dns = ["smoltcp/socket-dns", "smoltcp/proto-dns"]
+## Enable DHCPv4 support
dhcpv4 = ["proto-ipv4", "medium-ethernet", "smoltcp/socket-dhcpv4"]
+## Enable DHCPv4 support with hostname
dhcpv4-hostname = ["dhcpv4"]
+## Enable IPv4 support
proto-ipv4 = ["smoltcp/proto-ipv4"]
+## Enable IPv6 support
proto-ipv6 = ["smoltcp/proto-ipv6"]
+## Enable the Ethernet medium
medium-ethernet = ["smoltcp/medium-ethernet"]
+## Enable the IP medium
medium-ip = ["smoltcp/medium-ip"]
+## Enable the IEEE 802.15.4 medium
medium-ieee802154 = ["smoltcp/medium-ieee802154"]
+## Enable IGMP support
igmp = ["smoltcp/proto-igmp"]
[dependencies]
@@ -44,13 +64,13 @@ igmp = ["smoltcp/proto-igmp"]
defmt = { version = "0.3", optional = true }
log = { version = "0.4.14", optional = true }
-smoltcp = { git = "https://github.com/smoltcp-rs/smoltcp.git", rev = "b57e2f9e70e82a13f31d5ea17e55232c11cc2b2d", default-features = false, features = [
+smoltcp = { version = "0.11.0", default-features = false, features = [
"socket",
"async",
] }
embassy-net-driver = { version = "0.2.0", path = "../embassy-net-driver" }
-embassy-time = { version = "0.2", path = "../embassy-time" }
+embassy-time = { version = "0.3.0", path = "../embassy-time" }
embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
embedded-io-async = { version = "0.6.1" }
@@ -62,3 +82,4 @@ stable_deref_trait = { version = "1.2.0", default-features = false }
futures = { version = "0.3.17", default-features = false, features = [ "async-await" ] }
atomic-pool = "1.0"
embedded-nal-async = { version = "0.7.1" }
+document-features = "0.2.7"
diff --git a/embassy-net/README.md b/embassy-net/README.md
index 52d048e6a..94aa6f550 100644
--- a/embassy-net/README.md
+++ b/embassy-net/README.md
@@ -51,13 +51,3 @@ This crate can run on any executor.
[`embassy-time`](https://crates.io/crates/embassy-time) is used for timekeeping and timeouts. You must
link an `embassy-time` driver in your project to use this crate.
-
-## 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.
diff --git a/embassy-net/build.rs b/embassy-net/build.rs
deleted file mode 100644
index 78bd27ec7..000000000
--- a/embassy-net/build.rs
+++ /dev/null
@@ -1,18 +0,0 @@
-use std::env;
-use std::ffi::OsString;
-use std::process::Command;
-
-fn main() {
- println!("cargo:rerun-if-changed=build.rs");
-
- let rustc = env::var_os("RUSTC").unwrap_or_else(|| OsString::from("rustc"));
-
- let output = Command::new(rustc)
- .arg("--version")
- .output()
- .expect("failed to run `rustc --version`");
-
- if String::from_utf8_lossy(&output.stdout).contains("nightly") {
- println!("cargo:rustc-cfg=nightly");
- }
-}
diff --git a/embassy-net/src/device.rs b/embassy-net/src/device.rs
index 54a0c47e8..3b1d3c47c 100644
--- a/embassy-net/src/device.rs
+++ b/embassy-net/src/device.rs
@@ -76,7 +76,11 @@ where
where
F: FnOnce(&mut [u8]) -> R,
{
- self.0.consume(|buf| f(buf))
+ self.0.consume(|buf| {
+ #[cfg(feature = "packet-trace")]
+ trace!("rx: {:?}", buf);
+ f(buf)
+ })
}
}
@@ -92,6 +96,11 @@ where
where
F: FnOnce(&mut [u8]) -> R,
{
- self.0.consume(len, |buf| f(buf))
+ self.0.consume(len, |buf| {
+ let r = f(buf);
+ #[cfg(feature = "packet-trace")]
+ trace!("tx: {:?}", buf);
+ r
+ })
}
}
diff --git a/embassy-net/src/fmt.rs b/embassy-net/src/fmt.rs
index 78e583c1c..2ac42c557 100644
--- a/embassy-net/src/fmt.rs
+++ b/embassy-net/src/fmt.rs
@@ -1,5 +1,5 @@
#![macro_use]
-#![allow(unused_macros)]
+#![allow(unused)]
use core::fmt::{Debug, Display, LowerHex};
@@ -229,7 +229,6 @@ impl Try for Result {
}
}
-#[allow(unused)]
pub(crate) struct Bytes<'a>(pub &'a [u8]);
impl<'a> Debug for Bytes<'a> {
diff --git a/embassy-net/src/lib.rs b/embassy-net/src/lib.rs
index bf1468642..1c0cf1a12 100644
--- a/embassy-net/src/lib.rs
+++ b/embassy-net/src/lib.rs
@@ -1,10 +1,11 @@
#![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(nightly, feature(async_fn_in_trait, impl_trait_projections))]
-#![cfg_attr(nightly, allow(stable_features, unknown_lints))]
#![allow(async_fn_in_trait)]
#![warn(missing_docs)]
#![doc = include_str!("../README.md")]
+//! ## Feature flags
+#![doc = document_features::document_features!(feature_label = r#"{feature}"#)]
+
#[cfg(not(any(feature = "proto-ipv4", feature = "proto-ipv6")))]
compile_error!("You must enable at least one of the following features: proto-ipv4, proto-ipv6");
@@ -411,10 +412,12 @@ impl Stack {
/// ```ignore
/// let config = embassy_net::Config::dhcpv4(Default::default());
///// Init network stack
- /// let stack = &*make_static!(embassy_net::Stack::new(
+ /// static RESOURCES: StaticCell = StaticCell::new();
+ /// static STACK: StaticCell = 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`
diff --git a/embassy-net/src/tcp.rs b/embassy-net/src/tcp.rs
index dcfb5c96e..57c9b7a04 100644
--- a/embassy-net/src/tcp.rs
+++ b/embassy-net/src/tcp.rs
@@ -342,7 +342,7 @@ impl<'a> TcpSocket<'a> {
self.io.with(|s, _| s.may_send())
}
- /// return whether the recieve half of the full-duplex connection is open.
+ /// return whether the receive half of the full-duplex connection is open.
/// This function returns true if it’s possible to receive data from the remote endpoint.
/// It will return true while there is data in the receive buffer, and if there isn’t,
/// as long as the remote endpoint has not closed the connection.
@@ -471,7 +471,7 @@ impl<'d> TcpIo<'d> {
s.register_recv_waker(cx.waker());
Poll::Pending
} else {
- // if we can't receive because the recieve half of the duplex connection is closed then return an error
+ // if we can't receive because the receive half of the duplex connection is closed then return an error
Poll::Ready(Err(Error::ConnectionReset))
}
} else {
@@ -491,10 +491,16 @@ impl<'d> TcpIo<'d> {
async fn flush(&mut self) -> Result<(), Error> {
poll_fn(move |cx| {
self.with_mut(|s, _| {
- let waiting_close = s.state() == tcp::State::Closed && s.remote_endpoint().is_some();
+ let data_pending = s.send_queue() > 0;
+ let fin_pending = matches!(
+ s.state(),
+ tcp::State::FinWait1 | tcp::State::Closing | tcp::State::LastAck
+ );
+ let rst_pending = s.state() == tcp::State::Closed && s.remote_endpoint().is_some();
+
// If there are outstanding send operations, register for wake up and wait
// smoltcp issues wake-ups when octets are dequeued from the send buffer
- if s.send_queue() > 0 || waiting_close {
+ if data_pending || fin_pending || rst_pending {
s.register_send_waker(cx.waker());
Poll::Pending
// No outstanding sends, socket is flushed
@@ -547,6 +553,12 @@ mod embedded_io_impls {
}
}
+ impl<'d> embedded_io_async::ReadReady for TcpSocket<'d> {
+ fn read_ready(&mut self) -> Result {
+ Ok(self.io.with(|s, _| s.may_recv()))
+ }
+ }
+
impl<'d> embedded_io_async::Write for TcpSocket<'d> {
async fn write(&mut self, buf: &[u8]) -> Result {
self.io.write(buf).await
@@ -557,6 +569,12 @@ mod embedded_io_impls {
}
}
+ impl<'d> embedded_io_async::WriteReady for TcpSocket<'d> {
+ fn write_ready(&mut self) -> Result {
+ Ok(self.io.with(|s, _| s.may_send()))
+ }
+ }
+
impl<'d> embedded_io_async::ErrorType for TcpReader<'d> {
type Error = Error;
}
@@ -567,6 +585,12 @@ mod embedded_io_impls {
}
}
+ impl<'d> embedded_io_async::ReadReady for TcpReader<'d> {
+ fn read_ready(&mut self) -> Result {
+ Ok(self.io.with(|s, _| s.may_recv()))
+ }
+ }
+
impl<'d> embedded_io_async::ErrorType for TcpWriter<'d> {
type Error = Error;
}
@@ -580,6 +604,12 @@ mod embedded_io_impls {
self.io.flush().await
}
}
+
+ impl<'d> embedded_io_async::WriteReady for TcpWriter<'d> {
+ fn write_ready(&mut self) -> Result {
+ Ok(self.io.with(|s, _| s.may_send()))
+ }
+ }
}
/// TCP client compatible with `embedded-nal-async` traits.
diff --git a/embassy-net/src/udp.rs b/embassy-net/src/udp.rs
index 61058c1ba..a22cd8827 100644
--- a/embassy-net/src/udp.rs
+++ b/embassy-net/src/udp.rs
@@ -26,13 +26,21 @@ pub enum BindError {
/// Error returned by [`UdpSocket::recv_from`] and [`UdpSocket::send_to`].
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum Error {
+pub enum SendError {
/// No route to host.
NoRoute,
/// Socket not bound to an outgoing port.
SocketNotBound,
}
+/// Error returned by [`UdpSocket::recv_from`] and [`UdpSocket::send_to`].
+#[derive(PartialEq, Eq, Clone, Copy, Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum RecvError {
+ /// Provided buffer was smaller than the received packet.
+ Truncated,
+}
+
/// An UDP socket.
pub struct UdpSocket<'a> {
stack: &'a RefCell,
@@ -103,7 +111,7 @@ impl<'a> UdpSocket<'a> {
/// This method will wait until a datagram is received.
///
/// Returns the number of bytes received and the remote endpoint.
- pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, IpEndpoint), Error> {
+ pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, IpEndpoint), RecvError> {
poll_fn(move |cx| self.poll_recv_from(buf, cx)).await
}
@@ -114,10 +122,11 @@ impl<'a> UdpSocket<'a> {
///
/// When a datagram is received, this method will return `Poll::Ready` with the
/// number of bytes received and the remote endpoint.
- pub fn poll_recv_from(&self, buf: &mut [u8], cx: &mut Context<'_>) -> Poll> {
+ pub fn poll_recv_from(&self, buf: &mut [u8], cx: &mut Context<'_>) -> Poll> {
self.with_mut(|s, _| match s.recv_slice(buf) {
Ok((n, meta)) => Poll::Ready(Ok((n, meta.endpoint))),
// No data ready
+ Err(udp::RecvError::Truncated) => Poll::Ready(Err(RecvError::Truncated)),
Err(udp::RecvError::Exhausted) => {
s.register_recv_waker(cx.waker());
Poll::Pending
@@ -129,8 +138,8 @@ impl<'a> UdpSocket<'a> {
///
/// This method will wait until the datagram has been sent.
///
- /// When the remote endpoint is not reachable, this method will return `Err(Error::NoRoute)`
- pub async fn send_to(&self, buf: &[u8], remote_endpoint: T) -> Result<(), Error>
+ /// When the remote endpoint is not reachable, this method will return `Err(SendError::NoRoute)`
+ pub async fn send_to(&self, buf: &[u8], remote_endpoint: T) -> Result<(), SendError>
where
T: Into,
{
@@ -146,7 +155,7 @@ impl<'a> UdpSocket<'a> {
/// and register the current task to be notified when the buffer has space available.
///
/// When the remote endpoint is not reachable, this method will return `Poll::Ready(Err(Error::NoRoute))`.
- pub fn poll_send_to(&self, buf: &[u8], remote_endpoint: T, cx: &mut Context<'_>) -> Poll>
+ pub fn poll_send_to(&self, buf: &[u8], remote_endpoint: T, cx: &mut Context<'_>) -> Poll>
where
T: Into,
{
@@ -160,9 +169,9 @@ impl<'a> UdpSocket<'a> {
Err(udp::SendError::Unaddressable) => {
// If no sender/outgoing port is specified, there is not really "no route"
if s.endpoint().port == 0 {
- Poll::Ready(Err(Error::SocketNotBound))
+ Poll::Ready(Err(SendError::SocketNotBound))
} else {
- Poll::Ready(Err(Error::NoRoute))
+ Poll::Ready(Err(SendError::NoRoute))
}
}
})
@@ -213,6 +222,11 @@ impl<'a> UdpSocket<'a> {
pub fn payload_send_capacity(&self) -> usize {
self.with(|s, _| s.payload_send_capacity())
}
+
+ /// Set the hop limit field in the IP header of sent packets.
+ pub fn set_hop_limit(&mut self, hop_limit: Option) {
+ self.with_mut(|s, _| s.set_hop_limit(hop_limit))
+ }
}
impl Drop for UdpSocket<'_> {
diff --git a/embassy-nrf/Cargo.toml b/embassy-nrf/Cargo.toml
index a7f3cb35d..0045d9f97 100644
--- a/embassy-nrf/Cargo.toml
+++ b/embassy-nrf/Cargo.toml
@@ -3,6 +3,11 @@ name = "embassy-nrf"
version = "0.1.0"
edition = "2021"
license = "MIT OR Apache-2.0"
+description = "Embassy Hardware Abstraction Layer (HAL) for nRF series microcontrollers"
+keywords = ["embedded", "async", "nordic", "nrf", "embedded-hal"]
+categories = ["embedded", "hardware-support", "no-std", "asynchronous"]
+repository = "https://github.com/embassy-rs/embassy"
+documentation = "https://docs.embassy.dev/embassy-nrf"
[package.metadata.embassy_docs]
src_base = "https://github.com/embassy-rs/embassy/blob/embassy-nrf-v$VERSION/embassy-nrf/src/"
@@ -10,14 +15,21 @@ src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-nrf/s
features = ["time", "defmt", "unstable-pac", "gpiote", "time-driver-rtc1"]
flavors = [
+ { regex_feature = "nrf51", target = "thumbv6m-none-eabi" },
{ regex_feature = "nrf52.*", target = "thumbv7em-none-eabihf" },
{ regex_feature = "nrf53.*", target = "thumbv8m.main-none-eabihf" },
{ regex_feature = "nrf91.*", target = "thumbv8m.main-none-eabihf" },
]
+[package.metadata.docs.rs]
+features = ["nrf52840", "time", "defmt", "unstable-pac", "gpiote", "time-driver-rtc1"]
+rustdoc-args = ["--cfg", "docsrs"]
+
[features]
default = ["rt"]
+## Cortex-M runtime (enabled by default)
rt = [
+ "nrf51-pac?/rt",
"nrf52805-pac?/rt",
"nrf52810-pac?/rt",
"nrf52811-pac?/rt",
@@ -30,40 +42,64 @@ rt = [
"nrf9160-pac?/rt",
]
+## Enable features requiring `embassy-time`
time = ["dep:embassy-time"]
+## Enable defmt
defmt = ["dep:defmt", "embassy-hal-internal/defmt", "embassy-sync/defmt", "embassy-usb-driver/defmt", "embassy-embedded-hal/defmt"]
-# Reexport the PAC for the currently enabled chip at `embassy_nrf::pac`.
+## Reexport the PAC for the currently enabled chip at `embassy_nrf::pac` (unstable)
+unstable-pac = []
# This is unstable because semver-minor (non-breaking) releases of embassy-nrf may major-bump (breaking) the PAC version.
# If this is an issue for you, you're encouraged to directly depend on a fixed version of the PAC.
# There are no plans to make this stable.
-unstable-pac = []
-
-nrf52805 = ["nrf52805-pac", "_nrf52"]
-nrf52810 = ["nrf52810-pac", "_nrf52"]
-nrf52811 = ["nrf52811-pac", "_nrf52"]
-nrf52820 = ["nrf52820-pac", "_nrf52"]
-nrf52832 = ["nrf52832-pac", "_nrf52", "_nrf52832_anomaly_109"]
-nrf52833 = ["nrf52833-pac", "_nrf52", "_gpio-p1"]
-nrf52840 = ["nrf52840-pac", "_nrf52", "_gpio-p1"]
-nrf5340-app-s = ["_nrf5340-app", "_s"]
-nrf5340-app-ns = ["_nrf5340-app", "_ns"]
-nrf5340-net = ["_nrf5340-net"]
-nrf9160-s = ["_nrf9160", "_s"]
-nrf9160-ns = ["_nrf9160", "_ns"]
+## Enable GPIO tasks and events
gpiote = []
+
+## Use RTC1 as the time driver for `embassy-time`, with a tick rate of 32.768khz
time-driver-rtc1 = ["_time-driver"]
-# Allow using the NFC pins as regular GPIO pins (P0_09/P0_10 on nRF52, P0_02/P0_03 on nRF53)
+## Allow using the NFC pins as regular GPIO pins (P0_09/P0_10 on nRF52, P0_02/P0_03 on nRF53)
nfc-pins-as-gpio = []
-# Allow using the RST pin as a regular GPIO pin.
-# nrf52805, nrf52810, nrf52811, nrf52832: P0_21
-# nrf52820, nrf52833, nrf52840: P0_18
+## Allow using the RST pin as a regular GPIO pin.
+## * nRF52805, nRF52810, nRF52811, nRF52832: P0_21
+## * 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 [here](https://docs.rs/embedded-storage/0.3.1/embedded_storage/nor_flash/trait.MultiwriteNorFlash.html)
+qspi-multiwrite-flash = []
+
+#! ### Chip selection features
+## nRF51
+nrf51 = ["nrf51-pac", "_nrf51"]
+## nRF52805
+nrf52805 = ["nrf52805-pac", "_nrf52"]
+## nRF52810
+nrf52810 = ["nrf52810-pac", "_nrf52"]
+## nRF52811
+nrf52811 = ["nrf52811-pac", "_nrf52"]
+## nRF52820
+nrf52820 = ["nrf52820-pac", "_nrf52"]
+## nRF52832
+nrf52832 = ["nrf52832-pac", "_nrf52", "_nrf52832_anomaly_109"]
+## nRF52833
+nrf52833 = ["nrf52833-pac", "_nrf52", "_gpio-p1"]
+## nRF52840
+nrf52840 = ["nrf52840-pac", "_nrf52", "_gpio-p1"]
+## nRF5340 application core in Secure mode
+nrf5340-app-s = ["_nrf5340-app", "_s"]
+## nRF5340 application core in Non-Secure mode
+nrf5340-app-ns = ["_nrf5340-app", "_ns"]
+## nRF5340 network core
+nrf5340-net = ["_nrf5340-net"]
+## nRF9160 in Secure mode
+nrf9160-s = ["_nrf9160", "_s"]
+## nRF9160 in Non-Secure mode
+nrf9160-ns = ["_nrf9160", "_ns"]
+
# 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.
@@ -72,8 +108,9 @@ _nrf5340-net = ["_nrf5340", "nrf5340-net-pac"]
_nrf5340 = ["_gpio-p1", "_dppi"]
_nrf9160 = ["nrf9160-pac", "_dppi"]
_nrf52 = ["_ppi"]
+_nrf51 = ["_ppi"]
-_time-driver = ["dep:embassy-time", "embassy-time?/tick-hz-32_768"]
+_time-driver = ["dep:embassy-time-driver", "embassy-time-driver?/tick-hz-32_768"]
# trustzone state.
_s = []
@@ -87,19 +124,21 @@ _gpio-p1 = []
_nrf52832_anomaly_109 = []
[dependencies]
-embassy-time = { version = "0.2", path = "../embassy-time", optional = true }
+embassy-time-driver = { version = "0.1", path = "../embassy-time-driver", optional = true }
+embassy-time = { version = "0.3.0", path = "../embassy-time", optional = true }
embassy-sync = { version = "0.5.0", path = "../embassy-sync" }
embassy-hal-internal = {version = "0.1.0", path = "../embassy-hal-internal", features = ["cortex-m", "prio-bits-3"] }
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" }
+embedded-hal-async = { version = "1.0" }
embedded-io = { version = "0.6.0" }
embedded-io-async = { version = "0.6.1" }
defmt = { version = "0.3", optional = true }
+bitflags = "2.4.2"
log = { version = "0.4.14", optional = true }
cortex-m-rt = ">=0.6.15,<0.8"
cortex-m = "0.7.6"
@@ -107,9 +146,11 @@ critical-section = "1.1"
rand_core = "0.6.3"
fixed = "1.10.0"
embedded-storage = "0.3.1"
-embedded-storage-async = "0.4.0"
+embedded-storage-async = "0.4.1"
cfg-if = "1.0.0"
+document-features = "0.2.7"
+nrf51-pac = { version = "0.12.0", optional = true }
nrf52805-pac = { version = "0.12.0", optional = true }
nrf52810-pac = { version = "0.12.0", optional = true }
nrf52811-pac = { version = "0.12.0", optional = true }
@@ -120,4 +161,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 }
-
diff --git a/embassy-nrf/README.md b/embassy-nrf/README.md
index 129ec0c01..3df5f1fa5 100644
--- a/embassy-nrf/README.md
+++ b/embassy-nrf/README.md
@@ -4,7 +4,40 @@ HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so ra
The Embassy nRF HAL targets the Nordic Semiconductor nRF 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.
+complete operations in low power mode 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.
+
+For a complete list of available peripherals and features, see the [embassy-nrf documentation](https://docs.embassy.dev/embassy-nrf).
+
+## Hardware support
+
+The `embassy-nrf` HAL supports most variants of the nRF family:
+
+* nRF51 ([examples](https://github.com/embassy-rs/embassy/tree/main/examples/nrf51))
+* nRF52 ([examples](https://github.com/embassy-rs/embassy/tree/main/examples/nrf52840))
+* nRF53 ([examples](https://github.com/embassy-rs/embassy/tree/main/examples/nrf5340))
+* nRF91 ([examples](https://github.com/embassy-rs/embassy/tree/main/examples/nrf9160))
+
+Most peripherals are supported, but can vary between chip families. To check what's available, make sure to pick the MCU you're targeting in the top menu in the [documentation](https://docs.embassy.dev/embassy-nrf).
+
+For MCUs with TrustZone support, both Secure (S) and Non-Secure (NS) modes are supported. Running in Secure mode
+allows running Rust code without a SPM or TF-M binary, saving flash space and simplifying development.
+
+## Time driver
+
+If the `time-driver-rtc1` feature is enabled, the HAL uses the RTC peripheral as a global time driver for [embassy-time](https://crates.io/crates/embassy-time), with a tick rate of 32768 Hz.
+
+## Embedded-hal
+
+The `embassy-nrf` HAL implements the traits from [embedded-hal](https://crates.io/crates/embedded-hal) (v0.2 and 1.0) and [embedded-hal-async](https://crates.io/crates/embedded-hal-async), as well as [embedded-io](https://crates.io/crates/embedded-io) and [embedded-io-async](https://crates.io/crates/embedded-io-async).
+
+## Interoperability
+
+This crate can run on any executor.
+
+Optionally, some features requiring [`embassy-time`](https://crates.io/crates/embassy-time) can be activated with the `time` feature. If you enable it,
+you must link an `embassy-time` driver in your project.
## EasyDMA considerations
@@ -41,18 +74,3 @@ as the methods without the suffix will be allocating a statically sized buffer (
Note that the methods that read data like [`read`](spim::Spim::read) and [`transfer_in_place`](spim::Spim::transfer_in_place) do not have the corresponding `_from_ram` variants as
mutable slices always reside in RAM.
-
-## 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
- )
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or )
-
-at your option.
-
diff --git a/embassy-nrf/src/buffered_uarte.rs b/embassy-nrf/src/buffered_uarte.rs
index 4ac622d34..b04c96e09 100644
--- a/embassy-nrf/src/buffered_uarte.rs
+++ b/embassy-nrf/src/buffered_uarte.rs
@@ -17,29 +17,26 @@ use core::task::Poll;
use embassy_hal_internal::atomic_ring_buffer::RingBuffer;
use embassy_hal_internal::{into_ref, PeripheralRef};
-use embassy_sync::waitqueue::AtomicWaker;
// Re-export SVD variants to allow user to directly set values
pub use pac::uarte0::{baudrate::BAUDRATE_A as Baudrate, config::PARITY_A as Parity};
use crate::gpio::sealed::Pin;
-use crate::gpio::{self, AnyPin, Pin as GpioPin, PselBits};
+use crate::gpio::{AnyPin, Pin as GpioPin, PselBits};
use crate::interrupt::typelevel::Interrupt;
use crate::ppi::{
self, AnyConfigurableChannel, AnyGroup, Channel, ConfigurableChannel, Event, Group, Ppi, PpiGroup, Task,
};
use crate::timer::{Instance as TimerInstance, Timer};
-use crate::uarte::{apply_workaround_for_enable_anomaly, Config, Instance as UarteInstance};
+use crate::uarte::{configure, drop_tx_rx, Config, Instance as UarteInstance};
use crate::{interrupt, pac, Peripheral};
mod sealed {
use super::*;
pub struct State {
- pub tx_waker: AtomicWaker,
pub tx_buf: RingBuffer,
pub tx_count: AtomicUsize,
- pub rx_waker: AtomicWaker,
pub rx_buf: RingBuffer,
pub rx_started: AtomicBool,
pub rx_started_count: AtomicU8,
@@ -61,11 +58,9 @@ pub(crate) use sealed::State;
impl State {
pub(crate) const fn new() -> Self {
Self {
- tx_waker: AtomicWaker::new(),
tx_buf: RingBuffer::new(),
tx_count: AtomicUsize::new(0),
- rx_waker: AtomicWaker::new(),
rx_buf: RingBuffer::new(),
rx_started: AtomicBool::new(false),
rx_started_count: AtomicU8::new(0),
@@ -84,128 +79,131 @@ impl interrupt::typelevel::Handler for Interrupt
unsafe fn on_interrupt() {
//trace!("irq: start");
let r = U::regs();
+ let ss = U::state();
let s = U::buffered_state();
- let buf_len = s.rx_buf.len();
- let half_len = buf_len / 2;
- let mut tx = unsafe { s.tx_buf.reader() };
- let mut rx = unsafe { s.rx_buf.writer() };
+ if let Some(mut rx) = unsafe { s.rx_buf.try_writer() } {
+ let buf_len = s.rx_buf.len();
+ let half_len = buf_len / 2;
- if r.events_error.read().bits() != 0 {
- r.events_error.reset();
- let errs = r.errorsrc.read();
- r.errorsrc.write(|w| unsafe { w.bits(errs.bits()) });
+ if r.events_error.read().bits() != 0 {
+ r.events_error.reset();
+ let errs = r.errorsrc.read();
+ r.errorsrc.write(|w| unsafe { w.bits(errs.bits()) });
- if errs.overrun().bit() {
- panic!("BufferedUarte overrun");
+ if errs.overrun().bit() {
+ panic!("BufferedUarte overrun");
+ }
}
- }
- // Received some bytes, wake task.
- if r.inten.read().rxdrdy().bit_is_set() && r.events_rxdrdy.read().bits() != 0 {
- r.intenclr.write(|w| w.rxdrdy().clear());
- r.events_rxdrdy.reset();
- s.rx_waker.wake();
- }
+ // Received some bytes, wake task.
+ if r.inten.read().rxdrdy().bit_is_set() && r.events_rxdrdy.read().bits() != 0 {
+ r.intenclr.write(|w| w.rxdrdy().clear());
+ r.events_rxdrdy.reset();
+ ss.rx_waker.wake();
+ }
- if r.events_endrx.read().bits() != 0 {
- //trace!(" irq_rx: endrx");
- r.events_endrx.reset();
+ if r.events_endrx.read().bits() != 0 {
+ //trace!(" irq_rx: endrx");
+ r.events_endrx.reset();
- let val = s.rx_ended_count.load(Ordering::Relaxed);
- s.rx_ended_count.store(val.wrapping_add(1), Ordering::Relaxed);
- }
+ let val = s.rx_ended_count.load(Ordering::Relaxed);
+ s.rx_ended_count.store(val.wrapping_add(1), Ordering::Relaxed);
+ }
- if r.events_rxstarted.read().bits() != 0 || !s.rx_started.load(Ordering::Relaxed) {
- //trace!(" irq_rx: rxstarted");
- let (ptr, len) = rx.push_buf();
- if len >= half_len {
- r.events_rxstarted.reset();
+ if r.events_rxstarted.read().bits() != 0 || !s.rx_started.load(Ordering::Relaxed) {
+ //trace!(" irq_rx: rxstarted");
+ let (ptr, len) = rx.push_buf();
+ if len >= half_len {
+ r.events_rxstarted.reset();
- //trace!(" irq_rx: starting second {:?}", half_len);
+ //trace!(" irq_rx: starting second {:?}", half_len);
- // Set up the DMA read
- r.rxd.ptr.write(|w| unsafe { w.ptr().bits(ptr as u32) });
- r.rxd.maxcnt.write(|w| unsafe { w.maxcnt().bits(half_len as _) });
+ // Set up the DMA read
+ r.rxd.ptr.write(|w| unsafe { w.ptr().bits(ptr as u32) });
+ r.rxd.maxcnt.write(|w| unsafe { w.maxcnt().bits(half_len as _) });
- let chn = s.rx_ppi_ch.load(Ordering::Relaxed);
+ let chn = s.rx_ppi_ch.load(Ordering::Relaxed);
- // Enable endrx -> startrx PPI channel.
- // From this point on, if endrx happens, startrx is automatically fired.
- ppi::regs().chenset.write(|w| unsafe { w.bits(1 << chn) });
+ // Enable endrx -> startrx PPI channel.
+ // From this point on, if endrx happens, startrx is automatically fired.
+ ppi::regs().chenset.write(|w| unsafe { w.bits(1 << chn) });
- // It is possible that endrx happened BEFORE enabling the PPI. In this case
- // the PPI channel doesn't trigger, and we'd hang. We have to detect this
- // and manually start.
+ // It is possible that endrx happened BEFORE enabling the PPI. In this case
+ // the PPI channel doesn't trigger, and we'd hang. We have to detect this
+ // and manually start.
- // check again in case endrx has happened between the last check and now.
- if r.events_endrx.read().bits() != 0 {
- //trace!(" irq_rx: endrx");
- r.events_endrx.reset();
+ // check again in case endrx has happened between the last check and now.
+ if r.events_endrx.read().bits() != 0 {
+ //trace!(" irq_rx: endrx");
+ r.events_endrx.reset();
- let val = s.rx_ended_count.load(Ordering::Relaxed);
- s.rx_ended_count.store(val.wrapping_add(1), Ordering::Relaxed);
+ let val = s.rx_ended_count.load(Ordering::Relaxed);
+ s.rx_ended_count.store(val.wrapping_add(1), Ordering::Relaxed);
+ }
+
+ let rx_ended = s.rx_ended_count.load(Ordering::Relaxed);
+ let rx_started = s.rx_started_count.load(Ordering::Relaxed);
+
+ // If we started the same amount of transfers as ended, the last rxend has
+ // already occured.
+ let rxend_happened = rx_started == rx_ended;
+
+ // Check if the PPI channel is still enabled. The PPI channel disables itself
+ // when it fires, so if it's still enabled it hasn't fired.
+ let ppi_ch_enabled = ppi::regs().chen.read().bits() & (1 << chn) != 0;
+
+ // if rxend happened, and the ppi channel hasn't fired yet, the rxend got missed.
+ // this condition also naturally matches if `!started`, needed to kickstart the DMA.
+ if rxend_happened && ppi_ch_enabled {
+ //trace!("manually starting.");
+
+ // disable the ppi ch, it's of no use anymore.
+ ppi::regs().chenclr.write(|w| unsafe { w.bits(1 << chn) });
+
+ // manually start
+ r.tasks_startrx.write(|w| unsafe { w.bits(1) });
+ }
+
+ rx.push_done(half_len);
+
+ s.rx_started_count.store(rx_started.wrapping_add(1), Ordering::Relaxed);
+ s.rx_started.store(true, Ordering::Relaxed);
+ } else {
+ //trace!(" irq_rx: rxstarted no buf");
+ r.intenclr.write(|w| w.rxstarted().clear());
}
-
- let rx_ended = s.rx_ended_count.load(Ordering::Relaxed);
- let rx_started = s.rx_started_count.load(Ordering::Relaxed);
-
- // If we started the same amount of transfers as ended, the last rxend has
- // already occured.
- let rxend_happened = rx_started == rx_ended;
-
- // Check if the PPI channel is still enabled. The PPI channel disables itself
- // when it fires, so if it's still enabled it hasn't fired.
- let ppi_ch_enabled = ppi::regs().chen.read().bits() & (1 << chn) != 0;
-
- // if rxend happened, and the ppi channel hasn't fired yet, the rxend got missed.
- // this condition also naturally matches if `!started`, needed to kickstart the DMA.
- if rxend_happened && ppi_ch_enabled {
- //trace!("manually starting.");
-
- // disable the ppi ch, it's of no use anymore.
- ppi::regs().chenclr.write(|w| unsafe { w.bits(1 << chn) });
-
- // manually start
- r.tasks_startrx.write(|w| unsafe { w.bits(1) });
- }
-
- rx.push_done(half_len);
-
- s.rx_started_count.store(rx_started.wrapping_add(1), Ordering::Relaxed);
- s.rx_started.store(true, Ordering::Relaxed);
- } else {
- //trace!(" irq_rx: rxstarted no buf");
- r.intenclr.write(|w| w.rxstarted().clear());
}
}
// =============================
- // TX end
- if r.events_endtx.read().bits() != 0 {
- r.events_endtx.reset();
+ if let Some(mut tx) = unsafe { s.tx_buf.try_reader() } {
+ // TX end
+ if r.events_endtx.read().bits() != 0 {
+ r.events_endtx.reset();
- let n = s.tx_count.load(Ordering::Relaxed);
- //trace!(" irq_tx: endtx {:?}", n);
- tx.pop_done(n);
- s.tx_waker.wake();
- s.tx_count.store(0, Ordering::Relaxed);
- }
+ let n = s.tx_count.load(Ordering::Relaxed);
+ //trace!(" irq_tx: endtx {:?}", n);
+ tx.pop_done(n);
+ ss.tx_waker.wake();
+ s.tx_count.store(0, Ordering::Relaxed);
+ }
- // If not TXing, start.
- if s.tx_count.load(Ordering::Relaxed) == 0 {
- let (ptr, len) = tx.pop_buf();
- if len != 0 {
- //trace!(" irq_tx: starting {:?}", len);
- s.tx_count.store(len, Ordering::Relaxed);
+ // If not TXing, start.
+ if s.tx_count.load(Ordering::Relaxed) == 0 {
+ let (ptr, len) = tx.pop_buf();
+ if len != 0 {
+ //trace!(" irq_tx: starting {:?}", len);
+ s.tx_count.store(len, Ordering::Relaxed);
- // Set up the DMA write
- r.txd.ptr.write(|w| unsafe { w.ptr().bits(ptr as u32) });
- r.txd.maxcnt.write(|w| unsafe { w.maxcnt().bits(len as _) });
+ // Set up the DMA write
+ r.txd.ptr.write(|w| unsafe { w.ptr().bits(ptr as u32) });
+ r.txd.maxcnt.write(|w| unsafe { w.maxcnt().bits(len as _) });
- // Start UARTE Transmit transaction
- r.tasks_starttx.write(|w| unsafe { w.bits(1) });
+ // Start UARTE Transmit transaction
+ r.tasks_starttx.write(|w| unsafe { w.bits(1) });
+ }
}
}
@@ -215,11 +213,8 @@ impl interrupt::typelevel::Handler for Interrupt
/// Buffered UARTE driver.
pub struct BufferedUarte<'d, U: UarteInstance, T: TimerInstance> {
- _peri: PeripheralRef<'d, U>,
- timer: Timer<'d, T>,
- _ppi_ch1: Ppi<'d, AnyConfigurableChannel, 1, 1>,
- _ppi_ch2: Ppi<'d, AnyConfigurableChannel, 1, 2>,
- _ppi_group: PpiGroup<'d, AnyGroup>,
+ tx: BufferedUarteTx<'d, U>,
+ rx: BufferedUarteRx<'d, U, T>,
}
impl<'d, U: UarteInstance, T: TimerInstance> Unpin for BufferedUarte<'d, U, T> {}
@@ -243,7 +238,7 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
rx_buffer: &'d mut [u8],
tx_buffer: &'d mut [u8],
) -> Self {
- into_ref!(rxd, txd, ppi_ch1, ppi_ch2, ppi_group);
+ into_ref!(uarte, timer, rxd, txd, ppi_ch1, ppi_ch2, ppi_group);
Self::new_inner(
uarte,
timer,
@@ -280,7 +275,7 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
rx_buffer: &'d mut [u8],
tx_buffer: &'d mut [u8],
) -> Self {
- into_ref!(rxd, txd, cts, rts, ppi_ch1, ppi_ch2, ppi_group);
+ into_ref!(uarte, timer, rxd, txd, cts, rts, ppi_ch1, ppi_ch2, ppi_group);
Self::new_inner(
uarte,
timer,
@@ -298,8 +293,8 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
}
fn new_inner(
- peri: impl Peripheral + 'd,
- timer: impl Peripheral
+ 'd,
+ peri: PeripheralRef<'d, U>,
+ timer: PeripheralRef<'d, T>,
ppi_ch1: PeripheralRef<'d, AnyConfigurableChannel>,
ppi_ch2: PeripheralRef<'d, AnyConfigurableChannel>,
ppi_group: PeripheralRef<'d, AnyGroup>,
@@ -311,16 +306,127 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
rx_buffer: &'d mut [u8],
tx_buffer: &'d mut [u8],
) -> Self {
- into_ref!(peri, timer);
+ configure(U::regs(), config, cts.is_some());
- assert!(rx_buffer.len() % 2 == 0);
+ let tx = BufferedUarteTx::new_innerer(unsafe { peri.clone_unchecked() }, txd, cts, tx_buffer);
+ let rx = BufferedUarteRx::new_innerer(peri, timer, ppi_ch1, ppi_ch2, ppi_group, rxd, rts, rx_buffer);
+ U::Interrupt::pend();
+ unsafe { U::Interrupt::enable() };
+
+ U::state().tx_rx_refcount.store(2, Ordering::Relaxed);
+
+ Self { tx, rx }
+ }
+
+ /// Adjust the baud rate to the provided value.
+ pub fn set_baudrate(&mut self, baudrate: Baudrate) {
let r = U::regs();
+ r.baudrate.write(|w| w.baudrate().variant(baudrate));
+ }
- let hwfc = cts.is_some();
+ /// Split the UART in reader and writer parts.
+ ///
+ /// This allows reading and writing concurrently from independent tasks.
+ pub fn split(self) -> (BufferedUarteRx<'d, U, T>, BufferedUarteTx<'d, U>) {
+ (self.rx, self.tx)
+ }
- rxd.conf().write(|w| w.input().connect().drive().h0h1());
- r.psel.rxd.write(|w| unsafe { w.bits(rxd.psel_bits()) });
+ /// Split the UART in reader and writer parts, by reference.
+ ///
+ /// The returned halves borrow from `self`, so you can drop them and go back to using
+ /// the "un-split" `self`. This allows temporarily splitting the UART.
+ pub fn split_by_ref(&mut self) -> (&mut BufferedUarteRx<'d, U, T>, &mut BufferedUarteTx<'d, U>) {
+ (&mut self.rx, &mut self.tx)
+ }
+
+ /// Pull some bytes from this source into the specified buffer, returning how many bytes were read.
+ pub async fn read(&mut self, buf: &mut [u8]) -> Result {
+ self.rx.read(buf).await
+ }
+
+ /// Return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.
+ pub async fn fill_buf(&mut self) -> Result<&[u8], Error> {
+ self.rx.fill_buf().await
+ }
+
+ /// Tell this buffer that `amt` bytes have been consumed from the buffer, so they should no longer be returned in calls to `fill_buf`.
+ pub fn consume(&mut self, amt: usize) {
+ self.rx.consume(amt)
+ }
+
+ /// Write a buffer into this writer, returning how many bytes were written.
+ pub async fn write(&mut self, buf: &[u8]) -> Result {
+ self.tx.write(buf).await
+ }
+
+ /// Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
+ pub async fn flush(&mut self) -> Result<(), Error> {
+ self.tx.flush().await
+ }
+}
+
+/// Reader part of the buffered UARTE driver.
+pub struct BufferedUarteTx<'d, U: UarteInstance> {
+ _peri: PeripheralRef<'d, U>,
+}
+
+impl<'d, U: UarteInstance> BufferedUarteTx<'d, U> {
+ /// Create a new BufferedUarteTx without hardware flow control.
+ pub fn new(
+ uarte: impl Peripheral + 'd,
+ _irq: impl interrupt::typelevel::Binding> + 'd,
+ txd: impl Peripheral + 'd,
+ config: Config,
+ tx_buffer: &'d mut [u8],
+ ) -> Self {
+ into_ref!(uarte, txd);
+ Self::new_inner(uarte, txd.map_into(), None, config, tx_buffer)
+ }
+
+ /// Create a new BufferedUarte with hardware flow control (RTS/CTS)
+ ///
+ /// # Panics
+ ///
+ /// Panics if `rx_buffer.len()` is odd.
+ pub fn new_with_cts(
+ uarte: impl Peripheral
+ 'd,
+ _irq: impl interrupt::typelevel::Binding> + 'd,
+ txd: impl Peripheral + 'd,
+ cts: impl Peripheral
+ 'd,
+ config: Config,
+ tx_buffer: &'d mut [u8],
+ ) -> Self {
+ into_ref!(uarte, txd, cts);
+ Self::new_inner(uarte, txd.map_into(), Some(cts.map_into()), config, tx_buffer)
+ }
+
+ fn new_inner(
+ peri: PeripheralRef<'d, U>,
+ txd: PeripheralRef<'d, AnyPin>,
+ cts: Option>,
+ config: Config,
+ tx_buffer: &'d mut [u8],
+ ) -> Self {
+ configure(U::regs(), config, cts.is_some());
+
+ let this = Self::new_innerer(peri, txd, cts, tx_buffer);
+
+ U::Interrupt::pend();
+ unsafe { U::Interrupt::enable() };
+
+ U::state().tx_rx_refcount.store(1, Ordering::Relaxed);
+
+ this
+ }
+
+ fn new_innerer(
+ peri: PeripheralRef<'d, U>,
+ txd: PeripheralRef<'d, AnyPin>,
+ cts: Option>,
+ tx_buffer: &'d mut [u8],
+ ) -> Self {
+ let r = U::regs();
txd.set_high();
txd.conf().write(|w| w.dir().output().drive().h0h1());
@@ -331,6 +437,203 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
}
r.psel.cts.write(|w| unsafe { w.bits(cts.psel_bits()) });
+ // Initialize state
+ let s = U::buffered_state();
+ s.tx_count.store(0, Ordering::Relaxed);
+ let len = tx_buffer.len();
+ unsafe { s.tx_buf.init(tx_buffer.as_mut_ptr(), len) };
+
+ r.events_txstarted.reset();
+
+ // Enable interrupts
+ r.intenset.write(|w| {
+ w.endtx().set();
+ w
+ });
+
+ Self { _peri: peri }
+ }
+
+ /// Write a buffer into this writer, returning how many bytes were written.
+ pub async fn write(&mut self, buf: &[u8]) -> Result {
+ poll_fn(move |cx| {
+ //trace!("poll_write: {:?}", buf.len());
+ let ss = U::state();
+ let s = U::buffered_state();
+ let mut tx = unsafe { s.tx_buf.writer() };
+
+ let tx_buf = tx.push_slice();
+ if tx_buf.is_empty() {
+ //trace!("poll_write: pending");
+ ss.tx_waker.register(cx.waker());
+ return Poll::Pending;
+ }
+
+ let n = min(tx_buf.len(), buf.len());
+ tx_buf[..n].copy_from_slice(&buf[..n]);
+ tx.push_done(n);
+
+ //trace!("poll_write: queued {:?}", n);
+
+ compiler_fence(Ordering::SeqCst);
+ U::Interrupt::pend();
+
+ Poll::Ready(Ok(n))
+ })
+ .await
+ }
+
+ /// Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
+ pub async fn flush(&mut self) -> Result<(), Error> {
+ poll_fn(move |cx| {
+ //trace!("poll_flush");
+ let ss = U::state();
+ let s = U::buffered_state();
+ if !s.tx_buf.is_empty() {
+ //trace!("poll_flush: pending");
+ ss.tx_waker.register(cx.waker());
+ return Poll::Pending;
+ }
+
+ Poll::Ready(Ok(()))
+ })
+ .await
+ }
+}
+
+impl<'a, U: UarteInstance> Drop for BufferedUarteTx<'a, U> {
+ fn drop(&mut self) {
+ let r = U::regs();
+
+ r.intenclr.write(|w| {
+ w.txdrdy().set_bit();
+ w.txstarted().set_bit();
+ w.txstopped().set_bit();
+ w
+ });
+ r.events_txstopped.reset();
+ r.tasks_stoptx.write(|w| unsafe { w.bits(1) });
+ while r.events_txstopped.read().bits() == 0 {}
+
+ let s = U::buffered_state();
+ unsafe { s.tx_buf.deinit() }
+
+ let s = U::state();
+ drop_tx_rx(r, s);
+ }
+}
+
+/// Reader part of the buffered UARTE driver.
+pub struct BufferedUarteRx<'d, U: UarteInstance, T: TimerInstance> {
+ _peri: PeripheralRef<'d, U>,
+ timer: Timer<'d, T>,
+ _ppi_ch1: Ppi<'d, AnyConfigurableChannel, 1, 1>,
+ _ppi_ch2: Ppi<'d, AnyConfigurableChannel, 1, 2>,
+ _ppi_group: PpiGroup<'d, AnyGroup>,
+}
+
+impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarteRx<'d, U, T> {
+ /// Create a new BufferedUarte without hardware flow control.
+ ///
+ /// # Panics
+ ///
+ /// Panics if `rx_buffer.len()` is odd.
+ pub fn new(
+ uarte: impl Peripheral + 'd,
+ timer: impl Peripheral
+ 'd,
+ ppi_ch1: impl Peripheral
+ 'd,
+ ppi_ch2: impl Peripheral
+ 'd,
+ ppi_group: impl Peripheral
+ 'd,
+ _irq: impl interrupt::typelevel::Binding> + 'd,
+ rxd: impl Peripheral + 'd,
+ config: Config,
+ rx_buffer: &'d mut [u8],
+ ) -> Self {
+ into_ref!(uarte, timer, rxd, ppi_ch1, ppi_ch2, ppi_group);
+ Self::new_inner(
+ uarte,
+ timer,
+ ppi_ch1.map_into(),
+ ppi_ch2.map_into(),
+ ppi_group.map_into(),
+ rxd.map_into(),
+ None,
+ config,
+ rx_buffer,
+ )
+ }
+
+ /// Create a new BufferedUarte with hardware flow control (RTS/CTS)
+ ///
+ /// # Panics
+ ///
+ /// Panics if `rx_buffer.len()` is odd.
+ pub fn new_with_rts(
+ uarte: impl Peripheral
+ 'd,
+ timer: impl Peripheral
+ 'd,
+ ppi_ch1: impl Peripheral
+ 'd,
+ ppi_ch2: impl Peripheral
+ 'd,
+ ppi_group: impl Peripheral
+ 'd,
+ _irq: impl interrupt::typelevel::Binding> + 'd,
+ rxd: impl Peripheral + 'd,
+ rts: impl Peripheral
+ 'd,
+ config: Config,
+ rx_buffer: &'d mut [u8],
+ ) -> Self {
+ into_ref!(uarte, timer, rxd, rts, ppi_ch1, ppi_ch2, ppi_group);
+ Self::new_inner(
+ uarte,
+ timer,
+ ppi_ch1.map_into(),
+ ppi_ch2.map_into(),
+ ppi_group.map_into(),
+ rxd.map_into(),
+ Some(rts.map_into()),
+ config,
+ rx_buffer,
+ )
+ }
+
+ fn new_inner(
+ peri: PeripheralRef<'d, U>,
+ timer: PeripheralRef<'d, T>,
+ ppi_ch1: PeripheralRef<'d, AnyConfigurableChannel>,
+ ppi_ch2: PeripheralRef<'d, AnyConfigurableChannel>,
+ ppi_group: PeripheralRef<'d, AnyGroup>,
+ rxd: PeripheralRef<'d, AnyPin>,
+ rts: Option>,
+ config: Config,
+ rx_buffer: &'d mut [u8],
+ ) -> Self {
+ configure(U::regs(), config, rts.is_some());
+
+ let this = Self::new_innerer(peri, timer, ppi_ch1, ppi_ch2, ppi_group, rxd, rts, rx_buffer);
+
+ U::Interrupt::pend();
+ unsafe { U::Interrupt::enable() };
+
+ U::state().tx_rx_refcount.store(1, Ordering::Relaxed);
+
+ this
+ }
+
+ fn new_innerer(
+ peri: PeripheralRef<'d, U>,
+ timer: PeripheralRef<'d, T>,
+ ppi_ch1: PeripheralRef<'d, AnyConfigurableChannel>,
+ ppi_ch2: PeripheralRef<'d, AnyConfigurableChannel>,
+ ppi_group: PeripheralRef<'d, AnyGroup>,
+ rxd: PeripheralRef<'d, AnyPin>,
+ rts: Option>,
+ rx_buffer: &'d mut [u8],
+ ) -> Self {
+ assert!(rx_buffer.len() % 2 == 0);
+
+ let r = U::regs();
+
+ rxd.conf().write(|w| w.input().connect().drive().h0h1());
+ r.psel.rxd.write(|w| unsafe { w.bits(rxd.psel_bits()) });
+
if let Some(pin) = &rts {
pin.set_high();
pin.conf().write(|w| w.dir().output().drive().h0h1());
@@ -339,34 +642,21 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
// Initialize state
let s = U::buffered_state();
- s.tx_count.store(0, Ordering::Relaxed);
s.rx_started_count.store(0, Ordering::Relaxed);
s.rx_ended_count.store(0, Ordering::Relaxed);
- let len = tx_buffer.len();
- unsafe { s.tx_buf.init(tx_buffer.as_mut_ptr(), len) };
+ s.rx_started.store(false, Ordering::Relaxed);
let len = rx_buffer.len();
unsafe { s.rx_buf.init(rx_buffer.as_mut_ptr(), len) };
- // Configure
- r.config.write(|w| {
- w.hwfc().bit(hwfc);
- w.parity().variant(config.parity);
- w
- });
- r.baudrate.write(|w| w.baudrate().variant(config.baudrate));
-
// clear errors
let errors = r.errorsrc.read().bits();
r.errorsrc.write(|w| unsafe { w.bits(errors) });
r.events_rxstarted.reset();
- r.events_txstarted.reset();
r.events_error.reset();
r.events_endrx.reset();
- r.events_endtx.reset();
// Enable interrupts
- r.intenclr.write(|w| unsafe { w.bits(!0) });
r.intenset.write(|w| {
w.endtx().set();
w.rxstarted().set();
@@ -375,10 +665,6 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
w
});
- // Enable UARTE instance
- apply_workaround_for_enable_anomaly(&r);
- r.enable.write(|w| w.enable().enabled());
-
// Configure byte counter.
let timer = Timer::new_counter(timer);
timer.cc(1).write(rx_buffer.len() as u32 * 2);
@@ -400,9 +686,6 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
ppi_ch2.disable();
ppi_group.add_channel(&ppi_ch2);
- U::Interrupt::pend();
- unsafe { U::Interrupt::enable() };
-
Self {
_peri: peri,
timer,
@@ -412,80 +695,24 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
}
}
- fn pend_irq() {
- U::Interrupt::pend()
- }
-
- /// Adjust the baud rate to the provided value.
- pub fn set_baudrate(&mut self, baudrate: Baudrate) {
- let r = U::regs();
- r.baudrate.write(|w| w.baudrate().variant(baudrate));
- }
-
- /// Split the UART in reader and writer parts.
- ///
- /// This allows reading and writing concurrently from independent tasks.
- pub fn split<'u>(&'u mut self) -> (BufferedUarteRx<'u, 'd, U, T>, BufferedUarteTx<'u, 'd, U, T>) {
- (BufferedUarteRx { inner: self }, BufferedUarteTx { inner: self })
- }
-
- async fn inner_read(&self, buf: &mut [u8]) -> Result {
- let data = self.inner_fill_buf().await?;
+ /// Pull some bytes from this source into the specified buffer, returning how many bytes were read.
+ pub async fn read(&mut self, buf: &mut [u8]) -> Result {
+ let data = self.fill_buf().await?;
let n = data.len().min(buf.len());
buf[..n].copy_from_slice(&data[..n]);
- self.inner_consume(n);
+ self.consume(n);
Ok(n)
}
- async fn inner_write<'a>(&'a self, buf: &'a [u8]) -> Result {
- poll_fn(move |cx| {
- //trace!("poll_write: {:?}", buf.len());
- let s = U::buffered_state();
- let mut tx = unsafe { s.tx_buf.writer() };
-
- let tx_buf = tx.push_slice();
- if tx_buf.is_empty() {
- //trace!("poll_write: pending");
- s.tx_waker.register(cx.waker());
- return Poll::Pending;
- }
-
- let n = min(tx_buf.len(), buf.len());
- tx_buf[..n].copy_from_slice(&buf[..n]);
- tx.push_done(n);
-
- //trace!("poll_write: queued {:?}", n);
-
- compiler_fence(Ordering::SeqCst);
- Self::pend_irq();
-
- Poll::Ready(Ok(n))
- })
- .await
- }
-
- async fn inner_flush<'a>(&'a self) -> Result<(), Error> {
- poll_fn(move |cx| {
- //trace!("poll_flush");
- let s = U::buffered_state();
- if !s.tx_buf.is_empty() {
- //trace!("poll_flush: pending");
- s.tx_waker.register(cx.waker());
- return Poll::Pending;
- }
-
- Poll::Ready(Ok(()))
- })
- .await
- }
-
- async fn inner_fill_buf<'a>(&'a self) -> Result<&'a [u8], Error> {
+ /// Return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.
+ pub async fn fill_buf(&mut self) -> Result<&[u8], Error> {
poll_fn(move |cx| {
compiler_fence(Ordering::SeqCst);
//trace!("poll_read");
let r = U::regs();
let s = U::buffered_state();
+ let ss = U::state();
// Read the RXDRDY counter.
T::regs().tasks_capture[0].write(|w| unsafe { w.bits(1) });
@@ -509,7 +736,7 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
let len = s.rx_buf.len();
if start == end {
//trace!(" empty");
- s.rx_waker.register(cx.waker());
+ ss.rx_waker.register(cx.waker());
r.intenset.write(|w| w.rxdrdy().set_bit());
return Poll::Pending;
}
@@ -531,7 +758,8 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
.await
}
- fn inner_consume(&self, amt: usize) {
+ /// Tell this buffer that `amt` bytes have been consumed from the buffer, so they should no longer be returned in calls to `fill_buf`.
+ pub fn consume(&mut self, amt: usize) {
if amt == 0 {
return;
}
@@ -541,69 +769,31 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
rx.pop_done(amt);
U::regs().intenset.write(|w| w.rxstarted().set());
}
-
- /// Pull some bytes from this source into the specified buffer, returning how many bytes were read.
- pub async fn read(&mut self, buf: &mut [u8]) -> Result {
- self.inner_read(buf).await
- }
-
- /// Return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.
- pub async fn fill_buf(&mut self) -> Result<&[u8], Error> {
- self.inner_fill_buf().await
- }
-
- /// Tell this buffer that `amt` bytes have been consumed from the buffer, so they should no longer be returned in calls to `fill_buf`.
- pub fn consume(&mut self, amt: usize) {
- self.inner_consume(amt)
- }
-
- /// Write a buffer into this writer, returning how many bytes were written.
- pub async fn write(&mut self, buf: &[u8]) -> Result {
- self.inner_write(buf).await
- }
-
- /// Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
- pub async fn flush(&mut self) -> Result<(), Error> {
- self.inner_flush().await
- }
}
-/// Reader part of the buffered UARTE driver.
-pub struct BufferedUarteTx<'u, 'd, U: UarteInstance, T: TimerInstance> {
- inner: &'u BufferedUarte<'d, U, T>,
-}
+impl<'a, U: UarteInstance, T: TimerInstance> Drop for BufferedUarteRx<'a, U, T> {
+ fn drop(&mut self) {
+ self._ppi_group.disable_all();
-impl<'u, 'd, U: UarteInstance, T: TimerInstance> BufferedUarteTx<'u, 'd, U, T> {
- /// Write a buffer into this writer, returning how many bytes were written.
- pub async fn write(&mut self, buf: &[u8]) -> Result