205: pll: refine gains r=jordens a=jordens

this decouples frequency and phase gain

Co-authored-by: Robert Jördens <rj@quartiq.de>
This commit is contained in:
bors[bot] 2020-12-15 11:19:34 +00:00 committed by GitHub
commit a71f790574
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 18 deletions

View File

@ -10,12 +10,14 @@ use serde::{Deserialize, Serialize};
/// stable for any gain (1 <= shift <= 30). It has a single parameter that determines the loop
/// bandwidth in octave steps. The gain can be changed freely between updates.
///
/// The frequency and phase settling time constants for an (any) frequency jump are `1 << shift`
/// The frequency and phase settling time constants for a frequency/phase jump are `1 << shift`
/// update cycles. The loop bandwidth is about `1/(2*pi*(1 << shift))` in units of the sample rate.
/// While the phase is being settled within one turn, there is a typically very small frequency
/// overshoot.
///
/// All math is naturally wrapping 32 bit integer. Phase and frequency are understood modulo that
/// overflow in the first Nyquist zone. Expressing the IIR equations in other ways (e.g. single
/// (T)-DF-{I,II} biquad/IIR) would break on overflow.
/// (T)-DF-{I,II} biquad/IIR) would break on overflow (i.e. every cycle).
///
/// There are no floating point rounding errors here. But there is integer quantization/truncation
/// error of the `shift` lowest bits leading to a phase offset for very low gains. Truncation
@ -23,8 +25,8 @@ use serde::{Deserialize, Serialize};
/// efficiently by dithering.
///
/// This PLL does not unwrap phase slips during lock acquisition. This can and should be
/// implemented elsewhere by (down) scaling and then unwrapping the input phase and (up) scaling
/// and wrapping output phase and frequency. This affects dynamic range accordingly.
/// implemented elsewhere by unwrapping and scaling the input phase and un-scaling
/// and wrapping output phase and frequency. This affects dynamic range, gain, and noise accordingly.
///
/// The extension to I^3,I^2,I behavior to track chirps phase-accurately or to i64 data to
/// increase resolution for extremely narrowband applications is obvious.
@ -39,25 +41,39 @@ pub struct PLL {
}
impl PLL {
/// Update the PLL with a new phase sample.
/// Update the PLL with a new phase sample. This needs to be called (sampled) periodically.
/// The signal's phase/frequency is reconstructed relative to the sampling period.
///
/// Args:
/// * `input`: New input phase sample.
/// * `shift`: Error scaling. The frequency gain per update is `1/(1 << shift)`. The phase gain
/// is always twice the frequency gain.
/// * `shift_frequency`: Frequency error scaling. The frequency gain per update is
/// `1/(1 << shift_frequency)`.
/// * `shift_phase`: Phase error scaling. The phase gain is `1/(1 << shift_phase)`
/// per update. A good value is typically `shift_frequency - 1`.
///
/// Returns:
/// A tuple of instantaneous phase and frequency (the current phase increment).
pub fn update(&mut self, x: i32, shift: u8) -> (i32, i32) {
debug_assert!((1..=30).contains(&shift));
let bias = 1i32 << shift;
pub fn update(
&mut self,
x: i32,
shift_frequency: u8,
shift_phase: u8,
) -> (i32, i32) {
debug_assert!((1..=30).contains(&shift_frequency));
debug_assert!((1..=30).contains(&shift_phase));
let e = x.wrapping_sub(self.f);
self.f = self.f.wrapping_add(
(bias >> 1).wrapping_add(e).wrapping_sub(self.x) >> shift,
(1i32 << (shift_frequency - 1))
.wrapping_add(e)
.wrapping_sub(self.x)
>> shift_frequency,
);
self.x = x;
let f = self.f.wrapping_add(
bias.wrapping_add(e).wrapping_sub(self.y) >> (shift - 1),
(1i32 << (shift_phase - 1))
.wrapping_add(e)
.wrapping_sub(self.y)
>> shift_phase,
);
self.y = self.y.wrapping_add(f);
(self.y, f)
@ -70,8 +86,8 @@ mod tests {
#[test]
fn mini() {
let mut p = PLL::default();
let (y, f) = p.update(0x10000, 10);
assert_eq!(y, 0xc2);
let (y, f) = p.update(0x10000, 8, 4);
assert_eq!(y, 0x1100);
assert_eq!(f, y);
}
@ -79,17 +95,17 @@ mod tests {
fn converge() {
let mut p = PLL::default();
let f0 = 0x71f63049_i32;
let shift = 10;
let n = 31 << shift + 2;
let shift = (10, 9);
let n = 31 << shift.0 + 2;
let mut x = 0i32;
for i in 0..n {
x = x.wrapping_add(f0);
let (y, f) = p.update(x, shift);
let (y, f) = p.update(x, shift.0, shift.1);
if i > n / 4 {
assert_eq!(f.wrapping_sub(f0).abs() <= 1, true);
}
if i > n / 2 {
// The remaining error is removed by dithering.
// The remaining error would be removed by dithering.
assert_eq!(y.wrapping_sub(x).abs() < 1 << 18, true);
}
}