libbladerf-rs 0.5.2

//! LMS6002D gain control.
//!
//! RX gain chain: LNA + VGA1 + VGA2.
//! TX gain chain: VGA1 + VGA2.
//! Each stage has its own programmable gain range and step size.

use crate::Error;
use crate::bladerf1::hardware::lms6002d::Lms6002d;
use crate::maybe_future::Op;
use crate::range::{Range, RangeItem};
use nusb::MaybeFuture;

/// RX gain offset applied when converting between dB FS and dBm.
pub const BLADERF1_RX_GAIN_OFFSET: f32 = -6.0;
/// TX gain offset applied when converting between dB FS and dBm.
pub const BLADERF1_TX_GAIN_OFFSET: f32 = 52.0;

/// LMS6002D power amplifier selection.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum LmsPowerAmplifier {
    /// Auxiliary amplifier.
    PaAux,
    /// PA for low band (<1.5 GHz).
    Pa1,
    /// PA for high band (>=1.5 GHz).
    Pa2,
    /// No power amplifier selected.
    PaNone,
}
/// LMS6002D low-noise amplifier selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LmsLowNoiseAmplifier {
    /// No LNA selected.
    LnaNone,
    /// LNA for low band and general use.
    Lna1,
    /// LNA for high band.
    Lna2,
    /// LNA for XB-200 expansion.
    Lna3,
}
impl From<LmsLowNoiseAmplifier> for u8 {
    fn from(value: LmsLowNoiseAmplifier) -> Self {
        match value {
            LmsLowNoiseAmplifier::LnaNone => 0,
            LmsLowNoiseAmplifier::Lna1 => 1,
            LmsLowNoiseAmplifier::Lna2 => 2,
            LmsLowNoiseAmplifier::Lna3 => 3,
        }
    }
}
impl TryFrom<u8> for LmsLowNoiseAmplifier {
    type Error = Error;
    fn try_from(value: u8) -> crate::Result<Self> {
        match value {
            0 => Ok(LmsLowNoiseAmplifier::LnaNone),
            1 => Ok(LmsLowNoiseAmplifier::Lna1),
            2 => Ok(LmsLowNoiseAmplifier::Lna2),
            3 => Ok(LmsLowNoiseAmplifier::Lna3),
            _ => Err(Error::Argument("invalid LNA value".into())),
        }
    }
}
impl TryFrom<u8> for LmsPowerAmplifier {
    type Error = Error;
    fn try_from(pa_en: u8) -> crate::Result<Self> {
        match pa_en & 7 {
            0 => Ok(LmsPowerAmplifier::PaNone),
            2 => Ok(LmsPowerAmplifier::Pa1),
            4 => Ok(LmsPowerAmplifier::Pa2),
            _ => Err(Error::Argument("invalid PA value".into())),
        }
    }
}
/// Gain stage specification: minimum, maximum, and step in dB.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GainSpec {
    /// Minimum gain in dB.
    pub(crate) min: i8,
    /// Maximum gain in dB.
    pub(crate) max: i8,
    /// Gain step in dB.
    pub(crate) step: i8,
}
impl GainSpec {
    pub(crate) const fn new(min: i8, max: i8, step: i8) -> Self {
        Self { min, max, step }
    }
}

