PHY Management — MDC/MDIO, Clause 22 and Clause 45

Clause 22:  32 devices × 32 registers                = 1,024 registers
Clause 45:  32 ports  × 32 MMDs × 65,536 registers   = about 67 million

// SYNTHESIZABLE. Clause 22 MDIO master.
//
// The frame is the published one: 32 preamble bits, then ST(2) OP(2)
// PHYAD(5) REGAD(5) TA(2) DATA(16) -- 32 bits after the preamble.
//
// THE PART THAT BREAKS is the turnaround. MDIO is one bidirectional wire.
// On a read the master must STOP driving before the device starts, and if
// the two disagree by one bit time the frame still completes -- with one
// data bit sampled from contention. The result is a read that is usually
// correct and occasionally wrong in the same bit position.
//
// So output enable is derived from an explicit bit counter, never from a
// state that could be reached one cycle early or late.
package mdio_pkg;
  localparam logic [1:0] ST_C22 = 2'b01;
  localparam logic [1:0] ST_C45 = 2'b00;
 
  localparam logic [1:0] OP_C22_WRITE = 2'b01;
  localparam logic [1:0] OP_C22_READ  = 2'b10;
 
  // Clause 45 opcodes, as published.
  localparam logic [1:0] OP_C45_ADDR      = 2'b00;
  localparam logic [1:0] OP_C45_WRITE     = 2'b01;
  localparam logic [1:0] OP_C45_READ      = 2'b11;
  localparam logic [1:0] OP_C45_READ_INC  = 2'b10;
 
  // Bit positions within the post-preamble frame, counting from 0.
  localparam int unsigned BIT_ST   = 0;   // 2 bits
  localparam int unsigned BIT_OP   = 2;   // 2 bits
  localparam int unsigned BIT_PHY  = 4;   // 5 bits
  localparam int unsigned BIT_REG  = 9;   // 5 bits
  localparam int unsigned BIT_TA   = 14;  // 2 bits
  localparam int unsigned BIT_DATA = 16;  // 16 bits
  localparam int unsigned FRAME_BITS = 32;
endpackage
 
module mdio_master
  import mdio_pkg::*;
