Eye Centering

   WRITE direction: controller drives, DEVICE receives
     controller TX ───────────────────────────► DRAM RX
                                                  │
                                       compares against VrefDQ
                                       INSIDE THE DRAM.
                                       JEDEC-specified, MR6.

   READ direction: device drives, CONTROLLER receives
     DRAM TX  ◄─────────────────────────────── controller RX
        │                                          │
        │                            compares against a reference
        │                            INSIDE THE PHY.
        │                            Not JEDEC-specified at all.

   15.00 / 0.65 = 23.0769...      not an integer

   50 codes of travel, according to the table   : 32.50% of VDDQ

   50 codes of travel, if the design's step is
     0.5%  ->  25.00% of VDDQ
     0.65% ->  32.50% of VDDQ   (only here does the table hold)
     0.8%  ->  40.00% of VDDQ

                    sampling delay code
              0   2   4   6   8  10  12  14  16
        ┌─────────────────────────────────────
     32 │  F   F   F   F   F   F   F   F   F
     30 │  F   F   F   P   P   P   F   F   F
     28 │  F   F   P   P   P   P   P   F   F
  V  26 │  F   P   P   P   P   P   P   P   F
  r  24 │  F   P   P   P   P   P   P   P   F
  e  22 │  F   P   P   P   P   P   P   P   F
  f  20 │  F   F   P   P   P   P   P   F   F
     18 │  F   F   F   P   P   P   F   F   F
     16 │  F   F   F   F   F   F   F   F   F
        └─────────────────────────────────────

   PASS = the comparison succeeded at this (delay, Vref) pair.
   The passing cells form a region. Its shape is informative.
   Its AREA is not a number with units.

   FULL GRID                    COORDINATE DESCENT
   every cell probed            one row, then one column

    F F F F F F F                . . . . . . .
    F F P P P F F                . . . . . . .
    F P P P P P F                F P P P P P F   <- sweep Vref fixed
    F P P P P P F                . . . P . . .      then delay at
    F P P P P P F                . . . P . . .      the chosen Vref
    F F P P P F F                . . . P . . .
    F F F F F F F                . . . . . . .

   cost D x V x R                cost (D + V) x R
   sees the whole region         sees a cross through it

