esp_radio/

lib.rs

#![cfg_attr(
    all(docsrs, not(not_really_docsrs)),
    doc = "<div style='padding:30px;background:#810;color:#fff;text-align:center;'><p>You might want to <a href='https://docs.espressif.com/projects/rust/'>browse the <code>esp-radio</code> documentation on the esp-rs website</a> instead.</p><p>The documentation here on <a href='https://docs.rs'>docs.rs</a> is built for a single chip only (ESP32-C3, in particular), while on the esp-rs website you can select your exact chip from the list of supported devices. Available peripherals and their APIs might change depending on the chip.</p></div>\n\n<br/>\n\n"
)]
//! # Wireless support for Espressif ESP32 devices.
//!
//! This documentation is built for the
#![doc = concat!("**", chip_pretty!(), "**")]
//! . Please ensure you are reading the correct [documentation] for your target
//! device.
//!
//! ## Overview
//!
//! esp-radio provides Wi-Fi, Bluetooth Low Energy (BLE), ESP-NOW and IEEE
//! 802.15.4 drivers for Espressif microcontrollers. It builds on top of
//! [esp-hal] and the vendor binary blobs to provide wireless connectivity in a
//! `no_std` environment.
//!
//! Wi-Fi and BLE require a dynamic memory allocator and a preemptive task
//! scheduler at runtime. We recommend [`esp-alloc`] and [`esp-rtos`] for this,
//! though any allocator or RTOS (such as Ariel OS) that implements the required
//! interfaces will work.
#![cfg_attr(
    feature = "ieee802154",
    doc = "<div class=\"warning\"><b>Hint:</b> The scheduler is not required for IEEE 802.15.4.</div>"
)]
//! Drivers that don't currently have a stable API are marked as `unstable` in
//! the documentation. Enabling the `unstable` feature on `esp-radio` requires
//! you to also enable the `unstable` feature on `esp-hal` in the final binary
//! crate.
//!
//! ### Quick start
//!
//! ```rust, no_run
#![doc = esp_hal::before_snippet!()]
//! use esp_hal::interrupt::software::SoftwareInterrupt;
//! use esp_hal::ram;
//! use esp_hal::timer::timg::TimerGroup;
//!
//! esp_alloc::heap_allocator!(#[ram(reclaimed)] size: 64 * 1024);
//! esp_alloc::heap_allocator!(size: 36 * 1024);
//!
//! let timg0 = TimerGroup::new(peripherals.TIMG0);
//!
//! // THIS IS IMPORTANT FOR WIFI AND BLE: You MUST start the scheduler
//! // before initializing the radio!
//! esp_rtos::start(timg0.timer0);
#![cfg_attr(
    wifi_driver_supported,
    doc = r#"

if let Ok(controller) = esp_radio::wifi::WifiController::new(
    peripherals.WIFI,
    Default::default(),
) {}
"#
)]
#![cfg_attr(
    all(bt_driver_supported, not(wifi_driver_supported)),
    doc = r#"

