From f2daad20ab9acb7e0b8fa3c8079ca8a573817fb0 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen 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 TaskPool { /// /// 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 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 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>); 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

+ '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

+ '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 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

+ '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

+ Into + sealed::Pin + Sized + 'static { /// Number of the pin within the port (0..31) #[inline] @@ -392,6 +406,7 @@ pub trait Pin: Peripheral

+ Into + 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

+ Into + 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

+ '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

+ Sized { /// Returns the number of the channel fn number(&self) -> usize; } +/// Interface for PPI channels that can be configured. pub trait ConfigurableChannel: Channel + Into { + /// Convert into a type erased configurable channel. fn degrade(self) -> AnyConfigurableChannel; } +/// Interface for PPI channels that cannot be configured. pub trait StaticChannel: Channel + Into { + /// 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

+ '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

+ '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

+ '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<'_>; }