esp_phy/

lib.rs

//! PHY initialization handling for chips with a radio.
//!
//! This should be considered an implementation detail of `esp-radio` and similar 3rd party crates.
//!
//! # Usage
//! ## Enabling and Disabling the PHY
//! Use [enable_phy] to enable the PHY. Drop the returned [PhyInitGuard] to disable the PHY.
//! Enabling / disabling the PHY is ref-counted so these actions need to be balanced.
//!
//! ## Backing Up and Restoring PHY Calibration Data
//! If the PHY has already been calibrated, you can use [backup_phy_calibration_data] to persist
//! calibration data elsewhere (e.g. in flash). Using [set_phy_calibration_data] you can restore
//! previously persisted calibration data.
//! ## Config Options
#![doc = include_str!(concat!(env!("OUT_DIR"), "/esp_phy_config_table.md"))]
//! ## Feature Flags
#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
#![no_std]
#![deny(missing_docs)]

// MUST be the first module
mod fmt;
pub(crate) mod reg_access;

use core::{cell::Cell, marker::PhantomData};

use esp_hal::system::Cpu;
#[cfg(esp32)]
use esp_hal::time::{Duration, Instant};
use esp_sync::{NonReentrantMutex, RawMutex};

/// Tracks the number of references to the PHY clock.
static PHY_CLOCK_REF_COUNTER: embassy_sync::blocking_mutex::Mutex<RawMutex, Cell<u8>> =
    embassy_sync::blocking_mutex::Mutex::new(Cell::new(0));

fn increase_phy_clock_ref_count_internal() {
    PHY_CLOCK_REF_COUNTER.lock(|phy_clock_ref_counter| {
        let phy_clock_ref_count = phy_clock_ref_counter.get();

        if phy_clock_ref_count == 0 {
            phy_clocks::enable_phy(true);
        }
        let new_phy_clock_ref_count = unwrap!(
            phy_clock_ref_count.checked_add(1),
            "PHY clock ref count overflowed."
        );

        phy_clock_ref_counter.set(new_phy_clock_ref_count);
    })
}

fn decrease_phy_clock_ref_count_internal() {
    PHY_CLOCK_REF_COUNTER.lock(|phy_clock_ref_counter| {
        let new_phy_clock_ref_count = unwrap!(
            phy_clock_ref_counter.get().checked_sub(1),
            "PHY clock ref count underflowed. Either you forgot a PhyClockGuard, or used PhyController::decrease_phy_clock_ref_count incorrectly."
        );

        if new_phy_clock_ref_count == 0 {
            phy_clocks::enable_phy(false);
        }

        phy_clock_ref_counter.set(new_phy_clock_ref_count);
    })
}

#[derive(Debug)]
/// Prevents the PHY clock from being disabled.
///
/// As long as at least one [PhyClockGuard] exists, the PHY clock will remain
/// active. To release this guard, you can either let it go out of scope or use
/// [PhyClockGuard::release] to explicitly release it.
pub struct PhyClockGuard<'d> {
    _phantom: PhantomData<&'d ()>,
}

impl PhyClockGuard<'_> {
    #[inline]
    /// Release the clock guard.
    ///
    /// The PHY clock will be disabled, if this is the last clock guard.
    pub fn release(self) {
        // Runs the Drop implementation
    }
}

impl Drop for PhyClockGuard<'_> {
    fn drop(&mut self) {
        decrease_phy_clock_ref_count_internal();
    }
}
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::*;
}

mod common_adapter;
mod phy_clocks;
mod phy_init_data;

/// Length of the PHY calibration data.
pub const PHY_CALIBRATION_DATA_LENGTH: usize =
    core::mem::size_of::<sys::include::esp_phy_calibration_data_t>();

/// Type alias for opaque calibration data.
pub type PhyCalibrationData = [u8; PHY_CALIBRATION_DATA_LENGTH];

#[cfg(phy_backed_up_digital_register_count_is_set)]
type PhyDigRegsBackup =
    [u32; esp_metadata_generated::property!("phy.backed_up_digital_register_count")];

