XGMII — Seventy-Four Signals, and the Interface Built to Avoid Them

// SYNTHESIZABLE.
//
// The XGMII Extender Sublayer's transmit half: take an XGMII column,
// convert each byte lane to an 8B/10B code group, and hand it to that
// lane's serialiser.
//
// THE MAPPING:
//   XGMII byte lane n -> XAUI serial lane n. Always. Every column.
//   There is no striping and no deal, because the receiver identifies
//   a lane by WHICH WIRE it arrives on -- unlike Chapter 9.5's PCS
//   lanes, which carry their own names.
//
// THE NUMBERS:
//   10 Gb/s / 32 bits          = 312.5 M columns/s
//   one byte per lane per column = 312.5 M code groups/s per lane
//   x 10 bits (8B/10B)         = 3125 Mbaud per lane
//   4 lanes x 3.125 x 8/10     = 10 Gb/s   <- closes
//   1 UI                       = 320 ps
//
// XGMII CONTROL BITS BECOME CODE GROUPS. TXC[n] set means TXD[8n+7:8n]
// is a control character, which maps to an 8B/10B K code group. So the
// four control WIRES disappear into the encoding, exactly as Chapter
// 10.5's TX_CTL did.
package xaui_pkg;
 
  localparam int unsigned LANES        = 4;
  localparam int unsigned CODE_BITS    = 10;
  localparam int unsigned LANE_MBAUD   = 3125;
  localparam int unsigned COLUMNS_PER_S_M = 312;   // 312.5, truncated
 
  // 1 UI = 320 ps. Clause 47 receivers absorb roughly 40 UI of skew:
  //   40 x 320 ps = 12.8 ns
  // which is the number Section 9 turns into a FIFO depth.
  localparam int unsigned UI_PS         = 320;
  localparam int unsigned SKEW_UI       = 40;
  localparam int unsigned SKEW_PS       = SKEW_UI * UI_PS;   // 12800
 
  // XAUI code groups. /K/ carries the comma, /A/ is the deskew marker,
  // /R/ is the skip used for clock compensation.
  localparam logic [7:0] K28_0 = 8'h1C;   // /R/ skip
  localparam logic [7:0] K28_3 = 8'h7C;   // /A/ align
  localparam logic [7:0] K28_5 = 8'hBC;   // /K/ sync, contains the comma
  localparam logic [7:0] K27_7 = 8'hFB;   // /S/ start
  localparam logic [7:0] K29_7 = 8'hFD;   // /T/ terminate
  localparam logic [7:0] K30_7 = 8'hFE;   // /E/ error
 
  // The idle sequence is A K R K R K R ... with an /A/ column roughly
  // every 16 columns, so deskew markers arrive often enough to re-align
  // quickly and rarely enough to cost almost nothing.
  localparam int unsigned A_INTERVAL = 16;
 
  typedef enum logic [2:0] {
    COL_DATA, COL_IDLE_A, COL_IDLE_K, COL_IDLE_R,
    COL_START, COL_TERMINATE, COL_ERROR
  } column_kind_e;
 
endpackage
 
module xgmii_to_xaui_adapter
  import xaui_pkg::*;
#(
  parameter int unsigned CNT_W = 24
) (
  input  logic clk,                       // 312.5 MHz column clock
  input  logic rst_n,
 
  // XGMII, as Chapter 9.4 defines it.
  input  logic [31:0] xgmii_d,
  input  logic [3:0]  xgmii_c,
  input  logic        xgmii_valid,
 
  // To the four lane encoders.
  output logic [LANES-1:0][7:0] lane_octet,
  output logic [LANES-1:0]      lane_is_k,
  output logic                  lane_valid,
  output column_kind_e          column_kind,
 
  output logic [CNT_W-1:0] c_columns,
  output logic [CNT_W-1:0] c_data_columns,
  output logic [CNT_W-1:0] c_idle_columns,
  // A start character on a lane other than 0. Chapter 9.4 owns the
  // rule; this module owns DETECTING it before it is serialised,
  // because a serialised illegal column is four lanes of legal-looking
  // code groups that mean nothing.
  output logic             start_off_lane0,
  output logic [CNT_W-1:0] c_start_off_lane0
);
 
  integer i;
 
  always_comb begin
    column_kind = COL_DATA;
    if (xgmii_c[0] && (xgmii_d[7:0] == K27_7))       column_kind = COL_START;
    else if (|xgmii_c && (xgmii_d[7:0] == K29_7))    column_kind = COL_TERMINATE;
    else if (&xgmii_c && (xgmii_d[7:0] == K28_5))    column_kind = COL_IDLE_K;
    else if (&xgmii_c && (xgmii_d[7:0] == K28_3))    column_kind = COL_IDLE_A;
    else if (&xgmii_c && (xgmii_d[7:0] == K28_0))    column_kind = COL_IDLE_R;
  end
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      lane_valid <= 1'b0; c_columns <= '0; c_data_columns <= '0;
      c_idle_columns <= '0; start_off_lane0 <= 1'b0;
      c_start_off_lane0 <= '0;
      for (i = 0; i < LANES; i = i + 1) begin
        lane_octet[i] <= 8'd0;
        lane_is_k[i]  <= 1'b0;
      end
    end else begin
      lane_valid      <= 1'b0;
      start_off_lane0 <= 1'b0;
 
      if (xgmii_valid) begin
        // THE MAPPING. Byte lane n to serial lane n, and the control
        // bit becomes the K/data distinction the encoder needs.
        for (i = 0; i < LANES; i = i + 1) begin
          lane_octet[i] <= xgmii_d[8*i +: 8];
          lane_is_k[i]  <= xgmii_c[i];
        end
        lane_valid <= 1'b1;
 
        if (!(&c_columns)) c_columns <= c_columns + 1'b1;
        if (|xgmii_c) begin
          if (!(&c_idle_columns)) c_idle_columns <= c_idle_columns + 1'b1;
        end else begin
          if (!(&c_data_columns)) c_data_columns <= c_data_columns + 1'b1;
        end
 
        // A start character anywhere but lane 0 is illegal (Chapter
        // 9.4 §4). Detecting it HERE matters, because once serialised
        // it becomes four lanes of individually valid code groups and
        // nothing downstream has any reason to object.
        for (i = 1; i < LANES; i = i + 1) begin
          if (xgmii_c[i] && (xgmii_d[8*i +: 8] == K27_7)) begin
            start_off_lane0 <= 1'b1;
            if (!(&c_start_off_lane0))
              c_start_off_lane0 <= c_start_off_lane0 + 1'b1;
          end
        end
      end
    end
  end
 
