From 10d265b4806f04985d387132b1cbf93ea4b80c31 Mon Sep 17 00:00:00 2001 From: occheung Date: Thu, 24 Sep 2020 17:36:53 +0800 Subject: [PATCH] urukul: rebranded lib --- src/urukul.rs | 338 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 338 insertions(+) create mode 100644 src/urukul.rs diff --git a/src/urukul.rs b/src/urukul.rs new file mode 100644 index 0000000..a876ebe --- /dev/null +++ b/src/urukul.rs @@ -0,0 +1,338 @@ +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 { + 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 { + config_register: ConfigRegister, + attenuator: Attenuator, + multi_dds: DDS, + dds: [DDS; 4], + f_master_clk: f64, +} + +impl Urukul +where + SPI: Transfer, +{ + /* + * 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> { + // 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> { + 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 Urukul +where + SPI: Transfer +{ + + pub fn get_channel_switch_status(&mut self, channel: u32) -> Result> { + 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> { + 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> { + // 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> { + // 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> { + // 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> { + 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> { + // 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> { + 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> { + 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> { + 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> { + 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> { + 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> { + 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> { + 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> { + 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> { + 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> { + self.config_register.set_configurations(&mut [ + (CFGMask::IO_UPDATE, 1) + ])?; + self.config_register.set_configurations(&mut [ + (CFGMask::IO_UPDATE, 0) + ]).map(|_| ()) + } + +}