From 45db1b55eca45ab8cd3c31f32f7040bc0a94cec7 Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Thu, 25 Jul 2024 13:05:59 +0000 Subject: [PATCH] Add `#![deny(missing_docs)]` to the `aes`, `analog`, `clock`, and `dma` modules (#1849) * Deny missing documentation within the `analog` module * Deny missing documentation in the `dma` module * Remove unused `ENCRYPT_MODE`/`DECRYPT_MODE` constants from `AesFlavour` trait * Deny missing documentation in the `aes` module * Deny missing documentation in the `clock` module * Update `CHANGELOG.md` --- esp-hal/CHANGELOG.md | 1 + esp-hal/src/aes/esp32.rs | 6 ------ esp-hal/src/aes/esp32cX.rs | 4 ---- esp-hal/src/aes/esp32s2.rs | 6 ------ esp-hal/src/aes/esp32s3.rs | 4 ---- esp-hal/src/aes/mod.rs | 13 +++++++++++-- esp-hal/src/analog/adc/esp32.rs | 8 ++++++-- esp-hal/src/analog/adc/mod.rs | 10 ++++++++-- esp-hal/src/analog/adc/riscv.rs | 1 + esp-hal/src/analog/adc/xtensa.rs | 1 + esp-hal/src/analog/dac.rs | 2 -- esp-hal/src/analog/mod.rs | 2 ++ esp-hal/src/clock/mod.rs | 27 ++++++++++++++++++++++++++- esp-hal/src/dma/mod.rs | 3 ++- 14 files changed, 58 insertions(+), 30 deletions(-) diff --git a/esp-hal/CHANGELOG.md b/esp-hal/CHANGELOG.md index 65ed09e99..60ab17404 100644 --- a/esp-hal/CHANGELOG.md +++ b/esp-hal/CHANGELOG.md @@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Removed - This package no longer re-exports the `esp_hal_procmacros::main` macro (#1828) +- The `AesFlavour` trait no longer has the `ENCRYPT_MODE`/`DECRYPT_MODE` associated constants (#1849) ## [0.19.0] - 2024-07-15 diff --git a/esp-hal/src/aes/esp32.rs b/esp-hal/src/aes/esp32.rs index d57289447..f9920a9a4 100644 --- a/esp-hal/src/aes/esp32.rs +++ b/esp-hal/src/aes/esp32.rs @@ -73,18 +73,12 @@ impl<'d> Aes<'d> { impl AesFlavour for Aes128 { type KeyType<'b> = &'b [u8; 16]; - const ENCRYPT_MODE: u32 = 0; - const DECRYPT_MODE: u32 = 4; } impl AesFlavour for Aes192 { type KeyType<'b> = &'b [u8; 24]; - const ENCRYPT_MODE: u32 = 1; - const DECRYPT_MODE: u32 = 5; } impl AesFlavour for Aes256 { type KeyType<'b> = &'b [u8; 32]; - const ENCRYPT_MODE: u32 = 2; - const DECRYPT_MODE: u32 = 6; } diff --git a/esp-hal/src/aes/esp32cX.rs b/esp-hal/src/aes/esp32cX.rs index 1f59ed4cd..bd653da4a 100644 --- a/esp-hal/src/aes/esp32cX.rs +++ b/esp-hal/src/aes/esp32cX.rs @@ -50,12 +50,8 @@ impl<'d> Aes<'d> { impl AesFlavour for Aes128 { type KeyType<'b> = &'b [u8; 16]; - const ENCRYPT_MODE: u32 = 0; - const DECRYPT_MODE: u32 = 4; } impl AesFlavour for Aes256 { type KeyType<'b> = &'b [u8; 32]; - const ENCRYPT_MODE: u32 = 2; - const DECRYPT_MODE: u32 = 6; } diff --git a/esp-hal/src/aes/esp32s2.rs b/esp-hal/src/aes/esp32s2.rs index cb9273968..926612821 100644 --- a/esp-hal/src/aes/esp32s2.rs +++ b/esp-hal/src/aes/esp32s2.rs @@ -87,18 +87,12 @@ impl<'d> Aes<'d> { impl AesFlavour for Aes128 { type KeyType<'b> = &'b [u8; 16]; - const ENCRYPT_MODE: u32 = 0; - const DECRYPT_MODE: u32 = 4; } impl AesFlavour for Aes192 { type KeyType<'b> = &'b [u8; 24]; - const ENCRYPT_MODE: u32 = 1; - const DECRYPT_MODE: u32 = 5; } impl AesFlavour for Aes256 { type KeyType<'b> = &'b [u8; 32]; - const ENCRYPT_MODE: u32 = 2; - const DECRYPT_MODE: u32 = 6; } diff --git a/esp-hal/src/aes/esp32s3.rs b/esp-hal/src/aes/esp32s3.rs index 4cff965db..6adc10844 100644 --- a/esp-hal/src/aes/esp32s3.rs +++ b/esp-hal/src/aes/esp32s3.rs @@ -59,12 +59,8 @@ impl<'d> Aes<'d> { impl AesFlavour for Aes128 { type KeyType<'b> = &'b [u8; 16]; - const ENCRYPT_MODE: u32 = 0; - const DECRYPT_MODE: u32 = 4; } impl AesFlavour for Aes256 { type KeyType<'b> = &'b [u8; 32]; - const ENCRYPT_MODE: u32 = 2; - const DECRYPT_MODE: u32 = 6; } diff --git a/esp-hal/src/aes/mod.rs b/esp-hal/src/aes/mod.rs index 49d530897..99363307f 100644 --- a/esp-hal/src/aes/mod.rs +++ b/esp-hal/src/aes/mod.rs @@ -46,6 +46,8 @@ //! * AES-DMA mode is currently not supported on ESP32 and ESP32S2 //! * AES-DMA Initialization Vector (IV) is currently not supported +#![deny(missing_docs)] + use crate::{ peripheral::{Peripheral, PeripheralRef}, peripherals::AES, @@ -179,9 +181,11 @@ impl<'d> Aes<'d> { /// Specifications for AES flavours pub trait AesFlavour: crate::private::Sealed { + /// Type of the AES key, a fixed-size array of bytes + /// + /// The size of this type depends on various factors, such as the device + /// being targeted and the desired key size. type KeyType<'b>; - const ENCRYPT_MODE: u32; - const DECRYPT_MODE: u32; } /// Marker type for AES-128 @@ -202,7 +206,9 @@ impl crate::private::Sealed for Aes256 {} /// State matrix endianness #[cfg(any(esp32, esp32s2))] pub enum Endianness { + /// Big endian (most-significant byte at the smallest address) BigEndian = 1, + /// Little endian (least-significant byte at the smallest address) LittleEndian = 0, } @@ -258,6 +264,7 @@ pub mod dma { C: DmaChannel, C::P: AesPeripheral, { + /// The underlying [`Aes`](super::Aes) driver pub aes: super::Aes<'d>, pub(crate) channel: Channel<'d, C, crate::Blocking>, @@ -265,11 +272,13 @@ pub mod dma { rx_chain: DescriptorChain, } + /// Functionality for using AES with DMA. pub trait WithDmaAes<'d, C> where C: DmaChannel, C::P: AesPeripheral, { + /// Enable DMA for the current instance of the AES driver fn with_dma( self, channel: Channel<'d, C, crate::Blocking>, diff --git a/esp-hal/src/analog/adc/esp32.rs b/esp-hal/src/analog/adc/esp32.rs index fb80b2836..ec6bdac10 100644 --- a/esp-hal/src/analog/adc/esp32.rs +++ b/esp-hal/src/analog/adc/esp32.rs @@ -9,9 +9,13 @@ pub(super) const NUM_ATTENS: usize = 10; /// The sampling/readout resolution of the ADC. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub enum Resolution { + /// 9-bit resolution Resolution9Bit = 0b00, + /// 10-bit resolution Resolution10Bit = 0b01, + /// 11-bit resolution Resolution11Bit = 0b10, + /// 12-bit resolution #[default] Resolution12Bit = 0b11, } @@ -324,15 +328,15 @@ where } impl<'d, ADC1> Adc<'d, ADC1> { + /// Enable the Hall sensor pub fn enable_hall_sensor() { - // Connect hall sensor unsafe { &*RTC_IO::ptr() } .hall_sens() .modify(|_, w| w.xpd_hall().set_bit()); } + /// Disable the Hall sensor pub fn disable_hall_sensor() { - // Disconnect hall sensor unsafe { &*RTC_IO::ptr() } .hall_sens() .modify(|_, w| w.xpd_hall().clear_bit()); diff --git a/esp-hal/src/analog/adc/mod.rs b/esp-hal/src/analog/adc/mod.rs index aac7ab1bd..1185d05ba 100644 --- a/esp-hal/src/analog/adc/mod.rs +++ b/esp-hal/src/analog/adc/mod.rs @@ -87,13 +87,17 @@ pub enum Attenuation { #[cfg(not(esp32))] #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum AdcCalSource { + /// Use Ground as the calibration source Gnd, + /// Use Vref as the calibration source Ref, } /// An I/O pin which can be read using the ADC. pub struct AdcPin { + /// The underlying GPIO pin pub pin: PIN, + /// Calibration scheme used for the configured ADC pin #[cfg_attr(esp32, allow(unused))] pub cal_scheme: CS, _phantom: PhantomData, @@ -113,8 +117,9 @@ where /// Configuration for the ADC. pub struct AdcConfig { - pub resolution: Resolution, - pub attenuations: [Option; NUM_ATTENS], + #[cfg_attr(not(esp32), allow(unused))] + resolution: Resolution, + attenuations: [Option; NUM_ATTENS], _phantom: PhantomData, } @@ -190,6 +195,7 @@ pub trait CalibrationAccess: RegisterAccess { /// A helper trait to get the ADC channel of a compatible GPIO pin. pub trait AdcChannel { + /// Channel number used by the ADC const CHANNEL: u8; } diff --git a/esp-hal/src/analog/adc/riscv.rs b/esp-hal/src/analog/adc/riscv.rs index fbac76fa4..428acea33 100644 --- a/esp-hal/src/analog/adc/riscv.rs +++ b/esp-hal/src/analog/adc/riscv.rs @@ -103,6 +103,7 @@ cfg_if::cfg_if! { /// The sampling/readout resolution of the ADC. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub enum Resolution { + /// 12-bit resolution #[default] Resolution12Bit, } diff --git a/esp-hal/src/analog/adc/xtensa.rs b/esp-hal/src/analog/adc/xtensa.rs index c31ee154f..65e51d75f 100644 --- a/esp-hal/src/analog/adc/xtensa.rs +++ b/esp-hal/src/analog/adc/xtensa.rs @@ -74,6 +74,7 @@ cfg_if::cfg_if! { /// The sampling/readout resolution of the ADC. #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] pub enum Resolution { + /// 13-bit resolution #[default] Resolution13Bit, } diff --git a/esp-hal/src/analog/dac.rs b/esp-hal/src/analog/dac.rs index 3dfee0809..d0244c4ba 100644 --- a/esp-hal/src/analog/dac.rs +++ b/esp-hal/src/analog/dac.rs @@ -41,8 +41,6 @@ //! # } //! ``` -#![deny(missing_docs)] - use crate::{ gpio::{self, AnalogPin}, peripheral::{Peripheral, PeripheralRef}, diff --git a/esp-hal/src/analog/mod.rs b/esp-hal/src/analog/mod.rs index cac201b4c..714642f7d 100644 --- a/esp-hal/src/analog/mod.rs +++ b/esp-hal/src/analog/mod.rs @@ -5,6 +5,8 @@ //! available on the device. For more information about a peripheral driver, //! please refer to the relevant module documentation. +#![deny(missing_docs)] + #[cfg(adc)] pub mod adc; #[cfg(dac)] diff --git a/esp-hal/src/clock/mod.rs b/esp-hal/src/clock/mod.rs index c39388db9..af1f19d0a 100644 --- a/esp-hal/src/clock/mod.rs +++ b/esp-hal/src/clock/mod.rs @@ -70,6 +70,8 @@ //! # } //! ``` +#![deny(missing_docs)] + use fugit::HertzU32; #[cfg(any(esp32, esp32c2))] @@ -88,13 +90,17 @@ use crate::{ #[cfg_attr(esp32s3, path = "clocks_ll/esp32s3.rs")] pub(crate) mod clocks_ll; +/// Clock properties pub trait Clock { + /// Frequency of the clock in [Hertz](fugit::HertzU32), using [fugit] types. fn frequency(&self) -> HertzU32; + /// Frequency of the clock in Megahertz fn mhz(&self) -> u32 { self.frequency().to_MHz() } + /// Frequency of the clock in Hertz fn hz(&self) -> u32 { self.frequency().to_Hz() } @@ -103,14 +109,19 @@ pub trait Clock { /// CPU clock speed #[derive(Debug, Clone, Copy)] pub enum CpuClock { + /// 80MHz CPU clock #[cfg(not(esp32h2))] Clock80MHz, + /// 96MHz CPU clock #[cfg(esp32h2)] Clock96MHz, + /// 120MHz CPU clock #[cfg(esp32c2)] Clock120MHz, + /// 160MHz CPU clock #[cfg(not(any(esp32c2, esp32h2)))] Clock160MHz, + /// 240MHz CPU clock #[cfg(xtensa)] Clock240MHz, } @@ -133,15 +144,20 @@ impl Clock for CpuClock { } } +/// XTAL clock speed #[derive(Debug, Clone, Copy)] #[non_exhaustive] pub enum XtalClock { + /// 26MHz XTAL clock #[cfg(any(esp32, esp32c2))] RtcXtalFreq26M, + /// 32MHz XTAL clock #[cfg(any(esp32c3, esp32h2, esp32s3))] RtcXtalFreq32M, + /// 40MHz XTAL clock #[cfg(not(esp32h2))] RtcXtalFreq40M, + /// Other XTAL clock RtcXtalFreqOther(u32), } @@ -239,23 +255,32 @@ impl Clock for ApbClock { /// Frozen clock frequencies /// -/// The existence of this value indicates that the clock configuration can no +/// The instantiation of this type indicates that the clock configuration can no /// longer be changed pub struct Clocks<'d> { _private: PeripheralRef<'d, SystemClockControl>, + /// CPU clock frequency pub cpu_clock: HertzU32, + /// APB clock frequency pub apb_clock: HertzU32, + /// XTAL clock frequency pub xtal_clock: HertzU32, + /// I2C clock frequency #[cfg(esp32)] pub i2c_clock: HertzU32, + /// PWM clock frequency #[cfg(esp32)] pub pwm_clock: HertzU32, + /// Crypto PWM clock frequency #[cfg(esp32s3)] pub crypto_pwm_clock: HertzU32, + /// Crypto clock frequency #[cfg(any(esp32c6, esp32h2))] pub crypto_clock: HertzU32, + /// PLL 48M clock frequency (fixed) #[cfg(esp32h2)] pub pll_48m_clock: HertzU32, + /// PLL 96M clock frequency (fixed) #[cfg(esp32h2)] pub pll_96m_clock: HertzU32, } diff --git a/esp-hal/src/dma/mod.rs b/esp-hal/src/dma/mod.rs index dafadbd90..3d26f6ddc 100644 --- a/esp-hal/src/dma/mod.rs +++ b/esp-hal/src/dma/mod.rs @@ -49,7 +49,8 @@ //! on esp32s3. //! //! For convenience you can use the [crate::dma_buffers] macro. -#![warn(missing_docs)] + +#![deny(missing_docs)] use core::{fmt::Debug, marker::PhantomData, ptr::addr_of_mut, sync::atomic::compiler_fence};