/// LNA gain specification: 0–6 dB in 3 dB steps.
pub const GAIN_SPEC_LNA: GainSpec = GainSpec::new(0, 6, 3);
/// RX VGA1 gain specification: 5–30 dB in 1 dB steps.
pub const GAIN_SPEC_RXVGA1: GainSpec = GainSpec::new(5, 30, 1);
/// RX VGA2 gain specification: 0–30 dB in 3 dB steps.
pub const GAIN_SPEC_RXVGA2: GainSpec = GainSpec::new(0, 30, 3);
/// TX VGA1 gain specification: -35 to -4 dB in 1 dB steps.
pub const GAIN_SPEC_TXVGA1: GainSpec = GainSpec::new(-35, -4, 1);
/// TX VGA2 gain specification: 0–25 dB in 1 dB steps.
pub const GAIN_SPEC_TXVGA2: GainSpec = GainSpec::new(0, 25, 1);
/// Gain value in decibels.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct GainDb {
    db: i8,
}
impl GainDb {
    /// Returns the gain value in dB.
    pub fn db(&self) -> i8 {
        self.db
    }
}
impl From<i8> for GainDb {
    fn from(db: i8) -> Self {
        Self { db }
    }
}
/// LNA gain code used to program the LNA gain register.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum LnaGainCode {
    /// Bypass LNA1 and LNA2 (0 dB gain).
    BypassLna1Lna2 = 0x1,
    /// Mid-level gain for all LNAs (3 dB).
    MidAllLnas,
    /// Maximum gain for all LNAs (6 dB).
    MaxAllLnas,
}
impl From<LnaGainCode> for u8 {
    fn from(value: LnaGainCode) -> Self {
        match value {
            LnaGainCode::BypassLna1Lna2 => 1,
            LnaGainCode::MidAllLnas => 2,
            LnaGainCode::MaxAllLnas => 3,
        }
    }
}
impl TryFrom<u8> for LnaGainCode {
    type Error = ();
    fn try_from(value: u8) -> std::result::Result<Self, Self::Error> {
        match value {
            1 => Ok(LnaGainCode::BypassLna1Lna2),
            2 => Ok(LnaGainCode::MidAllLnas),
            3 => Ok(LnaGainCode::MaxAllLnas),
            _ => {
                log::error!("Unsupported Gain Code {value}");
                Err(())
            }
        }
    }
}
impl From<LnaGainCode> for GainDb {
    fn from(value: LnaGainCode) -> Self {
        GainDb {
            db: match value {
                LnaGainCode::MaxAllLnas => GAIN_SPEC_LNA.max,
                LnaGainCode::MidAllLnas => GAIN_SPEC_LNA.max / 2,
                LnaGainCode::BypassLna1Lna2 => 0i8,
            },
        }
    }
}
impl From<GainDb> for LnaGainCode {
    fn from(value: GainDb) -> Self {
        if value.db() >= GAIN_SPEC_LNA.max {
            LnaGainCode::MaxAllLnas
        } else if value.db() >= GAIN_SPEC_LNA.max / 2 {
            LnaGainCode::MidAllLnas
        } else {
            LnaGainCode::BypassLna1Lna2
        }
    }
}
/// RX VGA1 hardware gain code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Rxvga1GainCode {
    /// Raw register value.
    pub(crate) code: u8,
}
impl From<u8> for Rxvga1GainCode {
    fn from(code: u8) -> Self {
        Self { code }
    }
}
impl From<Rxvga1GainCode> for GainDb {
    fn from(value: Rxvga1GainCode) -> Self {
        let gain_db = (GAIN_SPEC_RXVGA1.min as f32
            + (20.0 * (127.0 / (127.0 - value.code as f32)).log10()))
        .round() as i8;
        GainDb {
            db: gain_db.clamp(GAIN_SPEC_RXVGA1.min, GAIN_SPEC_RXVGA1.max),
        }
    }
}
impl From<GainDb> for Rxvga1GainCode {
    fn from(value: GainDb) -> Self {
        let gain_db = value.db().clamp(GAIN_SPEC_RXVGA1.min, GAIN_SPEC_RXVGA1.max);
        Rxvga1GainCode {
            code: (127.0 - 127.0 / (10.0f32.powf((gain_db - GAIN_SPEC_RXVGA1.min) as f32 / 20.0)))
                .round() as u8,
        }
    }
}
/// RX VGA2 hardware gain code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Rxvga2GainCode {
    /// Raw register value.
    pub(crate) code: u8,
}
impl From<u8> for Rxvga2GainCode {
    fn from(code: u8) -> Self {
        Self { code }
    }
}
impl From<Rxvga2GainCode> for GainDb {
    fn from(value: Rxvga2GainCode) -> Self {
        let gain_db = (value.code * GAIN_SPEC_RXVGA2.step as u8) as i8;
        GainDb {
            db: gain_db.clamp(GAIN_SPEC_RXVGA2.min, GAIN_SPEC_RXVGA2.max),
        }
    }
}
impl From<GainDb> for Rxvga2GainCode {
    fn from(value: GainDb) -> Self {
        let gain_db = value.db().clamp(GAIN_SPEC_RXVGA2.min, GAIN_SPEC_RXVGA2.max);
        Rxvga2GainCode {
            code: (gain_db as f32 / GAIN_SPEC_RXVGA2.step as f32).round() as u8,
        }
    }
}
/// TX VGA1 hardware gain code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Txvga1GainCode {
    /// Raw register value.
    pub(crate) code: u8,
}
impl From<u8> for Txvga1GainCode {
    fn from(code: u8) -> Self {
        Self { code }
    }
}
impl From<Txvga1GainCode> for GainDb {
    fn from(value: Txvga1GainCode) -> Self {
        let clamped = value.code & 0x1f;
        GainDb {
            db: clamped as i8 + GAIN_SPEC_TXVGA1.min,
        }
    }
}
impl From<GainDb> for Txvga1GainCode {
    fn from(value: GainDb) -> Self {
        let clamped = value.db().clamp(GAIN_SPEC_TXVGA1.min, GAIN_SPEC_TXVGA1.max);
        Txvga1GainCode {
            code: (clamped - GAIN_SPEC_TXVGA1.min) as u8,
        }
    }
}
/// TX VGA2 hardware gain code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Txvga2GainCode {
    /// Raw register value.
    pub(crate) code: u8,
}
impl From<u8> for Txvga2GainCode {
    fn from(code: u8) -> Self {
        Self { code }
    }
}
impl From<Txvga2GainCode> for GainDb {
    fn from(value: Txvga2GainCode) -> Self {
        let clamped = (value.code >> 3) & 0x1f;
        GainDb {
            db: clamped.min(GAIN_SPEC_TXVGA2.max as u8) as i8,
        }
    }
}
impl From<GainDb> for Txvga2GainCode {
    fn from(value: GainDb) -> Self {
        let clamped = value.db().clamp(GAIN_SPEC_TXVGA2.min, GAIN_SPEC_TXVGA2.max);
        Txvga2GainCode {
            code: ((clamped & 0x1f) << 3) as u8,
        }
    }
}
/// Identifies a specific gain stage in the LMS6002D signal chain.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GainStage {
    /// RX low-noise amplifier (0–6 dB, step 3).
    Lna,
    /// RX variable gain amplifier stage 1 (5–30 dB, step 1).
    RxVga1,
    /// RX variable gain amplifier stage 2 (0–30 dB, step 3).
    RxVga2,
    /// TX variable gain amplifier stage 1 (-35 to -4 dB, step 1).
    TxVga1,
    /// TX variable gain amplifier stage 2 (0–25 dB, step 1).
    TxVga2,
}
impl GainStage {
    /// Returns `true` if this stage belongs to the RX path.
    pub const fn is_rx(&self) -> bool {
        matches!(self, GainStage::Lna | GainStage::RxVga1 | GainStage::RxVga2)
    }
    /// Returns `true` if this stage belongs to the TX path.
    pub const fn is_tx(&self) -> bool {
        matches!(self, GainStage::TxVga1 | GainStage::TxVga2)
    }
    /// Returns the gain range (min, max, step) for this stage.
    pub fn gain_range(self) -> Range {
        let spec = match self {
            Self::Lna => GAIN_SPEC_LNA,
            Self::RxVga1 => GAIN_SPEC_RXVGA1,
            Self::RxVga2 => GAIN_SPEC_RXVGA2,
            Self::TxVga1 => GAIN_SPEC_TXVGA1,
            Self::TxVga2 => GAIN_SPEC_TXVGA2,
        };
        Range::new(vec![RangeItem::Step(
            spec.min as f64,
            spec.max as f64,
            spec.step as f64,
            1.0,
        )])
    }
}
impl From<GainStage> for &'static str {
    fn from(stage: GainStage) -> Self {
        match stage {
            GainStage::Lna => "lna",
            GainStage::RxVga1 => "rxvga1",
            GainStage::RxVga2 => "rxvga2",
            GainStage::TxVga1 => "txvga1",
            GainStage::TxVga2 => "txvga2",
        }
    }
}
impl TryFrom<&str> for GainStage {
    type Error = crate::error::Error;
    fn try_from(name: &str) -> crate::error::Result<Self> {
        match name.to_lowercase().as_str() {
            "lna" => Ok(GainStage::Lna),
            "rxvga1" => Ok(GainStage::RxVga1),
            "rxvga2" => Ok(GainStage::RxVga2),
            "txvga1" => Ok(GainStage::TxVga1),
            "txvga2" => Ok(GainStage::TxVga2),
            _ => Err(Error::Argument("unknown gain stage".into())),
        }
    }
}
impl<'a> Lms6002d<'a> {
    pub(crate) fn lna_set_gain(
        &mut self,
        gain_db: GainDb,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut data = self.read(0x75).await?;
            data &= !(3 << 6);
            let lna_gain_code: LnaGainCode = gain_db.into();
            let lna_gain_code_u8: u8 = lna_gain_code.into();
            data |= (lna_gain_code_u8 & 3) << 6;
            self.write(0x75, data).await
        })
    }

    pub(crate) fn lna_get_gain(&mut self) -> impl MaybeFuture<Output = crate::Result<GainDb>> {
        Op::new(async move {
            let mut data = self.read(0x75).await?;
            data >>= 6;
            data &= 3;
            let lna_gain_code: LnaGainCode = data
                .try_into()
                .map_err(|_| Error::BoardState("invalid LNA gain code from hardware"))?;
            Ok(lna_gain_code.into())
        })
    }

    pub(crate) fn get_lna(
        &mut self,
    ) -> impl MaybeFuture<Output = crate::Result<LmsLowNoiseAmplifier>> {
        Op::new(async move {
            let data = self.read(0x75).await?;
            LmsLowNoiseAmplifier::try_from((data >> 4) & 0x3)
        })
    }

    pub(crate) fn get_pa(&mut self) -> impl MaybeFuture<Output = crate::Result<LmsPowerAmplifier>> {
        Op::new(async move {
            let data = self.read(0x44).await?;
            if (data & (1 << 1)) == 0 {
                return Ok(LmsPowerAmplifier::PaAux);
            }
            LmsPowerAmplifier::try_from((data >> 2) & 7)
        })
    }

    pub(crate) fn rxvga1_enable(
        &mut self,
        enable: bool,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut data = self.read(0x7d).await?;
            if enable {
                data &= !(1 << 3);
            } else {
                data |= 1 << 3;
            }
            self.write(0x7d, data).await
        })
    }

    pub(crate) fn rxvga1_set_gain(
        &mut self,
        gain_db: GainDb,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let code: Rxvga1GainCode = gain_db.into();
            self.write(0x76, code.code).await
        })
    }

    pub(crate) fn rxvga1_get_gain(&mut self) -> impl MaybeFuture<Output = crate::Result<GainDb>> {
        Op::new(async move {
            let mut data = self.read(0x76).await?;
            data &= 0x7f;
            let rxvga1_gain_code = Rxvga1GainCode::from(data.clamp(0, 120));
            Ok(rxvga1_gain_code.into())
        })
    }

    pub(crate) fn rxvga2_enable(
        &mut self,
        enable: bool,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut data = self.read(0x64).await?;
            if enable {
                data |= 1 << 1;
            } else {
                data &= !(1 << 1);
            }
            self.write(0x64, data).await
        })
    }

    pub(crate) fn rxvga2_set_gain(
        &mut self,
        gain_db: GainDb,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let code: Rxvga2GainCode = gain_db.into();
            self.write(0x65, code.code).await
        })
    }

    pub(crate) fn rxvga2_get_gain(&mut self) -> impl MaybeFuture<Output = crate::Result<GainDb>> {
        Op::new(async move {
            let rxvga2_gain_code = Rxvga2GainCode::from(self.read(0x65).await?);
            Ok(rxvga2_gain_code.into())
        })
    }

    pub(crate) fn txvga1_get_gain(&mut self) -> impl MaybeFuture<Output = crate::Result<GainDb>> {
        Op::new(async move {
            let txvga1_gain_code = Txvga1GainCode::from(self.read(0x41).await?);
            Ok(txvga1_gain_code.into())
        })
    }

    pub(crate) fn txvga2_get_gain(&mut self) -> impl MaybeFuture<Output = crate::Result<GainDb>> {
        Op::new(async move {
            let txvga2_gain_code = Txvga2GainCode::from(self.read(0x45).await?);
            Ok(txvga2_gain_code.into())
        })
    }

    pub(crate) fn txvga1_set_gain(
        &mut self,
        gain_db: GainDb,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let txvga1_gain_code: Txvga1GainCode = gain_db.into();
            self.write(0x41, txvga1_gain_code.code).await
        })
    }

    pub(crate) fn txvga2_set_gain(
        &mut self,
        gain_db: GainDb,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut data = self.read(0x45).await?;
            data &= !(0x1f << 3);
            let txvga2_gain_code: Txvga2GainCode = gain_db.into();
            data |= txvga2_gain_code.code;
            self.write(0x45, data).await
        })
    }

    pub(crate) fn enable_lna_power(
        &mut self,
        enable: bool,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut regval = self.read(0x7d).await?;
            if enable {
                regval &= !(1 << 0);
            } else {
                regval |= 1 << 0;
            }
            self.write(0x7d, regval).await?;
            let mut regval = self.read(0x70).await?;
            if enable {
                regval &= !(1 << 1);
            } else {
                regval |= 1 << 1;
            }
            self.write(0x70, regval).await
        })
    }

    pub(crate) fn select_pa(
        &mut self,
        pa: LmsPowerAmplifier,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut data = self.read(0x44).await?;
            data &= !0x1C;
            data |= 1 << 1;
            match pa {
                LmsPowerAmplifier::PaAux => {
                    data &= !(1 << 1);
                }
                LmsPowerAmplifier::Pa1 => {
                    data |= 2 << 2;
                }
                LmsPowerAmplifier::Pa2 => {
                    data |= 4 << 2;
                }
                LmsPowerAmplifier::PaNone => {}
            }
            self.write(0x44, data).await
        })
    }

    pub(crate) fn select_lna(
        &mut self,
        lna: LmsLowNoiseAmplifier,
    ) -> impl MaybeFuture<Output = crate::Result<()>> {
        Op::new(async move {
            let mut data = self.read(0x75).await?;
            data &= !(3 << 4);
            data |= (u8::from(lna) & 3) << 4;
            self.write(0x75, data).await
        })
    }
}