max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge #918

Browse Source 
918: Doc warnings r=Dirbaio a=lulf

Fixing a few doc warnings in embassy-executor, embassy-time, embassy-usb and embassy-nrf. There are more left, but I need a break :D 



Co-authored-by: Ulf Lilleengen <lulf@redhat.com>
This commit is contained in:
bors[bot] 2022-08-22 14:43:56 +00:00 committed by GitHub
commit 61356181b2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 63 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
embassy-executor/src/raw/mod.rs
View File

@ -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:
///

9
embassy-nrf/src/buffered_uarte.rs
View File

@ -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();

21
embassy-nrf/src/gpio.rs
View File

@ -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 }

10
embassy-nrf/src/nvmc.rs
View File

@ -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 }

12
embassy-nrf/src/ppi/mod.rs
View File

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

3
embassy-nrf/src/ppi/ppi.rs
View File

@ -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);

2
embassy-time/src/driver.rs
View File

@ -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.
//!

2
embassy-usb/src/builder.rs
View File

@ -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,

3
embassy-usb/src/control.rs
View File

@ -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,

6
embassy-usb/src/driver.rs
View File

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