# use esp_radio::ble::controller::BleConnector;
if let Ok(controller) = BleConnector::new(peripherals.BT, Default::default()) {}
"#
)]
#![doc = esp_hal::after_snippet!()]
//! ```
//! ```toml
//! [dependencies.esp-radio]
//! # A supported chip needs to be specified, as well as specific use-case features
#![doc = concat!(r#"features = [""#, chip!(), r#"", "wifi", "esp-now", "esp-alloc"]"#)]
//! [dependencies.esp-rtos]
#![doc = concat!(r#"features = [""#, chip!(), r#"", "esp-radio", "esp-alloc"]"#)]
//! [dependencies.esp-alloc]
#![doc = concat!(r#"features = [""#, chip!(), r#""]"#)]
//! ```
//! 
//! ## Examples
//!
//! We have a number of [examples] in the esp-hal repository. We use
//! an [xtask] to automate the building, running, and testing of code and
//! examples within esp-hal.
//!
//! Invoke the following command in the root of the esp-hal repository to get
//! started:
//! ```bash
//! cargo xtask help
//! ```
//! 
//! We have a [book] that explains the full esp-hal ecosystem
//! and how to get started, and a [training] that covers some common
//! scenarios with examples.
//!
//! ## Optimization level
//!
//! The radio blobs require optimization level 2 or 3 to function correctly.
//! Without it, Wi-Fi may fail to connect and BLE may fail to advertise.
//!
//! To apply this only to esp-radio in debug builds, add to your `Cargo.toml`:
//! ```toml
//! [profile.dev.package.esp-radio]
//! opt-level = 3
//! ```
//! 
//! ## Disabling logging
//!
//! `esp-radio` contains trace-level logging statements that may impact
//! performance. To disable them, use the `log` crate's compile-time
//! [filters](https://docs.rs/log/latest/log/#compile-time-filters) and set
//! `release_max_level_off`.
//!
//! [documentation]: https://docs.espressif.com/projects/rust/esp-radio/latest/
//! [esp-hal]: https://docs.espressif.com/projects/rust/esp-hal/latest/
//! [`esp-alloc`]: https://docs.espressif.com/projects/rust/esp-alloc/latest/
//! [`esp-rtos`]: https://docs.espressif.com/projects/rust/esp-rtos/latest/
//! [examples]: https://github.com/esp-rs/esp-hal/tree/main/examples
//! [xtask]: https://github.com/matklad/cargo-xtask
//! [book]: https://docs.espressif.com/projects/rust/book/
//! [training]: https://docs.espressif.com/projects/rust/no_std-training/
#![cfg_attr(
    multi_core,
    doc = concat!(
        "## Running on the second core",
        "\n\n",
        "BLE and Wi-Fi can also be run on the second core.",
        "\n\n",
        "`esp_radio::init` is recommended to be called on the first core. The tasks ",
        "created by `esp-radio` are pinned to the first core.",
        "\n\n",
        "It's also important to allocate adequate stack for the second core; in many ",
        "cases 8kB is not enough, and 16kB or more may be required depending on your ",
        "use case. Failing to allocate adequate stack may result in strange behaviour, ",
        "such as your application silently failing at some point during execution."
    )
)]
//! ## Feature flags
//!
//! Note that not all features are available on every MCU. For example, `ble`
//! (and thus, `coex`) is not available on ESP32-S2.
//!
//! When using the `dump_packets` config you can use the extcap in
//! `extras/esp-wifishark` to analyze the frames in Wireshark.
//! For more information see
//! [extras/esp-wifishark/README.md](../extras/esp-wifishark/README.md)
#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
//! ## Additional configuration
//!
//! We've exposed some configuration options that don't fit into cargo
//! features. These can be set via environment variables, or via cargo's `[env]`
//! section inside `.cargo/config.toml`. Below is a table of tunable parameters
//! for this crate:
#![doc = ""]
#![doc = include_str!(concat!(env!("OUT_DIR"), "/esp_radio_config_table.md"))]
#![doc(html_logo_url = "https://docs.espressif.com/projects/rust/esp-rs-grey-bg.svg")]
#![no_std]
#![deny(missing_docs, rust_2018_idioms, rustdoc::all)]
#![cfg_attr(
    not(any(feature = "wifi", feature = "ble")),
    allow(
        unused,
        reason = "There are a number of places where code is needed for either wifi or ble,
        and cfg-ing them out would make the code less readable just to avoid warnings in the
        less common case. Truly unused code will be flagged by the check that enables either
        ble or wifi."
    )
)]
#![cfg_attr(docsrs, feature(doc_cfg, custom_inner_attributes, proc_macro_hygiene))]

#[macro_use]
extern crate esp_metadata_generated;

extern crate alloc;

// These modules rely on `#[macro_use]` so they must be the first ones declared
mod coex_utils;
mod fmt;
pub(crate) mod reg_access;

use core::marker::PhantomData;

use esp_hal as hal;
#[instability::unstable]
pub use esp_phy::CalibrationResult;
use esp_radio_rtos_driver as preempt;
#[cfg(feature = "wifi")]
use hal::{after_snippet, before_snippet};
use sys::include::esp_phy_calibration_data_t;
pub(crate) mod sys {
    #[cfg(esp32)]
    pub use esp_wifi_sys_esp32::*;
    #[cfg(esp32c2)]
    pub use esp_wifi_sys_esp32c2::*;
    #[cfg(esp32c3)]
    pub use esp_wifi_sys_esp32c3::*;
    #[cfg(esp32c5)]
    pub use esp_wifi_sys_esp32c5::*;
    #[cfg(esp32c6)]
    pub use esp_wifi_sys_esp32c6::*;
    #[cfg(esp32c61)]
    pub use esp_wifi_sys_esp32c61::*;
    #[cfg(esp32h2)]
    pub use esp_wifi_sys_esp32h2::*;
    #[cfg(esp32s2)]
    pub use esp_wifi_sys_esp32s2::*;
    #[cfg(esp32s3)]
    pub use esp_wifi_sys_esp32s3::*;
    #[cfg(esp32s31)]
    pub use esp_wifi_sys_esp32s31::*;
}

