The Ethernet MAC as an SoC IP Block

// -----------------------------------------------------------------------
// macsoc_pkg -- shared types for an Ethernet MAC as an SoC IP block.
// -----------------------------------------------------------------------
package macsoc_pkg;

  localparam int ADDR_W   = 64;          // host physical address
  localparam int REG_AW   = 12;          // 4 KiB register window
  localparam int DATA_W   = 32;          // register data width
  localparam int NUM_CNT  = 16;          // RMON-style counters -- 19.7

  // The register map, kept deliberately small. Everything an operator
  // needs in the steady state is a counter; everything else is written
  // once at bring-up.
  typedef enum logic [REG_AW-1:0] {
    REG_CTRL        = 12'h000,
    REG_STATUS      = 12'h004,
    REG_RX_RING_LO  = 12'h010,
    REG_RX_RING_HI  = 12'h014,
    REG_RX_RING_LEN = 12'h018,
    REG_TX_RING_LO  = 12'h020,
    REG_TX_RING_HI  = 12'h024,
    REG_TX_RING_LEN = 12'h028,
    REG_IRQ_EN      = 12'h030,
    REG_IRQ_STATUS  = 12'h034,
    REG_COALESCE    = 12'h038,
    REG_CNT_BASE    = 12'h100
  } reg_addr_e;

  // Which domain a register's CONTENT lives in. Section 6's subject,
  // and the reason this file is not a simple array of flops.
  typedef enum logic [1:0] {
    DOM_HOST = 2'd0,                     // the bus clock -- no crossing
    DOM_RX   = 2'd1,                     // the receive recovered clock
    DOM_TX   = 2'd2,                     // the transmit clock
    DOM_PTP  = 2'd3                      // 16.3's timestamp clock
  } domain_e;

  typedef struct packed {
    logic        enable;
    logic        promiscuous;
    logic        loopback;
    logic [15:0] max_frame;              // 5.4's MTU
  } ctrl_t;

endpackage

// -----------------------------------------------------------------------
// mac_register_file -- the CPU-facing slave.
//
// Configuration flows OUT of the host domain and is synchronised into
// the domains that use it. Counters flow IN from other domains and are
// synchronised on the way back. Neither direction is a simple flop,
// and section 19's rejected property is about what happens when a
// verification engineer forgets that.
// -----------------------------------------------------------------------
module mac_register_file
  import macsoc_pkg::*;