#[cfg(esp32)]
/// Callback to update the MAC time.
///
/// The duration is the delta, that has been accumulated between the PHY clock and the normal
/// system timers, since the last time this callback was called. This accounts for the PHY being
/// enabled and disabled, before this callback was set.
pub type MacTimeUpdateCb = fn(Duration);

static ESP_PHY_LOCK: RawMutex = RawMutex::new();

/// PHY initialization state
struct PhyState {
    /// Number of references to the PHY.
    ref_count: usize,
    /// The calibration data used for initialization.
    ///
    /// If this is [None], when `PhyController::enable_phy` is called, it will be initialized to
    /// zero and a full calibration is performed.
    calibration_data: Option<PhyCalibrationData>,
    /// Has the PHY been calibrated since the chip was powered up.
    calibrated: bool,
    /// Last calibration result code.
    calibration_result: i32,

    #[cfg(phy_backed_up_digital_register_count_is_set)]
    /// Backup of the digital PHY registers.
    phy_digital_register_backup: Option<PhyDigRegsBackup>,

    // Chip specific.
    #[cfg(esp32)]
    /// Timestamp at which the modem clock domain state transitioned.
    phy_clock_state_transition_timestamp: Instant,
    #[cfg(esp32)]
    /// The accumulated delta since the last time the callback was called.
    mac_clock_delta_since_last_call: Duration,
    #[cfg(esp32)]
    /// Callback to update the MAC time.
    mac_time_update_cb: Option<MacTimeUpdateCb>,
}

impl PhyState {
    /// Initialize the PHY state.
    pub const fn new() -> Self {
        Self {
            ref_count: 0,
            calibration_data: None,
            calibrated: false,
            calibration_result: 0,

            #[cfg(phy_backed_up_digital_register_count_is_set)]
            phy_digital_register_backup: None,

            #[cfg(esp32)]
            phy_clock_state_transition_timestamp: Instant::EPOCH,
            #[cfg(esp32)]
            mac_clock_delta_since_last_call: Duration::ZERO,
            #[cfg(esp32)]
            mac_time_update_cb: None,
        }
    }

    /// Get a reference to the calibration data.
    ///
    /// If no calibration data is available, it will be initialized to zero.
    pub fn calibration_data(&mut self) -> &mut PhyCalibrationData {
        self.calibration_data
            .get_or_insert([0u8; PHY_CALIBRATION_DATA_LENGTH])
    }

