USB Audio Devices

    FLASH DRIVE    a command can FAIL      -> report it, host retries
    WEBCAM         a packet can be LOST    -> nothing to do, drop the frame
    AUDIO DEVICE   nothing fails or is lost -> and the buffer still empties

    SYNCHRONOUS   the device slaves its sample clock to the USB SOF.
                  Hardware: a PLL locked to a 1 kHz reference.
                  Cost: that PLL, and the jitter the bus gives you.

    ADAPTIVE      the device measures how many samples actually arrive and
                  retunes its own rate to match.
                  Hardware: a rate estimator and a tunable clock.
                  Cost: the device is chasing the host, always behind.

    ASYNCHRONOUS  the device keeps its own free-running crystal and TELLS THE
                  HOST what rate it wants. The host adjusts.
                  Hardware: a counter and a subtractor.
                  Cost: the host has to be willing to listen.

    48.000 samples/frame  =  48 * 16384  =  786,432
    48.250 samples/frame  =  790,528     =  786,432 + 4,096
    47.750 samples/frame  =  782,336     =  786,432 - 4,096

    one LSB               =  1/16384 sample/frame
                          =  1/786432 of the nominal rate
                          =  1.27 ppm

// =====================================================================
//  uac_feedback -- the control loop that keeps a USB audio device from
//  running out of samples, or drowning in them.
//
//  CLASSIFICATION: simplified synthesisable teaching RTL.
//  This is NOT an audio device. There is no DAC, no volume control, no
//  format negotiation and no mixer. It is the feedback endpoint: the one
//  number an asynchronous audio device sends back every frame, and the
//  arithmetic that decides what that number should be.
//
//  WHY THIS MECHANISM IS WORTH RTL
//  -------------------------------
//  A USB audio device runs on ITS OWN crystal. The host runs on its own.
//  Neither is wrong and neither can be adjusted to match the other, so
//  the device's idea of 48,000 samples per second and the host's differ
//  -- by a few parts per million, forever, in whichever direction the two
//  crystals happen to disagree.
//
//  A few parts per million sounds harmless. It is not, because the error
//  ACCUMULATES into a buffer:
//
//      100 ppm at 48 kHz = 4.8 samples per second
//                        = 288 samples per minute
//                        = a buffer of 288 samples emptied, or overflowed,
//                          every single minute, forever
//
//  There is no retry that fixes this and no error to report. The device
//  will run out of samples to play, and the listener hears a click. Then
//  it happens again a minute later.
//
//  SO USB AUDIO PUTS THE DEVICE IN CHARGE OF THE RATE.
//
//  An ASYNCHRONOUS audio device reports, once per frame on a dedicated
//  feedback endpoint, how many samples per frame it actually wants -- as
//  a fixed-point number, because the true answer is virtually never an
//  integer. At full speed the format is 10.14: ten integer bits and
//  fourteen fractional, so 48.000 samples/frame is 48 << 14.
//
//  The host accumulates that fractional value and sends floor() of it,
//  carrying the remainder into the next frame. Over many frames the
//  average rate the host sends matches the rate the device consumes, to
//  a precision of one part in 16384 of a sample.
//
//  This module is the device half: watch the buffer, and ask for what
//  will bring it back to where it should be.
// =====================================================================
module uac_feedback #(
  // Nominal samples per USB frame. 48 at 48 kHz with 1 ms frames.
  parameter integer NOM_SAMPLES = 48,
  // Buffer depth in samples. Real devices use a few milliseconds' worth;
  // the number only has to be big enough that the loop has room to work.
  parameter integer BUF_DEPTH   = 192
) (
  input  wire        clk,
  input  wire        rst_n,

  // One pulse per USB frame. Everything in this module happens once per
  // frame, because that is how often the host will look.
  input  wire        sof,

  // How many samples the host actually delivered this frame, and how many
  // the device's own clock consumed. These differ, and their difference
  // is the entire problem.
  input  wire [15:0] host_samples,
  input  wire [15:0] dev_consumed,

  // How aggressively to correct. The feedback correction is
  // (target - level) >> gain_shift, in whole samples per frame, so a
  // LARGER shift is a GENTLER loop.
  input  wire [3:0]  gain_shift,

  // ---- the feedback value, 10.14 fixed point ----
  //
  // This is the only thing the host ever sees from this module, and the
  // host will do exactly what it says.
  output wire [23:0] fb_value,

  output wire [15:0] buf_level,
  output wire        underrun,
  output wire        overrun,

  output wire [31:0] n_frames,
  output wire [31:0] n_underrun,
  output wire [31:0] n_overrun,
  output wire [31:0] n_clamped
);

  // 48 samples/frame in 10.14 is 48 * 16384.
  localparam [23:0] NOM_Q14 = NOM_SAMPLES * 16384;
  // The level the loop steers towards: half full, so it has equal room to
  // absorb an error in either direction.
  localparam [15:0] TARGET  = BUF_DEPTH / 2;

  // The specification bounds how far the reported rate may deviate from
  // nominal. A device that asked for wildly the wrong rate would be
  // indistinguishable from a broken one, and a host is entitled to stop
  // believing it. One sample per frame is the limit used here.
  localparam [23:0] FB_MAX = NOM_Q14 + 16384;
  localparam [23:0] FB_MIN = NOM_Q14 - 16384;

  reg [15:0] level;
  reg [23:0] fb_r;
  reg        under_r, over_r;
  reg [31:0] frame_c, under_c, over_c, clamp_c;

  assign buf_level  = level;
  assign fb_value   = fb_r;
  assign underrun   = under_r;
  assign overrun    = over_r;
  assign n_frames   = frame_c;
  assign n_underrun = under_c;
  assign n_overrun  = over_c;
  assign n_clamped  = clamp_c;

  // ---- the new level, before clamping ----
  //
  // Signed, because the device can consume more than arrived. Computed
  // combinationally so the clamp and the counters see one consistent
  // value rather than each recomputing it.
  wire signed [17:0] lvl_next = $signed({2'b00, level})
                              + $signed({2'b00, host_samples})
                              - $signed({2'b00, dev_consumed});

  wire hit_under = (lvl_next <= 0);
  wire hit_over  = (lvl_next >= $signed(BUF_DEPTH));

  wire [15:0] lvl_clamped = hit_under ? 16'd0 :
                            hit_over  ? BUF_DEPTH[15:0]
                                      : lvl_next[15:0];

  // ---- the correction ----
  //
  // Proportional only. An integral term would drive the steady-state
  // error to zero, and it would also wind up during the many frames where
  // the level is pinned at a clamp -- which is exactly when the error is
  // largest and the loop can do nothing about it. The chapter measures
  // what the proportional loop alone achieves.
  wire signed [17:0] err = $signed({2'b00, TARGET}) - $signed({2'b00, lvl_clamped});

  // err is in samples. Scaling it into 10.14 and then down by gain_shift
  // gives a correction of (err >> gain_shift) samples per frame.
  //
  // WHY A CONCATENATION AND NOT `err <<< 14`.
  //
  // The obvious way to write this is
  //
  //     wire signed [24:0] corr = ($signed({{7{err[17]}}, err}) <<< 14) >>> gain_shift;
  //
  // and it works, but not for the reason it appears to. A sign extension
  // placed before a LEFT shift is dead code at any width: the shift
  // discards exactly the bits the extension supplies. Here the seven
  // extension bits sit at bits 24:18 and the shift would move them to
  // 38:32, which do not exist. Bits 24:14 of the result come from
  // err[10:0] and from nothing else.
  //
  // The arithmetic is then correct only because eleven bits happens to be
  // enough for an error in [-96, +96]. The error spans +/- BUF_DEPTH/2 and
  // eleven signed bits hold [-1024, +1023], so the coincidence survives up
  // to BUF_DEPTH = 2046 and breaks at 2048: from there the top bits are
  // silently lost and the loop starts correcting in the WRONG DIRECTION
  // near the rails -- with no warning from any tool, because nothing is
  // out of range and nothing overflows.
  //
  // Written as a concatenation the width is STATED: {err, 14'b0} is
  // exactly 32 bits, err[17] lands on bit 31, and $signed makes the
  // following shift arithmetic. Nothing is extended and nothing is
  // discarded.
  wire signed [31:0] err_q14 = $signed({err, 14'b0});
  wire signed [31:0] corr    = err_q14 >>> gain_shift;

  // Also 32 bits, and for the same reason: corr is 32 bits and adding it
  // into anything narrower would truncate it silently. The sum cannot
  // overflow 32 bits, and now that is true by construction rather than by
  // a count of how large the correction happens to get.
  wire signed [31:0] fb_raw = $signed({8'b0, NOM_Q14}) + corr;

  wire fb_hi = (fb_raw > $signed({8'b0, FB_MAX}));
  wire fb_lo = (fb_raw < $signed({8'b0, FB_MIN}));

  wire [23:0] fb_next = fb_hi ? FB_MAX :
                        fb_lo ? FB_MIN : fb_raw[23:0];

  always @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      level   <= TARGET;          // start where the loop wants to be
      fb_r    <= NOM_Q14;
      under_r <= 1'b0;
      over_r  <= 1'b0;
      frame_c <= 32'd0;
      under_c <= 32'd0;
      over_c  <= 32'd0;
      clamp_c <= 32'd0;
    end else begin
      under_r <= 1'b0;
      over_r  <= 1'b0;

      if (sof) begin
        frame_c <= frame_c + 32'd1;
        level   <= lvl_clamped;
        fb_r    <= fb_next;

        // An underrun is not "the buffer got low". It is "the device
        // needed a sample that was not there", which is a click the
        // listener hears -- so it is counted separately from the loop
        // simply working hard.
        if (hit_under) begin
          under_r <= 1'b1;
          under_c <= under_c + 32'd1;
        end
        if (hit_over) begin
          over_r <= 1'b1;
          over_c <= over_c + 32'd1;
        end
        // How often the loop wanted to ask for more than it is allowed
        // to. A loop that is permanently clamped is not controlling
        // anything, and this counter is how that becomes visible.
        if (fb_hi || fb_lo) clamp_c <= clamp_c + 32'd1;
      end
    end
  end

endmodule

  wire signed [17:0] err  = $signed({2'b00, TARGET}) - $signed({2'b00, lvl_clamped});
  wire signed [24:0] corr = ($signed({{7{err[17]}}, err}) <<< 14) >>> gain_shift;

    MUT       V-ALL     V-DIR
    BASE          0         0
    R3            0         0        <-- a sign extension removed, and no failure

    corr is 25 bits.  err is 18.  The extension supplies bits 24:18.

        { ext[6:0] , err[17:0] }        <<< 14
          ^^^^^^^^
          bits 24:18                    would land at bits 38:32

    Bits 24:14 of the result come from err[10:0].  And from nothing else.

    err >= 0 :  err[10:0] << 14  =  err * 16384                  correct
    err <  0 :  err[10:0] << 14  =  2^25 + err * 16384
                read back as signed 25-bit  =  err * 16384       correct

  wire signed [31:0] err_q14 = $signed({err, 14'b0});
  wire signed [31:0] corr    = err_q14 >>> gain_shift;

    THE BENCH AS HOST      accumulate the reported 10.14 rate,
                           send floor() of it, carry the remainder

    THE BENCH AS CRYSTAL   accumulate its OWN true rate, consume
                           floor() of it, carry the remainder

    THE GAP BETWEEN THEM   is what the design has to discover

// =====================================================================
//  Testbench for uac_feedback.
//
//  THE BENCH IS BOTH CLOCKS.
//
//  It plays the host -- accumulating the feedback value in 10.14 and
//  sending floor() of it, carrying the remainder -- and it plays the
//  device's crystal, consuming at a rate that deliberately is NOT the
//  nominal one. The gap between those two is the whole problem the
//  feedback endpoint exists to solve.
//
//  THE MODEL USES MULTIPLICATION WHERE THE DESIGN USES SHIFTS.
//  The design computes its correction as (err << 14) >>> gain_shift. The
//  model computes err * (16384 >> gain_shift). Same number, different
//  derivation -- so a sign-extension or rounding mistake in one cannot be
//  reproduced by the other.
//
//  THE HEADLINE is not a pass/fail. It is: how far does the buffer
//  actually drift before the loop catches it, as a function of how hard
//  the loop pulls?
// =====================================================================
`timescale 1ns/1ps
module tb_fb_v;

  localparam integer NOM_SAMPLES = 48;
  localparam integer BUF_DEPTH   = 192;
  localparam integer TARGET      = BUF_DEPTH / 2;
  localparam integer NOM_Q14     = NOM_SAMPLES * 16384;
  localparam integer FB_MAX      = NOM_Q14 + 16384;
  localparam integer FB_MIN      = NOM_Q14 - 16384;

  reg clk = 1'b0, rst_n = 1'b0;
  always #5 clk = ~clk;

  reg         sof = 1'b0;
  reg  [15:0] host_samples = 16'd0, dev_consumed = 16'd0;
  reg  [3:0]  gain_shift = 4'd4;

  wire [23:0] fb_value;
  wire [15:0] buf_level;
  wire        underrun, overrun;
  wire [31:0] n_frames, n_underrun, n_overrun, n_clamped;

  uac_feedback #(.NOM_SAMPLES(NOM_SAMPLES), .BUF_DEPTH(BUF_DEPTH)) dut (
    .clk(clk), .rst_n(rst_n), .sof(sof),
    .host_samples(host_samples), .dev_consumed(dev_consumed),
    .gain_shift(gain_shift),
    .fb_value(fb_value), .buf_level(buf_level),
    .underrun(underrun), .overrun(overrun),
    .n_frames(n_frames), .n_underrun(n_underrun),
    .n_overrun(n_overrun), .n_clamped(n_clamped)
  );

  integer errors = 0, checks = 0, steps = 0;
  integer seed;

  // ---- cumulative across resets ----
  //
  // reset_dut runs once per configuration, so the DUT's own counters
  // describe only the last one.
  integer c_frames = 0, c_under = 0, c_over = 0, c_clamp = 0;

  // ---- per-reset tally, maintained from the MODEL ----
  //
  // The DUT's four counters do not affect its behaviour, which is exactly
  // why nothing else in the bench would notice if they were wrong -- and
  // they are what a bring-up engineer will trust when the audio clicks and
  // no other evidence exists. These are kept from the model's own
  // formulation of each condition, never from the DUT's outputs.
  integer t_frames, t_under, t_over, t_clamp;

  // $random is SIGNED: mask the sign bit before any modulo.
  function [31:0] urand;
    input dummy;
    begin urand = $random(seed) & 32'h3FFF_FFFF; end
  endfunction

  task ck(input cond, input [255:0] what);
    begin
      checks = checks + 1;
      if (!cond) begin
        errors = errors + 1;
        if (errors <= 20)
          $display("  ERROR @%0t step#%0d: %0s", $time, steps, what);
      end
    end
  endtask

  // ---- the model, formulated differently from the design ----
  integer m_level;

  // The design shifts; the model multiplies. err * (16384 >> shift) is
  // the same correction as (err << 14) >>> shift, arrived at from the
  // other side.
  function integer model_fb(input integer lvl, input integer shift);
    integer err, corr, raw;
    begin
      err  = TARGET - lvl;
      corr = err * (16384 >> shift);
      raw  = NOM_Q14 + corr;
      if      (raw > FB_MAX) model_fb = FB_MAX;
      else if (raw < FB_MIN) model_fb = FB_MIN;
      else                   model_fb = raw;
    end
  endfunction

  function integer clamp_level(input integer lvl);
    begin
      if      (lvl <= 0)         clamp_level = 0;
      else if (lvl >= BUF_DEPTH) clamp_level = BUF_DEPTH;
      else                       clamp_level = lvl;
    end
  endfunction

  // ---- what the design said, sampled at a DEFINED instant ----
  integer obs_level, obs_fb, obs_under, obs_over;

  // ---- the measurement ----
  integer tab_off  [0:4];
  integer tab_gain [0:3];
  integer tab_max  [0:4][0:3];   // worst excursion from target
  integer tab_bad  [0:4][0:3];   // under + overruns

  task reset_dut;
    begin
      rst_n = 1'b0; sof = 1'b0;
      host_samples = 16'd0; dev_consumed = 16'd0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
      m_level = TARGET;
      t_frames = 0; t_under = 0; t_over = 0; t_clamp = 0;
    end
  endtask

  // ---- PROPERTY 8: the four counters agree with an independent tally ----
  //
  // Called once per frame in the phases where the counted events actually
  // happen. Elsewhere no event occurs and the check would be trivially
  // true, which is worse than not making it: it would inflate the count
  // without testing anything.
  task chk_counters;
    begin
      ck(n_frames   == t_frames, "n_frames did not count every frame");
      ck(n_underrun == t_under,  "n_underrun disagrees with the tally");
      ck(n_overrun  == t_over,   "n_overrun disagrees with the tally");
      ck(n_clamped  == t_clamp,  "n_clamped disagrees with the tally");
    end
  endtask

  // One USB frame: the host delivers, the device consumes, the loop
  // reports a new rate.
  task one_frame(input integer send, input integer consume);
    integer e_level, e_fb;
    begin
      e_level = clamp_level(m_level + send - consume);
      e_fb    = model_fb(e_level, gain_shift);

      sof = 1'b1; host_samples = send[15:0]; dev_consumed = consume[15:0];
      @(posedge clk); #1;
      sof = 1'b0;
      obs_level = buf_level;
      obs_fb    = fb_value;
      obs_under = underrun;
      obs_over  = overrun;

      // ---- PROPERTY 1: the buffer level is exact ----
      //
      // Not approximately right. The level is the state the whole loop is
      // built on, and a level that drifted from the truth would make every
      // feedback value wrong in a way that looked like a tuning problem.
      ck(obs_level == e_level, "the buffer level disagrees with the model");
      // ---- PROPERTY 2: the feedback value is exact ----
      ck(obs_fb == e_fb, "the feedback value disagrees with the model");
      // ---- PROPERTY 3: the reported rate stays inside the legal band ----
      //
      // A device that asked for wildly the wrong rate is indistinguishable
      // from a broken one, and a host is entitled to stop believing it.
      ck(obs_fb <= FB_MAX && obs_fb >= FB_MIN,
         "the feedback value left the legal band");
      // ---- PROPERTY 4: underrun means the device ran dry ----
      //
      // Not "the buffer got low". A click the listener hears, which is why
      // it is flagged separately from the loop merely working hard.
      ck(obs_under == ((m_level + send - consume) <= 0 ? 1 : 0),
         "underrun does not mean the device ran out of samples");
      ck(obs_over == ((m_level + send - consume) >= BUF_DEPTH ? 1 : 0),
         "overrun does not mean the buffer filled");

      // the tally, from the model -- note it uses m_level BEFORE the
      // assignment below, which is the level the frame started from
      t_frames = t_frames + 1;
      if ((m_level + send - consume) <= 0)         t_under = t_under + 1;
      if ((m_level + send - consume) >= BUF_DEPTH) t_over  = t_over + 1;
      begin : tally_clamp
        integer raw;
        raw = NOM_Q14 + (TARGET - e_level) * (16384 >> gain_shift);
        if (raw > FB_MAX || raw < FB_MIN) t_clamp = t_clamp + 1;
      end

      m_level = e_level;
      c_frames = c_frames + 1;
      if (obs_under) c_under = c_under + 1;
      if (obs_over)  c_over  = c_over + 1;
      if (obs_fb == FB_MAX || obs_fb == FB_MIN) c_clamp = c_clamp + 1;
      steps = steps + 1;
    end
  endtask

  // -------------------------------------------------------------------
  //  Run the loop for `nframes` frames with the device's crystal running
  //  `off_q14` away from nominal, and report the worst excursion.
  //
  //  The host does exactly what a real host does: accumulate the reported
  //  10.14 rate, send floor() of it, carry the remainder. The device does
  //  the same with its own true rate. Neither ever sends a fractional
  //  sample, and the fractions are what make the average come out right.
  // -------------------------------------------------------------------
  task run_loop(input integer off_q14, input integer shift,
                input integer init_level, input integer nframes,
                output integer max_dev, output integer bad,
                output integer settled_dev);
    integer hacc, dacc, send, consume, f, dev;
    begin
      reset_dut;
      gain_shift = shift[3:0];

      // Place the buffer at its starting level: one frame in which the
      // host delivers `init_level` and the device consumes exactly the
      // reset level, which leaves the level at init_level.
      one_frame(init_level, TARGET);

      hacc = 0; dacc = 0;
      max_dev = 0; bad = 0; settled_dev = 0;
      dev = NOM_Q14 + off_q14;

      for (f = 0; f < nframes; f = f + 1) begin
        // the host: accumulate what the device asked for, send floor()
        hacc    = hacc + fb_value;
        send    = hacc >> 14;
        hacc    = hacc - (send << 14);
        // the device's own crystal, doing the same with its true rate
        dacc    = dacc + dev;
        consume = dacc >> 14;
        dacc    = dacc - (consume << 14);

        one_frame(send, consume);

        if ((m_level - TARGET) > max_dev)  max_dev = m_level - TARGET;
        if ((TARGET - m_level) > max_dev)  max_dev = TARGET - m_level;
        // The SETTLED excursion, over the last quarter of the run only.
        // max_dev includes the transient from wherever the buffer
        // started, which is an initial condition rather than a property
        // of the loop; this is the steady state.
        if (f >= (nframes * 3) / 4) begin
          if ((m_level - TARGET) > settled_dev) settled_dev = m_level - TARGET;
          if ((TARGET - m_level) > settled_dev) settled_dev = TARGET - m_level;
        end
        if (obs_under || obs_over) bad = bad + 1;
      end
    end
  endtask

  // ---- exhaustive reach ----
  //
  // 5 crystal offsets x 4 loop gains x 3 starting levels = 60. Every
  // dimension is an independent input with no forbidden combinations.
  reg reach [0:59];
  integer nr, ri;

  integer oi, gi, ii, k, mx, bd, sd;
  integer OFF  [0:4];
  integer GAIN [0:3];
  integer INIT [0:2];

  initial begin
    for (ri = 0; ri < 60; ri = ri + 1) reach[ri] = 1'b0;
    // Crystal error in 10.14 samples per frame. 4096 is a quarter of a
    // sample per frame -- about 5200 ppm, far beyond any real crystal, and
    // included so the sweep spans the whole transition rather than
    // stopping at the first configuration that copes. 256 is about 325 ppm,
    // which is the order of a cheap part.
    OFF[0] = -4096; OFF[1] = -256; OFF[2] = 0; OFF[3] = 256; OFF[4] = 4096;
    // Larger shift is a GENTLER loop.
    GAIN[0] = 3; GAIN[1] = 4; GAIN[2] = 5; GAIN[3] = 6;
    INIT[0] = 16; INIT[1] = TARGET; INIT[2] = BUF_DEPTH - 16;
    seed = 32'd29003;

    reset_dut;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- the whole configuration space.
    // =============================================================
    for (oi = 0; oi < 5; oi = oi + 1)
    for (gi = 0; gi < 4; gi = gi + 1)
    for (ii = 0; ii < 3; ii = ii + 1) begin
      // 1200 frames, not 400.
      //
      // A proportional loop's settling time scales with its gain: a
      // shift of 6 has a time constant four times longer than a shift of
      // 4, and from 80 samples away it needs several hundred frames just
      // for the transient. At 400 frames the last quarter still contained
      // one sample of it, and the closed-form check failed by exactly one
      // -- six times, all at the gentlest gain.
      //
      // The measurement window was adequate for an aggressive loop and
      // not for a gentle one. That is a property of the loop, and the
      // right response is to give every configuration enough time rather
      // than to loosen the property.
      run_loop(OFF[oi], GAIN[gi], INIT[ii], 1200, mx, bd, sd);
      ri = (oi * 4 + gi) * 3 + ii;
      reach[ri] = 1'b1;

      // ---- PROPERTY 5: the steady-state excursion is a CLOSED FORM ----
      //
      //   excursion = crystal error (samples/frame) x 2^gain_shift
      //
      // which in 10.14 units is |off| << shift >> 14, floored at one
      // sample because the buffer is counted in whole samples and any
      // non-zero error eventually moves it by one.
      //
      // This is the chapter's result, and asserting it is what turns the
      // table below from an observation into a measurement. A loop whose
      // gain did not do what the arithmetic says would still produce a
      // plausible-looking table.
      begin : closedform
        integer e_exc, a;
        a = (OFF[oi] < 0) ? -OFF[oi] : OFF[oi];
        e_exc = (a == 0) ? 0 : (((a << GAIN[gi]) >> 14) < 1 ? 1 : ((a << GAIN[gi]) >> 14));
        // Asserted against the settled value, not the peak. The peak
        // includes the transient from wherever the buffer happened to
        // start, which is an initial condition and not a property of the
        // loop -- asserting the closed form against the peak failed 40
        // times for exactly that reason.
        //
        // Stating it for EVERY starting level is also the convergence
        // property: wherever the buffer began, the loop brings it to the
        // same steady state.
        ck(sd == e_exc,
           "the settled excursion does not match error x 2^gain");
      end
      // record the middle starting level for the headline table, so the
      // table measures the loop rather than the initial condition
      if (ii == 1) begin
        tab_off[oi]      = OFF[oi];
        tab_gain[gi]     = GAIN[gi];
        tab_max[oi][gi]  = sd;
        tab_bad[oi][gi]  = bd;
      end
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- a matched crystal must not move at all.
    //
    //  With zero offset and the buffer starting exactly on target, the
    //  loop has nothing to correct. If it moves anyway, the loop is
    //  injecting the very error it exists to remove -- and every other
    //  measurement in this chapter would be contaminated by it.
    // =============================================================
    run_loop(0, 4, TARGET, 400, mx, bd, sd);
    ck(mx == 0, "the loop moved the buffer with a perfectly matched crystal");
    ck(bd == 0, "a matched crystal produced an underrun or overrun");
    ck(fb_value == NOM_Q14,
       "a matched crystal did not settle at exactly the nominal rate");

    // =============================================================
    //  PHASE 3 (DIRECTED) -- the loop pulls the RIGHT WAY.
    //
    //  Sign errors in a control loop are not subtle in their effect and
    //  are very subtle in the code. A loop wired backwards drives the
    //  buffer to a rail and holds it there, and every symptom points at
    //  the crystal rather than at the sign.
    // =============================================================
    reset_dut;
    gain_shift = 4'd4;
    one_frame(16, TARGET);                 // start well BELOW target
    ck(fb_value > NOM_Q14,
       "with the buffer low the device did not ask for MORE samples");
    reset_dut;
    one_frame(BUF_DEPTH - 16, TARGET);     // start well ABOVE target
    ck(fb_value < NOM_Q14,
       "with the buffer high the device did not ask for FEWER samples");

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE) -- the legal band is respected.
    //
    //  Every starting level from empty to full, at the most aggressive
    //  gain, so the correction the loop WANTS is as large as it can be.
    //  The reported rate must still never leave the band.
    // =============================================================
    for (k = 0; k <= BUF_DEPTH; k = k + 8) begin
      reset_dut;
      gain_shift = 4'd3;
      one_frame(k, TARGET);
      ck(fb_value <= FB_MAX && fb_value >= FB_MIN,
         "an extreme buffer level pushed the reported rate out of band");
    end

    // =============================================================
    //  PHASE 5 (DIRECTED) -- the bus goes quiet, and then it floods.
    //
    //  Every phase above keeps the buffer near the middle, which means
    //  the two clamps in the design are never actually exercised: the
    //  sweep touches the rails EXACTLY, never past them, and a clamp
    //  that fires exactly at its own bound returns the value it was
    //  given. A wrong clamp would have been inert in every phase so far.
    //
    //  A real device does go past the rails. The host loses its
    //  bandwidth reservation, or the bus is suspended, and nothing
    //  arrives for several frames while the device keeps consuming. That
    //  is the underrun the listener hears, and it is the one condition
    //  where the loop can do nothing except ask for the most it is
    //  allowed to and wait.
    //
    //  This phase also checks the DUT's four counters against a tally
    //  kept here, which is the only place in the bench where they are
    //  verified rather than merely printed.
    // =============================================================
    reset_dut;
    gain_shift = 4'd4;
    begin : rails
      integer f2;

      // ---- nothing arrives, the device keeps consuming ----
      for (f2 = 0; f2 < 20; f2 = f2 + 1) begin
        one_frame(0, NOM_SAMPLES);
        // ---- PROPERTY 6: the level never leaves the buffer ----
        //
        // A level below zero or above the depth is not a small error. It
        // is a read or write outside the ring buffer.
        ck(obs_level <= BUF_DEPTH, "the level rose above the buffer depth");
        // Checked every frame, not once at the end: a counter that is
        // right at the end of a phase and wrong in the middle of it is
        // still a counter that cannot be trusted.
        chk_counters;
      end
      ck(obs_level == 0, "twenty frames of silence did not empty the buffer");
      // ---- PROPERTY 7: at the rail the device asks for the most it may --
      //
      // It cannot ask for enough to refill instantly -- the band forbids
      // that -- so the correct behaviour is to sit at the limit until the
      // buffer recovers, which is what makes recovery gradual and audible
      // as a single click rather than a burst of them.
      ck(fb_value == FB_MAX,
         "an empty buffer did not make the device ask for the maximum rate");

      // ---- the host over-delivers: twice nominal, nothing consumed ----
      for (f2 = 0; f2 < 20; f2 = f2 + 1) begin
        one_frame(2 * NOM_SAMPLES, 0);
        ck(obs_level <= BUF_DEPTH, "the level rose above the buffer depth");
        chk_counters;
      end
      ck(obs_level == BUF_DEPTH, "twenty frames of flood did not fill the buffer");
      ck(fb_value == FB_MIN,
         "a full buffer did not make the device ask for the minimum rate");

      ck(n_frames == 40, "forty frames were played and not forty counted");
    end

    // =============================================================
    //  PHASE 6 (DIRECTED, EXHAUSTIVE) -- the two boundaries, reached
    //  five different ways.
    //
    //  `underrun` is defined on lvl_next <= 0 and `overrun` on
    //  lvl_next >= BUF_DEPTH. Both bounds are INCLUSIVE, and an inclusive
    //  bound differs from an exclusive one at exactly one point: the
    //  bound itself. A sweep cannot widen that domain, because the domain
    //  is one value.
    //
    //  What can be widened is the number of ways the bench arrives there,
    //  and the number of consequences it checks once it has. The boundary
    //  must hold however the level got to it, so the level is placed at
    //  five different starting points and driven to each of
    //  {-2,-1,0,+1,+2} around both bounds from each one.
    // =============================================================
    begin : bounds
      integer li, dd;
      integer LV [0:4];
      LV[0] = 24; LV[1] = 48; LV[2] = TARGET; LV[3] = 144; LV[4] = 168;
      for (li = 0; li < 5; li = li + 1)
      for (dd = -2; dd <= 2; dd = dd + 1) begin
        // ---- the EMPTY bound: drive lvl_next to exactly dd ----
        reset_dut;
        gain_shift = 4'd4;
        one_frame(LV[li], TARGET);            // place the level at LV[li]
        one_frame(0, LV[li] - dd);            // lvl_next = dd
        chk_counters;
        // ---- the FULL bound: drive lvl_next to exactly BUF_DEPTH+dd ----
        reset_dut;
        gain_shift = 4'd4;
        one_frame(LV[li], TARGET);
        one_frame(BUF_DEPTH + dd - LV[li], 0);
        chk_counters;
      end
    end

    // =============================================================
    //  PHASE 7 (RANDOM) -- a jittery host.
    //
    //  A real host does not deliver exactly what it was asked for every
    //  frame: scheduling, other devices and its own rounding all
    //  interfere. The loop has to survive that without the buffer
    //  wandering off.
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_dut;
    gain_shift = 4'd4;
    one_frame(TARGET, TARGET);
    for (k = 0; k < 600; k = k + 1) begin : jitter
      integer s, c;
      s = (fb_value >> 14) + (urand(0) % 3) - 1;   // host is +/-1 sample out
      c = NOM_SAMPLES + (urand(0) % 3) - 1;        // device jitters too
      if (s < 0) s = 0;
      if (c < 0) c = 0;
      one_frame(s, c);
    end
`endif

    nr = 0; for (ri = 0; ri < 60; ri = ri + 1) if (reach[ri]) nr = nr + 1;

    $display("steps=%0d checks=%0d reach=%0d/60 errors=%0d",
             steps, checks, nr, errors);
    $display("[uac] frames=%0d underruns=%0d overruns=%0d rate_clamped=%0d",
             c_frames, c_under, c_over, c_clamp);
    $display("--- worst buffer excursion from target, in samples ---");
    $display("    crystal err    gain>>3   gain>>4   gain>>5   gain>>6");
    for (oi = 0; oi < 5; oi = oi + 1)
      $display("    %11d %9d %9d %9d %9d", tab_off[oi],
               tab_max[oi][0], tab_max[oi][1], tab_max[oi][2], tab_max[oi][3]);
    $display("--- underruns + overruns in 1200 frames ---");
    $display("    crystal err    gain>>3   gain>>4   gain>>5   gain>>6");
    for (oi = 0; oi < 5; oi = oi + 1)
      $display("    %11d %9d %9d %9d %9d", tab_off[oi],
               tab_bad[oi][0], tab_bad[oi][1], tab_bad[oi][2], tab_bad[oi][3]);
    if (nr != 60) begin
      $display("FAIL: exhaustive sweep incomplete"); errors = errors + 1;
    end
    if (errors == 0) $display("PASS: 0 errors in %0d checks", checks);
    else             $display("FAIL: %0d errors in %0d checks", errors, checks);
    $finish;
  end

endmodule

    --- worst buffer excursion from target, in samples ---
        crystal err    gain>>3   gain>>4   gain>>5   gain>>6
              -4096         2         4         8        16
               -256         1         1         1         1
                  0         0         0         0         0
                256         1         1         1         1
               4096         2         4         8        16

    --- underruns + overruns in 1200 frames ---
        crystal err    gain>>3   gain>>4   gain>>5   gain>>6
              -4096         0         0         0         0
               -256         0         0         0         0
                  0         0         0         0         0
                256         0         0         0         0
               4096         0         0         0         0

     4096 / 786432  =  5,208 ppm     fifty times worse than any real part
      256 / 786432  =    326 ppm     the order of a cheap crystal
        0           =    perfectly matched, which never happens

    PHASE 1  DIRECTED, EXHAUSTIVE   5 offsets x 4 gains x 3 starts = 60
                                    1,200 frames each; the closed form asserted
                                    on every one

    PHASE 2  DIRECTED               a perfectly matched crystal must not move
                                    the buffer at all, and must settle at
                                    exactly the nominal rate

    PHASE 3  DIRECTED               the loop pulls the RIGHT WAY: buffer low
                                    means ask for MORE

    PHASE 4  DIRECTED, EXHAUSTIVE   every starting level 0..192 in steps of 8,
                                    at the most aggressive gain, must keep the
                                    reported rate inside the legal band

    PHASE 5  DIRECTED               the bus goes quiet, then floods: the only
                                    phase that drives the level PAST the rails

    PHASE 6  DIRECTED, EXHAUSTIVE   both inclusive bounds, reached five
                                    different ways each

    PHASE 7  RANDOM                 a jittery host, +/- 1 sample per frame,
                                    600 frames

    R6 (the inclusive bound made exclusive)     2  ->  51
    R5 (the upper clamp made off by one)       21  ->  36
    R8 (the underrun counter frozen)            1  ->  54
    R9 (only the upper rate clamp counted)      1  ->  54

                        steps     checks   reach   errors
    Verilog-2005       73,229    366,640   60/60        0
    SystemVerilog      73,229    366,640   60/60        0
    VHDL-2008          73,229    366,640   60/60        0

    DIRECTED ONLY (-D DIRECTED_ONLY / -gDIRECTED_ONLY=true)
    Verilog-2005       72,628    363,635   60/60        0
    SystemVerilog      72,628    363,635   60/60        0
    VHDL-2008          72,628    363,635   60/60        0

// =====================================================================
//  uac_feedback -- SystemVerilog.
//
//  Same hardware contract as the Verilog file: same ports, same widths,
//  same reset values, same cycle-by-cycle behaviour. What changes is that
//  the fixed-point quantities get named types, so the 10.14 format is
//  stated in the declaration rather than living in a comment.
//
//  EVERY CONTINUOUS ASSIGNMENT IS `logic` + `assign` ON SEPARATE LINES,
//  and that is not cosmetic. `logic x = expr;` is a one-shot VARIABLE
//  INITIALISER in SystemVerilog -- evaluated once at time zero and never
//  again -- while the Verilog `wire x = expr;` it came from is a
//  continuous assignment. Earlier in this track the mechanical
//  translation of five such lines produced 29,580 phantom failures
//  against a design that was entirely correct.
//
//  uac_feedback -- the control loop that keeps a USB audio device from
//  running out of samples, or drowning in them.
//
//  CLASSIFICATION: simplified synthesisable teaching RTL.
//  This is NOT an audio device. There is no DAC, no volume control, no
//  format negotiation and no mixer. It is the feedback endpoint: the one
//  number an asynchronous audio device sends back every frame, and the
//  arithmetic that decides what that number should be.
//
//  WHY THIS MECHANISM IS WORTH RTL
//  -------------------------------
//  A USB audio device runs on ITS OWN crystal. The host runs on its own.
//  Neither is wrong and neither can be adjusted to match the other, so
//  the device's idea of 48,000 samples per second and the host's differ
//  -- by a few parts per million, forever, in whichever direction the two
//  crystals happen to disagree.
//
//  A few parts per million sounds harmless. It is not, because the error
//  ACCUMULATES into a buffer:
//
//      100 ppm at 48 kHz = 4.8 samples per second
//                        = 288 samples per minute
//                        = a buffer of 288 samples emptied, or overflowed,
//                          every single minute, forever
//
//  There is no retry that fixes this and no error to report. The device
//  will run out of samples to play, and the listener hears a click. Then
//  it happens again a minute later.
//
//  SO USB AUDIO PUTS THE DEVICE IN CHARGE OF THE RATE.
//
//  An ASYNCHRONOUS audio device reports, once per frame on a dedicated
//  feedback endpoint, how many samples per frame it actually wants -- as
//  a fixed-point number, because the true answer is virtually never an
//  integer. At full speed the format is 10.14: ten integer bits and
//  fourteen fractional, so 48.000 samples/frame is 48 << 14.
//
//  The host accumulates that fractional value and sends floor() of it,
//  carrying the remainder into the next frame. Over many frames the
//  average rate the host sends matches the rate the device consumes, to
//  a precision of one part in 16384 of a sample.
//
//  This module is the device half: watch the buffer, and ask for what
//  will bring it back to where it should be.
// =====================================================================
module uac_feedback #(
  // Nominal samples per USB frame. 48 at 48 kHz with 1 ms frames.
  parameter integer NOM_SAMPLES = 48,
  // Buffer depth in samples. Real devices use a few milliseconds' worth;
  // the number only has to be big enough that the loop has room to work.
  parameter integer BUF_DEPTH   = 192
) (
  input  logic       clk,
  input  logic       rst_n,

  // One pulse per USB frame. Everything in this module happens once per
  // frame, because that is how often the host will look.
  input  logic       sof,

  // How many samples the host actually delivered this frame, and how many
  // the device's own clock consumed. These differ, and their difference
  // is the entire problem.
  input  logic[15:0] host_samples,
  input  logic[15:0] dev_consumed,

  // How aggressively to correct. The feedback correction is
  // (target - level) >> gain_shift, in whole samples per frame, so a
  // LARGER shift is a GENTLER loop.
  input  logic[3:0]  gain_shift,

  // ---- the feedback value, 10.14 fixed point ----
  //
  // This is the only thing the host ever sees from this module, and the
  // host will do exactly what it says.
  output logic[23:0] fb_value,

  output logic[15:0] buf_level,
  output logic       underrun,
  output logic       overrun,

  output logic[31:0] n_frames,
  output logic[31:0] n_underrun,
  output logic[31:0] n_overrun,
  output logic[31:0] n_clamped
);

  // 48 samples/frame in 10.14 is 48 * 16384.
  localparam [23:0] NOM_Q14 = NOM_SAMPLES * 16384;
  // The level the loop steers towards: half full, so it has equal room to
  // absorb an error in either direction.
  localparam [15:0] TARGET  = BUF_DEPTH / 2;

  // The specification bounds how far the reported rate may deviate from
  // nominal. A device that asked for wildly the wrong rate would be
  // indistinguishable from a broken one, and a host is entitled to stop
  // believing it. One sample per frame is the limit used here.
  localparam [23:0] FB_MAX = NOM_Q14 + 16384;
  localparam [23:0] FB_MIN = NOM_Q14 - 16384;

  // ---- named types for the two fixed-point quantities ----
  //
  // samples_t is a whole number of samples. q10_14_t is the wire format
  // the host reads: ten integer bits and fourteen fractional. Giving them
  // names means a mistake that mixes the two is visible at the
  // declaration instead of being buried inside a shift.
  typedef logic [15:0] samples_t;
  typedef logic [23:0] q10_14_t;

  samples_t    level;
  q10_14_t     fb_r;
  logic        under_r, over_r;
  logic [31:0] frame_c, under_c, over_c, clamp_c;

  assign buf_level  = level;
  assign fb_value   = fb_r;
  assign underrun   = under_r;
  assign overrun    = over_r;
  assign n_frames   = frame_c;
  assign n_underrun = under_c;
  assign n_overrun  = over_c;
  assign n_clamped  = clamp_c;

  // ---- the new level, before clamping ----
  //
  // Signed, because the device can consume more than arrived. Computed
  // combinationally so the clamp and the counters see one consistent
  // value rather than each recomputing it.
  logic signed [17:0] lvl_next;
  assign lvl_next = $signed({2'b00, level})
                  + $signed({2'b00, host_samples})
                  - $signed({2'b00, dev_consumed});

  logic hit_under;
  assign hit_under = (lvl_next <= 0);
  logic hit_over;
  assign hit_over = (lvl_next >= $signed(BUF_DEPTH));

  samples_t lvl_clamped;
  assign lvl_clamped = hit_under ? 16'd0 :
                       hit_over  ? samples_t'(BUF_DEPTH)
                                 : lvl_next[15:0];

  // ---- the correction ----
  //
  // Proportional only. An integral term would drive the steady-state
  // error to zero, and it would also wind up during the many frames where
  // the level is pinned at a clamp -- which is exactly when the error is
  // largest and the loop can do nothing about it. The chapter measures
  // what the proportional loop alone achieves.
  logic signed [17:0] err;
  assign err = $signed({2'b00, TARGET}) - $signed({2'b00, lvl_clamped});

  // err is in samples. Scaling it into 10.14 and then down by gain_shift
  // gives a correction of (err >> gain_shift) samples per frame.
  //
  // WHY A CONCATENATION AND NOT `err <<< 14`.
  //
  // The obvious way to write this is
  //
  //     wire signed [24:0] corr = ($signed({{7{err[17]}}, err}) <<< 14) >>> gain_shift;
  //
  // and it works, but not for the reason it appears to. A sign extension
  // placed before a LEFT shift is dead code at any width: the shift
  // discards exactly the bits the extension supplies. Here the seven
  // extension bits sit at bits 24:18 and the shift would move them to
  // 38:32, which do not exist. Bits 24:14 of the result come from
  // err[10:0] and from nothing else.
  //
  // The arithmetic is then correct only because eleven bits happens to be
  // enough for an error in [-96, +96]. The error spans +/- BUF_DEPTH/2 and
  // eleven signed bits hold [-1024, +1023], so the coincidence survives up
  // to BUF_DEPTH = 2046 and breaks at 2048: from there the top bits are
  // silently lost and the loop starts correcting in the WRONG DIRECTION
  // near the rails -- with no warning from any tool, because nothing is
  // out of range and nothing overflows.
  //
  // Written as a concatenation the width is STATED: {err, 14'b0} is
  // exactly 32 bits, err[17] lands on bit 31, and $signed makes the
  // following shift arithmetic. Nothing is extended and nothing is
  // discarded.
  logic signed [31:0] err_q14;
  assign err_q14 = $signed({err, 14'b0});
  logic signed [31:0] corr;
  assign corr = err_q14 >>> gain_shift;

  // Also 32 bits, and for the same reason: corr is 32 bits and adding it
  // into anything narrower would truncate it silently. The sum cannot
  // overflow 32 bits, and now that is true by construction rather than by
  // a count of how large the correction happens to get.
  logic signed [31:0] fb_raw;
  assign fb_raw = $signed({8'b0, NOM_Q14}) + corr;

  logic fb_hi;
  assign fb_hi = (fb_raw > $signed({8'b0, FB_MAX}));
  logic fb_lo;
  assign fb_lo = (fb_raw < $signed({8'b0, FB_MIN}));

  q10_14_t fb_next;
  assign fb_next = fb_hi ? FB_MAX :
                   fb_lo ? FB_MIN : fb_raw[23:0];

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      level   <= TARGET;          // start where the loop wants to be
      fb_r    <= NOM_Q14;
      under_r <= 1'b0;
      over_r  <= 1'b0;
      frame_c <= 32'd0;
      under_c <= 32'd0;
      over_c  <= 32'd0;
      clamp_c <= 32'd0;
    end else begin
      under_r <= 1'b0;
      over_r  <= 1'b0;

      if (sof) begin
        frame_c <= frame_c + 32'd1;
        level   <= lvl_clamped;
        fb_r    <= fb_next;

        // An underrun is not "the buffer got low". It is "the device
        // needed a sample that was not there", which is a click the
        // listener hears -- so it is counted separately from the loop
        // simply working hard.
        if (hit_under) begin
          under_r <= 1'b1;
          under_c <= under_c + 32'd1;
        end
        if (hit_over) begin
          over_r <= 1'b1;
          over_c <= over_c + 32'd1;
        end
        // How often the loop wanted to ask for more than it is allowed
        // to. A loop that is permanently clamped is not controlling
        // anything, and this counter is how that becomes visible.
        if (fb_hi || fb_lo) clamp_c <= clamp_c + 32'd1;
      end
    end
  end

endmodule

// =====================================================================
//  Testbench for uac_feedback. -- SystemVerilog.
//
//  SAME SEED AND SAME PHASE ORDER AS THE VERILOG BENCH, deliberately.
//  Icarus seeds $random identically, so both drive identical stimulus and
//  any difference between the two mutation columns is a real difference
//  between the two DESIGNS. The independent-stimulus role is VHDL's.
//
//  THE BENCH IS BOTH CLOCKS.
//
//  It plays the host -- accumulating the feedback value in 10.14 and
//  sending floor() of it, carrying the remainder -- and it plays the
//  device's crystal, consuming at a rate that deliberately is NOT the
//  nominal one. The gap between those two is the whole problem the
//  feedback endpoint exists to solve.
//
//  THE MODEL USES MULTIPLICATION WHERE THE DESIGN USES SHIFTS.
//  The design computes its correction as (err << 14) >>> gain_shift. The
//  model computes err * (16384 >> gain_shift). Same number, different
//  derivation -- so a sign-extension or rounding mistake in one cannot be
//  reproduced by the other.
//
//  THE HEADLINE is not a pass/fail. It is: how far does the buffer
//  actually drift before the loop catches it, as a function of how hard
//  the loop pulls?
// =====================================================================
`timescale 1ns/1ps
module tb_fb_sv;

  localparam integer NOM_SAMPLES = 48;
  localparam integer BUF_DEPTH   = 192;
  localparam integer TARGET      = BUF_DEPTH / 2;
  localparam integer NOM_Q14     = NOM_SAMPLES * 16384;
  localparam integer FB_MAX      = NOM_Q14 + 16384;
  localparam integer FB_MIN      = NOM_Q14 - 16384;

  logic clk = 1'b0, rst_n = 1'b0;
  always #5 clk = ~clk;

  logic         sof = 1'b0;
  logic [15:0] host_samples = 16'd0, dev_consumed = 16'd0;
  logic [3:0]  gain_shift = 4'd4;

  logic [23:0] fb_value;
  logic [15:0] buf_level;
  logic        underrun, overrun;
  logic [31:0] n_frames, n_underrun, n_overrun, n_clamped;

  uac_feedback #(.NOM_SAMPLES(NOM_SAMPLES), .BUF_DEPTH(BUF_DEPTH)) dut (
    .clk(clk), .rst_n(rst_n), .sof(sof),
    .host_samples(host_samples), .dev_consumed(dev_consumed),
    .gain_shift(gain_shift),
    .fb_value(fb_value), .buf_level(buf_level),
    .underrun(underrun), .overrun(overrun),
    .n_frames(n_frames), .n_underrun(n_underrun),
    .n_overrun(n_overrun), .n_clamped(n_clamped)
  );

  int errors = 0, checks = 0, steps = 0;
  int seed;

  // ---- cumulative across resets ----
  //
  // reset_dut runs once per configuration, so the DUT's own counters
  // describe only the last one.
  int c_frames = 0, c_under = 0, c_over = 0, c_clamp = 0;

  // ---- per-reset tally, maintained from the MODEL ----
  //
  // The DUT's four counters do not affect its behaviour, which is exactly
  // why nothing else in the bench would notice if they were wrong -- and
  // they are what a bring-up engineer will trust when the audio clicks and
  // no other evidence exists. These are kept from the model's own
  // formulation of each condition, never from the DUT's outputs.
  int t_frames, t_under, t_over, t_clamp;

  // $random is SIGNED: mask the sign bit before any modulo.
  function automatic logic [31:0] urand();
    return $random(seed) & 32'h3FFF_FFFF;
  endfunction

  task automatic ck(input logic cond, input string what);
    begin
      checks = checks + 1;
      if (!cond) begin
        errors = errors + 1;
        if (errors <= 20)
          $display("  ERROR @%0t step#%0d: %s", $time, steps, what);
      end
    end
  endtask

  // ---- the model, formulated differently from the design ----
  int m_level;

  // The design shifts; the model multiplies. err * (16384 >> shift) is
  // the same correction as (err << 14) >>> shift, arrived at from the
  // other side.
  function automatic integer model_fb(input integer lvl, input integer shift);
    int err, corr, raw;
    begin
      err  = TARGET - lvl;
      corr = err * (16384 >> shift);
      raw  = NOM_Q14 + corr;
      if      (raw > FB_MAX) model_fb = FB_MAX;
      else if (raw < FB_MIN) model_fb = FB_MIN;
      else                   model_fb = raw;
    end
  endfunction

  function automatic integer clamp_level(input integer lvl);
    begin
      if      (lvl <= 0)         clamp_level = 0;
      else if (lvl >= BUF_DEPTH) clamp_level = BUF_DEPTH;
      else                       clamp_level = lvl;
    end
  endfunction

  // ---- what the design said, sampled at a DEFINED instant ----
  int obs_level, obs_fb, obs_under, obs_over;

  // ---- the measurement ----
  int tab_off [0:4];
  int tab_gain [0:3];
  integer tab_max  [0:4][0:3];   // worst excursion from target
  integer tab_bad  [0:4][0:3];   // under + overruns

  task automatic reset_dut;
    begin
      rst_n = 1'b0; sof = 1'b0;
      host_samples = 16'd0; dev_consumed = 16'd0;
      @(posedge clk); @(posedge clk);
      rst_n = 1'b1;
      @(posedge clk); #1;
      m_level = TARGET;
      t_frames = 0; t_under = 0; t_over = 0; t_clamp = 0;
    end
  endtask

  // ---- PROPERTY 8: the four counters agree with an independent tally ----
  //
  // Called once per frame in the phases where the counted events actually
  // happen. Elsewhere no event occurs and the check would be trivially
  // true, which is worse than not making it: it would inflate the count
  // without testing anything.
  task automatic chk_counters;
    begin
      ck(n_frames   == t_frames, "n_frames did not count every frame");
      ck(n_underrun == t_under,  "n_underrun disagrees with the tally");
      ck(n_overrun  == t_over,   "n_overrun disagrees with the tally");
      ck(n_clamped  == t_clamp,  "n_clamped disagrees with the tally");
    end
  endtask

  // One USB frame: the host delivers, the device consumes, the loop
  // reports a new rate.
  task automatic one_frame(input integer send, input integer consume);
    int e_level, e_fb;
    begin
      e_level = clamp_level(m_level + send - consume);
      e_fb    = model_fb(e_level, gain_shift);

      sof = 1'b1; host_samples = send[15:0]; dev_consumed = consume[15:0];
      @(posedge clk); #1;
      sof = 1'b0;
      obs_level = buf_level;
      obs_fb    = fb_value;
      obs_under = underrun;
      obs_over  = overrun;

      // ---- PROPERTY 1: the buffer level is exact ----
      //
      // Not approximately right. The level is the state the whole loop is
      // built on, and a level that drifted from the truth would make every
      // feedback value wrong in a way that looked like a tuning problem.
      ck(obs_level == e_level, "the buffer level disagrees with the model");
      // ---- PROPERTY 2: the feedback value is exact ----
      ck(obs_fb == e_fb, "the feedback value disagrees with the model");
      // ---- PROPERTY 3: the reported rate stays inside the legal band ----
      //
      // A device that asked for wildly the wrong rate is indistinguishable
      // from a broken one, and a host is entitled to stop believing it.
      ck(obs_fb <= FB_MAX && obs_fb >= FB_MIN,
         "the feedback value left the legal band");
      // ---- PROPERTY 4: underrun means the device ran dry ----
      //
      // Not "the buffer got low". A click the listener hears, which is why
      // it is flagged separately from the loop merely working hard.
      ck(obs_under == ((m_level + send - consume) <= 0 ? 1 : 0),
         "underrun does not mean the device ran out of samples");
      ck(obs_over == ((m_level + send - consume) >= BUF_DEPTH ? 1 : 0),
         "overrun does not mean the buffer filled");

      // the tally, from the model -- note it uses m_level BEFORE the
      // assignment below, which is the level the frame started from
      t_frames = t_frames + 1;
      if ((m_level + send - consume) <= 0)         t_under = t_under + 1;
      if ((m_level + send - consume) >= BUF_DEPTH) t_over  = t_over + 1;
      begin : tally_clamp
        integer raw;
        raw = NOM_Q14 + (TARGET - e_level) * (16384 >> gain_shift);
        if (raw > FB_MAX || raw < FB_MIN) t_clamp = t_clamp + 1;
      end

      m_level = e_level;
      c_frames = c_frames + 1;
      if (obs_under) c_under = c_under + 1;
      if (obs_over)  c_over  = c_over + 1;
      if (obs_fb == FB_MAX || obs_fb == FB_MIN) c_clamp = c_clamp + 1;
      steps = steps + 1;
    end
  endtask

  // -------------------------------------------------------------------
  //  Run the loop for `nframes` frames with the device's crystal running
  //  `off_q14` away from nominal, and report the worst excursion.
  //
  //  The host does exactly what a real host does: accumulate the reported
  //  10.14 rate, send floor() of it, carry the remainder. The device does
  //  the same with its own true rate. Neither ever sends a fractional
  //  sample, and the fractions are what make the average come out right.
  // -------------------------------------------------------------------
  task automatic run_loop(input integer off_q14, input integer shift,
                input integer init_level, input integer nframes,
                output integer max_dev, output integer bad,
                output integer settled_dev);
    int hacc, dacc, send, consume, f, dev;
    begin
      reset_dut;
      gain_shift = shift[3:0];

      // Place the buffer at its starting level: one frame in which the
      // host delivers `init_level` and the device consumes exactly the
      // reset level, which leaves the level at init_level.
      one_frame(init_level, TARGET);

      hacc = 0; dacc = 0;
      max_dev = 0; bad = 0; settled_dev = 0;
      dev = NOM_Q14 + off_q14;

      for (f = 0; f < nframes; f = f + 1) begin
        // the host: accumulate what the device asked for, send floor()
        hacc    = hacc + fb_value;
        send    = hacc >> 14;
        hacc    = hacc - (send << 14);
        // the device's own crystal, doing the same with its true rate
        dacc    = dacc + dev;
        consume = dacc >> 14;
        dacc    = dacc - (consume << 14);

        one_frame(send, consume);

        if ((m_level - TARGET) > max_dev)  max_dev = m_level - TARGET;
        if ((TARGET - m_level) > max_dev)  max_dev = TARGET - m_level;
        // The SETTLED excursion, over the last quarter of the run only.
        // max_dev includes the transient from wherever the buffer
        // started, which is an initial condition rather than a property
        // of the loop; this is the steady state.
        if (f >= (nframes * 3) / 4) begin
          if ((m_level - TARGET) > settled_dev) settled_dev = m_level - TARGET;
          if ((TARGET - m_level) > settled_dev) settled_dev = TARGET - m_level;
        end
        if (obs_under || obs_over) bad = bad + 1;
      end
    end
  endtask

  // ---- exhaustive reach ----
  //
  // 5 crystal offsets x 4 loop gains x 3 starting levels = 60. Every
  // dimension is an independent input with no forbidden combinations.
  logic reach [0:59];
  int nr, ri;

  int oi, gi, ii, k, mx, bd, sd;
  int OFF [0:4];
  int GAIN [0:3];
  int INIT [0:2];

  initial begin
    for (ri = 0; ri < 60; ri = ri + 1) reach[ri] = 1'b0;
    // Crystal error in 10.14 samples per frame. 4096 is a quarter of a
    // sample per frame -- about 5200 ppm, far beyond any real crystal, and
    // included so the sweep spans the whole transition rather than
    // stopping at the first configuration that copes. 256 is about 325 ppm,
    // which is the order of a cheap part.
    OFF[0] = -4096; OFF[1] = -256; OFF[2] = 0; OFF[3] = 256; OFF[4] = 4096;
    // Larger shift is a GENTLER loop.
    GAIN[0] = 3; GAIN[1] = 4; GAIN[2] = 5; GAIN[3] = 6;
    INIT[0] = 16; INIT[1] = TARGET; INIT[2] = BUF_DEPTH - 16;
    seed = 32'd29003;

    reset_dut;

    // =============================================================
    //  PHASE 1 (DIRECTED, EXHAUSTIVE) -- the whole configuration space.
    // =============================================================
    for (oi = 0; oi < 5; oi = oi + 1)
    for (gi = 0; gi < 4; gi = gi + 1)
    for (ii = 0; ii < 3; ii = ii + 1) begin
      // 1200 frames, not 400.
      //
      // A proportional loop's settling time scales with its gain: a
      // shift of 6 has a time constant four times longer than a shift of
      // 4, and from 80 samples away it needs several hundred frames just
      // for the transient. At 400 frames the last quarter still contained
      // one sample of it, and the closed-form check failed by exactly one
      // -- six times, all at the gentlest gain.
      //
      // The measurement window was adequate for an aggressive loop and
      // not for a gentle one. That is a property of the loop, and the
      // right response is to give every configuration enough time rather
      // than to loosen the property.
      run_loop(OFF[oi], GAIN[gi], INIT[ii], 1200, mx, bd, sd);
      ri = (oi * 4 + gi) * 3 + ii;
      reach[ri] = 1'b1;

      // ---- PROPERTY 5: the steady-state excursion is a CLOSED FORM ----
      //
      //   excursion = crystal error (samples/frame) x 2^gain_shift
      //
      // which in 10.14 units is |off| << shift >> 14, floored at one
      // sample because the buffer is counted in whole samples and any
      // non-zero error eventually moves it by one.
      //
      // This is the chapter's result, and asserting it is what turns the
      // table below from an observation into a measurement. A loop whose
      // gain did not do what the arithmetic says would still produce a
      // plausible-looking table.
      begin : closedform
        integer e_exc, a;
        a = (OFF[oi] < 0) ? -OFF[oi] : OFF[oi];
        e_exc = (a == 0) ? 0 : (((a << GAIN[gi]) >> 14) < 1 ? 1 : ((a << GAIN[gi]) >> 14));
        // Asserted against the settled value, not the peak. The peak
        // includes the transient from wherever the buffer happened to
        // start, which is an initial condition and not a property of the
        // loop -- asserting the closed form against the peak failed 40
        // times for exactly that reason.
        //
        // Stating it for EVERY starting level is also the convergence
        // property: wherever the buffer began, the loop brings it to the
        // same steady state.
        ck(sd == e_exc,
           "the settled excursion does not match error x 2^gain");
      end
      // record the middle starting level for the headline table, so the
      // table measures the loop rather than the initial condition
      if (ii == 1) begin
        tab_off[oi]      = OFF[oi];
        tab_gain[gi]     = GAIN[gi];
        tab_max[oi][gi]  = sd;
        tab_bad[oi][gi]  = bd;
      end
    end

    // =============================================================
    //  PHASE 2 (DIRECTED) -- a matched crystal must not move at all.
    //
    //  With zero offset and the buffer starting exactly on target, the
    //  loop has nothing to correct. If it moves anyway, the loop is
    //  injecting the very error it exists to remove -- and every other
    //  measurement in this chapter would be contaminated by it.
    // =============================================================
    run_loop(0, 4, TARGET, 400, mx, bd, sd);
    ck(mx == 0, "the loop moved the buffer with a perfectly matched crystal");
    ck(bd == 0, "a matched crystal produced an underrun or overrun");
    ck(fb_value == NOM_Q14,
       "a matched crystal did not settle at exactly the nominal rate");

    // =============================================================
    //  PHASE 3 (DIRECTED) -- the loop pulls the RIGHT WAY.
    //
    //  Sign errors in a control loop are not subtle in their effect and
    //  are very subtle in the code. A loop wired backwards drives the
    //  buffer to a rail and holds it there, and every symptom points at
    //  the crystal rather than at the sign.
    // =============================================================
    reset_dut;
    gain_shift = 4'd4;
    one_frame(16, TARGET);                 // start well BELOW target
    ck(fb_value > NOM_Q14,
       "with the buffer low the device did not ask for MORE samples");
    reset_dut;
    one_frame(BUF_DEPTH - 16, TARGET);     // start well ABOVE target
    ck(fb_value < NOM_Q14,
       "with the buffer high the device did not ask for FEWER samples");

    // =============================================================
    //  PHASE 4 (DIRECTED, EXHAUSTIVE) -- the legal band is respected.
    //
    //  Every starting level from empty to full, at the most aggressive
    //  gain, so the correction the loop WANTS is as large as it can be.
    //  The reported rate must still never leave the band.
    // =============================================================
    for (k = 0; k <= BUF_DEPTH; k = k + 8) begin
      reset_dut;
      gain_shift = 4'd3;
      one_frame(k, TARGET);
      ck(fb_value <= FB_MAX && fb_value >= FB_MIN,
         "an extreme buffer level pushed the reported rate out of band");
    end

    // =============================================================
    //  PHASE 5 (DIRECTED) -- the bus goes quiet, and then it floods.
    //
    //  Every phase above keeps the buffer near the middle, which means
    //  the two clamps in the design are never actually exercised: the
    //  sweep touches the rails EXACTLY, never past them, and a clamp
    //  that fires exactly at its own bound returns the value it was
    //  given. A wrong clamp would have been inert in every phase so far.
    //
    //  A real device does go past the rails. The host loses its
    //  bandwidth reservation, or the bus is suspended, and nothing
    //  arrives for several frames while the device keeps consuming. That
    //  is the underrun the listener hears, and it is the one condition
    //  where the loop can do nothing except ask for the most it is
    //  allowed to and wait.
    //
    //  This phase also checks the DUT's four counters against a tally
    //  kept here, which is the only place in the bench where they are
    //  verified rather than merely printed.
    // =============================================================
    reset_dut;
    gain_shift = 4'd4;
    begin : rails
      int f2;

      // ---- nothing arrives, the device keeps consuming ----
      for (f2 = 0; f2 < 20; f2 = f2 + 1) begin
        one_frame(0, NOM_SAMPLES);
        // ---- PROPERTY 6: the level never leaves the buffer ----
        //
        // A level below zero or above the depth is not a small error. It
        // is a read or write outside the ring buffer.
        ck(obs_level <= BUF_DEPTH, "the level rose above the buffer depth");
        // Checked every frame, not once at the end: a counter that is
        // right at the end of a phase and wrong in the middle of it is
        // still a counter that cannot be trusted.
        chk_counters;
      end
      ck(obs_level == 0, "twenty frames of silence did not empty the buffer");
      // ---- PROPERTY 7: at the rail the device asks for the most it may --
      //
      // It cannot ask for enough to refill instantly -- the band forbids
      // that -- so the correct behaviour is to sit at the limit until the
      // buffer recovers, which is what makes recovery gradual and audible
      // as a single click rather than a burst of them.
      ck(fb_value == FB_MAX,
         "an empty buffer did not make the device ask for the maximum rate");

      // ---- the host over-delivers: twice nominal, nothing consumed ----
      for (f2 = 0; f2 < 20; f2 = f2 + 1) begin
        one_frame(2 * NOM_SAMPLES, 0);
        ck(obs_level <= BUF_DEPTH, "the level rose above the buffer depth");
        chk_counters;
      end
      ck(obs_level == BUF_DEPTH, "twenty frames of flood did not fill the buffer");
      ck(fb_value == FB_MIN,
         "a full buffer did not make the device ask for the minimum rate");

      ck(n_frames == 40, "forty frames were played and not forty counted");
    end

    // =============================================================
    //  PHASE 6 (DIRECTED, EXHAUSTIVE) -- the two boundaries, reached
    //  five different ways.
    //
    //  `underrun` is defined on lvl_next <= 0 and `overrun` on
    //  lvl_next >= BUF_DEPTH. Both bounds are INCLUSIVE, and an inclusive
    //  bound differs from an exclusive one at exactly one point: the
    //  bound itself. A sweep cannot widen that domain, because the domain
    //  is one value.
    //
    //  What can be widened is the number of ways the bench arrives there,
    //  and the number of consequences it checks once it has. The boundary
    //  must hold however the level got to it, so the level is placed at
    //  five different starting points and driven to each of
    //  {-2,-1,0,+1,+2} around both bounds from each one.
    // =============================================================
    begin : bounds
      int li, dd;
      integer LV [0:4];
      LV[0] = 24; LV[1] = 48; LV[2] = TARGET; LV[3] = 144; LV[4] = 168;
      for (li = 0; li < 5; li = li + 1)
      for (dd = -2; dd <= 2; dd = dd + 1) begin
        // ---- the EMPTY bound: drive lvl_next to exactly dd ----
        reset_dut;
        gain_shift = 4'd4;
        one_frame(LV[li], TARGET);            // place the level at LV[li]
        one_frame(0, LV[li] - dd);            // lvl_next = dd
        chk_counters;
        // ---- the FULL bound: drive lvl_next to exactly BUF_DEPTH+dd ----
        reset_dut;
        gain_shift = 4'd4;
        one_frame(LV[li], TARGET);
        one_frame(BUF_DEPTH + dd - LV[li], 0);
        chk_counters;
      end
    end

    // =============================================================
    //  PHASE 7 (RANDOM) -- a jittery host.
    //
    //  A real host does not deliver exactly what it was asked for every
    //  frame: scheduling, other devices and its own rounding all
    //  interfere. The loop has to survive that without the buffer
    //  wandering off.
    // =============================================================
`ifndef DIRECTED_ONLY
    reset_dut;
    gain_shift = 4'd4;
    one_frame(TARGET, TARGET);
    for (k = 0; k < 600; k = k + 1) begin : jitter
      int s, c;
      s = (fb_value >> 14) + (urand() % 3) - 1;   // host is +/-1 sample out
      c = NOM_SAMPLES + (urand() % 3) - 1;        // device jitters too
      if (s < 0) s = 0;
      if (c < 0) c = 0;
      one_frame(s, c);
    end
`endif

    nr = 0; for (ri = 0; ri < 60; ri = ri + 1) if (reach[ri]) nr = nr + 1;

    $display("steps=%0d checks=%0d reach=%0d/60 errors=%0d",
             steps, checks, nr, errors);
    $display("[uac] frames=%0d underruns=%0d overruns=%0d rate_clamped=%0d",
             c_frames, c_under, c_over, c_clamp);
    $display("--- worst buffer excursion from target, in samples ---");
    $display("    crystal err    gain>>3   gain>>4   gain>>5   gain>>6");
    for (oi = 0; oi < 5; oi = oi + 1)
      $display("    %11d %9d %9d %9d %9d", tab_off[oi],
               tab_max[oi][0], tab_max[oi][1], tab_max[oi][2], tab_max[oi][3]);
    $display("--- underruns + overruns in 1200 frames ---");
    $display("    crystal err    gain>>3   gain>>4   gain>>5   gain>>6");
    for (oi = 0; oi < 5; oi = oi + 1)
      $display("    %11d %9d %9d %9d %9d", tab_off[oi],
               tab_bad[oi][0], tab_bad[oi][1], tab_bad[oi][2], tab_bad[oi][3]);
    if (nr != 60) begin
      $display("FAIL: exhaustive sweep incomplete"); errors = errors + 1;
    end
    if (errors == 0) $display("PASS: 0 errors in %0d checks", checks);
    else             $display("FAIL: %0d errors in %0d checks", errors, checks);
    $finish;
  end

endmodule

-- =====================================================================
--  uac_feedback -- VHDL-2008.
--
--  Same hardware contract as the Verilog and SystemVerilog files: same
--  ports, same widths, same reset values, same cycle-by-cycle behaviour.
--
--  THIS IS THE INDEPENDENT IMPLEMENTATION, and in this track that has
--  repeatedly been the point rather than a formality. Icarus seeds
--  $random identically for Verilog and SystemVerilog, so those two benches
--  drive the SAME stimulus; the VHDL bench derives its own. A defect that
--  both Icarus benches share cannot be found by comparing them to each
--  other, and twice in this module the VHDL side is what exposed it.
--
--  VHDL also forces the arithmetic to be explicit in a way Verilog does
--  not. Verilog will silently truncate a 32-bit product assigned into a
--  narrower signal; numeric_std requires the width of every intermediate
--  to be stated, which is the same discipline the Verilog file adopted
--  deliberately after a mutation proved its sign extension was dead code.
--
--  uac_feedback -- the control loop that keeps a USB audio device from
--  running out of samples, or drowning in them.
--
--  CLASSIFICATION: simplified synthesisable teaching RTL.
--  This is NOT an audio device. There is no DAC, no volume control, no
--  format negotiation and no mixer. It is the feedback endpoint: the one
--  number an asynchronous audio device sends back every frame, and the
--  arithmetic that decides what that number should be.
--
--  A USB audio device runs on ITS OWN crystal and the host runs on its
--  own. Neither is wrong and neither can be adjusted to match the other,
--  so the device's idea of 48,000 samples per second and the host's differ
--  -- by a few parts per million, forever. A few parts per million sounds
--  harmless; it is not, because the error ACCUMULATES into a buffer:
--
--      100 ppm at 48 kHz = 4.8 samples per second
--                        = 288 samples per minute
--                        = a buffer emptied, or overflowed, every minute
--
--  There is no retry that fixes this and no error to report. So USB audio
--  puts the DEVICE in charge of the rate: an asynchronous device reports,
--  once per frame on a dedicated feedback endpoint, how many samples per
--  frame it actually wants, as a 10.14 fixed-point number. The host
--  accumulates that value, sends floor() of it, and carries the remainder.
-- =====================================================================
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity uac_feedback is
  generic (
    -- Nominal samples per USB frame. 48 at 48 kHz with 1 ms frames.
    NOM_SAMPLES : integer := 48;
    -- Buffer depth in samples. Real devices use a few milliseconds' worth;
    -- the number only has to be big enough that the loop has room to work.
    BUF_DEPTH   : integer := 192
  );
  port (
    clk          : in  std_logic;
    rst_n        : in  std_logic;

    -- One pulse per USB frame. Everything here happens once per frame,
    -- because that is how often the host will look.
    sof          : in  std_logic;

    -- How many samples the host actually delivered this frame, and how
    -- many the device's own clock consumed. These differ, and their
    -- difference is the entire problem.
    host_samples : in  unsigned(15 downto 0);
    dev_consumed : in  unsigned(15 downto 0);

    -- How aggressively to correct. The correction is
    -- (target - level) >> gain_shift, so a LARGER shift is a GENTLER loop.
    gain_shift   : in  unsigned(3 downto 0);

    -- The feedback value, 10.14 fixed point. The only thing the host ever
    -- sees from this module, and the host will do exactly what it says.
    fb_value     : out unsigned(23 downto 0);

    buf_level    : out unsigned(15 downto 0);
    underrun     : out std_logic;
    overrun      : out std_logic;

    n_frames     : out unsigned(31 downto 0);
    n_underrun   : out unsigned(31 downto 0);
    n_overrun    : out unsigned(31 downto 0);
    n_clamped    : out unsigned(31 downto 0)
  );
end entity;

architecture rtl of uac_feedback is

  -- 48 samples/frame in 10.14 is 48 * 16384.
  constant NOM_Q14 : unsigned(23 downto 0) := to_unsigned(NOM_SAMPLES * 16384, 24);
  -- The level the loop steers towards: half full, so it has equal room to
  -- absorb an error in either direction.
  constant TARGET  : unsigned(15 downto 0) := to_unsigned(BUF_DEPTH / 2, 16);

  -- The specification bounds how far the reported rate may deviate from
  -- nominal. A device that asked for wildly the wrong rate would be
  -- indistinguishable from a broken one, and a host is entitled to stop
  -- believing it. One sample per frame is the limit used here.
  constant FB_MAX : unsigned(23 downto 0) := to_unsigned(NOM_SAMPLES * 16384 + 16384, 24);
  constant FB_MIN : unsigned(23 downto 0) := to_unsigned(NOM_SAMPLES * 16384 - 16384, 24);

  signal level   : unsigned(15 downto 0);
  signal fb_r    : unsigned(23 downto 0);
  signal under_r : std_logic;
  signal over_r  : std_logic;
  signal frame_c : unsigned(31 downto 0);
  signal under_c : unsigned(31 downto 0);
  signal over_c  : unsigned(31 downto 0);
  signal clamp_c : unsigned(31 downto 0);

  signal lvl_next    : signed(17 downto 0);
  signal hit_under   : std_logic;
  signal hit_over    : std_logic;
  signal lvl_clamped : unsigned(15 downto 0);
  signal err         : signed(17 downto 0);
  signal err_q14     : signed(31 downto 0);
  signal corr        : signed(31 downto 0);
  signal fb_raw      : signed(31 downto 0);
  signal fb_hi       : std_logic;
  signal fb_lo       : std_logic;
  signal fb_next     : unsigned(23 downto 0);

begin

  buf_level  <= level;
  fb_value   <= fb_r;
  underrun   <= under_r;
  overrun    <= over_r;
  n_frames   <= frame_c;
  n_underrun <= under_c;
  n_overrun  <= over_c;
  n_clamped  <= clamp_c;

  -- ---- the new level, before clamping ----
  --
  -- Signed, because the device can consume more than arrived. Computed
  -- concurrently so the clamp and the counters see one consistent value
  -- rather than each recomputing it.
  lvl_next <= signed(resize(level, 18))
            + signed(resize(host_samples, 18))
            - signed(resize(dev_consumed, 18));

  hit_under <= '1' when lvl_next <= 0 else '0';
  hit_over  <= '1' when lvl_next >= to_signed(BUF_DEPTH, 18) else '0';

  lvl_clamped <= (others => '0')              when hit_under = '1' else
                 to_unsigned(BUF_DEPTH, 16)   when hit_over  = '1' else
                 unsigned(std_logic_vector(lvl_next(15 downto 0)));

  -- ---- the correction ----
  --
  -- Proportional only. An integral term would drive the steady-state
  -- error to zero, and it would also wind up during the many frames where
  -- the level is pinned at a clamp -- which is exactly when the error is
  -- largest and the loop can do nothing about it. The chapter measures
  -- what the proportional loop alone achieves.
  err <= signed(resize(TARGET, 18)) - signed(resize(lvl_clamped, 18));

  -- err is in samples. Scaling it into 10.14 and then down by gain_shift
  -- gives a correction of (err >> gain_shift) samples per frame.
  --
  -- WRITTEN AS A CONCATENATION, exactly as the Verilog is, and for the
  -- same reason: a sign extension placed before a LEFT shift is dead code
  -- at any width, because the shift discards precisely the bits the
  -- extension supplies. Concatenating fourteen zeros onto an 18-bit
  -- error gives 32 bits by construction, with err's sign bit landing on
  -- bit 31 -- so nothing is extended and nothing is discarded.
  --
  -- numeric_std would not have let the original mistake pass silently
  -- anyway: it requires the width of every intermediate to be stated,
  -- where Verilog infers one and truncates without comment.
  err_q14 <= signed(std_logic_vector(err) & "00000000000000");

  -- shift_right on a SIGNED value is an arithmetic shift. On an unsigned
  -- it is logical, which is the VHDL spelling of the same trap that makes
  -- Verilog's `>>` and `>>>` different operators.
  corr <= shift_right(err_q14, to_integer(gain_shift));

  -- Also 32 bits, and for the same reason: corr is 32 bits and adding it
  -- into anything narrower would truncate it.
  fb_raw <= signed(resize(NOM_Q14, 32)) + corr;

  fb_hi <= '1' when fb_raw > signed(resize(FB_MAX, 32)) else '0';
  fb_lo <= '1' when fb_raw < signed(resize(FB_MIN, 32)) else '0';

  fb_next <= FB_MAX when fb_hi = '1' else
             FB_MIN when fb_lo = '1' else
             unsigned(std_logic_vector(fb_raw(23 downto 0)));

  process (clk, rst_n)
  begin
    if rst_n = '0' then
      level   <= TARGET;            -- start where the loop wants to be
      fb_r    <= NOM_Q14;
      under_r <= '0';
      over_r  <= '0';
      frame_c <= (others => '0');
      under_c <= (others => '0');
      over_c  <= (others => '0');
      clamp_c <= (others => '0');
    elsif rising_edge(clk) then
      under_r <= '0';
      over_r  <= '0';

      if sof = '1' then
        frame_c <= frame_c + 1;
        level   <= lvl_clamped;
        fb_r    <= fb_next;

        -- An underrun is not "the buffer got low". It is "the device
        -- needed a sample that was not there", which is a click the
        -- listener hears -- so it is counted separately from the loop
        -- simply working hard.
        if hit_under = '1' then
          under_r <= '1';
          under_c <= under_c + 1;
        end if;
        if hit_over = '1' then
          over_r <= '1';
          over_c <= over_c + 1;
        end if;
        -- How often the loop wanted to ask for more than it is allowed
        -- to. A loop that is permanently clamped is not controlling
        -- anything, and this counter is how that becomes visible.
        if fb_hi = '1' or fb_lo = '1' then
          clamp_c <= clamp_c + 1;
        end if;
      end if;
    end if;
  end process;

end architecture;