Prefer cfg_if (#2003)

documentation/API-GUIDELINES.md

@@ -53,6 +53,7 @@ The following paragraphs contain additional recommendations.
 - If necessary provide further context as comments (consider linking to code, PRs, TRM - make sure to use permanent links, e.g. include the hash when linking to a Git repository, include the revision, page number etc. when linking to TRMs)
 - Generally, follow common "good practices" and idiomatic Rust style
 - All `Future` objects (public or private) must be marked with ``#[must_use = "futures do nothing unless you `.await` or poll them"]``.
+- Prefer `cfg_if!` over multiple exclusive `#[cfg]` attributes. `cfg_if!` visually divides the options, often results in simpler conditions and simplifies adding new branches in the future.
 
 ## Modules Documentation
 

esp-hal-embassy/src/executor/thread.rs

@@ -71,6 +71,7 @@ impl Executor {
     #[cfg_attr(
         multi_core,
         doc = r#"
+
     This will use software-interrupt 3 which isn't
     available for anything else to wake the other core(s).
     "#

esp-hal/src/aes/mod.rs

@@ -1,21 +1,26 @@
 //! # Advanced Encryption Standard (AES).
 //!
 //! ## Overview
+//!
 //! The AES accelerator is a hardware device that speeds up computation
 //! using AES algorithm significantly, compared to AES algorithms implemented
 //! solely in software.  The AES accelerator has two working modes, which are
 //! Typical AES and AES-DMA.
 //!
 //! ## Configuration
+//!
 //! The AES peripheral can be configured to encrypt or decrypt data using
 //! different encryption/decryption modes.
 //!
 //! When using AES-DMA, the peripheral can be configured to use different block
 //! cipher modes such as ECB, CBC, OFB, CTR, CFB8, and CFB128.
 //!
 //! ## Examples
-//! ### Encrypting and Decrypting a Message
+//!
+//! ### Encrypting and decrypting a message
+//!
 //! Simple example of encrypting and decrypting a message using AES-128:
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::aes::{Aes, Mode};

esp-hal/src/analog/adc/mod.rs

@@ -1,11 +1,13 @@
 //! # Analog to Digital Converter (ADC)
 //!
 //! ## Overview
+//!
 //! The ADC is integrated on the chip, and is capable of measuring analog
 //! signals from specific analog I/O pins. One or more ADC units are available,
 //! depending on the device being used.
 //!
 //! ## Configuration
+//!
 //! The ADC can be configured to measure analog signals from specific pins. The
 //! configuration includes the resolution of the ADC, the attenuation of the
 //! input signal, and the pins to be measured.
@@ -15,10 +17,13 @@
 //! schemes can be used to improve the accuracy of the ADC readings.
 //!
 //! ## Usage
+//!
 //! The ADC driver implements the `[email protected]` ADC traits.
 //!
-//! ## Examples
-//! #### Read an analog signal from a pin
+//! ## Example
+//!
+//! ### Read an analog signal from a pin
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::analog::adc::AdcConfig;

esp-hal/src/clock/mod.rs

@@ -1,6 +1,7 @@
-//! # Clock Control
+//! # CPU Clock Control
 //!
 //! ## Overview
+//!
 //! Clocks are mainly sourced from oscillator (OSC), RC, and PLL circuits, and
 //! then processed by the dividers or selectors, which allows most functional
 //! modules to select their working clock according to their power consumption

esp-hal/src/dma/mod.rs

@@ -1,6 +1,7 @@
 //! # Direct Memory Access (DMA)
 //!
 //! ## Overview
+//!
 //! The DMA driver provides an interface to efficiently transfer data between
 //! different memory regions and peripherals within the ESP microcontroller
 //! without involving the CPU. The DMA controller is responsible for managing
@@ -10,8 +11,10 @@
 //! `ESP32-S2` are using older `PDMA` controller, whenever other chips are using
 //! newer `GDMA` controller.
 //!
-//! ## Examples
-//! ### Initialize and Utilize DMA Controller in `SPI`
+//! ## Example
+//!
+//! ### Initialize and utilize DMA controller in `SPI`
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::dma_buffers;

esp-hal/src/gpio/mod.rs

@@ -1,23 +1,27 @@
 //! # General Purpose I/Os (GPIO)
 //!
 //! ## Overview
+//!
 //! Each pin can be used as a general-purpose I/O, or be connected to an
 //! internal peripheral signal.
 //!
 //! ## Configuration
+//!
 //! This driver supports various operations on GPIO pins, including setting the
 //! pin mode, direction, and manipulating the pin state (setting high/low,
 //! toggling). It provides an interface to interact with GPIO pins on ESP chips,
 //! allowing developers to control and read the state of the pins.
 //!
 //! ## Usage
+//!
 //! This module also implements a number of traits from [embedded-hal] to
 //! provide a common interface for GPIO pins.
 //!
 //! To get access to the pins, you first need to convert them into a HAL
 //! designed struct from the pac struct `GPIO` and `IO_MUX` using `Io::new`.
 //!
 //! ### Pin Types
+//!
 //! - [Input] pins can be used as digital inputs.
 //! - [Output] and [OutputOpenDrain] pins can be used as digital outputs.
 //! - [Flex] pin is a pin that can be used as an input and output pin.
@@ -27,7 +31,9 @@
 //!   but real pin cannot be used.
 //!
 //! ## Examples
+//!
 //! ### Set up a GPIO as an Output
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::gpio::{Io, Level, Output};
@@ -37,6 +43,7 @@
 //! ```
 //! 
 //! ### Blink an LED
+//!
 //! See the [Commonly Used Setup] section of the crate documentation.
 //!
 //! ### Inverting a signal using `AnyPin`

esp-hal/src/i2c.rs

@@ -1068,12 +1068,15 @@ pub trait Instance: crate::private::Sealed {
         self.set_filter(Some(7), Some(7));
 
         // Configure frequency
-        #[cfg(esp32)]
-        self.set_frequency(clocks.i2c_clock.convert(), frequency, timeout);
-        #[cfg(esp32s2)]
-        self.set_frequency(clocks.apb_clock.convert(), frequency, timeout);
-        #[cfg(not(any(esp32, esp32s2)))]
-        self.set_frequency(clocks.xtal_clock.convert(), frequency, timeout);
+        cfg_if::cfg_if! {
+            if #[cfg(esp32)] {
+                self.set_frequency(clocks.i2c_clock.convert(), frequency, timeout);
+            } else if #[cfg(esp32s2)] {
+                self.set_frequency(clocks.apb_clock.convert(), frequency, timeout);
+            } else {
+                self.set_frequency(clocks.xtal_clock.convert(), frequency, timeout);
+            }
+        }
 
         self.update_config();
 

esp-hal/src/interrupt/mod.rs

@@ -24,8 +24,10 @@
 //! We reserve a number of CPU interrupts, which cannot be used; see
 //! [`RESERVED_INTERRUPTS`].
 //!
-//! ## Examples
-//! ### Using the Peripheral Driver to Register an Interrupt Handler
+//! ## Example
+//!
+//! ### Using the peripheral driver to register an interrupt handler
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use core::cell::RefCell;

esp-hal/src/ledc/mod.rs

@@ -1,6 +1,7 @@
 //! # LED Controller (LEDC)
 //!
 //! ## Overview
+//!
 //! The LEDC peripheral is primarily designed to control the intensity of LEDs,
 //! although it can also be used to generate PWM signals for other purposes. It
 //! has multiple channels which can generate independent waveforms that can be
@@ -15,6 +16,7 @@
 //! supported chips.
 //!
 //! ## Examples
+//!
 //! ### Low Speed Channel
 //! The following will configure the Low Speed Channel0 to 24kHz output with
 //! 10% duty using the ABPClock

esp-hal/src/mcpwm/mod.rs

@@ -1,6 +1,7 @@
 //! # Motor Control Pulse Width Modulator (MCPWM)
 //!
 //! ## Overview
+//!
 //! The MCPWM peripheral is a versatile PWM generator, which contains various
 //! submodules to make it a key element in power electronic applications like
 //! motor control, digital power, and so on. Typically, the MCPWM peripheral can
@@ -13,6 +14,7 @@
 //! - Generate Space Vector PWM (SVPWM) signals for Field Oriented Control (FOC)
 //!
 //! ## Configuration
+//!
 //! * PWM Timers 0, 1 and 2
 //!     * Every PWM timer has a dedicated 8-bit clock prescaler.
 //!     * The 16-bit counter in the PWM timer can work in count-up mode,
@@ -201,14 +203,17 @@ impl<'a> PeripheralClockConfig<'a> {
     /// The peripheral clock frequency is calculated as:
     /// `peripheral_clock = input_clock / (prescaler + 1)`
     pub fn with_prescaler(clocks: &'a Clocks<'a>, prescaler: u8) -> Self {
-        #[cfg(esp32)]
-        let source_clock = clocks.pwm_clock;
-        #[cfg(esp32c6)]
-        let source_clock = clocks.crypto_clock;
-        #[cfg(esp32s3)]
-        let source_clock = clocks.crypto_pwm_clock;
-        #[cfg(esp32h2)]
-        let source_clock = clocks.xtal_clock;
+        cfg_if::cfg_if! {
+            if #[cfg(esp32)] {
+                let source_clock = clocks.pwm_clock;
+            } else if #[cfg(esp32c6)] {
+                let source_clock = clocks.crypto_clock;
+            } else if #[cfg(esp32s3)] {
+                let source_clock = clocks.crypto_pwm_clock;
+            } else if #[cfg(esp32h2)] {
+                let source_clock = clocks.xtal_clock;
+            }
+        }
 
         Self {
             frequency: source_clock / (prescaler as u32 + 1),
@@ -235,14 +240,17 @@ impl<'a> PeripheralClockConfig<'a> {
         clocks: &'a Clocks<'a>,
         target_freq: HertzU32,
     ) -> Result<Self, FrequencyError> {
-        #[cfg(esp32)]
-        let source_clock = clocks.pwm_clock;
-        #[cfg(esp32c6)]
-        let source_clock = clocks.crypto_clock;
-        #[cfg(esp32s3)]
-        let source_clock = clocks.crypto_pwm_clock;
-        #[cfg(esp32h2)]
-        let source_clock = clocks.xtal_clock;
+        cfg_if::cfg_if! {
+            if #[cfg(esp32)] {
+                let source_clock = clocks.pwm_clock;
+            } else if #[cfg(esp32c6)] {
+                let source_clock = clocks.crypto_clock;
+            } else if #[cfg(esp32s3)] {
+                let source_clock = clocks.crypto_pwm_clock;
+            } else if #[cfg(esp32h2)] {
+                let source_clock = clocks.xtal_clock;
+            }
+        }
 
         if target_freq.raw() == 0 || target_freq > source_clock {
             return Err(FrequencyError);

esp-hal/src/peripheral.rs

@@ -1,12 +1,14 @@
 //! # Exclusive peripheral access
 //!
 //! ## Overview
+//!
 //! The Peripheral module provides an exclusive access mechanism to peripherals
 //! on ESP chips. It includes the `PeripheralRef` struct, which represents an
 //! exclusive reference to a peripheral. It offers memory efficiency benefits
 //! for zero-sized types.
 //!
 //! ## Configuration
+//!
 //! The `PeripheralRef` struct is used to access and interact with peripherals.
 //! It implements the `Deref` and `DerefMut` traits, allowing you to dereference
 //! it to access the underlying peripheral. It also provides methods for cloning

esp-hal/src/rmt.rs

@@ -228,11 +228,13 @@ where
         PeripheralClockControl::reset(crate::system::Peripheral::Rmt);
         PeripheralClockControl::enable(crate::system::Peripheral::Rmt);
 
-        #[cfg(not(any(esp32, esp32s2)))]
-        me.configure_clock(frequency, _clocks)?;
-
-        #[cfg(any(esp32, esp32s2))]
-        self::chip_specific::configure_clock();
+        cfg_if::cfg_if! {
+            if #[cfg(any(esp32, esp32s2))] {
+                self::chip_specific::configure_clock();
+            } else {
+                me.configure_clock(frequency, _clocks)?;
+            }
+        }
 
         Ok(me)
     }