    /// Calibrate the PHY.
    fn calibrate(&mut self) {
        #[cfg(esp32s2)]
        unsafe {
            sys::include::phy_eco_version_sel(esp_hal::efuse::chip_revision().major);
        }
        // Causes headaches for some reason.
        // See: https://github.com/esp-rs/esp-hal/issues/4015
        // #[cfg(phy_combo_module)]
        // unsafe {
        // phy_init_param_set(1);
        // }

        #[cfg(all(
            phy_enable_usb,
            any(soc_has_usb0, soc_has_usb_device),
            not(any(esp32s2, esp32h2))
        ))]
        unsafe {
            // FIXME: we should be using from esp-wifi-sys, but the function is missing for C6
            // (CONFIG_ESP_PHY_ENABLE_USB is not defined)
            unsafe extern "C" {
                fn phy_bbpll_en_usb(param: bool);
            }
            phy_bbpll_en_usb(true);
        }

        let calibration_data_available = self.calibration_data.is_some();
        let calibration_mode = if calibration_data_available {
            // If the SOC just woke up from deep sleep and
            // `phy_skip_calibration_after_deep_sleep` is enabled, no calibration will be
            // performed.
            if cfg!(phy_skip_calibration_after_deep_sleep) && is_reset_from_deepsleep() {
                sys::include::esp_phy_calibration_mode_t_PHY_RF_CAL_NONE
            } else if cfg!(phy_full_calibration) {
                sys::include::esp_phy_calibration_mode_t_PHY_RF_CAL_FULL
            } else {
                sys::include::esp_phy_calibration_mode_t_PHY_RF_CAL_PARTIAL
            }
        } else {
            sys::include::esp_phy_calibration_mode_t_PHY_RF_CAL_FULL
        };
        let init_data = &phy_init_data::PHY_INIT_DATA_DEFAULT;
        unsafe {
            self.calibration_result = sys::include::register_chipv7_phy(
                init_data,
                self.calibration_data() as *mut PhyCalibrationData as *mut _,
                calibration_mode,
            );
        }
        self.calibrated = true;
    }

    #[cfg(phy_backed_up_digital_register_count_is_set)]
    /// Backup the digital PHY register into memory.
    fn backup_digital_regs(&mut self) {
        unsafe {
            sys::include::phy_dig_reg_backup(
                true,
                self.phy_digital_register_backup.get_or_insert_default() as *mut u32,
            );
        }
    }

    #[cfg(phy_backed_up_digital_register_count_is_set)]
    /// Restore the digital PHY registers from memory.
    ///
    /// This panics if the registers weren't previously backed up.
    fn restore_digital_regs(&mut self) {
        unsafe {
            sys::include::phy_dig_reg_backup(
                false,
                self.phy_digital_register_backup
                    .as_mut()
                    .expect("Can't restore digital PHY registers from backup, without a backup.")
                    as *mut u32,
            );
            self.phy_digital_register_backup = None;
        }
    }

    /// Increase the number of references to the PHY.
    ///
    /// If the ref count was zero, the PHY will be initialized.
    pub fn increase_ref_count(&mut self) {
        if self.ref_count == 0 {
            #[cfg(esp32)]
            {
                let now = Instant::now();
                let delta = now - self.phy_clock_state_transition_timestamp;
                self.phy_clock_state_transition_timestamp = now;
                self.mac_clock_delta_since_last_call += delta;
            }
            if self.calibrated {
                unsafe {
                    sys::include::phy_wakeup_init();
                }
                #[cfg(phy_backed_up_digital_register_count_is_set)]
                self.restore_digital_regs();
            } else {
                self.calibrate();
                self.calibrated = true;
            }
        }
        #[cfg(esp32)]
        if let Some(cb) = self.mac_time_update_cb {
            (cb)(self.mac_clock_delta_since_last_call);
            self.mac_clock_delta_since_last_call = Duration::ZERO;
        }

        self.ref_count += 1;
    }

    /// Decrease the number of reference to the PHY.
    ///
    /// If the ref count hits zero, the PHY will be deinitialized.
    ///
    /// # Panics
    /// This panics, if the PHY ref count is already at zero.
    pub fn decrease_ref_count(&mut self) {
        self.ref_count = self
            .ref_count
            .checked_sub(1)
            .expect("PHY init ref count dropped below zero.");
        if self.ref_count == 0 {
            #[cfg(phy_backed_up_digital_register_count_is_set)]
            self.backup_digital_regs();
            unsafe {
                // Disable PHY and RF.
                sys::include::phy_close_rf();

                // Power down PHY temperature sensor.
                #[cfg(not(esp32))]
                sys::include::phy_xpd_tsens();
            }
            #[cfg(esp32)]
            {
                self.phy_clock_state_transition_timestamp = Instant::now();
            }
            // The PHY clock guard will get released in the drop code of the PhyInitGuard. Note
            // that this accepts a slight skewing of the delta, since the clock will be disabled
            // after we record the value. This shouldn't be too bad though.
        }
    }
}

fn is_reset_from_deepsleep() -> bool {
    // feature gated to avoid forgetting to double check the correct value for future chips
    #[cfg(any(
        esp32, esp32c2, esp32c3, esp32c5, esp32c6, esp32c61, esp32h2, esp32s2, esp32s3
    ))]
    const CORE_DEEP_SLEEP: u32 = 5;

    unsafe extern "C" {
        fn rtc_get_reset_reason(cpu_num: u32) -> u32;
    }

    let reason = unsafe { rtc_get_reset_reason(Cpu::current() as u32) };

    reason == CORE_DEEP_SLEEP
}

/// Global PHY initialization state
static PHY_STATE: NonReentrantMutex<PhyState> = NonReentrantMutex::new(PhyState::new());

/// Prevents the PHY from being deinitialized.
///
/// As long as at least one [PhyInitGuard] exists, the PHY will remain initialized. To release this
/// guard, you can either let it go out of scope, or use [PhyInitGuard::release] to explicitly
/// release it.
#[derive(Debug)]
pub struct PhyInitGuard<'d> {
    _phy_clock_guard: PhyClockGuard<'d>,
}

