From ede98679fc4a21c760b2da5d7238c83f9f37a31b Mon Sep 17 00:00:00 2001 From: Robert Jordens Date: Wed, 14 Feb 2018 09:05:03 +0100 Subject: [PATCH] ad9910: add documentation --- artiq/coredevice/ad9910.py | 65 +++++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 4 deletions(-) diff --git a/artiq/coredevice/ad9910.py b/artiq/coredevice/ad9910.py index 4b958b97e..285ec8816 100644 --- a/artiq/coredevice/ad9910.py +++ b/artiq/coredevice/ad9910.py @@ -30,11 +30,21 @@ _AD9910_REG_RAM = 0x16 class AD9910: """ - Support for the AD9910 DDS on Urukul + AD9910 DDS channel on Urukul. - :param chip_select: Chip select configuration. + This class supports a single DDS channel and exposes the DDS, + the digital step attenuator, and the RF switch. + + :param chip_select: Chip select configuration. On Urukul this is an + encoded chip select and not "one-hot". :param cpld_device: Name of the Urukul CPLD this device is on. - :param sw_device: Name of the RF switch device. + :param sw_device: Name of the RF switch device. The RF switch is a + TTLOut channel available as the :attr:`sw` attribute of this instance. + :param pll_n: DDS PLL multiplier. The DDS sample clock is + f_ref/4*pll_n where f_ref is the reference frequency (set in the parent + Urukul CPLD instance). + :param pll_cp: DDS PLL charge pump setting. + :param pll_vco: DDS PLL VCO range selection. """ kernel_invariants = {"chip_select", "cpld", "core", "bus", "sw", "ftw_per_hz", "sysclk", "pll_n", "pll_cp", "pll_vco"} @@ -50,7 +60,9 @@ class AD9910: self.sw = dmgr.get(sw_device) assert 12 <= pll_n <= 127 self.pll_n = pll_n + assert self.cpld.refclk < 60e6 self.sysclk = self.cpld.refclk*pll_n/4 # Urukul clock fanout divider + assert self.sysclk < 1e9 self.ftw_per_hz = 1./self.sysclk*(int64(1) << 32) assert 0 <= pll_vco <= 5 vco_min, vco_max = [(370, 510), (420, 590), (500, 700), @@ -62,6 +74,11 @@ class AD9910: @kernel def write32(self, addr, data): + """Write to 32 bit register. + + :param addr: Register address + :param data: Data to be written + """ self.bus.set_xfer(self.chip_select, 8, 0) self.bus.write(addr << 24) delay_mu(-self.bus.xfer_period_mu + 8) @@ -71,6 +88,12 @@ class AD9910: @kernel def write64(self, addr, data_high, data_low): + """Write to 64 bit register. + + :param addr: Register address + :param data_high: High (MSB) 32 bits of the data + :param data_low: Low (LSB) 32 data bits + """ self.bus.set_xfer(self.chip_select, 8, 0) self.bus.write(addr << 24) t = self.bus.xfer_period_mu @@ -82,6 +105,10 @@ class AD9910: @kernel def read32(self, addr): + """Read from 32 bit register. + + :param addr: Register address + """ self.bus.set_xfer(self.chip_select, 8, 0) self.bus.write((addr | 0x80) << 24) delay_mu(-self.bus.xfer_period_mu + 8) @@ -93,13 +120,17 @@ class AD9910: @kernel def init(self): + """Initialize and configure the DDS.""" + # Set SPI mode self.write32(_AD9910_REG_CFR1, 0x00000002) - delay(100*ns) + delay(100*us) self.cpld.io_update.pulse(100*ns) + # Use the AUX DAC setting to identify and confirm presence aux_dac = self.read32(_AD9910_REG_AUX_DAC) if aux_dac & 0xff != 0x7f: raise ValueError("Urukul AD9910 AUX_DAC mismatch") delay(100*us) + # Configure PLL settings and bring up PLL self.write32(_AD9910_REG_CFR2, 0x01400020) cfr3 = (0x0807c100 | (self.pll_vco << 24) | (self.pll_cp << 19) | (self.pll_n << 1)) @@ -109,6 +140,7 @@ class AD9910: self.write32(_AD9910_REG_CFR3, cfr3) delay(100*us) self.cpld.io_update.pulse(100*ns) + # Wait for PLL lock, up to 100 ms for i in range(100): lock = urukul_sta_pll_lock(self.cpld.sta_read()) delay(1*ms) @@ -118,6 +150,15 @@ class AD9910: @kernel def set_mu(self, ftw, pow=0, asf=0x3fff): + """Set profile 0 data in machine units. + + After the SPI transfer, the shared IO update pin is pulsed to + activate the data. + + :param ftw: Frequency tuning word: 32 bit unsigned. + :param pow: Phase tuning word: 16 bit unsigned. + :param asf: Amplitude scale factor: 14 bit unsigned. + """ self.write64(_AD9910_REG_PR0, (asf << 16) | pow, ftw) self.cpld.io_update.pulse(10*ns) @@ -141,14 +182,30 @@ class AD9910: @kernel def set(self, frequency, phase=0.0, amplitude=1.0): + """Set profile 0 data in SI units. + + .. seealso:: :meth:`set_mu` + + :param ftw: Frequency in Hz + :param pow: Phase tuning word in turns + :param asf: Amplitude in units of full scale + """ self.set_mu(self.frequency_to_ftw(frequency), self.turns_to_pow(phase), self.amplitude_to_asf(amplitude)) @kernel def set_att_mu(self, att): + """Set digital step attenuator in machine units. + + :param att: Attenuation setting, 8 bit digital. + """ self.cpld.set_att_mu(self.chip_select - 4, att) @kernel def set_att(self, att): + """Set digital step attenuator in SI units. + + :param att: Attenuation in dB. + """ self.cpld.set_att(self.chip_select - 4, att)