humpback-dds/src/dds.rs

use embedded_hal::blocking::spi::Transfer;
use crate::Error;
use core::mem::size_of;

/*
 *  Bitmask for all configurations (Order: CFR3, CFR2, CFR1)
 */
construct_bitmask!(DDSCFRMask; u32;
	// CFR1 bitmasks
	LSB_FIRST,						0,	1,
	SDIO_IN_ONLY,					1,	1,
	EXT_POWER_DOWN_CTRL,			3,	1,
	AUX_DAC_POWER_DOWN,				4,	1,
	REFCLK_IN_POWER_DOWN,			5,	1,
	DAC_POWER_DOWN,					6,	1,
	DIGITAL_POWER_DOWN,				7,	1,
	SEL_AUTO_OSK,					8,	1,
	OSK_ENABLE,						9,	1,
	LOAD_ARR_IO_UPDATE,				10,	1,
	CLEAR_PHASE_ACU,				11,	1,
	CLEAR_DIGITAL_RAMP_ACU,			12,	1,
	AUTOCLEAR_PHASE_ACU,			13,	1,
	AUTOCLEAR_DIGITAL_RAMP_ACU,		14,	1,
	LOAD_LRR_IO_UPDATE,				15,	1,
	SEL_DDS_SIN_OUT,				16,	1,
	PROFILE_CTRL,					17,	4,
	INV_SINC_FILTER_ENABLE,			22,	1,
	MANUAL_OSK_EXT_CTRL,			23,	1,
	RAM_PLAYBACK_DST,				29,	2,
	RAM_ENABLE,						31,	1,

	// CFR2 bitmasks
	FM_GAIN,						0  +32,	4,
	PARALLEL_DATA_PORT_ENABLE,		4  +32,	1,
	SYNC_TIM_VALIDATION_DISABLE,	5  +32,	1,
	DATA_ASSEM_HOLD_LAST_VALUE,		6  +32,	1,
	MATCHED_LATENCY_ENABLE,			7  +32,	1,
	TXENABLE_INV,					9  +32,	1,
	PDCLK_INV,						10 +32,	1,
	PDCLK_ENABLE,					11 +32,	1,
	IO_UPDATE_RATE_CTRL,			14 +32,	2,
	READ_EFFECTIVE_FTW,				16 +32,	1,
	DIGITAL_RAMP_NO_DWELL_LOW,		17 +32,	1,
	DIGITAL_RAMP_NO_DWELL_HIGH,		18 +32,	1,
	DIGITAL_RAMP_ENABLE,			19 +32,	1,
	DIGITAL_RAMP_DEST,				20 +32,	2,
	SYNC_CLK_ENABLE,				22 +32,	1,	
	INT_IO_UPDATE_ACTIVE,			23 +32,	1,
	EN_AMP_SCALE_SINGLE_TONE_PRO,	24 +32,	1,

	// CFR3 bitmasks
	N,								1  +64,	7,
	PLL_ENABLE,						8  +64,	1,
	PFD_RESET,						10 +64,	1,
	REFCLK_IN_DIV_RESETB,			14 +64,	1,
	REFCLK_IN_DIV_BYPASS,			15 +64,	1,
	I_CP,							19 +64,	3,
	VCO_SEL,						24 +64,	3,
	DRV0,							28 +64,	2
);

const WRITE_MASK 	:u8 = 0x00;
const READ_MASK		:u8 = 0x80;

pub struct DDS<SPI> {
	spi: SPI,
	f_ref_clk: u64,
	f_sys_clk: u64,
}

impl<SPI, E> DDS<SPI>
where
	SPI: Transfer<u8, Error = E>
{
	pub fn new(spi: SPI, f_ref_clk: u64) -> Self {
		DDS {
			spi,
			f_ref_clk,
			f_sys_clk: f_ref_clk,
		}
	}
}

impl<SPI, E> Transfer<u8> for DDS<SPI>
where
	SPI: Transfer<u8, Error = E>
{
	type Error = Error<E>;

	fn transfer<'w>(&mut self, words: &'w mut [u8]) -> Result<&'w [u8], Self::Error> {
		self.spi.transfer(words).map_err(Error::SPI)
	}
}