impl PhyInitGuard<'_> {
    #[inline]
    /// Release the init guard.
    ///
    /// The PHY will be disabled, if this is the last init guard.
    pub fn release(self) {
        // Runs the Drop implementation
    }
}

impl Drop for PhyInitGuard<'_> {
    fn drop(&mut self) {
        PHY_STATE.with(|phy_state| phy_state.decrease_ref_count());
    }
}

/// Enable the PHY.
///
/// If no other [PhyInitGuard] is currently alive, this will also initialize the PHY, which
/// will involve a full RF calibration, unless you loaded previously backed up calibration
/// data with [set_phy_calibration_data].
pub fn enable_phy<'d>() -> PhyInitGuard<'d> {
    // In esp-idf, this is done after calculating the MAC time delta, but it shouldn't make
    // much of a difference.
    let _phy_clock_guard = enable_phy_clock();

    PHY_STATE.with(|phy_state| phy_state.increase_ref_count());

    PhyInitGuard { _phy_clock_guard }
}

/// Manually disable the PHY.
///
/// This is only useful if you [core::mem::forget] the [PhyInitGuard].
pub fn disable_phy() {
    PHY_STATE.with(|phy_state| phy_state.decrease_ref_count());
    // Balance the PhyClockGuard that was mem::forget'd with PhyInitGuard.
    // Without this, PHY_CLOCK_REF_COUNTER (u8) leaks on every phy_enable/phy_disable
    // cycle from the WiFi blob C-callback interface, overflowing after ~9 TCP connects.
    decrease_phy_clock_ref_count_internal();
}

/// Enable the PHY clock and acquire a [PhyClockGuard].
///
/// The PHY clock will only be disabled once all [PhyClockGuard]s are dropped.
pub fn enable_phy_clock<'d>() -> PhyClockGuard<'d> {
    increase_phy_clock_ref_count_internal();
    PhyClockGuard {
        _phantom: PhantomData,
    }
}

/// Set the MAC time update callback.
///
/// See [MacTimeUpdateCb] for details.
#[cfg(esp32)]
pub fn set_mac_time_update_cb(mac_time_update_cb: MacTimeUpdateCb) {
    PHY_STATE.with(|phy_state| phy_state.mac_time_update_cb = Some(mac_time_update_cb));
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
/// Calibration data was already set.
pub struct CalibrationDataAlreadySetError;

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
/// No calibration data is available.
pub struct NoCalibrationDataError;

/// Result of the PHY calibration.
#[derive(Debug, Clone, Copy)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[non_exhaustive]
pub enum CalibrationResult {
    /// The calibration data was valid and was used for calibration.
    Ok,

    /// The calibration data checksum check failed, or the calibration data was outdated.
    DataCheckFailed,
}

/// Load previously backed up PHY calibration data.
pub fn set_phy_calibration_data(
    calibration_data: &PhyCalibrationData,
) -> Result<(), CalibrationDataAlreadySetError> {
    PHY_STATE.with(|phy_state| {
        if phy_state.calibration_data.is_some() {
            Err(CalibrationDataAlreadySetError)
        } else {
            phy_state.calibration_data = Some(*calibration_data);
            Ok(())
        }
    })
}

/// Backup the PHY calibration data to the provided slice.
pub fn backup_phy_calibration_data(
    buffer: &mut PhyCalibrationData,
) -> Result<(), NoCalibrationDataError> {
    PHY_STATE.with(|phy_state| {
        phy_state
            .calibration_data
            .as_mut()
            .ok_or(NoCalibrationDataError)
            .map(|calibration_data| buffer.copy_from_slice(calibration_data.as_slice()))
    })
}

/// 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.
pub fn last_calibration_result() -> Option<CalibrationResult> {
    PHY_STATE.with(|phy_state| {
        if phy_state.calibrated {
            Some(
                if phy_state.calibration_result == sys::include::ESP_CAL_DATA_CHECK_FAIL as i32 {
                    CalibrationResult::DataCheckFailed
                } else {
                    CalibrationResult::Ok
                },
            )
        } else {
            None
        }
    })
}