esp-hal/src/rom/md5.rs

@@ -25,7 +25,9 @@
 //! than it would be if you included an MD5 implementation in your project.
 //!
 //! ## Examples
-//! ## Compute a Full Digest From a Single Buffer
+//!
+//! ### Compute a Full Digest From a Single Buffer
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::rom::md5;
@@ -40,7 +42,8 @@
 //! writeln!(uart0, "{}", d);
 //! # }
 //! ```
-//! ## Compute a Digest Over Multiple Buffers
+//! 
+//! ### Compute a Digest Over Multiple Buffers
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::rom::md5;

esp-hal/src/rtc_cntl/mod.rs

@@ -1,13 +1,16 @@
-//! # Real-Time Clock Control and Low-power Management (RTC_CNTL)
+//! # Real-Time Control and Low-power Management (RTC_CNTL)
 //!
 //! ## Overview
-//! The RTC_CNTL peripheral is responsible for managing the real-time clock and
-//! low-power modes on the chip.
+//!
+//! The RTC_CNTL peripheral is responsible for managing the low-power modes on
+//! the chip.
 //!
 //! ## Configuration
-//!  It also includes the necessary configurations and constants for clock
+//!
+//! It also includes the necessary configurations and constants for clock
 //! sources and low-power management. The driver provides the following features
 //! and functionalities:
+//!
 //!    * Clock Configuration
 //!    * Calibration
 //!    * Low-Power Management

esp-hal/src/soc/esp32/efuse/mod.rs

@@ -1,22 +1,26 @@
 //! # Reading of eFuses (ESP32)
 //!
 //! ## Overview
+//!
 //! The `efuse` module provides functionality for reading eFuse data
 //! from the `ESP32` chip, allowing access to various chip-specific information
-//! such as :
+//! such as:
+//!
 //!   * MAC address
-//!   * core count
-//!   * CPU frequency
-//!   * chip type
+//!   * Chip type, revision
+//!   * Core count
+//!   * Max CPU frequency
 //!
 //! and more. It is useful for retrieving chip-specific configuration and
 //! identification data during runtime.
 //!
 //! The `Efuse` struct represents the eFuse peripheral and is responsible for
 //! reading various eFuse fields and values.
 //!
-//! ## Examples
+//! ## Example
+//!
 //! ### Read chip's MAC address from the eFuse storage.
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::efuse::Efuse;