impl<SPI, E> DDS<SPI>
where
	SPI: Transfer<u8, Error = E>
{
	/*
	 *  Implement init: Set SDIO to be input only, using LSB first
	 */
	pub fn init(&mut self) -> Result<(), Error<E>> {
		match self.write_register(0x00, &mut [
			0x00, 0x00, 0x00, 0x02
		]) {
			Ok(_) => Ok(()),
			Err(e) => Err(e),
		}
	}

	/*
	 *  Implement clock control
	 */
	pub fn enable_divided_ref_clk(&mut self) -> Result<(), Error<E>> {
		self.set_configurations(&mut [
			// Disable PLL
			(DDSCFRMask::PLL_ENABLE, 0),
			// Take ref_clk source from divider
			(DDSCFRMask::REFCLK_IN_DIV_BYPASS, 0),
			// Ensure divider is not reset
			(DDSCFRMask::REFCLK_IN_DIV_RESETB, 1),
		])?;
		self.f_sys_clk = self.f_ref_clk / 2;
		Ok(())
	}

	pub fn enable_normal_ref_clk(&mut self) -> Result<(), Error<E>> {
		self.set_configurations(&mut [
			// Disable PLL
			(DDSCFRMask::PLL_ENABLE, 0),
			// Take ref_clk source from divider bypass
			(DDSCFRMask::REFCLK_IN_DIV_BYPASS, 1),
			// Reset does not matter
			(DDSCFRMask::REFCLK_IN_DIV_RESETB, 1),
		])?;
		self.f_sys_clk = self.f_ref_clk;
		Ok(())
	}

	pub fn enable_pll(&mut self, f_sys_clk: u64) -> Result<(), Error<E>> {
		// Get a divider
		let divider = f_sys_clk / self.f_ref_clk;
		// Reject extreme divider values. However, accept no frequency division
		if ((divider > 127 || divider < 12) && divider != 1) {
			// panic!("Invalid divider value for PLL!");
			return Err(Error::DDSCLKError);
		}
		let vco = self.get_VCO_no(f_sys_clk, divider as u8)?;

		self.set_configurations(&mut [
			// Enable PLL, set divider (valid or not) and VCO
			(DDSCFRMask::PLL_ENABLE, 1),
			(DDSCFRMask::N, divider as u32),
			(DDSCFRMask::VCO_SEL, vco.into()),
			// Reset PLL lock before re-enabling it
			(DDSCFRMask::PFD_RESET, 1),
		])?;
		self.set_configurations(&mut [
			(DDSCFRMask::PFD_RESET, 0),
		])?;
		self.f_sys_clk = self.f_ref_clk * divider;
		Ok(())
	}

	// Change external clock source (ref_clk)
	pub fn set_ref_clk_frequency(&mut self, f_ref_clk: u64) -> Result<(), Error<E>> {
		self.f_ref_clk = f_ref_clk;
		// TODO: Examine clock tree and update f_sys_clk
		let mut configuration_queries = [
			// Acquire PLL status
			(DDSCFRMask::PLL_ENABLE, 0),
			// Acquire N-divider, to adjust VCO if necessary
			(DDSCFRMask::N, 0),
			// Acquire REF_CLK divider bypass
			(DDSCFRMask::REFCLK_IN_DIV_BYPASS, 0)
		];

		self.get_configurations(&mut configuration_queries)?;
		if configuration_queries[0].1 == 1 {
			// Recalculate sys_clk
			let divider :u64 = configuration_queries[1].1.into();
			let f_sys_clk = self.f_ref_clk * divider;
			// Adjust VCO
			match self.get_VCO_no(f_sys_clk, divider as u8) {
				Ok(vco_no) => {
					self.set_configurations(&mut [
						// Update VCO selection
						(DDSCFRMask::VCO_SEL, vco_no.into()),
						// Reset PLL lock before re-enabling it
						(DDSCFRMask::PFD_RESET, 1),
					])?;
					self.set_configurations(&mut [
						(DDSCFRMask::PFD_RESET, 0),
					])?;
					// Update f_sys_clk from recalculation
					self.f_sys_clk = f_sys_clk;
					Ok(())
				},
				Err(_) => {
					// Forcibly turn off PLL, enable default clk tree (divide by 2)
					self.enable_divided_ref_clk()
				}
			}
		}
		else if configuration_queries[2].1 == 0 {
			self.f_sys_clk = self.f_ref_clk / 2;
			Ok(())
		}
		else {
			self.f_sys_clk = self.f_ref_clk;
			Ok(())
		}
	}

	#[allow(non_snake_case)]
	fn get_VCO_no(&mut self, f_sys_clk: u64, divider: u8) -> Result<u8, Error<E>> {
		// Select a VCO
		if divider == 1 {
			Ok(6)	// Bypass PLL if no frequency division needed
		} else if f_sys_clk > 1_150_000_000 {
			Err(Error::DDSCLKError)
		} else if f_sys_clk > 820_000_000 {
			Ok(5)
		} else if f_sys_clk > 700_000_000 {
			Ok(4)
		} else if f_sys_clk > 600_000_000 {
			Ok(3)
		} else if f_sys_clk > 500_000_000 {
			Ok(2)
		} else if f_sys_clk > 420_000_000 {
			Ok(1)
		} else if f_sys_clk > 370_000_000 {
			Ok(0)
		} else {
			Ok(7)	// Bypass PLL if f_sys_clk is too low
		}
	}

	/*
	 *  Implement configurations registers I/O through bitmasks
	 *
	 *  Get all (cfr1, cfr2, cfr3) contents
	 */
	fn get_all_configurations(&mut self) -> Result<[u32; 3], Error<E>> {
		let mut cfr_reg = [0; 12];
		self.read_register(0x00, &mut cfr_reg[0..4])?;
		self.read_register(0x01, &mut cfr_reg[4..8])?;
		self.read_register(0x02, &mut cfr_reg[8..12])?;
		Ok([
			(cfr_reg[0] as u32) << 24 | (cfr_reg[1] as u32) << 16 | (cfr_reg[2] as u32) << 8 | (cfr_reg[3] as u32),
			(cfr_reg[4] as u32) << 24 | (cfr_reg[5] as u32) << 16 | (cfr_reg[6] as u32) << 8 | (cfr_reg[7] as u32),
			(cfr_reg[8] as u32) << 24 | (cfr_reg[9] as u32) << 16 | (cfr_reg[10] as u32) << 8 | (cfr_reg[11] as u32)
		])
	}

	/*
	 *  Get a set of configurations using DDSCFRMask
	 */
	pub fn get_configurations<'w>(&mut self, mask_pairs: &'w mut[(DDSCFRMask, u32)]) -> Result<&'w [(DDSCFRMask, u32)], Error<E>> {
		let data_array = self.get_all_configurations()?;
		for index in 0..mask_pairs.len() {
			mask_pairs[index].1 = match mask_pairs[index].0.get_shift() {
				0..=31 => mask_pairs[index].0.get_filtered_content(data_array[0]),
				32..=63 => mask_pairs[index].0.get_filtered_content(data_array[1]),
				64..=95 => mask_pairs[index].0.get_filtered_content(data_array[2]),
				_ => panic!("Invalid DDSCFRMask!"),
			}
		}
		Ok(mask_pairs)
	}

	/*
	 *  Write (cfr1, cfr2, cfr3) contents
	 */
	fn set_all_configurations(&mut self, data_array: [u32; 3]) -> Result<(), Error<E>> {
		for register in 0x00..=0x02 {
			self.write_register(register, &mut [
				((data_array[register as usize] >> 24) & 0xFF) as u8,
				((data_array[register as usize] >> 16) & 0xFF) as u8,
				((data_array[register as usize] >> 8 ) & 0xFF) as u8,
				((data_array[register as usize] >> 0 ) & 0xFF) as u8
			])?;
		}
		Ok(())
	}

	/*
	 *  Set a set of configurations using DDSCFRMask
	 */
	pub fn set_configurations(&mut self, mask_pairs: &mut[(DDSCFRMask, u32)]) -> Result<(), Error<E>> {
		let mut data_array = self.get_all_configurations()?;
		for index in 0..mask_pairs.len() {
			// Reject any attempt to rewrite LSB_FIRST and SBIO_INPUT_ONLY
			if mask_pairs[index].0 == DDSCFRMask::LSB_FIRST || mask_pairs[index].0 == DDSCFRMask::SDIO_IN_ONLY {
				continue;
			}
			match mask_pairs[index].0.get_shift() {
				0..=31 => mask_pairs[index].0.set_data_by_arg(&mut data_array[0], mask_pairs[index].1),
				32..=63 => mask_pairs[index].0.set_data_by_arg(&mut data_array[1], mask_pairs[index].1),
				64..=95 => mask_pairs[index].0.set_data_by_arg(&mut data_array[2], mask_pairs[index].1),
				_ => panic!("Invalid DDSCFRMask!"),
			};
		}
		self.set_all_configurations(data_array.clone())
	}

	/*
	 *  Set a single tone profile
	 *  Phase: Expressed in positive degree
	 *  Frequency: Must be integer
	 *  Amplitude: In a scale from 0 to 1, taking float
	 */
	pub fn set_single_tone_profile(&mut self, profile: u8, f_out: u64, phase_offset: f64, amp_scale_factor: f64) -> Result<(), Error<E>> {

		assert!(profile < 8);
		assert!(phase_offset >= 0.0 && phase_offset < 360.0);
		assert!(amp_scale_factor >=0.0 && amp_scale_factor <= 1.0);

		let resolutions :[u64; 3] = [1 << 32, 1 << 16, 1 << 14];
		let ftw = (resolutions[0] * f_out / self.f_sys_clk) as u32;
		let pow = ((resolutions[1] as f64) * phase_offset / 360.0) as u16;
		let asf :u16 = if amp_scale_factor == 1.0 {
			0x3FFF
		} else {
			((resolutions[2] as f64) * amp_scale_factor) as u16
		};
		// Setup configuration registers before writing single tone register
		self.set_configurations(&mut [
			(DDSCFRMask::RAM_ENABLE, 0),
			(DDSCFRMask::DIGITAL_RAMP_ENABLE, 0),
			(DDSCFRMask::OSK_ENABLE, 0),
			(DDSCFRMask::PARALLEL_DATA_PORT_ENABLE, 0),
		])?;
		self.set_configurations(&mut [
			(DDSCFRMask::EN_AMP_SCALE_SINGLE_TONE_PRO,	1),
		])?;
		// Transfer single tone profile data
		self.write_register(0x0E + profile, &mut [
			((asf >> 8 ) & 0xFF) as u8,
			((asf >> 0 ) & 0xFF) as u8,
			((pow >> 8 ) & 0xFF) as u8,
			((pow >> 0 ) & 0xFF) as u8,
			((ftw >> 24) & 0xFF) as u8,
			((ftw >> 16) & 0xFF) as u8,
			((ftw >> 8 ) & 0xFF) as u8,
			((ftw >> 0 ) & 0xFF) as u8,
		])
	}


	/*
	 *  Test method for DDS.
	 *  Return the number of test failed.
	 */
	pub fn test(&mut self) -> Result<u32, Error<E>> {
		// Test configuration register by getting SDIO_IN_ONLY and LSB_FIRST.
		let mut error_count = 0;
		let mut config_checks = [
			(DDSCFRMask::SDIO_IN_ONLY, 1),
			(DDSCFRMask::LSB_FIRST, 0)
		];
		self.get_configurations(&mut config_checks)?;
		if config_checks[0].1 == 0 {
			error_count += 1;
		}
		if config_checks[1].1 == 1 {
			error_count += 1;
		}
		Ok(error_count)
	}

}

