Prefer cfg_if (#2003)

Author: bugadani

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 `embedded-hal@0.2.x` 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