use crate::refcount::Refcount;
#[cfg(feature = "wifi")]
use crate::wifi::WifiError;

// can't use instability on inline module definitions, see https://github.com/rust-lang/rust/issues/54727
#[doc(hidden)]
macro_rules! unstable_module {
    ($(
        $(#[$meta:meta])*
        pub mod $module:ident;
    )*) => {
        $(
            $(#[$meta])*
            #[cfg(feature = "unstable")]
            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
            pub mod $module;

            $(#[$meta])*
            #[cfg(not(feature = "unstable"))]
            #[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
            #[allow(unused)]
            pub(crate) mod $module;
        )*
    };
}

mod asynch;
mod compat;
#[cfg(esp32s31)]
mod compiler_rt_abi;
mod interrupt_dispatch;
mod radio_clocks;
mod refcount;
mod time;

#[cfg(feature = "wifi")]
pub mod wifi;

unstable_module! {
    #[cfg(feature = "esp-now")]
    #[cfg_attr(docsrs, doc(cfg(feature = "esp-now")))]
    pub mod esp_now;
    #[cfg(feature = "ble")]
    #[cfg_attr(docsrs, doc(cfg(feature = "ble")))]
    pub mod ble;
    #[cfg(feature = "ieee802154")]
    #[cfg_attr(docsrs, doc(cfg(feature = "ieee802154")))]
    pub mod ieee802154;
}

pub(crate) mod common_adapter;

#[cfg(all(feature = "ble", bt_controller = "npl"))]
pub(crate) static ESP_RADIO_LOCK: esp_sync::RawMutex = esp_sync::RawMutex::new();

// 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 _: () = {
    #[cfg(wifi_driver_supported)]
    {
        core::assert!(sys::include::CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM == 10);
        core::assert!(sys::include::CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM == 32);
        core::assert!(sys::include::WIFI_STATIC_TX_BUFFER_NUM == 0);
        core::assert!(sys::include::CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM == 32);
        core::assert!(sys::include::CONFIG_ESP_WIFI_AMPDU_RX_ENABLED == 1);
        core::assert!(sys::include::CONFIG_ESP_WIFI_AMPDU_TX_ENABLED == 1);
        core::assert!(sys::include::WIFI_AMSDU_TX_ENABLED == 0);
        core::assert!(sys::include::CONFIG_ESP32_WIFI_RX_BA_WIN == 6);
    };
};

#[procmacros::doc_replace]
/// Initialize for using Wi-Fi and or BLE.
///
/// Wi-Fi and BLE require a preemptive scheduler to be present. Without one, the underlying firmware
/// can't operate. The scheduler must implement the interfaces in the `esp-radio-rtos-driver`
/// crate. If you are using an embedded RTOS like Ariel OS, it needs to provide an appropriate
/// implementation.
///
/// If you are not using an embedded RTOS, use the `esp-rtos` crate which provides the
/// necessary functionality.
///
/// Make sure to **not** call this function while interrupts are disabled.
///
/// ## Errors
///
/// - The function may return an error if the scheduler is not initialized.
#[cfg_attr(
    esp32,
    doc = " - The function may return an error if ADC2 is already in use."
)]
/// - The function may return an error if interrupts are disabled.
/// - The function may return an error if initializing the underlying driver fails.
pub(crate) fn init() {
    esp_hal::if_unstable_hal! {
        #[cfg(esp32)]
        if hal::analog::adc::try_claim_adc2(unsafe { hal::Internal::conjure() }).is_err() {
            panic!(
                "ADC2 is currently in use by esp-hal, but esp-radio requires it for Wi-Fi operation."
            );
        }
        esp_hal::rtc_cntl::WakeLock::acquire();
    }

    if !preempt::initialized() {
        panic!("The scheduler must be initialized before initializing the radio.");
    }

    // A minimum clock of 80MHz is required to operate Wi-Fi module.
    const MIN_CLOCK: u32 = 80;
    let cpu_clock = esp_hal::clock::cpu_clock().as_mhz();
    if cpu_clock < MIN_CLOCK {
        panic!(
            "CPU clock {} MHz is too slow for Wi-Fi operation, minimum required is {} MHz",
            cpu_clock, MIN_CLOCK
        );
    }

    // Ungate the modem clocks first: `enable_wifi_power_domain` pulses the
    // modem reset, which is ineffective while the clocks are gated — and
    // esp-phy's clock guard has gated them again by the time we re-init.
    // (ESP-IDF never gates these clocks, so its power-up reset always lands.)
    radio_clocks::init_radio_clocks();

    crate::common_adapter::enable_wifi_power_domain();

    wifi_set_log_verbose();

    #[cfg(feature = "coex")]
    match crate::wifi::coex_initialize() {
        0 => {}
        error => panic!("Failed to initialize coexistence, error code: {}", error),
    }

    debug!("Radio initialized");
}

