humpback-dds/src/urukul.rs

extern crate embedded_hal;
use embedded_hal::{
    blocking::spi::Transfer,
};

use crate::config_register::ConfigRegister;
use crate::config_register::CFGMask;
use crate::config_register::StatusMask;
use crate::attenuator::Attenuator;
use crate::dds::DDS;

/*
 * Enum for structuring error
 */
#[derive(Debug)]
pub enum Error<E> {
    SPI(E),
    CSError,
    GetRefMutDataError,
    AttenuatorError,
    IOUpdateError,
    DDSError,
    ConfigRegisterError,
    DDSCLKError,
    DDSRAMError,
    ParameterError,
    MqttTopicError,
    MqttCommandError,
}

#[derive(Debug, Clone)]
pub enum ClockSource {
    OSC,
    SMA,
    MMCX,
}

/*
 *  Struct for Urukul master device
 */
pub struct Urukul<SPI> {
    config_register: ConfigRegister<SPI>,
    attenuator: Attenuator<SPI>,
    multi_dds: DDS<SPI>,
    dds: [DDS<SPI>; 4],
    f_master_clk: f64,
}

impl<SPI, E> Urukul<SPI>
where
    SPI: Transfer<u8, Error = E>,
{
    /*
     *  Master constructor for the entire Urukul device
     *  Supply 7 SPI channels to Urukul and 4 reference clock frequencies
     */
    pub fn new(spi1: SPI, spi2: SPI, spi3: SPI, spi4: SPI, spi5: SPI, spi6: SPI, spi7: SPI) -> Self {
        // Construct Urukul
        Urukul {
            config_register: ConfigRegister::new(spi1),
            attenuator: Attenuator::new(spi2),
            // Create a multi-channel DDS with predefined 25MHz clock
            multi_dds: DDS::new(spi3, 25_000_000.0),
            // Create 4 DDS instances with predefined 25MHz clock
            // Counter-intuitive to assign urukul clock before having a urukul
            dds: [
                DDS::new(spi4, 25_000_000.0),
                DDS::new(spi5, 25_000_000.0),
                DDS::new(spi6, 25_000_000.0),
                DDS::new(spi7, 25_000_000.0),
            ],
            // Default clock selection: OSC, predefined 100MHz speed
            f_master_clk: 100_000_000.0,
        }
    }

    /*
     *  Reset method. To be invoked by initialization and manual reset.
     *  Only Urukul struct provides reset method.
     *  DDS reset is controlled by Urukul (RST).
     *  Attenuators only have shift register reset, which does not affect its data
     *  CPLD only has a "all-zero" default state.
     */
    pub fn reset(&mut self) -> Result<(), Error<E>> {
        // Reset DDS and attenuators
        self.config_register.set_configurations(&mut [
            (CFGMask::RST, 1),
            (CFGMask::IO_RST, 1),
            (CFGMask::IO_UPDATE, 0)
        ])?;
        // Set 0 to all fields on configuration register.
        self.config_register.set_configurations(&mut [
            (CFGMask::RF_SW,         0),
            (CFGMask::LED,             0),
            (CFGMask::PROFILE,         0),
            (CFGMask::IO_UPDATE,     0),
            (CFGMask::MASK_NU,         0),
            (CFGMask::CLK_SEL0,     0),
            (CFGMask::SYNC_SEL,     0),
            (CFGMask::RST,             0),
            (CFGMask::IO_RST,         0),
            (CFGMask::CLK_SEL1,     0),
            (CFGMask::DIV,             0),
        ])?;
        // Init all DDS chips. Configure SDIO as input only.
        for chip_no in 0..4 {
            self.dds[chip_no].init()?;
        }
        // Clock tree reset. OSC clock source by default
        self.f_master_clk = 100_000_000.0;
        // CPLD divides clock frequency by 4 by default.
        for chip_no in 0..4 {
            self.dds[chip_no].set_ref_clk_frequency(self.f_master_clk / 4.0)?;
        }
        Ok(())
    }

    /*
     *  Test method fo Urukul.
     *  Return the number of test failed.
     */
    pub fn test(&mut self) -> Result<u32, Error<E>> {
        let mut count = self.config_register.test()?;
        count += self.attenuator.test()?;
        for chip_no in 0..4 {
            count += self.dds[chip_no].test()?;
        }
        Ok(count)
    }
}

