Scatter-Gather — One Logical Transfer Across Many Segments

application's view          what the DMA engine addresses
──────────────────          ─────────────────────────────
one 256 KB buffer     →     0x4A21_2000   16 KB
                            0x7F03_8000   64 KB
                            0x1C88_C000    4 KB
                            ...

segment_done   this segment's bytes have all moved
job_done       every segment completed AND the end condition was reached

// SYNTHESIZABLE. Normalized scatter-gather types.
// NOT A PCIe FORMAT (section 1). PCIe defines no scatter-gather mechanism,
// no descriptor layout and no chaining convention.
package sg_pkg;
 
  parameter int ADDR_W    = 64;
  parameter int LEN_W     = 24;
  parameter int DESC_BYTES = 32;                 // this layout's record size
  parameter int DBYTE_W   = $clog2(DESC_BYTES+1);
 
  typedef struct packed {
    logic [ADDR_W-1:0] host_addr;      // segment address (device-visible, 20.1 §11)
    logic [LEN_W-1:0]  length;         // segment length
    logic [ADDR_W-1:0] next_desc;      // pointer to the next descriptor (§4)
    logic              end_of_chain;   // §7's explicit termination
    logic              irq;            // request an interrupt at this segment (§9)
  } sg_desc_t;
 
  typedef enum logic [2:0] {
    SG_OK              = 3'd0,
    SG_ERR_ZERO_LEN    = 3'd1,   // §8 -- a segment that cannot progress
    SG_ERR_CHAIN_LIMIT = 3'd2,   // §8 -- bounded walk exceeded
    SG_ERR_FETCH       = 3'd3,   // §5 -- the descriptor read itself failed
    SG_ERR_SEGMENT     = 3'd4,   // a segment's data transfer failed
    SG_ERR_ABORT       = 3'd5
  } sg_status_e;
 
endpackage

import sg_pkg::*;
 
// SYNTHESIZABLE. Fetch one descriptor from host memory.
// THIS IS A MEMORY READ (section 5). It allocates a Tag and creates a
// context exactly as Chapter 20.3 section 15 does for data -- the control
// plane has no privileged path.
module sg_desc_fetch (
  input  logic clk,
  input  logic rst_n,
 
  input  logic              start,
  input  logic [ADDR_W-1:0] desc_addr,
 
  // Memory Read request, to the same transmit path as data (§5).
  output logic              rd_valid,
  output logic [ADDR_W-1:0] rd_addr,
  output logic [LEN_W-1:0]  rd_len,
  input  logic              rd_ready,
  input  logic              link_ok,
 
  input  logic              tag_granted,
  input  logic              busy_downstream,
 
  output logic              fetch_outstanding
);
  logic pending_q, out_q;
  assign fetch_outstanding = out_q;
 
  // The descriptor read is a fixed-size request for this layout. A larger
  // descriptor, or a prefetch of several, would be chunked exactly as data
  // is (Chapter 20.3 §7) -- and prefetch depth belongs to Chapter 20.5.
  assign rd_valid = pending_q && tag_granted && link_ok && !busy_downstream;
  assign rd_addr  = desc_addr;
  assign rd_len   = LEN_W'(DESC_BYTES);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin pending_q <= 1'b0; out_q <= 1'b0; end
    else begin
      if (start && !pending_q && !out_q) pending_q <= 1'b1;
      if (rd_valid && rd_ready) begin pending_q <= 1'b0; out_q <= 1'b1; end
      // out_q is cleared by the assembler when the record completes.
    end
  end
endmodule

import sg_pkg::*;
 