// ---------------------------------------------------------------------
// eye_center_search -- two-axis centring by coordinate descent.
//
// CLASSIFICATION: educational, synthesisable.
//
// WHAT IT DOES NOT MODEL:
//   - any delay element or reference-level generator
//   - volts, VDDQ, or the code-to-voltage map of §4 -- the Vref axis
//     here is an INDEX, and the standard specifies the physical step
//     it maps to only as a 0.5%..0.8% band
//   - Vref set tolerance, which accumulates over steps (§4)
//   - the comparison, the stimulus, or the link
//
// Selection is PER AXIS and never compares the two axes, because no
// conversion between them exists inside this block (§7).
// ---------------------------------------------------------------------
module eye_center_search #(
  parameter int VREF_W    = 6,
  // JESD79-4 usable VrefDQ codes are 0..50; 51..63 are reserved. The
  // default reflects that, and the guard below enforces it.
  parameter int VREF_MAX  = 50,
  parameter int DLY_W     = 6,
  parameter int DLY_MAX   = 40,
  parameter int REPEATS   = 4,
  // Minimum acceptable passing width, PER AXIS. Two separate values,
  // because the axes are not commensurable (§7) -- a single shared
  // threshold would be asserting a conversion that does not exist.
  parameter int MIN_VREF_WIDTH = 4,
  parameter int MIN_DLY_WIDTH  = 4,
  // Coordinate-descent passes. One pass is a Vref sweep then a delay
  // sweep; more passes refine the estimate (§6).
  parameter int PASSES    = 2,
  parameter int REP_W = (REPEATS <= 1) ? 1 : $clog2(REPEATS + 1),
  parameter int PAS_W = (PASSES  <= 1) ? 1 : $clog2(PASSES + 1),
  parameter int VW_W  = $clog2(VREF_MAX + 2),
  parameter int DW_W  = $clog2(DLY_MAX + 2)
) (
  input  logic                clk,
  input  logic                rst_n,

  input  logic                start,
  // Starting point for the first sweep. Coordinate descent needs one,
  // and a bad one can stall the search (§6) -- so it is an input, not
  // a constant, and 21.5 supplies it from an earlier step's result.
  input  logic [VREF_W-1:0]   seed_vref,
  input  logic [DLY_W-1:0]    seed_delay,

  // ── To the two configurable resources. EXPERIMENTAL values.
  output logic [VREF_W-1:0]   cand_vref,
  output logic [DLY_W-1:0]    cand_delay,
  output logic                probe_req,

  // ── The observable: one bit, a conjunction (21.2 §1).
  input  logic                probe_done,
  input  logic                cmp_pass,

  // ── THE COMMITTED PAIR. Both, or neither -- see §8.
  output logic [VREF_W-1:0]   trained_vref,
  output logic [DLY_W-1:0]    trained_delay,
  output logic                trained_valid,
  output logic                train_done,
  output logic                train_failed,

  // ── Observability: the per-axis regions that produced the centres.
  output logic [VREF_W-1:0]   vref_lo, vref_hi,
  output logic [DLY_W-1:0]    dly_lo,  dly_hi,
  output logic [VW_W-1:0]     vref_width,
  output logic [DW_W-1:0]     dly_width,
  output logic                sweeping_vref,   // which axis is active
  output logic [2:0]          state_out,

  output logic                err_axis_empty,
  output logic                err_reserved_code
);

  initial begin
    // JESD79-4 reserves VrefDQ codes 51..63. Driving one is not a
    // subtle error: the device's behaviour is undefined.
    if (VREF_MAX > 50)
      $fatal(1, "eye_center_search: VREF_MAX (%0d) enters the reserved range", VREF_MAX);
    if (VREF_MAX > (2**VREF_W - 1))
      $fatal(1, "eye_center_search: VREF_MAX does not fit VREF_W");
    if (DLY_MAX > (2**DLY_W - 1))
      $fatal(1, "eye_center_search: DLY_MAX does not fit DLY_W");
    if (PASSES < 1)
      $fatal(1, "eye_center_search: PASSES must be at least 1");
    if (MIN_VREF_WIDTH < 1 || MIN_DLY_WIDTH < 1)
      $fatal(1, "eye_center_search: per-axis minimum widths must be at least 1");
  end

  typedef enum logic [2:0] {
    S_IDLE   = 3'd0,
    S_ARM    = 3'd1,
    S_PROBE  = 3'd2,
    S_CLASS  = 3'd3,
    S_STEP   = 3'd4,
    S_AXIS   = 3'd5,   // finish one axis: select its centre, swap axes
    S_COMMIT = 3'd6,
    S_FAIL   = 3'd7
  } state_e;

  state_e             state, next;

  logic               on_vref;      // currently sweeping the Vref axis
  logic [PAS_W-1:0]   pass_num;
  logic [REP_W-1:0]   reps;
  logic               all_passed;

  // The swept coordinate, and the fixed one.
  logic [VREF_W-1:0]  v_cur, v_fixed;
  logic [DLY_W-1:0]   d_cur, d_fixed;

  // Run tracking for the axis being swept. Widths are kept per axis
  // so a stalled axis cannot inherit the other's region.
  logic               in_run;
  logic [VW_W-1:0]    run_w;
  logic [VREF_W-1:0]  run_v_lo;
  logic [DLY_W-1:0]   run_d_lo;

  logic [VREF_W-1:0]  v_lo, v_hi;
  logic [DLY_W-1:0]   d_lo, d_hi;
  logic [VW_W-1:0]    v_w;
  logic [DW_W-1:0]    d_w;

  logic [VREF_W-1:0]  c_vref;
  logic [DLY_W-1:0]   c_delay;
  logic               c_ok;

  logic this_pass;
  assign this_pass = all_passed;

  logic axis_done;
  assign axis_done = on_vref ? (v_cur >= VREF_W'(VREF_MAX))
                             : (d_cur >= DLY_W'(DLY_MAX));

  // Effective widths, including a run still open at the top of the
  // axis being swept. S_AXIS folds that run into v_w / d_w in its
  // SEQUENTIAL block, which lands on the edge leaving the state --
  // while the next-state logic below evaluates during it. Deciding on
  // v_w / d_w alone would use pre-fold values and could FAIL an
  // axis whose region reaches its domain limit.
  logic [VW_W-1:0] eff_v_w;
  logic [DW_W-1:0] eff_d_w;
  assign eff_v_w = (on_vref  && in_run && (run_w >= v_w)) ? run_w : v_w;
  assign eff_d_w = (!on_vref && in_run && (DW_W'(run_w) >= d_w)) ? DW_W'(run_w) : d_w;

  // Both axes must satisfy their OWN minimum width. Checked separately,
  // never combined into a single area or score (§7).
  logic widths_ok;
  assign widths_ok = (eff_v_w >= VW_W'(MIN_VREF_WIDTH)) && (eff_d_w >= DW_W'(MIN_DLY_WIDTH));

  logic last_pass;
  assign last_pass = (pass_num + PAS_W'(1) >= PAS_W'(PASSES));

  always_comb begin
    next = state;
    unique case (state)
      S_IDLE   : if (start) next = S_ARM;
      S_ARM    : next = S_PROBE;
      S_PROBE  : if (probe_done)
                   next = (reps + REP_W'(1) >= REP_W'(REPEATS)) ? S_CLASS : S_PROBE;
      // Like 21.2 and unlike 21.3, each axis is swept to its end: a
      // per-axis region can be fragmented for the same reason.
      S_CLASS  : next = axis_done ? S_AXIS : S_STEP;
      S_STEP   : next = S_ARM;
      S_AXIS   : if (on_vref)            next = S_ARM;   // now sweep delay
                 else if (!last_pass)    next = S_ARM;   // another pass
                 else                    next = widths_ok ? S_COMMIT : S_FAIL;
      S_COMMIT : next = S_IDLE;
      S_FAIL   : next = S_IDLE;
      default  : next = S_IDLE;
    endcase
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      state      <= S_IDLE;
      on_vref    <= 1'b1;
      pass_num   <= '0;
      reps       <= '0;
      all_passed <= 1'b1;
      v_cur      <= '0;  d_cur   <= '0;
      v_fixed    <= '0;  d_fixed <= '0;
      in_run     <= 1'b0; run_w  <= '0;
      run_v_lo   <= '0;  run_d_lo <= '0;
      v_lo <= '0; v_hi <= '0; d_lo <= '0; d_hi <= '0;
      v_w  <= '0; d_w  <= '0;
      // SAFE STATE: neither axis committed, valid low. A mismatched
      // pair would be worse than none, because each half looks sane.
      c_vref  <= '0; c_delay <= '0; c_ok <= 1'b0;
    end else begin
      state <= next;

      unique case (state)
        S_IDLE : if (start) begin
          on_vref    <= 1'b1;         // Vref axis first
          pass_num   <= '0;
          reps       <= '0;
          all_passed <= 1'b1;
          v_cur      <= '0;           // sweep Vref from the bottom
          d_cur      <= seed_delay;   // with delay held at the seed
          v_fixed    <= seed_vref;
          d_fixed    <= seed_delay;
          in_run     <= 1'b0; run_w <= '0;
          v_w <= '0;  d_w <= '0;
          c_ok       <= 1'b0;
        end

        S_PROBE : if (probe_done) begin
          reps <= reps + REP_W'(1);
          if (!cmp_pass) all_passed <= 1'b0;
        end

        S_CLASS : begin
          if (this_pass) begin
            if (!in_run) begin
              in_run <= 1'b1; run_w <= VW_W'(1);
              run_v_lo <= v_cur; run_d_lo <= d_cur;
            end else begin
              run_w <= run_w + VW_W'(1);
            end
          end else if (in_run) begin
            // Close the run; keep it if it is the widest on this axis.
            if (on_vref) begin
              if (run_w >= v_w) begin
                v_lo <= run_v_lo; v_hi <= v_cur - VREF_W'(1); v_w <= run_w;
              end
            end else begin
              if (DW_W'(run_w) >= d_w) begin
                d_lo <= run_d_lo; d_hi <= d_cur - DLY_W'(1); d_w <= DW_W'(run_w);
              end
            end
            in_run <= 1'b0; run_w <= '0;
          end
          reps       <= '0;
          all_passed <= 1'b1;
        end

        S_STEP : if (on_vref) v_cur <= v_cur + VREF_W'(1);
                 else         d_cur <= d_cur + DLY_W'(1);

        S_AXIS : begin
          // Fold in a run still open at the top of this axis -- the
          // same omission that 21.2 §10 flagged, once per axis here.
          if (in_run) begin
            if (on_vref) begin
              if (run_w >= v_w) begin
                v_lo <= run_v_lo; v_hi <= VREF_W'(VREF_MAX); v_w <= run_w;
              end
            end else begin
              if (DW_W'(run_w) >= d_w) begin
                d_lo <= run_d_lo; d_hi <= DLY_W'(DLY_MAX); d_w <= DW_W'(run_w);
              end
            end
          end
          in_run <= 1'b0; run_w <= '0;

          if (on_vref) begin
            // Vref axis finished: fix Vref at its own midpoint and
            // sweep delay next. PER-AXIS selection -- §7.
            v_fixed <= v_lo + VREF_W'((v_hi - v_lo) / 2);
            v_cur   <= v_lo + VREF_W'((v_hi - v_lo) / 2);
            d_cur   <= '0;
            on_vref <= 1'b0;
          end else begin
            d_fixed <= d_lo + DLY_W'((d_hi - d_lo) / 2);
            d_cur   <= d_lo + DLY_W'((d_hi - d_lo) / 2);
            if (!last_pass) begin
              // Another descent pass, restarting on the Vref axis from
              // the delay centre just found.
              pass_num <= pass_num + PAS_W'(1);
              on_vref  <= 1'b1;
              v_cur    <= '0;
              v_w      <= '0;
              d_w      <= '0;
            end
          end
        end

        S_COMMIT : begin
          // BOTH axes commit together, from the per-axis midpoints.
          c_vref  <= v_lo + VREF_W'((v_hi - v_lo) / 2);
          c_delay <= d_lo + DLY_W'((d_hi - d_lo) / 2);
          c_ok    <= 1'b1;
        end

        default : ;
      endcase
    end
  end

  assign cand_vref  = on_vref ? v_cur : v_fixed;
  assign cand_delay = on_vref ? d_fixed : d_cur;
  assign probe_req  = (state == S_PROBE) && !probe_done;

  assign trained_vref  = c_vref;
  assign trained_delay = c_delay;
  assign trained_valid = c_ok;
  assign train_done    = (state == S_COMMIT) || (state == S_FAIL);
  assign train_failed  = (state == S_FAIL);

  assign vref_lo = v_lo; assign vref_hi = v_hi; assign vref_width = v_w;
  assign dly_lo  = d_lo; assign dly_hi  = d_hi; assign dly_width  = d_w;
  assign sweeping_vref = on_vref;
  assign state_out     = state;

  // An axis that produced no passing cell at all: §6's stall.
  assign err_axis_empty     = (state == S_FAIL) && ((v_w == '0) || (d_w == '0));
  // A reserved VrefDQ code would reach the device. Should be
  // impossible given the elaboration guard; published as a belt.
  assign err_reserved_code  = probe_req && (cand_vref > VREF_W'(50));

endmodule

// Bind unit note: these properties reference eye_center_search's
// internal state and are written as though bound into the module, so
// clk and rst_n are visible directly.

// P1 -- exactly one axis moves at a time. This IS coordinate descent,
// stated as a checkable invariant.
property p_one_axis_at_a_time;
  @(posedge clk) disable iff (!rst_n)
    ((cand_vref != $past(cand_vref, 1)) && (cand_delay != $past(cand_delay, 1)))
      |-> (state_out == 3'd5);
endproperty
assert property (p_one_axis_at_a_time);

// P2 -- both coordinates commit together. A half-committed pair is
// the failure mode of §9, and this is the property that forbids it.
property p_both_or_neither;
  @(posedge clk) disable iff (!rst_n)
    $rose(trained_valid)
      |-> ((trained_vref == vref_lo + VREF_W'((vref_hi - vref_lo) / 2))
        && (trained_delay == dly_lo + DLY_W'((dly_hi - dly_lo) / 2)));
endproperty
assert property (p_both_or_neither);

// P3 -- each axis's own minimum width was satisfied. Checked per axis,
// never as a combined score (§7).
property p_per_axis_width;
  @(posedge clk) disable iff (!rst_n)
    trained_valid
      |-> ((vref_width >= VW_W'(MIN_VREF_WIDTH))
        && (dly_width  >= DW_W'(MIN_DLY_WIDTH)));
endproperty
assert property (p_per_axis_width);

// P4 -- candidate/committed separation, as in every chapter so far.
property p_commit_only_on_commit;
  @(posedge clk) disable iff (!rst_n)
    ((trained_vref != $past(trained_vref, 1))
      || (trained_delay != $past(trained_delay, 1)))
      |-> ($past(state_out, 1) == 3'd6);
endproperty
assert property (p_commit_only_on_commit);

// P5 -- no reserved VrefDQ code is ever driven at the device.
// JESD79-4 reserves 51..63, and undefined device behaviour is not a
// failure the search could diagnose.
property p_no_reserved_vref;
  @(posedge clk) disable iff (!rst_n)
    probe_req |-> (cand_vref <= VREF_W'(50));
endproperty
assert property (p_no_reserved_vref);

// P6 -- the committed point lies inside both regions it came from.
// Weaker than P2 and survives a change of rounding policy.
property p_commit_inside_both;
  @(posedge clk) disable iff (!rst_n)
    trained_valid
      |-> ((trained_vref  >= vref_lo) && (trained_vref  <= vref_hi)
        && (trained_delay >= dly_lo)  && (trained_delay <= dly_hi));
endproperty
assert property (p_commit_inside_both);

// P7 -- an axis is only ever declared finished at the top of its own
// domain. The per-axis analogue of 21.2's P5.
property p_axis_swept_fully;
  @(posedge clk) disable iff (!rst_n)
    (state_out == 3'd5)
      |-> ($past(sweeping_vref, 1)
             ? ($past(cand_vref, 1)  == VREF_W'(VREF_MAX))
             : ($past(cand_delay, 1) == DLY_W'(DLY_MAX)));
endproperty
assert property (p_axis_swept_fully);

// ── Cover.
cover property (@(posedge clk) disable iff (!rst_n) $rose(trained_valid));
cover property (@(posedge clk) disable iff (!rst_n) err_axis_empty);
// A second descent pass actually ran -- PASSES > 1 exercised.
cover property (@(posedge clk) disable iff (!rst_n)
                  (state_out == 3'd5) && !sweeping_vref && !$past(train_done, 1)
                    && (pass_num != '0));
// One axis satisfied its width and the other did not: the case a
// combined area score would have wrongly accepted.
cover property (@(posedge clk) disable iff (!rst_n)
                  train_failed && (vref_width >= VW_W'(MIN_VREF_WIDTH))
                    && (dly_width < DW_W'(MIN_DLY_WIDTH)));
// An axis region touching the top of its domain: extent unknown.
cover property (@(posedge clk) disable iff (!rst_n)
                  trained_valid && (dly_hi == DLY_W'(DLY_MAX)));
// The whole Vref axis passed -- suspect the observable, per 21.2 §5.
cover property (@(posedge clk) disable iff (!rst_n)
                  trained_valid && (vref_width == VW_W'(VREF_MAX + 1)));

// Independent two-axis model. Knows the region; the engine does not.
// SIMULATION-ONLY.
class eye_region_model;
  // A parallelogram: the passing delay window SHIFTS with Vref, which
  // is the shape coordinate descent handles worst (§6).
  int unsigned v_lo, v_hi;      // Vref extent
  int          d_lo_at_vlo;     // delay window at the bottom of Vref
  int          d_width;
  int          tilt;            // delay-window shift per Vref code

  function bit pass(int unsigned v, int unsigned d);
    int lo;
    if (v < v_lo || v > v_hi) return 1'b0;
    lo = d_lo_at_vlo + tilt * int'(v - v_lo);
    return (int'(d) >= lo) && (int'(d) < lo + d_width);
  endfunction
endclass

  COORDINATE DESCENT ON A TILTED REGION
    Vref axis 20..40, delay window 8 wide, tilt = +1 delay code
    per Vref code. True best cell (largest all-pass box centre):
    Vref 30, delay 18.

    PASSES = 1, seed_delay = 12
      Vref sweep at delay 12   : passes for Vref 20..24 only
                                 (above 24 the window has shifted
                                  past delay 12)
      Vref centre selected     : 22
      delay sweep at Vref 22   : passes 10..17, centre 13
      committed                : (22, 13)   -- a PASSING cell
      distance from true best  : 8 Vref codes, 5 delay codes

    PASSES = 3, same seed
      pass 1 -> (22, 13)
      pass 2 -> Vref sweep at delay 13 gives 20..25, centre 22;
                delay sweep at 22 gives 10..17, centre 13
      pass 3 -> unchanged
      committed                : (22, 13)   -- CONVERGED, and still
                                 8 codes from the true best

    diagnosis : more passes did not help. Coordinate descent converged
                to a FIXED POINT that is not the global best, because
                on a tilted region each axis's midpoint is optimal
                given the other axis's current value.
    why it matters : the committed cell passes every property in §11
                and every check above except the fourth. The search is
                self-consistent and locally optimal and wrong.
    the real fix : a better seed, or a search that samples the grid
                more widely before descending -- not more passes.