Documenting a number of peripherals and packages

CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implement sleep with some wakeup methods for `esp32-s3` (#660, #689, #696)
 - Add feature enabling directly hooking the interrupt vector table
 - Add `ClockControl::max` helper for all chips (#701)
+- Added module-level documentation for all peripherals
+- Added module-level documentation for all peripherals (#680)
 
 ### Changed
 

esp-hal-common/src/aes/mod.rs

@@ -1,10 +1,61 @@
-//! Advanced Encryption Standard (AES) support.
+//! # Advanced Encryption Standard (AES) support.
 //!
-//! This module provides functions and structs for AES encryption and
-//! decryption.
+//! ## Overview
+//! The AES module provides an interface to interact with the AES peripheral,
+//! provides encryption and decryption capabilities for ESP chips using the AES
+//! algorithm. We currently support the following AES encryption modes:
+//! * AES-128
+//! * AES-192
+//! * AES-256
+//!
+//! ## Example
+//! ### Initialization
+//! ```no_run
+//! let mut aes = Aes::new(peripherals.AES, &mut system.peripheral_clock_control);
+//! ```
+//! ### Creating key and block Buffer
+//! ```no_run
+//! let keytext = "SUp4SeCp@sSw0rd".as_bytes();
+//! let plaintext = "message".as_bytes();
+//!
+//! // create an array with aes128 key size
+//! let mut keybuf = [0_u8; 16];
+//! keybuf[..keytext.len()].copy_from_slice(keytext);
+//!
+//! // create an array with aes block size
+//! let mut block_buf = [0_u8; 16];
+//! block_buf[..plaintext.len()].copy_from_slice(plaintext);
+//! ```
+//!
+//! ### Encrypting and Decrypting (using hardware)
+//! ```no_run
+//! let key = Key::<Aes128>::from(&keybuf);
+//!
+//! let mut cipher = Cipher::new(&mut aes, &key);
+//! let mut block = block_buf.clone();
+//! cipher.encrypt_block(&mut block);
+//!
+//! let hw_encrypted = block.clone();
+//! cipher.decrypt_block(&mut block);
+//! let hw_decrypted = block;
+//! ```
+//!
+//! ### Encrypting and Decrypting (using software)
+//! ```no_run
+//! let key = GenericArray::from(keybuf);
+//!
+//! let mut block = GenericArray::from(block_buf);
+//! let cipher = Aes128SW::new(&key);
+//! cipher.encrypt_block(&mut block);
+//!
+//! let sw_encrypted = block.clone();
+//! cipher.decrypt_block(&mut block);
+//!
+//! let sw_decrypted = block;
+//! ```
 //!
 //! ### Implementation State
-//! * DMA mode is currently not supported.
+//! * DMA mode is currently not supported ⚠️
 
 use core::marker::PhantomData;
 

esp-hal-common/src/analog/adc/esp32.rs

@@ -421,10 +421,15 @@ macro_rules! impl_adc_interface {
 pub use impl_adc_interface;
 
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
     //!
-    //! This module provides functions for reading analog values from two
-    //! analog to digital converters available on the ESP32: `ADC1` and `ADC2`.
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
+    //!
+    //! This module provides functions for reading analog values from the
+    //! analog to digital converter available on the ESP32: `ADC1` and `ADC2`.
     //!
     //! The following pins can be configured for analog readout:
     //!
@@ -440,6 +445,28 @@ pub mod implementation {
     //! | 7       | GPIO35 (VDET_2)      | GPIO27        |
     //! | 8       |                      | GPIO25        |
     //! | 9       |                      | GPIO26        |
+    //!
+    //! ## Example
+    //! #### ADC on Xtensa architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.SENS.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin3 =
+    //!     adc1_config.enable_pin(io.pins.gpio3.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(analog.adc1, adc1_config).unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
+    //!
+    //! loop {
+    //!     let pin3_value: u16 = nb::block!(adc1.read(&mut pin3)).unwrap();
+    //!     println!("PIN3 ADC reading = {}", pin3_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;
 

esp-hal-common/src/analog/adc/riscv.rs

@@ -691,10 +691,41 @@ pub use impl_adc_interface;
 
 #[cfg(esp32c2)]
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
+    //!
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
     //!
     //! This module provides functions for reading analog values from the
     //! analog to digital converter available on the ESP32-C2: `ADC1`.
+    //!
+    //! ## Example
+    //! #### ADC on Risc-V architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.APB_SARADC.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin = adc1_config.enable_pin(io.pins.gpio2.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(
+    //!     &mut system.peripheral_clock_control,
+    //!     analog.adc1,
+    //!     adc1_config,
+    //! )
+    //! .unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
+    //!
+    //! loop {
+    //!     let pin_value: u16 = nb::block!(adc1.read(&mut pin)).unwrap();
+    //!     println!("PIN2 ADC reading = {}", pin_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;
 
@@ -714,11 +745,42 @@ pub mod implementation {
 
 #[cfg(esp32c3)]
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
+    //!
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
     //!
-    //! This module provides functions for reading analog values from two
-    //! analog to digital converters available on the ESP32-C3: `ADC1` and
+    //! This module provides functions for reading analog values from the
+    //! analog to digital converter available on the ESP32-C3: `ADC1` and
     //! `ADC2`.
+    //!
+    //! ## Example
+    //! #### ADC on Risc-V architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.APB_SARADC.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin = adc1_config.enable_pin(io.pins.gpio2.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(
+    //!     &mut system.peripheral_clock_control,
+    //!     analog.adc1,
+    //!     adc1_config,
+    //! )
+    //! .unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
+    //!
+    //! loop {
+    //!     let pin_value: u16 = nb::block!(adc1.read(&mut pin)).unwrap();
+    //!     println!("PIN2 ADC reading = {}", pin_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;
 
@@ -744,10 +806,41 @@ pub mod implementation {
 
 #[cfg(esp32c6)]
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
+    //!
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
     //!
-    //! This module provides functions for reading analog values from one
+    //! This module provides functions for reading analog values from the
     //! analog to digital converter available on the ESP32-C6: `ADC1`.
+    //!
+    //! ## Example
+    //! #### ADC on Risc-V architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.APB_SARADC.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin = adc1_config.enable_pin(io.pins.gpio2.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(
+    //!     &mut system.peripheral_clock_control,
+    //!     analog.adc1,
+    //!     adc1_config,
+    //! )
+    //! .unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
+    //!
+    //! loop {
+    //!     let pin_value: u16 = nb::block!(adc1.read(&mut pin)).unwrap();
+    //!     println!("PIN2 ADC reading = {}", pin_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;
 
@@ -769,10 +862,41 @@ pub mod implementation {
 
 #[cfg(esp32h2)]
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
+    //!
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
+    //!
+    //! This module provides functions for reading analog values from the
+    //! analog to digital converter available on the  ESP32-H2: `ADC1`.
+    //!
+    //! ## Example
+    //! #### ADC on Risc-V architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.APB_SARADC.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin = adc1_config.enable_pin(io.pins.gpio2.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(
+    //!     &mut system.peripheral_clock_control,
+    //!     analog.adc1,
+    //!     adc1_config,
+    //! )
+    //! .unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
     //!
-    //! This module provides functions for reading analog values from one
-    //! analog to digital converter available on the ESP32-H2: `ADC1`.
+    //! loop {
+    //!     let pin_value: u16 = nb::block!(adc1.read(&mut pin)).unwrap();
+    //!     println!("PIN2 ADC reading = {}", pin_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;
 

esp-hal-common/src/analog/adc/xtensa.rs

@@ -753,11 +753,38 @@ pub use impl_adc_interface;
 
 #[cfg(esp32s3)]
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
     //!
-    //! This module provides functions for reading analog values from two
-    //! analog to digital converters available on the ESP32-S3: `ADC1` and
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
+    //!
+    //! This module provides functions for reading analog values from the
+    //! analog to digital converter available on the ESP32-S3: `ADC1` and
     //! `ADC2`.
+    //!
+    //! ## Example
+    //! #### ADC on Xtensa architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.SENS.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin3 =
+    //!     adc1_config.enable_pin(io.pins.gpio3.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(analog.adc1, adc1_config).unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
+    //!
+    //! loop {
+    //!     let pin3_value: u16 = nb::block!(adc1.read(&mut pin3)).unwrap();
+    //!     println!("PIN3 ADC reading = {}", pin3_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;
 
@@ -798,11 +825,38 @@ pub mod implementation {
 
 #[cfg(esp32s2)]
 pub mod implementation {
-    //! Analog to digital (ADC) conversion support.
+    //! # Analog to digital (ADC) conversion support.
     //!
-    //! This module provides functions for reading analog values from two
-    //! analog to digital converters available on the ESP32-S2: `ADC1` and
+    //! ## Overview
+    //! The `ADC` module in the `analog` driver enables users to perform
+    //! analog-to-digital conversions, allowing them to measure real-world
+    //! analog signals with high accuracy.
+    //!
+    //! This module provides functions for reading analog values from the
+    //! analog to digital converter available on the ESP32-S2: `ADC1` and
     //! `ADC2`.
+    //!
+    //! ## Example
+    //! #### ADC on Xtensa architecture
+    //! ```no_run
+    //! // Create ADC instances
+    //! let analog = peripherals.SENS.split();
+    //!
+    //! let mut adc1_config = AdcConfig::new();
+    //!
+    //! let mut pin3 =
+    //!     adc1_config.enable_pin(io.pins.gpio3.into_analog(), Attenuation::Attenuation11dB);
+    //!
+    //! let mut adc1 = ADC::<ADC1>::adc(analog.adc1, adc1_config).unwrap();
+    //!
+    //! let mut delay = Delay::new(&clocks);
+    //!
+    //! loop {
+    //!     let pin3_value: u16 = nb::block!(adc1.read(&mut pin3)).unwrap();
+    //!     println!("PIN3 ADC reading = {}", pin3_value);
+    //!     delay.delay_ms(1500u32);
+    //! }
+    //! ```
 
     use embedded_hal::adc::Channel;