diff --git a/esp-hal/src/embassy/executor/interrupt.rs b/esp-hal/src/embassy/executor/interrupt.rs index 0900072cc41..b9485fb1b87 100644 --- a/esp-hal/src/embassy/executor/interrupt.rs +++ b/esp-hal/src/embassy/executor/interrupt.rs @@ -54,7 +54,7 @@ impl CallbackContext { } fn handle_interrupt() { - let mut swi = unsafe { SoftwareInterrupt::::steal() }; + let swi = unsafe { SoftwareInterrupt::::steal() }; swi.reset(); unsafe { diff --git a/esp-hal/src/etm.rs b/esp-hal/src/etm.rs index 5b7370ce7ca..b148067bdc2 100644 --- a/esp-hal/src/etm.rs +++ b/esp-hal/src/etm.rs @@ -18,8 +18,8 @@ //! a particular Event to a particular Task. When an event is activated, the ETM //! channel will trigger the corresponding task automatically. //! -//! More information: -//! +//! For more information, please refer to the +#![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/etm.html)")] //! ## Example //! ```no_run //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); diff --git a/esp-hal/src/mcpwm/timer.rs b/esp-hal/src/mcpwm/timer.rs index 0ed21105277..be50577ab1e 100644 --- a/esp-hal/src/mcpwm/timer.rs +++ b/esp-hal/src/mcpwm/timer.rs @@ -17,7 +17,7 @@ use crate::{ /// A MCPWM timer /// -/// Every timer of a particular [`MCPWM`](super::MCPWM) peripheral can be used +/// Every timer of a particular [`MCPWM`](super::McPwm) peripheral can be used /// as a timing reference for every /// [`Operator`](super::operator::Operator) of that peripheral pub struct Timer { diff --git a/esp-hal/src/rmt.rs b/esp-hal/src/rmt.rs index 294e1c95d4c..70d098982f7 100644 --- a/esp-hal/src/rmt.rs +++ b/esp-hal/src/rmt.rs @@ -1,41 +1,41 @@ //! # Remote Control Peripheral (RMT) //! //! ## Overview -//! Some ESP32 bitss include a remote control peripheral (RMT) that -//! is designed to handle infrared remote control signals. For that -//! purpose, it can convert bitstreams of data (from the RAM) into -//! pulse codes and even modulate those codes into a carrier wave. +//! The RMT (Remote Control Transceiver) peripheral was designed to act as an +//! infrared transceiver. However, due to the flexibility of its data format, +//! RMT can be extended to a versatile and general-purpose transceiver, +//! transmitting or receiving many other types of signals. //! -//! It can also convert received pulse codes (again, with carrier -//! wave support) into data bits. //! -//! A secondary use case for this peripheral is to drive RGB(W) LEDs -//! that bear an internal IC and use a pulse code protocol. +//! Typically, the RMT peripheral can be used in the following scenarios: +//! - Transmit or receive infrared signals, with any IR protocols, e.g., NEC +//! - General-purpose sequence generator +//! - Transmit signals in a hardware-controlled loop, with a finite or infinite +//! number of times +//! - Modulate the carrier to the output signal or demodulate the carrier from +//! the input signal //! //! ## Channels -//! The RMT peripheral has the following channels available -//! on individual chips: -//! -//! * The **ESP32** has 8 channels, each of them can be either receiver or -//! transmitter -//! * The **ESP32-C3** has 4 channels, `Channel<0>` and `Channel<1>` hardcoded -//! for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for -//! receiving signals. -//! * The **ESP32-C6** has 4 channels, `Channel<0>` and `Channel<1>` hardcoded -//! for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for -//! receiving signals. -//! * The **ESP32-H2** has 4 channels, `Channel<0>` and `Channel<1>` hardcoded -//! for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for -//! receiving signals. -//! * The **ESP32-S2** has 4 channels, each of them can be either receiver or -//! transmitter. -//! * The **ESP32-S3** has 8 channels, `Channel<0>`-`Channel<3>` hardcoded for -//! transmitting signals and `Channel<4>`-`Channel<7>` hardcoded for receiving -//! signals. -//! -//! For more information, please refer to the ESP-IDF documentation: -//! -//! +//! There are +#![cfg_attr( + esp32, + doc = "8 channels, each of them can be either receiver or transmitter" +)] +#![cfg_attr( + esp32s2, + doc = "4 channels, each of them can be either receiver or transmitter" +)] +#![cfg_attr( + esp32s3, + doc = "8 channels, `Channel<0>`-`Channel<3>` hardcoded for transmitting signals and `Channel<4>`-`Channel<7>` hardcoded for receiving signals" +)] +#![cfg_attr( + any(esp32c3, esp32c6, esp32h2), + doc = "4 channels, `Channel<0>` and `Channel<1>` hardcoded for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for receiving signals." +)] +#![doc = " "] +//! For more information, please refer to the +#![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/rmt.html)")] //! ## Examples //! //! ### Initialization @@ -82,6 +82,7 @@ //! let transaction = channel.transmit(&data); //! channel = transaction.wait().unwrap(); //! ``` +#![warn(missing_docs)] use core::marker::PhantomData; @@ -97,12 +98,17 @@ use crate::{ system::PeripheralClockControl, }; +/// Errors #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// The desired frequency is impossible to reach UnreachableTargetFrequency, + /// The amount of pulses exceeds the size of the FIFO Overflow, + /// An argument is invalid InvalidArgument, + /// An error occurred during transmission TransmissionError, } @@ -211,7 +217,7 @@ impl<'d, M> Rmt<'d, M> where M: crate::Mode, { - pub fn new_internal( + pub(crate) fn new_internal( peripheral: impl Peripheral

+ 'd, frequency: HertzU32, _clocks: &Clocks, @@ -295,6 +301,7 @@ impl<'d> Rmt<'d, crate::Async> { } } +/// Creates a TX channel pub trait TxChannelCreator<'d, T, P> where P: OutputPin, @@ -325,6 +332,7 @@ where } } +/// Creates a TX channel in async mode #[cfg(feature = "async")] pub trait TxChannelCreatorAsync<'d, T, P> where @@ -356,6 +364,7 @@ where } } +/// Creates a RX channel pub trait RxChannelCreator<'d, T, P> where P: InputPin, @@ -401,6 +410,7 @@ where } } +/// Creates a RX channel in async mode #[cfg(feature = "async")] pub trait RxChannelCreatorAsync<'d, T, P> where @@ -573,6 +583,7 @@ where Ok(self.channel) } + /// Check if the `loopcount` interrupt bit is set pub fn is_loopcount_interrupt_set(&self) -> bool { >::is_loopcount_interrupt_set() } @@ -634,6 +645,7 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance + #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, @@ -700,6 +712,7 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance + #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, @@ -806,6 +819,7 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance + #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, @@ -880,6 +894,7 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance + #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, @@ -972,6 +987,7 @@ where phantom: PhantomData, } +/// Channel in TX mode pub trait TxChannel: private::TxChannelInternal { /// Start transmitting the given pulse code sequence. /// This returns a [`SingleShotTxTransaction`] which can be used to wait for @@ -1064,6 +1080,7 @@ where } } +/// Channel is RX mode pub trait RxChannel: private::RxChannelInternal { /// Start receiving pulse codes into the given buffer. /// This returns a [RxTransaction] which can be used to wait for receive to @@ -1086,6 +1103,7 @@ pub trait RxChannel: private::RxChannelInternal { } } +/// Async functionality #[cfg(feature = "async")] pub mod asynch { use core::{ @@ -1141,6 +1159,7 @@ pub mod asynch { } } + /// TX channel in async mode pub trait TxChannelAsync: private::TxChannelInternal { /// Start transmitting the given pulse code sequence. /// The length of sequence cannot exceed the size of the allocated RMT @@ -1202,6 +1221,7 @@ pub mod asynch { } } + /// RX channel in async mode pub trait RxChannelAsync: private::RxChannelInternal { /// Start receiving a pulse code sequence. /// The length of sequence cannot exceed the size of the allocated RMT diff --git a/esp-hal/src/rng.rs b/esp-hal/src/rng.rs index 389aa695e21..98e61709bf8 100644 --- a/esp-hal/src/rng.rs +++ b/esp-hal/src/rng.rs @@ -39,9 +39,8 @@ //! If none of the above conditions are true, the output of the RNG should be //! considered pseudo-random only. //! -//! For more information, please refer to the ESP-IDF documentation: -//! -//! +//! For more information, please refer to the +#![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/system/random.html)")] //! # Examples //! //! ## Initialization diff --git a/esp-hal/src/soc/esp32/mod.rs b/esp-hal/src/soc/esp32/mod.rs index 544f2a9e612..c97a73fa08f 100644 --- a/esp-hal/src/soc/esp32/mod.rs +++ b/esp-hal/src/soc/esp32/mod.rs @@ -18,6 +18,14 @@ pub mod peripherals; pub mod psram; pub mod radio_clocks; +macro_rules! chip { + () => { + "esp32" + }; +} + +pub(crate) use chip; + pub(crate) mod constants { pub const I2S_SCLK: u32 = 160_000_000; pub const I2S_DEFAULT_CLK_SRC: u32 = 2; diff --git a/esp-hal/src/soc/esp32c2/mod.rs b/esp-hal/src/soc/esp32c2/mod.rs index 057a32cb9a2..341332b9074 100644 --- a/esp-hal/src/soc/esp32c2/mod.rs +++ b/esp-hal/src/soc/esp32c2/mod.rs @@ -13,6 +13,14 @@ pub mod gpio; pub mod peripherals; pub mod radio_clocks; +macro_rules! chip { + () => { + "esp32c2" + }; +} + +pub(crate) use chip; + #[allow(unused)] pub(crate) mod registers { pub const INTERRUPT_MAP_BASE: u32 = 0x600c2000; diff --git a/esp-hal/src/soc/esp32c3/mod.rs b/esp-hal/src/soc/esp32c3/mod.rs index c24827218db..b461679a849 100644 --- a/esp-hal/src/soc/esp32c3/mod.rs +++ b/esp-hal/src/soc/esp32c3/mod.rs @@ -17,6 +17,14 @@ pub mod gpio; pub mod peripherals; pub mod radio_clocks; +macro_rules! chip { + () => { + "esp32c2" + }; +} + +pub(crate) use chip; + #[allow(unused)] pub(crate) mod registers { pub const INTERRUPT_MAP_BASE: u32 = 0x600c2000; diff --git a/esp-hal/src/soc/esp32c6/mod.rs b/esp-hal/src/soc/esp32c6/mod.rs index 97c0025b66b..ef49ce117ce 100644 --- a/esp-hal/src/soc/esp32c6/mod.rs +++ b/esp-hal/src/soc/esp32c6/mod.rs @@ -19,6 +19,14 @@ pub mod lp_core; pub mod peripherals; pub mod radio_clocks; +macro_rules! chip { + () => { + "esp32c6" + }; +} + +pub(crate) use chip; + #[allow(unused)] pub(crate) mod registers { pub const INTERRUPT_MAP_BASE: u32 = 0x60010000; diff --git a/esp-hal/src/soc/esp32h2/mod.rs b/esp-hal/src/soc/esp32h2/mod.rs index f94ed271780..a7a0bac0b0f 100644 --- a/esp-hal/src/soc/esp32h2/mod.rs +++ b/esp-hal/src/soc/esp32h2/mod.rs @@ -18,6 +18,14 @@ pub mod gpio; pub mod peripherals; pub mod radio_clocks; +macro_rules! chip { + () => { + "esp32h2" + }; +} + +pub(crate) use chip; + #[allow(unused)] pub(crate) mod registers { pub const INTERRUPT_MAP_BASE: u32 = 0x60010000; diff --git a/esp-hal/src/soc/esp32s2/mod.rs b/esp-hal/src/soc/esp32s2/mod.rs index 19e322ae4fd..f7b30243a23 100644 --- a/esp-hal/src/soc/esp32s2/mod.rs +++ b/esp-hal/src/soc/esp32s2/mod.rs @@ -23,6 +23,14 @@ pub mod radio_clocks; pub mod ulp_core; +macro_rules! chip { + () => { + "esp32s2" + }; +} + +pub(crate) use chip; + pub(crate) mod constants { pub const I2S_SCLK: u32 = 160_000_000; pub const I2S_DEFAULT_CLK_SRC: u32 = 2; diff --git a/esp-hal/src/soc/esp32s3/mod.rs b/esp-hal/src/soc/esp32s3/mod.rs index 7234df070d9..2f2acaed91a 100644 --- a/esp-hal/src/soc/esp32s3/mod.rs +++ b/esp-hal/src/soc/esp32s3/mod.rs @@ -24,6 +24,14 @@ pub mod radio_clocks; pub mod ulp_core; +macro_rules! chip { + () => { + "esp32s3" + }; +} + +pub(crate) use chip; + pub(crate) mod constants { pub const I2S_SCLK: u32 = 160_000_000; pub const I2S_DEFAULT_CLK_SRC: u8 = 2; diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs index b6db955a991..a3d882d2e8e 100644 --- a/esp-hal/src/spi/master.rs +++ b/esp-hal/src/spi/master.rs @@ -417,7 +417,7 @@ where /// sequential transfers are performed. This function will return before /// all bytes of the last chunk to transmit have been sent to the wire. If /// you must ensure that the whole messages was written correctly, use - /// [`Self::flush`]. + /// `flush`. pub fn write_bytes(&mut self, words: &[u8]) -> Result<(), Error> { self.spi.write_bytes(words)?; self.spi.flush()?; diff --git a/esp-hal/src/time.rs b/esp-hal/src/time.rs index 4f1c4d23a59..126838696e0 100644 --- a/esp-hal/src/time.rs +++ b/esp-hal/src/time.rs @@ -10,10 +10,10 @@ /// /// The counter won’t measure time in sleep-mode. /// -/// The timer will wrap after: -/// - ESP32 = 36_558 years, -/// - ESP32-S2 = 7_311 years, -/// - others = > 7 years +/// The timer will wrap after +#[cfg_attr(esp32, doc = "36_558 years")] +#[cfg_attr(esp32s2, doc = "7_311 years")] +#[cfg_attr(not(any(esp32, esp32s2)), doc = "more than 7 years")] pub fn current_time() -> fugit::Instant { #[cfg(esp32)] let (ticks, div) = {