From 5a5b0cc7c0175bf945c04b44f1aacc504e2f26d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20J=C3=B6rdens?= Date: Thu, 28 Oct 2021 15:19:48 +0000 Subject: [PATCH] fastino: expand docs --- artiq/coredevice/fastino.py | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/artiq/coredevice/fastino.py b/artiq/coredevice/fastino.py index c60d5d1b1..193a9d9ba 100644 --- a/artiq/coredevice/fastino.py +++ b/artiq/coredevice/fastino.py @@ -200,7 +200,7 @@ class Fastino: @kernel def stage_cic_mu(self, rate_mantissa, rate_exponent, gain_exponent): - """Stage machine unit interpolator configuration. + """Stage machine unit CIC interpolator configuration. """ if rate_mantissa < 0 or rate_mantissa >= 1 << 6: raise ValueError("rate_mantissa out of bounds") @@ -215,15 +215,18 @@ class Fastino: def stage_cic(self, rate) -> TInt32: """Compute and stage interpolator configuration. - Approximates rate using 6+4 bit floating point representation, - approximates optimal interpolation gain compensation exponent to avoid - clipping. Gains for rates that are powers of two are accurately - compensated. Other rates lead to overall less than unity gain. + This method approximates the desired interpolation rate using a 10 bit + floating point representation (6 bit mantissa, 4 bit exponent) and + then determines an optimal interpolation gain compensation exponent + to avoid clipping. Gains for rates that are powers of two are accurately + compensated. Other rates lead to overall less than unity gain (but more + than 0.5 gain). - Returns the actual interpolation rate. - The actual overall interpolation gain including gain compensation is + The overall gain including gain compensation is `actual_rate**order/2**ceil(log2(actual_rate**order))` where `order = 3`. + + Returns the actual interpolation rate. """ if rate <= 0 or rate > 1 << 16: raise ValueError("rate out of bounds") @@ -248,10 +251,21 @@ class Fastino: def apply_cic(self, channel_mask): """Apply the staged interpolator configuration on the specified channels. - Channels using non-unity interpolation rate and variable data should have - continous DAC updates enabled (see :meth:`set_continuous`). + Each Fastino channel includes a fourth order (cubic) CIC interpolator with + variable rate change and variable output gain compensation (see + :meth:`stage_cic`). - This resets and settles the interpolators. There will be no output - updates for the next `order = 3` input samples. + Channels using non-unity interpolation rate should have + continous DAC updates enabled (see :meth:`set_continuous`) unless + their output is supposed to be constant. + + This method resets and settles the affected interpolators. There will be + no output updates for the next `order = 3` input samples. + Affected channels will only accept one input sample per input sample + period. This method synchronizes the input sample period to the current + frame on the affected channels. + + If application of new interpolator settings results in a change of the + overall gain, there will be a corresponding output step. """ self.write(0x27, channel_mask)