endmodule

// SYNTHESIZABLE (with an 8B/10B encoder core per lane).
//
// Four independent 8B/10B encoders, one per XAUI lane.
//
// THE WORD THAT MATTERS IS "INDEPENDENT". Each lane has its OWN running
// disparity, because each lane is its own serial stream with its own
// DC-balance requirement. There is no shared disparity across a column,
// and a design that keeps one is wrong in a way that produces valid
// code groups and a slowly drifting DC level on three of four lanes.
//
// Chapter 10.5 owns 8B/10B's convergence behaviour on ONE lane. Here
// there are four of them, converging independently after a common
// alignment event -- so the convergence WINDOW is per lane, and the
// slowest lane sets when the link is usable.
module xaui_8b10b_lane_encoder
  import xaui_pkg::*;
#(
  parameter int unsigned CNT_W = 24
) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic [LANES-1:0][7:0] lane_octet,
  input  logic [LANES-1:0]      lane_is_k,
  input  logic                  lane_valid,
 
  output logic [LANES-1:0][CODE_BITS-1:0] lane_code,
  output logic [LANES-1:0]                lane_code_valid,
 
  // Per-lane running disparity, exported. Four numbers, not one.
  output logic [LANES-1:0] lane_rd,
  // A lane whose running disparity has been the same polarity for an
  // implausibly long run. Not illegal, and a strong hint that the
  // encoder's alternate-code selection is broken on that lane.
  output logic [LANES-1:0] lane_rd_stuck,
  output logic [LANES-1:0][CNT_W-1:0] c_lane_codes,
  output logic [LANES-1:0][7:0]       lane_rd_run
);
 
  // A run of same-polarity disparity longer than this is a hint, not a
  // violation -- legal data can produce long runs, but not this long
  // by chance.
  localparam int unsigned RD_RUN_ALARM = 8'd64;
 
  // Placeholder for the 8B/10B encoder core. Chapter 3.5 owns the
  // table; what matters here is that it CONSUMES and PRODUCES the
  // running disparity, which is why each lane needs its own copy.
  function automatic logic [CODE_BITS-1:0] encode_8b10b
    (input logic [7:0] octet, input logic is_k, input logic rd_in);
    encode_8b10b = {rd_in, is_k, octet};
  endfunction
 
  function automatic logic next_rd
    (input logic [7:0] octet, input logic is_k, input logic rd_in);
    next_rd = rd_in ^ (^octet) ^ is_k;
  endfunction
 
  integer i;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (i = 0; i < LANES; i = i + 1) begin
        lane_code[i]       <= '0;
        lane_code_valid[i] <= 1'b0;
        lane_rd[i]         <= 1'b0;
        lane_rd_stuck[i]   <= 1'b0;
        lane_rd_run[i]     <= 8'd0;
        c_lane_codes[i]    <= '0;
      end
    end else begin
      for (i = 0; i < LANES; i = i + 1) lane_code_valid[i] <= 1'b0;
 
      if (lane_valid) begin
        for (i = 0; i < LANES; i = i + 1) begin
          lane_code[i]       <= encode_8b10b(lane_octet[i], lane_is_k[i],
                                             lane_rd[i]);
          lane_code_valid[i] <= 1'b1;
 
          // EACH LANE UPDATES ITS OWN DISPARITY. Sharing one across
          // four lanes produces valid code groups on every lane and a
          // DC level that drifts on three of them.
          lane_rd[i] <= next_rd(lane_octet[i], lane_is_k[i], lane_rd[i]);
 
          if (next_rd(lane_octet[i], lane_is_k[i], lane_rd[i]) == lane_rd[i]) begin
            if (lane_rd_run[i] != 8'hFF) lane_rd_run[i] <= lane_rd_run[i] + 8'd1;
            if (lane_rd_run[i] == 8'(RD_RUN_ALARM)) lane_rd_stuck[i] <= 1'b1;
          end else begin
            lane_rd_run[i]   <= 8'd0;
            lane_rd_stuck[i] <= 1'b0;
          end
 
          if (!(&c_lane_codes[i])) c_lane_codes[i] <= c_lane_codes[i] + 1'b1;
        end
      end
    end
  end
 
endmodule

// SYNTHESIZABLE.
//
// Generates XAUI's idle sequence, which is three mechanisms wearing one
// costume.
//
//   A K R K R K R K R K R K R K R K A K R K R ...
//
//   /A/ K28.3 -- transmitted SIMULTANEOUSLY on all four lanes, roughly
//        every 16 columns. The deskew reference.
//   /K/ K28.5 -- carries the comma, so per-lane code-group alignment
//        has something to hunt for.
//   /R/ K28.0 -- the skip column. Section 10's clock compensation
//        inserts and deletes these, and ONLY these.
//
// WHY /R/ AND NOT /K/ OR /A/ IS THE DELETABLE ONE:
//   /A/ is a timing reference -- deleting one loses a deskew
//        opportunity, and deleting a pair changes the interval the far
//        end measures against.
//   /K/ carries the comma -- deleting them starves alignment recovery.
//   /R/ carries NOTHING. It exists to be deletable, which is why the
//        idle sequence is more than half /R/.
module xaui_align_sequencer
  import xaui_pkg::*;
#(
  parameter int unsigned CNT_W = 24
) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic idle_request,       // no data to send this column
  input  logic force_align,        // e.g. after a link event
 
  output logic [LANES-1:0][7:0] idle_octet,
  output logic [LANES-1:0]      idle_is_k,
  output logic                  idle_valid,
  output column_kind_e          idle_kind,
 
  // Exported so Section 10's compensator knows which columns it may
  // delete and which it must not.
  output logic                  is_deletable,
  output logic [4:0]            columns_since_a,
 
  output logic [CNT_W-1:0] c_a_columns,
  output logic [CNT_W-1:0] c_k_columns,
  output logic [CNT_W-1:0] c_r_columns,
  // The interval since the last /A/ exceeded the nominal. Legal after
  // a compensation event; a fault if it persists, because the far end
  // measures skew against these.
  output logic             a_interval_stretched
);
 
  logic [4:0] since_a_q;
  logic       kr_phase_q;      // alternates K and R between /A/ columns
 
  assign columns_since_a = since_a_q;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      since_a_q <= 5'd0; kr_phase_q <= 1'b0;
      idle_valid <= 1'b0; idle_kind <= COL_IDLE_K;
      is_deletable <= 1'b0; a_interval_stretched <= 1'b0;
      c_a_columns <= '0; c_k_columns <= '0; c_r_columns <= '0;
      for (int i = 0; i < LANES; i = i + 1) begin
        idle_octet[i] <= K28_5;
        idle_is_k[i]  <= 1'b1;
      end
    end else begin
      idle_valid           <= 1'b0;
      is_deletable         <= 1'b0;
      a_interval_stretched <= 1'b0;
 
      if (idle_request) begin
        idle_valid <= 1'b1;
 
        if (force_align || (since_a_q >= 5'(A_INTERVAL))) begin
          // /A/ COLUMN. K28.3 on ALL FOUR LANES, at the same instant --
          // which is the property that makes it a skew measurement
          // rather than just another idle character.
          for (int i = 0; i < LANES; i = i + 1) begin
            idle_octet[i] <= K28_3;
            idle_is_k[i]  <= 1'b1;
          end
          idle_kind    <= COL_IDLE_A;
          is_deletable <= 1'b0;          // NEVER deletable
          since_a_q    <= 5'd0;
          kr_phase_q   <= 1'b0;
          if (!(&c_a_columns)) c_a_columns <= c_a_columns + 1'b1;
 
        end else if (!kr_phase_q) begin
          // /K/ -- carries the comma. Not deletable: alignment recovery
          // needs a supply of them.
          for (int i = 0; i < LANES; i = i + 1) begin
            idle_octet[i] <= K28_5;
            idle_is_k[i]  <= 1'b1;
          end
          idle_kind    <= COL_IDLE_K;
          is_deletable <= 1'b0;
          kr_phase_q   <= 1'b1;
          since_a_q    <= since_a_q + 5'd1;
          if (!(&c_k_columns)) c_k_columns <= c_k_columns + 1'b1;
 
        end else begin
          // /R/ -- carries nothing, and exists to be deletable. More
          // than half of the idle sequence is /R/ for exactly this
          // reason: clock compensation needs a supply of columns whose
          // removal costs nothing.
          for (int i = 0; i < LANES; i = i + 1) begin
            idle_octet[i] <= K28_0;
            idle_is_k[i]  <= 1'b1;
          end
          idle_kind    <= COL_IDLE_R;
          is_deletable <= 1'b1;          // THE deletable column
          kr_phase_q   <= 1'b0;
          since_a_q    <= since_a_q + 5'd1;
          if (!(&c_r_columns)) c_r_columns <= c_r_columns + 1'b1;
        end
 
        // The /A/ interval is what the far end measures skew against.
        // Stretching it is legal after a compensation event and a fault
        // if it persists.
        if (since_a_q > 5'(A_INTERVAL + 4)) a_interval_stretched <= 1'b1;
      end
    end
  end
 
endmodule

// SYNTHESIZABLE.
//
// Aligns the four lanes using the /A/ column, and reports the measured
// skew.
//
// THE DEPTH, computed from the standard rather than guessed:
//   1 UI at 3.125 Gbaud   = 320 ps
//   clause 47 skew budget = ~40 UI
//   40 x 320 ps           = 12.8 ns
//   one code group        = 10 UI = 3.2 ns
//   12.8 / 3.2            = 4 code groups
//   so a 6-deep FIFO per lane covers the budget with margin
//
// AND THE MEASUREMENT IS FREE. The /A/ columns left the transmitter
// simultaneously, so the difference in their arrival times IS the skew
// -- obtained as a by-product of the alignment the receiver had to do
// anyway, exactly as Chapter 9.5 §7 gets it from alignment markers.
module xaui_lane_deskew_stage
  import xaui_pkg::*;
#(
  parameter int unsigned DEPTH = 6,
  parameter int unsigned DW    = 3,
  parameter int unsigned CNT_W = 20
) (
  input  logic clk,
  input  logic rst_n,
  input  logic clear,
 
  input  logic [LANES-1:0]      lane_valid,
  input  logic [LANES-1:0][7:0] lane_octet,
  input  logic [LANES-1:0]      lane_is_k,
  input  logic [LANES-1:0]      lane_a_seen,     // /A/ on this lane
  input  logic [LANES-1:0]      lane_synced,     // comma alignment held
 
  output logic                  deskew_done,
  output logic [LANES-1:0][7:0] aligned_octet,
  output logic [LANES-1:0]      aligned_is_k,
  output logic                  aligned_valid,
 
  // The measured skew, per lane, in code groups. The number a board
  // engineer needs and nothing else in the design produces.
  output logic [LANES-1:0][DW-1:0] lane_depth,
  output logic [DW-1:0]            worst_depth,
 
  // A lane arrived further behind than the buffer holds. REPORTED and
  // deskew REFUSED -- aligning three lanes and guessing the fourth
  // produces a stream that reassembles into plausible garbage.
  output logic                     skew_exceeded,
  output logic [1:0]               skew_exceeded_lane,
 
  output logic [CNT_W-1:0] c_deskews,
  output logic             ever_skew_exceeded,
  // Deskew is only meaningful once every lane has code-group sync.
  output logic             waiting_for_sync
);
 
  logic [DW-1:0]     depth_q [LANES];
  logic [LANES-1:0]  seen_q;
  logic              hunting_q;
 
  assign waiting_for_sync = !(&lane_synced);
 
  integer i;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      deskew_done <= 1'b0; aligned_valid <= 1'b0; worst_depth <= '0;
      skew_exceeded <= 1'b0; skew_exceeded_lane <= 2'd0;
      c_deskews <= '0; ever_skew_exceeded <= 1'b0;
      seen_q <= '0; hunting_q <= 1'b1;
      for (i = 0; i < LANES; i = i + 1) begin
        depth_q[i]    <= '0;
        lane_depth[i] <= '0;
      end
    end else if (clear || !(&lane_synced)) begin
      // Losing code-group sync on ANY lane invalidates the deskew: the
      // code-group boundary that /A/ was measured against is gone.
      deskew_done <= 1'b0; hunting_q <= 1'b1; seen_q <= '0;
      skew_exceeded <= 1'b0;
      for (i = 0; i < LANES; i = i + 1) depth_q[i] <= '0;
      // ever_skew_exceeded survives: a board is a board.
    end else begin
      aligned_valid <= 1'b0;
      skew_exceeded <= 1'b0;
 
      if (hunting_q) begin
        for (i = 0; i < LANES; i = i + 1) begin
          if (lane_valid[i]) begin
            if (lane_a_seen[i] && !seen_q[i]) begin
              // This lane's /A/. Its current depth IS how far behind
              // the earliest lane it is.
              seen_q[i]     <= 1'b1;
              lane_depth[i] <= depth_q[i];
              if (depth_q[i] > worst_depth) worst_depth <= depth_q[i];
            end else if (|seen_q) begin
              if (depth_q[i] == DW'(DEPTH - 1)) begin
                // OUT OF RANGE. Refuse; do not wrap. A wrapped buffer
                // aligns on stale data and reports a plausible SMALL
                // skew, which is the most convincing wrong answer this
                // module can give.
                skew_exceeded      <= 1'b1;
                skew_exceeded_lane <= 2'(i);
                ever_skew_exceeded <= 1'b1;
                hunting_q          <= 1'b1;
                seen_q             <= '0;
              end else begin
                depth_q[i] <= depth_q[i] + 1'b1;
              end
            end
          end
        end
 
        if (&seen_q) begin
          // ALL FOUR. Three is not deskew -- an XGMII column needs all
          // four bytes, so a missing lane means every column is wrong.
          hunting_q   <= 1'b0;
          deskew_done <= 1'b1;
          if (!(&c_deskews)) c_deskews <= c_deskews + 1'b1;
        end
 
      end else begin
        aligned_octet <= lane_octet;
        aligned_is_k  <= lane_is_k;
        aligned_valid <= &lane_valid;
      end
    end
  end
 
endmodule

// SYNTHESIZABLE.
//
// Clock compensation: absorb the frequency difference between the two
// ends by inserting and deleting /R/ columns.
//
// WHY IT IS NEEDED. The transmitting XGXS runs on ITS clock; the
// receiving one runs on ITS clock. Both are within tolerance and
// neither is exactly 156.25 MHz. Over time the receiver either
// accumulates columns it cannot forward or runs out of columns to
// forward -- Chapter 4.4's elastic buffer problem, at 312.5 M columns
// per second.
//
// THE MECHANISM, and it is the reason for this chapter's rejected
// property: the XGXS DELETES an /R/ column when its buffer fills and
// INSERTS one when it empties. So the column sequence leaving the far
// XGXS is NOT the sequence that entered the near one -- by design, on
// every conforming link, whenever the two clocks differ at all.
//
// AND THE GUARANTEE IT DOES MAKE is that FRAMES are unchanged. Not one
// byte of frame content, not one column between /S/ and /T/, is ever
// added or removed. Transparency is stated over frames; the stream is
// deliberately modified.
module xaui_clock_compensation
  import xaui_pkg::*;
#(
  parameter int unsigned FIFO_DEPTH = 32,
  parameter int unsigned HIGH_MARK  = 24,
  parameter int unsigned LOW_MARK   = 8,
  parameter int unsigned CNT_W = 24
) (
  input  logic clk,
  input  logic rst_n,
  input  logic clear,
 
  input  logic         col_valid,
  input  column_kind_e col_kind,
  input  logic         col_is_deletable,   // TRUE only for /R/
  input  logic         in_frame,
 
  input  logic [5:0]   fifo_level,
 
  output logic         forward_column,
  output logic         delete_column,
  output logic         insert_column,
 
  output logic [CNT_W-1:0] c_deletions,
  output logic [CNT_W-1:0] c_insertions,
  // The buffer reached a limit with no deletable column available.
  // This is the real failure: compensation had nowhere to act, so a
  // column will be lost or duplicated somewhere it matters.
  output logic             compensation_starved,
  output logic [CNT_W-1:0] c_starvations,
  output logic             ever_starved,
  // Net columns added minus removed. A number that should hover near
  // zero and drift slowly; a monotone trend means the clocks differ by
  // more than the mechanism can absorb.
  output logic signed [CNT_W-1:0] net_adjustment
);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      forward_column <= 1'b0; delete_column <= 1'b0; insert_column <= 1'b0;
      c_deletions <= '0; c_insertions <= '0;
      compensation_starved <= 1'b0; c_starvations <= '0;
      ever_starved <= 1'b0; net_adjustment <= '0;
    end else if (clear) begin
      c_deletions <= '0; c_insertions <= '0; c_starvations <= '0;
      net_adjustment <= '0;
      // ever_starved survives.
    end else begin
      forward_column       <= 1'b0;
      delete_column        <= 1'b0;
      insert_column        <= 1'b0;
      compensation_starved <= 1'b0;
 
      if (col_valid) begin
        if (in_frame) begin
          // NEVER touch a frame. Not one column between /S/ and /T/,
          // whatever the buffer is doing. This is the guarantee that
          // makes "transparent" true at the granularity it is stated.
          forward_column <= 1'b1;
 
        end else if (fifo_level > 6'(HIGH_MARK)) begin
          if (col_is_deletable) begin
            // DELETE an /R/. The stream is now shorter than it was,
            // and nothing above notices, because /R/ carries nothing.
            delete_column <= 1'b1;
            net_adjustment <= net_adjustment - 1;
            if (!(&c_deletions)) c_deletions <= c_deletions + 1'b1;
          end else begin
            // The buffer is filling and this column is /A/ or /K/,
            // which must not be removed. Forward it and wait.
            forward_column <= 1'b1;
            if (fifo_level == 6'(FIFO_DEPTH - 1)) begin
              compensation_starved <= 1'b1;
              ever_starved         <= 1'b1;
              if (!(&c_starvations)) c_starvations <= c_starvations + 1'b1;
            end
          end
 
        end else if (fifo_level < 6'(LOW_MARK)) begin
          // INSERT an /R/. Also invisible above, for the same reason.
          insert_column  <= 1'b1;
          forward_column <= 1'b1;
          net_adjustment <= net_adjustment + 1;
          if (!(&c_insertions)) c_insertions <= c_insertions + 1'b1;
 
        end else begin
          forward_column <= 1'b1;
        end
      end
    end
  end
 
endmodule

// SYNTHESIZABLE.
//
// A loopback self-test for the XGXS pair, and its checker is built
// around what the extender ACTUALLY guarantees.
//
// THE GUARANTEE, stated precisely:
//   FRAMES are preserved exactly. Every column between /S/ and /T/,
//   in order, unmodified, none added and none removed.
//   THE STREAM IS NOT. /R/ columns are inserted and deleted outside
//   frames whenever the two ends' clocks differ -- which is always.
//
// So this checker compares FRAMES and counts IDLE ADJUSTMENTS. A test
// that compared the two streams bit for bit would fail on every
// conforming link, which is Section 14's rejected property in the form
// of a testbench rather than an assertion.
module xgxs_loopback_selftest
  import xaui_pkg::*;
#(
  parameter int unsigned CNT_W = 20,
  parameter int unsigned PATTERN_FRAMES = 16'd1000
) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic start,
 
  // What was sent into the near XGXS.
  input  logic         tx_col_valid,
  input  logic [31:0]  tx_col_data,
  input  logic         tx_in_frame,
 
  // What emerged from the far XGXS.
  input  logic         rx_col_valid,
  input  logic [31:0]  rx_col_data,
  input  logic         rx_in_frame,
 
  output logic running,
  output logic done,
  output logic passed,
 
  // FRAME comparison -- the real check.
  output logic [CNT_W-1:0] c_frame_columns_sent,
  output logic [CNT_W-1:0] c_frame_columns_received,
  output logic [CNT_W-1:0] c_frame_column_mismatches,
 
  // IDLE accounting -- expected to be non-zero, and reported rather
  // than treated as an error.
  output logic signed [CNT_W-1:0] idle_columns_net,
  output logic                    idle_adjusted,
 
  // The two verdicts, which are deliberately separate.
  output logic frames_preserved,
  output logic stream_modified
);
 
  logic [15:0] frames_q;
  logic [31:0] tx_fifo_q;      // one-entry model of the frame path
  logic        tx_have_q;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      running <= 1'b0; done <= 1'b0; passed <= 1'b0;
      frames_q <= '0; tx_fifo_q <= '0; tx_have_q <= 1'b0;
      c_frame_columns_sent <= '0; c_frame_columns_received <= '0;
      c_frame_column_mismatches <= '0;
      idle_columns_net <= '0; idle_adjusted <= 1'b0;
      frames_preserved <= 1'b0; stream_modified <= 1'b0;
    end else if (start) begin
      running <= 1'b1; done <= 1'b0; passed <= 1'b0;
      frames_q <= '0; tx_have_q <= 1'b0;
      c_frame_columns_sent <= '0; c_frame_columns_received <= '0;
      c_frame_column_mismatches <= '0;
      idle_columns_net <= '0; idle_adjusted <= 1'b0;
    end else if (running) begin
      idle_adjusted <= 1'b0;
 
      // ---- FRAME columns: compared exactly ----
      if (tx_col_valid && tx_in_frame) begin
        tx_fifo_q <= tx_col_data;
        tx_have_q <= 1'b1;
        if (!(&c_frame_columns_sent))
          c_frame_columns_sent <= c_frame_columns_sent + 1'b1;
      end
 
      if (rx_col_valid && rx_in_frame) begin
        if (!(&c_frame_columns_received))
          c_frame_columns_received <= c_frame_columns_received + 1'b1;
        if (tx_have_q && (rx_col_data != tx_fifo_q)) begin
          // A frame column that changed. THIS is a failure.
          if (!(&c_frame_column_mismatches))
            c_frame_column_mismatches <= c_frame_column_mismatches + 1'b1;
        end
        tx_have_q <= 1'b0;
      end
 
      // ---- IDLE columns: counted, never compared ----
      if (tx_col_valid && !tx_in_frame) idle_columns_net <= idle_columns_net + 1;
      if (rx_col_valid && !rx_in_frame) begin
        idle_columns_net <= idle_columns_net - 1;
        // A net difference means the compensator acted, which is the
        // mechanism working. Recorded as an EVENT, not an error.
        if (idle_columns_net != 0) idle_adjusted <= 1'b1;
      end
 
      if (rx_col_valid && rx_in_frame && !tx_in_frame) begin
        frames_q <= frames_q + 16'd1;
      end
 
      if (frames_q == PATTERN_FRAMES) begin
        running <= 1'b0;
        done    <= 1'b1;
 
        // THE TWO VERDICTS, and they are independent.
        //   frames_preserved -- the guarantee the XGXS makes.
        //   stream_modified  -- the mechanism it needed to make it.
        // A healthy link has the first TRUE and the second ALSO TRUE.
        frames_preserved <= (c_frame_column_mismatches == '0) &&
                            (c_frame_columns_sent == c_frame_columns_received);
        stream_modified  <= (idle_columns_net != 0);
        passed           <= (c_frame_column_mismatches == '0) &&
                            (c_frame_columns_sent == c_frame_columns_received);
      end
    end
  end
 
endmodule

// SYNTHESIZABLE.
//
// Checks the XAUI rules that only exist because there are four lanes.
//
// THE FOUR-LANE RULES, none of which has a single-lane analogue:
//   1. /A/ is transmitted on ALL FOUR lanes simultaneously. An /A/ on
//      one lane and not the others is not an align column; it is a lane
//      that has lost sync and is decoding rubbish that happens to look
//      like K28.3.
//   2. Idle columns are the SAME character on all four lanes. A column
//      with /K/ on two lanes and /R/ on two is not a legal column.
//   3. /S/ appears on lane 0 only (Chapter 9.4 §4), and after
//      deskew that rule is checkable again.
//   4. Every lane must hold code-group sync. Three synced lanes is not
//      75% of a link -- an XGMII column needs all four bytes.
module xaui_conformance_monitor
  import xaui_pkg::*;
#(
  parameter int unsigned CNT_W = 20
) (
  input  logic clk,
  input  logic rst_n,
  input  logic clear,
 
  input  logic                  deskew_done,
  input  logic [LANES-1:0]      lane_synced,
  input  logic [LANES-1:0][7:0] lane_octet,
  input  logic [LANES-1:0]      lane_is_k,
  input  logic                  col_valid,
  input  logic                  in_frame,
 
  output logic partial_align_column,
  output logic mixed_idle_column,
  output logic start_off_lane0,
  output logic lane_sync_incomplete,
 
  output logic [CNT_W-1:0] c_partial_align,
  output logic [CNT_W-1:0] c_mixed_idle,
  output logic [CNT_W-1:0] c_start_off_lane0,
  output logic [CNT_W-1:0] c_sync_incomplete,
 
  output logic [LANES-1:0] ever_lost_sync,
  output logic       first_violation_valid,
  output logic [1:0] first_violation_kind,
  output logic       ever_violated
);
 
  logic a_any_c, a_all_c;
  logic idle_any_c, idle_same_c;
  logic any_c;
  logic [1:0] kind_c;
 
  always_comb begin
    a_any_c = 1'b0;
    a_all_c = 1'b1;
    for (int i = 0; i < LANES; i = i + 1) begin
      if (lane_is_k[i] && (lane_octet[i] == K28_3)) a_any_c = 1'b1;
      else                                          a_all_c = 1'b0;
    end
 
    // A legal idle column carries the SAME control character on all
    // four lanes. Mixed characters mean the lanes are not aligned to
    // the same column, whatever the deskew stage believes.
    idle_any_c  = 1'b0;
    idle_same_c = 1'b1;
    for (int i = 0; i < LANES; i = i + 1) begin
      if (lane_is_k[i]) idle_any_c = 1'b1;
      if (lane_is_k[i] && (lane_octet[i] != lane_octet[0])) idle_same_c = 1'b0;
    end
 
    any_c  = 1'b0;
    kind_c = 2'd0;
    if      (partial_align_column)  begin any_c = 1'b1; kind_c = 2'd0; end
    else if (mixed_idle_column)     begin any_c = 1'b1; kind_c = 2'd1; end
    else if (start_off_lane0)       begin any_c = 1'b1; kind_c = 2'd2; end
    else if (lane_sync_incomplete)  begin any_c = 1'b1; kind_c = 2'd3; end
  end
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      partial_align_column <= 1'b0; mixed_idle_column <= 1'b0;
      start_off_lane0 <= 1'b0; lane_sync_incomplete <= 1'b0;
      c_partial_align <= '0; c_mixed_idle <= '0;
      c_start_off_lane0 <= '0; c_sync_incomplete <= '0;
      ever_lost_sync <= '0;
      first_violation_valid <= 1'b0; first_violation_kind <= 2'd0;
      ever_violated <= 1'b0;
    end else if (clear) begin
      c_partial_align <= '0; c_mixed_idle <= '0;
      c_start_off_lane0 <= '0; c_sync_incomplete <= '0;
      first_violation_valid <= 1'b0;
      // ever_lost_sync and ever_violated survive.
    end else begin
      partial_align_column <= 1'b0;
      mixed_idle_column    <= 1'b0;
      start_off_lane0      <= 1'b0;
      lane_sync_incomplete <= 1'b0;
 
      for (int i = 0; i < LANES; i = i + 1)
        if (!lane_synced[i]) ever_lost_sync[i] <= 1'b1;
 
      // Nothing is checked before deskew. Before it, every lane is
      // presenting a code group from a different column, so every rule
      // is violated simultaneously and none of it is information.
      if (deskew_done && col_valid) begin
        if (!(&lane_synced)) begin
          lane_sync_incomplete <= 1'b1;
          if (!(&c_sync_incomplete)) c_sync_incomplete <= c_sync_incomplete + 1'b1;
        end
 
        // /A/ ON SOME LANES BUT NOT ALL. Not a partial align column --
        // there is no such thing. It is a lane decoding rubbish.
        if (a_any_c && !a_all_c) begin
          partial_align_column <= 1'b1;
          if (!(&c_partial_align)) c_partial_align <= c_partial_align + 1'b1;
        end
 
        if (!in_frame && idle_any_c && !idle_same_c) begin
          mixed_idle_column <= 1'b1;
          if (!(&c_mixed_idle)) c_mixed_idle <= c_mixed_idle + 1'b1;
        end
 
        for (int i = 1; i < LANES; i = i + 1) begin
          if (lane_is_k[i] && (lane_octet[i] == K27_7)) begin
            start_off_lane0 <= 1'b1;
            if (!(&c_start_off_lane0))
              c_start_off_lane0 <= c_start_off_lane0 + 1'b1;
          end
        end
      end
 
      if (any_c) begin
        ever_violated <= 1'b1;
        if (!first_violation_valid) begin
          first_violation_valid <= 1'b1;
          first_violation_kind  <= kind_c;
        end
      end
    end
  end
 
endmodule

// P1. Byte lane n maps to serial lane n. Always, every column, with no
// striping -- because the receiver identifies lanes by their wires.
property p_lane_mapping_fixed;
  @(posedge clk) disable iff (!rst_n)
  lane_valid |-> (lane_octet[2] == $past(xgmii_d[23:16]));
endproperty
a_lane_mapping_fixed: assert property (p_lane_mapping_fixed);
 
// P2. An XGMII control bit becomes a K code group on its own lane.
// The four control wires disappear into the encoding.
property p_control_becomes_k;
  @(posedge clk) disable iff (!rst_n)
  lane_valid |-> (lane_is_k == $past(xgmii_c));
endproperty
a_control_becomes_k: assert property (p_control_becomes_k);
 
// P3. A start character off lane 0 is detected BEFORE serialisation,
// while it is still expressible. Afterwards it is four valid code
// groups nothing downstream can object to.
property p_start_off_lane0_detected;
  @(posedge clk) disable iff (!rst_n)
  (xgmii_valid && xgmii_c[2] && (xgmii_d[23:16] == K27_7))
    |=> start_off_lane0;
endproperty
a_start_off_lane0_detected: assert property (p_start_off_lane0_detected);
 
// P4. Every column produces exactly one code group per lane. No
// column is dropped and none is duplicated in the adapter.
property p_one_code_per_lane_per_column;
  @(posedge clk) disable iff (!rst_n)
  xgmii_valid |=> lane_valid;
endproperty
a_one_code_per_column: assert property (p_one_code_per_lane_per_column);

// P5. Each lane's running disparity is updated from ITS OWN data.
// Sharing one across four produces valid code groups and a drifting
// DC level on three lanes.
property p_disparity_is_per_lane;
  @(posedge clk) disable iff (!rst_n)
  lane_valid |=> (lane_rd[1] == next_rd($past(lane_octet[1]),
                                        $past(lane_is_k[1]),
                                        $past(lane_rd[1])));
endproperty
a_disparity_per_lane: assert property (p_disparity_is_per_lane);
 
// P6. An implausibly long same-polarity run is reported as a hint.
property p_rd_stuck_reported;
  @(posedge clk) disable iff (!rst_n)
  (lane_rd_run[0] == 8'(RD_RUN_ALARM)) |=> lane_rd_stuck[0];
endproperty
a_rd_stuck_reported: assert property (p_rd_stuck_reported);

// P7. An /A/ column is the SAME character on all four lanes. There is
// no such thing as a partial align column.
property p_align_is_all_lanes;
  @(posedge clk) disable iff (!rst_n)
  (idle_valid && (idle_kind == COL_IDLE_A))
    |-> ((idle_octet[0] == K28_3) && (idle_octet[1] == K28_3) &&
         (idle_octet[2] == K28_3) && (idle_octet[3] == K28_3));
endproperty
a_align_all_lanes: assert property (p_align_is_all_lanes);
 
// P8. /A/ is NEVER marked deletable. It is a timing reference the far
// end measures skew against.
property p_align_not_deletable;
  @(posedge clk) disable iff (!rst_n)
  (idle_kind == COL_IDLE_A) |-> !is_deletable;
endproperty
a_align_not_deletable: assert property (p_align_not_deletable);
 
// P9. Nor is /K/ -- it carries the comma, and alignment recovery needs
// a supply of them.
property p_sync_not_deletable;
  @(posedge clk) disable iff (!rst_n)
  (idle_kind == COL_IDLE_K) |-> !is_deletable;
endproperty
a_sync_not_deletable: assert property (p_sync_not_deletable);
 
// P10. /R/ is the ONLY deletable column. It exists for that purpose.
property p_only_r_deletable;
  @(posedge clk) disable iff (!rst_n)
  is_deletable |-> (idle_kind == COL_IDLE_R);
endproperty
a_only_r_deletable: assert property (p_only_r_deletable);
 
// P11. The /A/ interval is bounded. The far end's deskew depends on
// them arriving regularly.
property p_align_interval_bounded;
  @(posedge clk) disable iff (!rst_n)
  idle_valid |-> (columns_since_a <= 5'(A_INTERVAL + 8));
endproperty
a_align_interval_bounded: assert property (p_align_interval_bounded);

// P12. Deskew requires code-group sync on EVERY lane first. Skew is
// measured in code groups, and a lane without sync has no code groups.
property p_deskew_needs_sync;
  @(posedge clk) disable iff (!rst_n)
  deskew_done |-> (&lane_synced);
endproperty
a_deskew_needs_sync: assert property (p_deskew_needs_sync);
 
// P13. And it requires all four /A/ characters. Three is not deskew --
// an XGMII column needs four bytes.
property p_deskew_needs_all_lanes;
  @(posedge clk) disable iff (!rst_n)
  $rose(deskew_done) |-> $past(&seen_q);
endproperty
a_deskew_needs_all_lanes: assert property (p_deskew_needs_all_lanes);
 
// P14. THE ALIASING PROPERTY. No recorded depth ever reaches DEPTH.
// A wrapped FIFO reports a PLAUSIBLE SMALL skew, which is the most
// convincing wrong answer this module can produce.
property p_depth_within_buffer;
  @(posedge clk) disable iff (!rst_n)
  deskew_done |-> (worst_depth < DW'(DEPTH));
endproperty
a_depth_within_buffer: assert property (p_depth_within_buffer);
 
// P15. An excess REFUSES deskew and names the lane.
property p_excess_refuses_and_names;
  @(posedge clk) disable iff (!rst_n)
  skew_exceeded |-> (!deskew_done && (skew_exceeded_lane < 2'(LANES)));
endproperty
a_excess_refuses: assert property (p_excess_refuses_and_names);
 
// P16. Losing sync on any lane invalidates the deskew.
property p_sync_loss_invalidates_deskew;
  @(posedge clk) disable iff (!rst_n)
  !(&lane_synced) |=> !deskew_done;
endproperty
a_sync_loss_invalidates: assert property (p_sync_loss_invalidates_deskew);

// P17. THE GUARANTEE. No column inside a frame is ever deleted.
property p_never_delete_in_frame;
  @(posedge clk) disable iff (!rst_n)
  in_frame |-> !delete_column;
endproperty
a_never_delete_in_frame: assert property (p_never_delete_in_frame);
 
// P18. Nor inserted into one.
property p_never_insert_in_frame;
  @(posedge clk) disable iff (!rst_n)
  in_frame |-> !insert_column;
endproperty
a_never_insert_in_frame: assert property (p_never_insert_in_frame);
 
// P19. Only a deletable column is ever deleted.
property p_delete_only_deletable;
  @(posedge clk) disable iff (!rst_n)
  delete_column |-> col_is_deletable;
endproperty
a_delete_only_deletable: assert property (p_delete_only_deletable);
 
// P20. Delete and insert are mutually exclusive.
property p_adjust_exclusive;
  @(posedge clk) disable iff (!rst_n)
  !(delete_column && insert_column);
endproperty
a_adjust_exclusive: assert property (p_adjust_exclusive);
 
// P21. Starvation is REPORTED. The buffer reached a limit with no
// deletable column available, which is the real failure -- as distinct
// from the buffer being full, which is the mechanism working.
property p_starvation_reported;
  @(posedge clk) disable iff (!rst_n)
  (col_valid && !in_frame && (fifo_level == 6'(FIFO_DEPTH - 1)) &&
   !col_is_deletable) |=> compensation_starved;
endproperty
a_starvation_reported: assert property (p_starvation_reported);
 
// P22. FRAMES are preserved across the pair -- the property the layer
// actually promises, at the granularity it promises it.
property p_frames_preserved;
  @(posedge clk) disable iff (!rst_n)
  done |-> (c_frame_column_mismatches == '0);
endproperty
a_frames_preserved: assert property (p_frames_preserved);