// SYNTHESIZABLE. Assemble a descriptor from Completion fragments.
// SECTION 6: 96.9% of 32-byte fetches arrive in more than one fragment
// (section 18), so publishing on the first fragment publishes a record
// that is part new and part stale.
//
// SAME DISCIPLINE as Chapter 20.3 section 15's data accumulator, applied
// to the control plane -- including comparing the NEXT byte count.
module sg_desc_assembler (
  input  logic clk,
  input  logic rst_n,
 
  input  logic                  fetch_started,
  input  logic                  cpl_valid,
  input  logic [DBYTE_W-1:0]    cpl_bytes,
  input  logic [DESC_BYTES*8-1:0] cpl_data,
  input  logic                  cpl_error,
 
  output sg_desc_t desc,
  output logic     desc_valid,       // asserted ONLY when whole
  output logic     desc_err_fetch
);
  logic [DBYTE_W-1:0]       got_q;
  logic [DESC_BYTES*8-1:0]  buf_q;
  logic                     v_q, err_q;
 
  assign desc           = sg_desc_t'(buf_q);
  assign desc_valid     = v_q;
  assign desc_err_fetch = err_q;
 
  // NEXT value, not current -- Chapter 20.3 §18 measured the alternative
  // at 100.0% failure to retire.
  wire [DBYTE_W-1:0] next_got = got_q + cpl_bytes;
  wire complete = cpl_valid && !cpl_error && (next_got == DBYTE_W'(DESC_BYTES));
  wire overrun  = cpl_valid && (next_got > DBYTE_W'(DESC_BYTES));
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin got_q <= '0; v_q <= 1'b0; err_q <= 1'b0; end
    else begin
      if (fetch_started) begin got_q <= '0; v_q <= 1'b0; err_q <= 1'b0; end
      else if (cpl_valid) begin
        if (cpl_error || overrun) begin
          // A FAILED DESCRIPTOR FETCH IS NOT A DATA ERROR (section 5): the
          // engine does not know what to do next, which ends the job.
          err_q <= 1'b1;
        end else begin
          // Accumulate the fragment into the record buffer. Placement by
          // offset is elided here; what matters is that nothing is
          // published until the whole record has arrived.
          buf_q <= buf_q | cpl_data;
          got_q <= next_got;
          // ==========================================================
          // PUBLISH EXACTLY ONCE, WHEN COMPLETE (section 6).
          // ==========================================================
          if (complete) v_q <= 1'b1;
        end
      end
    end
  end
endmodule

import sg_pkg::*;
 
// SYNTHESIZABLE. Walk a descriptor chain -- bounded, and with the next
// pointer taken only from an owned snapshot.
//
// THIS IS NOT A COMPLETE DMA ENGINE. Segment execution is Chapter 20.3's;
// prefetch and pipelining are Chapter 20.5's; a full FPGA composition is
// Chapter 20.6's.
module sg_walker #(
  parameter int MAX_DESCRIPTORS_PER_JOB = 256,
  parameter int CNT_W = $clog2(MAX_DESCRIPTORS_PER_JOB + 1)
) (
  input  logic clk,
  input  logic rst_n,
 
  // ---- Job input ----------------------------------------------------------
  input  logic              job_valid,
  input  logic [ADDR_W-1:0] job_first_desc,
  input  logic [15:0]       job_id,
  output logic              job_ready,
 
  // ---- Descriptor fetch (section 11) --------------------------------------
  output logic              fetch_start,
  output logic [ADDR_W-1:0] fetch_addr,
  input  sg_desc_t          fetch_desc,
  input  logic              fetch_desc_valid,
  input  logic              fetch_err,
 
  // ---- Segment execution (Chapter 20.3) -----------------------------------
  output logic              seg_start,
  output logic [ADDR_W-1:0] seg_addr,
  output logic [LEN_W-1:0]  seg_len,
  input  logic              seg_done_valid,
  output logic              seg_done_ready,
  input  logic              seg_error,
  input  logic [LEN_W-1:0]  seg_bytes,
 
  // ---- Job completion (section 13) ----------------------------------------
  output logic              job_done_valid,
  input  logic              job_done_ready,
  output sg_status_e        job_status,
  output logic [15:0]       job_done_id,
  output logic [CNT_W-1:0]  segments_completed,
  output logic [31:0]       bytes_completed,
  output logic [ADDR_W-1:0] failing_desc_addr    // §19's key diagnostic
);
  typedef enum logic [2:0] {
    S_IDLE, S_FETCH, S_WAIT_DESC, S_VALIDATE, S_SEGMENT, S_ADVANCE, S_REPORT
  } st_e;
  st_e st_q;
 
  sg_desc_t          desc_q;          // THE SNAPSHOT (section 13)
  logic [ADDR_W-1:0] cur_addr_q, first_q;
  logic [CNT_W-1:0]  seen_q, segs_q;
  logic [31:0]       bytes_q;
  logic [15:0]       id_q;
  sg_status_e        st_stat_q;
  logic              jd_v_q;
 
  assign job_ready         = (st_q == S_IDLE) && !jd_v_q;   // §17
  assign fetch_start       = (st_q == S_FETCH);
  assign fetch_addr        = cur_addr_q;
  assign seg_start         = (st_q == S_SEGMENT);
  assign seg_addr          = desc_q.host_addr;    // FROM THE SNAPSHOT
  assign seg_len           = desc_q.length;
  assign seg_done_ready    = (st_q == S_SEGMENT);
  assign job_done_valid    = jd_v_q;
  assign job_status        = st_stat_q;
  assign job_done_id       = id_q;
  assign segments_completed= segs_q;
  assign bytes_completed   = bytes_q;
  assign failing_desc_addr = cur_addr_q;
 
  // ==================================================================
  // THE CHAIN LIMIT (section 8).
  //
  // Section 18: 10,000 deliberately cyclic chains without a bound hung
  // 100.0% of the time. A DMA engine cannot detect a cycle -- that needs
  // unbounded state -- so the defence is a bound, and the failure must be
  // REPORTED with the descriptor address (section 19).
  //
  // IMPLEMENTATION POLICY, not a PCIe requirement (section 1).
  // ==================================================================
  wire chain_exceeded = (seen_q >= CNT_W'(MAX_DESCRIPTORS_PER_JOB));
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      st_q <= S_IDLE; desc_q <= '0; cur_addr_q <= '0; first_q <= '0;
      seen_q <= '0; segs_q <= '0; bytes_q <= '0; id_q <= '0;
      st_stat_q <= SG_OK; jd_v_q <= 1'b0;
    end else begin
      if (jd_v_q && job_done_ready) jd_v_q <= 1'b0;
 
      unique case (st_q)
        S_IDLE :
          if (job_valid && job_ready) begin
            cur_addr_q <= job_first_desc; first_q <= job_first_desc;
            id_q <= job_id; seen_q <= '0; segs_q <= '0; bytes_q <= '0;
            st_stat_q <= SG_OK;
            st_q <= S_FETCH;
          end
 
        S_FETCH :
          if (chain_exceeded) begin
            st_stat_q <= SG_ERR_CHAIN_LIMIT; st_q <= S_REPORT;
          end else st_q <= S_WAIT_DESC;
 
        S_WAIT_DESC :
          if (fetch_err) begin
            st_stat_q <= SG_ERR_FETCH; st_q <= S_REPORT;
          end else if (fetch_desc_valid) begin
            // ======================================================
            // THE SNAPSHOT. The whole descriptor, in one assignment.
            // Everything afterwards -- the segment address, the length,
            // AND THE NEXT POINTER -- comes from desc_q, never from a
            // re-read of host memory (section 13, mutation 1).
            // ======================================================
            desc_q <= fetch_desc;
            seen_q <= seen_q + CNT_W'(1);
            st_q   <= S_VALIDATE;
          end
 
        S_VALIDATE :
          // A ZERO-LENGTH SEGMENT ENDS THE JOB WITH AN ERROR (section 8).
          // Skipping silently makes byte accounting wrong; retrying makes
          // no progress forever.
          if (desc_q.length == '0) begin
            st_stat_q <= SG_ERR_ZERO_LEN; st_q <= S_REPORT;
          end else st_q <= S_SEGMENT;
 
        S_SEGMENT :
          // ADVANCE ONLY ON THE SEGMENT-DONE HANDSHAKE (section 13's
          // counterexample). A pulse would be lost; starting the next
          // fetch at seg_start destroys ownership of the current segment.
          if (seg_done_valid) begin
            segs_q  <= segs_q + CNT_W'(1);
            bytes_q <= bytes_q + 32'(seg_bytes);
            if (seg_error) begin
              st_stat_q <= SG_ERR_SEGMENT; st_q <= S_REPORT;
            end else st_q <= S_ADVANCE;
          end
 
        S_ADVANCE :
          // ======================================================
          // END-OF-CHAIN WINS OVER A NON-NULL NEXT POINTER (section 7's
          // declared policy). The flag is the explicit statement of
          // intent; a leftover pointer is the likelier accident.
          // ======================================================
          if (desc_q.end_of_chain) begin
            st_stat_q <= SG_OK; st_q <= S_REPORT;
          end else begin
            cur_addr_q <= desc_q.next_desc;   // FROM THE SNAPSHOT
            st_q       <= S_FETCH;
          end
 
        S_REPORT :
          if (!jd_v_q) begin jd_v_q <= 1'b1; st_q <= S_IDLE; end
 
        default : st_q <= S_IDLE;
      endcase
    end
  end
endmodule

// SVA over the scatter-gather blocks. LOCAL contract only. Nothing asserts
// that Completions arrive, that software supplies well-formed lists, or
// that a job ever completes.
 
// ---- DESCRIPTOR FETCH AND ASSEMBLY ------------------------------------
 
// P1: the fetch request is stable under stall.
property p_fetch_stable;
  @(posedge clk) disable iff (!rst_n)
  (rd_valid && !rd_ready) |=> (rd_valid && $stable(rd_addr) && $stable(rd_len));
endproperty
a_fetch : assert property (p_fetch_stable);
 
// P2: A DESCRIPTOR IS PUBLISHED ONLY WHEN WHOLE. Section 18: 96.9% of
// fetches arrive in more than one fragment.
property p_publish_when_complete;
  @(posedge clk) disable iff (!rst_n)
  $rose(desc_valid) |-> ($past(got_q) + $past(cpl_bytes) == DBYTE_W'(DESC_BYTES));
endproperty
a_whole : assert property (p_publish_when_complete);
 
// P2b: and exactly once per fetch.
property p_publish_once;
  @(posedge clk) disable iff (!rst_n)
  (desc_valid && !fetch_started) |=> (desc_valid || $past(fetch_started));
endproperty
a_once : assert property (p_publish_once);
 
// P3: A DESCRIPTOR-FETCH ERROR ENDS THE JOB and is distinguishable from a
// segment error (section 5).
property p_fetch_err_status;
  @(posedge clk) disable iff (!rst_n)
  (fetch_err && (st_q == S_WAIT_DESC)) |=> (job_status == SG_ERR_FETCH);
endproperty
a_ferr : assert property (p_fetch_err_status);
 
// ---- THE SNAPSHOT -----------------------------------------------------
 
// P4: THE WORKING DESCRIPTOR IS IMMUTABLE while its segment executes.
// The fifth appearance of this law in the curriculum (20.2 §6).
property p_snapshot_immutable;
  @(posedge clk) disable iff (!rst_n)
  (st_q inside {S_VALIDATE, S_SEGMENT, S_ADVANCE}) |=> $stable(desc_q)
    || (st_q == S_REPORT) || !rst_n;
endproperty
a_snap : assert property (p_snapshot_immutable);
 
// P5: THE NEXT POINTER COMES FROM THE SNAPSHOT, not from host memory.
property p_next_from_snapshot;
  @(posedge clk) disable iff (!rst_n)
  ((st_q == S_ADVANCE) && !desc_q.end_of_chain)
    |=> (cur_addr_q == $past(desc_q.next_desc));
endproperty
a_next : assert property (p_next_from_snapshot);
 
// P6: SEGMENT ADDRESS AND LENGTH COME FROM THE SNAPSHOT.
property p_seg_from_snapshot;
  @(posedge clk) disable iff (!rst_n)
  seg_start |-> ((seg_addr == desc_q.host_addr) && (seg_len == desc_q.length));
endproperty
a_seg : assert property (p_seg_from_snapshot);
 
// ---- WALK ORDERING ----------------------------------------------------
 
// P7: NO ADVANCE BEFORE THE SEGMENT RETIRES. Section 18's counterexample.
property p_advance_after_retire;
  @(posedge clk) disable iff (!rst_n)
  ((st_q == S_SEGMENT) && !seg_done_valid) |=> (st_q == S_SEGMENT) || !rst_n;
endproperty
a_adv : assert property (p_advance_after_retire);
 
// P8: NO NEXT FETCH while a segment is still executing.
property p_no_overlap_fetch;
  @(posedge clk) disable iff (!rst_n)
  (st_q == S_SEGMENT) |-> !fetch_start;
endproperty
a_ovl : assert property (p_no_overlap_fetch);
 
// P9: THE SEGMENT COUNT INCREMENTS EXACTLY ONCE PER COMPLETED SEGMENT.
property p_seg_count_once;
  @(posedge clk) disable iff (!rst_n)
  (segments_completed > $past(segments_completed))
    |-> ($past(st_q) == S_SEGMENT) && $past(seg_done_valid);
endproperty
a_cnt : assert property (p_seg_count_once);
 
// ---- BOUNDS AND POLICY ------------------------------------------------
 
// P10: THE WALK IS BOUNDED. Section 18: 100.0% hang rate without this.
property p_chain_bounded;
  @(posedge clk) disable iff (!rst_n)
  seen_q <= CNT_W'(MAX_DESCRIPTORS_PER_JOB);
endproperty
a_bound : assert property (p_chain_bounded);
 
// P10b: and exceeding it REPORTS rather than hangs, with the address.
property p_limit_reports;
  @(posedge clk) disable iff (!rst_n)
  ((st_q == S_FETCH) && chain_exceeded)
    |=> (job_status == SG_ERR_CHAIN_LIMIT);
endproperty
a_limit : assert property (p_limit_reports);
 
// P11: A ZERO-LENGTH SEGMENT ENDS THE JOB (section 8's declared policy).
property p_zero_len_policy;
  @(posedge clk) disable iff (!rst_n)
  ((st_q == S_VALIDATE) && (desc_q.length == '0))
    |=> (job_status == SG_ERR_ZERO_LEN);
endproperty
a_zero : assert property (p_zero_len_policy);
 
// P12: END-OF-CHAIN WINS over a non-null next pointer (section 7).
property p_eoc_wins;
  @(posedge clk) disable iff (!rst_n)
  ((st_q == S_ADVANCE) && desc_q.end_of_chain) |=> (st_q == S_REPORT);
endproperty
a_eoc : assert property (p_eoc_wins);
 
// ---- JOB COMPLETION ---------------------------------------------------
 
// P13: JOB COMPLETION IS NOT SEGMENT COMPLETION (section 9).
property p_job_not_segment;
  @(posedge clk) disable iff (!rst_n)
  ($rose(job_done_valid) && (job_status == SG_OK))
    |-> $past(desc_q.end_of_chain);
endproperty
a_job : assert property (p_job_not_segment);
 
// P14: the completion record is HELD until accepted, and stable.
property p_job_held;
  @(posedge clk) disable iff (!rst_n)
  (job_done_valid && !job_done_ready)
    |=> (job_done_valid && $stable(job_status) && $stable(job_done_id));
endproperty
a_held : assert property (p_job_held);
 
// P14b: A NEW JOB CANNOT OVERWRITE AN UNCLAIMED COMPLETION (section 17).
property p_no_overwrite;
  @(posedge clk) disable iff (!rst_n) job_done_valid |-> !job_ready;
endproperty
a_nowr : assert property (p_no_overwrite);
 
// P15: CONSERVATION -- job bytes are the sum of completed segment bytes.
// Section 18 verified this across 20,000 random jobs.
property p_byte_conservation;
  @(posedge clk) disable iff (!rst_n)
  (bytes_completed > $past(bytes_completed))
    |-> (bytes_completed == $past(bytes_completed) + 32'($past(seg_bytes)));
endproperty
a_cons : assert property (p_byte_conservation);
 
// P16: a segment error propagates into the job status.
property p_seg_err_propagates;
  @(posedge clk) disable iff (!rst_n)
  ((st_q == S_SEGMENT) && seg_done_valid && seg_error)
    |=> (job_status == SG_ERR_SEGMENT);
endproperty
a_serr : assert property (p_seg_err_propagates);
 
// P17: an interrupt is requested only after the job completion ownership
// point -- never at segment retirement unless the descriptor asked.
property p_irq_after_job;
  @(posedge clk) disable iff (!rst_n)
  irq_event_valid |-> (job_done_valid || $past(desc_q.irq));
endproperty
a_irq : assert property (p_irq_after_job);
 
// P18: reset clears the walk -- no stale descriptor or job survives.
property p_reset;
  @(posedge clk)
  !rst_n |=> ((st_q == S_IDLE) && !job_done_valid && (seen_q == '0));
endproperty
a_reset : assert property (p_reset);

import sg_pkg::*;
 
// SYNTHESIZABLE. Ring-based segment walking -- no next pointer at all.
// THE TRADE (section 4): a ring cannot loop, because indices are bounded
// by construction -- so no chain-limit guard is needed. What it gives up
// is topology: the list is a fixed array of fixed depth.
module sg_ring_walker #(
  parameter int DEPTH = 8,
  parameter int PTR_W = (DEPTH <= 1) ? 1 : $clog2(DEPTH)
) (
  input  logic clk,
  input  logic rst_n,
  input  logic [PTR_W-1:0] producer_ptr,     // published by software (20.2 §7)
  input  logic             seg_done_valid,
  output logic [PTR_W-1:0] consumer_ptr,
  output logic             work_available,
  output logic             fetch_start
);
  logic [PTR_W-1:0] cons_q;
  assign consumer_ptr = cons_q;
 
  // Work exists when the consumer has not caught the producer. Section
  // 20.2 §12's ambiguity is avoided here because software owns one
  // pointer and hardware the other, and hardware never passes the
  // producer -- P11 of Chapter 20.2.
  assign work_available = (cons_q != producer_ptr);
  assign fetch_start    = work_available;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) cons_q <= '0;
    // ADVANCE ON RETIREMENT, exactly as the linked walker does (§12).
    // EXPLICIT WRAP at DEPTH-1 -- Chapter 20.2 §19 measured binary
    // overflow at 19.9% out-of-range for non-power-of-two depths.
    else if (seg_done_valid)
      cons_q <= (cons_q == PTR_W'(DEPTH-1)) ? '0 : (cons_q + PTR_W'(1));
  end
endmodule