The Transmit DMA Path

// -----------------------------------------------------------------------
// txdma_pkg -- the transmit DMA path.
// -----------------------------------------------------------------------
package txdma_pkg;

  localparam int ADDR_W    = 64;
  localparam int BUS_BYTES = 64;         // 512-bit
  localparam int MAX_BEATS = 16;         // 18.5 revisits this choice
  localparam int MAX_SG    = 8;
  localparam int IN_FLIGHT = 32;
  localparam int DESC_B    = 16;

  // A transmit descriptor. Compare 18.2's receive descriptor: the
  // length and the last-fragment flag have moved from the MAC's
  // column to the driver's, which is section 2's whole subject.
  typedef struct packed {
    logic [ADDR_W-1:0] buf_ptr;          // the driver asserts this
    logic [15:0]       buf_len;          // the driver asserts this
    logic              first;            // the driver asserts this
    logic              last;             // the driver asserts this
    logic              insert_fcs;       // let the MAC append 6.2's FCS
    logic              insert_vlan;      // 13.2's tag
    logic [3:0]        flags;
    logic [7:0]        status;           // the MAC writes this, after
    logic              own;              // 1 = MAC, 0 = driver
  } tx_desc_t;

  // Status bits the MAC writes back.
  localparam int TS_SENT      = 0;
  localparam int TS_UNDERRUN  = 1;       // 7.3 -- the frame was corrupted
  localparam int TS_BUS_ERROR = 2;
  localparam int TS_TOO_LONG  = 3;       // the chain exceeded the MTU
  localparam int TS_TOO_SHORT = 4;       // padded to 60 -- 5.2
  localparam int TS_TIMESTAMP = 5;       // 16.3 captured one

  // A chain, as the walker assembles it.
  typedef struct packed {
    logic [$clog2(MAX_SG+1)-1:0] n;
    logic [15:0]                 total_bytes;
    logic [15:0]                 first_index;
    logic                        complete;
  } chain_t;

endpackage

// -----------------------------------------------------------------------
// tx_ring_walker -- finds a complete chain and refuses a partial one.
//
// The asymmetry with 18.3 section 5: a RECEIVE walker takes
// descriptors as it needs them, because the frame's length is not
// known in advance. A TRANSMIT walker must find the LAST descriptor
// before it may start, because starting a frame it cannot finish is
// section 6's underrun by construction.
// -----------------------------------------------------------------------
module tx_ring_walker
  import txdma_pkg::*;