(
  input  logic                clk_host,
  input  logic                rst_host_n,

  // APB-style slave -- deliberately the simplest possible.
  input  logic                psel,
  input  logic                penable,
  input  logic                pwrite,
  input  logic [REG_AW-1:0]   paddr,
  input  logic [DATA_W-1:0]   pwdata,
  output logic [DATA_W-1:0]   prdata,
  output logic                pready,
  output logic                pslverr,

  // Configuration out, in the HOST domain. Every consumer synchronises.
  output ctrl_t               cfg_ctrl,
  output logic [ADDR_W-1:0]   cfg_rx_ring_base,
  output logic [ADDR_W-1:0]   cfg_tx_ring_base,
  output logic [15:0]         cfg_rx_ring_len,
  output logic [15:0]         cfg_tx_ring_len,
  output logic [31:0]         cfg_coalesce,

  // Counters in, ALREADY synchronised by their owners. This module
  // does not cross domains itself; it refuses to hold a value that
  // has not been handed to it in its own clock.
  input  logic [31:0]         cnt_value  [NUM_CNT],
  input  logic                cnt_valid  [NUM_CNT],

  input  logic [31:0]         irq_status_sync,
  output logic [31:0]         irq_enable,
  output logic                irq_ack,

  output logic                cfg_write_while_enabled
);

  ctrl_t             ctrl_q;
  logic [ADDR_W-1:0] rx_base_q, tx_base_q;
  logic [15:0]       rx_len_q,  tx_len_q;
  logic [31:0]       coalesce_q, irq_en_q;
  logic [31:0]       cnt_shadow [NUM_CNT];

  wire access = psel && penable;
  wire wr     = access && pwrite;

  // A ring base written while the MAC is enabled is the classic
  // integration bug: the DMA is mid-descriptor against the old base
  // and the next fetch uses the new one. The register file cannot
  // prevent it -- it can only refuse it and say so.
  assign cfg_write_while_enabled =
    wr && ctrl_q.enable &&
    (paddr == REG_RX_RING_LO || paddr == REG_RX_RING_HI ||
     paddr == REG_TX_RING_LO || paddr == REG_TX_RING_HI ||
     paddr == REG_RX_RING_LEN || paddr == REG_TX_RING_LEN);

  always_ff @(posedge clk_host or negedge rst_host_n) begin
    int i;
    if (!rst_host_n) begin
      ctrl_q     <= '0;
      rx_base_q  <= '0; tx_base_q <= '0;
      rx_len_q   <= '0; tx_len_q  <= '0;
      coalesce_q <= '0; irq_en_q  <= '0;
      irq_ack    <= 1'b0;
      for (i = 0; i < NUM_CNT; i++) cnt_shadow[i] <= '0;
    end else begin
      irq_ack <= 1'b0;

      // Counters land here only when their owner asserts valid, which
      // that owner does from ITS synchroniser's output. The shadow is
      // therefore always a value that was coherent at some instant --
      // just not necessarily this one.
      for (i = 0; i < NUM_CNT; i++)
        if (cnt_valid[i]) cnt_shadow[i] <= cnt_value[i];

      if (wr && !cfg_write_while_enabled) begin
        case (paddr)
          REG_CTRL:        {ctrl_q.max_frame, ctrl_q.loopback,
                            ctrl_q.promiscuous, ctrl_q.enable}
                             <= pwdata[18:0];
          REG_RX_RING_LO:  rx_base_q[31:0]  <= pwdata;
          REG_RX_RING_HI:  rx_base_q[63:32] <= pwdata;
          REG_RX_RING_LEN: rx_len_q         <= pwdata[15:0];
          REG_TX_RING_LO:  tx_base_q[31:0]  <= pwdata;
          REG_TX_RING_HI:  tx_base_q[63:32] <= pwdata;
          REG_TX_RING_LEN: tx_len_q         <= pwdata[15:0];
          REG_IRQ_EN:      irq_en_q         <= pwdata;
          REG_COALESCE:    coalesce_q       <= pwdata;
          REG_IRQ_STATUS:  irq_ack          <= 1'b1;   // write-1-to-clear
          default: ;
        endcase
      end
    end
  end

  always_comb begin
    prdata  = '0;
    pslverr = 1'b0;
    if (paddr >= REG_CNT_BASE && paddr < REG_CNT_BASE + (NUM_CNT * 4))
      prdata = cnt_shadow[(paddr - REG_CNT_BASE) >> 2];
    else begin
      case (paddr)
        REG_CTRL:        prdata = {13'b0, ctrl_q.max_frame, ctrl_q.loopback,
                                   ctrl_q.promiscuous, ctrl_q.enable};
        REG_STATUS:      prdata = {31'b0, ctrl_q.enable};
        REG_RX_RING_LO:  prdata = rx_base_q[31:0];
        REG_RX_RING_HI:  prdata = rx_base_q[63:32];
        REG_RX_RING_LEN: prdata = {16'b0, rx_len_q};
        REG_TX_RING_LO:  prdata = tx_base_q[31:0];
        REG_TX_RING_HI:  prdata = tx_base_q[63:32];
        REG_TX_RING_LEN: prdata = {16'b0, tx_len_q};
        REG_IRQ_EN:      prdata = irq_en_q;
        REG_IRQ_STATUS:  prdata = irq_status_sync;
        REG_COALESCE:    prdata = coalesce_q;
        default:         pslverr = access && !pwrite;
      endcase
    end
  end

  assign pready           = 1'b1;
  assign cfg_ctrl         = ctrl_q;
  assign cfg_rx_ring_base = rx_base_q;
  assign cfg_tx_ring_base = tx_base_q;
  assign cfg_rx_ring_len  = rx_len_q;
  assign cfg_tx_ring_len  = tx_len_q;
  assign cfg_coalesce     = coalesce_q;
  assign irq_enable       = irq_en_q;

endmodule

// -----------------------------------------------------------------------
// mac_memory_master -- the MAC's bus-mastering front end.
//
// It accepts logical requests (fetch this descriptor, write this frame
// data, post this status) and issues bus transactions. It enforces the
// two rules the bus imposes and the MAC does not naturally respect:
// a burst may not cross a 4 KiB boundary, and the number of
// outstanding transactions is bounded.
// -----------------------------------------------------------------------
module mac_memory_master
  import macsoc_pkg::*;
#(
  parameter int BUS_BYTES    = 32,       // 256-bit data bus
  parameter int MAX_OUTSTAND = 16,
  parameter int MAX_BEATS    = 16
)(
  input  logic               clk,
  input  logic               rst_n,

  // Logical request in.
  input  logic               req_valid,
  output logic               req_ready,
  input  logic               req_write,
  input  logic [ADDR_W-1:0]  req_addr,
  input  logic [15:0]        req_bytes,
  input  logic [1:0]         req_kind,   // 0 desc, 1 data, 2 status

  // Bus address channel out.
  output logic               ax_valid,
  input  logic               ax_ready,
  output logic               ax_write,
  output logic [ADDR_W-1:0]  ax_addr,
  output logic [7:0]         ax_len,     // beats minus one
  output logic [2:0]         ax_size,

  // Completion in -- one per issued transaction.
  input  logic               done_valid,
  input  logic               done_error,

  output logic [31:0]        c_txn_desc,
  output logic [31:0]        c_txn_data,
  output logic [31:0]        c_txn_status,
  output logic [31:0]        c_split_4k,
  output logic [31:0]        c_stall_outstanding,
  output logic [31:0]        c_bus_error,
  output logic               outstanding_full
);

  localparam int SIZE_ENC = $clog2(BUS_BYTES);

  logic [ADDR_W-1:0] cur_addr;
  logic [15:0]       cur_bytes;
  logic [1:0]        cur_kind;
  logic              busy;

  logic [$clog2(MAX_OUTSTAND+1)-1:0] outstanding;

  // How many bytes may this burst cover before the 4 KiB boundary?
  // A burst that crosses one is illegal on AXI and the MAC has no
  // reason to respect a boundary it cannot see -- a frame lands
  // wherever the descriptor's buffer pointer says.
  logic [12:0] to_boundary;
  assign to_boundary = 13'h1000 - {1'b0, cur_addr[11:0]};

  logic [15:0] max_burst_bytes;
  assign max_burst_bytes = MAX_BEATS * BUS_BYTES;

  logic [15:0] this_burst;
  always_comb begin
    this_burst = cur_bytes;
    if (this_burst > max_burst_bytes) this_burst = max_burst_bytes;
    if (this_burst > {3'b0, to_boundary}) this_burst = {3'b0, to_boundary};
  end

  assign outstanding_full = (outstanding == MAX_OUTSTAND[$bits(outstanding)-1:0]);
  assign req_ready        = !busy;

  assign ax_valid = busy && !outstanding_full;
  assign ax_write = (cur_kind != 2'd0);          // only a fetch reads
  assign ax_addr  = cur_addr;
  assign ax_size  = SIZE_ENC[2:0];
  assign ax_len   = (( this_burst + BUS_BYTES - 1) / BUS_BYTES) - 1;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      busy <= 1'b0; cur_addr <= '0; cur_bytes <= '0; cur_kind <= '0;
      outstanding <= '0;
      c_txn_desc <= '0; c_txn_data <= '0; c_txn_status <= '0;
      c_split_4k <= '0; c_stall_outstanding <= '0; c_bus_error <= '0;
    end else begin
      if (!busy && req_valid) begin
        busy      <= 1'b1;
        cur_addr  <= req_addr;
        cur_bytes <= req_bytes;
        cur_kind  <= req_kind;
      end

      if (busy && outstanding_full)
        c_stall_outstanding <= c_stall_outstanding + 1;

      if (ax_valid && ax_ready) begin
        outstanding <= outstanding + 1;

        case (cur_kind)
          2'd0: c_txn_desc   <= c_txn_desc   + 1;
          2'd1: c_txn_data   <= c_txn_data   + 1;
          default: c_txn_status <= c_txn_status + 1;
        endcase

        // A split happened if the boundary, not the beat limit, was
        // what shortened this burst. Counting it separately is what
        // makes a misaligned buffer pool visible.
        if ({3'b0, to_boundary} < cur_bytes &&
            {3'b0, to_boundary} < max_burst_bytes)
          c_split_4k <= c_split_4k + 1;

        if (this_burst >= cur_bytes) begin
          busy      <= 1'b0;
          cur_bytes <= '0;
        end else begin
          cur_addr  <= cur_addr  + {{(ADDR_W-16){1'b0}}, this_burst};
          cur_bytes <= cur_bytes - this_burst;
        end
      end

      if (done_valid) begin
        outstanding <= outstanding - 1;
        if (done_error) c_bus_error <= c_bus_error + 1;
      end

      // Simultaneous issue and completion cancel.
      if (ax_valid && ax_ready && done_valid)
        outstanding <= outstanding;
    end
  end

endmodule

// -----------------------------------------------------------------------
// phy_boundary_adapter -- normalises the xMII family to one internal
// interface.
//
// MII, GMII, XGMII, XXVGMII and CGMII differ in width and clock and
// agree on almost nothing else. Everything above this module sees a
// width-W stream with a start, an end and a byte-enable on the last
// beat. Everything below sees the standard's signalling.
// -----------------------------------------------------------------------
module phy_boundary_adapter
  import macsoc_pkg::*;
#(
  parameter int XMII_BYTES = 8,          // 1 = MII/GMII, 8 = XGMII, 64 = CGMII
  parameter int INT_BYTES  = 8
)(
  input  logic                      clk_rx,     // RECOVERED from the wire
  input  logic                      rst_rx_n,

  // xMII receive side.
  input  logic [XMII_BYTES*8-1:0]   xgmii_rxd,
  input  logic [XMII_BYTES-1:0]     xgmii_rxc,  // control, not data
  input  logic                      rx_clk_present,

  // Normalised internal stream out, still in clk_rx.
  output logic                      s_valid,
  output logic [INT_BYTES*8-1:0]    s_data,
  output logic [$clog2(INT_BYTES+1)-1:0] s_bytes,
  output logic                      s_sof,
  output logic                      s_eof,
  output logic                      s_error,

  output logic [31:0]               c_sof,
  output logic [31:0]               c_eof,
  output logic [31:0]               c_local_fault,
  output logic [31:0]               c_clock_lost,
  output logic                      rx_clock_stopped
);

  // The control characters that matter. 4.2's SFD does not appear on
  // XGMII -- the start control character replaces it, which is one of
  // the family's least obvious incompatibilities.
  localparam logic [7:0] XG_START = 8'hFB;
  localparam logic [7:0] XG_TERM  = 8'hFD;
  localparam logic [7:0] XG_ERROR = 8'hFE;
  localparam logic [7:0] XG_IDLE  = 8'h07;

  logic in_frame;

  // A recovered clock that stops is not an error condition on the
  // wire -- it is the partner having stopped transmitting, or the
  // cable having been removed. It is, however, fatal to anything
  // clocked by it, which is why the detector lives in the HOST
  // domain in a real design and is modelled here as an input.
  assign rx_clock_stopped = !rx_clk_present;

  logic [INT_BYTES-1:0] is_start, is_term, is_error;
  always_comb begin
    int i;
    for (i = 0; i < INT_BYTES; i++) begin
      is_start[i] = xgmii_rxc[i] && (xgmii_rxd[i*8 +: 8] == XG_START);
      is_term[i]  = xgmii_rxc[i] && (xgmii_rxd[i*8 +: 8] == XG_TERM);
      is_error[i] = xgmii_rxc[i] && (xgmii_rxd[i*8 +: 8] == XG_ERROR);
    end
  end

  // How many bytes of this beat belong to the frame? Everything up to
  // the terminate character.
  logic [$clog2(INT_BYTES+1)-1:0] bytes_this_beat;
  always_comb begin
    int i;
    bytes_this_beat = INT_BYTES[$bits(bytes_this_beat)-1:0];
    for (i = INT_BYTES-1; i >= 0; i--)
      if (is_term[i]) bytes_this_beat = i[$bits(bytes_this_beat)-1:0];
  end

  always_ff @(posedge clk_rx or negedge rst_rx_n) begin
    if (!rst_rx_n) begin
      in_frame <= 1'b0;
      s_valid <= 1'b0; s_sof <= 1'b0; s_eof <= 1'b0; s_error <= 1'b0;
      s_data <= '0; s_bytes <= '0;
      c_sof <= '0; c_eof <= '0; c_local_fault <= '0; c_clock_lost <= '0;
    end else begin
      s_valid <= 1'b0; s_sof <= 1'b0; s_eof <= 1'b0; s_error <= 1'b0;

      if (rx_clock_stopped) begin
        c_clock_lost <= c_clock_lost + 1;
        in_frame     <= 1'b0;
      end else if (|is_start && !in_frame) begin
        in_frame <= 1'b1;
        s_valid  <= 1'b1;
        s_sof    <= 1'b1;
        s_data   <= xgmii_rxd;
        s_bytes  <= INT_BYTES[$bits(s_bytes)-1:0];
        c_sof    <= c_sof + 1;
      end else if (in_frame) begin
        s_valid <= 1'b1;
        s_data  <= xgmii_rxd;
        if (|is_term) begin
          in_frame <= 1'b0;
          s_eof    <= 1'b1;
          s_bytes  <= bytes_this_beat;
          c_eof    <= c_eof + 1;
        end else begin
          s_bytes <= INT_BYTES[$bits(s_bytes)-1:0];
        end
        if (|is_error) begin
          s_error       <= 1'b1;
          c_local_fault <= c_local_fault + 1;
        end
      end
    end
  end

endmodule

// -----------------------------------------------------------------------
// async_fifo_cdc -- the receive-to-host frame crossing.
//
// Gray-coded pointers, two-flop synchronisers, and a deliberately
// pessimistic full/empty. The pessimism is the point: a synchronised
// pointer is always STALE, so the reader sees fewer entries than
// exist and the writer sees less space than exists. Both errors are
// safe; the opposite of either is not.
// -----------------------------------------------------------------------
module async_fifo_cdc
  import macsoc_pkg::*;
#(
  parameter int WIDTH = 72,              // 64 data + 8 control
  parameter int DEPTH = 512              // must be a power of two
)(
  // Write side -- the recovered receive clock.
  input  logic               clk_w,
  input  logic               rst_w_n,
  input  logic               w_en,
  input  logic [WIDTH-1:0]   w_data,
  output logic               w_full,
  output logic [31:0]        c_overflow,

  // Read side -- the host clock.
  input  logic               clk_r,
  input  logic               rst_r_n,
  input  logic               r_en,
  output logic [WIDTH-1:0]   r_data,
  output logic               r_empty,
  output logic [31:0]        c_underflow
);

  localparam int AW = $clog2(DEPTH);

  logic [WIDTH-1:0] mem [DEPTH];

  logic [AW:0] w_bin, w_gray, w_gray_r1, w_gray_r2;
  logic [AW:0] r_bin, r_gray, r_gray_w1, r_gray_w2;

  function automatic logic [AW:0] to_gray(input logic [AW:0] b);
    return b ^ (b >> 1);
  endfunction

  // ---- write side -------------------------------------------------
  wire [AW:0] w_bin_next = w_bin + {{AW{1'b0}}, (w_en && !w_full)};

  always_ff @(posedge clk_w or negedge rst_w_n) begin
    if (!rst_w_n) begin
      w_bin <= '0; w_gray <= '0; c_overflow <= '0;
      r_gray_w1 <= '0; r_gray_w2 <= '0;
    end else begin
      if (w_en && !w_full) mem[w_bin[AW-1:0]] <= w_data;
      if (w_en &&  w_full) c_overflow <= c_overflow + 1;
      w_bin  <= w_bin_next;
      w_gray <= to_gray(w_bin_next);

      // The read pointer arrives here two flops late. Everything the
      // write side believes about the FIFO's occupancy is therefore
      // at least two read-clock periods out of date -- and that is
      // exactly why it is safe.
      r_gray_w1 <= r_gray;
      r_gray_w2 <= r_gray_w1;
    end
  end

  // Full: the write pointer has wrapped onto the read pointer. In
  // Gray code that is the top two bits inverted and the rest equal.
  assign w_full = (w_gray == {~r_gray_w2[AW:AW-1], r_gray_w2[AW-2:0]});

  // ---- read side --------------------------------------------------
  wire [AW:0] r_bin_next = r_bin + {{AW{1'b0}}, (r_en && !r_empty)};

  always_ff @(posedge clk_r or negedge rst_r_n) begin
    if (!rst_r_n) begin
      r_bin <= '0; r_gray <= '0; c_underflow <= '0;
      w_gray_r1 <= '0; w_gray_r2 <= '0;
    end else begin
      if (r_en && r_empty) c_underflow <= c_underflow + 1;
      r_bin  <= r_bin_next;
      r_gray <= to_gray(r_bin_next);
      w_gray_r1 <= w_gray;
      w_gray_r2 <= w_gray_r1;
    end
  end

  assign r_empty = (r_gray == w_gray_r2);
  assign r_data  = mem[r_bin[AW-1:0]];

endmodule

// -----------------------------------------------------------------------
// mac_interrupt_iface -- event aggregation, masking and coalescing.
//
// The coalescing here is deliberately minimal -- a count threshold
// and a timer, which is the smallest thing that bounds both the CPU
// cost and the latency. Chapter 18.6's is adaptive.
// -----------------------------------------------------------------------
module mac_interrupt_iface
  import macsoc_pkg::*;
#(
  parameter int NUM_EVENTS = 8
)(
  input  logic                   clk_host,
  input  logic                   rst_host_n,

  // Events, ALREADY in the host domain. Anything arriving from the
  // receive or transmit domain has been through a handshake first.
  input  logic [NUM_EVENTS-1:0]  evt,

  // Which event indices are "a frame completed" and therefore
  // subject to coalescing. Errors are never coalesced.
  input  logic [NUM_EVENTS-1:0]  evt_coalescable,

  input  logic [31:0]            cfg_coalesce,   // {timer_us, count}
  input  logic [31:0]            irq_enable,
  input  logic                   irq_ack,
  input  logic                   tick_1us,

  output logic                   irq,
  output logic [31:0]            irq_status,

  output logic [31:0]            c_irq_raised,
  output logic [31:0]            c_irq_by_count,
  output logic [31:0]            c_irq_by_timer,
  output logic [31:0]            c_events_total,
  output logic                   coalesce_misconfigured
);

  wire [15:0] cfg_count    = cfg_coalesce[15:0];
  wire [15:0] cfg_timer_us = cfg_coalesce[31:16];

  // A count threshold with no timer stalls whenever the traffic stops
  // one frame short. This is the single most common coalescing
  // misconfiguration and the design can see it at configuration time.
  assign coalesce_misconfigured = (cfg_count > 16'd1) && (cfg_timer_us == '0);

  logic [15:0] pending_count;
  logic [15:0] timer_us;
  logic [31:0] status_q;

  wire [NUM_EVENTS-1:0] evt_masked  = evt & irq_enable[NUM_EVENTS-1:0];
  wire [NUM_EVENTS-1:0] evt_coal    = evt_masked &  evt_coalescable;
  wire [NUM_EVENTS-1:0] evt_urgent  = evt_masked & ~evt_coalescable;

  wire count_reached = (pending_count >= cfg_count) && (cfg_count != '0);
  wire timer_expired = (timer_us    >= cfg_timer_us) && (cfg_timer_us != '0)
                       && (pending_count != '0);

  always_ff @(posedge clk_host or negedge rst_host_n) begin
    if (!rst_host_n) begin
      pending_count <= '0; timer_us <= '0; status_q <= '0; irq <= 1'b0;
      c_irq_raised <= '0; c_irq_by_count <= '0; c_irq_by_timer <= '0;
      c_events_total <= '0;
    end else begin
      c_events_total <= c_events_total + $countones(evt);

      // Urgent events -- errors, overflow, a bus fault -- go straight
      // through. Coalescing an error is how a design turns a
      // diagnosable fault into a mysterious one.
      if (|evt_urgent) begin
        status_q <= status_q | {{(32-NUM_EVENTS){1'b0}}, evt_urgent};
        irq      <= 1'b1;
        if (!irq) c_irq_raised <= c_irq_raised + 1;
      end

      if (|evt_coal) begin
        status_q      <= status_q | {{(32-NUM_EVENTS){1'b0}}, evt_coal};
        pending_count <= pending_count + $countones(evt_coal);
      end

      if (tick_1us && pending_count != '0)
        timer_us <= timer_us + 1;

      if (count_reached || timer_expired) begin
        irq           <= 1'b1;
        pending_count <= '0;
        timer_us      <= '0;
        if (!irq) c_irq_raised <= c_irq_raised + 1;
        if (count_reached) c_irq_by_count <= c_irq_by_count + 1;
        else               c_irq_by_timer <= c_irq_by_timer + 1;
      end

      if (irq_ack) begin
        irq      <= 1'b0;
        status_q <= '0;
      end
    end
  end

  assign irq_status = status_q;

endmodule

// -----------------------------------------------------------------------
// mac_datapath_fifos -- occupancy accounting and watermarks for the
// receive and transmit paths.
//
// The depths are elsewhere (section 9). What lives here is the part
// integration gets wrong: WHEN to tell the far end to stop, and how
// much must remain free after telling it.
// -----------------------------------------------------------------------
module mac_datapath_fifos
  import macsoc_pkg::*;
#(
  parameter int RX_DEPTH_B  = 16384,     // octets
  parameter int TX_DEPTH_B  = 16384
)(
  input  logic               clk_host,
  input  logic               rst_host_n,

  input  logic [15:0]        rx_occupancy_b,   // synchronised in
  input  logic [15:0]        tx_occupancy_b,

  // 14.2's headroom, in octets, for this line rate. The integrator
  // supplies it because it depends on the CABLE, not on the MAC.
  input  logic [15:0]        cfg_headroom_b,

  input  logic               cfg_flow_control_en,

  output logic               xoff_request,
  output logic               rx_nearly_full,
  output logic               tx_starving,

  output logic [31:0]        c_xoff_asserted,
  output logic [31:0]        c_rx_high_water,
  output logic [31:0]        c_tx_underrun_risk,
  output logic               headroom_impossible
);

  // The watermark is the depth minus the headroom. If the headroom
  // exceeds the depth there is no watermark that works: by the time
  // the far end stops, the FIFO has already overflowed. This is a
  // CONFIGURATION fault and it is silent without this flag.
  wire [16:0] watermark = {1'b0, RX_DEPTH_B[15:0]} - {1'b0, cfg_headroom_b};
  assign headroom_impossible = (cfg_headroom_b >= RX_DEPTH_B[15:0]);

  assign rx_nearly_full = !headroom_impossible &&
                          ({1'b0, rx_occupancy_b} >= watermark);

  assign xoff_request   = cfg_flow_control_en && rx_nearly_full;

  // A transmit FIFO that empties mid-frame causes an underrun, which
  // corrupts a frame already on the wire -- 7.3's subject. The risk
  // threshold is one maximum frame's worth still unsent.
  assign tx_starving = (tx_occupancy_b < 16'd1518) && (tx_occupancy_b != '0);

  always_ff @(posedge clk_host or negedge rst_host_n) begin
    if (!rst_host_n) begin
      c_xoff_asserted <= '0; c_rx_high_water <= '0; c_tx_underrun_risk <= '0;
    end else begin
      if (xoff_request) c_xoff_asserted <= c_xoff_asserted + 1;
      if ({16'b0, rx_occupancy_b} > c_rx_high_water)
        c_rx_high_water <= {16'b0, rx_occupancy_b};
      if (tx_starving) c_tx_underrun_risk <= c_tx_underrun_risk + 1;
    end
  end

endmodule

// -----------------------------------------------------------------------
// soc_integration_telemetry -- one handshake, a whole counter set.
//
// Section 6: at 100 Gb/s, 4.46 frames arrive during a single
// synchroniser round trip. Crossing per counter per update is not
// possible; crossing the SET on request is.
// -----------------------------------------------------------------------
module soc_integration_telemetry
  import macsoc_pkg::*;
#(
  parameter int NUM_CNT_LOCAL = 8
)(
  // Source domain -- one instance per domain, parameterised.
  input  logic                clk_src,
  input  logic                rst_src_n,
  input  logic [31:0]         cnt_src [NUM_CNT_LOCAL],

  // Host domain.
  input  logic                clk_host,
  input  logic                rst_host_n,
  input  logic                req,                 // host asks for a snapshot
  output logic [31:0]         cnt_host [NUM_CNT_LOCAL],
  output logic                cnt_host_valid,

  output logic [31:0]         c_snapshots,
  output logic [31:0]         c_req_while_busy
);

  // ---- request crossing: host -> source ---------------------------
  logic req_tgl_host, req_tgl_s1, req_tgl_s2, req_tgl_s3;
  logic busy_host;

  always_ff @(posedge clk_host or negedge rst_host_n) begin
    if (!rst_host_n) begin
      req_tgl_host <= 1'b0; busy_host <= 1'b0; c_req_while_busy <= '0;
    end else begin
      if (req && !busy_host) begin
        req_tgl_host <= ~req_tgl_host;
        busy_host    <= 1'b1;
      end else if (req && busy_host) begin
        c_req_while_busy <= c_req_while_busy + 1;
      end
    end
  end

  always_ff @(posedge clk_src or negedge rst_src_n) begin
    if (!rst_src_n) begin
      req_tgl_s1 <= 1'b0; req_tgl_s2 <= 1'b0; req_tgl_s3 <= 1'b0;
    end else begin
      req_tgl_s1 <= req_tgl_host;
      req_tgl_s2 <= req_tgl_s1;
      req_tgl_s3 <= req_tgl_s2;
    end
  end

  wire req_pulse_src = req_tgl_s2 ^ req_tgl_s3;

  // ---- the snapshot ----------------------------------------------
  // Taken in ONE source-clock cycle. Every counter in the set is
  // therefore consistent with every other, which is the entire
  // reason this block exists rather than a synchroniser per counter.
  logic [31:0] snap [NUM_CNT_LOCAL];
  logic        ack_tgl_src;

  always_ff @(posedge clk_src or negedge rst_src_n) begin
    int i;
    if (!rst_src_n) begin
      for (i = 0; i < NUM_CNT_LOCAL; i++) snap[i] <= '0;
      ack_tgl_src <= 1'b0;
    end else if (req_pulse_src) begin
      for (i = 0; i < NUM_CNT_LOCAL; i++) snap[i] <= cnt_src[i];
      ack_tgl_src <= ~ack_tgl_src;
    end
  end

  // ---- acknowledge crossing: source -> host -----------------------
  logic ack_tgl_h1, ack_tgl_h2, ack_tgl_h3;

  always_ff @(posedge clk_host or negedge rst_host_n) begin
    int i;
    if (!rst_host_n) begin
      ack_tgl_h1 <= 1'b0; ack_tgl_h2 <= 1'b0; ack_tgl_h3 <= 1'b0;
      cnt_host_valid <= 1'b0; c_snapshots <= '0;
      for (i = 0; i < NUM_CNT_LOCAL; i++) cnt_host[i] <= '0;
    end else begin
      ack_tgl_h1 <= ack_tgl_src;
      ack_tgl_h2 <= ack_tgl_h1;
      ack_tgl_h3 <= ack_tgl_h2;
      cnt_host_valid <= 1'b0;

      // The snapshot registers are stable by now -- they were written
      // before ack_tgl_src toggled, and that toggle took three host
      // clocks to arrive. No synchroniser on the DATA is needed or
      // wanted; the handshake is what makes it safe.
      if (ack_tgl_h2 ^ ack_tgl_h3) begin
        for (i = 0; i < NUM_CNT_LOCAL; i++) cnt_host[i] <= snap[i];
        cnt_host_valid <= 1'b1;
        busy_host      <= 1'b0;
        c_snapshots    <= c_snapshots + 1;
      end
    end
  end

endmodule

// -----------------------------------------------------------------------
// macsoc_conformance_monitor -- what an integrator can check from the
// host side alone.
//
// Every property here has operands sampled in ONE clock domain. The
// ones that would relate a host-domain signal to a receive-domain
// one are absent by design, and section 19 explains why they are not
// merely hard but unevaluable.
// -----------------------------------------------------------------------
module macsoc_conformance_monitor
  import macsoc_pkg::*;
(
  input  logic        clk_host,
  input  logic        rst_host_n,

  input  ctrl_t       cfg_ctrl,
  input  logic        cfg_write_while_enabled,
  input  logic        headroom_impossible,
  input  logic        coalesce_misconfigured,

  input  logic [31:0] c_overflow,
  input  logic [31:0] c_stall_outstanding,
  input  logic [31:0] c_bus_error,
  input  logic [31:0] c_split_4k,
  input  logic [31:0] c_txn_desc,
  input  logic [31:0] c_txn_data,
  input  logic [31:0] c_irq_by_timer,
  input  logic [31:0] c_irq_by_count,
  input  logic [31:0] c_req_while_busy,
  input  logic [31:0] c_sof_host,        // snapshotted, section 14
  input  logic [31:0] c_eof_host,        // snapshotted in the SAME snapshot

  output logic        integration_ok,
  output logic        cfg_fault,
  output logic        memory_system_marginal,
  output logic        interrupt_mistuned,
  output logic        phy_truncating,
  output logic        alignment_poor,
  output logic        none_of_the_above
);

  // Configuration faults: checkable immediately, always fatal.
  assign cfg_fault = cfg_write_while_enabled |
                     headroom_impossible     |
                     coalesce_misconfigured;

  // The memory system is marginal if the MAC is stalling on its own
  // outstanding limit or, worse, has overflowed. Overflow is the
  // symptom that presents as a CRC error -- section 9.
  assign memory_system_marginal = (c_overflow != '0) ||
                                  (c_stall_outstanding > 32'd1000) ||
                                  (c_bus_error != '0);

  // Almost all interrupts by timer means the count threshold is never
  // reached: every frame is waiting the full timer for no reason.
  assign interrupt_mistuned = (c_irq_by_timer > (c_irq_by_count << 3)) &&
                              (c_irq_by_timer > 32'd100);

  // c_sof and c_eof come from the SAME snapshot, so this comparison
  // is legitimate. Comparing them across two snapshots would not be.
  assign phy_truncating = (c_sof_host > c_eof_host + 32'd1);

  // A 4 KiB split on a meaningful fraction of data transactions means
  // the buffer pool is not page-aligned -- 18.3's subject.
  assign alignment_poor = (c_txn_data != '0) &&
                          (c_split_4k > (c_txn_data >> 4));

  assign integration_ok = !cfg_fault && !memory_system_marginal &&
                          !phy_truncating;

  // 14.3's habit: an explicit "nothing here is wrong" is what ends an
  // investigation rather than deferring it.
  assign none_of_the_above = integration_ok && !interrupt_mistuned &&
                             !alignment_poor && (c_req_while_busy == '0);

  // ---- properties -------------------------------------------------
  // Every one of these samples only host-domain signals.

  p_cfg_fault_is_sticky_until_fixed:
    assert property (@(posedge clk_host) disable iff (!rst_host_n)
      headroom_impossible |-> ##1 (headroom_impossible ||
                                   $changed(cfg_ctrl)))
    else $error("headroom fault cleared without a configuration change");

  p_overflow_implies_not_ok:
    assert property (@(posedge clk_host) disable iff (!rst_host_n)
      (c_overflow != '0) |-> !integration_ok)
    else $error("receive overflow reported while integration_ok is high");

  p_exactly_one_verdict_or_none:
    assert property (@(posedge clk_host) disable iff (!rst_host_n)
      none_of_the_above |-> (!cfg_fault && !memory_system_marginal &&
                             !interrupt_mistuned && !phy_truncating &&
                             !alignment_poor))
    else $error("none_of_the_above asserted alongside a finding");

  p_desc_txn_never_exceeds_data_txn_by_much:
    assert property (@(posedge clk_host) disable iff (!rst_host_n)
      (c_txn_data > 32'd1000) |-> (c_txn_desc <= (c_txn_data << 1)))
    else $error("descriptor fetches far exceed data writes -- ring starvation");

endmodule

// A configuration write to a ring base while the MAC is enabled must
// be refused, not applied. Applying it points the DMA at a new base
// mid-descriptor.
p_ring_base_write_refused_when_enabled:
  assert property (@(posedge clk_host) disable iff (!rst_host_n)
    (psel && penable && pwrite && cfg_ctrl.enable &&
     (paddr == REG_RX_RING_LO)) |=> $stable(cfg_rx_ring_base))
  else $error("ring base changed while the MAC was enabled");

// A refused write must be reported, or a driver bug becomes an
// unexplained absence of traffic.
p_refused_write_flags:
  assert property (@(posedge clk_host) disable iff (!rst_host_n)
    (psel && penable && pwrite && cfg_ctrl.enable &&
     (paddr inside {REG_RX_RING_LO, REG_RX_RING_HI,
                    REG_TX_RING_LO, REG_TX_RING_HI}))
      |-> cfg_write_while_enabled)
  else $error("a ring-base write was refused silently");

// Reads never have side effects. A counter that clears on read cannot
// be sampled by two agents.
p_read_is_side_effect_free:
  assert property (@(posedge clk_host) disable iff (!rst_host_n)
    (psel && penable && !pwrite) |=> $stable(cfg_ctrl))
  else $error("a register read changed configuration state");

// An unmapped read errors rather than returning zero, because zero is
// a plausible value for every register in the map.
p_unmapped_read_errors:
  assert property (@(posedge clk_host) disable iff (!rst_host_n)
    (psel && penable && !pwrite && (paddr == 12'hFFC)) |-> pslverr)
  else $error("an unmapped read returned data instead of an error");

// The counter shadow only updates when its owner says the value is
// coherent.
p_counter_shadow_needs_valid:
  assert property (@(posedge clk_host) disable iff (!rst_host_n)
    !cnt_valid[0] |=> $stable(cnt_shadow[0]))
  else $error("a counter shadow updated without its valid");

// A burst may not cross a 4 KiB boundary. This is the bus's rule and
// the MAC has no natural reason to respect it.
p_burst_within_4k:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ax_valid && ax_ready) |->
      ((ax_addr[11:0] + ((ax_len + 1) << ax_size)) <= 13'h1000))
  else $error("a burst crossed a 4 KiB boundary");

// Outstanding transactions never exceed the limit the system agreed.
p_outstanding_bounded:
  assert property (@(posedge clk) disable iff (!rst_n)
    outstanding <= MAX_OUTSTAND)
  else $error("outstanding transactions exceeded the agreed limit");

// A completion with no transaction outstanding is a bus-level fault
// or a tracking bug, and both are fatal.
p_no_orphan_completion:
  assert property (@(posedge clk) disable iff (!rst_n)
    done_valid |-> (outstanding != '0))
  else $error("a completion arrived with nothing outstanding");

// The burst length never exceeds the parameterised maximum.
p_len_bounded:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ax_valid && ax_ready) |-> (ax_len < MAX_BEATS))
  else $error("burst length exceeded MAX_BEATS");

// A request is not accepted while one is in progress.
p_no_overlapping_requests:
  assert property (@(posedge clk) disable iff (!rst_n)
    busy |-> !req_ready)
  else $error("a request was accepted while another was in progress");

// A descriptor fetch is a read; data and status are writes.
p_kind_implies_direction:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ax_valid && (cur_kind == 2'd0)) |-> !ax_write)
  else $error("a descriptor fetch was issued as a write");

// Every issued transaction eventually completes. Without a bound the
// MAC's outstanding counter leaks and the port stops.
p_transaction_completes:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ax_valid && ax_ready) |-> ##[1:$] done_valid)
  else $error("an issued transaction never completed");

// A remaining byte count only decreases.
p_bytes_monotonic:
  assert property (@(posedge clk) disable iff (!rst_n)
    busy |=> (cur_bytes <= $past(cur_bytes)))
  else $error("the remaining byte count increased");