From 39329646e86f8e51b85ed5085d479e6902120127 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov <konnor1980@yandex.ru> Date: Mon, 19 Aug 2024 10:32:25 +0200 Subject: [PATCH] Get rid of missing docs in a number of modules --- esp-backtrace/src/riscv.rs | 50 +++++++++- esp-backtrace/src/xtensa.rs | 82 +++++++++++++++- esp-hal/src/dma/mod.rs | 17 +++- esp-hal/src/ecc.rs | 20 +++- esp-hal/src/etm.rs | 8 +- esp-hal/src/gpio/etm.rs | 17 +++- esp-hal/src/gpio/mod.rs | 17 +++- esp-hal/src/hmac.rs | 16 ++- esp-hal/src/i2c.rs | 49 +++++++++- esp-hal/src/i2s.rs | 32 +++++- esp-hal/src/interrupt/riscv.rs | 49 +++++++++- esp-hal/src/interrupt/xtensa.rs | 38 +++++++- esp-hal/src/lcd_cam/cam.rs | 32 ++++++ esp-hal/src/lcd_cam/lcd/i8080.rs | 20 ++++ esp-hal/src/lcd_cam/lcd/mod.rs | 17 ++++ esp-hal/src/lcd_cam/mod.rs | 7 +- esp-hal/src/ledc/channel.rs | 16 +++ esp-hal/src/ledc/mod.rs | 5 +- esp-hal/src/ledc/timer.rs | 32 ++++++ esp-hal/src/otg_fs.rs | 8 +- esp-hal/src/parl_io.rs | 11 ++- esp-hal/src/pcnt/channel.rs | 8 ++ esp-hal/src/pcnt/mod.rs | 3 +- esp-hal/src/pcnt/unit.rs | 12 ++- esp-hal/src/peripheral.rs | 5 + esp-hal/src/rmt.rs | 28 +++++- esp-hal/src/rsa/esp32.rs | 12 +++ esp-hal/src/rsa/esp32cX.rs | 12 +++ esp-hal/src/rsa/esp32sX.rs | 11 +++ esp-hal/src/rsa/mod.rs | 59 +++++++---- esp-hal/src/rtc_cntl/mod.rs | 4 +- esp-hal/src/rtc_cntl/rtc/esp32.rs | 1 + esp-hal/src/rtc_cntl/rtc/esp32c2.rs | 1 + esp-hal/src/rtc_cntl/rtc/esp32c3.rs | 1 + esp-hal/src/rtc_cntl/rtc/esp32c6.rs | 1 + esp-hal/src/rtc_cntl/rtc/esp32h2.rs | 1 + esp-hal/src/rtc_cntl/rtc/esp32s2.rs | 1 + esp-hal/src/rtc_cntl/rtc/esp32s3.rs | 1 + esp-hal/src/rtc_cntl/sleep/esp32.rs | 32 +++++- esp-hal/src/rtc_cntl/sleep/esp32c3.rs | 64 +++++++++++- esp-hal/src/rtc_cntl/sleep/esp32c6.rs | 58 ++++++++++- esp-hal/src/rtc_cntl/sleep/esp32s3.rs | 40 +++++++- esp-hal/src/rtc_cntl/sleep/mod.rs | 28 ++++++ esp-hal/src/soc/esp32/cpu_control.rs | 6 ++ esp-hal/src/soc/esp32/efuse/mod.rs | 10 ++ esp-hal/src/soc/esp32/gpio.rs | 1 + esp-hal/src/soc/esp32/mod.rs | 10 +- esp-hal/src/soc/esp32/psram.rs | 6 ++ esp-hal/src/soc/esp32/trng.rs | 7 +- esp-hal/src/soc/esp32c2/efuse/mod.rs | 1 + esp-hal/src/soc/esp32c2/gpio.rs | 1 + esp-hal/src/soc/esp32c2/mod.rs | 3 + esp-hal/src/soc/esp32c2/trng.rs | 3 + esp-hal/src/soc/esp32c3/efuse/mod.rs | 1 + esp-hal/src/soc/esp32c3/gpio.rs | 1 + esp-hal/src/soc/esp32c3/mod.rs | 9 ++ esp-hal/src/soc/esp32c3/trng.rs | 3 + esp-hal/src/soc/esp32c6/efuse/mod.rs | 1 + esp-hal/src/soc/esp32c6/gpio.rs | 1 + esp-hal/src/soc/esp32c6/lp_core.rs | 3 + esp-hal/src/soc/esp32c6/mod.rs | 13 ++- esp-hal/src/soc/esp32c6/trng.rs | 5 +- esp-hal/src/soc/esp32h2/efuse/mod.rs | 1 + esp-hal/src/soc/esp32h2/gpio.rs | 1 + esp-hal/src/soc/esp32h2/mod.rs | 12 +++ esp-hal/src/soc/esp32h2/trng.rs | 3 + esp-hal/src/soc/esp32s2/efuse/mod.rs | 1 + esp-hal/src/soc/esp32s2/gpio.rs | 1 + esp-hal/src/soc/esp32s2/mod.rs | 10 +- esp-hal/src/soc/esp32s2/psram.rs | 5 + esp-hal/src/soc/esp32s2/trng.rs | 5 +- esp-hal/src/soc/esp32s2/ulp_core.rs | 5 + esp-hal/src/soc/esp32s3/cpu_control.rs | 6 ++ esp-hal/src/soc/esp32s3/efuse/mod.rs | 1 + esp-hal/src/soc/esp32s3/gpio.rs | 1 + esp-hal/src/soc/esp32s3/mod.rs | 12 +++ esp-hal/src/soc/esp32s3/psram.rs | 10 ++ esp-hal/src/soc/esp32s3/trng.rs | 5 +- esp-hal/src/soc/esp32s3/ulp_core.rs | 6 ++ esp-hal/src/soc/mod.rs | 4 +- esp-hal/src/timer/mod.rs | 7 +- esp-hal/src/twai/filter.rs | 9 ++ esp-hal/src/twai/mod.rs | 130 +++++++++++++++---------- esp-riscv-rt/src/lib.rs | 50 +++++++++- 84 files changed, 1154 insertions(+), 142 deletions(-) diff --git a/esp-backtrace/src/riscv.rs b/esp-backtrace/src/riscv.rs index 06d666174ee..50aae2bf17e 100644 --- a/esp-backtrace/src/riscv.rs +++ b/esp-backtrace/src/riscv.rs @@ -12,45 +12,93 @@ pub(super) const RA_OFFSET: usize = 4; /// Registers saved in trap handler #[doc(hidden)] -#[allow(missing_docs)] #[derive(Default, Clone, Copy)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[repr(C)] pub(crate) struct TrapFrame { + /// Return address, stores the address to return to after a function call or + /// interrupt. pub ra: usize, + /// Temporary register t0, used for intermediate values. pub t0: usize, + /// Temporary register t1, used for intermediate values. pub t1: usize, + /// Temporary register t2, used for intermediate values. pub t2: usize, + /// Temporary register t3, used for intermediate values. pub t3: usize, + /// Temporary register t4, used for intermediate values. pub t4: usize, + /// Temporary register t5, used for intermediate values. pub t5: usize, + /// Temporary register t6, used for intermediate values. pub t6: usize, + /// Argument register a0, typically used to pass the first argument to a + /// function. pub a0: usize, + /// Argument register a1, typically used to pass the second argument to a + /// function. pub a1: usize, + /// Argument register a2, typically used to pass the third argument to a + /// function. pub a2: usize, + /// Argument register a3, typically used to pass the fourth argument to a + /// function. pub a3: usize, + /// Argument register a4, typically used to pass the fifth argument to a + /// function. pub a4: usize, + /// Argument register a5, typically used to pass the sixth argument to a + /// function. pub a5: usize, + /// Argument register a6, typically used to pass the seventh argument to a + /// function. pub a6: usize, + /// Argument register a7, typically used to pass the eighth argument to a + /// function. pub a7: usize, + /// Saved register s0, used to hold values across function calls. pub s0: usize, + /// Saved register s1, used to hold values across function calls. pub s1: usize, + /// Saved register s2, used to hold values across function calls. pub s2: usize, + /// Saved register s3, used to hold values across function calls. pub s3: usize, + /// Saved register s4, used to hold values across function calls. pub s4: usize, + /// Saved register s5, used to hold values across function calls. pub s5: usize, + /// Saved register s6, used to hold values across function calls. pub s6: usize, + /// Saved register s7, used to hold values across function calls. pub s7: usize, + /// Saved register s8, used to hold values across function calls. pub s8: usize, + /// Saved register s9, used to hold values across function calls. pub s9: usize, + /// Saved register s10, used to hold values across function calls. pub s10: usize, + /// Saved register s11, used to hold values across function calls. pub s11: usize, + /// Global pointer register, holds the address of the global data area. pub gp: usize, + /// Thread pointer register, holds the address of the thread-local storage + /// area. pub tp: usize, + /// Stack pointer register, holds the address of the top of the stack. pub sp: usize, + /// Program counter, stores the address of the next instruction to be + /// executed. pub pc: usize, + /// Machine status register, holds the current status of the processor, + /// including interrupt enable bits and privilege mode. pub mstatus: usize, + /// Machine cause register, contains the reason for the trap (e.g., + /// exception or interrupt number). pub mcause: usize, + /// Machine trap value register, contains additional information about the + /// trap (e.g., faulting address). pub mtval: usize, } diff --git a/esp-backtrace/src/xtensa.rs b/esp-backtrace/src/xtensa.rs index 64b8287ef6d..e22e1b5a938 100644 --- a/esp-backtrace/src/xtensa.rs +++ b/esp-backtrace/src/xtensa.rs @@ -9,8 +9,8 @@ use crate::MAX_BACKTRACE_ADDRESSES; #[cfg(feature = "panic-handler")] pub(super) const RA_OFFSET: usize = 3; +/// Exception Cause #[doc(hidden)] -#[allow(missing_docs)] #[derive(Debug, Clone, Copy)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[repr(C)] @@ -95,89 +95,165 @@ pub enum ExceptionCause { Cp6Disabled = 38, /// Access To Coprocessor 7 When Disabled Cp7Disabled = 39, - + /// None None = 255, } #[doc(hidden)] -#[allow(missing_docs, non_snake_case)] +#[allow(non_snake_case)] #[derive(Clone, Copy)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[repr(C)] pub struct Context { + /// Program counter, stores the address of the next instruction to be + /// executed. pub PC: u32, + /// Processor status, holds various status flags for the CPU. pub PS: u32, + /// General-purpose register A0 used for data storage and manipulation. pub A0: u32, + /// General-purpose register A1 used for data storage and manipulation. pub A1: u32, + /// General-purpose register A2 used for data storage and manipulation. pub A2: u32, + /// General-purpose register A3 used for data storage and manipulation. pub A3: u32, + /// General-purpose register A4 used for data storage and manipulation. pub A4: u32, + /// General-purpose register A5 used for data storage and manipulation. pub A5: u32, + /// General-purpose register A6 used for data storage and manipulation. pub A6: u32, + /// General-purpose register A7 used for data storage and manipulation. pub A7: u32, + /// General-purpose register A8 used for data storage and manipulation. pub A8: u32, + /// General-purpose register A9 used for data storage and manipulation. pub A9: u32, + /// General-purpose register A10 used for data storage and manipulation. pub A10: u32, + /// General-purpose register A11 used for data storage and manipulation. pub A11: u32, + /// General-purpose register A12 used for data storage and manipulation. pub A12: u32, + /// General-purpose register A13 used for data storage and manipulation. pub A13: u32, + /// General-purpose register A14 used for data storage and manipulation. pub A14: u32, + /// General-purpose register A15 used for data storage and manipulation. pub A15: u32, + /// Shift amount register, used for shift and rotate instructions. pub SAR: u32, + /// Exception cause, indicates the reason for the last exception. pub EXCCAUSE: u32, + /// Exception address, holds the address related to the exception. pub EXCVADDR: u32, + /// Loop start address, used in loop instructions. pub LBEG: u32, + /// Loop end address, used in loop instructions. pub LEND: u32, + /// Loop counter, used to count iterations in loop instructions. pub LCOUNT: u32, + /// Thread pointer, used for thread-local storage. pub THREADPTR: u32, + /// Compare register, used for certain compare instructions. pub SCOMPARE1: u32, + /// Break register, used for breakpoint-related operations. pub BR: u32, + /// Accumulator low register, used for extended arithmetic operations. pub ACCLO: u32, + /// Accumulator high register, used for extended arithmetic operations. pub ACCHI: u32, + /// Additional register M0 used for special operations. pub M0: u32, + /// Additional register M1 used for special operations. pub M1: u32, + /// Additional register M2 used for special operations. pub M2: u32, + /// Additional register M3 used for special operations. pub M3: u32, + /// 64-bit floating-point register (low part), available if the + /// `print-float-registers` feature is enabled. #[cfg(feature = "print-float-registers")] pub F64R_LO: u32, + /// 64-bit floating-point register (high part), available if the + /// `print-float-registers` feature is enabled. #[cfg(feature = "print-float-registers")] pub F64R_HI: u32, + /// Floating-point status register, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F64S: u32, + /// Floating-point control register, available if the + /// `print-float-registers` feature is enabled. #[cfg(feature = "print-float-registers")] pub FCR: u32, + /// Floating-point status register, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub FSR: u32, + /// Floating-point register F0, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F0: u32, + /// Floating-point register F1, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F1: u32, + /// Floating-point register F2, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F2: u32, + /// Floating-point register F3, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F3: u32, + /// Floating-point register F4, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F4: u32, + /// Floating-point register F5, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F5: u32, + /// Floating-point register F6, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F6: u32, + /// Floating-point register F7, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F7: u32, + /// Floating-point register F8, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F8: u32, + /// Floating-point register F9, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F9: u32, + /// Floating-point register F10, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F10: u32, + /// Floating-point register F11, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F11: u32, + /// Floating-point register F12, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F12: u32, + /// Floating-point register F13, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F13: u32, + /// Floating-point register F14, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F14: u32, + /// Floating-point register F15, available if the `print-float-registers` + /// feature is enabled. #[cfg(feature = "print-float-registers")] pub F15: u32, } diff --git a/esp-hal/src/dma/mod.rs b/esp-hal/src/dma/mod.rs index 4adf05d97b7..071f80f77f9 100644 --- a/esp-hal/src/dma/mod.rs +++ b/esp-hal/src/dma/mod.rs @@ -521,17 +521,26 @@ pub enum DmaError { #[cfg(gdma)] #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] -#[allow(missing_docs)] pub enum DmaPriority { + /// The lowest priority level (Priority 0). Priority0 = 0, + /// Priority level 1. Priority1 = 1, + /// Priority level 2. Priority2 = 2, + /// Priority level 3. Priority3 = 3, + /// Priority level 4. Priority4 = 4, + /// Priority level 5. Priority5 = 5, + /// Priority level 6. Priority6 = 6, + /// Priority level 7. Priority7 = 7, + /// Priority level 8. Priority8 = 8, + /// The highest priority level (Priority 9). Priority9 = 9, } @@ -540,8 +549,8 @@ pub enum DmaPriority { #[cfg(pdma)] #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] -#[allow(missing_docs)] pub enum DmaPriority { + /// The lowest priority level (Priority 0). Priority0 = 0, } @@ -858,10 +867,12 @@ impl DescriptorChain { /// Block size for transfers to/from psram #[derive(Copy, Clone, Debug, PartialEq)] -#[allow(missing_docs)] pub enum DmaExtMemBKSize { + /// External memory block size of 16 bytes. Size16 = 0, + /// External memory block size of 32 bytes. Size32 = 1, + /// External memory block size of 64 bytes. Size64 = 2, } diff --git a/esp-hal/src/ecc.rs b/esp-hal/src/ecc.rs index e094deb2bf9..7097f604187 100644 --- a/esp-hal/src/ecc.rs +++ b/esp-hal/src/ecc.rs @@ -25,8 +25,6 @@ //! //! [ECC]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/ecc.rs -#![allow(missing_docs)] // TODO: Remove when able - use core::marker::PhantomData; use crate::{ @@ -55,30 +53,47 @@ pub enum Error { PointNotOnSelectedCurve, } +/// Represents supported elliptic curves for cryptographic operations. pub enum EllipticCurve { + /// The P-192 elliptic curve, a 192-bit curve. P192 = 0, + /// The P-256 elliptic curve. a 256-bit curve. P256 = 1, } #[derive(Clone)] +/// Represents the operational modes for elliptic curve or modular arithmetic +/// computations. pub enum WorkMode { + /// Point multiplication mode. PointMultiMode = 0, #[cfg(esp32c2)] + /// Division mode. DivisionMode = 1, + /// Point verification mode. PointVerif = 2, + /// Point verification and multiplication mode. PointVerifMulti = 3, + /// Jacobian point multiplication mode. JacobianPointMulti = 4, #[cfg(esp32h2)] + /// Point addition mode. PointAdd = 5, + /// Jacobian point verification mode. JacobianPointVerif = 6, + /// Point verification and multiplication in Jacobian coordinates. PointVerifJacobianMulti = 7, #[cfg(esp32h2)] + /// Modular addition mode. ModAdd = 8, #[cfg(esp32h2)] + /// Modular subtraction mode. ModSub = 9, #[cfg(esp32h2)] + /// Modular multiplication mode. ModMulti = 10, #[cfg(esp32h2)] + /// Modular multiplication mode. ModDiv = 11, } @@ -111,6 +126,7 @@ impl<'d> InterruptConfigurable for Ecc<'d, crate::Blocking> { } impl<'d, DM: crate::Mode> Ecc<'d, DM> { + /// Resets the ECC peripheral. pub fn reset(&mut self) { self.ecc.mult_conf().reset() } diff --git a/esp-hal/src/etm.rs b/esp-hal/src/etm.rs index 2b016fa456f..1e8322c1852 100644 --- a/esp-hal/src/etm.rs +++ b/esp-hal/src/etm.rs @@ -61,8 +61,6 @@ //! # } //! ``` -#![allow(missing_docs)] // TODO: Remove when able - use crate::{ peripheral::{Peripheral, PeripheralRef}, system::PeripheralClockControl, @@ -144,10 +142,14 @@ macro_rules! create_etm { /// Provides access to all the [EtmChannel] pub struct Etm<'d> { _peripheral: PeripheralRef<'d, crate::peripherals::SOC_ETM>, - $(pub [< channel $num >]: EtmChannel<$num>,)+ + $( + /// An individual ETM channel, identified by its index number. + pub [< channel $num >]: EtmChannel<$num>, + )+ } impl<'d> Etm<'d> { + /// Creates a new `Etm` instance. pub fn new(peripheral: impl Peripheral<P = crate::peripherals::SOC_ETM> + 'd) -> Self { crate::into_ref!(peripheral); diff --git a/esp-hal/src/gpio/etm.rs b/esp-hal/src/gpio/etm.rs index 2c99f21d8ed..7cfe6d8b6ab 100644 --- a/esp-hal/src/gpio/etm.rs +++ b/esp-hal/src/gpio/etm.rs @@ -60,24 +60,39 @@ use crate::{ /// All the GPIO ETM channels #[non_exhaustive] -#[allow(missing_docs)] pub struct GpioEtmChannels<'d> { _gpio_sd: PeripheralRef<'d, crate::peripherals::GPIO_SD>, + /// Task channel 0 for triggering GPIO tasks. pub channel0_task: GpioEtmTaskChannel<0>, + /// Event channel 0 for handling GPIO events. pub channel0_event: GpioEtmEventChannel<0>, + /// Task channel 1 for triggering GPIO tasks. pub channel1_task: GpioEtmTaskChannel<1>, + /// Event channel 1 for handling GPIO events. pub channel1_event: GpioEtmEventChannel<1>, + /// Task channel 2 for triggering GPIO tasks. pub channel2_task: GpioEtmTaskChannel<2>, + /// Event channel 2 for handling GPIO events. pub channel2_event: GpioEtmEventChannel<2>, + /// Task channel 3 for triggering GPIO tasks. pub channel3_task: GpioEtmTaskChannel<3>, + /// Event channel 3 for handling GPIO events. pub channel3_event: GpioEtmEventChannel<3>, + /// Task channel 4 for triggering GPIO tasks. pub channel4_task: GpioEtmTaskChannel<4>, + /// Event channel 4 for handling GPIO events. pub channel4_event: GpioEtmEventChannel<4>, + /// Task channel 5 for triggering GPIO tasks. pub channel5_task: GpioEtmTaskChannel<5>, + /// Event channel 5 for handling GPIO events. pub channel5_event: GpioEtmEventChannel<5>, + /// Task channel 6 for triggering GPIO tasks. pub channel6_task: GpioEtmTaskChannel<6>, + /// Event channel 6 for handling GPIO events. pub channel6_event: GpioEtmEventChannel<6>, + /// Task channel 7 for triggering GPIO tasks. pub channel7_task: GpioEtmTaskChannel<7>, + /// Event channel 7 for handling GPIO events. pub channel7_event: GpioEtmEventChannel<7>, } diff --git a/esp-hal/src/gpio/mod.rs b/esp-hal/src/gpio/mod.rs index 14465ea4a93..d6e796406e1 100644 --- a/esp-hal/src/gpio/mod.rs +++ b/esp-hal/src/gpio/mod.rs @@ -170,31 +170,40 @@ pub struct RtcOutput; pub struct Analog; /// Drive strength (values are approximates) -#[allow(missing_docs)] pub enum DriveStrength { + /// Drive strength of approximately 5mA. I5mA = 0, + /// Drive strength of approximately 10mA. I10mA = 1, + /// Drive strength of approximately 20mA. I20mA = 2, + /// Drive strength of approximately 40mA. I40mA = 3, } /// Alternate functions #[derive(PartialEq)] -#[allow(missing_docs)] pub enum AlternateFunction { + /// Alternate function 0. Function0 = 0, + /// Alternate function 1. Function1 = 1, + /// Alternate function 2. Function2 = 2, + /// Alternate function 3. Function3 = 3, + /// Alternate function 4. Function4 = 4, + /// Alternate function 5. Function5 = 5, } /// RTC function #[derive(PartialEq)] -#[allow(missing_docs)] pub enum RtcFunction { + /// RTC mode. Rtc = 0, + /// Digital mode. Digital = 1, } @@ -1390,9 +1399,9 @@ macro_rules! gpio { )+ /// Pins available on this chip - #[allow(missing_docs)] pub struct Pins { $( + /// GPIO pin number `$gpionum`. pub [< gpio $gpionum >] : GpioPin<$gpionum>, )+ } diff --git a/esp-hal/src/hmac.rs b/esp-hal/src/hmac.rs index 5016a189af9..a10f10c2fc2 100644 --- a/esp-hal/src/hmac.rs +++ b/esp-hal/src/hmac.rs @@ -34,8 +34,6 @@ //! //! [HMAC]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/hmac.rs -#![allow(missing_docs)] // TODO: Remove when able - use core::convert::Infallible; use crate::{ @@ -45,6 +43,9 @@ use crate::{ system::{Peripheral as PeripheralEnable, PeripheralClockControl}, }; +/// Provides an interface for interacting with the HMAC hardware peripheral. +/// It allows users to compute HMACs for cryptographic purposes, ensuring data +/// integrity and authenticity. pub struct Hmac<'d> { hmac: PeripheralRef<'d, HMAC>, alignment_helper: AlignmentHelper<SocDependentEndianess>, @@ -79,12 +80,19 @@ pub enum HmacPurpose { #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Represents the key identifiers for the HMAC peripheral. pub enum KeyId { + /// Key 0. Key0 = 0, + /// Key 1. Key1 = 1, + /// Key 2. Key2 = 2, + /// Key 3. Key3 = 3, + /// Key 4. Key4 = 4, + /// Key 5. Key5 = 5, } @@ -95,6 +103,7 @@ enum NextCommand { } impl<'d> Hmac<'d> { + /// Creates a new instance of the HMAC peripheral. pub fn new(hmac: impl Peripheral<P = HMAC> + 'd) -> Self { crate::into_ref!(hmac); @@ -109,6 +118,8 @@ impl<'d> Hmac<'d> { } } + /// Releases the HMAC peripheral, returning ownership of the `HMAC` + /// peripheral reference. pub fn free(self) -> PeripheralRef<'d, HMAC> { self.hmac } @@ -159,6 +170,7 @@ impl<'d> Hmac<'d> { Ok(remaining) } + /// Finalizes the HMAC computation and retrieves the resulting hash output. pub fn finalize(&mut self, output: &mut [u8]) -> nb::Result<(), Infallible> { if self.is_busy() { return Err(nb::Error::WouldBlock); diff --git a/esp-hal/src/i2c.rs b/esp-hal/src/i2c.rs index a2274b0b328..e2fc2b7dbf8 100644 --- a/esp-hal/src/i2c.rs +++ b/esp-hal/src/i2c.rs @@ -69,8 +69,6 @@ //! # } //! ``` -#![allow(missing_docs)] // TODO: Remove when able - use core::marker::PhantomData; use fugit::HertzU32; @@ -100,11 +98,17 @@ const MAX_ITERATIONS: u32 = 1_000_000; #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// The transmission exceeded the FIFO size. ExceedingFifo, + /// The acknowledgment check failed. AckCheckFailed, + /// A timeout occurred during transmission. TimeOut, + /// The arbitration for the bus was lost. ArbitrationLost, + /// The execution of the I2C command was incomplete. ExecIncomplete, + /// The number of commands issued exceeded the limit. CommandNrExceeded, } @@ -1010,19 +1014,29 @@ mod asynch { /// I2C Peripheral Instance pub trait Instance: crate::private::Sealed { + /// The identifier number for this I2C instance. const I2C_NUMBER: usize; + /// Returns the interrupt associated with this I2C peripheral. fn interrupt() -> crate::peripherals::Interrupt; + /// Returns the SCL output signal for this I2C peripheral. fn scl_output_signal(&self) -> OutputSignal; + /// Returns the SCL input signal for this I2C peripheral. fn scl_input_signal(&self) -> InputSignal; + /// Returns the SDA output signal for this I2C peripheral. fn sda_output_signal(&self) -> OutputSignal; + /// Returns the SDA input signal for this I2C peripheral. fn sda_input_signal(&self) -> InputSignal; + /// Returns a reference to the register block of the I2C peripheral. fn register_block(&self) -> &RegisterBlock; + /// Returns the I2C peripheral's index number. fn i2c_number(&self) -> usize; + /// Configures the I2C peripheral with the specified frequency, clocks, and + /// optional timeout. fn setup(&mut self, frequency: HertzU32, clocks: &Clocks<'_>, timeout: Option<u32>) { self.register_block().ctr().modify(|_, w| unsafe { // Clear register @@ -1339,6 +1353,7 @@ pub trait Instance: crate::private::Sealed { } #[allow(clippy::too_many_arguments, unused)] + /// Configures the clock and timing parameters for the I2C peripheral. fn configure_clock( &mut self, sclk_div: u32, @@ -1445,6 +1460,7 @@ pub trait Instance: crate::private::Sealed { } } + /// Configures the I2C peripheral for a write operation. fn setup_write<'a, I>(&self, addr: u8, bytes: &[u8], cmd_iterator: &mut I) -> Result<(), Error> where I: Iterator<Item = &'a COMD>, @@ -1475,6 +1491,7 @@ pub trait Instance: crate::private::Sealed { Ok(()) } + /// Configures the I2C peripheral for a read operation. fn setup_read<'a, I>( &self, addr: u8, @@ -1528,6 +1545,7 @@ pub trait Instance: crate::private::Sealed { } #[cfg(not(any(esp32, esp32s2)))] + /// Reads all bytes from the RX FIFO fn read_all_from_fifo(&self, buffer: &mut [u8]) -> Result<(), Error> { // Read bytes from FIFO // FIXME: Handle case where less data has been provided by the slave than @@ -1549,6 +1567,7 @@ pub trait Instance: crate::private::Sealed { } #[cfg(any(esp32, esp32s2))] + /// Reads all bytes from the RX FIFO fn read_all_from_fifo(&self, buffer: &mut [u8]) -> Result<(), Error> { // on ESP32/ESP32-S2 we currently don't support I2C transactions larger than the // FIFO apparently it would be possible by using non-fifo mode @@ -1573,12 +1592,14 @@ pub trait Instance: crate::private::Sealed { Ok(()) } + /// Clears all pending interrupts for the I2C peripheral. fn clear_all_interrupts(&self) { self.register_block() .int_clr() .write(|w| unsafe { w.bits(I2C_LL_INTR_MASK) }); } + /// Waits for the completion of an I2C transaction. fn wait_for_completion(&self, end_only: bool) -> Result<(), Error> { let mut tout = MAX_ITERATIONS; loop { @@ -1604,6 +1625,7 @@ pub trait Instance: crate::private::Sealed { Ok(()) } + /// Checks whether all I2C commands have completed execution. fn check_all_commands_done(&self) -> Result<(), Error> { // NOTE: on esp32 executing the end command generates the end_detect interrupt // but does not seem to clear the done bit! So we don't check the done @@ -1618,6 +1640,8 @@ pub trait Instance: crate::private::Sealed { Ok(()) } + + /// Checks for I2C transmission errors and handles them. fn check_errors(&self) -> Result<(), Error> { let interrupts = self.register_block().int_raw().read(); @@ -1658,6 +1682,7 @@ pub trait Instance: crate::private::Sealed { Ok(()) } + /// Updates the configuration of the I2C peripheral. fn update_config(&self) { // Ensure that the configuration of the peripheral is correctly propagated // (only necessary for C2, C3, C6, H2 and S3 variant) @@ -1667,6 +1692,7 @@ pub trait Instance: crate::private::Sealed { .modify(|_, w| w.conf_upgate().set_bit()); } + /// Starts an I2C transmission. fn start_transmission(&self) { // Start transmission self.register_block() @@ -1675,6 +1701,7 @@ pub trait Instance: crate::private::Sealed { } #[cfg(not(any(esp32, esp32s2)))] + /// Fills the TX FIFO with data from the provided slice. fn fill_tx_fifo(&self, bytes: &[u8]) -> usize { let mut index = 0; while index < bytes.len() @@ -1704,6 +1731,8 @@ pub trait Instance: crate::private::Sealed { } #[cfg(not(any(esp32, esp32s2)))] + /// Writes remaining data from byte slice to the TX FIFO from the specified + /// index. fn write_remaining_tx_fifo(&self, start_index: usize, bytes: &[u8]) -> Result<(), Error> { let mut index = start_index; loop { @@ -1743,6 +1772,7 @@ pub trait Instance: crate::private::Sealed { } #[cfg(any(esp32, esp32s2))] + /// Fills the TX FIFO with data from the provided slice. fn fill_tx_fifo(&self, bytes: &[u8]) -> usize { // on ESP32/ESP32-S2 we currently don't support I2C transactions larger than the // FIFO apparently it would be possible by using non-fifo mode @@ -1760,6 +1790,8 @@ pub trait Instance: crate::private::Sealed { } #[cfg(any(esp32, esp32s2))] + /// Writes remaining data from byte slice to the TX FIFO from the specified + /// index. fn write_remaining_tx_fifo(&self, start_index: usize, bytes: &[u8]) -> Result<(), Error> { // on ESP32/ESP32-S2 we currently don't support I2C transactions larger than the // FIFO apparently it would be possible by using non-fifo mode @@ -1838,6 +1870,7 @@ pub trait Instance: crate::private::Sealed { .write(|w| w.rxfifo_full().clear_bit_by_one()); } + /// Executes an I2C write operation. fn write_operation<'a, I>( &self, address: u8, @@ -1870,6 +1903,7 @@ pub trait Instance: crate::private::Sealed { Ok(()) } + /// Executes an I2C read operation. fn read_operation<'a, I>( &self, address: u8, @@ -1964,6 +1998,7 @@ pub trait Instance: crate::private::Sealed { } } +/// Adds a command to the I2C command sequence. fn add_cmd<'a, I>(cmd_iterator: &mut I, command: Command) -> Result<(), Error> where I: Iterator<Item = &'a COMD>, @@ -2139,12 +2174,19 @@ pub mod lp_i2c { #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// The transmission exceeded the FIFO size. ExceedingFifo, + /// The acknowledgment check failed. AckCheckFailed, + /// A timeout occurred during transmission. TimeOut, + /// The arbitration for the bus was lost. ArbitrationLost, + /// The execution of the I2C command was incomplete. ExecIncomplete, + /// The number of commands issued exceeded the limit. CommandNrExceeded, + /// The response received from the I2C device was invalid. InvalidResponse, } @@ -2197,11 +2239,13 @@ pub mod lp_i2c { // Configure LP_EXT_I2C_CK_EN high to enable the clock source of I2C_SCLK. // Adjust the timing registers accordingly when the clock frequency changes. + /// Represents a Low-Power I2C peripheral. pub struct LpI2c { i2c: LP_I2C0, } impl LpI2c { + /// Creates a new instance of the `LpI2c` peripheral. pub fn new( i2c: LP_I2C0, _sda: LowPowerOutputOpenDrain<'_, 6>, @@ -2444,6 +2488,7 @@ pub mod lp_i2c { self.i2c.ctr().modify(|_, w| w.conf_upgate().set_bit()); } + /// Resets the transmit and receive FIFO buffers. fn reset_fifo(&self) { self.i2c .fifo_conf() diff --git a/esp-hal/src/i2s.rs b/esp-hal/src/i2s.rs index d39c3a0c778..08f0f3a5b32 100644 --- a/esp-hal/src/i2s.rs +++ b/esp-hal/src/i2s.rs @@ -80,8 +80,6 @@ //! - Only master mode is supported. //! - Only TDM Philips standard is supported. -#![allow(missing_docs)] // TODO: Remove when able - use core::marker::PhantomData; use enumset::{EnumSet, EnumSetType}; @@ -121,12 +119,17 @@ use crate::{ }; #[derive(EnumSetType)] +/// Represents the various interrupt types for the I2S peripheral. pub enum I2sInterrupt { + /// Transmit buffer hung, indicating a stall in data transmission. TxHung, + /// Receive buffer hung, indicating a stall in data reception. RxHung, #[cfg(not(any(esp32, esp32s2)))] + /// Transmission of data is complete. TxDone, #[cfg(not(any(esp32, esp32s2)))] + /// Reception of data is complete. RxDone, } @@ -150,8 +153,11 @@ impl AcceptedWord for i32 {} #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// An unspecified or unknown error occurred during an I2S operation. Unknown, + /// A DMA-related error occurred during I2S operations. DmaError(DmaError), + /// An illegal or invalid argument was passed to an I2S function or method. IllegalArgument, } @@ -165,6 +171,7 @@ impl From<DmaError> for Error { #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Standard { + /// The Philips I2S standard. Philips, // Tdm, // Pdm, @@ -175,12 +182,19 @@ pub enum Standard { #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[cfg(not(any(esp32, esp32s2)))] pub enum DataFormat { + /// 32-bit data width and 32-bit channel width. Data32Channel32, + /// 32-bit data width and 24-bit channel width. Data32Channel24, + /// 32-bit data width and 16-bit channel width. Data32Channel16, + /// 32-bit data width and 8-bit channel width. Data32Channel8, + /// 16-bit data width and 16-bit channel width. Data16Channel16, + /// 16-bit data width and 8-bit channel width. Data16Channel8, + /// 8-bit data width and 8-bit channel width. Data8Channel8, } @@ -189,12 +203,15 @@ pub enum DataFormat { #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[cfg(any(esp32, esp32s2))] pub enum DataFormat { + /// 32-bit data width and 32-bit channel width. Data32Channel32, + /// 16-bit data width and 16-bit channel width. Data16Channel16, } #[cfg(not(any(esp32, esp32s2)))] impl DataFormat { + /// Returns the number of data bits for the selected data format. pub fn data_bits(&self) -> u8 { match self { DataFormat::Data32Channel32 => 32, @@ -207,6 +224,7 @@ impl DataFormat { } } + /// Returns the number of channel bits for the selected data format. pub fn channel_bits(&self) -> u8 { match self { DataFormat::Data32Channel32 => 32, @@ -222,6 +240,7 @@ impl DataFormat { #[cfg(any(esp32, esp32s2))] impl DataFormat { + /// Returns the number of data bits for the selected data format. pub fn data_bits(&self) -> u8 { match self { DataFormat::Data32Channel32 => 32, @@ -229,6 +248,7 @@ impl DataFormat { } } + /// Returns the number of channel bits for the selected data format. pub fn channel_bits(&self) -> u8 { match self { DataFormat::Data32Channel32 => 32, @@ -239,6 +259,7 @@ impl DataFormat { /// Blocking I2s Write pub trait I2sWrite<W> { + /// Writes a slice of data to the I2S peripheral. fn write(&mut self, words: &[W]) -> Result<(), Error>; } @@ -269,6 +290,8 @@ where /// Blocking I2S Read pub trait I2sRead<W> { + /// Reads a slice of data from the I2S peripheral and stores it in the + /// provided buffer. fn read(&mut self, words: &mut [W]) -> Result<(), Error>; } @@ -305,7 +328,9 @@ where CH: DmaChannel, DmaMode: Mode, { + /// Handles the transmission (TX) side of the I2S peripheral. pub i2s_tx: TxCreator<'d, I, CH, DmaMode>, + /// Handles the reception (RX) side of the I2S peripheral. pub i2s_rx: RxCreator<'d, I, CH, DmaMode>, phantom: PhantomData<DmaMode>, } @@ -481,6 +506,7 @@ where ) } + /// Configures the I2S peripheral to use a master clock (MCLK) output pin. pub fn with_mclk<P: OutputPin>(self, pin: impl Peripheral<P = P> + 'd) -> Self { into_ref!(pin); pin.set_to_push_pull_output(crate::private::Internal); @@ -850,6 +876,7 @@ where } } +/// Provides an abstraction for accessing the I2S peripheral registers. pub trait RegisterAccess: RegisterAccessPrivate {} mod private { @@ -2153,6 +2180,7 @@ mod private { } } +/// Async functionality #[cfg(feature = "async")] pub mod asynch { use super::{Error, I2sRx, I2sTx, RegisterAccess}; diff --git a/esp-hal/src/interrupt/riscv.rs b/esp-hal/src/interrupt/riscv.rs index 19e062ef5f8..5770ede1e86 100644 --- a/esp-hal/src/interrupt/riscv.rs +++ b/esp-hal/src/interrupt/riscv.rs @@ -53,38 +53,68 @@ pub enum InterruptKind { #[repr(u32)] #[derive(Debug, Copy, Clone)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] -#[allow(missing_docs)] pub enum CpuInterrupt { + /// Interrupt number 1. Interrupt1 = 1, + /// Interrupt number 2. Interrupt2, + /// Interrupt number 3. Interrupt3, + /// Interrupt number 4. Interrupt4, + /// Interrupt number 5. Interrupt5, + /// Interrupt number 6. Interrupt6, + /// Interrupt number 7. Interrupt7, + /// Interrupt number 8. Interrupt8, + /// Interrupt number 9. Interrupt9, + /// Interrupt number 10. Interrupt10, + /// Interrupt number 11. Interrupt11, + /// Interrupt number 12. Interrupt12, + /// Interrupt number 13. Interrupt13, + /// Interrupt number 14. Interrupt14, + /// Interrupt number 15. Interrupt15, + /// Interrupt number 16. Interrupt16, + /// Interrupt number 17. Interrupt17, + /// Interrupt number 18. Interrupt18, + /// Interrupt number 19. Interrupt19, + /// Interrupt number 20. Interrupt20, + /// Interrupt number 21. Interrupt21, + /// Interrupt number 22. Interrupt22, + /// Interrupt number 23. Interrupt23, + /// Interrupt number 24. Interrupt24, + /// Interrupt number 25. Interrupt25, + /// Interrupt number 26. Interrupt26, + /// Interrupt number 27. Interrupt27, + /// Interrupt number 28. Interrupt28, + /// Interrupt number 29. Interrupt29, + /// Interrupt number 30. Interrupt30, + /// Interrupt number 31. Interrupt31, } @@ -92,30 +122,45 @@ pub enum CpuInterrupt { #[derive(Copy, Clone, Debug, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[repr(u8)] -#[allow(missing_docs)] pub enum Priority { + /// No priority. None = 0, + /// Priority level 1. Priority1, + /// Priority level 2. Priority2, + /// Priority level 3. Priority3, + /// Priority level 4. Priority4, + /// Priority level 5. Priority5, + /// Priority level 6. Priority6, + /// Priority level 7. Priority7, + /// Priority level 8. #[cfg(not(clic))] Priority8, + /// Priority level 9. #[cfg(not(clic))] Priority9, + /// Priority level 10. #[cfg(not(clic))] Priority10, + /// Priority level 11. #[cfg(not(clic))] Priority11, + /// Priority level 12. #[cfg(not(clic))] Priority12, + /// Priority level 13. #[cfg(not(clic))] Priority13, + /// Priority level 14. #[cfg(not(clic))] Priority14, + /// Priority level 15. #[cfg(not(clic))] Priority15, } diff --git a/esp-hal/src/interrupt/xtensa.rs b/esp-hal/src/interrupt/xtensa.rs index 23382b03a63..7ae866ff0e2 100644 --- a/esp-hal/src/interrupt/xtensa.rs +++ b/esp-hal/src/interrupt/xtensa.rs @@ -27,39 +27,70 @@ pub enum Error { #[derive(Debug, Copy, Clone)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[repr(u32)] -#[allow(missing_docs)] pub enum CpuInterrupt { + /// Level-triggered interrupt with priority 1. Interrupt0LevelPriority1 = 0, + /// Level-triggered interrupt with priority 1. Interrupt1LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt2LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt3LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt4LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt5LevelPriority1, + /// Timer 0 interrupt with priority 1. Interrupt6Timer0Priority1, + /// Software-triggered interrupt with priority 1. Interrupt7SoftwarePriority1, + /// Level-triggered interrupt with priority 1. Interrupt8LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt9LevelPriority1, + /// Edge-triggered interrupt with priority 1. Interrupt10EdgePriority1, + /// Profiling-related interrupt with priority 3. Interrupt11ProfilingPriority3, + /// Level-triggered interrupt with priority 1. Interrupt12LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt13LevelPriority1, + /// Non-maskable interrupt (NMI) with priority 7. Interrupt14NmiPriority7, + /// Timer 1 interrupt with priority 3. Interrupt15Timer1Priority3, + /// Timer 2 interrupt with priority 5. Interrupt16Timer2Priority5, + /// Level-triggered interrupt with priority 1. Interrupt17LevelPriority1, + /// Level-triggered interrupt with priority 1. Interrupt18LevelPriority1, + /// Level-triggered interrupt with priority 2. Interrupt19LevelPriority2, + /// Level-triggered interrupt with priority 2. Interrupt20LevelPriority2, + /// Level-triggered interrupt with priority 2. Interrupt21LevelPriority2, + /// Edge-triggered interrupt with priority 3. Interrupt22EdgePriority3, + /// Level-triggered interrupt with priority 3. Interrupt23LevelPriority3, + /// Level-triggered interrupt with priority 4. Interrupt24LevelPriority4, + /// Level-triggered interrupt with priority 4. Interrupt25LevelPriority4, + /// Level-triggered interrupt with priority 5. Interrupt26LevelPriority5, + /// Level-triggered interrupt with priority 3. Interrupt27LevelPriority3, + /// Edge-triggered interrupt with priority 4. Interrupt28EdgePriority4, + /// Software-triggered interrupt with priority 3. Interrupt29SoftwarePriority3, + /// Edge-triggered interrupt with priority 4. Interrupt30EdgePriority4, + /// Edge-triggered interrupt with priority 5. Interrupt31EdgePriority5, } @@ -267,11 +298,14 @@ mod vectored { #[derive(Copy, Clone, Debug, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[repr(u8)] - #[allow(missing_docs)] pub enum Priority { + /// No priority. None = 0, + /// Priority level 1. Priority1, + /// Priority level 2. Priority2, + /// Priority level 3. Priority3, } diff --git a/esp-hal/src/lcd_cam/cam.rs b/esp-hal/src/lcd_cam/cam.rs index 111016d9110..a37a6f40fe3 100644 --- a/esp-hal/src/lcd_cam/cam.rs +++ b/esp-hal/src/lcd_cam/cam.rs @@ -102,20 +102,31 @@ pub enum EofMode { #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum VsyncFilterThreshold { + /// Requires 1 valid VSYNC pulse to trigger synchronization. One, + /// Requires 2 valid VSYNC pulse to trigger synchronization. Two, + /// Requires 3 valid VSYNC pulse to trigger synchronization. Three, + /// Requires 4 valid VSYNC pulse to trigger synchronization. Four, + /// Requires 5 valid VSYNC pulse to trigger synchronization. Five, + /// Requires 6 valid VSYNC pulse to trigger synchronization. Six, + /// Requires 7 valid VSYNC pulse to trigger synchronization. Seven, + /// Requires 8 valid VSYNC pulse to trigger synchronization. Eight, } +/// Represents the camera interface. pub struct Cam<'d> { + /// The LCD_CAM peripheral reference for managing the camera functionality. pub(crate) lcd_cam: PeripheralRef<'d, LCD_CAM>, } +/// Represents the camera interface with DMA support. pub struct Camera<'d, CH: DmaChannel> { lcd_cam: PeripheralRef<'d, LCD_CAM>, rx_channel: ChannelRx<'d, CH>, @@ -128,6 +139,7 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> where CH::P: LcdCamPeripheral, { + /// Creates a new `Camera` instance with DMA support. pub fn new<P: RxPins>( cam: Cam<'d>, mut channel: ChannelRx<'d, CH>, @@ -244,6 +256,7 @@ impl<'d, CH: DmaChannel> DmaSupportRx for Camera<'d, CH> { } impl<'d, CH: DmaChannel> Camera<'d, CH> { + /// Configures the byte order for the camera data. pub fn set_byte_order(&mut self, byte_order: ByteOrder) -> &mut Self { self.lcd_cam .cam_ctrl() @@ -251,6 +264,7 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self } + /// Configures the bit order for the camera data. pub fn set_bit_order(&mut self, bit_order: BitOrder) -> &mut Self { self.lcd_cam .cam_ctrl() @@ -258,6 +272,7 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self } + /// Configures the VSYNC filter threshold. pub fn set_vsync_filter(&mut self, threshold: Option<VsyncFilterThreshold>) -> &mut Self { if let Some(threshold) = threshold { let value = match threshold { @@ -285,6 +300,7 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self } + /// Configures the master clock (MCLK) pin for the camera interface. pub fn with_master_clock<MCLK: OutputPin>(self, mclk: impl Peripheral<P = MCLK> + 'd) -> Self { crate::into_ref!(mclk); mclk.set_to_push_pull_output(crate::private::Internal); @@ -292,6 +308,7 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self } + /// Configures the pixel clock (PCLK) pin for the camera interface. pub fn with_pixel_clock<PCLK: InputPin>(self, pclk: impl Peripheral<P = PCLK> + 'd) -> Self { crate::into_ref!(pclk); @@ -301,6 +318,8 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self } + /// Configures the control pins for the camera interface (VSYNC and + /// HENABLE). pub fn with_ctrl_pins<VSYNC: InputPin, HENABLE: InputPin>( self, vsync: impl Peripheral<P = VSYNC> + 'd, @@ -321,6 +340,8 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self } + /// Configures the control pins for the camera interface (VSYNC, HSYNC, and + /// HENABLE) with DE (data enable). pub fn with_ctrl_pins_and_de<VSYNC: InputPin, HSYNC: InputPin, HENABLE: InputPin>( self, vsync: impl Peripheral<P = VSYNC> + 'd, @@ -388,6 +409,7 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { self.rx_channel.start_transfer() } + /// Starts a DMA transfer to receive data from the camera peripheral. pub fn read_dma<'t, RXBUF: WriteBuffer>( &'t mut self, buf: &'t mut RXBUF, @@ -400,6 +422,8 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { Ok(DmaTransferRx::new(self)) } + /// Starts a circular DMA transfer to receive data from the camera + /// peripheral. pub fn read_dma_circular<'t, RXBUF: WriteBuffer>( &'t mut self, buf: &'t mut RXBUF, @@ -413,12 +437,16 @@ impl<'d, CH: DmaChannel> Camera<'d, CH> { } } +/// Represents an 8-bit wide camera data bus. +/// Is used to configure the camera interface to receive 8-bit data. pub struct RxEightBits { _pins: (), } impl RxEightBits { #[allow(clippy::too_many_arguments)] + /// Creates a new instance of `RxEightBits`, configuring the specified pins + /// as the 8-bit data bus. pub fn new<'d, P0, P1, P2, P3, P4, P5, P6, P7>( pin_0: impl Peripheral<P = P0> + 'd, pin_1: impl Peripheral<P = P1> + 'd, @@ -473,12 +501,16 @@ impl RxPins for RxEightBits { const BUS_WIDTH: usize = 1; } +/// Represents a 16-bit wide camera data bus. +/// Is used to configure the camera interface to receive 16-bit data. pub struct RxSixteenBits { _pins: (), } impl RxSixteenBits { #[allow(clippy::too_many_arguments)] + /// Creates a new instance of `RxSixteenBits`, configuring the specified + /// pins as the 16-bit data bus. pub fn new<'d, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10, P11, P12, P13, P14, P15>( pin_0: impl Peripheral<P = P0> + 'd, pin_1: impl Peripheral<P = P1> + 'd, diff --git a/esp-hal/src/lcd_cam/lcd/i8080.rs b/esp-hal/src/lcd_cam/lcd/i8080.rs index 288d5148410..0a67505bda9 100644 --- a/esp-hal/src/lcd_cam/lcd/i8080.rs +++ b/esp-hal/src/lcd_cam/lcd/i8080.rs @@ -91,6 +91,7 @@ use crate::{ Mode, }; +/// Represents the I8080 LCD interface. pub struct I8080<'d, CH: DmaChannel, P, DM: Mode> { lcd_cam: PeripheralRef<'d, LCD_CAM>, tx_channel: ChannelTx<'d, CH>, @@ -104,6 +105,7 @@ where CH::P: LcdCamPeripheral, P::Word: Into<u16>, { + /// Creates a new instance of the I8080 LCD interface. pub fn new( lcd: Lcd<'d, DM>, mut channel: ChannelTx<'d, CH>, @@ -287,6 +289,7 @@ impl<'d, CH: DmaChannel, P: TxPins, DM: Mode> I8080<'d, CH, P, DM> where P::Word: Into<u16>, { + /// Configures the byte order for data transmission. pub fn set_byte_order(&mut self, byte_order: ByteOrder) -> &mut Self { let is_inverted = byte_order != ByteOrder::default(); self.lcd_cam.lcd_user().modify(|_, w| { @@ -299,6 +302,7 @@ where self } + /// Configures the bit order for data transmission. pub fn set_bit_order(&mut self, bit_order: BitOrder) -> &mut Self { self.lcd_cam .lcd_user() @@ -306,6 +310,7 @@ where self } + /// Associates a CS pin with the I8080 interface. pub fn with_cs<CS: OutputPin>(self, cs: impl Peripheral<P = CS> + 'd) -> Self { crate::into_ref!(cs); cs.set_to_push_pull_output(crate::private::Internal); @@ -314,6 +319,7 @@ where self } + /// Configures the control pins for the I8080 interface. pub fn with_ctrl_pins<DC: OutputPin, WRX: OutputPin>( self, dc: impl Peripheral<P = DC> + 'd, @@ -331,6 +337,7 @@ where self } + /// Sends a command and data to the LCD using the I8080 interface. pub fn send( &mut self, cmd: impl Into<Command<P::Word>>, @@ -350,6 +357,7 @@ where Ok(()) } + /// Sends a command and data to the LCD using DMA. pub fn send_dma<'t, TXBUF>( &'t mut self, cmd: impl Into<Command<P::Word>>, @@ -374,6 +382,7 @@ impl<'d, CH: DmaChannel, P: TxPins> I8080<'d, CH, P, crate::Async> where P::Word: Into<u16>, { + /// Asynchronously sends a command and data to the LCD using DMA. pub async fn send_dma_async<'t, TXBUF>( &'t mut self, cmd: impl Into<Command<P::Word>>, @@ -517,7 +526,9 @@ impl<'d, CH: DmaChannel, P, DM: Mode> core::fmt::Debug for I8080<'d, CH, P, DM> #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Configuration settings for the I8080 interface. pub struct Config { + /// Specifies the clock mode, including polarity and phase settings. pub clock_mode: ClockMode, /// Setup cycles expected, must be at least 1. (6 bits) @@ -563,8 +574,11 @@ impl Default for Config { #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Command<T> { + /// Suppresses the command phase. No command is sent. None, + /// Sends a single-word command. One(T), + /// Sends a two-word command. Two(T, T), } @@ -574,6 +588,8 @@ impl<T> From<T> for Command<T> { } } +/// Represents a group of 8 output pins configured for 8-bit parallel data +/// transmission. pub struct TxEightBits<'d, P0, P1, P2, P3, P4, P5, P6, P7> { pin_0: PeripheralRef<'d, P0>, pin_1: PeripheralRef<'d, P1>, @@ -597,6 +613,7 @@ where P7: OutputPin, { #[allow(clippy::too_many_arguments)] + /// Creates a new `TxEightBits` instance with the provided output pins. pub fn new( pin_0: impl Peripheral<P = P0> + 'd, pin_1: impl Peripheral<P = P1> + 'd, @@ -670,6 +687,8 @@ where } } +/// Represents a group of 16 output pins configured for 16-bit parallel data +/// transmission. pub struct TxSixteenBits<'d, P0, P1, P2, P3, P4, P5, P6, P7, P8, P9, P10, P11, P12, P13, P14, P15> { pin_0: PeripheralRef<'d, P0>, pin_1: PeripheralRef<'d, P1>, @@ -710,6 +729,7 @@ where P15: OutputPin, { #[allow(clippy::too_many_arguments)] + /// Creates a new `TxSixteenBits` instance with the provided output pins. pub fn new( pin_0: impl Peripheral<P = P0> + 'd, pin_1: impl Peripheral<P = P1> + 'd, diff --git a/esp-hal/src/lcd_cam/lcd/mod.rs b/esp-hal/src/lcd_cam/lcd/mod.rs index a1e5dc85153..08ce3cdd413 100644 --- a/esp-hal/src/lcd_cam/lcd/mod.rs +++ b/esp-hal/src/lcd_cam/lcd/mod.rs @@ -14,36 +14,53 @@ use crate::{peripheral::PeripheralRef, peripherals::LCD_CAM}; pub mod i8080; +/// Represents an LCD interface peripheral. pub struct Lcd<'d, DM: crate::Mode> { + /// The `LCD_CAM` peripheral reference for managing the LCD functionality. pub(crate) lcd_cam: PeripheralRef<'d, LCD_CAM>, + + /// A marker for the mode of operation (blocking or asynchronous). pub(crate) _mode: core::marker::PhantomData<DM>, } #[derive(Debug, Clone, Copy, PartialEq, Default)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Represents the clock mode configuration for the LCD interface. pub struct ClockMode { + /// The polarity of the clock signal (idle high or low). pub polarity: Polarity, + + /// The phase of the clock signal (shift on the rising or falling edge). pub phase: Phase, } #[derive(Debug, Clone, Copy, PartialEq, Default)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Represents the polarity of the clock signal for the LCD interface. pub enum Polarity { + /// The clock signal is low when idle. #[default] IdleLow, + + /// The clock signal is high when idle. IdleHigh, } #[derive(Debug, Clone, Copy, PartialEq, Default)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Represents the phase of the clock signal for the LCD interface. pub enum Phase { + /// Data is shifted on the low (falling) edge of the clock signal. #[default] ShiftLow, + + /// Data is shifted on the high (rising) edge of the clock signal. ShiftHigh, } #[derive(Debug, Clone, Copy, PartialEq, Default)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] +/// Represents the delay mode for the LCD signal output. pub enum DelayMode { /// Output without delay. #[default] diff --git a/esp-hal/src/lcd_cam/mod.rs b/esp-hal/src/lcd_cam/mod.rs index 196f81e7646..3f9769693c9 100644 --- a/esp-hal/src/lcd_cam/mod.rs +++ b/esp-hal/src/lcd_cam/mod.rs @@ -5,7 +5,7 @@ //! used simultaneously. For more information on these modules, please refer to //! the documentation in their respective modules. -#![allow(missing_docs)] // TODO: Remove when able +// #![allow(missing_docs)] // TODO: Remove when able pub mod cam; pub mod lcd; @@ -21,12 +21,16 @@ use crate::{ InterruptConfigurable, }; +/// Represents a combined LCD and Camera interface peripheral. pub struct LcdCam<'d, DM: crate::Mode> { + /// The LCD interface. pub lcd: Lcd<'d, DM>, + /// The Camera interface. pub cam: Cam<'d>, } impl<'d> LcdCam<'d, crate::Blocking> { + /// Creates a new `LcdCam` instance. pub fn new(lcd_cam: impl Peripheral<P = LCD_CAM> + 'd) -> Self { crate::into_ref!(lcd_cam); @@ -63,6 +67,7 @@ impl<'d> InterruptConfigurable for LcdCam<'d, crate::Blocking> { #[cfg(feature = "async")] impl<'d> LcdCam<'d, crate::Async> { + /// Creates a new `LcdCam` instance for asynchronous operation. pub fn new_async(lcd_cam: impl Peripheral<P = LCD_CAM> + 'd) -> Self { crate::into_ref!(lcd_cam); diff --git a/esp-hal/src/ledc/channel.rs b/esp-hal/src/ledc/channel.rs index 21701ac82ba..aff67d1e6dc 100644 --- a/esp-hal/src/ledc/channel.rs +++ b/esp-hal/src/ledc/channel.rs @@ -48,15 +48,23 @@ pub enum Error { #[derive(PartialEq, Eq, Copy, Clone, Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Number { + /// Channel 0 Channel0 = 0, + /// Channel 1 Channel1 = 1, + /// Channel 2 Channel2 = 2, + /// Channel 3 Channel3 = 3, + /// Channel 4 Channel4 = 4, + /// Channel 5 Channel5 = 5, #[cfg(not(any(esp32c2, esp32c3, esp32c6, esp32h2)))] + /// Channel 6 Channel6 = 6, #[cfg(not(any(esp32c2, esp32c3, esp32c6, esp32h2)))] + /// Channel 7 Channel7 = 7, } @@ -66,16 +74,22 @@ pub mod config { #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] + /// Pin configuration for the LEDC channel. pub enum PinConfig { + /// Push-pull pin configuration. PushPull, + /// Open-drain pin configuration. OpenDrain, } /// Channel configuration #[derive(Copy, Clone)] pub struct Config<'a, S: TimerSpeed> { + /// A reference to the timer associated with this channel. pub timer: &'a dyn TimerIFace<S>, + /// The duty cycle percentage (0-100). pub duty_pct: u8, + /// The pin configuration (PushPull or OpenDrain). pub pin_config: PinConfig, } } @@ -108,6 +122,8 @@ pub trait ChannelHW<O: OutputPin> { /// Configure Channel HW except for the duty which is set via /// [`Self::set_duty_hw`]. fn configure_hw(&mut self) -> Result<(), Error>; + /// Configure the hardware for the channel with a specific pin + /// configuration. fn configure_hw_with_pin_config(&mut self, cfg: config::PinConfig) -> Result<(), Error>; /// Set channel duty HW diff --git a/esp-hal/src/ledc/mod.rs b/esp-hal/src/ledc/mod.rs index 006308f3d58..c935daec320 100644 --- a/esp-hal/src/ledc/mod.rs +++ b/esp-hal/src/ledc/mod.rs @@ -60,8 +60,6 @@ //! - Source clock selection is not supported //! - Interrupts are not supported -#![allow(missing_docs)] // TODO: Remove when able - use self::{ channel::Channel, timer::{Timer, TimerSpeed}, @@ -79,6 +77,7 @@ pub mod timer; /// Global slow clock source #[derive(PartialEq, Eq, Copy, Clone, Debug)] pub enum LSGlobalClkSource { + /// APB clock. APBClk, } @@ -96,7 +95,9 @@ pub struct HighSpeed {} /// Used to specify LowSpeed Timer/Channel pub struct LowSpeed {} +/// Trait representing the speed mode of a clock or peripheral. pub trait Speed { + /// Boolean constant indicating whether the speed is high-speed. const IS_HS: bool; } diff --git a/esp-hal/src/ledc/timer.rs b/esp-hal/src/ledc/timer.rs index 5c81489e8c7..dee5876b9b4 100644 --- a/esp-hal/src/ledc/timer.rs +++ b/esp-hal/src/ledc/timer.rs @@ -33,6 +33,7 @@ pub enum Error { #[derive(PartialEq, Eq, Copy, Clone, Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum HSClockSource { + /// APB clock. APBClk, // TODO RefTick, } @@ -41,6 +42,7 @@ pub enum HSClockSource { #[derive(PartialEq, Eq, Copy, Clone, Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum LSClockSource { + /// APB clock. APBClk, // TODO SLOWClk } @@ -49,9 +51,13 @@ pub enum LSClockSource { #[derive(PartialEq, Eq, Copy, Clone, Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Number { + /// Timer 0. Timer0 = 0, + /// Timer 1. Timer1 = 1, + /// Timer 2. Timer2 = 2, + /// Timer 3. Timer3 = 3, } @@ -63,56 +69,82 @@ pub mod config { #[derive(PartialEq, Eq, Copy, Clone, Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Duty { + /// 1-bit resolution for duty cycle adjustment. Duty1Bit = 1, + /// 2-bit resolution for duty cycle adjustment. Duty2Bit, + /// 3-bit resolution for duty cycle adjustment. Duty3Bit, + /// 4-bit resolution for duty cycle adjustment. Duty4Bit, + /// 5-bit resolution for duty cycle adjustment. Duty5Bit, + /// 6-bit resolution for duty cycle adjustment. Duty6Bit, + /// 7-bit resolution for duty cycle adjustment. Duty7Bit, + /// 8-bit resolution for duty cycle adjustment. Duty8Bit, + /// 9-bit resolution for duty cycle adjustment. Duty9Bit, + /// 10-bit resolution for duty cycle adjustment. Duty10Bit, + /// 11-bit resolution for duty cycle adjustment. Duty11Bit, + /// 12-bit resolution for duty cycle adjustment. Duty12Bit, + /// 13-bit resolution for duty cycle adjustment. Duty13Bit, + /// 14-bit resolution for duty cycle adjustment. Duty14Bit, #[cfg(esp32)] + /// 15-bit resolution for duty cycle adjustment. Duty15Bit, #[cfg(esp32)] + /// 16-bit resolution for duty cycle adjustment. Duty16Bit, #[cfg(esp32)] + /// 17-bit resolution for duty cycle adjustment. Duty17Bit, #[cfg(esp32)] + /// 18-bit resolution for duty cycle adjustment. Duty18Bit, #[cfg(esp32)] + /// 19-bit resolution for duty cycle adjustment. Duty19Bit, #[cfg(esp32)] + /// 20-bit resolution for duty cycle adjustment. Duty20Bit, } /// Timer configuration #[derive(Copy, Clone)] pub struct Config<CS> { + /// The duty cycle resolution. pub duty: Duty, + /// The clock source for the timer. pub clock_source: CS, + /// The frequency of the PWM signal in Hertz. pub frequency: HertzU32, } } /// Trait defining the type of timer source pub trait TimerSpeed: Speed { + /// The type of clock source used by the timer in this speed mode. type ClockSourceType; } /// Timer source type for LowSpeed timers impl TimerSpeed for LowSpeed { + /// The clock source type for low-speed timers. type ClockSourceType = LSClockSource; } #[cfg(esp32)] /// Timer source type for HighSpeed timers impl TimerSpeed for HighSpeed { + /// The clock source type for high-speed timers. type ClockSourceType = HSClockSource; } diff --git a/esp-hal/src/otg_fs.rs b/esp-hal/src/otg_fs.rs index 62132428b69..2a6eb23fc18 100644 --- a/esp-hal/src/otg_fs.rs +++ b/esp-hal/src/otg_fs.rs @@ -36,8 +36,6 @@ //! ## Implementation State //! - Low-speed (LS) is not supported. -#![allow(missing_docs)] // TODO: Remove when able - pub use esp_synopsys_usb_otg::UsbBus; use esp_synopsys_usb_otg::UsbPeripheral; @@ -49,16 +47,20 @@ use crate::{ }; #[doc(hidden)] +/// Trait representing the USB D+ (data plus) pin. pub trait UsbDp: crate::private::Sealed {} #[doc(hidden)] +/// Trait representing the USB D- (data minus) pin. pub trait UsbDm: crate::private::Sealed {} +/// USB peripheral. pub struct Usb<'d> { _usb0: PeripheralRef<'d, peripherals::USB0>, } impl<'d> Usb<'d> { + /// Creates a new `Usb` instance. pub fn new<P, M>( usb0: impl Peripheral<P = peripherals::USB0> + 'd, _usb_dp: impl Peripheral<P = P> + 'd, @@ -129,7 +131,7 @@ unsafe impl<'d> UsbPeripheral for Usb<'d> { 80_000_000 } } - +/// Asynch functionality #[cfg(feature = "async")] pub mod asynch { use embassy_usb_driver::{ diff --git a/esp-hal/src/parl_io.rs b/esp-hal/src/parl_io.rs index 309ac6a2254..72cfdd3ddc8 100644 --- a/esp-hal/src/parl_io.rs +++ b/esp-hal/src/parl_io.rs @@ -1096,14 +1096,17 @@ fn internal_clear_interrupts(interrupts: EnumSet<ParlIoInterrupt>) { /// Parallel IO in full duplex mode /// /// Full duplex mode might limit the maximum possible bit width. -#[allow(missing_docs)] pub struct ParlIoFullDuplex<'d, CH, DM> where CH: DmaChannel, CH::P: ParlIoPeripheral, DM: Mode, { + /// The transmitter (TX) channel responsible for handling DMA transfers in + /// the parallel I/O full-duplex operation. pub tx: TxCreatorFullDuplex<'d, CH, DM>, + /// The receiver (RX) channel responsible for handling DMA transfers in the + /// parallel I/O full-duplex operation. pub rx: RxCreatorFullDuplex<'d, CH, DM>, } @@ -1191,13 +1194,14 @@ where } /// Parallel IO in half duplex / TX only mode -#[allow(missing_docs)] pub struct ParlIoTxOnly<'d, CH, DM> where CH: DmaChannel, CH::P: ParlIoPeripheral, DM: Mode, { + /// The transmitter (TX) channel responsible for handling DMA transfers in + /// the parallel I/O operation. pub tx: TxCreator<'d, CH, DM>, } @@ -1279,13 +1283,14 @@ where } /// Parallel IO in half duplex / RX only mode -#[allow(missing_docs)] pub struct ParlIoRxOnly<'d, CH, DM> where CH: DmaChannel, CH::P: ParlIoPeripheral, DM: Mode, { + /// The receiver (RX) channel responsible for handling DMA transfers in the + /// parallel I/O operation. pub rx: RxCreator<'d, CH, DM>, } diff --git a/esp-hal/src/pcnt/channel.rs b/esp-hal/src/pcnt/channel.rs index 1e6ac296f70..d0a2782486e 100644 --- a/esp-hal/src/pcnt/channel.rs +++ b/esp-hal/src/pcnt/channel.rs @@ -39,6 +39,8 @@ pub struct PcntSource { } impl PcntSource { + /// Creates a `PcntSource` from an input pin with the specified + /// configuration. pub fn from_pin<'a, P: InputPin>( pin: impl Peripheral<P = P> + 'a, pin_config: PcntInputConfig, @@ -56,12 +58,16 @@ impl PcntSource { inverted: false, } } + + /// Creates a `PcntSource` that is always high. pub fn always_high() -> Self { Self { source: ONE_INPUT, inverted: false, } } + + /// Creates a `PcntSource` that is always low. pub fn always_low() -> Self { Self { source: ZERO_INPUT, @@ -69,6 +75,7 @@ impl PcntSource { } } + /// Inverts the `PcntSource` signal. pub fn invert(self) -> Self { Self { source: self.source, @@ -77,6 +84,7 @@ impl PcntSource { } } +/// Represents a channel within a pulse counter unit. pub struct Channel<'d, const UNIT: usize, const NUM: usize> { _phantom: PhantomData<&'d ()>, // Individual channels are not Send, since they share registers. diff --git a/esp-hal/src/pcnt/mod.rs b/esp-hal/src/pcnt/mod.rs index 36f7d6fdd09..4c4817c46cf 100644 --- a/esp-hal/src/pcnt/mod.rs +++ b/esp-hal/src/pcnt/mod.rs @@ -20,8 +20,6 @@ //! [unit]: unit/index.html //! [PCNT Encoder]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/pcnt_encoder.rs -#![allow(missing_docs)] // TODO: Remove when able - use self::unit::Unit; use crate::{ interrupt::{self, InterruptHandler}, @@ -34,6 +32,7 @@ use crate::{ pub mod channel; pub mod unit; +/// Pulse Counter (PCNT) peripheral driver. pub struct Pcnt<'d> { _instance: PeripheralRef<'d, peripherals::PCNT>, diff --git a/esp-hal/src/pcnt/unit.rs b/esp-hal/src/pcnt/unit.rs index 01e9c706eaa..1f0006f64e6 100644 --- a/esp-hal/src/pcnt/unit.rs +++ b/esp-hal/src/pcnt/unit.rs @@ -57,21 +57,30 @@ impl From<u8> for ZeroMode { } } -// Events +/// Events that can occur in a pulse counter unit. #[derive(Copy, Clone, Debug, Default)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct Events { + /// Set when the pulse counter reaches the low limit. pub low_limit: bool, + /// Set when the pulse counter reaches the high limit. pub high_limit: bool, + /// Set when the pulse counter crosses threshold 0. pub threshold0: bool, + /// Set when the pulse counter crosses threshold 1. pub threshold1: bool, + /// Set when the pulse counter reaches zero. pub zero: bool, } +/// Represents a pulse counter unit. #[non_exhaustive] pub struct Unit<'d, const NUM: usize> { + /// The counter for PCNT unit. pub counter: Counter<'d, NUM>, + /// The first channel in PCNT unit. pub channel0: Channel<'d, NUM, 0>, + /// The second channel in PCNT unit. pub channel1: Channel<'d, NUM, 1>, } @@ -301,6 +310,7 @@ impl<'d, const NUM: usize> Drop for Unit<'d, NUM> { // The entire Unit is Send but the individual channels are not. unsafe impl<'d, const NUM: usize> Send for Unit<'d, NUM> {} +/// Represents the counter within a pulse counter unit. #[derive(Clone)] pub struct Counter<'d, const NUM: usize> { _phantom: PhantomData<&'d ()>, diff --git a/esp-hal/src/peripheral.rs b/esp-hal/src/peripheral.rs index 05824c5a556..d92f8b4aa7e 100644 --- a/esp-hal/src/peripheral.rs +++ b/esp-hal/src/peripheral.rs @@ -272,10 +272,12 @@ mod peripheral_macros { $crate::impl_dma_eligible!(MEM2MEM15,Mem2Mem15); } + /// The `Peripherals` struct provides access to all of the hardware peripherals on the chip. #[allow(non_snake_case)] pub struct Peripherals { $( $(#[$cfg])? + /// Each field represents a hardware peripheral. pub $name: peripherals::$name, )* } @@ -325,6 +327,7 @@ mod peripheral_macros { impl peripherals::$name { $( paste::paste!{ + /// Binds an interrupt handler to the corresponding interrupt for this peripheral. pub fn [<bind_ $interrupt:lower _interrupt >](&mut self, handler: unsafe extern "C" fn() -> ()) { unsafe { $crate::interrupt::bind_interrupt($crate::peripherals::Interrupt::$interrupt, handler); } } @@ -355,6 +358,7 @@ mod peripheral_macros { $(#[$cfg])? #[derive(Debug)] #[allow(non_camel_case_types)] + /// Macro to create a peripheral structure with a virtual interface. pub struct $name { _inner: () } $(#[$cfg])? @@ -385,6 +389,7 @@ mod peripheral_macros { $(#[$cfg])? #[derive(Debug)] #[allow(non_camel_case_types)] + /// Macro to create a peripheral structure with a virtual interface. pub struct $name { _inner: () } $(#[$cfg])? diff --git a/esp-hal/src/rmt.rs b/esp-hal/src/rmt.rs index d283569903a..99929bc44fd 100644 --- a/esp-hal/src/rmt.rs +++ b/esp-hal/src/rmt.rs @@ -642,15 +642,18 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance - #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, { _peripheral: PeripheralRef<'d, crate::peripherals::RMT>, + /// RMT Channel 0. pub channel0: ChannelCreator<M, 0>, + /// RMT Channel 1. pub channel1: ChannelCreator<M, 1>, + /// RMT Channel 2. pub channel2: ChannelCreator<M, 2>, + /// RMT Channel 3. pub channel3: ChannelCreator<M, 3>, phantom: PhantomData<M>, } @@ -710,19 +713,26 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance - #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, { _peripheral: PeripheralRef<'d, crate::peripherals::RMT>, + /// RMT Channel 0. pub channel0: ChannelCreator<M, 0>, + /// RMT Channel 1. pub channel1: ChannelCreator<M, 1>, + /// RMT Channel 2. pub channel2: ChannelCreator<M, 2>, + /// RMT Channel 3. pub channel3: ChannelCreator<M, 3>, + /// RMT Channel 4. pub channel4: ChannelCreator<M, 4>, + /// RMT Channel 5. pub channel5: ChannelCreator<M, 5>, + /// RMT Channel 6. pub channel6: ChannelCreator<M, 6>, + /// RMT Channel 7. pub channel7: ChannelCreator<M, 7>, phantom: PhantomData<M>, } @@ -818,15 +828,18 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance - #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, { _peripheral: PeripheralRef<'d, crate::peripherals::RMT>, + /// RMT Channel 0. pub channel0: ChannelCreator<M, 0>, + /// RMT Channel 1. pub channel1: ChannelCreator<M, 1>, + /// RMT Channel 2. pub channel2: ChannelCreator<M, 2>, + /// RMT Channel 3. pub channel3: ChannelCreator<M, 3>, phantom: PhantomData<M>, } @@ -894,19 +907,26 @@ mod impl_for_chip { use crate::peripheral::{Peripheral, PeripheralRef}; /// RMT Instance - #[allow(missing_docs)] pub struct Rmt<'d, M> where M: crate::Mode, { _peripheral: PeripheralRef<'d, crate::peripherals::RMT>, + /// RMT Channel 0. pub channel0: ChannelCreator<M, 0>, + /// RMT Channel 1. pub channel1: ChannelCreator<M, 1>, + /// RMT Channel 2. pub channel2: ChannelCreator<M, 2>, + /// RMT Channel 3. pub channel3: ChannelCreator<M, 3>, + /// RMT Channel 4. pub channel4: ChannelCreator<M, 4>, + /// RMT Channel 5. pub channel5: ChannelCreator<M, 5>, + /// RMT Channel 6. pub channel6: ChannelCreator<M, 6>, + /// RMT Channel 7. pub channel7: ChannelCreator<M, 7>, phantom: PhantomData<M>, } diff --git a/esp-hal/src/rsa/esp32.rs b/esp-hal/src/rsa/esp32.rs index 22fad29f1a3..6cf1efde639 100644 --- a/esp-hal/src/rsa/esp32.rs +++ b/esp-hal/src/rsa/esp32.rs @@ -25,28 +25,35 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { Ok(()) } + /// Writes the multi-mode configuration to the RSA hardware. pub(super) fn write_multi_mode(&mut self, mode: u32) { self.rsa.mult_mode().write(|w| unsafe { w.bits(mode) }); } + /// Writes the modular exponentiation mode configuration to the RSA + /// hardware. pub(super) fn write_modexp_mode(&mut self, mode: u32) { self.rsa.modexp_mode().write(|w| unsafe { w.bits(mode) }); } + /// Starts the modular exponentiation operation. pub(super) fn write_modexp_start(&mut self) { self.rsa .modexp_start() .write(|w| w.modexp_start().set_bit()); } + /// Starts the multiplication operation. pub(super) fn write_multi_start(&mut self) { self.rsa.mult_start().write(|w| w.mult_start().set_bit()); } + /// Clears the RSA interrupt flag. pub(super) fn clear_interrupt(&mut self) { self.rsa.interrupt().write(|w| w.interrupt().set_bit()); } + /// Checks if the RSA peripheral is idle. pub(super) fn is_idle(&mut self) -> bool { self.rsa.interrupt().read().bits() == 1 } @@ -62,6 +69,7 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } +/// Module defining marker types for various RSA operand sizes. pub mod operand_sizes { //! Marker types for the operand sizes use paste::paste; @@ -165,10 +173,12 @@ where } } + /// Sets the modular exponentiation mode for the RSA hardware. pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) { rsa.write_modexp_mode((N / 16 - 1) as u32) } + /// Starts the modular exponentiation operation on the RSA hardware. pub(super) fn set_start(&mut self) { self.rsa.write_modexp_start(); } @@ -196,10 +206,12 @@ where self.set_start(); } + /// Sets the multiplication mode for the RSA hardware. pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) { rsa.write_multi_mode(((N * 2) / 16 + 7) as u32) } + /// Starts the multiplication operation on the RSA hardware. pub(super) fn set_start(&mut self) { self.rsa.write_multi_start(); } diff --git a/esp-hal/src/rsa/esp32cX.rs b/esp-hal/src/rsa/esp32cX.rs index e89edadaac6..b84135e2159 100644 --- a/esp-hal/src/rsa/esp32cX.rs +++ b/esp-hal/src/rsa/esp32cX.rs @@ -51,10 +51,12 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } + /// Checks if the search functionality is enabled in the RSA hardware. pub(super) fn is_search_enabled(&mut self) -> bool { self.rsa.search_enable().read().search_enable().bit_is_set() } + /// Sets the search position in the RSA hardware. pub(super) fn write_search_position(&mut self, search_position: u32) { self.rsa .search_pos() @@ -79,28 +81,33 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } + /// Starts the modular exponentiation operation. pub(super) fn write_modexp_start(&mut self) { self.rsa .set_start_modexp() .write(|w| w.set_start_modexp().set_bit()); } + /// Starts the multiplication operation. pub(super) fn write_multi_start(&mut self) { self.rsa .set_start_mult() .write(|w| w.set_start_mult().set_bit()); } + /// Starts the modular multiplication operation. fn write_modmulti_start(&mut self) { self.rsa .set_start_modmult() .write(|w| w.set_start_modmult().set_bit()); } + /// Clears the RSA interrupt flag. pub(super) fn clear_interrupt(&mut self) { self.rsa.int_clr().write(|w| w.clear_interrupt().set_bit()); } + /// Checks if the RSA peripheral is idle. pub(super) fn is_idle(&mut self) -> bool { self.rsa.query_idle().read().query_idle().bit_is_set() } @@ -110,6 +117,7 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } +/// Module defining marker types for various RSA operand sizes. pub mod operand_sizes { //! Marker types for the operand sizes use paste::paste; @@ -255,10 +263,12 @@ where 0 } + /// Sets the modular exponentiation mode for the RSA hardware. pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) { rsa.write_mode((N - 1) as u32) } + /// Starts the modular exponentiation operation on the RSA hardware. pub(super) fn set_start(&mut self) { self.rsa.write_modexp_start(); } @@ -335,10 +345,12 @@ where self.set_start(); } + /// Sets the multiplication mode for the RSA hardware. pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) { rsa.write_mode((N * 2 - 1) as u32) } + /// Starts the multiplication operation on the RSA hardware. pub(super) fn set_start(&mut self) { self.rsa.write_multi_start(); } diff --git a/esp-hal/src/rsa/esp32sX.rs b/esp-hal/src/rsa/esp32sX.rs index 31120033570..bc521333e8e 100644 --- a/esp-hal/src/rsa/esp32sX.rs +++ b/esp-hal/src/rsa/esp32sX.rs @@ -57,10 +57,12 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } + /// Checks if the search functionality is enabled in the RSA hardware. pub(super) fn is_search_enabled(&mut self) -> bool { self.rsa.search_enable().read().search_enable().bit_is_set() } + /// Sets the search position in the RSA hardware. pub(super) fn write_search_position(&mut self, search_position: u32) { self.rsa .search_pos() @@ -85,28 +87,33 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } + /// Starts the modular exponentiation operation. pub(super) fn write_modexp_start(&mut self) { self.rsa .modexp_start() .write(|w| w.modexp_start().set_bit()); } + /// Starts the multiplication operation. pub(super) fn write_multi_start(&mut self) { self.rsa.mult_start().write(|w| w.mult_start().set_bit()); } + /// Starts the modular multiplication operation. fn write_modmulti_start(&mut self) { self.rsa .modmult_start() .write(|w| w.modmult_start().set_bit()); } + /// Clears the RSA interrupt flag. pub(super) fn clear_interrupt(&mut self) { self.rsa .clear_interrupt() .write(|w| w.clear_interrupt().set_bit()); } + /// Checks if the RSA peripheral is idle. pub(super) fn is_idle(&mut self) -> bool { self.rsa.idle().read().idle().bit_is_set() } @@ -296,10 +303,12 @@ where 0 } + /// Sets the modular exponentiation mode for the RSA hardware. pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) { rsa.write_mode((N - 1) as u32) } + /// Starts the modular exponentiation operation on the RSA hardware. pub(super) fn set_start(&mut self) { self.rsa.write_modexp_start(); } @@ -376,10 +385,12 @@ where self.set_start(); } + /// Sets the multiplication mode for the RSA hardware. pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) { rsa.write_mode((N * 2 - 1) as u32) } + /// Starts the multiplication operation on the RSA hardware. pub(super) fn set_start(&mut self) { self.rsa.write_multi_start(); } diff --git a/esp-hal/src/rsa/mod.rs b/esp-hal/src/rsa/mod.rs index a9496b41d28..41139cf8e7f 100644 --- a/esp-hal/src/rsa/mod.rs +++ b/esp-hal/src/rsa/mod.rs @@ -34,8 +34,6 @@ //! [nb]: https://docs.rs/nb/1.1.0/nb/ //! [the repository with corresponding example]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/rsa.rs -#![allow(missing_docs)] // TODO: Remove when able - use core::{marker::PhantomData, ptr::copy_nonoverlapping}; use crate::{ @@ -141,38 +139,52 @@ impl<'d, DM: crate::Mode> Rsa<'d, DM> { } } +/// Defines an RSA operation mode. pub trait RsaMode: crate::private::Sealed { + /// The input data type used for the RSA operation. type InputType; } + +/// A trait for RSA operations that involve multiple inputs and outputs. pub trait Multi: RsaMode { + /// The type of the output produced by the RSA operation. type OutputType; } macro_rules! implement_op { (($x:literal, multi)) => { - paste! {pub struct [<Op $x>];} - paste! { - impl Multi for [<Op $x>] { - type OutputType = [u32; $x*2 / 32]; - }} - paste! { - impl crate::private::Sealed for [<Op $x>] {} - } - paste! { - impl RsaMode for [<Op $x>] { - type InputType = [u32; $x / 32]; - }} + paste! { + /// Represents an RSA operation for the given bit size with multi-output. + pub struct [<Op $x>]; + } + paste! { + impl Multi for [<Op $x>] { + type OutputType = [u32; $x * 2 / 32]; + } + } + paste! { + impl crate::private::Sealed for [<Op $x>] {} + } + paste! { + impl RsaMode for [<Op $x>] { + type InputType = [u32; $x / 32]; + } + } }; (($x:literal)) => { - paste! {pub struct [<Op $x>];} + paste! { + /// Represents an RSA operation for the given bit size. + pub struct [<Op $x>]; + } paste! { impl crate::private::Sealed for [<Op $x>] {} } - paste!{ - impl RsaMode for [<Op $x>] { - type InputType = [u32; $x / 32]; - }} + paste! { + impl RsaMode for [<Op $x>] { + type InputType = [u32; $x / 32]; + } + } }; ($x:tt, $($y:tt),+) => { @@ -286,6 +298,7 @@ where } } +/// Async functionality #[cfg(feature = "async")] pub(crate) mod asynch { use core::task::Poll; @@ -303,11 +316,13 @@ pub(crate) mod asynch { static WAKER: AtomicWaker = AtomicWaker::new(); + /// `Future` that waits for the RSA operation to complete. pub(crate) struct RsaFuture<'d> { instance: &'d crate::peripherals::RSA, } impl<'d> RsaFuture<'d> { + /// Asynchronously initializes the RSA peripheral. pub async fn new(instance: &'d crate::peripherals::RSA) -> Self { #[cfg(not(any(esp32, esp32s2, esp32s3)))] instance.int_ena().modify(|_, w| w.int_ena().set_bit()); @@ -360,6 +375,7 @@ pub(crate) mod asynch { where T: RsaMode<InputType = [u32; N]>, { + /// Asynchronously performs an RSA modular exponentiation operation. pub async fn exponentiation( &mut self, base: &T::InputType, @@ -377,6 +393,7 @@ pub(crate) mod asynch { T: RsaMode<InputType = [u32; N]>, { #[cfg(not(esp32))] + /// Asynchronously performs an RSA modular multiplication operation. pub async fn modular_multiplication( &mut self, r: &T::InputType, @@ -388,6 +405,7 @@ pub(crate) mod asynch { } #[cfg(esp32)] + /// Asynchronously performs an RSA modular multiplication operation. pub async fn modular_multiplication( &mut self, operand_a: &T::InputType, @@ -407,6 +425,7 @@ pub(crate) mod asynch { T: RsaMode<InputType = [u32; N]>, { #[cfg(not(esp32))] + /// Asynchronously performs an RSA multiplication operation. pub async fn multiplication<'b, const O: usize>( &mut self, operand_b: &T::InputType, @@ -420,6 +439,7 @@ pub(crate) mod asynch { } #[cfg(esp32)] + /// Asynchronously performs an RSA multiplication operation. pub async fn multiplication<'b, const O: usize>( &mut self, operand_a: &T::InputType, @@ -435,6 +455,7 @@ pub(crate) mod asynch { } #[handler] + /// Interrupt handler for RSA. pub(super) fn rsa_interrupt_handler() { #[cfg(not(any(esp32, esp32s2, esp32s3)))] unsafe { &*crate::peripherals::RSA::ptr() } diff --git a/esp-hal/src/rtc_cntl/mod.rs b/esp-hal/src/rtc_cntl/mod.rs index db6a056361f..505e2cbe4e2 100644 --- a/esp-hal/src/rtc_cntl/mod.rs +++ b/esp-hal/src/rtc_cntl/mod.rs @@ -69,8 +69,6 @@ //! } //! ``` -#![allow(missing_docs)] // TODO: Remove when able - #[cfg(not(any(esp32c6, esp32h2)))] use fugit::HertzU32; use fugit::MicrosDurationU64; @@ -186,8 +184,10 @@ pub(crate) enum RtcCalSel { /// Low-power Management pub struct Rtc<'d> { _inner: PeripheralRef<'d, crate::peripherals::LPWR>, + /// Reset Watchdog Timer. pub rwdt: Rwdt, #[cfg(any(esp32c2, esp32c3, esp32c6, esp32h2, esp32s3))] + /// Super Watchdog pub swd: Swd, } diff --git a/esp-hal/src/rtc_cntl/rtc/esp32.rs b/esp-hal/src/rtc_cntl/rtc/esp32.rs index 59fe4a85980..77a900dbaee 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32.rs @@ -34,6 +34,7 @@ pub(crate) fn configure_clock() { // Chip Reset: Reset the whole chip, including the analog part #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] +/// SOC Reset Reason. pub enum SocResetReason { /// Power on reset ChipPowerOn = 0x01, diff --git a/esp-hal/src/rtc_cntl/rtc/esp32c2.rs b/esp-hal/src/rtc_cntl/rtc/esp32c2.rs index ab9c7efc870..75eba0d45c2 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32c2.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32c2.rs @@ -201,6 +201,7 @@ fn rtc_sleep_pu() { // Chip Reset: Reset the whole chip, including the analog part #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] +/// SOC Reset Reason. pub enum SocResetReason { /// Power on reset ChipPowerOn = 0x01, diff --git a/esp-hal/src/rtc_cntl/rtc/esp32c3.rs b/esp-hal/src/rtc_cntl/rtc/esp32c3.rs index 0c795e9bab4..4c1b6c88da7 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32c3.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32c3.rs @@ -259,6 +259,7 @@ fn rtc_sleep_pu() { // System Reset: Reset the whole digital system, including RTC sub-system // Chip Reset: Reset the whole chip, including the analog part +/// SOC Reset Reason #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] pub enum SocResetReason { /// Power on reset diff --git a/esp-hal/src/rtc_cntl/rtc/esp32c6.rs b/esp-hal/src/rtc_cntl/rtc/esp32c6.rs index 2f888ed299b..76fcc86dbfa 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32c6.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32c6.rs @@ -1305,6 +1305,7 @@ fn modem_clk_domain_active_state_icg_map_preinit() { // System Reset: Reset the whole digital system, including RTC sub-system // Chip Reset: Reset the whole chip, including the analog part +/// SOC Reset Reason #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] pub enum SocResetReason { /// Power on reset diff --git a/esp-hal/src/rtc_cntl/rtc/esp32h2.rs b/esp-hal/src/rtc_cntl/rtc/esp32h2.rs index 22f6989f2a8..a8508533ded 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32h2.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32h2.rs @@ -149,6 +149,7 @@ pub(crate) fn configure_clock() { // System Reset: Reset the whole digital system, including RTC sub-system // Chip Reset: Reset the whole chip, including the analog part +/// SOC Reset Reason #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] pub enum SocResetReason { /// Power on reset diff --git a/esp-hal/src/rtc_cntl/rtc/esp32s2.rs b/esp-hal/src/rtc_cntl/rtc/esp32s2.rs index e27462d8376..bdb20c3a150 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32s2.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32s2.rs @@ -39,6 +39,7 @@ pub(crate) fn configure_clock() { // System Reset: Reset the whole digital system, including RTC sub-system // Chip Reset: Reset the whole chip, including the analog part +/// SOC Reset Reason #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] pub enum SocResetReason { /// Power on reset diff --git a/esp-hal/src/rtc_cntl/rtc/esp32s3.rs b/esp-hal/src/rtc_cntl/rtc/esp32s3.rs index 53364bafc09..3fd53123ba2 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32s3.rs +++ b/esp-hal/src/rtc_cntl/rtc/esp32s3.rs @@ -39,6 +39,7 @@ pub(crate) fn configure_clock() { // System Reset: Reset the whole digital system, including RTC sub-system // Chip Reset: Reset the whole chip, including the analog part +/// SOC reset reason #[derive(Debug, Clone, Copy, PartialEq, Eq, FromRepr)] pub enum SocResetReason { /// Power on reset diff --git a/esp-hal/src/rtc_cntl/sleep/esp32.rs b/esp-hal/src/rtc_cntl/sleep/esp32.rs index cfc70e67e2c..77435035172 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32.rs +++ b/esp-hal/src/rtc_cntl/sleep/esp32.rs @@ -7,38 +7,66 @@ use crate::{ // Approximate mapping of voltages to RTC_CNTL_DBIAS_WAK, RTC_CNTL_DBIAS_SLP, // RTC_CNTL_DIG_DBIAS_WAK, RTC_CNTL_DIG_DBIAS_SLP values. // Valid if RTC_CNTL_DBG_ATTEN is 0. +/// RTC digital bias setting corresponding to 0.90V. pub const RTC_CNTL_DBIAS_0V90: u8 = 0; +/// RTC digital bias setting corresponding to 0.95V. pub const RTC_CNTL_DBIAS_0V95: u8 = 1; +/// RTC digital bias setting corresponding to 1.00V. pub const RTC_CNTL_DBIAS_1V00: u8 = 2; +/// RTC digital bias setting corresponding to 1.05V. pub const RTC_CNTL_DBIAS_1V05: u8 = 3; +/// RTC digital bias setting corresponding to 1.10V. pub const RTC_CNTL_DBIAS_1V10: u8 = 4; +/// RTC digital bias setting corresponding to 1.15V. pub const RTC_CNTL_DBIAS_1V15: u8 = 5; +/// RTC digital bias setting corresponding to 1.20V. pub const RTC_CNTL_DBIAS_1V20: u8 = 6; +/// RTC digital bias setting corresponding to 1.25V. pub const RTC_CNTL_DBIAS_1V25: u8 = 7; + // Various delays to be programmed into power control state machines +/// Time (in microseconds) for waiting the XTL buffer to stabilize during sleep. pub const RTC_CNTL_XTL_BUF_WAIT_SLP_US: u32 = 1000; +/// Cycles to wait for PLL buffer stabilization. pub const RTC_CNTL_PLL_BUF_WAIT_SLP_CYCLES: u8 = 1; +/// Cycles to wait for the 8MHz clock to stabilize. pub const RTC_CNTL_CK8M_WAIT_SLP_CYCLES: u8 = 4; +/// Delay in cycles for wakeup signal to be applied. pub const RTC_CNTL_WAKEUP_DELAY_CYCLES: u8 = 7; +/// Power-up cycles for other blocks. pub const RTC_CNTL_OTHER_BLOCKS_POWERUP_CYCLES: u8 = 1; +/// Wait cycles for other blocks. pub const RTC_CNTL_OTHER_BLOCKS_WAIT_CYCLES: u16 = 1; +/// Minimum sleep value (in cycles). pub const RTC_CNTL_MIN_SLP_VAL_MIN: u8 = 128; +/// Default debug attenuation value. pub const RTC_CNTL_DBG_ATTEN_DEFAULT: u8 = 3; +/// Power-up cycles for RTC memory. pub const RTC_MEM_POWERUP_CYCLES: u8 = RTC_CNTL_OTHER_BLOCKS_POWERUP_CYCLES; +/// Wait cycles for RTC memory. pub const RTC_MEM_WAIT_CYCLES: u16 = RTC_CNTL_OTHER_BLOCKS_WAIT_CYCLES; +/// Power-up cycles for ROM and RAM. pub const ROM_RAM_POWERUP_CYCLES: u8 = RTC_CNTL_OTHER_BLOCKS_POWERUP_CYCLES; +/// Wait cycles for ROM and RAM. pub const ROM_RAM_WAIT_CYCLES: u16 = RTC_CNTL_OTHER_BLOCKS_WAIT_CYCLES; +/// Power-up cycles for Wi-Fi. pub const WIFI_POWERUP_CYCLES: u8 = RTC_CNTL_OTHER_BLOCKS_POWERUP_CYCLES; +/// Wait cycles for Wi-Fi. pub const WIFI_WAIT_CYCLES: u16 = RTC_CNTL_OTHER_BLOCKS_WAIT_CYCLES; +/// Power-up cycles for RTC components. pub const RTC_POWERUP_CYCLES: u8 = RTC_CNTL_OTHER_BLOCKS_POWERUP_CYCLES; +/// Wait cycles for RTC components. pub const RTC_WAIT_CYCLES: u16 = RTC_CNTL_OTHER_BLOCKS_WAIT_CYCLES; +/// Power-up cycles for the digital wrap components. pub const DG_WRAP_POWERUP_CYCLES: u8 = RTC_CNTL_OTHER_BLOCKS_POWERUP_CYCLES; +/// Wait cycles for the digital wrap components. pub const DG_WRAP_WAIT_CYCLES: u16 = RTC_CNTL_OTHER_BLOCKS_WAIT_CYCLES; +/// Default wait cycles for the 8MHz clock. pub const RTC_CNTL_CK8M_WAIT_DEFAULT: u8 = 20; +/// Default wait cycles to enable the 8MHz clock. pub const RTC_CK8M_ENABLE_WAIT_DEFAULT: u8 = 5; - impl WakeSource for TimerWakeupSource { fn apply( &self, @@ -162,6 +190,7 @@ impl Drop for Ext1WakeupSource<'_, '_> { bitfield::bitfield! { #[derive(Clone, Copy)] + /// Configuration for the RTC sleep behavior. pub struct RtcSleepConfig(u32); impl Debug; /// force normal voltage in sleep mode (digital domain memory) @@ -221,6 +250,7 @@ impl Default for RtcSleepConfig { } impl RtcSleepConfig { + /// Configures the RTC for deep sleep mode. pub fn deep() -> Self { let mut cfg = Self::default(); cfg.set_deep_slp(true); diff --git a/esp-hal/src/rtc_cntl/sleep/esp32c3.rs b/esp-hal/src/rtc_cntl/sleep/esp32c3.rs index e5a0c89eff6..77cb796ddb4 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32c3.rs +++ b/esp-hal/src/rtc_cntl/sleep/esp32c3.rs @@ -42,46 +42,83 @@ const I2C_ULP_HOSTID: u8 = 0; // Approximate mapping of voltages to RTC_CNTL_DBIAS_WAK, RTC_CNTL_DBIAS_SLP, // RTC_CNTL_DIG_DBIAS_WAK, RTC_CNTL_DIG_DBIAS_SLP values. // Valid if RTC_CNTL_DBG_ATTEN is 0. +/// Digital bias voltage level of 0.90V. pub const RTC_CNTL_DBIAS_0V90: u32 = 13; +/// Digital bias voltage level of 0.95V. pub const RTC_CNTL_DBIAS_0V95: u32 = 16; +/// Digital bias voltage level of 1.00V. pub const RTC_CNTL_DBIAS_1V00: u32 = 18; +/// Digital bias voltage level of 1.05V. pub const RTC_CNTL_DBIAS_1V05: u32 = 20; +/// Digital bias voltage level of 1.10V. pub const RTC_CNTL_DBIAS_1V10: u32 = 23; +/// Digital bias voltage level of 1.15V. pub const RTC_CNTL_DBIAS_1V15: u32 = 25; +/// Digital bias voltage level of 1.20V. pub const RTC_CNTL_DBIAS_1V20: u32 = 28; +/// Digital bias voltage level of 1.25V. pub const RTC_CNTL_DBIAS_1V25: u32 = 30; -pub const RTC_CNTL_DBIAS_1V30: u32 = 31; //< voltage is about 1.34v in fact +/// Digital bias voltage level of approximately 1.34V. +pub const RTC_CNTL_DBIAS_1V30: u32 = 31; +/// Default attenuation setting during light sleep, with a voltage drop. pub const RTC_CNTL_DBG_ATTEN_LIGHTSLEEP_DEFAULT: u8 = 5; +/// No attenuation (no voltage drop) during light sleep. pub const RTC_CNTL_DBG_ATTEN_LIGHTSLEEP_NODROP: u8 = 0; +/// Default attenuation setting during deep sleep, with maximum voltage drop. pub const RTC_CNTL_DBG_ATTEN_DEEPSLEEP_DEFAULT: u8 = 15; +/// No attenuation (no voltage drop) during deep sleep. pub const RTC_CNTL_DBG_ATTEN_DEEPSLEEP_NODROP: u8 = 0; + +/// Default bias setting during sleep mode. pub const RTC_CNTL_BIASSLP_SLEEP_DEFAULT: u8 = 1; +/// Keeps the bias for ultra-low power sleep mode always on. pub const RTC_CNTL_BIASSLP_SLEEP_ON: u8 = 0; + +/// Default power-down current setting during sleep mode. pub const RTC_CNTL_PD_CUR_SLEEP_DEFAULT: u8 = 1; +/// Keeps the power-down current setting for sleep mode always on. pub const RTC_CNTL_PD_CUR_SLEEP_ON: u8 = 0; + +/// Default driver bias setting for the digital domain during sleep mode. pub const RTC_CNTL_DG_VDD_DRV_B_SLP_DEFAULT: u8 = 254; +/// Default debug attenuation setting for the monitor mode. pub const RTC_CNTL_DBG_ATTEN_MONITOR_DEFAULT: u8 = 0; +/// Default bias setting for sleep mode in the monitor mode. pub const RTC_CNTL_BIASSLP_MONITOR_DEFAULT: bool = false; +/// Default power-down current setting for the monitor mode. pub const RTC_CNTL_PD_CUR_MONITOR_DEFAULT: bool = false; +/// Default number of cycles to wait for the PLL buffer to stabilize. pub const RTC_CNTL_PLL_BUF_WAIT_DEFAULT: u8 = 20; +/// Default number of cycles to wait for the XTL buffer to stabilize. pub const RTC_CNTL_XTL_BUF_WAIT_DEFAULT: u8 = 100; +/// Default number of cycles to wait for the internal 8MHz clock to stabilize. pub const RTC_CNTL_CK8M_WAIT_DEFAULT: u8 = 20; +/// Default number of cycles required to enable the internal 8MHz clock. pub const RTC_CK8M_ENABLE_WAIT_DEFAULT: u8 = 5; +/// Minimum number of cycles for sleep duration. pub const RTC_CNTL_MIN_SLP_VAL_MIN: u8 = 2; +/// Power-up cycles for other hardware blocks. pub const OTHER_BLOCKS_POWERUP: u8 = 1; +/// Wait cycles for other hardware blocks to stabilize. pub const OTHER_BLOCKS_WAIT: u16 = 1; +/// Disables GPIO interrupt. pub const GPIO_INTR_DISABLE: u8 = 0; +/// Sets GPIO interrupt to trigger on a low level signal. pub const GPIO_INTR_LOW_LEVEL: u8 = 4; +/// Sets GPIO interrupt to trigger on a high level signal. pub const GPIO_INTR_HIGH_LEVEL: u8 = 5; +/// Specifies the function configuration for GPIO pins. pub const PIN_FUNC_GPIO: u8 = 1; +/// Index for signaling GPIO output. pub const SIG_GPIO_OUT_IDX: u32 = 128; +/// Maximum number of GPIO pins supported. pub const GPIO_NUM_MAX: usize = 22; impl WakeSource for TimerWakeupSource { @@ -256,6 +293,7 @@ impl WakeSource for RtcioWakeupSource<'_, '_> { bitfield::bitfield! { #[derive(Clone, Copy)] + /// RTC Configuration. pub struct RtcConfig(u32); impl Debug; /// Number of rtc_fast_clk cycles to wait for 8M clock to be ready @@ -264,16 +302,19 @@ bitfield::bitfield! { pub u8, xtal_wait, set_xtal_wait: 15, 8; /// Number of rtc_fast_clk cycles to wait for PLL clock to be ready pub u8, pll_wait, set_pll_wait: 23, 16; - // Perform clock control related initialization. + /// Perform clock control related initialization. pub clkctl_init, set_clkctl_init: 24; - // Perform power control related initialization. + /// Perform power control related initialization. pub pwrctl_init, set_pwrctl_init: 25; - // Force power down RTC_DBOOST + /// Force power down RTC_DBOOST pub rtc_dboost_fpd, set_rtc_dboost_fpd: 26; + /// Keep the XTAL oscillator powered up in sleep. pub xtal_fpu, set_xtal_fpu: 27; + /// Keep the BBPLL oscillator powered up in sleep. pub bbpll_fpu, set_bbpll_fpu: 28; + /// Enable clock gating when the CPU is in wait-for-interrupt state. pub cpu_waiti_clk_gate, set_cpu_waiti_clk_gate: 29; - // Calibrate Ocode to make bandgap voltage more precise. + /// Calibrate Ocode to make bandgap voltage more precise. pub cali_ocode, set_cali_ocode: 30; } @@ -293,17 +334,28 @@ impl Default for RtcConfig { bitfield::bitfield! { #[derive(Clone, Copy)] + /// Configuration for RTC initialization. pub struct RtcInitConfig(u128); impl Debug; + /// Number of cycles required to power up WiFi pub u8, wifi_powerup_cycles, set_wifi_powerup_cycles: 6, 0; + /// Number of wait cycles for WiFi to stabilize pub u16, wifi_wait_cycles, set_wifi_wait_cycles: 15, 7; + /// Number of cycles required to power up Bluetooth pub u8, bt_powerup_cycles, set_bt_powerup_cycles: 22, 16; + /// Number of wait cycles for Bluetooth to stabilize pub u16, bt_wait_cycles, set_bt_wait_cycles: 31, 23; + /// Number of cycles required to power up the top CPU pub u8, cpu_top_powerup_cycles, set_cpu_top_powerup_cycles: 38, 32; + /// Number of wait cycles for the top CPU to stabilize pub u16, cpu_top_wait_cycles, set_cpu_top_wait_cycles: 47, 39; + /// Number of cycles required to power up the digital wrapper pub u8, dg_wrap_powerup_cycles, set_dg_wrap_powerup_cycles: 54, 48; + /// Number of wait cycles for the digital wrapper to stabilize pub u16, dg_wrap_wait_cycles, set_dg_wrap_wait_cycles: 63, 55; + /// Number of cycles required to power up the digital peripherals pub u8, dg_peri_powerup_cycles, set_dg_peri_powerup_cycles: 70, 64; + /// Number of wait cycles for the digital peripherals to stabilize pub u16, dg_peri_wait_cycles, set_dg_peri_wait_cycles: 79, 71; } @@ -326,6 +378,7 @@ impl Default for RtcInitConfig { bitfield::bitfield! { #[derive(Clone, Copy)] + /// Configuration for RTC sleep mode. pub struct RtcSleepConfig(u64); impl Debug; /// force normal voltage in sleep mode (digital domain memory) @@ -437,6 +490,7 @@ fn rtc_sleep_pu(val: bool) { } impl RtcSleepConfig { + /// Configures the RTC for deep sleep mode. pub fn deep() -> Self { // Set up for ultra-low power sleep. Wakeup sources may modify these settings. let mut cfg = Self::default(); diff --git a/esp-hal/src/rtc_cntl/sleep/esp32c6.rs b/esp-hal/src/rtc_cntl/sleep/esp32c6.rs index 3336bc34372..fb052aed945 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32c6.rs +++ b/esp-hal/src/rtc_cntl/sleep/esp32c6.rs @@ -160,11 +160,14 @@ impl WakeSource for WakeFromLpCoreWakeupSource { } } +/// Configuration for controlling the behavior during sleep modes. #[derive(Clone, Copy)] // pmu_sleep_analog_config_t pub struct AnalogSleepConfig { + /// High-power system configuration. pub hp_sys: HpAnalog, // pub lp_sys_active: LpAnalog, // unused + /// Low-power system analog configuration. pub lp_sys_sleep: LpAnalog, } @@ -298,9 +301,12 @@ impl AnalogSleepConfig { } } +/// Configuration for controlling the behavior of digital peripherals during +/// sleep modes. #[derive(Clone, Copy)] // pmu_sleep_digital_config_t pub struct DigitalSleepConfig { + /// High-power system control register configuration. pub syscntl: HpSysCntlReg, } @@ -329,11 +335,16 @@ impl DigitalSleepConfig { } } +/// Configuration for controlling the power settings of high-power and low-power +/// systems during sleep modes. #[derive(Clone, Copy)] // pmu_sleep_power_config_t pub struct PowerSleepConfig { + /// Power configuration for the high-power system during sleep. pub hp_sys: HpSysPower, + /// Power configuration for the low-power system when it is active. pub lp_sys_active: LpSysPower, + /// Power configuration for the low-power system when it is in sleep mode. pub lp_sys_sleep: LpSysPower, } @@ -424,42 +435,64 @@ impl PowerSleepConfig { } } +/// Parameters for high-power system configurations during sleep modes. #[derive(Clone, Copy)] // pmu_hp_param_t pub struct HpParam { + /// Number of cycles to wait for the modem to wake up. pub modem_wakeup_wait_cycle: u32, + /// Number of cycles to wait for the analog component stabilization. pub analog_wait_target_cycle: u16, + /// Number of cycles to wait for the digital power-down sequence. pub digital_power_down_wait_cycle: u16, + /// Number of cycles to wait for the digital power supply to stabilize. pub digital_power_supply_wait_cycle: u16, + /// Number of cycles to wait for the digital power-up sequence. pub digital_power_up_wait_cycle: u16, + /// Number of cycles to wait for the PLL to stabilize. pub pll_stable_wait_cycle: u16, + /// Number of cycles to wait for modifying the ICG control. pub modify_icg_cntl_wait_cycle: u8, + /// Number of cycles to wait for switching the ICG coйntrol. pub switch_icg_cntl_wait_cycle: u8, + /// Minimum sleep time measured in slow clock cycles. pub min_slp_slow_clk_cycle: u8, } +/// Parameters for low-power system configurations during sleep modes. #[derive(Clone, Copy)] // pmu_lp_param_t pub struct LpParam { + /// Number of cycles to wait for the digital power supply to stabilize. pub digital_power_supply_wait_cycle: u16, + /// Minimum sleep time measured in slow clock cycles. pub min_slp_slow_clk_cycle: u8, + /// Number of cycles to wait for the analog component stabilization. pub analog_wait_target_cycle: u8, + /// Number of cycles to wait for the digital power-down sequence. pub digital_power_down_wait_cycle: u8, + /// Number of cycles to wait for the digital power-up sequence. pub digital_power_up_wait_cycle: u8, } +/// Parameters for high-power and low-power system configurations during sleep +/// modes. #[derive(Clone, Copy)] // pmu_hp_lp_param_t pub struct HpLpParam { - // union of two u16 variants, I've elected to not complicate things... + /// Union of two u16 variants pub xtal_stable_wait_cycle: u16, } +/// Configuration of parameters for sleep modes #[derive(Clone, Copy)] // pmu_sleep_param_config_t pub struct ParamSleepConfig { + /// Configuration of high-power system parameters. pub hp_sys: HpParam, + /// Configuration of low-power system parameters. pub lp_sys: LpParam, + /// Shared configuration parameters for high-power and low-power systems. pub hp_lp: HpLpParam, } impl ParamSleepConfig { @@ -729,10 +762,13 @@ impl SleepTimeConfig { } } +/// Configuration for the RTC sleep behavior. #[derive(Clone, Copy)] // pmu_sleep_config_t + deep sleep flag + pd flags pub struct RtcSleepConfig { + /// Deep Sleep flag pub deep: bool, + /// Power Down flags pub pd_flags: PowerDownFlags, } @@ -761,28 +797,46 @@ bitfield::bitfield! { /// Power domains to be powered down during sleep pub struct PowerDownFlags(u32); + /// Controls the power-down status of the top power domain. pub u32, pd_top , set_pd_top : 0; + /// Controls the power-down status of the VDD_SDIO power domain. pub u32, pd_vddsdio , set_pd_vddsdio : 1; + /// Controls the power-down status of the modem power domain. pub u32, pd_modem , set_pd_modem : 2; + /// Controls the power-down status of the high-performance peripheral power domain. pub u32, pd_hp_periph, set_pd_hp_periph: 3; + /// Controls the power-down status of the CPU power domain. pub u32, pd_cpu , set_pd_cpu : 4; + /// Controls the power-down status of the high-performance always-on domain. pub u32, pd_hp_aon , set_pd_hp_aon : 5; + /// Controls the power-down status of memory group 0. pub u32, pd_mem_g0 , set_pd_mem_g0 : 6; + /// Controls the power-down status of memory group 1. pub u32, pd_mem_g1 , set_pd_mem_g1 : 7; + /// Controls the power-down status of memory group 2. pub u32, pd_mem_g2 , set_pd_mem_g2 : 8; + /// Controls the power-down status of memory group 3. pub u32, pd_mem_g3 , set_pd_mem_g3 : 9; + /// Controls the power-down status of the crystal oscillator. pub u32, pd_xtal , set_pd_xtal : 10; + /// Controls the power-down status of the fast RC oscillator. pub u32, pd_rc_fast , set_pd_rc_fast : 11; + /// Controls the power-down status of the 32kHz crystal oscillator. pub u32, pd_xtal32k , set_pd_xtal32k : 12; + /// Controls the power-down status of the 32kHz RC oscillator. pub u32, pd_rc32k , set_pd_rc32k : 13; + /// Controls the power-down status of the low-power peripheral domain. pub u32, pd_lp_periph, set_pd_lp_periph: 14; } impl PowerDownFlags { + /// Checks whether all memory groups (G0, G1, G2, G3) are powered down. pub fn pd_mem(self) -> bool { self.pd_mem_g0() && self.pd_mem_g1() && self.pd_mem_g2() && self.pd_mem_g3() } + /// Sets the power-down status for all memory groups (G0, G1, G2, G3) at + /// once. pub fn set_pd_mem(&mut self, value: bool) { self.set_pd_mem_g0(value); self.set_pd_mem_g1(value); @@ -826,10 +880,12 @@ impl MachineConstants { } impl RtcSleepConfig { + /// Returns whether the device is in deep sleep mode. pub fn deep_slp(&self) -> bool { self.deep } + /// Configures the device for deep sleep mode with ultra-low power settings. pub fn deep() -> Self { // Set up for ultra-low power sleep. Wakeup sources may modify these settings. Self { diff --git a/esp-hal/src/rtc_cntl/sleep/esp32s3.rs b/esp-hal/src/rtc_cntl/sleep/esp32s3.rs index 23a9585825e..ea97060daaf 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32s3.rs +++ b/esp-hal/src/rtc_cntl/sleep/esp32s3.rs @@ -42,41 +42,69 @@ const I2C_DIG_REG_XPD_DIG_REG_LSB: u32 = 3; // Approximate mapping of voltages to RTC_CNTL_DBIAS_WAK, RTC_CNTL_DBIAS_SLP, // RTC_CNTL_DIG_DBIAS_WAK, RTC_CNTL_DIG_DBIAS_SLP values. // Valid if RTC_CNTL_DBG_ATTEN is 0. +/// Digital bias setting for 0.90V. pub const RTC_CNTL_DBIAS_0V90: u32 = 13; +/// Digital bias setting for 0.95V. pub const RTC_CNTL_DBIAS_0V95: u32 = 16; +/// Digital bias setting for 1.00V. pub const RTC_CNTL_DBIAS_1V00: u32 = 18; +/// Digital bias setting for 1.05V. pub const RTC_CNTL_DBIAS_1V05: u32 = 20; +/// Digital bias setting for 1.10V. pub const RTC_CNTL_DBIAS_1V10: u32 = 23; +/// Digital bias setting for 1.15V. pub const RTC_CNTL_DBIAS_1V15: u32 = 25; +/// Digital bias setting for 1.20V. pub const RTC_CNTL_DBIAS_1V20: u32 = 28; +/// Digital bias setting for 1.25V. pub const RTC_CNTL_DBIAS_1V25: u32 = 30; -pub const RTC_CNTL_DBIAS_1V30: u32 = 31; //< voltage is about 1.34v in fact - +/// Digital bias setting for 1.30V. Voltage is approximately 1.34V in practice. +pub const RTC_CNTL_DBIAS_1V30: u32 = 31; +/// Default monitor debug attenuation value. pub const RTC_CNTL_DBG_ATTEN_MONITOR_DEFAULT: u8 = 0; +/// ULP co-processor touch start wait time during sleep, set to maximum. pub const RTC_CNTL_ULPCP_TOUCH_START_WAIT_IN_SLEEP: u16 = 0xFF; +/// ULP co-processor touch start wait time default value. pub const RTC_CNTL_ULPCP_TOUCH_START_WAIT_DEFAULT: u16 = 0x10; - +/// Default wait time for PLL buffer during startup. pub const RTC_CNTL_PLL_BUF_WAIT_DEFAULT: u8 = 20; +/// Default wait time for CK8M during startup. pub const RTC_CNTL_CK8M_WAIT_DEFAULT: u8 = 20; +/// Minimum sleep value. pub const RTC_CNTL_MIN_SLP_VAL_MIN: u8 = 2; +/// Deep sleep debug attenuation setting for ultra-low power mode. pub const RTC_CNTL_DBG_ATTEN_DEEPSLEEP_ULTRA_LOW: u8 = 15; - +/// Power-up setting for other blocks. pub const OTHER_BLOCKS_POWERUP: u8 = 1; +/// Wait cycles for other blocks. pub const OTHER_BLOCKS_WAIT: u16 = 1; - +/// WiFi power-up cycles. pub const WIFI_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// WiFi wait cycles. pub const WIFI_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; +/// Bluetooth power-up cycles. pub const BT_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// Bluetooth wait cycles. pub const BT_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; +/// RTC power-up cycles. pub const RTC_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// RTC wait cycles. pub const RTC_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; +/// CPU top power-up cycles. pub const CPU_TOP_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// CPU top wait cycles. pub const CPU_TOP_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; +/// DG wrap power-up cycles. pub const DG_WRAP_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// DG wrap wait cycles. pub const DG_WRAP_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; +/// DG peripheral power-up cycles. pub const DG_PERI_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// DG peripheral wait cycles. pub const DG_PERI_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; +/// RTC memory power-up cycles. pub const RTC_MEM_POWERUP_CYCLES: u8 = OTHER_BLOCKS_POWERUP; +/// RTC memory wait cycles. pub const RTC_MEM_WAIT_CYCLES: u16 = OTHER_BLOCKS_WAIT; impl WakeSource for TimerWakeupSource { @@ -266,6 +294,7 @@ impl Drop for RtcioWakeupSource<'_, '_> { } bitfield::bitfield! { + /// Configuration for the RTC sleep behavior. #[derive(Clone, Copy)] pub struct RtcSleepConfig(u64); impl Debug; @@ -382,6 +411,7 @@ fn rtc_sleep_pu(val: bool) { } impl RtcSleepConfig { + /// Configures the RTC for deep sleep mode. pub fn deep() -> Self { // Set up for ultra-low power sleep. Wakeup sources may modify these settings. let mut cfg = Self::default(); diff --git a/esp-hal/src/rtc_cntl/sleep/mod.rs b/esp-hal/src/rtc_cntl/sleep/mod.rs index 71ee0712a24..1390ed437cb 100644 --- a/esp-hal/src/rtc_cntl/sleep/mod.rs +++ b/esp-hal/src/rtc_cntl/sleep/mod.rs @@ -33,41 +33,56 @@ mod sleep_impl; pub use sleep_impl::*; #[derive(Debug, Default, Clone, Copy, PartialEq)] +/// Level at which a wake-up event is triggered pub enum WakeupLevel { + /// The wake-up event is triggered when the pin is low. Low, #[default] + /// The wake-up event is triggered when the pin is high. High, } +/// Represents a timer wake-up source, triggering an event after a specified +/// duration. #[derive(Debug, Default, Clone, Copy)] #[cfg(any(esp32, esp32c3, esp32s3, esp32c6))] pub struct TimerWakeupSource { + /// The duration after which the wake-up event is triggered. duration: Duration, } #[cfg(any(esp32, esp32c3, esp32s3, esp32c6))] impl TimerWakeupSource { + /// Creates a new timer wake-up source with the specified duration. pub fn new(duration: Duration) -> Self { Self { duration } } } +/// Errors that can occur when configuring RTC wake-up sources. #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// The selected pin is not a valid RTC pin. NotRtcPin, + /// The maximum number of wake-up sources has been exceeded. TooManyWakeupSources, } +/// External wake-up source (Ext0). #[derive(Debug)] #[cfg(any(esp32, esp32s3))] pub struct Ext0WakeupSource<'a, P: RtcIoWakeupPinType> { + /// The pin used as the wake-up source. pin: RefCell<&'a mut P>, + /// The level at which the wake-up event is triggered. level: WakeupLevel, } #[cfg(any(esp32, esp32s3))] impl<'a, P: RtcIoWakeupPinType> Ext0WakeupSource<'a, P> { + /// Creates a new external wake-up source (Ext0``) with the specified pin + /// and wake-up level. pub fn new(pin: &'a mut P, level: WakeupLevel) -> Self { Self { pin: RefCell::new(pin), @@ -76,14 +91,19 @@ impl<'a, P: RtcIoWakeupPinType> Ext0WakeupSource<'a, P> { } } +/// External wake-up source (Ext1). #[cfg(any(esp32, esp32s3))] pub struct Ext1WakeupSource<'a, 'b> { + /// A collection of pins used as wake-up sources. pins: RefCell<&'a mut [&'b mut dyn RtcIoWakeupPinType]>, + /// The level at which the wake-up event is triggered across all pins. level: WakeupLevel, } #[cfg(any(esp32, esp32s3))] impl<'a, 'b> Ext1WakeupSource<'a, 'b> { + /// Creates a new external wake-up source (Ext1) with the specified pins and + /// wake-up level. pub fn new(pins: &'a mut [&'b mut dyn RtcIoWakeupPinType], level: WakeupLevel) -> Self { Self { pins: RefCell::new(pins), @@ -92,6 +112,7 @@ impl<'a, 'b> Ext1WakeupSource<'a, 'b> { } } +/// External wake-up source (Ext1). #[cfg(esp32c6)] pub struct Ext1WakeupSource<'a, 'b> { pins: RefCell<&'a mut [(&'b mut dyn RtcIoWakeupPinType, WakeupLevel)]>, @@ -99,6 +120,8 @@ pub struct Ext1WakeupSource<'a, 'b> { #[cfg(esp32c6)] impl<'a, 'b> Ext1WakeupSource<'a, 'b> { + /// Creates a new external wake-up source (Ext1) with the specified pins and + /// wake-up level. pub fn new(pins: &'a mut [(&'b mut dyn RtcIoWakeupPinType, WakeupLevel)]) -> Self { Self { pins: RefCell::new(pins), @@ -118,6 +141,7 @@ pub struct RtcioWakeupSource<'a, 'b> { #[cfg(any(esp32c3, esp32s3))] impl<'a, 'b> RtcioWakeupSource<'a, 'b> { + /// Creates a new external wake-up source (Ext1). pub fn new(pins: &'a mut [(&'b mut dyn RtcIoWakeupPinType, WakeupLevel)]) -> Self { Self { pins: RefCell::new(pins), @@ -247,6 +271,7 @@ uart_wakeup_impl!(1); #[cfg(not(pmu))] bitfield::bitfield! { + /// Represents the wakeup triggers. #[derive(Default, Clone, Copy)] pub struct WakeTriggers(u16); impl Debug; @@ -276,6 +301,7 @@ bitfield::bitfield! { #[cfg(pmu)] bitfield::bitfield! { + /// Represents the wakeup triggers. #[derive(Default, Clone, Copy)] pub struct WakeTriggers(u16); impl Debug; @@ -306,6 +332,8 @@ bitfield::bitfield! { pub usb, set_usb: 14; } +/// Trait representing a wakeup source. pub trait WakeSource { + /// Configures the RTC and applies the wakeup triggers. fn apply(&self, rtc: &Rtc<'_>, triggers: &mut WakeTriggers, sleep_config: &mut RtcSleepConfig); } diff --git a/esp-hal/src/soc/esp32/cpu_control.rs b/esp-hal/src/soc/esp32/cpu_control.rs index 7319639379a..2e1572fdb83 100644 --- a/esp-hal/src/soc/esp32/cpu_control.rs +++ b/esp-hal/src/soc/esp32/cpu_control.rs @@ -99,14 +99,17 @@ impl<const SIZE: usize> Stack<SIZE> { } } + /// Returns the size of the stack. pub const fn len(&self) -> usize { SIZE } + /// Provides a mutable pointer to the bottom of the stack. pub fn bottom(&mut self) -> *mut u32 { self.mem.as_mut_ptr() as *mut u32 } + /// Provides a mutable pointer to the top of the stack. pub fn top(&mut self) -> *mut u32 { unsafe { self.bottom().add(SIZE / 4) } } @@ -132,9 +135,11 @@ impl<'a> Drop for AppCoreGuard<'a> { } } +/// Represents error that can occur in the system. #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// Core is already running. CoreAlreadyRunning, } @@ -168,6 +173,7 @@ unsafe fn internal_park_core(core: Cpu) { } impl<'d> CpuControl<'d> { + /// Creates a new instance of `CpuControl`. pub fn new(cpu_control: impl Peripheral<P = CPU_CTRL> + 'd) -> CpuControl<'d> { crate::into_ref!(cpu_control); diff --git a/esp-hal/src/soc/esp32/efuse/mod.rs b/esp-hal/src/soc/esp32/efuse/mod.rs index 0a6de1bac83..bf16993fc9e 100644 --- a/esp-hal/src/soc/esp32/efuse/mod.rs +++ b/esp-hal/src/soc/esp32/efuse/mod.rs @@ -47,20 +47,30 @@ use crate::peripherals::EFUSE; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; +/// Representing different types of ESP32 chips. #[derive(PartialEq, Eq, Copy, Clone, Debug)] pub enum ChipType { + /// Represents the ESP32 D0WDQ6 chip variant. Esp32D0wdq6, + /// Represents the ESP32 D0WDQ5 chip variant. Esp32D0wdq5, + /// Represents the ESP32 D2WDQ5 chip variant. Esp32D2wdq5, + /// Represents the ESP32 Pico D2 chip variant. Esp32Picod2, + /// Represents the ESP32 Pico D4 chip variant. Esp32Picod4, + /// Represents the ESP32 Pico v3.02 chip variant. Esp32Picov302, + /// Represents an unknown or unsupported chip variant. Unknown, } impl Efuse { + /// Reads the base MAC address from the eFuse memory. pub fn read_base_mac_address() -> [u8; 6] { Self::read_field_be(MAC) } diff --git a/esp-hal/src/soc/esp32/gpio.rs b/esp-hal/src/soc/esp32/gpio.rs index fb8b29ed161..e354aae23d2 100644 --- a/esp-hal/src/soc/esp32/gpio.rs +++ b/esp-hal/src/soc/esp32/gpio.rs @@ -58,6 +58,7 @@ use crate::{ Cpu, }; +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 40; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32/mod.rs b/esp-hal/src/soc/esp32/mod.rs index be3b74f9ab3..c50c937af8c 100644 --- a/esp-hal/src/soc/esp32/mod.rs +++ b/esp-hal/src/soc/esp32/mod.rs @@ -33,15 +33,19 @@ macro_rules! chip { pub use chip; pub(crate) mod constants { + /// The base clock frequency for the I2S peripheral (Hertz). pub const I2S_SCLK: u32 = 160_000_000; + /// The default clock source for I2S operations. pub const I2S_DEFAULT_CLK_SRC: u32 = 2; - + /// The starting address of the Remote Control (RMT) module's RAM. pub const RMT_RAM_START: usize = 0x3ff56800; + /// The size, in bytes, of each RMT channel's dedicated RAM. pub const RMT_CHANNEL_RAM_SIZE: usize = 64; - + /// The lower bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_LOW: u32 = 0x3FFA_E000; + /// The upper bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_HIGH: u32 = 0x4000_0000; - + /// A reference clock tick of 1 MHz. pub const REF_TICK: fugit::HertzU32 = fugit::HertzU32::MHz(1); } diff --git a/esp-hal/src/soc/esp32/psram.rs b/esp-hal/src/soc/esp32/psram.rs index 83c684e3882..0ad25216335 100644 --- a/esp-hal/src/soc/esp32/psram.rs +++ b/esp-hal/src/soc/esp32/psram.rs @@ -18,8 +18,12 @@ //! //! NOTE: If you want to use `PSRAM` on `ESP32` or `ESP32-S3`, it'll work only //! in `release` mode. + +/// The starting virtual address of the PSRAM (Pseudo-SRAM) region in memory. pub const PSRAM_VADDR_START: usize = 0x3F800000; +/// Retrieves the starting virtual address of the PSRAM (Pseudo-SRAM) region in +/// memory. pub fn psram_vaddr_start() -> usize { PSRAM_VADDR_START } @@ -36,8 +40,10 @@ cfg_if::cfg_if! { } } +/// The total size of the PSRAM (Pseudo-SRAM) in bytes. pub const PSRAM_BYTES: usize = PSRAM_SIZE as usize * 1024 * 1024; +/// Initializes the PSRAM memory on supported devices. #[cfg(any(feature = "psram-2m", feature = "psram-4m", feature = "psram-8m"))] pub fn init_psram(_peripheral: impl crate::peripheral::Peripheral<P = crate::peripherals::PSRAM>) { utils::psram_init(); diff --git a/esp-hal/src/soc/esp32/trng.rs b/esp-hal/src/soc/esp32/trng.rs index f8bf24a4c83..aeb55fcab16 100644 --- a/esp-hal/src/soc/esp32/trng.rs +++ b/esp-hal/src/soc/esp32/trng.rs @@ -1,6 +1,8 @@ //! Helper functions for TRNG functionality -pub fn ensure_randomness() { +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. +pub(crate) fn ensure_randomness() { let rtc_cntl = unsafe { &*crate::peripherals::RTC_CNTL::ptr() }; let sens = unsafe { &*crate::peripherals::SENS::ptr() }; let dport = unsafe { &*crate::peripherals::DPORT::ptr() }; @@ -104,7 +106,8 @@ pub fn ensure_randomness() { } } -pub fn revert_trng() { +/// Disable true randomness. Unlocks `ADC` peripheral. +pub(crate) fn revert_trng() { let sens = unsafe { &*crate::peripherals::SENS::ptr() }; let i2s0 = unsafe { &*crate::peripherals::I2S0::ptr() }; let apb_ctrl = unsafe { &*crate::peripherals::APB_CTRL::ptr() }; diff --git a/esp-hal/src/soc/esp32c2/efuse/mod.rs b/esp-hal/src/soc/esp32c2/efuse/mod.rs index 257ceef3639..7ead2a94903 100644 --- a/esp-hal/src/soc/esp32c2/efuse/mod.rs +++ b/esp-hal/src/soc/esp32c2/efuse/mod.rs @@ -45,6 +45,7 @@ use crate::{analog::adc::Attenuation, peripherals::EFUSE}; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; impl Efuse { diff --git a/esp-hal/src/soc/esp32c2/gpio.rs b/esp-hal/src/soc/esp32c2/gpio.rs index 103f97f6c3f..c50f33cf2d0 100644 --- a/esp-hal/src/soc/esp32c2/gpio.rs +++ b/esp-hal/src/soc/esp32c2/gpio.rs @@ -50,6 +50,7 @@ use crate::{ peripherals::GPIO, }; +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 21; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32c2/mod.rs b/esp-hal/src/soc/esp32c2/mod.rs index 71a0f469765..c8fcaa96da9 100644 --- a/esp-hal/src/soc/esp32c2/mod.rs +++ b/esp-hal/src/soc/esp32c2/mod.rs @@ -30,9 +30,12 @@ pub(crate) mod registers { } pub(crate) mod constants { + /// The lower bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_LOW: u32 = 0x3FCA_0000; + /// The upper bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_HIGH: u32 = 0x3FCE_0000; + /// RC FAST Clock value (Hertz). pub const RC_FAST_CLK: fugit::HertzU32 = fugit::HertzU32::kHz(17500); } diff --git a/esp-hal/src/soc/esp32c2/trng.rs b/esp-hal/src/soc/esp32c2/trng.rs index 88c5db4b23f..92a565ae665 100644 --- a/esp-hal/src/soc/esp32c2/trng.rs +++ b/esp-hal/src/soc/esp32c2/trng.rs @@ -15,6 +15,8 @@ const ADC_SARADC_ENT_TSENS_ADDR_LSB: u8 = 2; use crate::regi2c_write_mask; +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. pub(crate) fn ensure_randomness() { let rtc_cntl = unsafe { &*crate::peripherals::RTC_CNTL::ptr() }; let system = unsafe { &*crate::peripherals::SYSTEM::ptr() }; @@ -100,6 +102,7 @@ pub(crate) fn ensure_randomness() { } } +/// Disable true randomness. Unlocks `ADC` peripheral. pub(crate) fn revert_trng() { let apb_saradc = unsafe { &*crate::peripherals::APB_SARADC::ptr() }; let rtc_cntl = unsafe { &*crate::peripherals::RTC_CNTL::ptr() }; diff --git a/esp-hal/src/soc/esp32c3/efuse/mod.rs b/esp-hal/src/soc/esp32c3/efuse/mod.rs index cf4463bbabf..2d326c6aa16 100644 --- a/esp-hal/src/soc/esp32c3/efuse/mod.rs +++ b/esp-hal/src/soc/esp32c3/efuse/mod.rs @@ -45,6 +45,7 @@ use crate::{analog::adc::Attenuation, peripherals::EFUSE}; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; impl Efuse { diff --git a/esp-hal/src/soc/esp32c3/gpio.rs b/esp-hal/src/soc/esp32c3/gpio.rs index aca0ebe4878..4c6a3091301 100644 --- a/esp-hal/src/soc/esp32c3/gpio.rs +++ b/esp-hal/src/soc/esp32c3/gpio.rs @@ -51,6 +51,7 @@ use crate::{ peripherals::GPIO, }; +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 22; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32c3/mod.rs b/esp-hal/src/soc/esp32c3/mod.rs index b4e9fc23dd1..b74aa9a4460 100644 --- a/esp-hal/src/soc/esp32c3/mod.rs +++ b/esp-hal/src/soc/esp32c3/mod.rs @@ -34,17 +34,26 @@ pub(crate) mod registers { } pub(crate) mod constants { + /// The base clock frequency for the I2S peripheral (Hertz). pub const I2S_SCLK: u32 = 160_000_000; + /// The default clock source for I2S operations. pub const I2S_DEFAULT_CLK_SRC: u8 = 2; + /// The starting address of the Remote Control (RMT) module's RAM. pub const RMT_RAM_START: usize = 0x60016400; + /// The size, in bytes, of each RMT channel's dedicated RAM. pub const RMT_CHANNEL_RAM_SIZE: usize = 48; + /// RMT Clock source value. pub const RMT_CLOCK_SRC: u8 = 1; + /// RMT Clock source frequence. pub const RMT_CLOCK_SRC_FREQ: fugit::HertzU32 = fugit::HertzU32::MHz(80); + /// The lower bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_LOW: u32 = 0x3FC8_0000; + /// The upper bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_HIGH: u32 = 0x3FCE_0000; + /// RC FAST Clock value (Hertz). pub const RC_FAST_CLK: fugit::HertzU32 = fugit::HertzU32::kHz(17500); } diff --git a/esp-hal/src/soc/esp32c3/trng.rs b/esp-hal/src/soc/esp32c3/trng.rs index b78ed8d49a4..a1e7f5d281b 100644 --- a/esp-hal/src/soc/esp32c3/trng.rs +++ b/esp-hal/src/soc/esp32c3/trng.rs @@ -15,6 +15,8 @@ const ADC_SARADC_ENT_TSENS_ADDR_LSB: u8 = 2; use crate::regi2c_write_mask; +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. pub(crate) fn ensure_randomness() { let rtc_cntl = unsafe { &*crate::peripherals::RTC_CNTL::ptr() }; let system = unsafe { &*crate::peripherals::SYSTEM::ptr() }; @@ -100,6 +102,7 @@ pub(crate) fn ensure_randomness() { } } +/// Disable true randomness. Unlocks `ADC` peripheral. pub(crate) fn revert_trng() { let rtc_cntl = unsafe { &*crate::peripherals::RTC_CNTL::ptr() }; let apb_saradc = unsafe { &*crate::peripherals::APB_SARADC::ptr() }; diff --git a/esp-hal/src/soc/esp32c6/efuse/mod.rs b/esp-hal/src/soc/esp32c6/efuse/mod.rs index 97711a5a3e4..e56293ba3cc 100644 --- a/esp-hal/src/soc/esp32c6/efuse/mod.rs +++ b/esp-hal/src/soc/esp32c6/efuse/mod.rs @@ -45,6 +45,7 @@ use crate::{analog::adc::Attenuation, peripherals::EFUSE}; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; impl Efuse { diff --git a/esp-hal/src/soc/esp32c6/gpio.rs b/esp-hal/src/soc/esp32c6/gpio.rs index 74d524f10d5..4e688237e06 100644 --- a/esp-hal/src/soc/esp32c6/gpio.rs +++ b/esp-hal/src/soc/esp32c6/gpio.rs @@ -51,6 +51,7 @@ use crate::{ peripherals::GPIO, }; +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 31; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32c6/lp_core.rs b/esp-hal/src/soc/esp32c6/lp_core.rs index 24330a3492f..151e47268f1 100644 --- a/esp-hal/src/soc/esp32c6/lp_core.rs +++ b/esp-hal/src/soc/esp32c6/lp_core.rs @@ -23,8 +23,10 @@ use esp32c6 as pac; use crate::peripheral::{Peripheral, PeripheralRef}; +/// Represents the possible wakeup sources for the LP (Low Power) core. #[derive(Debug, Clone, Copy)] pub enum LpCoreWakeupSource { + /// Wakeup source from the HP (High Performance) CPU. HpCpu, } @@ -39,6 +41,7 @@ pub enum LpCoreClockSource { XtalD2Clk, } +/// Represents the Low Power (LP) core peripheral. pub struct LpCore<'d> { _lp_core: PeripheralRef<'d, crate::soc::peripherals::LP_CORE>, } diff --git a/esp-hal/src/soc/esp32c6/mod.rs b/esp-hal/src/soc/esp32c6/mod.rs index 2f7d2138554..d57051c7990 100644 --- a/esp-hal/src/soc/esp32c6/mod.rs +++ b/esp-hal/src/soc/esp32c6/mod.rs @@ -36,22 +36,33 @@ pub(crate) mod registers { } pub(crate) mod constants { + /// The default clock source for the timer group. pub const TIMG_DEFAULT_CLK_SRC: u8 = 1; + /// The clock frequency for the I2S peripheral in Hertz. pub const I2S_SCLK: u32 = 160_000_000; + /// The default clock source for the I2S peripheral. pub const I2S_DEFAULT_CLK_SRC: u8 = 2; + /// The starting address of the RMT (Remote Control) peripheral's RAM. pub const RMT_RAM_START: usize = 0x60006400; + /// The size of each RMT channel's RAM in bytes. pub const RMT_CHANNEL_RAM_SIZE: usize = 48; + /// The default clock source for the RMT peripheral. pub const RMT_CLOCK_SRC: u8 = 1; + /// The frequency of the RMT clock source in Hertz. pub const RMT_CLOCK_SRC_FREQ: fugit::HertzU32 = fugit::HertzU32::MHz(80); + /// The clock frequency for the Parallel IO peripheral in Hertz. pub const PARL_IO_SCLK: u32 = 240_000_000; + /// The lower address boundary for system DRAM. pub const SOC_DRAM_LOW: u32 = 0x4080_0000; + /// The upper address boundary for system DRAM. pub const SOC_DRAM_HIGH: u32 = 0x4088_0000; - pub const RC_FAST_CLK: fugit::HertzU32 = fugit::HertzU32::kHz(17500); + /// RC FAST Clock value (Hertz). + pub const RC_FAST_CLK: fugit::HertzU32 = fugit::HertzU32::kHz(17_500); } #[export_name = "__post_init"] diff --git a/esp-hal/src/soc/esp32c6/trng.rs b/esp-hal/src/soc/esp32c6/trng.rs index cfe6e75daf7..576f5c0442b 100644 --- a/esp-hal/src/soc/esp32c6/trng.rs +++ b/esp-hal/src/soc/esp32c6/trng.rs @@ -60,6 +60,8 @@ const ADC_SARADC2_ENCAL_REF_ADDR: u8 = 0x7; const ADC_SARADC2_ENCAL_REF_ADDR_MSB: u8 = 6; const ADC_SARADC2_ENCAL_REF_ADDR_LSB: u8 = 6; +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. pub(crate) fn ensure_randomness() { let pcr = unsafe { &*crate::peripherals::PCR::ptr() }; let pmu = unsafe { &*crate::peripherals::PMU::ptr() }; @@ -190,10 +192,9 @@ pub(crate) fn ensure_randomness() { } } -#[allow(unused)] +/// Disable true randomness. Unlocks `ADC` peripheral. pub(crate) fn revert_trng() { let apb_saradc = unsafe { &*crate::peripherals::APB_SARADC::ptr() }; - let pmu = unsafe { &*crate::peripherals::PMU::ptr() }; let pcr = unsafe { &*crate::peripherals::PCR::ptr() }; unsafe { diff --git a/esp-hal/src/soc/esp32h2/efuse/mod.rs b/esp-hal/src/soc/esp32h2/efuse/mod.rs index 81df45fad38..131a9287470 100644 --- a/esp-hal/src/soc/esp32h2/efuse/mod.rs +++ b/esp-hal/src/soc/esp32h2/efuse/mod.rs @@ -45,6 +45,7 @@ use crate::peripherals::EFUSE; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; impl Efuse { diff --git a/esp-hal/src/soc/esp32h2/gpio.rs b/esp-hal/src/soc/esp32h2/gpio.rs index d6f2710eec1..519b6f56b6a 100644 --- a/esp-hal/src/soc/esp32h2/gpio.rs +++ b/esp-hal/src/soc/esp32h2/gpio.rs @@ -52,6 +52,7 @@ use crate::{ }; // https://github.com/espressif/esp-idf/blob/df9310a/components/soc/esp32h2/gpio_periph.c#L42 +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 28; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32h2/mod.rs b/esp-hal/src/soc/esp32h2/mod.rs index 457e0ff9f15..225a2ca93d5 100644 --- a/esp-hal/src/soc/esp32h2/mod.rs +++ b/esp-hal/src/soc/esp32h2/mod.rs @@ -35,21 +35,33 @@ pub(crate) mod registers { } pub(crate) mod constants { + /// Default clock source for the timer group (TIMG) peripheral. pub const TIMG_DEFAULT_CLK_SRC: u8 = 2; + /// Default clock source for the I2S peripheral. pub const I2S_DEFAULT_CLK_SRC: u8 = 1; + /// Clock frequency for the I2S peripheral, in Hertz. pub const I2S_SCLK: u32 = 96_000_000; + /// Start address of the RMT (Remote Control) peripheral's RAM. pub const RMT_RAM_START: usize = 0x60007400; + /// Size of the RAM allocated per RMT channel, in bytes. pub const RMT_CHANNEL_RAM_SIZE: usize = 48; + /// Clock source for the RMT peripheral (false = default source). pub const RMT_CLOCK_SRC: bool = false; + /// Frequency of the RMT clock source, in Hertz. pub const RMT_CLOCK_SRC_FREQ: fugit::HertzU32 = fugit::HertzU32::MHz(32); + /// System clock frequency for the parallel I/O (PARL IO) peripheral, in + /// Hertz. pub const PARL_IO_SCLK: u32 = 96_000_000; + /// Start address of the system's DRAM (low range). pub const SOC_DRAM_LOW: u32 = 0x4080_0000; + /// End address of the system's DRAM (high range). pub const SOC_DRAM_HIGH: u32 = 0x4085_0000; + /// RC FAST Clock value (Hertz). pub const RC_FAST_CLK: fugit::HertzU32 = fugit::HertzU32::kHz(17500); } diff --git a/esp-hal/src/soc/esp32h2/trng.rs b/esp-hal/src/soc/esp32h2/trng.rs index 0b1e25e1188..e0c3aab93c5 100644 --- a/esp-hal/src/soc/esp32h2/trng.rs +++ b/esp-hal/src/soc/esp32h2/trng.rs @@ -56,6 +56,8 @@ const REGI2C_RTC_WR_CNTL_S: u8 = 24; const REGI2C_RTC_DATA_V: u8 = 0xFF; const REGI2C_RTC_DATA_S: u8 = 16; +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. pub(crate) fn ensure_randomness() { let pcr = unsafe { &*crate::peripherals::PCR::ptr() }; let pmu = unsafe { &*crate::peripherals::PMU::ptr() }; @@ -177,6 +179,7 @@ pub(crate) fn ensure_randomness() { } } +/// Disable true randomness. Unlocks `ADC` peripheral. pub(crate) fn revert_trng() { let apb_saradc = unsafe { &*crate::peripherals::APB_SARADC::ptr() }; let pcr = unsafe { &*crate::peripherals::PCR::ptr() }; diff --git a/esp-hal/src/soc/esp32s2/efuse/mod.rs b/esp-hal/src/soc/esp32s2/efuse/mod.rs index e93849c107b..61d2975344e 100644 --- a/esp-hal/src/soc/esp32s2/efuse/mod.rs +++ b/esp-hal/src/soc/esp32s2/efuse/mod.rs @@ -45,6 +45,7 @@ use crate::peripherals::EFUSE; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; impl Efuse { diff --git a/esp-hal/src/soc/esp32s2/gpio.rs b/esp-hal/src/soc/esp32s2/gpio.rs index 78cd541c23e..bdb53bc9423 100644 --- a/esp-hal/src/soc/esp32s2/gpio.rs +++ b/esp-hal/src/soc/esp32s2/gpio.rs @@ -64,6 +64,7 @@ use crate::{ peripherals::GPIO, }; +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 47; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32s2/mod.rs b/esp-hal/src/soc/esp32s2/mod.rs index a19d919f8f2..e6b4d10add5 100644 --- a/esp-hal/src/soc/esp32s2/mod.rs +++ b/esp-hal/src/soc/esp32s2/mod.rs @@ -38,15 +38,19 @@ macro_rules! chip { pub use chip; pub(crate) mod constants { + /// System clock frequency for the I2S peripheral, in Hertz. pub const I2S_SCLK: u32 = 160_000_000; + /// Default clock source for the I2S peripheral. pub const I2S_DEFAULT_CLK_SRC: u32 = 2; - + /// Start address of the RMT (Remote Control) peripheral's RAM. pub const RMT_RAM_START: usize = 0x3f416400; + /// Size of the RAM allocated per RMT channel, in bytes. pub const RMT_CHANNEL_RAM_SIZE: usize = 64; - + /// Start address of the system's DRAM (low range). pub const SOC_DRAM_LOW: u32 = 0x3FFB_0000; + /// End address of the system's DRAM (high range). pub const SOC_DRAM_HIGH: u32 = 0x4000_0000; - + /// Reference clock tick frequency, set to 1 MHz. pub const REF_TICK: fugit::HertzU32 = fugit::HertzU32::MHz(1); } diff --git a/esp-hal/src/soc/esp32s2/psram.rs b/esp-hal/src/soc/esp32s2/psram.rs index a47fcbd6d2d..54fbb2ec2e0 100644 --- a/esp-hal/src/soc/esp32s2/psram.rs +++ b/esp-hal/src/soc/esp32s2/psram.rs @@ -17,6 +17,7 @@ //! `4MB`, and `8MB`. const PSRAM_VADDR: u32 = 0x3f500000; +/// Returns the start address of the PSRAM virtual address space. pub fn psram_vaddr_start() -> usize { PSRAM_VADDR_START } @@ -33,10 +34,14 @@ cfg_if::cfg_if! { } } +/// The total size of the PSRAM in bytes, calculated from the PSRAM size +/// constant. pub const PSRAM_BYTES: usize = PSRAM_SIZE as usize * 1024 * 1024; +/// The start address of the PSRAM virtual address space. pub const PSRAM_VADDR_START: usize = PSRAM_VADDR as usize; +/// Initialize PSRAM to be used for data. #[cfg(any(feature = "psram-2m", feature = "psram-4m", feature = "psram-8m"))] pub fn init_psram(_peripheral: impl crate::peripheral::Peripheral<P = crate::peripherals::PSRAM>) { #[allow(unused)] diff --git a/esp-hal/src/soc/esp32s2/trng.rs b/esp-hal/src/soc/esp32s2/trng.rs index 2999ac1d339..48eeb6f9d33 100644 --- a/esp-hal/src/soc/esp32s2/trng.rs +++ b/esp-hal/src/soc/esp32s2/trng.rs @@ -45,6 +45,8 @@ const I2C_RTC_BBPLL_MASK: u32 = 1 << 17; const I2C_RTC_SAR_MASK: u32 = 1 << 18; const I2C_RTC_BOD_MASK: u32 = 1 << 22; +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. pub(crate) fn ensure_randomness() { let rtc_cntl = unsafe { &*crate::peripherals::RTC_CNTL::ptr() }; let dport = unsafe { &*crate::peripherals::SYSTEM::ptr() }; @@ -157,7 +159,8 @@ pub(crate) fn ensure_randomness() { } } -pub fn revert_trng() { +/// Disable true randomness. Unlocks `ADC` peripheral. +pub(crate) fn revert_trng() { let dport = unsafe { &*crate::peripherals::SYSTEM::ptr() }; let apb_saradc = unsafe { &*crate::peripherals::APB_SARADC::ptr() }; let sens = unsafe { &*crate::peripherals::SENS::ptr() }; diff --git a/esp-hal/src/soc/esp32s2/ulp_core.rs b/esp-hal/src/soc/esp32s2/ulp_core.rs index cedfef686e0..579317b2a8f 100644 --- a/esp-hal/src/soc/esp32s2/ulp_core.rs +++ b/esp-hal/src/soc/esp32s2/ulp_core.rs @@ -42,16 +42,20 @@ use esp32s2 as pac; use crate::peripheral::{Peripheral, PeripheralRef}; +/// Enum representing the possible wakeup sources for the ULP core. #[derive(Debug, Clone, Copy)] pub enum UlpCoreWakeupSource { + /// Wakeup source from the HP (High Performance) CPU. HpCpu, } +/// Structure representing the ULP (Ultra-Low Power) core. pub struct UlpCore<'d> { _lp_core: PeripheralRef<'d, crate::soc::peripherals::ULP_RISCV_CORE>, } impl<'d> UlpCore<'d> { + /// Creates a new instance of the `UlpCore` struct. pub fn new(lp_core: impl Peripheral<P = crate::soc::peripherals::ULP_RISCV_CORE> + 'd) -> Self { crate::into_ref!(lp_core); @@ -70,6 +74,7 @@ impl<'d> UlpCore<'d> { // ulp_stop(); // } + /// Runs the ULP core with the specified wakeup source. pub fn run(&mut self, wakeup_src: UlpCoreWakeupSource) { ulp_run(wakeup_src); } diff --git a/esp-hal/src/soc/esp32s3/cpu_control.rs b/esp-hal/src/soc/esp32s3/cpu_control.rs index efe7397681b..5c1f0bc0a95 100644 --- a/esp-hal/src/soc/esp32s3/cpu_control.rs +++ b/esp-hal/src/soc/esp32s3/cpu_control.rs @@ -100,14 +100,17 @@ impl<const SIZE: usize> Stack<SIZE> { } } + /// Returns the length of the stack in bytes. pub const fn len(&self) -> usize { SIZE } + /// Returns a mutable pointer to the bottom of the stack. pub fn bottom(&mut self) -> *mut u32 { self.mem.as_mut_ptr() as *mut u32 } + /// Returns a mutable pointer to the top of the stack. pub fn top(&mut self) -> *mut u32 { unsafe { self.bottom().add(SIZE / 4) } } @@ -132,9 +135,11 @@ impl<'a> Drop for AppCoreGuard<'a> { } } +/// Represents error that can occur in the system. #[derive(Debug, Clone, Copy, PartialEq)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { + /// Core is already running. CoreAlreadyRunning, } @@ -168,6 +173,7 @@ unsafe fn internal_park_core(core: Cpu) { } impl<'d> CpuControl<'d> { + /// Creates a new instance of `CpuControl`. pub fn new(cpu_control: impl Peripheral<P = CPU_CTRL> + 'd) -> CpuControl<'d> { crate::into_ref!(cpu_control); diff --git a/esp-hal/src/soc/esp32s3/efuse/mod.rs b/esp-hal/src/soc/esp32s3/efuse/mod.rs index 8acdc754326..72fc1d2c37e 100644 --- a/esp-hal/src/soc/esp32s3/efuse/mod.rs +++ b/esp-hal/src/soc/esp32s3/efuse/mod.rs @@ -45,6 +45,7 @@ use crate::{analog::adc::Attenuation, peripherals::EFUSE}; mod fields; +/// A struct representing the eFuse functionality of the chip. pub struct Efuse; impl Efuse { diff --git a/esp-hal/src/soc/esp32s3/gpio.rs b/esp-hal/src/soc/esp32s3/gpio.rs index 96f0c6a3658..5ee417e4e57 100644 --- a/esp-hal/src/soc/esp32s3/gpio.rs +++ b/esp-hal/src/soc/esp32s3/gpio.rs @@ -52,6 +52,7 @@ use crate::{ peripherals::GPIO, }; +/// The total number of GPIO pins available. pub const NUM_PINS: usize = 49; pub(crate) const FUNC_IN_SEL_OFFSET: usize = 0; diff --git a/esp-hal/src/soc/esp32s3/mod.rs b/esp-hal/src/soc/esp32s3/mod.rs index f711304123c..0cf538d17c2 100644 --- a/esp-hal/src/soc/esp32s3/mod.rs +++ b/esp-hal/src/soc/esp32s3/mod.rs @@ -39,17 +39,26 @@ macro_rules! chip { pub use chip; pub(crate) mod constants { + /// The base clock frequency for the I2S peripheral (Hertz). pub const I2S_SCLK: u32 = 160_000_000; + /// The default clock source for I2S operations. pub const I2S_DEFAULT_CLK_SRC: u8 = 2; + /// The starting address of the Remote Control (RMT) module's RAM. pub const RMT_RAM_START: usize = 0x60016800; + /// The size, in bytes, of each RMT channel's dedicated RAM. pub const RMT_CHANNEL_RAM_SIZE: usize = 48; + /// RMT Clock source value. pub const RMT_CLOCK_SRC: u8 = 1; + /// RMT Clock source frequence. pub const RMT_CLOCK_SRC_FREQ: fugit::HertzU32 = fugit::HertzU32::MHz(80); + /// The lower bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_LOW: u32 = 0x3FC8_8000; + /// The upper bound of the system's DRAM (Data RAM) address space. pub const SOC_DRAM_HIGH: u32 = 0x3FD0_0000; + /// A reference clock tick of 1 MHz. pub const RC_FAST_CLK: fugit::HertzU32 = fugit::HertzU32::kHz(17500); } @@ -171,6 +180,7 @@ unsafe fn post_init() { Wdt::<TIMG1, crate::Blocking>::set_wdt_enabled(false); } +/// Write back a specific range of data in the cache. #[doc(hidden)] #[link_section = ".rwtext"] pub unsafe fn cache_writeback_addr(addr: u32, size: u32) { @@ -185,6 +195,7 @@ pub unsafe fn cache_writeback_addr(addr: u32, size: u32) { Cache_Resume_DCache_Autoload(autoload); } +/// Invalidate a specific range of addresses in the cache. #[doc(hidden)] #[link_section = ".rwtext"] pub unsafe fn cache_invalidate_addr(addr: u32, size: u32) { @@ -194,6 +205,7 @@ pub unsafe fn cache_invalidate_addr(addr: u32, size: u32) { Cache_Invalidate_Addr(addr, size); } +/// Get the size of a cache line in the DCache. #[doc(hidden)] #[link_section = ".rwtext"] pub unsafe fn cache_get_dcache_line_size() -> u32 { diff --git a/esp-hal/src/soc/esp32s3/psram.rs b/esp-hal/src/soc/esp32s3/psram.rs index f9f986af9de..59aa01d16e4 100644 --- a/esp-hal/src/soc/esp32s3/psram.rs +++ b/esp-hal/src/soc/esp32s3/psram.rs @@ -18,6 +18,7 @@ static mut PSRAM_VADDR: u32 = 0x3C000000; +/// Returns the start address of the PSRAM virtual address space. pub fn psram_vaddr_start() -> usize { unsafe { PSRAM_VADDR as usize } } @@ -42,6 +43,8 @@ cfg_if::cfg_if! { } } +/// The total size of the PSRAM in bytes, calculated from the PSRAM size +/// constant. pub const PSRAM_BYTES: usize = PSRAM_SIZE as usize * 1024 * 1024; /// Initialize PSRAM to be used for data. @@ -862,14 +865,21 @@ pub(crate) mod utils { fn esp_rom_opiflash_pin_config(); } + /// Represents the operational mode registers of an OPI PSRAM. #[derive(Default)] #[repr(C)] struct OpiPsramModeReg { + // Mode register 0 (MR0). pub mr0: u8, + // Mode register 1 (MR1). pub mr1: u8, + // Mode register 2 (MR2). pub mr2: u8, + // Mode register 3 (MR3). pub mr3: u8, + // Mode register 4 (MR4). pub mr4: u8, + // Mode register 8 (MR8). pub mr8: u8, } diff --git a/esp-hal/src/soc/esp32s3/trng.rs b/esp-hal/src/soc/esp32s3/trng.rs index c67933c8f5c..fc98ddda813 100644 --- a/esp-hal/src/soc/esp32s3/trng.rs +++ b/esp-hal/src/soc/esp32s3/trng.rs @@ -17,6 +17,8 @@ const ADC_SARADC_DTEST_RTC_ADDR_LSB: u32 = 0; use crate::regi2c_write_mask; +/// Enable true randomness by enabling the entropy source. +/// Blocks `ADC` usage. pub(crate) fn ensure_randomness() { unsafe { let rtc_cntl = &*crate::peripherals::RTC_CNTL::ptr(); @@ -117,7 +119,8 @@ pub(crate) fn ensure_randomness() { } } -pub fn revert_trng() { +/// Disable true randomness. Unlocks `ADC` peripheral. +pub(crate) fn revert_trng() { let system = unsafe { &*crate::peripherals::SYSTEM::ptr() }; let apb_saradc = unsafe { &*crate::peripherals::APB_SARADC::ptr() }; let sens = unsafe { &*crate::peripherals::SENS::ptr() }; diff --git a/esp-hal/src/soc/esp32s3/ulp_core.rs b/esp-hal/src/soc/esp32s3/ulp_core.rs index f704a2a171b..865387bcb15 100644 --- a/esp-hal/src/soc/esp32s3/ulp_core.rs +++ b/esp-hal/src/soc/esp32s3/ulp_core.rs @@ -42,16 +42,20 @@ use esp32s3 as pac; use crate::peripheral::{Peripheral, PeripheralRef}; +/// Enum representing the possible wakeup sources for the ULP core. #[derive(Debug, Clone, Copy)] pub enum UlpCoreWakeupSource { + /// Wakeup source from the HP (High Performance) CPU. HpCpu, } +/// Structure representing the ULP (Ultra-Low Power) core. pub struct UlpCore<'d> { _lp_core: PeripheralRef<'d, crate::soc::peripherals::ULP_RISCV_CORE>, } impl<'d> UlpCore<'d> { + /// Creates a new instance of the `UlpCore` struct. pub fn new(lp_core: impl Peripheral<P = crate::soc::peripherals::ULP_RISCV_CORE> + 'd) -> Self { crate::into_ref!(lp_core); @@ -66,10 +70,12 @@ impl<'d> UlpCore<'d> { this } + /// Stops the ULP core. pub fn stop(&mut self) { ulp_stop(); } + /// Runs the ULP core with the specified wakeup source. pub fn run(&mut self, wakeup_src: UlpCoreWakeupSource) { ulp_run(wakeup_src); } diff --git a/esp-hal/src/soc/mod.rs b/esp-hal/src/soc/mod.rs index 8f2b49538e4..6ba4093dd23 100644 --- a/esp-hal/src/soc/mod.rs +++ b/esp-hal/src/soc/mod.rs @@ -1,5 +1,3 @@ -#![allow(missing_docs)] // TODO: Remove when able - use portable_atomic::{AtomicU8, Ordering}; pub use self::implementation::*; @@ -26,8 +24,10 @@ mod efuse_field; static MAC_OVERRIDE_STATE: AtomicU8 = AtomicU8::new(0); static mut MAC_OVERRIDE: [u8; 6] = [0; 6]; +/// Error indicating issues with setting the MAC address. #[derive(PartialEq, Eq, Copy, Clone, Debug)] pub enum SetMacError { + /// The MAC address has already been set and cannot be changed. AlreadySet, } diff --git a/esp-hal/src/timer/mod.rs b/esp-hal/src/timer/mod.rs index 99efaf8838e..f72fc16b932 100644 --- a/esp-hal/src/timer/mod.rs +++ b/esp-hal/src/timer/mod.rs @@ -364,17 +364,22 @@ impl<'d, T> embedded_hal_02::timer::Periodic for PeriodicTimer<'d, T> where T: T /// A type-erased timer /// /// You can create an instance of this by just calling `.into()` on a timer. -#[allow(missing_docs)] pub enum ErasedTimer { + /// Timer 0 of the TIMG0 peripheral in blocking mode. Timg0Timer0(timg::Timer<timg::Timer0<crate::peripherals::TIMG0>, Blocking>), + /// Timer 1 of the TIMG0 peripheral in blocking mode. #[cfg(timg_timer1)] Timg0Timer1(timg::Timer<timg::Timer1<crate::peripherals::TIMG0>, Blocking>), + /// Timer 0 of the TIMG1 peripheral in blocking mode. #[cfg(timg1)] Timg1Timer0(timg::Timer<timg::Timer0<crate::peripherals::TIMG1>, Blocking>), + /// Timer 1 of the TIMG1 peripheral in blocking mode. #[cfg(all(timg1, timg_timer1))] Timg1Timer1(timg::Timer<timg::Timer1<crate::peripherals::TIMG1>, Blocking>), + /// Systimer Alarm in periodic mode with blocking behavior. #[cfg(systimer)] SystimerAlarmPeriodic(systimer::Alarm<'static, systimer::Periodic, Blocking>), + /// Systimer Target in periodic mode with blocking behavior. #[cfg(systimer)] SystimerAlarmTarget(systimer::Alarm<'static, systimer::Target, Blocking>), } diff --git a/esp-hal/src/twai/filter.rs b/esp-hal/src/twai/filter.rs index bbdf2780351..2d0494f20a0 100644 --- a/esp-hal/src/twai/filter.rs +++ b/esp-hal/src/twai/filter.rs @@ -14,8 +14,15 @@ use super::{ExtendedId, StandardId}; #[derive(Debug, PartialEq, Eq)] +/// Represents the type of filtering to be applied to incoming TWAI frames. pub enum FilterType { + /// Uses the acceptance code and mask to define a single filter, which + /// allows for the first two data bytes of a standard frame to be filtered, + /// or the entirety of an extended frame's 29-bit ID. Single, + /// Uses the acceptance code and mask to define two separate filters + /// allowing for increased flexibility of ID's to accept, but does not allow + /// for all 29-bits of an extended ID to be filtered. Dual, } @@ -32,6 +39,7 @@ pub enum FilterType { pub trait Filter { /// The type of the filter. const FILTER_TYPE: FilterType; + /// Returns filter type. fn filter_type(&self) -> FilterType { Self::FILTER_TYPE } @@ -40,6 +48,7 @@ pub trait Filter { fn to_registers(&self) -> [u8; 8]; } +/// A type representing the bitmask used to filter incoming TWAI frames. pub type BitFilter<const N: usize> = [u8; N]; // Convert a byte from a bytestring into a bit inside a given code and mask. diff --git a/esp-hal/src/twai/mod.rs b/esp-hal/src/twai/mod.rs index 0953b543414..2a5ab3fbd95 100644 --- a/esp-hal/src/twai/mod.rs +++ b/esp-hal/src/twai/mod.rs @@ -14,7 +14,7 @@ //! up the timing parameters, configuring acceptance filters, handling //! interrupts, and transmitting/receiving messages on the TWAI bus. //! -//! This driver manages the ISO 11898-1 (CAN Specification 2.0) compatible TWAI +//! This driver manages the ISO 11898-1 compatible TWAI //! controllers. It supports Standard Frame Format (11-bit) and Extended Frame //! Format (29-bit) frame identifiers. //! @@ -34,13 +34,13 @@ //! # use core::option::Option::None; //! # use nb::block; //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); -//! // Use GPIO pins 2 and 3 to connect to the respective pins on the CAN +//! // Use GPIO pins 2 and 3 to connect to the respective pins on the TWAI //! // transceiver. //! let can_tx_pin = io.pins.gpio2; //! let can_rx_pin = io.pins.gpio3; //! -//! // The speed of the CAN bus. -//! const CAN_BAUDRATE: twai::BaudRate = BaudRate::B1000K; +//! // The speed of the TWAI bus. +//! const TWAI_BAUDRATE: twai::BaudRate = BaudRate::B1000K; //! //! // Begin configuring the TWAI peripheral. The peripheral is in a reset like //! // state that prevents transmission but allows configuration. @@ -49,7 +49,7 @@ //! can_tx_pin, //! can_rx_pin, //! &clocks, -//! CAN_BAUDRATE, +//! TWAI_BAUDRATE, //! TwaiMode::Normal //! ); //! @@ -90,13 +90,13 @@ //! # use core::option::Option::None; //! # use nb::block; //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX); -//! // Use GPIO pins 2 and 3 to connect to the respective pins on the CAN +//! // Use GPIO pins 2 and 3 to connect to the respective pins on the TWAI //! // transceiver. //! let can_tx_pin = io.pins.gpio2; //! let can_rx_pin = io.pins.gpio3; //! -//! // The speed of the CAN bus. -//! const CAN_BAUDRATE: twai::BaudRate = BaudRate::B1000K; +//! // The speed of the TWAI bus. +//! const TWAI_BAUDRATE: twai::BaudRate = BaudRate::B1000K; //! //! // Begin configuring the TWAI peripheral. //! let mut can_config = twai::TwaiConfiguration::new( @@ -104,7 +104,7 @@ //! can_tx_pin, //! can_rx_pin, //! &clocks, -//! CAN_BAUDRATE, +//! TWAI_BAUDRATE, //! TwaiMode::SelfTest //! ); //! @@ -129,8 +129,6 @@ //! # } //! ``` -#![allow(missing_docs)] // TODO: Remove when able - use core::marker::PhantomData; use self::filter::{Filter, FilterType}; @@ -146,12 +144,12 @@ use crate::{ pub mod filter; -/// CAN error kind +/// TWAI error kind /// -/// This represents a common set of CAN operation errors. HAL implementations +/// This represents a common set of TWAI operation errors. HAL implementations /// are free to define more specific or additional error types. However, by -/// providing a mapping to these common CAN errors, generic code can still react -/// to them. +/// providing a mapping to these common TWAI errors, generic code can still +/// react to them. #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] #[non_exhaustive] pub enum ErrorKind { @@ -256,15 +254,15 @@ pub enum TwaiMode { ListenOnly, } -/// Standard 11-bit CAN Identifier (`0..=0x7FF`). +/// Standard 11-bit TWAI Identifier (`0..=0x7FF`). #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub struct StandardId(u16); impl StandardId { - /// CAN ID `0`, the highest priority. + /// TWAI ID `0`, the highest priority. pub const ZERO: Self = StandardId(0); - /// CAN ID `0x7FF`, the lowest priority. + /// TWAI ID `0x7FF`, the lowest priority. pub const MAX: Self = StandardId(0x7FF); /// Tries to create a `StandardId` from a raw 16-bit integer. @@ -290,7 +288,7 @@ impl StandardId { StandardId(raw) } - /// Returns this CAN Identifier as a raw 16-bit integer. + /// Returns TWAI Identifier as a raw 16-bit integer. #[inline] pub fn as_raw(&self) -> u16 { self.0 @@ -325,15 +323,15 @@ impl From<embedded_can::StandardId> for StandardId { } } -/// Extended 29-bit CAN Identifier (`0..=1FFF_FFFF`). +/// Extended 29-bit TWAI Identifier (`0..=1FFF_FFFF`). #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub struct ExtendedId(u32); impl ExtendedId { - /// CAN ID `0`, the highest priority. + /// TWAI ID `0`, the highest priority. pub const ZERO: Self = ExtendedId(0); - /// CAN ID `0x1FFFFFFF`, the lowest priority. + /// TWAI ID `0x1FFFFFFF`, the lowest priority. pub const MAX: Self = ExtendedId(0x1FFF_FFFF); /// Tries to create a `ExtendedId` from a raw 32-bit integer. @@ -359,7 +357,7 @@ impl ExtendedId { ExtendedId(raw) } - /// Returns this CAN Identifier as a raw 32-bit integer. + /// Returns TWAI Identifier as a raw 32-bit integer. #[inline] pub fn as_raw(&self) -> u32 { self.0 @@ -400,7 +398,7 @@ impl From<embedded_can::ExtendedId> for ExtendedId { } } -/// A CAN Identifier (standard or extended). +/// A TWAI Identifier (standard or extended). #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub enum Id { /// Standard 11-bit Identifier (`0..=0x7FF`). @@ -474,8 +472,9 @@ pub struct EspTwaiFrame { } impl EspTwaiFrame { + /// Creates a new `EspTwaiFrame` with the specified ID and data payload. pub fn new(id: Id, data: &[u8]) -> Option<Self> { - // CAN2.0 frames cannot contain more than 8 bytes of data. + // TWAI frames cannot contain more than 8 bytes of data. if data.len() > 8 { return None; } @@ -493,8 +492,10 @@ impl EspTwaiFrame { }) } + /// Creates a new `EspTwaiFrame` for a transmission request with the + /// specified ID and data length (DLC). pub fn new_remote(id: Id, dlc: usize) -> Option<Self> { - // CAN2.0 frames cannot have more than 8 bytes. + // TWAI frames cannot have more than 8 bytes. if dlc > 8 { return None; } @@ -508,6 +509,8 @@ impl EspTwaiFrame { }) } + /// Creates a new `EspTwaiFrame` ready for self-reception with the specified + /// ID and data payload. pub fn new_self_reception(id: Id, data: &[u8]) -> Option<Self> { if data.len() > 8 { return None; @@ -635,10 +638,23 @@ impl embedded_can::Frame for EspTwaiFrame { /// The underlying timings for the TWAI peripheral. pub struct TimingConfig { + /// The baudrate prescaler is used to determine the period of each time + /// quantum by dividing the TWAI controller's source clock. pub baud_rate_prescaler: u16, + + /// The synchronization jump width is used to determine the maximum number + /// of time quanta a single bit time can be lengthened/shortened for + /// synchronization purposes. pub sync_jump_width: u8, + + /// Timing segment 1 consists of 1 to 16 time quanta before sample point. pub tseg_1: u8, + + /// Timing Segment 2 consists of 1 to 8 time quanta after sample point. pub tseg_2: u8, + + /// Enabling triple sampling causes 3 time quanta to be sampled per bit + /// instead of 1. pub triple_sample: bool, } @@ -646,33 +662,24 @@ pub struct TimingConfig { /// Currently these timings are sourced from the ESP IDF C driver which assumes /// an APB clock of 80MHz. pub enum BaudRate { + /// A baud rate of 125 Kbps. B125K, + /// A baud rate of 250 Kbps. B250K, + /// A baud rate of 500 Kbps. B500K, + /// A baud rate of 1 Mbps. B1000K, + /// A custom baud rate defined by the user. + /// + /// This variant allows users to specify their own timing configuration + /// using a `TimingConfig` struct. Custom(TimingConfig), } impl BaudRate { /// Convert the BaudRate into the timings that the peripheral needs. - // These timings are copied from the ESP IDF C driver. - // #define TWAI_TIMING_CONFIG_25KBITS() {.brp = 128, .tseg_1 = 16, .tseg_2 = - // 8, .sjw = 3, .triple_sampling = false} - // #define TWAI_TIMING_CONFIG_50KBITS() {.brp = 80, .tseg_1 = 15, .tseg_2 = - // 4, .sjw = 3, .triple_sampling = false} - // #define TWAI_TIMING_CONFIG_100KBITS() {.brp = 40, .tseg_1 = 15, .tseg_2 = - // 4, .sjw = 3, .triple_sampling = false} - // #define TWAI_TIMING_CONFIG_125KBITS() {.brp = 32, .tseg_1 = 15, .tseg_2 = - // 4, .sjw = 3, .triple_sampling = false} - // #define TWAI_TIMING_CONFIG_250KBITS() {.brp = 16, .tseg_1 = 15, .tseg_2 = - // 4, .sjw = 3, .triple_sampling = false} - // #define TWAI_TIMING_CONFIG_500KBITS() {.brp = 8, .tseg_1 = 15, .tseg_2 = 4, - // .sjw = 3, .triple_sampling = false} #define TWAI_TIMING_CONFIG_800KBITS() - // {.brp = 4, .tseg_1 = 16, .tseg_2 = 8, .sjw = 3, .triple_sampling = false} - // #define TWAI_TIMING_CONFIG_1MBITS() {.brp = 4, .tseg_1 = 15, .tseg_2 = 4, - // .sjw = 3, .triple_sampling = false} - // - // see https://github.com/espressif/esp-idf/tree/master/components/hal/include/hal/twai_types.h + // See: https://github.com/espressif/esp-idf/tree/master/components/hal/include/hal/twai_types.h const fn timing(self) -> TimingConfig { #[allow(unused_mut)] let mut timing = match self { @@ -1024,10 +1031,12 @@ where } } + /// Returns the value of the receive error counter. pub fn receive_error_count(&self) -> u8 { T::register_block().rx_err_cnt().read().rx_err_cnt().bits() } + /// Returns the value of the transmit error counter. pub fn transmit_error_count(&self) -> u8 { T::register_block().tx_err_cnt().read().tx_err_cnt().bits() } @@ -1067,10 +1076,12 @@ where } } + /// Sends the specified `EspTwaiFrame` over the TWAI bus. pub fn transmit(&mut self, frame: &EspTwaiFrame) -> nb::Result<(), EspTwaiError> { self.tx.transmit(frame) } + /// Receives a TWAI frame from the TWAI bus. pub fn receive(&mut self) -> nb::Result<EspTwaiFrame, EspTwaiError> { self.rx.receive() } @@ -1082,7 +1093,7 @@ where } } -/// Interface to the CAN transmitter part. +/// Interface to the TWAI transmitter part. pub struct TwaiTx<'d, T, DM: crate::Mode> { _peripheral: PhantomData<&'d T>, phantom: PhantomData<DM>, @@ -1124,7 +1135,7 @@ where } } -/// Interface to the CAN receiver part. +/// Interface to the TWAI receiver part. pub struct TwaiRx<'d, T, DM: crate::Mode> { _peripheral: PhantomData<&'d T>, phantom: PhantomData<DM>, @@ -1135,7 +1146,7 @@ where T: OperationInstance, DM: crate::Mode, { - // Receive a frame + /// Receive a frame pub fn receive(&mut self) -> nb::Result<EspTwaiFrame, EspTwaiError> { let register_block = T::register_block(); let status = register_block.status().read(); @@ -1166,9 +1177,14 @@ where } } +/// Represents errors that can occur in the TWAI driver. +/// This enum defines the possible errors that can be encountered when +/// interacting with the TWAI peripheral. #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub enum EspTwaiError { + /// TWAI peripheral has entered a bus-off state. BusOff, + /// Encapsulates errors defined by the embedded-hal crate. EmbeddedHAL(ErrorKind), } @@ -1274,28 +1290,41 @@ where } } +/// TWAI peripheral instance. pub trait Instance: crate::private::Sealed { + /// The system peripheral associated with this TWAI instance. const SYSTEM_PERIPHERAL: system::Peripheral; + /// The identifier number for this TWAI instance. const NUMBER: usize; + /// Input signal. const INPUT_SIGNAL: InputSignal; + /// Output signal. const OUTPUT_SIGNAL: OutputSignal; - + /// The interrupt associated with this TWAI instance. const INTERRUPT: crate::peripherals::Interrupt; #[cfg(feature = "async")] + /// Provides an asynchronous interrupt handler for TWAI instance. fn async_handler() -> InterruptHandler; + /// Returns a reference to the register block for TWAI instance. fn register_block() -> &'static RegisterBlock; + /// Enables the TWAI peripheral. fn enable_peripheral(); + /// Resets the TWAI peripheral. fn reset_peripheral(); + /// Enables interrupts for the TWAI peripheral. fn enable_interrupts(); } +/// An extension of the `Instance` trait that provides additional operations +/// for managing and interacting with the TWAI peripheral. pub trait OperationInstance: Instance { #[cfg(feature = "async")] + /// Returns a reference to the asynchronous state for this TWAI instance. fn async_state() -> &'static asynch::TwaiAsyncState { &asynch::TWAI_STATE[Self::NUMBER] } @@ -1652,10 +1681,11 @@ mod asynch { where T: OperationInstance, { + /// Transmits an `EspTwaiFrame` asynchronously over the TWAI bus. pub async fn transmit_async(&mut self, frame: &EspTwaiFrame) -> Result<(), EspTwaiError> { self.tx.transmit_async(frame).await } - + /// Receives an `EspTwaiFrame` asynchronously over the TWAI bus. pub async fn receive_async(&mut self) -> Result<EspTwaiFrame, EspTwaiError> { self.rx.receive_async().await } @@ -1665,6 +1695,7 @@ mod asynch { where T: OperationInstance, { + /// Transmits an `EspTwaiFrame` asynchronously over the TWAI bus. pub async fn transmit_async(&mut self, frame: &EspTwaiFrame) -> Result<(), EspTwaiError> { T::enable_interrupts(); poll_fn(|cx| { @@ -1694,6 +1725,7 @@ mod asynch { where T: OperationInstance, { + /// Receives an `EspTwaiFrame` asynchronously over the TWAI bus. pub async fn receive_async(&mut self) -> Result<EspTwaiFrame, EspTwaiError> { T::enable_interrupts(); poll_fn(|cx| { diff --git a/esp-riscv-rt/src/lib.rs b/esp-riscv-rt/src/lib.rs index 2283280c96d..a7f344327e3 100644 --- a/esp-riscv-rt/src/lib.rs +++ b/esp-riscv-rt/src/lib.rs @@ -71,44 +71,92 @@ pub unsafe extern "C" fn start_rust(a0: usize, a1: usize, a2: usize) -> ! { } /// Registers saved in trap handler -#[allow(missing_docs)] #[derive(Debug, Default, Clone, Copy)] #[repr(C)] pub struct TrapFrame { + /// Return address, stores the address to return to after a function call or + /// interrupt. pub ra: usize, + /// Temporary register t0, used for intermediate values. pub t0: usize, + /// Temporary register t1, used for intermediate values. pub t1: usize, + /// Temporary register t2, used for intermediate values. pub t2: usize, + /// Temporary register t3, used for intermediate values. pub t3: usize, + /// Temporary register t4, used for intermediate values. pub t4: usize, + /// Temporary register t5, used for intermediate values. pub t5: usize, + /// Temporary register t6, used for intermediate values. pub t6: usize, + /// Argument register a0, typically used to pass the first argument to a + /// function. pub a0: usize, + /// Argument register a1, typically used to pass the second argument to a + /// function. pub a1: usize, + /// Argument register a2, typically used to pass the third argument to a + /// function. pub a2: usize, + /// Argument register a3, typically used to pass the fourth argument to a + /// function. pub a3: usize, + /// Argument register a4, typically used to pass the fifth argument to a + /// function. pub a4: usize, + /// Argument register a5, typically used to pass the sixth argument to a + /// function. pub a5: usize, + /// Argument register a6, typically used to pass the seventh argument to a + /// function. pub a6: usize, + /// Argument register a7, typically used to pass the eighth argument to a + /// function. pub a7: usize, + /// Saved register s0, used to hold values across function calls. pub s0: usize, + /// Saved register s1, used to hold values across function calls. pub s1: usize, + /// Saved register s2, used to hold values across function calls. pub s2: usize, + /// Saved register s3, used to hold values across function calls. pub s3: usize, + /// Saved register s4, used to hold values across function calls. pub s4: usize, + /// Saved register s5, used to hold values across function calls. pub s5: usize, + /// Saved register s6, used to hold values across function calls. pub s6: usize, + /// Saved register s7, used to hold values across function calls. pub s7: usize, + /// Saved register s8, used to hold values across function calls. pub s8: usize, + /// Saved register s9, used to hold values across function calls. pub s9: usize, + /// Saved register s10, used to hold values across function calls. pub s10: usize, + /// Saved register s11, used to hold values across function calls. pub s11: usize, + /// Global pointer register, holds the address of the global data area. pub gp: usize, + /// Thread pointer register, holds the address of the thread-local storage + /// area. pub tp: usize, + /// Stack pointer register, holds the address of the top of the stack. pub sp: usize, + /// Program counter, stores the address of the next instruction to be + /// executed. pub pc: usize, + /// Machine status register, holds the current status of the processor, + /// including interrupt enable bits and privilege mode. pub mstatus: usize, + /// Machine cause register, contains the reason for the trap (e.g., + /// exception or interrupt number). pub mcause: usize, + /// Machine trap value register, contains additional information about the + /// trap (e.g., faulting address). pub mtval: usize, }