From f2daad20ab9acb7e0b8fa3c8079ca8a573817fb0 Mon Sep 17 00:00:00 2001
From: Ulf Lilleengen <lulf@redhat.com>
Date: Mon, 22 Aug 2022 09:11:00 +0200
Subject: [PATCH 1/3] Remove warnings
---
embassy-executor/src/raw/mod.rs | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/embassy-executor/src/raw/mod.rs b/embassy-executor/src/raw/mod.rs
index c55d10699..e1258ebb5 100644
--- a/embassy-executor/src/raw/mod.rs
+++ b/embassy-executor/src/raw/mod.rs
@@ -5,7 +5,7 @@
//! ## WARNING: here be dragons!
//!
//! Using this module requires respecting subtle safety contracts. If you can, prefer using the safe
-//! executor wrappers in [`executor`](crate::executor) and the [`embassy_executor::task`](embassy_macros::task) macro, which are fully safe.
+//! [executor wrappers](crate::Executor) and the [`embassy_executor::task`](embassy_macros::task) macro, which are fully safe.
mod run_queue;
#[cfg(feature = "integrated-timers")]
@@ -249,7 +249,7 @@ impl<F: Future + 'static, const N: usize> TaskPool<F, N> {
///
/// This is the core of the Embassy executor. It is low-level, requiring manual
/// handling of wakeups and task polling. If you can, prefer using one of the
-/// higher level executors in [`crate::executor`].
+/// [higher level executors](crate::Executor).
///
/// The raw executor leaves it up to you to handle wakeups and scheduling:
///
From 5fddff849eea74fb240147432a1739ae1759cb6c Mon Sep 17 00:00:00 2001
From: Ulf Lilleengen <lulf@redhat.com>
Date: Mon, 22 Aug 2022 09:11:24 +0200
Subject: [PATCH 2/3] Remove warnings for embassy-time
---
embassy-time/src/driver.rs | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/embassy-time/src/driver.rs b/embassy-time/src/driver.rs
index 216b27408..79ae14b91 100644
--- a/embassy-time/src/driver.rs
+++ b/embassy-time/src/driver.rs
@@ -6,7 +6,7 @@
//!
//! - Define a struct `MyDriver`
//! - Implement [`Driver`] for it
-//! - Register it as the global driver with [`time_driver_impl`].
+//! - Register it as the global driver with [`time_driver_impl`](crate::time_driver_impl).
//! - Enable the Cargo features `embassy-executor/time` and one of `embassy-time/tick-*` corresponding to the
//! tick rate of your driver.
//!
From 3e155d2ec366379584bf7ba4a447109555aa0d77 Mon Sep 17 00:00:00 2001
From: Ulf Lilleengen <lulf@redhat.com>
Date: Mon, 22 Aug 2022 10:36:33 +0200
Subject: [PATCH 3/3] nRF documentation warning fixes
---
embassy-nrf/src/buffered_uarte.rs | 9 +++++++++
embassy-nrf/src/gpio.rs | 21 ++++++++++++++++++++-
embassy-nrf/src/nvmc.rs | 10 +++++++++-
embassy-nrf/src/ppi/mod.rs | 12 ++++++++++++
embassy-nrf/src/ppi/ppi.rs | 3 +++
embassy-usb/src/builder.rs | 2 ++
embassy-usb/src/control.rs | 3 ++-
embassy-usb/src/driver.rs | 6 +++---
8 files changed, 60 insertions(+), 6 deletions(-)
diff --git a/embassy-nrf/src/buffered_uarte.rs b/embassy-nrf/src/buffered_uarte.rs
index 21ff1d73b..08dfcbcf9 100644
--- a/embassy-nrf/src/buffered_uarte.rs
+++ b/embassy-nrf/src/buffered_uarte.rs
@@ -45,8 +45,10 @@ enum TxState {
Transmitting(usize),
}
+/// A type for storing the state of the UARTE peripheral that can be stored in a static.
pub struct State<'d, U: UarteInstance, T: TimerInstance>(StateStorage<StateInner<'d, U, T>>);
impl<'d, U: UarteInstance, T: TimerInstance> State<'d, U, T> {
+ /// Create an instance for storing UARTE peripheral state.
pub fn new() -> Self {
Self(StateStorage::new())
}
@@ -75,6 +77,12 @@ pub struct BufferedUarte<'d, U: UarteInstance, T: TimerInstance> {
impl<'d, U: UarteInstance, T: TimerInstance> Unpin for BufferedUarte<'d, U, T> {}
impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
+ /// Create a new instance of a BufferedUarte.
+ ///
+ /// See the [module documentation](crate::buffered_uarte) for more details about the intended use.
+ ///
+ /// The BufferedUarte uses the provided state to store the buffers and peripheral state. The timer and ppi channels are used to 'emulate' idle line detection so that read operations
+ /// can return early if there is no data to receive.
pub fn new(
state: &'d mut State<'d, U, T>,
peri: impl Peripheral<P = U> + 'd,
@@ -178,6 +186,7 @@ impl<'d, U: UarteInstance, T: TimerInstance> BufferedUarte<'d, U, T> {
}
}
+ /// Adjust the baud rate to the provided value.
pub fn set_baudrate(&mut self, baudrate: Baudrate) {
self.inner.with(|state| {
let r = U::regs();
diff --git a/embassy-nrf/src/gpio.rs b/embassy-nrf/src/gpio.rs
index a61ff6aa5..924629908 100644
--- a/embassy-nrf/src/gpio.rs
+++ b/embassy-nrf/src/gpio.rs
@@ -1,3 +1,4 @@
+//! General purpose input/output for nRF.
#![macro_use]
use core::convert::Infallible;
@@ -26,8 +27,11 @@ pub enum Port {
#[derive(Debug, Eq, PartialEq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Pull {
+ /// No pull.
None,
+ /// Internal pull-up resistor.
Up,
+ /// Internal pull-down resistor.
Down,
}
@@ -37,6 +41,7 @@ pub struct Input<'d, T: Pin> {
}
impl<'d, T: Pin> Input<'d, T> {
+ /// Create GPIO input driver for a [Pin] with the provided [Pull] configuration.
#[inline]
pub fn new(pin: impl Peripheral<P = T> + 'd, pull: Pull) -> Self {
let mut pin = Flex::new(pin);
@@ -45,11 +50,13 @@ impl<'d, T: Pin> Input<'d, T> {
Self { pin }
}
+ /// Test if current pin level is high.
#[inline]
pub fn is_high(&self) -> bool {
self.pin.is_high()
}
+ /// Test if current pin level is low.
#[inline]
pub fn is_low(&self) -> bool {
self.pin.is_low()
@@ -66,7 +73,9 @@ impl<'d, T: Pin> Input<'d, T> {
#[derive(Debug, Eq, PartialEq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Level {
+ /// Logical low.
Low,
+ /// Logical high.
High,
}
@@ -88,6 +97,7 @@ impl Into<bool> for Level {
}
}
+/// Drive strength settings for an output pin.
// These numbers match DRIVE_A exactly so hopefully the compiler will unify them.
#[derive(Clone, Copy, Debug, PartialEq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -117,6 +127,7 @@ pub struct Output<'d, T: Pin> {
}
impl<'d, T: Pin> Output<'d, T> {
+ /// Create GPIO output driver for a [Pin] with the provided [Level] and [OutputDriver] configuration.
#[inline]
pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level, drive: OutputDrive) -> Self {
let mut pin = Flex::new(pin);
@@ -264,11 +275,13 @@ impl<'d, T: Pin> Flex<'d, T> {
self.pin.conf().reset();
}
+ /// Test if current pin level is high.
#[inline]
pub fn is_high(&self) -> bool {
!self.is_low()
}
+ /// Test if current pin level is low.
#[inline]
pub fn is_low(&self) -> bool {
self.pin.block().in_.read().bits() & (1 << self.pin.pin()) == 0
@@ -374,6 +387,7 @@ pub(crate) mod sealed {
}
}
+/// Interface for a Pin that can be configured by an [Input] or [Output] driver, or converted to an [AnyPin].
pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'static {
/// Number of the pin within the port (0..31)
#[inline]
@@ -392,6 +406,7 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
}
}
+ /// Peripheral port register value
#[inline]
fn psel_bits(&self) -> u32 {
self.pin_port() as u32
@@ -406,12 +421,16 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
}
}
-// Type-erased GPIO pin
+/// Type-erased GPIO pin
pub struct AnyPin {
pin_port: u8,
}
impl AnyPin {
+ /// Create an [AnyPin] for a specific pin.
+ ///
+ /// # Safety
+ /// - `pin_port` should not in use by another driver.
#[inline]
pub unsafe fn steal(pin_port: u8) -> Self {
Self { pin_port }
diff --git a/embassy-nrf/src/nvmc.rs b/embassy-nrf/src/nvmc.rs
index cd6100339..6f66f7a78 100644
--- a/embassy-nrf/src/nvmc.rs
+++ b/embassy-nrf/src/nvmc.rs
@@ -1,4 +1,4 @@
-//! Nvmcerature sensor interface.
+//! Non-Volatile Memory Controller (NVMC) module.
use core::{ptr, slice};
@@ -10,13 +10,19 @@ use embedded_storage::nor_flash::{
use crate::peripherals::NVMC;
use crate::{pac, Peripheral};
+/// Erase size of NVMC flash in bytes.
pub const PAGE_SIZE: usize = 4096;
+
+/// Size of NVMC flash in bytes.
pub const FLASH_SIZE: usize = crate::chip::FLASH_SIZE;
+/// Error type for NVMC operations.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Error {
+ /// Opration using a location not in flash.
OutOfBounds,
+ /// Unaligned operation or using unaligned buffers.
Unaligned,
}
@@ -29,11 +35,13 @@ impl NorFlashError for Error {
}
}
+/// Non-Volatile Memory Controller (NVMC) that implements the `embedded-storage` traits.
pub struct Nvmc<'d> {
_p: PeripheralRef<'d, NVMC>,
}
impl<'d> Nvmc<'d> {
+ /// Create Nvmc driver.
pub fn new(_p: impl Peripheral<P = NVMC> + 'd) -> Self {
into_ref!(_p);
Self { _p }
diff --git a/embassy-nrf/src/ppi/mod.rs b/embassy-nrf/src/ppi/mod.rs
index 23ab011bc..1fdd35717 100644
--- a/embassy-nrf/src/ppi/mod.rs
+++ b/embassy-nrf/src/ppi/mod.rs
@@ -26,6 +26,7 @@ mod dppi;
#[cfg(feature = "_ppi")]
mod ppi;
+/// An instance of the Programmable peripheral interconnect on nRF devices.
pub struct Ppi<'d, C: Channel, const EVENT_COUNT: usize, const TASK_COUNT: usize> {
ch: PeripheralRef<'d, C>,
#[cfg(feature = "_dppi")]
@@ -48,6 +49,7 @@ impl Task {
Self(unsafe { NonNull::new_unchecked(reg as *const _ as *mut _) })
}
+ /// Address off subscription register for this task.
pub fn subscribe_reg(&self) -> *mut u32 {
unsafe { self.0.as_ptr().add(REGISTER_DPPI_CONFIG_OFFSET) }
}
@@ -69,6 +71,7 @@ impl Event {
Self(unsafe { NonNull::new_unchecked(reg as *const _ as *mut _) })
}
+ /// Address of publish register for this event.
pub fn publish_reg(&self) -> *mut u32 {
unsafe { self.0.as_ptr().add(REGISTER_DPPI_CONFIG_OFFSET) }
}
@@ -87,21 +90,29 @@ pub(crate) mod sealed {
pub trait Group {}
}
+/// Interface for PPI channels.
pub trait Channel: sealed::Channel + Peripheral<P = Self> + Sized {
/// Returns the number of the channel
fn number(&self) -> usize;
}
+/// Interface for PPI channels that can be configured.
pub trait ConfigurableChannel: Channel + Into<AnyConfigurableChannel> {
+ /// Convert into a type erased configurable channel.
fn degrade(self) -> AnyConfigurableChannel;
}
+/// Interface for PPI channels that cannot be configured.
pub trait StaticChannel: Channel + Into<AnyStaticChannel> {
+ /// Convert into a type erased static channel.
fn degrade(self) -> AnyStaticChannel;
}
+/// Interface for a group of PPI channels.
pub trait Group: sealed::Group + Sized {
+ /// Returns the number of the group.
fn number(&self) -> usize;
+ /// Convert into a type erased group.
fn degrade(self) -> AnyGroup {
AnyGroup {
number: self.number() as u8,
@@ -196,6 +207,7 @@ macro_rules! impl_ppi_channel {
// ======================
// groups
+/// A type erased PPI group.
pub struct AnyGroup {
number: u8,
}
diff --git a/embassy-nrf/src/ppi/ppi.rs b/embassy-nrf/src/ppi/ppi.rs
index 450a290a2..19abc4e18 100644
--- a/embassy-nrf/src/ppi/ppi.rs
+++ b/embassy-nrf/src/ppi/ppi.rs
@@ -20,6 +20,7 @@ fn regs() -> &'static pac::ppi::RegisterBlock {
#[cfg(not(feature = "nrf51"))] // Not for nrf51 because of the fork task
impl<'d, C: StaticChannel> Ppi<'d, C, 0, 1> {
+ /// Configure PPI channel to trigger `task`.
pub fn new_zero_to_one(ch: impl Peripheral<P = C> + 'd, task: Task) -> Self {
into_ref!(ch);
@@ -32,6 +33,7 @@ impl<'d, C: StaticChannel> Ppi<'d, C, 0, 1> {
}
impl<'d, C: ConfigurableChannel> Ppi<'d, C, 1, 1> {
+ /// Configure PPI channel to trigger `task` on `event`.
pub fn new_one_to_one(ch: impl Peripheral<P = C> + 'd, event: Event, task: Task) -> Self {
into_ref!(ch);
@@ -46,6 +48,7 @@ impl<'d, C: ConfigurableChannel> Ppi<'d, C, 1, 1> {
#[cfg(not(feature = "nrf51"))] // Not for nrf51 because of the fork task
impl<'d, C: ConfigurableChannel> Ppi<'d, C, 1, 2> {
+ /// Configure PPI channel to trigger `task1` and `task2` on `event`.
pub fn new_one_to_two(ch: impl Peripheral<P = C> + 'd, event: Event, task1: Task, task2: Task) -> Self {
into_ref!(ch);
diff --git a/embassy-usb/src/builder.rs b/embassy-usb/src/builder.rs
index 1ca24cc08..6be88bc76 100644
--- a/embassy-usb/src/builder.rs
+++ b/embassy-usb/src/builder.rs
@@ -10,6 +10,7 @@ use crate::{Interface, STRING_INDEX_CUSTOM_START};
#[derive(Debug, Copy, Clone)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[non_exhaustive]
+/// Configuration used when creating [UsbDevice].
pub struct Config<'a> {
pub(crate) vendor_id: u16,
pub(crate) product_id: u16,
@@ -96,6 +97,7 @@ pub struct Config<'a> {
}
impl<'a> Config<'a> {
+ /// Create default configuration with the provided vid and pid values.
pub fn new(vid: u16, pid: u16) -> Self {
Self {
device_class: 0x00,
diff --git a/embassy-usb/src/control.rs b/embassy-usb/src/control.rs
index 12e5303c3..3e5749a01 100644
--- a/embassy-usb/src/control.rs
+++ b/embassy-usb/src/control.rs
@@ -1,3 +1,4 @@
+//! USB control data types.
use core::mem;
use super::types::*;
@@ -8,7 +9,7 @@ use super::types::*;
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum RequestType {
/// Request is a USB standard request. Usually handled by
- /// [`UsbDevice`](crate::device::UsbDevice).
+ /// [`UsbDevice`](crate::UsbDevice).
Standard = 0,
/// Request is intended for a USB class.
Class = 1,
diff --git a/embassy-usb/src/driver.rs b/embassy-usb/src/driver.rs
index 2a84ff9e7..7888f1639 100644
--- a/embassy-usb/src/driver.rs
+++ b/embassy-usb/src/driver.rs
@@ -12,7 +12,7 @@ pub trait Driver<'a> {
/// Allocates an endpoint and specified endpoint parameters. This method is called by the device
/// and class implementations to allocate endpoints, and can only be called before
- /// [`start`](UsbBus::start) is called.
+ /// [`start`](Self::start) is called.
///
/// # Arguments
///
@@ -95,7 +95,7 @@ pub trait Bus {
///
/// # Errors
///
- /// * [`Unsupported`](crate::UsbError::Unsupported) - This UsbBus implementation doesn't support
+ /// * [`Unsupported`](crate::driver::Unsupported) - This UsbBus implementation doesn't support
/// simulating a disconnect or it has not been enabled at creation time.
fn force_reset(&mut self) -> Result<(), Unsupported> {
Err(Unsupported)
@@ -105,7 +105,7 @@ pub trait Bus {
///
/// # Errors
///
- /// * [`Unsupported`](crate::UsbError::Unsupported) - This UsbBus implementation doesn't support
+ /// * [`Unsupported`](crate::driver::Unsupported) - This UsbBus implementation doesn't support
/// remote wakeup or it has not been enabled at creation time.
fn remote_wakeup(&mut self) -> Self::RemoteWakeupFuture<'_>;
}