macro_rules! impl_register_io {
	($($reg_addr: expr, $reg_byte_size: expr),+) => {
		impl<SPI, E> DDS<SPI>
		where
			SPI: Transfer<u8, Error = E>
		{
			pub fn write_register(&mut self, addr: u8, bytes: &mut[u8]) -> Result<(), Error<E>> {
				match addr {
					$(
						$reg_addr => {
							assert_eq!(bytes.len(), $reg_byte_size);
							let mut arr: [u8; $reg_byte_size + 1] = [0; ($reg_byte_size + 1)];
							arr[0] = addr | WRITE_MASK;
							for i in 0..$reg_byte_size {
								arr[i+1] = bytes[i];
							}
							self.spi.transfer(&mut arr)
									.map(|_| ())
									.map_err(Error::SPI)
						},
					)*
					_ => panic!("Bad address for DDS writing.")
				}
			}

			pub fn read_register<'w>(&mut self, addr: u8, bytes: &'w mut[u8]) -> Result<&'w [u8], Error<E>> {
				match addr {
					$(
						$reg_addr => {
							assert_eq!(bytes.len(), $reg_byte_size);
							let mut arr: [u8; $reg_byte_size + 1] = [0; ($reg_byte_size + 1)];
							arr[0] = addr | READ_MASK;
							match self.spi.transfer(&mut arr).map_err(Error::SPI) {
								Ok(ret) => {
									assert_eq!(ret.len(), $reg_byte_size + 1);
									for i in 0..$reg_byte_size {
										bytes[i] = ret[i+1];
									}
									Ok(bytes)
								},
								Err(e) => Err(e),
							}
						},
					)*
					_ => panic!("Bad address for DDS reading.")
				}
			}
		}
	}
}

impl_register_io!(
	0x00,	4,
	0x01,	4,
	0x02,	4,
	0x03,	4,
	0x04,	4,
	0x07,	4,
	0x08,	2,
	0x09,	4,
	0x0A,	4,
	0x0B,	8,
	0x0C,	8,
	0x0D,	4,
	0x0E,	8,
	0x0F,	8,
	0x10,	8,
	0x11,	8,
	0x12,	8,
	0x13,	8,
	0x14,	8,
	0x15,	8
	// RAM works in other way
	// 0x16,	4
);