DDR Latency Anatomy

   TRULY IRREDUCIBLE      CL, burst
                          every access pays these, always

   IRREDUCIBLE PER ACCESS,  tRP, tRCD
   AVOIDABLE IN AGGREGATE   paid only on a miss or conflict;
                            how often is a POLICY outcome

   AVOIDABLE                queue wait, arbitration
                            entirely a policy outcome

// ---------------------------------------------------------------------
// latency_decomposer -- attributes one request's end-to-end latency to
// named, disjoint, exhaustive components.
//
// CLASSIFICATION: educational, synthesisable.
//
// WHAT IT DOES NOT MODEL:
//   - the device, its timing rules, or their legality (10.5 owns that)
//   - the arbitration policy (17.4 / 23.4 own it)
//   - any absolute time. Everything here is in CLOCK CYCLES; the
//     conversion to nanoseconds needs tCK, which is a configuration
//     fact and not this block's business.
//
// THE CENTRAL INVARIANT: the components SUM to the total, exactly, on
// every cycle of a tracked request's life. §14's P1 asserts it, and
// it is what makes this a decomposition rather than a set of timers.
// ---------------------------------------------------------------------
module latency_decomposer #(
  // Widest latency this block can attribute, in cycles. Saturating,
  // never wrapping: §12's note that a wrapped latency reads as a small
  // one and inverts the conclusion.
  parameter int MAX_LAT = 1023,
  parameter int LAT_W   = $clog2(MAX_LAT + 1),
  // Number of stages. Fixed by §3's decomposition, not configurable --
  // changing it would change what the block claims to measure.
  parameter int STAGES  = 6
) (
  input  logic              clk,
  input  logic              rst_n,

  // ── Stage-transition events. Each is a ONE-CYCLE pulse marking the
  //    boundary between two components of §3. The controller already
  //    produces every one of these internally; the contribution here is
  //    attributing the intervals between them.
  input  logic              ev_accept,      // ingress -> queue wait
  input  logic              ev_selected,    // queue wait -> arbitration
  input  logic              ev_committed,   // arbitration -> row work
  input  logic              ev_col_cmd,     // row work -> CAS
  input  logic              ev_first_beat,  // CAS -> burst
  input  logic              ev_last_beat,   // burst -> return
  input  logic              ev_delivered,   // return -> done

  // ── Per-component results, valid when `done` is asserted.
  output logic [LAT_W-1:0]  c_queue,
  output logic [LAT_W-1:0]  c_arb,
  output logic [LAT_W-1:0]  c_rowwork,
  output logic [LAT_W-1:0]  c_cas,
  output logic [LAT_W-1:0]  c_burst,
  output logic [LAT_W-1:0]  c_return,
  output logic [LAT_W-1:0]  total,

  // ── Observability.
  output logic              busy,
  output logic [2:0]        stage,
  output logic              done,
  // The invariant, published as a signal so a checker can require it
  // rather than recompute it. Held high while the sum is correct.
  output logic              sum_ok,
  // Which component is currently the largest. Costs a small comparison
  // tree and answers the only question anyone asks of a breakdown.
  output logic [2:0]        dominant,

  output logic              err_saturated,
  output logic              err_out_of_order,
  output logic              err_restart_while_busy
);

  initial begin
    if (MAX_LAT < 8)
      $fatal(1, "latency_decomposer: MAX_LAT (%0d) too small to be useful", MAX_LAT);
    if (STAGES != 6)
      $fatal(1, "latency_decomposer: STAGES is fixed at 6 by the decomposition");
  end

  localparam logic [2:0] S_IDLE  = 3'd0;
  localparam logic [2:0] S_QUEUE = 3'd1;
  localparam logic [2:0] S_ARB   = 3'd2;
  localparam logic [2:0] S_ROW   = 3'd3;
  localparam logic [2:0] S_CAS   = 3'd4;
  localparam logic [2:0] S_BURST = 3'd5;
  localparam logic [2:0] S_RET   = 3'd6;

  logic [2:0]       st;
  logic [LAT_W-1:0] acc [6];      // one accumulator per component
  logic [LAT_W-1:0] tot;
  logic             sat;
  logic             dn;
  logic             ooo;

  // Which accumulator the current stage charges. Declared above the
  // assigns that read it.
  logic [2:0] chg;
  always_comb begin
    unique case (st)
      S_QUEUE : chg = 3'd0;
      S_ARB   : chg = 3'd1;
      S_ROW   : chg = 3'd2;
      S_CAS   : chg = 3'd3;
      S_BURST : chg = 3'd4;
      S_RET   : chg = 3'd5;
      default : chg = 3'd0;
    endcase
  end

  // ── Legal next-event check. The stages are ORDERED (§3: each one's
  //    end is the next one's start), so an event arriving out of order
  //    is an integration error and must not silently mis-attribute.
  logic ev_expected;
  always_comb begin
    unique case (st)
      S_IDLE  : ev_expected = ev_accept;
      S_QUEUE : ev_expected = ev_selected;
      S_ARB   : ev_expected = ev_committed;
      S_ROW   : ev_expected = ev_col_cmd;
      S_CAS   : ev_expected = ev_first_beat;
      S_BURST : ev_expected = ev_last_beat;
      S_RET   : ev_expected = ev_delivered;
      default : ev_expected = 1'b0;
    endcase
  end

  logic any_ev;
  assign any_ev = ev_accept | ev_selected | ev_committed | ev_col_cmd
                | ev_first_beat | ev_last_beat | ev_delivered;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      st  <= S_IDLE;
      tot <= '0;
      sat <= 1'b0;
      dn  <= 1'b0;
      ooo <= 1'b0;
      for (int i = 0; i < 6; i++) acc[i] <= '0;
    end else begin
      dn  <= 1'b0;
      ooo <= 1'b0;

      if (st == S_IDLE) begin
        if (ev_accept) begin
          // A fresh request clears every accumulator. Not clearing them
          // is the defect that makes a second request's breakdown the
          // SUM of two requests -- plausible-looking and wrong.
          for (int i = 0; i < 6; i++) acc[i] <= '0;
          tot <= '0;
          sat <= 1'b0;
          st  <= S_QUEUE;
        end
      end else begin
        // ── Charge this cycle to the current stage, and to the total.
        //    Both saturate, and they saturate TOGETHER so the invariant
        //    of §14's P1 survives saturation rather than breaking at it.
        if (tot != LAT_W'(MAX_LAT)) begin
          acc[chg] <= acc[chg] + LAT_W'(1);
          tot      <= tot + LAT_W'(1);
        end else begin
          sat <= 1'b1;
        end

        // ── Advance on the expected event.
        if (ev_expected) begin
          unique case (st)
            S_QUEUE : st <= S_ARB;
            S_ARB   : st <= S_ROW;
            S_ROW   : st <= S_CAS;
            S_CAS   : st <= S_BURST;
            S_BURST : st <= S_RET;
            S_RET   : begin st <= S_IDLE; dn <= 1'b1; end
            default : st <= S_IDLE;
          endcase
        end else if (any_ev) begin
          // An event arrived that is not the one this stage expects.
          ooo <= 1'b1;
        end
      end
    end
  end

  assign c_queue   = acc[0];
  assign c_arb     = acc[1];
  assign c_rowwork = acc[2];
  assign c_cas     = acc[3];
  assign c_burst   = acc[4];
  assign c_return  = acc[5];
  assign total     = tot;
  assign busy      = (st != S_IDLE);
  assign stage     = st;
  assign done      = dn;

  // ── THE INVARIANT. Computed in a wider accumulator so the comparison
  //    itself cannot overflow and report a false pass.
  logic [LAT_W+2:0] sum_wide;
  always_comb begin
    sum_wide = '0;
    for (int i = 0; i < 6; i++) sum_wide = sum_wide + {3'b0, acc[i]};
  end
  assign sum_ok = (sum_wide == {3'b0, tot});

  // ── Largest component. Answers "where did the time go" in one value.
  always_comb begin
    dominant = 3'd0;
    for (int i = 1; i < 6; i++)
      if (acc[i] > acc[dominant]) dominant = 3'(i);
  end

  assign err_saturated          = sat;
  assign err_out_of_order       = ooo;
  assign err_restart_while_busy = busy && ev_accept;

endmodule

// ---------------------------------------------------------------------
// latency_distribution -- bounded-storage shape of a latency
// distribution, plus the statistics a histogram cannot provide.
//
// CLASSIFICATION: educational, synthesisable.
//
// WHAT IT DOES NOT MODEL:
//   - causes. It reports shape, never why.
//   - sub-bucket detail (§9's callout): within a bucket the
//     distribution is unknown, and the top bucket is open-ended.
//
// WHY A SEPARATE MAXIMUM: §9 -- the top bucket is open-ended, so the
// worst case is NOT recoverable from the histogram. A design reporting
// only buckets has lost the statistic §8 says matters most.
// ---------------------------------------------------------------------
module latency_distribution #(
  parameter int LAT_W   = 10,
  // Histogram buckets. Boundaries are POWERS OF TWO, so bucket
  // selection is a leading-one search rather than a divide -- which is
  // why the buckets are logarithmic and the resolution is coarse at
  // the tail. That is a deliberate trade, stated in §9.
  parameter int BUCKETS = 8,
  parameter int CNT_W   = 20,
  parameter int BKT_W   = (BUCKETS <= 1) ? 1 : $clog2(BUCKETS)
) (
  input  logic                clk,
  input  logic                rst_n,

  // ── One completed request.
  input  logic                sample_valid,
  input  logic [LAT_W-1:0]    sample_lat,

  // ── Shape.
  output logic [CNT_W-1:0]    bucket_count [BUCKETS],
  output logic [BKT_W-1:0]    last_bucket,

  // ── Percentile query. §9's table names a high percentile the most
  //    useful statistic; §9's callout states its resolution limit. Both
  //    are honoured here: the answer is a BUCKET, never a value.
  //    Target is a fraction over 256, so 253 is approximately the 99th
  //    percentile and no divider is needed.
  input  logic [7:0]          pctl_target_256,
  output logic [BKT_W-1:0]    pctl_bucket,
  output logic                pctl_valid,

  // ── Statistics the histogram cannot give (§9's callout).
  output logic [LAT_W-1:0]    lat_min,
  output logic [LAT_W-1:0]    lat_max,
  output logic [CNT_W-1:0]    n_samples,
  // Running sum, for a mean the CONSUMER computes -- this block does
  // not divide, because a mean needs a stated denominator and §9 says
  // the mean is the wrong summary anyway. Published so a consumer that
  // wants it must state what it divided by.
  output logic [CNT_W+LAT_W-1:0] lat_sum,

  // ── Saturation. Sticky and per-source, because a saturated bucket
  //    and a saturated sum invalidate different conclusions.
  output logic                any_bucket_saturated,
  output logic                sum_saturated,
  output logic                counts_valid,

  output logic                err_sample_while_reset
);

  initial begin
    if (BUCKETS < 2)
      $fatal(1, "latency_distribution: BUCKETS must be at least 2");
    if (LAT_W < 2)
      $fatal(1, "latency_distribution: LAT_W must be at least 2");
    if (CNT_W < 4)
      $fatal(1, "latency_distribution: CNT_W too small");
    // With power-of-two boundaries, BUCKETS-1 doublings must cover the
    // latency range or the top bucket swallows most of the data and the
    // histogram stops being informative.
    if ((BUCKETS - 1) > LAT_W)
      $fatal(1, "latency_distribution: %0d buckets exceed a %0d-bit range",
             BUCKETS, LAT_W);
  end

  // ── Bucket selection: a leading-one search. Bucket b holds latencies
  //    in [2^(b-1), 2^b), with bucket 0 holding 0 and 1, and the top
  //    bucket open-ended.
  logic [BKT_W-1:0] sel;
  always_comb begin
    sel = '0;
    for (int b = 1; b < BUCKETS; b++)
      if (sample_lat >= (LAT_W'(1) << (b - 1))) sel = BKT_W'(b);
  end

  logic [CNT_W-1:0]        bkt [BUCKETS];
  logic [LAT_W-1:0]        mn, mx;
  logic [CNT_W-1:0]        n;
  logic [CNT_W+LAT_W-1:0]  sm;
  logic                    bsat, ssat, first;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int b = 0; b < BUCKETS; b++) bkt[b] <= '0;
      // min starts at ALL ONES so the first sample always replaces it.
      // Starting at zero would pin the minimum at zero forever.
      mn    <= {LAT_W{1'b1}};
      mx    <= '0;
      n     <= '0;
      sm    <= '0;
      bsat  <= 1'b0;
      ssat  <= 1'b0;
      first <= 1'b1;
    end else if (sample_valid) begin
      // ── Bucket. Saturate rather than wrap.
      if (bkt[sel] == {CNT_W{1'b1}}) bsat <= 1'b1;
      else                           bkt[sel] <= bkt[sel] + CNT_W'(1);

      // ── Extremes. The maximum is the statistic §8 cares about and it
      //    is one compare.
      if (first || (sample_lat < mn)) mn <= sample_lat;
      if (sample_lat > mx)            mx <= sample_lat;
      first <= 1'b0;

      if (n != {CNT_W{1'b1}}) n <= n + CNT_W'(1);

      // ── Running sum, saturating. A wrapped sum produces a mean that
      //    is not merely wrong but LOWER than the truth -- flattering,
      //    which is the worst direction for a performance metric.
      if (sm > ({(CNT_W+LAT_W){1'b1}} - {{CNT_W{1'b0}}, sample_lat}))
        ssat <= 1'b1;
      else
        sm <= sm + {{CNT_W{1'b0}}, sample_lat};
    end
  end

  always_comb
    for (int b = 0; b < BUCKETS; b++) bucket_count[b] = bkt[b];

  // ── Percentile scan. A running prefix sum over the buckets, and the
  //    lowest bucket whose cumulative count reaches the target share of
  //    the samples. Combinational: BUCKETS is small and a prefix sum
  //    over it is a short adder chain, so no multi-cycle scan is needed.
  //
  //    THE COMPARISON IS DONE BY CROSS-MULTIPLICATION, not by dividing.
  //    cum/n >= target/256  becomes  cum*256 >= n*target, which is
  //    exact in integers. Dividing would truncate and bias the answer
  //    one bucket low on almost every query.
  logic [CNT_W+8:0] cum;
  logic [CNT_W+8:0] threshold;
  logic [BKT_W-1:0] pb;
  logic             pfound;

  always_comb begin
    threshold = {{9{1'b0}}, n} * {{(CNT_W+1){1'b0}}, pctl_target_256};
    cum       = '0;
    pb        = BKT_W'(BUCKETS - 1);
    pfound    = 1'b0;
    for (int b = 0; b < BUCKETS; b++) begin
      cum = cum + {9'b0, bkt[b]};
      if (!pfound && ((cum << 8) >= threshold)) begin
        pb     = BKT_W'(b);
        pfound = 1'b1;
      end
    end
  end

  assign pctl_bucket          = pb;
  // A percentile is meaningless without samples, and untrustworthy if
  // any bucket clamped -- the cumulative sum would then understate.
  assign pctl_valid           = pfound && (n != '0) && !bsat;

  assign last_bucket          = sel;
  assign lat_min              = first ? '0 : mn;
  assign lat_max              = mx;
  assign n_samples            = n;
  assign lat_sum              = sm;
  assign any_bucket_saturated = bsat;
  assign sum_saturated        = ssat;
  // Every reported figure is trustworthy only while nothing clamped.
  assign counts_valid         = !bsat && !ssat && (n != '0);

  assign err_sample_while_reset = sample_valid && !rst_n;

endmodule

// Bind unit note: P1-P6 reference latency_decomposer's internal state
// and are written as though bound into it, so clk and rst_n are
// visible directly. P7-P10 reference latency_distribution likewise.

// P1 -- THE property of this chapter. The components sum to the total,
// on every cycle. If this holds, the breakdown is a decomposition; if
// it does not, it is six unrelated timers.
property p_components_sum_to_total;
  @(posedge clk) disable iff (!rst_n)
    sum_ok;
endproperty
assert property (p_components_sum_to_total);

// P2 -- exactly one component charges per cycle while busy. §3's
// disjointness, and the guard against a cycle being counted twice.
property p_one_component_per_cycle;
  @(posedge clk) disable iff (!rst_n)
    (busy && !err_saturated)
      |=> ($countones({c_queue   != $past(c_queue, 1),
                       c_arb     != $past(c_arb, 1),
                       c_rowwork != $past(c_rowwork, 1),
                       c_cas     != $past(c_cas, 1),
                       c_burst   != $past(c_burst, 1),
                       c_return  != $past(c_return, 1)}) <= 1);
endproperty
assert property (p_one_component_per_cycle);

// P3 -- the total only ever grows while a request is tracked, and only
// by one. A total that could jump would mean a stage was skipped.
property p_total_monotonic_by_one;
  @(posedge clk) disable iff (!rst_n)
    (busy && !err_saturated && $past(busy, 1))
      |-> (total == $past(total, 1) + 1);
endproperty
assert property (p_total_monotonic_by_one);

// P4 -- a fresh request starts from zero. The stale-accumulator defect
// of §10, forbidden: without this, a second request reports the sum of
// two and still satisfies P1.
property p_fresh_request_starts_clean;
  @(posedge clk) disable iff (!rst_n)
    (ev_accept && !busy) |=> (total == LAT_W'(1));
endproperty
assert property (p_fresh_request_starts_clean);

// P5 -- stages advance in the fixed order of §3. An out-of-order event
// is reported and never silently mis-attributed.
property p_stage_order;
  @(posedge clk) disable iff (!rst_n)
    (stage != $past(stage, 1)) && $past(busy, 1) && busy
      |-> (stage == $past(stage, 1) + 3'd1);
endproperty
assert property (p_stage_order);

// P6 -- the saturation flag and the total's ceiling agree, so a
// clamped measurement is never reported as a real one.
property p_saturation_is_flagged;
  @(posedge clk) disable iff (!rst_n)
    (total == LAT_W'(MAX_LAT)) && busy |=> err_saturated;
endproperty
assert property (p_saturation_is_flagged);

// P7 -- the maximum never falls. A high-water mark that could decrease
// loses the event it exists to record (§9).
property p_max_monotonic;
  @(posedge clk) disable iff (!rst_n)
    (lat_max >= $past(lat_max, 1));
endproperty
assert property (p_max_monotonic);

// P8 -- the minimum never rises once established.
property p_min_monotonic;
  @(posedge clk) disable iff (!rst_n)
    ((n_samples != '0) && $past(n_samples, 1) != '0)
      |-> (lat_min <= $past(lat_min, 1));
endproperty
assert property (p_min_monotonic);

// P9 -- min bounds max. Trivial-looking, and it catches the
// all-ones-initialisation bug of §12 in both directions.
property p_min_le_max;
  @(posedge clk) disable iff (!rst_n)
    (n_samples != '0) |-> (lat_min <= lat_max);
endproperty
assert property (p_min_le_max);

// P10 -- counts_valid is only asserted when nothing has clamped, so no
// consumer can compute a ratio from a saturated count.
property p_valid_requires_no_saturation;
  @(posedge clk) disable iff (!rst_n)
    counts_valid |-> (!any_bucket_saturated && !sum_saturated);
endproperty
assert property (p_valid_requires_no_saturation);

// P11 -- the percentile bucket is monotonic in the target. A higher
// target can never select a LOWER bucket, which is the one structural
// property a percentile must have and the one a truncating divide
// breaks.
property p_percentile_monotonic;
  @(posedge clk) disable iff (!rst_n)
    (pctl_valid && $past(pctl_valid, 1)
       && (pctl_target_256 >= $past(pctl_target_256, 1))
       && (n_samples == $past(n_samples, 1)))
      |-> (pctl_bucket >= $past(pctl_bucket, 1));
endproperty
assert property (p_percentile_monotonic);

// P12 -- a percentile is never reported from a clamped histogram, where
// the cumulative sum would understate and bias the answer low.
property p_percentile_needs_clean_counts;
  @(posedge clk) disable iff (!rst_n)
    pctl_valid |-> !any_bucket_saturated;
endproperty
assert property (p_percentile_needs_clean_counts);

// ── Cover.
cover property (@(posedge clk) disable iff (!rst_n) done);
// A high percentile landing in the open-ended top bucket: the answer
// is "at least this much" and §9's callout says so.
cover property (@(posedge clk) disable iff (!rst_n)
                  pctl_valid && (pctl_bucket == BKT_W'(BUCKETS - 1)));
// A row HIT: row work charged zero cycles. The decomposition must
// handle a component of length zero, which is the case a naive
// implementation with a minimum-one-cycle stage gets wrong.
cover property (@(posedge clk) disable iff (!rst_n)
                  done && (c_rowwork == '0));
// A CONFLICT-shaped request: row work at least twice the CAS
// component, which at §2's parameters means a PRE preceded the ACT.
cover property (@(posedge clk) disable iff (!rst_n)
                  done && (c_rowwork >= (c_cas << 1)) && (c_cas != '0));
// Queue wait dominant -- §8's case, and the one that says the device
// is not the problem.
cover property (@(posedge clk) disable iff (!rst_n)
                  done && (dominant == 3'd0));
// Row work dominant -- the locality-bound case of 23.3.
cover property (@(posedge clk) disable iff (!rst_n)
                  done && (dominant == 3'd2));
cover property (@(posedge clk) disable iff (!rst_n) err_out_of_order);
cover property (@(posedge clk) disable iff (!rst_n) err_saturated);
// A sample landing in the open-ended top bucket: §9's resolution limit
// actually exercised.
cover property (@(posedge clk) disable iff (!rst_n)
                  sample_valid && (last_bucket == BKT_W'(BUCKETS - 1)));

// Independent timeline reconstruction. Records the cycle at which each
// event occurred, then computes the components by SUBTRACTION -- a
// different method from the DUT's per-cycle accumulation, so agreement
// is evidence rather than tautology.
// SIMULATION-ONLY.
class latency_timeline;
  int unsigned t_accept, t_selected, t_committed;
  int unsigned t_col, t_first, t_last, t_delivered;

  function int unsigned comp_queue();   return t_selected  - t_accept;    endfunction
  function int unsigned comp_arb();     return t_committed - t_selected;  endfunction
  function int unsigned comp_rowwork(); return t_col       - t_committed; endfunction
  function int unsigned comp_cas();     return t_first     - t_col;       endfunction
  function int unsigned comp_burst();   return t_last      - t_first;     endfunction
  function int unsigned comp_return();  return t_delivered - t_last;      endfunction
  function int unsigned total();        return t_delivered - t_accept;    endfunction

  // The reference's own sanity check: subtraction must be exhaustive.
  function bit intervals_partition();
    return (comp_queue() + comp_arb() + comp_rowwork() + comp_cas()
          + comp_burst() + comp_return()) == total();
  endfunction
endclass

  STALE-ACCUMULATOR DEFECT — TWO REQUESTS, ONE BREAKDOWN
    MAX_LAT = 1023. Two identical row-miss reads, back to back.
    §4's configuration: queue 6, arb 1, rowwork 11, cas 11, burst 4.

    request A : timeline gives 6 / 1 / 11 / 11 / 4  total 33
    request B : timeline gives 6 / 1 / 11 / 11 / 4  total 33

    DUT with accumulators cleared at DONE (the natural choice):
      request A reports 6 / 1 / 11 / 11 / 4  total 33      CORRECT
      request B reports 6 / 1 / 11 / 11 / 4  total 33      CORRECT

    DUT with accumulators cleared NOWHERE (the defect):
      request A reports 6 / 1 / 11 / 11 / 4  total 33      CORRECT
      request B reports 12 / 2 / 22 / 22 / 8  total 66     WRONG

    and note what still passes on request B:
      sum_ok    : 12+2+22+22+8 = 66 == total.  P1 HOLDS.
      P2        : still one component per cycle. HOLDS.
      P3        : total still grew by one per cycle. HOLDS.
      P5        : stages still advanced in order. HOLDS.
      dominant  : still reports rowwork. PLAUSIBLE.

    diagnosis : every arithmetic property is satisfied because the
                breakdown is internally consistent -- it is the
                breakdown of a REQUEST THAT DOES NOT EXIST, namely
                A and B concatenated.
    caught by : P4 (total == 1 on the cycle after a fresh accept) and
                by this check comparing against a per-request timeline.
    why it matters : the reported latency is exactly DOUBLE, which on
                a real system looks like a genuine performance problem
                and sends the investigation to the arbiter.