impl<SPI, E> Urukul<SPI>
where
    SPI: Transfer<u8, Error = E>
{

    pub fn get_channel_switch_status(&mut self, channel: u32) -> Result<bool, Error<E>> {
        if channel < 4 {
            self.config_register.get_status(StatusMask::RF_SW).map(|val| (val & (1 << channel)) != 0)
        } else {
            Err(Error::ParameterError)
        }
    }

    pub fn set_channel_switch(&mut self, channel: u32, status: bool) -> Result<(), Error<E>> {
        if channel < 4 {
            let prev = u32::from(self.config_register.get_status(StatusMask::RF_SW)?);
            let next = {
                if status {
                    prev | (1 << channel)
                } else {
                    prev & (!(1 << channel))
                }
            };
            self.config_register.set_configurations(&mut [
                (CFGMask::RF_SW, next),
            ]).map(|_| ())
        } else {
            Err(Error::ParameterError)
        }
    }

    pub fn set_clock(&mut self, source: ClockSource, frequency: f64, division: u8) -> Result<(), Error<E>> {
        // Change clock source through configuration register
        self.set_clock_source(source)?;

        // Modify the master clock frequency
        // Prevent redundunt call to change f_ref_clk
        self.f_master_clk = frequency;

        self.set_clock_division(division)
    }

    pub fn set_clock_source(&mut self, source: ClockSource) -> Result<(), Error<E>> {
        // Change clock source through configuration register
        match source {
            ClockSource::OSC => self.config_register.set_configurations(&mut [
                (CFGMask::CLK_SEL0, 0),
                (CFGMask::CLK_SEL1, 0),
            ]),
            ClockSource::MMCX => self.config_register.set_configurations(&mut [
                (CFGMask::CLK_SEL0, 0),
                (CFGMask::CLK_SEL1, 1),
            ]),
            ClockSource::SMA => self.config_register.set_configurations(&mut [
                (CFGMask::CLK_SEL0, 1),
            ]),
        }.map(|_| ())
    }

    pub fn set_clock_frequency(&mut self, frequency: f64) -> Result<(), Error<E>> {
        // Update master clock frequency
        self.f_master_clk = frequency;

        // Update all DDS f_ref_clk
        self.set_dds_ref_clk()
    }

    pub fn set_clock_division(&mut self, division: u8) -> Result<(), Error<E>> {
        match division {
            1 => self.config_register.set_configurations(&mut [
                (CFGMask::DIV, 1),
            ]),
            2 => self.config_register.set_configurations(&mut [
                (CFGMask::DIV, 2),
            ]),
            4 => self.config_register.set_configurations(&mut [
                (CFGMask::DIV, 3),
            ]),
            _ => Err(Error::ParameterError),
        }?;

        self.set_dds_ref_clk()
    }

    fn set_dds_ref_clk(&mut self) -> Result<(), Error<E>> {
        // Calculate reference clock frequency after clock division from configuration register
        let f_ref_clk = self.f_master_clk / (self.get_master_clock_division() as f64);

        // Update all DDS chips on reference clock frequency
        for dds_channel in 0..4 {
            self.dds[dds_channel].set_ref_clk_frequency(f_ref_clk)?;
        }
        Ok(())
    }

    fn get_master_clock_division(&mut self) -> u8 {
        match self.config_register.get_configuration(CFGMask::DIV) {
            0 | 3 => 4,
            1 => 1,
            2 => 2,
            _ => panic!("Divisor out of range, when reading configuration register (CPLD)."),
        }
    }

    pub fn set_channel_attenuation(&mut self, channel: u8, attenuation: f32) -> Result<(), Error<E>> {
        if channel >= 4 || attenuation < 0.0 || attenuation > 31.5 {
            return Err(Error::ParameterError);
        }
        self.attenuator.set_channel_attenuation(channel, attenuation)
    }

    pub fn set_profile(&mut self, profile: u8) -> Result<(), Error<E>> {
        if profile >= 8 {
            return Err(Error::ParameterError);
        }
        self.config_register.set_configurations(&mut [
            (CFGMask::PROFILE, profile.into())
        ]).map(|_| ())
    }

    pub fn set_channel_single_tone_profile(&mut self, channel: u8, profile: u8, frequency: f64, phase: f64, amplitude: f64) -> Result<(), Error<E>> {
        if channel >= 4 || profile >= 8 || frequency < 0.0 || phase >= 360.0 ||
            phase < 0.0 || amplitude < 0.0 || amplitude > 1.0 {
            return Err(Error::ParameterError);
        }
        self.dds[usize::from(channel)].set_single_tone_profile(profile, frequency, phase, amplitude)
    }

    pub fn set_channel_single_tone_profile_frequency(&mut self, channel: u8, profile: u8, frequency: f64)-> Result<(), Error<E>> {
        if channel >= 4 || profile >= 8 || frequency < 0.0 {
            return Err(Error::ParameterError);
        }
        self.dds[usize::from(channel)].set_single_tone_profile_frequency(profile, frequency)
    }

    pub fn set_channel_single_tone_profile_phase(&mut self, channel: u8, profile: u8, phase: f64)-> Result<(), Error<E>> {
        if channel >= 4 || profile >= 8 || phase >= 360.0 || phase < 0.0 {
            return Err(Error::ParameterError);
        }
        self.dds[usize::from(channel)].set_single_tone_profile_phase(profile, phase)
    }

    pub fn set_channel_single_tone_profile_amplitude(&mut self, channel: u8, profile: u8, amplitude: f64)-> Result<(), Error<E>> {
        if channel >= 4 || profile >= 8 || amplitude < 0.0 || amplitude > 1.0 {
            return Err(Error::ParameterError);
        }
        self.dds[usize::from(channel)].set_single_tone_profile_amplitude(profile, amplitude)
    }

    pub fn set_channel_sys_clk(&mut self, channel: u8, f_sys_clk: f64) -> Result<(), Error<E>> {
        self.dds[usize::from(channel)].set_sys_clk_frequency(f_sys_clk).map(|_| ())
    }

    // Multi-dds channel functions
    // Do not allow reading of DDS registers
    // Make sure only 1 SPI transaction is compelted per function call

    // Setup NU_MASK in configuration register
    // This selects the DDS channels that will be covered by multi_channel DDS (spi3)
    // Note: If a channel is masked, io_update must be completed through configuration register (IO_UPDATE bit-field)
    // Implication: Deselect such channel if individual communication is needed.
    pub fn set_multi_channel_coverage(&mut self, channel: u8) -> Result<(), Error<E>> {
        self.config_register.set_configurations(&mut [
            (CFGMask::MASK_NU, channel.into())
        ]).map(|_| ())
    }

    // Difference from individual single tone setup function:
    // - Remove the need of passing channel
    // All selected channels must share the same f_sys_clk
    pub fn set_multi_channel_single_tone_profile(&mut self, profile: u8, frequency: f64, phase: f64, amplitude: f64) -> Result<(), Error<E>> {
        if profile >= 8 || frequency < 0.0 || phase >= 360.0 ||
            phase < 0.0 || amplitude < 0.0 || amplitude > 1.0 {
            return Err(Error::ParameterError);
        }
        // Check f_sys_clk of all selected channels
        let selected_channels = self.config_register.get_configuration(CFGMask::MASK_NU);
        let mut found_a_selected_channel = false;
        let mut reported_f_sys_clk: f64 = 0.0;
        for channel_bit in 0..4 {
            if (selected_channels & (1 << (channel_bit as u8))) != 0 {
                if !found_a_selected_channel {
                    found_a_selected_channel = true;
                    reported_f_sys_clk = self.dds[channel_bit].get_f_sys_clk();
                } else if reported_f_sys_clk != self.dds[channel_bit].get_f_sys_clk() {
                    return Err(Error::DDSError);
                }
            }
        }
        self.multi_dds.set_sys_clk_frequency(reported_f_sys_clk)?;
        self.multi_dds.set_single_tone_profile(profile, frequency, phase, amplitude)?;
        self.invoke_io_update()?;
        Ok(())
    }

    // Generate a pulse for io_update bit in configuration register
    // This acts like io_update in CPLD struct, but for multi-dds channel
    fn invoke_io_update(&mut self) -> Result<(), Error<E>> {
        self.config_register.set_configurations(&mut [
            (CFGMask::IO_UPDATE, 1)
        ])?;
        self.config_register.set_configurations(&mut [
            (CFGMask::IO_UPDATE, 0)
        ]).map(|_| ())
    }
}