Refactor esp_radio::init() (#4482)

* Refactor esp_radio::init()

* Introduce BleInitError and WifiInitError enums and call RadioRefGuard new and drop in critical section

* reviews (wifi::new returns WifiError)

* Changelog and MG

* Redo tests

* Add coex qa-test that drops ble and test if wifi still works

Author: JurajSadel

esp-radio/CHANGELOG.md

@@ -12,13 +12,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `ble::mac` to get the MAC address of the device (#4485)
 - `last_calibration_result` to get the result of the last calibration (#4479)
+- `BleInitError` for BLE init failures and `Internal`, `WrongClockConfig`, `SchedulerNotInitialized` and `Adc2IsUsed` variants to `WifiError (#4482) 
 
 ### Changed
 
 - `phy_calibration_data` and `set_phy_calibration_data` are now marked as `unstable`. (#4463)
 - The `InitializationError::General` is replaced by `InitializationError::Internal` (#4467)
 - The `WifiError::InternalError` is removed and `InternalWifiError` was folded into `WifiError`, some variants renamed for clarity (#4467)
 - Refactor: extract submodules from `esp_radio::wifi` module (#4460)
+- `BleConnector::new` returns `BleInitError` instead of `InvalidConfigError` (#4482)
+- `esp_radio::init()` is not public anymore (#4482)
+- `esp_radio::wifi::new` and `BleConnector::new` no longer take a `Controller` (#4482)
 
 ### Fixed
 
@@ -29,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 
 - The `serde` feature has been removed (#4435)
+- `Controller` struct and `InitializationError::InterruptsDisabled` enum variant have been removed (#4482)
 
 ## [v0.17.0] - 2025-10-30
 

esp-radio/Cargo.toml

@@ -44,6 +44,7 @@ cfg-if  = "1"
 esp-hal = { version = "1.0.0", path = "../esp-hal", default-features = false, features = ["requires-unstable"] }
 portable-atomic = { version = "1.11", default-features = false }
 enumset = { version = "1.1", default-features = false, optional = true }
+critical-section         = { version = "1", default-features = false, optional = true }
 
 # ⚠️ Unstable dependencies
 esp-radio-rtos-driver = { version = "0.2.0", path = "../esp-radio-rtos-driver" }
@@ -137,6 +138,7 @@ esp32 = [
   "dep:esp-wifi-sys-esp32",
   "esp-metadata-generated/esp32",
   "xtensa-lx-rt/float-save-restore",
+  "critical-section",
 ]
 ##
 esp32c2 = [
@@ -145,6 +147,7 @@ esp32c2 = [
   "esp-phy/esp32c2",
   "dep:esp-wifi-sys-esp32c2",
   "esp-metadata-generated/esp32c2",
+  "critical-section",
 ]
 ##
 esp32c3 = [
@@ -153,6 +156,7 @@ esp32c3 = [
   "esp-phy/esp32c3",
   "dep:esp-wifi-sys-esp32c3",
   "esp-metadata-generated/esp32c3",
+  "critical-section",
 ]
 ##
 esp32c6 = [
@@ -161,6 +165,7 @@ esp32c6 = [
   "esp-phy/esp32c6",
   "dep:esp-wifi-sys-esp32c6",
   "esp-metadata-generated/esp32c6",
+  "critical-section",
 ]
 ##
 esp32h2 = [
@@ -169,6 +174,7 @@ esp32h2 = [
   "esp-phy/esp32h2",
   "dep:esp-wifi-sys-esp32h2",
   "esp-metadata-generated/esp32h2",
+  "critical-section",
 ]
 ##
 esp32s2 = [
@@ -178,6 +184,7 @@ esp32s2 = [
   "dep:esp-wifi-sys-esp32s2",
   "esp-metadata-generated/esp32s2",
   "xtensa-lx-rt/float-save-restore",
+  "critical-section",
 ]
 ##
 esp32s3 = [
@@ -187,6 +194,7 @@ esp32s3 = [
   "dep:esp-wifi-sys-esp32s3",
   "esp-metadata-generated/esp32s3",
   "xtensa-lx-rt/float-save-restore",
+  "critical-section",
 ]
 
 #! ### Wireless Feature Flags

esp-radio/MIGRATING-0.17.0.md

@@ -36,3 +36,21 @@ impl From<ScanMethod> for esp_radio::wifi::ScanMethod {
 - `EapFastConfig`, `TlsPhase2Method` and `EapClientConfig` are now located in `wifi::ap::eap`.
 
 You will need to update any imports in your project accordingly.
+
+## `esp_radio::init()` and `Controller` is no longer available
+
+WiFi initialization:
+```diff
+-    let esp_radio_ctrl = esp_radio::init().unwrap();
+-    let (mut controller, interfaces) =
+-        esp_radio::wifi::new(&esp_radio_ctrl, wifi, Default::default()).unwrap();
++    let (mut controller, interfaces) = esp_radio::wifi::new(wifi, Default::default()).unwrap();
+```
+
+BLE initialization:
+```diff
+-    static RADIO: StaticCell<esp_radio::Controller<'static>> = StaticCell::new();
+-    let radio = RADIO.init(esp_radio::init().unwrap());
+-    let connector = BleConnector::new(radio, bluetooth, Default::default()).unwrap();
++    let connector = BleConnector::new(bluetooth, Default::default()).unwrap();
+```

esp-radio/src/ble/controller/mod.rs

@@ -12,16 +12,37 @@ use esp_hal::asynch::AtomicWaker;
 use esp_phy::PhyInitGuard;
 
 use crate::{
-    Controller,
+    InitializationError,
+    RadioRefGuard,
     ble::{Config, InvalidConfigError, have_hci_read_data, read_hci, read_next, send_hci},
 };
 
+#[derive(Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Error enum for BLE initialization failures.
+pub enum BleInitError {
+    /// Failure during initial validation of the provided configuration.
+    Config(InvalidConfigError),
+
+    /// Failure during the acquisition or initialization of the global radio hardware.
+    RadioInit(InitializationError),
+}
+
+// Implement the From trait for cleaner error mapping
+impl From<InvalidConfigError> for BleInitError {
+    fn from(err: InvalidConfigError) -> Self {
+        BleInitError::Config(err)
+    }
+}
+
 /// A blocking HCI connector
 #[instability::unstable]
 pub struct BleConnector<'d> {
     _phy_init_guard: PhyInitGuard<'d>,
     _device: crate::hal::peripherals::BT<'d>,
+    _guard: RadioRefGuard,
 }
+
 impl Drop for BleConnector<'_> {
     fn drop(&mut self) {
         crate::ble::ble_deinit();
@@ -31,14 +52,17 @@ impl<'d> BleConnector<'d> {
     /// Create and init a new BLE connector.
     #[instability::unstable]
     pub fn new(
-        _init: &'d Controller<'d>,
         device: crate::hal::peripherals::BT<'d>,
         config: Config,
-    ) -> Result<BleConnector<'d>, InvalidConfigError> {
+    ) -> Result<BleConnector<'d>, BleInitError> {
+        let _guard = RadioRefGuard::new().map_err(BleInitError::RadioInit)?;
+
         config.validate()?;
+
         Ok(Self {
             _phy_init_guard: crate::ble::ble_init(&config),
             _device: device,
+            _guard,
         })
     }
 

esp-radio/src/lib.rs

@@ -136,8 +136,6 @@ extern crate alloc;
 // MUST be the first module
 mod fmt;
 
-use core::marker::PhantomData;
-
 use esp_hal::{
     self as hal,
 
@@ -226,6 +224,9 @@ pub(crate) mod memory_fence;
 
 pub(crate) static ESP_RADIO_LOCK: RawMutex = RawMutex::new();
 
+static RADIO_REFCOUNT: critical_section::Mutex<core::cell::Cell<u32>> =
+    critical_section::Mutex::new(core::cell::Cell::new(0));
+
 // this is just to verify that we use the correct defaults in `build.rs`
 #[allow(clippy::assertions_on_constants)] // TODO: try assert_eq once it's usable in const context
 const _: () = {
@@ -243,30 +244,6 @@ const _: () = {
     };
 };
 
-#[derive(Debug, PartialEq, PartialOrd)]
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-/// Controller for the ESP Radio driver.
-pub struct Controller<'d> {
-    _inner: PhantomData<&'d ()>,
-}
-
-impl Drop for Controller<'_> {
-    fn drop(&mut self) {
-        // Disable coexistence
-        #[cfg(coex)]
-        {
-            unsafe { crate::wifi::os_adapter::coex_disable() };
-            unsafe { crate::wifi::os_adapter::coex_deinit() };
-        }
-
-        shutdown_radio_isr();
-
-        #[cfg(esp32)]
-        // Allow using `ADC2` again
-        release_adc2(unsafe { esp_hal::Internal::conjure() });
-    }
-}
-
 #[procmacros::doc_replace]
 /// Initialize for using Wi-Fi and or BLE.
 ///
@@ -289,35 +266,12 @@ impl Drop for Controller<'_> {
 )]
 /// - The function may return an error if interrupts are disabled.
 /// - The function may return an error if initializing the underlying driver fails.
-///
-/// ## Example
-///
-/// For examples of the necessary setup, see your RTOS's documentation. If you are
-/// using the `esp-rtos` crate, you will need to initialize the scheduler before calling this
-/// function:
-///
-/// ```rust, no_run
-/// # {before_snippet}
-/// use esp_hal::{interrupt::software::SoftwareInterruptControl, timer::timg::TimerGroup};
-///
-/// let timg0 = TimerGroup::new(peripherals.TIMG0);
-/// let software_interrupt = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
-/// esp_rtos::start(timg0.timer0, software_interrupt.software_interrupt0);
-///
-/// // You can now start esp-radio:
-/// let esp_radio_controller = esp_radio::init().unwrap();
-/// # {after_snippet}
-/// ```
-pub fn init<'d>() -> Result<Controller<'d>, InitializationError> {
+pub(crate) fn init() -> Result<(), InitializationError> {
     #[cfg(esp32)]
     if try_claim_adc2(unsafe { hal::Internal::conjure() }).is_err() {
         return Err(InitializationError::Adc2IsUsed);
     }
 
-    if crate::is_interrupts_disabled() {
-        return Err(InitializationError::InterruptsDisabled);
-    }
-
     if !preempt::initialized() {
         return Err(InitializationError::SchedulerNotInitialized);
     }
@@ -339,12 +293,75 @@ pub fn init<'d>() -> Result<Controller<'d>, InitializationError> {
     #[cfg(coex)]
     match crate::wifi::coex_initialize() {
         0 => {}
-        error => return Err(InitializationError::Internal),
+        error => panic!("Failed to initialize coexistence, error code: {}", error),
+    }
+
+    debug!("Radio initialized");
+
+    Ok(())
+}
+
+pub(crate) fn deinit() {
+    // Disable coexistence
+    #[cfg(coex)]
+    {
+        unsafe { crate::wifi::os_adapter::coex_disable() };
+        unsafe { crate::wifi::os_adapter::coex_deinit() };
     }
 
-    Ok(Controller {
-        _inner: PhantomData,
-    })
+    shutdown_radio_isr();
+
+    #[cfg(esp32)]
+    // Allow using `ADC2` again
+    release_adc2(unsafe { esp_hal::Internal::conjure() });
+
+    debug!("Radio deinitialized");
+}
+
+/// Management of the global reference count
+/// and conditional hardware initialization/deinitialization.
+#[derive(Debug)]
+pub(crate) struct RadioRefGuard;
+
+impl RadioRefGuard {
+    /// Increments the refcount. If the old count was 0, it performs hardware init.
+    /// If hardware init fails, it rolls back the refcount only once.
+    fn new() -> Result<Self, InitializationError> {
+        critical_section::with(|cs| {
+            debug!("Creating RadioRefGuard");
+            let rc = RADIO_REFCOUNT.borrow(cs);
+
+            let prev = rc.get();
+            rc.set(prev + 1);
+
+            if prev == 0
+                && let Err(e) = init()
+            {
+                rc.set(prev);
+                return Err(e);
+            }
+
+            Ok(RadioRefGuard)
+        })
+    }
+}
+
+impl Drop for RadioRefGuard {
+    /// Decrements the refcount. If the count drops to 0, it performs hardware de-init.
+    fn drop(&mut self) {
+        critical_section::with(|cs| {
+            debug!("Dropping RadioRefGuard");
+            let rc = RADIO_REFCOUNT.borrow(cs);
+
+            let prev = rc.get();
+            rc.set(prev - 1);
+
+            if prev == 1 {
+                // Last user dropped, run de-initialization
+                deinit();
+            }
+        });
+    }
 }
 
 /// Returns true if at least some interrupt levels are disabled.
@@ -360,19 +377,14 @@ fn is_interrupts_disabled() -> bool {
 
 #[derive(Debug, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-/// Error which can be returned during [`init`].
+/// Error which can be returned during radio initialization.
 #[non_exhaustive]
 pub enum InitializationError {
-    /// An internal error occurred.
-    Internal,
     /// An error from the Wi-Fi driver.
     #[cfg(feature = "wifi")]
     WifiError(WifiError),
     /// The current CPU clock frequency is too low.
     WrongClockConfig,
-    /// Tried to initialize while interrupts are disabled.
-    /// This is not supported.
-    InterruptsDisabled,
     /// The scheduler is not initialized.
     SchedulerNotInitialized,
     #[cfg(esp32)]
@@ -385,18 +397,13 @@ impl core::error::Error for InitializationError {}
 impl core::fmt::Display for InitializationError {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            InitializationError::Internal => write!(f, "An internal error occurred"),
             #[cfg(feature = "wifi")]
             InitializationError::WifiError(e) => {
                 write!(f, "Wi-Fi driver related error occurred: {e}")
             }
             InitializationError::WrongClockConfig => {
                 write!(f, "The current CPU clock frequency is too low")
             }
-            InitializationError::InterruptsDisabled => write!(
-                f,
-                "Attempted to initialize while interrupts are disabled (Unsupported)"
-            ),
             InitializationError::SchedulerNotInitialized => {
                 write!(f, "The scheduler is not initialized")
             }