From 3fb83898bc2ed0c8c9eccdf17a4852457b0bcebb Mon Sep 17 00:00:00 2001
From: Dario Nieuwenhuis <dirbaio@dirbaio.net>
Date: Tue, 19 Jul 2022 07:57:29 +0200
Subject: [PATCH 1/2] embassy-cortex-m: docs
---
embassy-cortex-m/src/interrupt.rs | 9 +++++++++
embassy-cortex-m/src/lib.rs | 1 +
2 files changed, 10 insertions(+)
diff --git a/embassy-cortex-m/src/interrupt.rs b/embassy-cortex-m/src/interrupt.rs
index 8a63b18b1..715f00381 100644
--- a/embassy-cortex-m/src/interrupt.rs
+++ b/embassy-cortex-m/src/interrupt.rs
@@ -211,6 +211,7 @@ const PRIO_MASK: u8 = 0xff;
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
}
@@ -222,6 +223,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x80,
@@ -234,6 +236,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x40,
@@ -248,6 +251,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x20,
@@ -266,6 +270,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x10,
@@ -292,6 +297,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x8,
@@ -334,6 +340,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x4,
@@ -408,6 +415,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x2,
@@ -546,6 +554,7 @@ pub enum Priority {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
+#[allow(missing_docs)]
pub enum Priority {
P0 = 0x0,
P1 = 0x1,
diff --git a/embassy-cortex-m/src/lib.rs b/embassy-cortex-m/src/lib.rs
index 680c2c8db..fba23367b 100644
--- a/embassy-cortex-m/src/lib.rs
+++ b/embassy-cortex-m/src/lib.rs
@@ -1,5 +1,6 @@
//! Embassy executor and interrupt handling specific to cortex-m devices.
#![no_std]
+#![warn(missing_docs)]
// This mod MUST go first, so that the others see its macros.
pub(crate) mod fmt;
From d2f4a9bf8df8de9f51b29659b464b4509af47dc6 Mon Sep 17 00:00:00 2001
From: Dario Nieuwenhuis <dirbaio@dirbaio.net>
Date: Tue, 19 Jul 2022 07:57:39 +0200
Subject: [PATCH 2/2] embassy-embedded-hal: docs
---
embassy-embedded-hal/src/adapter.rs | 7 +++++--
embassy-embedded-hal/src/lib.rs | 17 +++++++++++++++++
.../src/shared_bus/asynch/i2c.rs | 8 ++++++++
.../src/shared_bus/asynch/spi.rs | 8 ++++++++
.../src/shared_bus/blocking/i2c.rs | 8 ++++++++
.../src/shared_bus/blocking/spi.rs | 8 ++++++++
embassy-embedded-hal/src/shared_bus/mod.rs | 5 +++++
7 files changed, 59 insertions(+), 2 deletions(-)
diff --git a/embassy-embedded-hal/src/adapter.rs b/embassy-embedded-hal/src/adapter.rs
index 7d25d89fc..1c43f015f 100644
--- a/embassy-embedded-hal/src/adapter.rs
+++ b/embassy-embedded-hal/src/adapter.rs
@@ -1,9 +1,12 @@
+//! Adapters between embedded-hal traits.
+
use core::future::Future;
use embedded_hal_02::{blocking, serial};
-/// BlockingAsync is a wrapper that implements async traits using blocking peripherals. This allows
-/// driver writers to depend on the async traits while still supporting embedded-hal peripheral implementations.
+/// Wrapper that implements async traits using blocking implementations.
+///
+/// This allows driver writers to depend on the async traits while still supporting embedded-hal peripheral implementations.
///
/// BlockingAsync will implement any async trait that maps to embedded-hal traits implemented for the wrapped driver.
///
diff --git a/embassy-embedded-hal/src/lib.rs b/embassy-embedded-hal/src/lib.rs
index d77c2d635..0c6f2786a 100644
--- a/embassy-embedded-hal/src/lib.rs
+++ b/embassy-embedded-hal/src/lib.rs
@@ -1,12 +1,29 @@
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))]
+#![warn(missing_docs)]
+
+//! Utilities to use `embedded-hal` traits with Embassy.
#[cfg(feature = "nightly")]
pub mod adapter;
pub mod shared_bus;
+/// Set the configuration of a peripheral driver.
+///
+/// This trait is intended to be implemented by peripheral drivers such as SPI
+/// and I2C. It allows changing the configuration at runtime.
+///
+/// The exact type of the "configuration" is defined by each individual driver, since different
+/// drivers support different options. Therefore it is defined as an associated type.
+///
+/// For example, it is used by [`SpiDeviceWithConfig`](crate::shared_bus::asynch::spi::SpiDeviceWithConfig) and
+/// [`I2cDeviceWithConfig`](crate::shared_bus::asynch::i2c::I2cDeviceWithConfig) to allow different
+/// devices on the same bus to use different communication settings.
pub trait SetConfig {
+ /// The configuration type used by this driver.
type Config;
+
+ /// Set the configuration of the driver.
fn set_config(&mut self, config: &Self::Config);
}
diff --git a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
index 5bd3d9bc5..fa77a06d3 100644
--- a/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
+++ b/embassy-embedded-hal/src/shared_bus/asynch/i2c.rs
@@ -31,11 +31,13 @@ use embedded_hal_async::i2c;
use crate::shared_bus::I2cDeviceError;
use crate::SetConfig;
+/// I2C device on a shared bus.
pub struct I2cDevice<'a, M: RawMutex, BUS> {
bus: &'a Mutex<M, BUS>,
}
impl<'a, M: RawMutex, BUS> I2cDevice<'a, M, BUS> {
+ /// Create a new `I2cDevice`.
pub fn new(bus: &'a Mutex<M, BUS>) -> Self {
Self { bus }
}
@@ -103,12 +105,18 @@ where
}
}
+/// I2C device on a shared bus, with its own configuration.
+///
+/// This is like [`I2cDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
pub struct I2cDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig> {
bus: &'a Mutex<M, BUS>,
config: BUS::Config,
}
impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> {
+ /// Create a new `I2cDeviceWithConfig`.
pub fn new(bus: &'a Mutex<M, BUS>, config: BUS::Config) -> Self {
Self { bus, config }
}
diff --git a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
index 343184d12..a08eaa82d 100644
--- a/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
+++ b/embassy-embedded-hal/src/shared_bus/asynch/spi.rs
@@ -36,12 +36,14 @@ use embedded_hal_async::spi;
use crate::shared_bus::SpiDeviceError;
use crate::SetConfig;
+/// SPI device on a shared bus.
pub struct SpiDevice<'a, M: RawMutex, BUS, CS> {
bus: &'a Mutex<M, BUS>,
cs: CS,
}
impl<'a, M: RawMutex, BUS, CS> SpiDevice<'a, M, BUS, CS> {
+ /// Create a new `SpiDevice`.
pub fn new(bus: &'a Mutex<M, BUS>, cs: CS) -> Self {
Self { bus, cs }
}
@@ -93,6 +95,11 @@ where
}
}
+/// SPI device on a shared bus, with its own configuration.
+///
+/// This is like [`SpiDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
bus: &'a Mutex<M, BUS>,
cs: CS,
@@ -100,6 +107,7 @@ pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
}
impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> {
+ /// Create a new `SpiDeviceWithConfig`.
pub fn new(bus: &'a Mutex<M, BUS>, cs: CS, config: BUS::Config) -> Self {
Self { bus, cs, config }
}
diff --git a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
index 1ec480c0c..c8b5e30f6 100644
--- a/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
+++ b/embassy-embedded-hal/src/shared_bus/blocking/i2c.rs
@@ -26,11 +26,13 @@ use embedded_hal_1::i2c::ErrorType;
use crate::shared_bus::I2cDeviceError;
use crate::SetConfig;
+/// I2C device on a shared bus.
pub struct I2cDevice<'a, M: RawMutex, BUS> {
bus: &'a Mutex<M, RefCell<BUS>>,
}
impl<'a, M: RawMutex, BUS> I2cDevice<'a, M, BUS> {
+ /// Create a new `I2cDevice`.
pub fn new(bus: &'a Mutex<M, RefCell<BUS>>) -> Self {
Self { bus }
}
@@ -143,12 +145,18 @@ where
}
}
+/// I2C device on a shared bus, with its own configuration.
+///
+/// This is like [`I2cDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
pub struct I2cDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig> {
bus: &'a Mutex<M, RefCell<BUS>>,
config: BUS::Config,
}
impl<'a, M: RawMutex, BUS: SetConfig> I2cDeviceWithConfig<'a, M, BUS> {
+ /// Create a new `I2cDeviceWithConfig`.
pub fn new(bus: &'a Mutex<M, RefCell<BUS>>, config: BUS::Config) -> Self {
Self { bus, config }
}
diff --git a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
index ff92e1a7e..d0648f59a 100644
--- a/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
+++ b/embassy-embedded-hal/src/shared_bus/blocking/spi.rs
@@ -29,12 +29,14 @@ use embedded_hal_1::spi::blocking::SpiBusFlush;
use crate::shared_bus::SpiDeviceError;
use crate::SetConfig;
+/// SPI device on a shared bus.
pub struct SpiDevice<'a, M: RawMutex, BUS, CS> {
bus: &'a Mutex<M, RefCell<BUS>>,
cs: CS,
}
impl<'a, M: RawMutex, BUS, CS> SpiDevice<'a, M, BUS, CS> {
+ /// Create a new `SpiDevice`.
pub fn new(bus: &'a Mutex<M, RefCell<BUS>>, cs: CS) -> Self {
Self { bus, cs }
}
@@ -117,6 +119,11 @@ where
}
}
+/// SPI device on a shared bus, with its own configuration.
+///
+/// This is like [`SpiDevice`], with an additional bus configuration that's applied
+/// to the bus before each use using [`SetConfig`]. This allows different
+/// devices on the same bus to use different communication settings.
pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
bus: &'a Mutex<M, RefCell<BUS>>,
cs: CS,
@@ -124,6 +131,7 @@ pub struct SpiDeviceWithConfig<'a, M: RawMutex, BUS: SetConfig, CS> {
}
impl<'a, M: RawMutex, BUS: SetConfig, CS> SpiDeviceWithConfig<'a, M, BUS, CS> {
+ /// Create a new `SpiDeviceWithConfig`.
pub fn new(bus: &'a Mutex<M, RefCell<BUS>>, cs: CS, config: BUS::Config) -> Self {
Self { bus, cs, config }
}
diff --git a/embassy-embedded-hal/src/shared_bus/mod.rs b/embassy-embedded-hal/src/shared_bus/mod.rs
index 3cd380f72..76ee413d9 100644
--- a/embassy-embedded-hal/src/shared_bus/mod.rs
+++ b/embassy-embedded-hal/src/shared_bus/mod.rs
@@ -8,8 +8,10 @@ pub mod asynch;
pub mod blocking;
+/// Error returned by I2C device implementations in this crate.
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
pub enum I2cDeviceError<BUS> {
+ /// An operation on the inner I2C bus failed.
I2c(BUS),
}
@@ -24,9 +26,12 @@ where
}
}
+/// Error returned by SPI device implementations in this crate.
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
pub enum SpiDeviceError<BUS, CS> {
+ /// An operation on the inner SPI bus failed.
Spi(BUS),
+ /// Setting the value of the Chip Select (CS) pin failed.
Cs(CS),
}