itsscb/esp-hal
1
0
Fork 0
mirror of https://github.com/esp-rs/esp-hal.git synced 2025-09-28 04:40:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Assorted doc improvements (#1507)

Browse Source 
* Assorted doc improvements

* Fix `missing_docs`

* Remove unnecessary `mut`

* Chip specific ESP-IDF link for ETM and RNG

* Move `chip!` macro to soc-module
This commit is contained in:
Björn Quentin 2024-04-24 14:59:51 +02:00 committed by GitHub
parent 373735f96a
commit c77f48388a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
14 changed files with 119 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
esp-hal/src/embassy/executor/interrupt.rs
View File

@ -54,7 +54,7 @@ impl CallbackContext {
}
fn handle_interrupt<const NUM: u8>() {
let mut swi = unsafe { SoftwareInterrupt::<NUM>::steal() };
let swi = unsafe { SoftwareInterrupt::<NUM>::steal() };
swi.reset();
unsafe {

4
esp-hal/src/etm.rs
View File

@ -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: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-reference/peripherals/etm.html>
//!
//! 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);

2
esp-hal/src/mcpwm/timer.rs
View File

@ -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<const TIM: u8, PWM> {

84
esp-hal/src/rmt.rs
View File

@ -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:
//! <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/rmt.html>
//!
//! 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<P = crate::peripherals::RMT> + '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 {
<C as private::TxChannelInternal<crate::Blocking>>::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<M>,
}
/// Channel in TX mode
pub trait TxChannel: private::TxChannelInternal<crate::Blocking> {
/// 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<crate::Blocking> {
/// 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<crate::Blocking> {
}
}
/// 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<crate::Async> {
/// 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<crate::Async> {
/// Start receiving a pulse code sequence.
/// The length of sequence cannot exceed the size of the allocated RMT

5
esp-hal/src/rng.rs
View File

@ -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:
//! <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html>
//!
//! 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

8
esp-hal/src/soc/esp32/mod.rs
View File

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

8
esp-hal/src/soc/esp32c2/mod.rs
View File

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

8
esp-hal/src/soc/esp32c3/mod.rs
View File

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

8
esp-hal/src/soc/esp32c6/mod.rs
View File

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

8
esp-hal/src/soc/esp32h2/mod.rs
View File

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

8
esp-hal/src/soc/esp32s2/mod.rs
View File

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

8
esp-hal/src/soc/esp32s3/mod.rs
View File

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

2
esp-hal/src/spi/master.rs
View File

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

8
esp-hal/src/time.rs
View File

@ -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<u64, 1, 1_000_000> {
#[cfg(esp32)]
let (ticks, div) = {