#(
  parameter int BATCH = 8
)(
  input  logic               clk,
  input  logic               rst_n,

  input  logic [ADDR_W-1:0]  ring_base,
  input  logic [15:0]        ring_len,
  input  logic               doorbell,           // section 10
  input  logic               cfg_poll_enable,
  input  logic [15:0]        cfg_poll_interval,
  input  logic               tick,

  // Batched descriptor read.
  output logic               rd_valid,
  input  logic               rd_ready,
  output logic [ADDR_W-1:0]  rd_addr,
  output logic [15:0]        rd_bytes,
  input  logic               rd_done,
  input  logic               rd_error,
  input  tx_desc_t           rd_desc [BATCH],
  input  logic [$clog2(BATCH+1)-1:0] rd_count,

  // A COMPLETE chain out. Nothing is emitted until `last` is seen.
  output logic               chain_valid,
  input  logic               chain_ready,
  output chain_t             chain,
  output tx_desc_t           chain_desc [MAX_SG],

  output logic [31:0]        c_polls,
  output logic [31:0]        c_doorbells,
  output logic [31:0]        c_chains,
  output logic [31:0]        c_partial_stalls,
  output logic [31:0]        c_chain_too_long,
  output logic [15:0]        next_index,
  output logic               waiting_for_last
);

  tx_desc_t                     acc [MAX_SG];
  logic [$clog2(MAX_SG+1)-1:0]  acc_n;
  logic [15:0]                  acc_bytes;
  logic [15:0]                  acc_first_index;
  logic                         acc_active;
  logic [15:0]                  idx;
  logic [15:0]                  poll_age;

  wire [15:0] mask = ring_len - 16'd1;

  // A partial chain is a chain whose last descriptor the driver has
  // not yet published. The walker HOLDS -- it does not start. This
  // counter separates "the driver is slow" from "the driver is wrong".
  assign waiting_for_last = acc_active && (acc_n != '0);

  // Fetch when a doorbell rang, or when polling is enabled and the
  // interval expired. Section 11 is about which of those to use.
  wire poll_due = cfg_poll_enable && (poll_age >= cfg_poll_interval);
  assign rd_valid = (doorbell || poll_due) && !chain_valid;
  assign rd_addr  = ring_base +
                    ({{(ADDR_W-16){1'b0}}, (idx & mask)} << $clog2(DESC_B));
  assign rd_bytes = 16'(BATCH) * 16'(DESC_B);

  assign chain_valid = acc_active && (acc_n != '0) &&
                       acc[acc_n - 1].last;
  assign chain       = '{ n:           acc_n,
                          total_bytes: acc_bytes,
                          first_index: acc_first_index,
                          complete:    1'b1 };
  assign next_index  = idx;

  always_ff @(posedge clk or negedge rst_n) begin
    int i;
    if (!rst_n) begin
      for (i = 0; i < MAX_SG; i++) acc[i] <= '0;
      acc_n <= '0; acc_bytes <= '0; acc_first_index <= '0;
      acc_active <= 1'b0; idx <= '0; poll_age <= '0;
      c_polls <= '0; c_doorbells <= '0; c_chains <= '0;
      c_partial_stalls <= '0; c_chain_too_long <= '0;
    end else begin
      if (tick) poll_age <= poll_age + 16'd1;
      if (doorbell) c_doorbells <= c_doorbells + 1;

      if (rd_valid && rd_ready) begin
        if (poll_due) begin
          c_polls  <= c_polls + 1;
          poll_age <= '0;
        end
      end

      // Accumulate descriptors the MAC owns, stopping at `last`.
      if (rd_done && !rd_error) begin
        for (i = 0; i < BATCH; i++) begin
          if ((i < int'(rd_count)) && rd_desc[i].own &&
              (acc_n < MAX_SG[$bits(acc_n)-1:0]) && !chain_valid) begin
            if (acc_n == '0) acc_first_index <= idx;
            acc[acc_n]  <= rd_desc[i];
            acc_n       <= acc_n + 1'b1;
            acc_bytes   <= acc_bytes + rd_desc[i].buf_len;
            acc_active  <= 1'b1;
            idx         <= idx + 16'd1;
          end
        end
        if (acc_n >= MAX_SG[$bits(acc_n)-1:0] && !chain_valid)
          c_chain_too_long <= c_chain_too_long + 1;
      end

      if (waiting_for_last && !chain_valid)
        c_partial_stalls <= c_partial_stalls + 1;

      if (chain_valid && chain_ready) begin
        acc_n      <= '0;
        acc_bytes  <= '0;
        acc_active <= 1'b0;
        c_chains   <= c_chains + 1;
      end
    end
  end

endmodule

// -----------------------------------------------------------------------
// tx_gather_engine -- reads a chain's buffers into the transmit FIFO.
//
// The three-way minimum is 18.3 section 7's, unchanged: a buffer
// boundary, a 4 KiB page boundary and the burst limit. What is new is
// the DEADLINE -- the octets must arrive before the wire needs them,
// and section 6 is what happens when they do not.
// -----------------------------------------------------------------------
module tx_gather_engine
  import txdma_pkg::*;
(
  input  logic               clk,
  input  logic               rst_n,

  input  logic               chain_valid,
  output logic               chain_ready,
  input  chain_t             chain,
  input  tx_desc_t           chain_desc [MAX_SG],

  // Read requests out.
  output logic               ar_valid,
  input  logic               ar_ready,
  output logic [ADDR_W-1:0]  ar_addr,
  output logic [7:0]         ar_len,
  output logic [$clog2(IN_FLIGHT)-1:0] ar_tag,

  // Read data in. NOTE: data may return out of order across tags,
  // which is why the reorder buffer below exists at all.
  input  logic               r_valid,
  input  logic [BUS_BYTES*8-1:0] r_data,
  input  logic               r_last,
  input  logic [$clog2(IN_FLIGHT)-1:0] r_tag,
  input  logic               r_error,

  // Into the transmit FIFO, strictly in frame order.
  output logic               fifo_wr,
  output logic [BUS_BYTES*8-1:0] fifo_data,
  output logic [$clog2(BUS_BYTES+1)-1:0] fifo_bytes,
  output logic               fifo_sof,
  output logic               fifo_eof,
  input  logic               fifo_full,

  output logic [15:0]        bytes_fetched,
  output logic [15:0]        bytes_total,
  output logic [31:0]        c_bursts,
  output logic [31:0]        c_page_splits,
  output logic [31:0]        c_buffer_splits,
  output logic [31:0]        c_read_errors,
  output logic [31:0]        c_reorder_stalls,
  output logic               gather_error
);

  logic [$clog2(MAX_SG+1)-1:0] sg_i;
  logic [ADDR_W-1:0]           cur_addr;
  logic [15:0]                 cur_remaining;
  logic                        active;

  wire [12:0] to_page  = 13'h1000 - {1'b0, cur_addr[11:0]};
  wire [15:0] by_burst = 16'(MAX_BEATS * BUS_BYTES);
  wire [15:0] by_page  = {3'b0, to_page};

  logic [15:0] this_burst;
  always_comb begin
    this_burst = cur_remaining;
    if (this_burst > by_burst) this_burst = by_burst;
    if (this_burst > by_page)  this_burst = by_page;
  end

  // A read burst may be issued whenever the FIFO has room. Unlike
  // 18.3's write engine, this one may run AHEAD -- and it must, by
  // section 16's deadline.
  assign ar_valid = active && (cur_remaining != '0) && !fifo_full;
  assign ar_addr  = cur_addr;
  assign ar_len   = 8'(((this_burst + BUS_BYTES - 1) / BUS_BYTES) - 1);
  assign ar_tag   = {{($clog2(IN_FLIGHT)-$clog2(MAX_SG)){1'b0}}, sg_i};

  assign chain_ready = !active;
  assign gather_error = c_read_errors != '0;

  // Read data must enter the FIFO in FRAME order, not in response
  // order. On a bus that returns different tags out of order, a
  // reorder buffer is required -- 18.5 designs the ID policy that
  // makes it small.
  logic [$clog2(IN_FLIGHT)-1:0] expect_tag;
  wire   in_order = r_valid && (r_tag == expect_tag);

  assign fifo_wr    = in_order && !fifo_full;
  assign fifo_data  = r_data;
  assign fifo_bytes = BUS_BYTES[$bits(fifo_bytes)-1:0];
  assign fifo_sof   = in_order && (bytes_fetched == '0);
  assign fifo_eof   = in_order && r_last &&
                      (sg_i == (chain.n - 1'b1));

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      active <= 1'b0; sg_i <= '0; cur_addr <= '0; cur_remaining <= '0;
      bytes_fetched <= '0; bytes_total <= '0; expect_tag <= '0;
      c_bursts <= '0; c_page_splits <= '0; c_buffer_splits <= '0;
      c_read_errors <= '0; c_reorder_stalls <= '0;
    end else begin
      if (chain_valid && chain_ready) begin
        active        <= 1'b1;
        sg_i          <= '0;
        cur_addr      <= chain_desc[0].buf_ptr;
        cur_remaining <= chain_desc[0].buf_len;
        bytes_total   <= chain.total_bytes;
        bytes_fetched <= '0;
        expect_tag    <= '0;
      end

      if (ar_valid && ar_ready) begin
        c_bursts <= c_bursts + 1;
        if (this_burst == by_page && this_burst != cur_remaining)
          c_page_splits <= c_page_splits + 1;
        if (this_burst == cur_remaining)
          c_buffer_splits <= c_buffer_splits + 1;

        cur_addr      <= cur_addr + {{(ADDR_W-16){1'b0}}, this_burst};
        cur_remaining <= cur_remaining - this_burst;

        if (this_burst == cur_remaining) begin
          if (sg_i < (chain.n - 1'b1)) begin
            sg_i          <= sg_i + 1'b1;
            cur_addr      <= chain_desc[sg_i + 1].buf_ptr;
            cur_remaining <= chain_desc[sg_i + 1].buf_len;
          end
        end
      end

      if (r_valid && !in_order) c_reorder_stalls <= c_reorder_stalls + 1;
      if (r_valid && r_error)   c_read_errors    <= c_read_errors + 1;

      if (fifo_wr) begin
        bytes_fetched <= bytes_fetched + 16'(BUS_BYTES);
        if (r_last) expect_tag <= expect_tag + 1'b1;
      end

      if (fifo_eof) active <= 1'b0;
    end
  end

endmodule

// -----------------------------------------------------------------------
// tx_fifo_writer -- fill policy and the start-of-transmission decision.
//
// Two policies: store-and-forward (start when the frame is complete)
// and cut-through (start when `cfg_start_threshold` octets are
// buffered). Section 9 derives the rate at which the second stops
// being available, and this block is where that is enforced rather
// than assumed.
// -----------------------------------------------------------------------
module tx_fifo_writer
  import txdma_pkg::*;
#(
  parameter int DEPTH_B = 16384
)(
  input  logic               clk,
  input  logic               rst_n,

  input  logic               wr,
  input  logic [BUS_BYTES*8-1:0] wr_data,
  input  logic [$clog2(BUS_BYTES+1)-1:0] wr_bytes,
  input  logic               wr_sof,
  input  logic               wr_eof,

  input  logic               cfg_cut_through,
  input  logic [15:0]        cfg_start_threshold,
  input  logic [15:0]        cfg_line_rate_mbps,
  input  logic [15:0]        cfg_worst_stall_ns,

  output logic               full,
  output logic [15:0]        occupancy_b,
  output logic               may_start,
  output logic               frame_complete,

  // The refusal. If the configured threshold cannot cover the
  // configured stall at the configured rate, cut-through is unsafe
  // and the block falls back rather than transmitting a frame it may
  // not be able to finish.
  output logic               cut_through_unsafe,
  output logic [15:0]        required_lead_b,

  output logic [31:0]        c_frames_started,
  output logic [31:0]        c_cut_through_used,
  output logic [31:0]        c_fallbacks,
  output logic [15:0]        c_peak_occupancy
);

  logic [15:0] occ;
  logic        have_eof;

  // Required lead = stall x rate / 8, in octets.
  //   Mbps x ns / 8000 = octets.  100000 Mbps x 300 ns / 8000 = 3750.
  wire [31:0] lead32 = (32'(cfg_line_rate_mbps) * 32'(cfg_worst_stall_ns))
                       / 32'd8000;
  assign required_lead_b = lead32[15:0];

  // Section 6's table, as a runtime check. A threshold below the
  // required lead is a design that will underrun -- not often, and
  // not reproducibly, which is the worst frequency for a fault that
  // corrupts a frame on the wire.
  assign cut_through_unsafe = cfg_cut_through &&
                              (cfg_start_threshold < required_lead_b);

  // Start when the frame is complete, or -- only if cut-through is
  // both enabled AND safe -- when the threshold is reached.
  assign may_start = have_eof ||
                     (cfg_cut_through && !cut_through_unsafe &&
                      (occ >= cfg_start_threshold));

  assign frame_complete = have_eof;
  assign occupancy_b    = occ;
  assign full           = (occ >= (DEPTH_B[15:0] - 16'(BUS_BYTES)));

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      occ <= '0; have_eof <= 1'b0;
      c_frames_started <= '0; c_cut_through_used <= '0;
      c_fallbacks <= '0; c_peak_occupancy <= '0;
    end else begin
      if (wr && !full) begin
        occ <= occ + {{(16-$bits(wr_bytes)){1'b0}}, wr_bytes};
        if (wr_sof) have_eof <= 1'b0;
        if (wr_eof) have_eof <= 1'b1;
      end

      if (may_start && !$past(may_start)) begin
        c_frames_started <= c_frames_started + 1;
        if (!have_eof) c_cut_through_used <= c_cut_through_used + 1;
      end

      if (cfg_cut_through && cut_through_unsafe)
        c_fallbacks <= c_fallbacks + 1;

      if (occ > c_peak_occupancy) c_peak_occupancy <= occ;
    end
  end

endmodule

// -----------------------------------------------------------------------
// underrun_guard -- detects an empty FIFO during transmission and
// guarantees the frame is DISCARDED by the far end.
//
// The guarantee is the point. An underrun always loses the frame; the
// only question is whether the far end knows. Corrupting the FCS
// deliberately is what converts an undetectable corruption into an
// ordinary CRC error -- 6.1's mechanism, used on purpose.
// -----------------------------------------------------------------------
module underrun_guard
  import txdma_pkg::*;
(
  input  logic        clk_tx,             // the TRANSMIT clock domain
  input  logic        rst_tx_n,

  input  logic        transmitting,
  input  logic        fifo_empty,
  input  logic        frame_last_octet,

  // To 6.2's FCS generator.
  output logic        force_bad_fcs,
  output logic        abort_now,

  // To the completion reporter, via a handshake -- 18.1 section 14.
  output logic        underrun_event,
  output logic [31:0] c_underruns,
  output logic [31:0] c_underrun_octets,
  output logic [15:0] worst_shortfall_b,

  output logic        guard_disabled_unsafely
);

  logic in_underrun;
  logic [15:0] shortfall;

  // An empty FIFO while transmitting and not at the frame's end is an
  // underrun. There is no other condition, and there is no recovery:
  // the octets already sent cannot be recalled.
  wire underrun_now = transmitting && fifo_empty && !frame_last_octet;

  // Once entered, the guard stays asserted for the rest of the frame.
  // A FIFO that refills mid-underrun does NOT rescue the frame -- the
  // gap has already been transmitted as whatever the PHY emitted.
  assign force_bad_fcs = in_underrun;

  // Aborting immediately is an alternative to running to the end with
  // a bad FCS. Both lose the frame; aborting frees the wire sooner.
  assign abort_now = in_underrun;

  assign underrun_event = underrun_now && !in_underrun;

  // A design that can disable the guard can transmit a frame whose
  // FCS is valid over wrong data -- section 6's row three. There is
  // no legitimate reason to allow it, so it is flagged.
  assign guard_disabled_unsafely = 1'b0;   // tied off: the guard is not optional

  always_ff @(posedge clk_tx or negedge rst_tx_n) begin
    if (!rst_tx_n) begin
      in_underrun <= 1'b0; shortfall <= '0;
      c_underruns <= '0; c_underrun_octets <= '0; worst_shortfall_b <= '0;
    end else begin
      if (underrun_now && !in_underrun) begin
        in_underrun <= 1'b1;
        shortfall   <= '0;
        c_underruns <= c_underruns + 1;
      end

      if (in_underrun) begin
        shortfall         <= shortfall + 16'd1;
        c_underrun_octets <= c_underrun_octets + 1;
        if ((shortfall + 16'd1) > worst_shortfall_b)
          worst_shortfall_b <= shortfall + 16'd1;
      end

      if (frame_last_octet) in_underrun <= 1'b0;
    end
  end

endmodule

// -----------------------------------------------------------------------
// doorbell_unit -- the transmit-side notification, and its fallback.
//
// A doorbell is a register write from the CPU. It costs the CPU an
// MMIO write and costs the MAC nothing. Polling costs the MAC a
// descriptor read per interval and costs the CPU nothing. Section 11
// derives which is cheaper where, and this block supports both
// because the answer depends on the traffic.
// -----------------------------------------------------------------------
module doorbell_unit
  import txdma_pkg::*;
(
  input  logic               clk,
  input  logic               rst_n,

  // The register write. `db_count` is the number of descriptors the
  // driver has published -- a COUNT, not a flag, so that a doorbell
  // arriving during a fetch is not lost.
  input  logic               db_write,
  input  logic [15:0]        db_count,

  input  logic               cfg_poll_enable,
  input  logic [15:0]        cfg_poll_interval,
  input  logic               tick,

  // Work acknowledged by the walker.
  input  logic               chain_taken,

  output logic               work_available,
  output logic               poll_due,
  output logic [15:0]        outstanding_work,

  output logic [31:0]        c_doorbells,
  output logic [31:0]        c_polls,
  output logic [31:0]        c_empty_polls,
  output logic [31:0]        c_doorbells_coalesced,
  output logic               doorbell_lost           // must never assert
);

  logic [15:0] pending;
  logic [15:0] poll_age;
  logic [15:0] last_db_count;

  // The doorbell is CUMULATIVE. A driver that publishes 8 descriptors
  // and writes 8 has told the MAC everything even if the MAC was
  // mid-fetch when the write landed. A doorbell that is a pulse can
  // be missed; one that is a count cannot.
  wire [15:0] delta = db_count - last_db_count;

  assign work_available   = (pending != 16'd0);
  assign outstanding_work = pending;
  assign poll_due         = cfg_poll_enable &&
                            (poll_age >= cfg_poll_interval);

  // A doorbell whose delta is zero means the driver rang without
  // publishing, or the count wrapped. Either is a driver fault.
  assign doorbell_lost = db_write && (delta == 16'd0);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      pending <= '0; poll_age <= '0; last_db_count <= '0;
      c_doorbells <= '0; c_polls <= '0; c_empty_polls <= '0;
      c_doorbells_coalesced <= '0;
    end else begin
      if (tick) poll_age <= poll_age + 16'd1;

      if (db_write) begin
        c_doorbells   <= c_doorbells + 1;
        last_db_count <= db_count;
        pending       <= pending + delta;
        // A doorbell that added more than one descriptor is the
        // driver batching -- section 11's lever.
        if (delta > 16'd1)
          c_doorbells_coalesced <= c_doorbells_coalesced + 1;
      end

      if (poll_due) begin
        poll_age <= '0;
        c_polls  <= c_polls + 1;
        if (pending == 16'd0) c_empty_polls <= c_empty_polls + 1;
      end

      if (chain_taken && (pending != 16'd0))
        pending <= pending - 16'd1;
    end
  end

endmodule

// -----------------------------------------------------------------------
// tx_completion_reporter -- writes status and ownership back, in
// chain order, and only when the frame is genuinely gone.
//
// "Gone" is the question. A frame is not complete when its last
// descriptor was read, nor when its last octet entered the FIFO --
// it is complete when its last octet has left the PHY interface and
// its underrun status is known.
// -----------------------------------------------------------------------
module tx_completion_reporter
  import txdma_pkg::*;
#(
  parameter int MAX_BATCH = 8
)(
  input  logic               clk,
  input  logic               rst_n,

  // From the transmit domain, already synchronised -- 18.1 sec 14.
  input  logic               frame_done,
  input  logic               frame_underrun,
  input  logic [15:0]        frame_first_index,
  input  logic [$clog2(MAX_SG+1)-1:0] frame_desc_count,
  input  logic               frame_timestamped,      // 16.3

  input  logic [ADDR_W-1:0]  ring_base,
  input  logic [15:0]        ring_len,
  input  logic               cfg_batch_enable,
  input  logic [15:0]        cfg_batch_timeout,
  input  logic               tick,

  output logic               wr_valid,
  input  logic               wr_ready,
  output logic [ADDR_W-1:0]  wr_addr,
  output logic [15:0]        wr_bytes,
  output logic [7:0]         wr_status,

  output logic [31:0]        c_completions,
  output logic [31:0]        c_underrun_completions,
  output logic [31:0]        c_batched_entries,
  output logic [31:0]        c_timeout_flushes,
  output logic [15:0]        mean_batch_x100,
  output logic               completed_before_done   // must never assert
);

  logic [15:0] batch_first, batch_next;
  logic [$clog2(MAX_BATCH+1)-1:0] batch_n;
  logic [15:0] age;
  logic        have;
  logic [7:0]  status_acc;

  wire [15:0] mask = ring_len - 16'd1;

  // A chain's descriptors are contiguous by construction -- section 3
  // accumulated them in index order -- so a chain always batches. The
  // contiguity break 18.3 section 12 had to handle cannot occur here
  // WITHIN a chain, only BETWEEN chains.
  wire is_next  = have && (frame_first_index == batch_next);
  wire no_wrap  = ((frame_first_index & mask) != 16'd0);
  wire can_join = cfg_batch_enable && is_next && no_wrap &&
                  ((batch_n + frame_desc_count) <= MAX_BATCH[$bits(batch_n)-1:0]);

  wire timed_out = have && (age >= cfg_batch_timeout) &&
                   (cfg_batch_timeout != 16'd0);

  assign wr_valid = have && (timed_out || (frame_done && !can_join) ||
                             (batch_n == MAX_BATCH[$bits(batch_n)-1:0]));
  assign wr_addr  = ring_base +
                    ({{(ADDR_W-16){1'b0}}, (batch_first & mask)} << $clog2(DESC_B));
  assign wr_bytes = 16'(batch_n) * 16'(DESC_B);
  assign wr_status = status_acc;

  // The invariant: nothing is reported that the transmit domain has
  // not declared done. `frame_done` is the ONLY permitted trigger.
  assign completed_before_done = wr_valid && !have;

  always_comb begin
    if (c_completions == '0) mean_batch_x100 = 16'd0;
    else mean_batch_x100 = 16'((c_batched_entries * 32'd100) / c_completions);
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      have <= 1'b0; batch_first <= '0; batch_next <= '0;
      batch_n <= '0; age <= '0; status_acc <= '0;
      c_completions <= '0; c_underrun_completions <= '0;
      c_batched_entries <= '0; c_timeout_flushes <= '0;
    end else begin
      if (tick && have) age <= age + 16'd1;

      if (wr_valid && wr_ready) begin
        c_completions     <= c_completions + 1;
        c_batched_entries <= c_batched_entries + {29'b0, batch_n};
        if (timed_out) c_timeout_flushes <= c_timeout_flushes + 1;
        have <= 1'b0; batch_n <= '0; age <= '0; status_acc <= '0;
      end

      if (frame_done) begin
        if (frame_underrun)
          c_underrun_completions <= c_underrun_completions + 1;

        if (can_join) begin
          batch_next <= frame_first_index + 16'(frame_desc_count);
          batch_n    <= batch_n + frame_desc_count;
        end else begin
          batch_first <= frame_first_index;
          batch_next  <= frame_first_index + 16'(frame_desc_count);
          batch_n     <= frame_desc_count;
          have        <= 1'b1;
          age         <= '0;
        end

        status_acc <= status_acc |
                      (8'(1) << TS_SENT) |
                      (frame_underrun    ? (8'(1) << TS_UNDERRUN)  : 8'd0) |
                      (frame_timestamped ? (8'(1) << TS_TIMESTAMP) : 8'd0);
      end
    end
  end

endmodule

// -----------------------------------------------------------------------
// txdma_telemetry -- the transmit path's observable state.
// -----------------------------------------------------------------------
module txdma_telemetry
  import txdma_pkg::*;
(
  input  logic        clk,
  input  logic        rst_n,

  input  logic        chain_started,
  input  logic        chain_completed,
  input  logic        waiting_for_last,       // section 3
  input  logic        fifo_starved,           // gather behind the wire
  input  logic        underrun,               // section 8
  input  logic        doorbell,
  input  logic        poll,
  input  logic        empty_poll,
  input  logic        cut_through_start,
  input  logic [15:0] fifo_occupancy_b,
  input  logic [15:0] chain_bytes,

  output logic [31:0] c_chains,
  output logic [31:0] c_completions,
  output logic [31:0] c_partial_wait_cycles,
  output logic [31:0] c_starve_cycles,
  output logic [31:0] c_underruns,
  output logic [31:0] c_doorbells,
  output logic [31:0] c_polls,
  output logic [31:0] c_empty_polls,
  output logic [31:0] c_cut_through,
  output logic [15:0] c_min_occupancy,        // the underrun margin
  output logic [31:0] c_octets,
  output logic [15:0] in_flight_chains
);

  logic [15:0] open_chains;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      c_chains <= '0; c_completions <= '0; c_partial_wait_cycles <= '0;
      c_starve_cycles <= '0; c_underruns <= '0; c_doorbells <= '0;
      c_polls <= '0; c_empty_polls <= '0; c_cut_through <= '0;
      c_min_occupancy <= 16'hFFFF; c_octets <= '0; open_chains <= '0;
    end else begin
      if (chain_started) begin
        c_chains    <= c_chains + 1;
        open_chains <= open_chains + 16'd1;
        c_octets    <= c_octets + {16'b0, chain_bytes};
      end
      if (chain_completed) begin
        c_completions <= c_completions + 1;
        if (open_chains != 16'd0) open_chains <= open_chains - 16'd1;
      end

      if (waiting_for_last) c_partial_wait_cycles <= c_partial_wait_cycles + 1;
      if (fifo_starved)     c_starve_cycles       <= c_starve_cycles + 1;
      if (underrun)         c_underruns           <= c_underruns + 1;
      if (doorbell)         c_doorbells           <= c_doorbells + 1;
      if (poll)             c_polls               <= c_polls + 1;
      if (empty_poll)       c_empty_polls         <= c_empty_polls + 1;
      if (cut_through_start) c_cut_through        <= c_cut_through + 1;

      // The MINIMUM occupancy during transmission is the underrun
      // margin, measured. A port that has never underrun but whose
      // minimum reached 64 octets is one stall away.
      if (fifo_occupancy_b < c_min_occupancy)
        c_min_occupancy <= fifo_occupancy_b;
    end
  end

  assign in_flight_chains = open_chains;

endmodule

// -----------------------------------------------------------------------
// txdma_conformance_monitor -- what the transmit counters mean.
// -----------------------------------------------------------------------
module txdma_conformance_monitor
  import txdma_pkg::*;
(
  input  logic        clk,
  input  logic        rst_n,

  input  logic [31:0] c_chains,
  input  logic [31:0] c_completions,
  input  logic [31:0] c_underruns,
  input  logic [31:0] c_partial_wait_cycles,
  input  logic [31:0] c_starve_cycles,
  input  logic [31:0] c_doorbells,
  input  logic [31:0] c_doorbells_coalesced,
  input  logic [31:0] c_polls,
  input  logic [31:0] c_empty_polls,
  input  logic [31:0] c_page_splits,
  input  logic [31:0] c_bursts,
  input  logic [31:0] c_chain_too_long,
  input  logic [15:0] c_min_occupancy,
  input  logic [15:0] required_lead_b,

  input  logic        cut_through_unsafe,
  input  logic        doorbell_lost,
  input  logic        completed_before_done,

  output logic        tx_path_ok,
  output logic        memory_missed_deadline,
  output logic        underrun_margin_thin,
  output logic        driver_not_batching,
  output logic        driver_publishing_late,
  output logic        polling_wasteful,
  output logic        chain_limit_reached,
  output logic        cfg_fault,
  output logic        none_of_the_above
);

  // Fatal and non-negotiable: a frame was corrupted on the wire.
  assign memory_missed_deadline = (c_underruns != '0);

  // Predictive: the margin was thin even though nothing failed.
  assign underrun_margin_thin = (c_chains > 32'd1000) &&
                                (c_min_occupancy < required_lead_b);

  // The driver rings per packet rather than per batch -- section 10.
  assign driver_not_batching = (c_doorbells > 32'd10000) &&
                               (c_doorbells_coalesced < (c_doorbells >> 3));

  // The driver publishes a chain's last descriptor late -- section 3.
  assign driver_publishing_late = (c_chains > 32'd1000) &&
                                  (c_partial_wait_cycles >
                                   (c_chains << 6));      // > 64 cycles/chain

  // Polling finds nothing almost every time -- section 11.
  assign polling_wasteful = (c_polls > 32'd10000) &&
                            (c_empty_polls > ((c_polls >> 1) + (c_polls >> 2)));

  assign chain_limit_reached = (c_chain_too_long != '0);

  assign cfg_fault = cut_through_unsafe | doorbell_lost |
                     completed_before_done;

  assign tx_path_ok = !memory_missed_deadline && !cfg_fault;

  assign none_of_the_above = tx_path_ok && !underrun_margin_thin &&
                             !driver_not_batching && !driver_publishing_late &&
                             !polling_wasteful && !chain_limit_reached;

  // ---- properties -------------------------------------------------

  p_underrun_is_fatal:
    assert property (@(posedge clk) disable iff (!rst_n)
      (c_underruns != '0) |-> !tx_path_ok)
    else $error("tx_path_ok asserted with underruns recorded");

  p_completions_le_chains:
    assert property (@(posedge clk) disable iff (!rst_n)
      c_completions <= c_chains)
    else $error("more chains completed than were started");

  p_never_complete_before_done:
    assert property (@(posedge clk) disable iff (!rst_n)
      !completed_before_done)
    else $error("a completion was reported before the transmit domain declared done");

  p_cut_through_refused_when_unsafe:
    assert property (@(posedge clk) disable iff (!rst_n)
      cut_through_unsafe |-> cfg_fault)
    else $error("an unsafe cut-through configuration was not flagged");

  p_verdicts_exclusive_with_clear:
    assert property (@(posedge clk) disable iff (!rst_n)
      none_of_the_above |-> (!memory_missed_deadline && !cfg_fault &&
                             !driver_not_batching && !polling_wasteful))
    else $error("none_of_the_above asserted alongside a finding");

endmodule

// A chain is only emitted when its last descriptor has been seen.
p_chain_requires_last:
  assert property (@(posedge clk) disable iff (!rst_n)
    (chain_valid && chain_ready) |-> acc[acc_n - 1].last)
  else $error("a chain was emitted without its last descriptor");

// Only MAC-owned descriptors are accumulated.
p_accumulate_only_owned:
  assert property (@(posedge clk) disable iff (!rst_n)
    (rd_done && !rd_error && rd_desc[0].own == 1'b0) |=>
      (acc_n == $past(acc_n)))
  else $error("a driver-owned descriptor was accumulated");

// The first descriptor of a chain carries `first`.
p_first_is_first:
  assert property (@(posedge clk) disable iff (!rst_n)
    (chain_valid && (acc_n != '0)) |-> acc[0].first)
  else $error("a chain's first descriptor did not carry the first flag");

// A chain never exceeds MAX_SG without being flagged.
p_chain_bounded:
  assert property (@(posedge clk) disable iff (!rst_n)
    (acc_n >= MAX_SG) |=> (c_chain_too_long > $past(c_chain_too_long)))
  else $error("an over-long chain was not counted");

// The ring index only advances.
p_index_monotonic:
  assert property (@(posedge clk) disable iff (!rst_n)
    ##1 (next_index >= $past(next_index)))
  else $error("the transmit ring index went backwards");

// A partial chain is held, never started.
p_partial_never_starts:
  assert property (@(posedge clk) disable iff (!rst_n)
    waiting_for_last |-> !chain_valid)
  else $error("a partial chain was offered as complete");

// No read burst crosses a 4 KiB boundary.
p_read_within_page:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ar_valid && ar_ready) |->
      ((ar_addr[11:0] + this_burst) <= 13'h1000))
  else $error("a transmit read crossed a page boundary");

// No burst exceeds the beat limit.
p_read_within_burst:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ar_valid && ar_ready) |-> (ar_len < MAX_BEATS))
  else $error("a read burst exceeded MAX_BEATS");

// No burst reads past the end of its buffer.
p_read_within_buffer:
  assert property (@(posedge clk) disable iff (!rst_n)
    (ar_valid && ar_ready) |-> (this_burst <= cur_remaining))
  else $error("a read ran past the end of its buffer");

// Data enters the FIFO in frame order only.
p_fifo_order:
  assert property (@(posedge clk) disable iff (!rst_n)
    fifo_wr |-> (r_tag == expect_tag))
  else $error("out-of-order data entered the transmit FIFO");

// Exactly one start-of-frame per chain.
p_one_sof:
  assert property (@(posedge clk) disable iff (!rst_n)
    fifo_sof |=> (!fifo_sof throughout fifo_eof[->1]))
  else $error("two starts of frame without an end");

// The octets fetched never exceed the chain's declared total.
p_fetch_within_total:
  assert property (@(posedge clk) disable iff (!rst_n)
    active |-> (bytes_fetched <= bytes_total))
  else $error("more octets were fetched than the chain declared");

// A read error is counted and does not silently pass.
p_read_error_counted:
  assert property (@(posedge clk) disable iff (!rst_n)
    (r_valid && r_error) |=> (c_read_errors > $past(c_read_errors)))
  else $error("a read error was not counted");