#(
  parameter int unsigned PREAMBLE_BITS = 32,
  // MDC is specified up to 2.5 MHz. The divider is from the system clock,
  // and it is a parameter because getting it wrong is a common integration
  // fault that produces a bus no device answers.
  parameter int unsigned MDC_DIVIDER   = 40,
  parameter int unsigned DIV_W         = $clog2(MDC_DIVIDER + 1)
) (
  input  logic clk,
  input  logic rst_n,
 
  // ── Request ─────────────────────────────────────────────────────────────
  input  logic        req_valid,
  input  logic        req_is_read,
  input  logic [4:0]  req_phyad,
  input  logic [4:0]  req_regad,
  input  logic [15:0] req_wdata,
  output logic        req_ready,
 
  // ── Response ────────────────────────────────────────────────────────────
  output logic        rsp_valid,
  output logic [15:0] rsp_rdata,
  // The device did not take the wire during turnaround. Either no device
  // responded at that address, or the bus is faulty -- Section 10 separates
  // those two, and they have different owners.
  output logic        rsp_no_response,
 
  // ── Pins ────────────────────────────────────────────────────────────────
  output logic        mdc,
  output logic        mdio_out,
  output logic        mdio_oe,     // drive enable; low releases the wire
  input  logic        mdio_in
);
 
  typedef enum logic [2:0] {
    M_IDLE, M_PREAMBLE, M_FRAME, M_DONE
  } m_state_e;
 
  m_state_e         state_q;
  logic [DIV_W-1:0] div_q;
  logic [5:0]       bit_q;
  logic [31:0]      shift_q;
  logic [15:0]      rdata_q;
  logic             is_read_q;
  logic             saw_device_q;
 
  wire mdc_rise = (div_q == DIV_W'(MDC_DIVIDER - 1));
  wire mdc_fall = (div_q == DIV_W'(MDC_DIVIDER / 2 - 1));
 
  // THE TURNAROUND RULE, expressed against the bit counter alone.
  //
  // On a READ the master drives bits 0..14 -- through the first TA bit --
  // and releases from bit 15 onward. On a WRITE it drives the whole frame.
  //
  // Deriving this from a bit index rather than from a state means it cannot
  // be off by a cycle, which is exactly the failure this module exists to
  // avoid.
  wire drive_c = (state_q == M_PREAMBLE)
              || ((state_q == M_FRAME)
                  && (!is_read_q || (bit_q < 6'd15)));
 
  assign req_ready = (state_q == M_IDLE);
  assign mdio_oe   = drive_c;
  assign mdio_out  = (state_q == M_PREAMBLE) ? 1'b1 : shift_q[31];
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      state_q         <= M_IDLE;
      div_q           <= '0;
      bit_q           <= '0;
      shift_q         <= '0;
      rdata_q         <= '0;
      is_read_q       <= 1'b0;
      saw_device_q    <= 1'b0;
      mdc             <= 1'b0;
      rsp_valid       <= 1'b0;
      rsp_rdata       <= '0;
      rsp_no_response <= 1'b0;
    end else begin
      rsp_valid <= 1'b0;
 
      div_q <= (div_q == DIV_W'(MDC_DIVIDER - 1)) ? '0 : div_q + 1'b1;
      if (mdc_rise) mdc <= 1'b1;
      if (mdc_fall) mdc <= 1'b0;
 
      unique case (state_q)
        M_IDLE: begin
          if (req_valid) begin
            is_read_q <= req_is_read;
            // Assemble the frame once, most-significant bit first.
            shift_q   <= {ST_C22,
                          req_is_read ? OP_C22_READ : OP_C22_WRITE,
                          req_phyad, req_regad,
                          // On a write the master drives TA as 10. On a
                          // read these two bits are not driven at all.
                          2'b10,
                          req_wdata};
            bit_q        <= '0;
            saw_device_q <= 1'b0;
            state_q      <= M_PREAMBLE;
          end
        end
 
        M_PREAMBLE: if (mdc_rise) begin
          if (bit_q == 6'(PREAMBLE_BITS - 1)) begin
            bit_q   <= '0;
            state_q <= M_FRAME;
          end else begin
            bit_q <= bit_q + 1'b1;
          end
        end
 
        M_FRAME: if (mdc_rise) begin
          // Sample on the rising edge; the device drives on the falling one.
          if (is_read_q && (bit_q >= 6'd16)) begin
            rdata_q <= {rdata_q[14:0], mdio_in};
          end
          // During the second TA bit a responding device pulls the line
          // low. Nothing pulling it low means nothing answered.
          if (is_read_q && (bit_q == 6'd15) && !mdio_in) saw_device_q <= 1'b1;
 
          shift_q <= {shift_q[30:0], 1'b0};
 
          if (bit_q == 6'(FRAME_BITS - 1)) state_q <= M_DONE;
          else                             bit_q   <= bit_q + 1'b1;
        end
 
        M_DONE: begin
          rsp_valid       <= 1'b1;
          rsp_rdata       <= rdata_q;
          rsp_no_response <= is_read_q && !saw_device_q;
          state_q         <= M_IDLE;
        end
 
        default: state_q <= M_IDLE;
      endcase
    end
  end
 
endmodule

// SYNTHESIZABLE. Clause 22 MDIO slave.
//
// NO REGISTER MAP IS ENCODED. Register meanings are vendor-specific and
// clause-specific; the module presents a generic read/write port and the
// map lives where it belongs.
//
// The slave's turnaround rule is the EXACT MIRROR of the master's, and the
// two must agree bit for bit. The slave starts driving on the SECOND TA
// bit -- bit 15 -- and drives through the data field. One bit either way
// and the frame still completes, with one bit sampled from contention.
module mdio_slave
  import mdio_pkg::*;
#(
  parameter logic [4:0] MY_PHYAD = 5'd1
) (
  input  logic        rst_n,
  input  logic        mdc,
 
  input  logic        mdio_in,
  output logic        mdio_out,
  output logic        mdio_oe,
 
  // Register file interface. Deliberately generic.
  output logic        reg_wr,
  output logic        reg_rd,
  output logic [4:0]  reg_addr,
  output logic [15:0] reg_wdata,
  input  logic [15:0] reg_rdata,
 
  // A frame addressed to a different device. Counted, because a bus with
  // many devices should see mostly these -- and a device seeing NONE is
  // probably not connected to the bus it thinks it is.
  output logic        frame_not_for_me
);
 
  typedef enum logic [1:0] { S_HUNT, S_FRAME, S_TURN, S_DATA } s_state_e;
 
  s_state_e    state_q;
  logic [5:0]  bit_q;
  logic [31:0] sh_q;
  logic [15:0] rdata_q;
  logic        is_read_q, for_me_q;
  logic [5:0]  ones_q;      // consecutive ones seen, for preamble detection
 
  // Drive only on the second TA bit onward, and only for a read addressed
  // to us. Same bit-index derivation as the master, for the same reason.
  wire drive_c = for_me_q && is_read_q
              && ((state_q == S_TURN) || (state_q == S_DATA));
 
  assign mdio_oe  = drive_c;
  assign mdio_out = (state_q == S_TURN) ? 1'b0        // pull low: "I am here"
                                        : rdata_q[15];
 
  assign reg_addr  = sh_q[9 +: 5];
  assign reg_wdata = sh_q[15:0];
 
  always_ff @(posedge mdc or negedge rst_n) begin
    if (!rst_n) begin
      state_q          <= S_HUNT;
      bit_q            <= '0;
      sh_q             <= '0;
      rdata_q          <= '0;
      is_read_q        <= 1'b0;
      for_me_q         <= 1'b0;
      ones_q           <= '0;
      reg_wr           <= 1'b0;
      reg_rd           <= 1'b0;
      frame_not_for_me <= 1'b0;
    end else begin
      reg_wr           <= 1'b0;
      reg_rd           <= 1'b0;
      frame_not_for_me <= 1'b0;
 
      unique case (state_q)
        S_HUNT: begin
          // A preamble is 32 consecutive ones. Counting them is how a
          // device finds a frame boundary on a bus with no framing signal
          // -- the same evidence-accumulation argument Chapter 3.5 §9 made
          // for block alignment, at a much lower rate.
          if (mdio_in) begin
            if (ones_q >= 6'd31) begin
              ones_q  <= '0;
              bit_q   <= '0;
              state_q <= S_FRAME;
            end else begin
              ones_q <= ones_q + 1'b1;
            end
          end else begin
            ones_q <= '0;
          end
        end
 
        S_FRAME: begin
          sh_q <= {sh_q[30:0], mdio_in};
 
          // Once the address fields have arrived, decide whether this frame
          // is ours and what kind it is.
          if (bit_q == 6'd13) begin
            is_read_q <= (sh_q[11:10] == OP_C22_READ);
            for_me_q  <= (sh_q[9:5] == MY_PHYAD);
            if (sh_q[9:5] != MY_PHYAD) frame_not_for_me <= 1'b1;
          end
 
          if (bit_q == 6'd14) begin
            state_q <= S_TURN;
            if (for_me_q && is_read_q) begin
              reg_rd  <= 1'b1;
              rdata_q <= reg_rdata;
            end
          end
          bit_q <= bit_q + 1'b1;
        end
 
        S_TURN: begin
          state_q <= S_DATA;
          bit_q   <= '0;
        end
 
        S_DATA: begin
          if (is_read_q) rdata_q <= {rdata_q[14:0], 1'b0};
          else           sh_q    <= {sh_q[30:0], mdio_in};
 
          if (bit_q == 6'd15) begin
            if (for_me_q && !is_read_q) reg_wr <= 1'b1;
            state_q  <= S_HUNT;
            for_me_q <= 1'b0;
          end else begin
            bit_q <= bit_q + 1'b1;
          end
        end
      endcase
    end
  end
 
endmodule

// SYNTHESIZABLE. Clause 45 indirect addressing.
//
// Two frames per access: an ADDRESS frame stores a 16-bit register address,
// then a DATA frame reads or writes at it. That buys about 67 million
// addressable registers -- 32 ports x 32 MMDs x 65536 -- from a frame whose
// register field is only 5 bits wide.
//
// THE HAZARD THIS MODULE MAKES VISIBLE: the stored address is PERSISTENT
// STATE, shared by everyone who touches this port. Two software threads
// issuing Clause 45 accesses without coordination corrupt each other --
// one sets an address, the other overwrites it, the first reads the wrong
// register and gets a plausible value.
//
// Nothing in the protocol detects this. Only the sequence counter below
// can, and only if someone looks.
module mdio_c45_addressing
  import mdio_pkg::*;
#(
  parameter int unsigned CNT_W = 20
) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic        frame_valid,
  input  logic [1:0]  frame_op,
  input  logic [4:0]  frame_prtad,
  input  logic [4:0]  frame_devad,
  input  logic [15:0] frame_data,
 
  // The stored address, per MMD. Persistent between transactions.
  output logic [15:0] current_addr [32],
  output logic        addr_valid   [32],
 
  output logic        do_read,
  output logic        do_write,
  output logic [15:0] access_addr,
 
  // ── Observability ───────────────────────────────────────────────────────
  // A data frame arrived for an MMD whose address was never set. The access
  // targets whatever the address register happened to hold -- a plausible
  // value from a wrong register, which is worse than an error.
  output logic             unaddressed_access,
  output logic [CNT_W-1:0] c_unaddressed_access,
 
  // An address frame overwrote an address that had been set and not yet
  // used. Almost always two uncoordinated accessors, and the signature of
  // the hazard above.
  output logic             addr_overwritten,
  output logic [CNT_W-1:0] c_addr_overwritten,
 
  // Address frames against data frames. A ratio near one means every access
  // is paying the two-frame cost; well below one means read-and-increment
  // is being used, which is a 45 percent saving on bulk reads.
  output logic [CNT_W-1:0] c_addr_frames,
  output logic [CNT_W-1:0] c_data_frames
);
 
  logic [15:0] addr_q  [32];
  logic        valid_q [32];
  logic        used_q  [32];
 
  always_comb begin
    unaddressed_access = frame_valid
                      && ((frame_op == OP_C45_READ) || (frame_op == OP_C45_WRITE)
                       || (frame_op == OP_C45_READ_INC))
                      && !valid_q[frame_devad];
 
    addr_overwritten   = frame_valid && (frame_op == OP_C45_ADDR)
                      && valid_q[frame_devad] && !used_q[frame_devad];
 
    do_read     = frame_valid && ((frame_op == OP_C45_READ)
                               || (frame_op == OP_C45_READ_INC));
    do_write    = frame_valid && (frame_op == OP_C45_WRITE);
    access_addr = addr_q[frame_devad];
  end
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int unsigned d = 0; d < 32; d++) begin
        addr_q[d]  <= '0;
        valid_q[d] <= 1'b0;
        used_q[d]  <= 1'b0;
      end
      c_unaddressed_access <= '0;
      c_addr_overwritten   <= '0;
      c_addr_frames        <= '0;
      c_data_frames        <= '0;
    end else if (frame_valid) begin
      unique case (frame_op)
        OP_C45_ADDR: begin
          addr_q[frame_devad]  <= frame_data;
          valid_q[frame_devad] <= 1'b1;
          used_q[frame_devad]  <= 1'b0;
          if (!(&c_addr_frames)) c_addr_frames <= c_addr_frames + 1'b1;
          if (addr_overwritten && !(&c_addr_overwritten))
            c_addr_overwritten <= c_addr_overwritten + 1'b1;
        end
 
        OP_C45_READ_INC: begin
          // The optimisation that makes bulk reads affordable: advance the
          // stored address so the next data frame needs no address frame.
          addr_q[frame_devad] <= addr_q[frame_devad] + 16'd1;
          used_q[frame_devad] <= 1'b1;
          if (!(&c_data_frames)) c_data_frames <= c_data_frames + 1'b1;
        end
 
        default: begin   // READ or WRITE
          used_q[frame_devad] <= 1'b1;
          if (!(&c_data_frames)) c_data_frames <= c_data_frames + 1'b1;
        end
      endcase
 
      if (unaddressed_access && !(&c_unaddressed_access))
        c_unaddressed_access <= c_unaddressed_access + 1'b1;
    end
  end
 
  assign current_addr = addr_q;
  assign addr_valid   = valid_q;
 
endmodule

// SYNTHESIZABLE. Sample age tracking for management reads.
//
// A Clause 22 transaction takes about 26 microseconds at 2.5 MHz; a Clause
// 45 addressed read takes about 52. During that time the link keeps running.
// The value that reaches software describes a moment that has PASSED.
//
// That is not a defect to fix -- it is what a management path is. What IS a
// defect is presenting the value without its age, because software then
// reasons about the link's present state from a stale sample.
//
// Chapter 3.2 §11 built this for optical modules and called it module
// status. It is not module-specific. It is what every management path does.
module mgmt_sample_age #(
  parameter int unsigned FIELDS      = 8,
  parameter int unsigned AGE_W       = 24,
  // Cycles after which a sample is too old to reason from. A link event
  // takes microseconds; a management sweep takes milliseconds.
  parameter int unsigned STALE_AFTER = 250_000
) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic             sample_valid,
  input  logic [$clog2(FIELDS)-1:0] sample_index,
  input  logic [15:0]      sample_data,
  input  logic             sample_failed,   // the read did not complete
 
  output logic [15:0]      value      [FIELDS],
  output logic             has_value  [FIELDS],
  output logic [AGE_W-1:0] age        [FIELDS],
  output logic             is_stale   [FIELDS],
 
  // The oldest field in the set. Software reasoning across several
  // registers is only as current as its oldest sample, and a design that
  // reports per-field ages without this makes that easy to forget.
  output logic [AGE_W-1:0] worst_age,
  output logic [$clog2(FIELDS)-1:0] worst_field,
 
  // A read that never completed. Distinct from a stale value: stale means
  // old, failed means absent, and they need different responses.
  output logic [15:0]      c_read_failed
);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int unsigned f = 0; f < FIELDS; f++) begin
        value[f]     <= '0;
        has_value[f] <= 1'b0;
        age[f]       <= '0;
      end
      c_read_failed <= '0;
    end else begin
      // Every field ages every cycle. Ageing is the default; being fresh
      // is the exception that a completed read produces.
      for (int unsigned f = 0; f < FIELDS; f++) begin
        if (has_value[f] && (age[f] != '1)) age[f] <= age[f] + 1'b1;
      end
 
      if (sample_valid && !sample_failed) begin
        value[sample_index]     <= sample_data;
        has_value[sample_index] <= 1'b1;
        age[sample_index]       <= '0;
      end
 
      if (sample_valid && sample_failed && !(&c_read_failed))
        c_read_failed <= c_read_failed + 1'b1;
    end
  end
 
  always_comb begin
    for (int unsigned f = 0; f < FIELDS; f++)
      is_stale[f] = has_value[f] && (age[f] >= AGE_W'(STALE_AFTER));
 
    worst_age   = '0;
    worst_field = '0;
    for (int unsigned f = 0; f < FIELDS; f++) begin
      if (has_value[f] && (age[f] > worst_age)) begin
        worst_age   = age[f];
        worst_field = ($clog2(FIELDS))'(f);
      end
    end
  end
 
endmodule

// SYNTHESIZABLE INSTRUMENTATION.
//
// Reading an address where NO DEVICE EXISTS returns whatever the pull-up
// gives: all ones. And 0xFFFF is a plausible register value.
//
// So three situations produce the same 16 bits:
//   - no device at that address        -> a configuration or wiring fault
//   - a device that genuinely reads all ones -> normal
//   - a bus stuck high (broken driver, missing pull-down path) -> hardware
//
// The ONLY thing that separates them is whether something pulled the line
// low during turnaround, and whether it did so consistently. That is what
// this module records.
module mdio_bus_telemetry #(
  parameter int unsigned CNT_W = 20
) (
  input  logic clk,
  input  logic rst_n,
  input  logic clear,
 
  input  logic        rsp_valid,
  input  logic        rsp_is_read,
  input  logic [4:0]  rsp_phyad,
  input  logic [15:0] rsp_rdata,
  input  logic        rsp_no_response,   // nothing drove during turnaround
 
  // Per-address evidence. A device that has EVER responded exists; one that
  // never has is absent or misaddressed -- and the two need different
  // investigations, exactly as Chapter 3.1 §9's ever_ready distinguished a
  // broken pair from a marginal one.
  output logic [31:0] device_ever_responded,
  output logic [31:0] device_responding_now,
 
  output logic [CNT_W-1:0] c_reads,
  output logic [CNT_W-1:0] c_no_response,
  // Reads that returned all ones AND had a responder. Normal, and worth
  // separating from the no-responder case so the two are not conflated.
  output logic [CNT_W-1:0] c_all_ones_with_responder,
 
  // Every address on the bus reads all ones with nothing responding. That
  // is not 32 absent devices -- it is one stuck bus, and the distinction
  // is the difference between a wiring check and a driver replacement.
  output logic             bus_stuck_high_suspected,
 
  // A device that responded before and does not now. Distinct from one that
  // never has: this one was working.
  output logic             device_lost,
  output logic [4:0]       lost_address
);
 
  logic [31:0] ever_q, now_q;
  logic [31:0] seen_q;      // addresses actually probed since reset
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      ever_q                    <= '0;
      now_q                     <= '0;
      seen_q                    <= '0;
      c_reads                   <= '0;
      c_no_response             <= '0;
      c_all_ones_with_responder <= '0;
      device_lost               <= 1'b0;
      lost_address              <= '0;
    end else begin
      device_lost <= 1'b0;
 
      if (clear) begin
        c_reads                   <= '0;
        c_no_response             <= '0;
        c_all_ones_with_responder <= '0;
        // ever_q deliberately survives: it is a property of the
        // installation, not of a measurement window.
      end
 
      if (rsp_valid && rsp_is_read) begin
        seen_q[rsp_phyad] <= 1'b1;
        if (!(&c_reads)) c_reads <= c_reads + 1'b1;
 
        if (rsp_no_response) begin
          now_q[rsp_phyad] <= 1'b0;
          if (!(&c_no_response)) c_no_response <= c_no_response + 1'b1;
          // It answered before and does not now. That is a loss, not an
          // absence, and it points at the device rather than the map.
          if (ever_q[rsp_phyad]) begin
            device_lost  <= 1'b1;
            lost_address <= rsp_phyad;
          end
        end else begin
          ever_q[rsp_phyad] <= 1'b1;
          now_q[rsp_phyad]  <= 1'b1;
          if ((rsp_rdata == 16'hFFFF) && !(&c_all_ones_with_responder))
            c_all_ones_with_responder <= c_all_ones_with_responder + 1'b1;
        end
      end
    end
  end
 
  assign device_ever_responded = ever_q;
  assign device_responding_now = now_q;
 
  // Every probed address silent. One stuck bus, not many absent devices.
  assign bus_stuck_high_suspected = (seen_q != '0) && (now_q == '0)
                                 && (ever_q == '0);
 
endmodule

// SYNTHESIZABLE INSTRUMENTATION. Lives in the master.
//
// A testbench can see both output enables and check contention directly.
// SILICON CANNOT -- no device exposes its enable. So this infers from the
// wire's behaviour during the two turnaround bits, which is weaker and is
// what is actually available.
//
// The three things the wire can do during turnaround, and what each means:
//
//   stays high, then data      -> nothing responded. Absent device.
//   goes low on bit 2, data    -> normal. The device announced itself.
//   goes low on bit 1          -> the device drove EARLY, overlapping the
//                                 master's last driven bit. Contention.
//
// The third is the failure that produces reads wrong in one bit position,
// and it is invisible in the returned data because the contended bit is
// usually resolved to a plausible value.
module mdio_turnaround_monitor #(
  parameter int unsigned CNT_W = 16
) (
  input  logic clk,
  input  logic rst_n,
  input  logic clear,
 
  input  logic       frame_active,
  input  logic       is_read,
  input  logic [5:0] bit_index,     // position within the 32-bit frame
  input  logic       mdio_in,
  input  logic       master_oe,
 
  // The device drove during the FIRST turnaround bit, while the master was
  // still driving. Direct contention.
  output logic             contention_detected,
  output logic [CNT_W-1:0] c_contention,
 
  // The device never drove during either turnaround bit. Either absent, or
  // it drove late and the first data bit was sampled from the pull-up.
  output logic             late_or_absent,
  output logic [CNT_W-1:0] c_late_or_absent,
 
  // Turnarounds that behaved exactly as specified. The denominator: a
  // contention rate is meaningless without knowing how many were clean.
  output logic [CNT_W-1:0] c_clean_turnaround,
 
  // Sticky. Contention is intermittent by nature -- it depends on
  // temperature, supply and the exact clock relationship -- so by the time
  // anyone looks it has usually stopped. This bit is what remains.
  output logic             contention_ever
);
 
  // Bit 14 is the first turnaround bit, 15 the second. On a read the master
  // drives through 14 and releases from 15, per Section 4's rule.
  wire ta_first_c  = frame_active && is_read && (bit_index == 6'd14);
  wire ta_second_c = frame_active && is_read && (bit_index == 6'd15);
 
  logic saw_low_first_q, saw_low_second_q;
 
  always_comb begin
    // The device pulling low while the master is still driving.
    contention_detected = ta_first_c && master_oe && !mdio_in;
  end
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      saw_low_first_q    <= 1'b0;
      saw_low_second_q   <= 1'b0;
      c_contention       <= '0;
      c_late_or_absent   <= '0;
      c_clean_turnaround <= '0;
      late_or_absent     <= 1'b0;
      contention_ever    <= 1'b0;
    end else begin
      late_or_absent <= 1'b0;
 
      if (clear) begin
        c_contention       <= '0;
        c_late_or_absent   <= '0;
        c_clean_turnaround <= '0;
        // contention_ever deliberately survives -- see below.
      end
 
      if (ta_first_c) begin
        saw_low_first_q <= !mdio_in;
        if (contention_detected) begin
          if (!(&c_contention)) c_contention <= c_contention + 1'b1;
          contention_ever <= 1'b1;
        end
      end
 
      if (ta_second_c) begin
        saw_low_second_q <= !mdio_in;
 
        // Classify the turnaround now that both bits are known.
        if (!saw_low_first_q && !mdio_in) begin
          // Clean: high through the first, low on the second.
          if (!(&c_clean_turnaround)) c_clean_turnaround <= c_clean_turnaround + 1'b1;
        end else if (!saw_low_first_q && mdio_in) begin
          // Nothing ever drove.
          late_or_absent <= 1'b1;
          if (!(&c_late_or_absent)) c_late_or_absent <= c_late_or_absent + 1'b1;
        end
      end
    end
  end
 
endmodule

// ─── FRAME PROPERTY: Clause 22 field widths and order ──────────────────────
// Published structure. Catches a frame assembled with fields transposed,
// which addresses the wrong register in the wrong device and returns a
// plausible value.
property p_c22_frame_structure;
  @(posedge clk) disable iff (!rst_n)
  (state_q == M_FRAME) && (bit_q == 0) |-> (shift_q[31:30] == ST_C22);
endproperty
 
// ─── FRAME PROPERTY: the read opcode is 10, write is 01 ────────────────────
// Catches the two transposed, which turns every read into a write to the
// same address -- corrupting configuration while appearing to read it.
property p_c22_opcode;
  @(posedge clk) disable iff (!rst_n)
  (state_q == M_FRAME) && (bit_q == 0)
    |-> (shift_q[29:28] == (is_read_q ? OP_C22_READ : OP_C22_WRITE));
endproperty
 
// ─── Safety: the master releases the wire before the device drives ─────────
// THE property of this chapter. Catches an overlap of even one bit time,
// which produces contention and a read that is usually correct and
// occasionally wrong in the same bit position.
property p_master_releases_for_read;
  @(posedge clk) disable iff (!rst_n)
  (is_read_q && (state_q == M_FRAME) && (bit_q >= 15)) |-> !mdio_oe;
endproperty
 
// ─── Safety: the slave drives only its own read data ───────────────────────
// The mirror. Catches a slave driving on a frame addressed elsewhere, which
// corrupts another device's response.
property p_slave_drives_only_when_addressed;
  @(posedge mdc) disable iff (!rst_n)
  mdio_oe |-> (for_me_q && is_read_q);
endproperty
 
// ─── Mutual exclusion: never two drivers ───────────────────────────────────
// The contention check itself, expressible only where both enables are
// visible -- so it is a testbench property, and Section 10's note explains
// why that is acceptable here and was not in Chapter 4.1.
property p_never_two_drivers;
  @(posedge mdc) disable iff (!rst_n)
  !(master_oe && slave_oe);
endproperty
 
// ─── Ordering: a data frame follows an address frame ───────────────────────
// Clause 45's sequence. Catches a data frame issued with no address set,
// which accesses whatever the pointer held -- a plausible value from a
// wrong register.
property p_c45_data_needs_address;
  @(posedge clk) disable iff (!rst_n)
  (do_read || do_write) |-> addr_valid[frame_devad];
endproperty
 
// ─── Causation: read-and-increment advances the address ────────────────────
// Catches an increment that does not happen, turning a bulk sweep into
// repeated reads of one register -- which returns plausible data and looks
// like a device whose counters are stuck.
property p_read_inc_advances;
  @(posedge clk) disable iff (!rst_n)
  (frame_valid && (frame_op == OP_C45_READ_INC))
    |=> (current_addr[$past(frame_devad)] == $past(current_addr[$past(frame_devad)]) + 1);
endproperty
 
// ─── Safety: ageing is the default ─────────────────────────────────────────
// Catches an implementation where freshness must be actively detected,
// which will forget to detect it somewhere and present a stale value as
// current.
property p_fields_age_by_default;
  @(posedge clk) disable iff (!rst_n)
  (has_value[0] && !(sample_valid && (sample_index == 0)))
    |=> (age[0] >= $past(age[0]));
endproperty
 
// ─── Causation: only a completed read resets an age ────────────────────────
// Catches a failed read resetting the age, which presents an absent value
// as a fresh one.
property p_failed_read_does_not_refresh;
  @(posedge clk) disable iff (!rst_n)
  (sample_valid && sample_failed) |=> (age[$past(sample_index)] != 0);
endproperty
 
// ─── Conservation: worst_age is the maximum over valid fields ──────────────
// Catches a worst-age that ignores a field, after which software reasoning
// across registers believes its conclusion is fresher than it is.
property p_worst_age_is_max;
  @(posedge clk) disable iff (!rst_n)
  has_value[0] |-> (worst_age >= age[0]);
endproperty
 
// ─── Causation: no-response requires no turnaround drive ───────────────────
// Catches a design inferring absence from the DATA rather than from the
// turnaround, which cannot distinguish an absent device from one reporting
// all ones.
property p_no_response_from_turnaround;
  @(posedge clk) disable iff (!rst_n)
  rsp_no_response |-> !$past(saw_device_q);
endproperty
 
// ─── Stability: the ever-responded history survives a clear ────────────────
// Catches it folded into the clear branch, destroying the distinction
// between a device that failed and one that was never there.
property p_ever_responded_sticky;
  @(posedge clk) disable iff (!rst_n)
  clear |=> (device_ever_responded == $past(device_ever_responded));
endproperty
 
// ─── Safety: a stuck bus is not reported as many absent devices ────────────
// Catches the conclusion that 32 devices are missing, which sends someone
// to check a device map instead of one pull-up.
property p_stuck_bus_not_absent_devices;
  @(posedge clk) disable iff (!rst_n)
  bus_stuck_high_suspected |-> (device_ever_responded == '0);
endproperty
 
// ─── Causation: contention is inferred only during turnaround ──────────────
// Catches a monitor that flags contention on data bits, where the device is
// legitimately driving and the master is not.
property p_contention_only_in_turnaround;
  @(posedge clk) disable iff (!rst_n)
  contention_detected |-> (bit_index == 6'd14) && master_oe;
endproperty
 
// ─── Stability: the contention history survives a clear ────────────────────
// Contention is intermittent and usually not happening when anyone looks.
// Catches the sticky bit folded into the clear branch, removing the only
// evidence that remains.
property p_contention_ever_sticky;
  @(posedge clk) disable iff (!rst_n)
  contention_ever |=> contention_ever;
endproperty