pub(crate) fn deinit() {
    // Disable coexistence
    #[cfg(feature = "coex")]
    {
        unsafe { crate::wifi::os_adapter::coex_disable() };
        unsafe { crate::wifi::os_adapter::coex_deinit() };
    }

    #[cfg(feature = "wifi")]
    wifi::shutdown_wifi_isr();
    #[cfg(feature = "ble")]
    ble::shutdown_ble_isr();

    // Gate the BT clocks (the Wi-Fi driver gates its own clocks during
    // `wifi_deinit`), power down the modem power domain, and gate the
    // remaining modem clocks, mirroring ESP-IDF's fixed-mask clock control
    // (`periph_ll_wifi_module_disable_clk_set_rst` and friends). This must
    // only run once all radios are off: PHY teardown still needs the modem
    // clocks.
    #[cfg(feature = "ble")]
    crate::radio_clocks::clocks_ll::enable_bt(false);
    crate::common_adapter::disable_wifi_power_domain();
    crate::radio_clocks::deinit_radio_clocks();

    // After the modem power domain has been powered down, the PHY driver's
    // internal init flag must be reset, otherwise the next `phy_wakeup_init`
    // assumes retained PHY registers that the power-down wiped (mirrors
    // ESP-IDF's `esp_phy_modem_deinit`, "Fix the issue caused by the power
    // domain off. This issue is only on ESP32C3.").
    #[cfg(esp32c3)]
    unsafe {
        crate::sys::include::phy_init_flag()
    };

    esp_hal::if_unstable_hal! {
        // Allow using `ADC2` again
        #[cfg(esp32)]
        hal::analog::adc::release_adc2(unsafe { esp_hal::Internal::conjure() });

        esp_hal::rtc_cntl::WakeLock::release();
    }

    debug!("Radio deinitialized");
}

/// Management of the global reference count
/// and conditional hardware initialization/deinitialization.
#[derive(Debug)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub(crate) struct RadioRefGuard {
    _private: PhantomData<()>,
}

static RADIO_REFCOUNT: Refcount = Refcount::new();

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.
    pub(crate) fn new() -> Self {
        debug!("Creating RadioRefGuard");

        RADIO_REFCOUNT.increment(init);
        RadioRefGuard {
            _private: PhantomData,
        }
    }
}

impl Drop for RadioRefGuard {
    /// Decrements the refcount. If the count drops to 0, it performs hardware de-init.
    fn drop(&mut self) {
        debug!("Dropping RadioRefGuard");

        RADIO_REFCOUNT.decrement(deinit);
    }
}

/// Enable verbose logging within the Wi-Fi driver
/// Does nothing unless the `print-logs-from-driver` feature is enabled.
#[instability::unstable]
pub fn wifi_set_log_verbose() {
    #[cfg(all(feature = "print-logs-from-driver", not(esp32h2)))]
    unsafe {
        use crate::sys::include::{
            esp_wifi_internal_set_log_level,
            wifi_log_level_t_WIFI_LOG_VERBOSE,
        };

        esp_wifi_internal_set_log_level(wifi_log_level_t_WIFI_LOG_VERBOSE);
    }
}

/// Get calibration data.
///
/// Returns the last calibration result.
///
/// If [last_calibration_result] returns [CalibrationResult::DataCheckFailed], consider persisting
/// the new data.
#[instability::unstable]
pub fn phy_calibration_data(data: &mut [u8; esp_phy::PHY_CALIBRATION_DATA_LENGTH]) {
    let _ = esp_phy::backup_phy_calibration_data(data);
}

/// Set calibration data.
///
/// This will be used next time the phy gets initialized.
#[instability::unstable]
pub fn set_phy_calibration_data(data: &[u8; core::mem::size_of::<esp_phy_calibration_data_t>()]) {
    // Although we're ignoring the result here, this doesn't change the behavior, as this just
    // doesn't do anything in case an error is returned.
    let _ = esp_phy::set_phy_calibration_data(data);
}

/// Get the last calibration result.
///
/// This can be used to know if any previously persisted calibration data is outdated/invalid and
/// needs to get updated.
#[instability::unstable]
pub fn last_calibration_result() -> Option<CalibrationResult> {
    esp_phy::last_calibration_result()
}