FPGA Examples — Composing the Blocks Into a Real DMA Engine

// SYNTHESIZABLE. Normalized internal interfaces for the whole engine.
// THESE ARE NOT PCIe WIRE FORMATS AND NOT ANY VENDOR'S INTERFACE (§1, §4).
// A thin adapter maps them to whatever core is used, which is also what
// makes the engine testable without one.
package dma_top_pkg;
 
  parameter int ADDR_W = 64;
  parameter int LEN_W  = 24;
  parameter int TAG_W  = 5;              // 20.3 §1: 5-bit Tag field
  parameter int N_TAGS = 32;
  parameter int DATA_W = 256;            // internal datapath width
  parameter int KEEP_W = DATA_W/8;
 
  // ---- Request toward the PCIe core -------------------------------------
  typedef struct packed {
    logic              is_write;         // 20.3 §2: direction picks MWr / MRd
    logic [ADDR_W-1:0] addr;
    logic [LEN_W-1:0]  length_bytes;
    logic [TAG_W-1:0]  tag;              // meaningful for reads
    logic [15:0]       owner_id;         // which descriptor / job
  } dma_req_t;
 
  // ---- Completion from the PCIe core ------------------------------------
  typedef struct packed {
    logic [TAG_W-1:0]  tag;
    logic [LEN_W-1:0]  bytes;
    logic              error;
    logic              last;
  } dma_cpl_hdr_t;
 
  // ---- Local stream, AXI-Stream-like TEACHING convention ----------------
  typedef struct packed {
    logic [DATA_W-1:0] data;
    logic [KEEP_W-1:0] keep;
    logic              last;
  } dma_beat_t;
 
  // ---- Normalized error taxonomy (section 11) ---------------------------
  // NOT PCIe-defined. Every one has an owner, a sticky status, and a
  // defined effect on the job.
  typedef enum logic [3:0] {
    ERR_NONE          = 4'd0,
    ERR_BAD_DESC      = 4'd1,
    ERR_CPL_STATUS    = 4'd2,
    ERR_CPL_OVERRUN   = 4'd3,
    ERR_UNKNOWN_TAG   = 4'd4,
    ERR_BUFFER_OVF    = 4'd5,
    ERR_CHAIN_LIMIT   = 4'd6,
    ERR_LINK_ABORT    = 4'd7,
    ERR_RESET_ABORT   = 4'd8
  } dma_err_e;
 
endpackage

import dma_top_pkg::*;
 
// SYNTHESIZABLE. Completion handling with a SYNCHRONOUS context RAM.
// SECTION 7: pairing the RAM output with the current cycle's header
// misassociates 98.5% of back-to-back Completion streams (section 14).
//
// The metadata travels WITH the RAM read, in a stage register, and the
// whole stage stalls together.
module cpl_path #(
  parameter int TAGS = N_TAGS
) (
  input  logic clk,
  input  logic rst_n,
 
  // From the PCIe core (normalized, §6)
  input  logic          cpl_valid,
  output logic          cpl_ready,
  input  dma_cpl_hdr_t  cpl_hdr,
  input  dma_beat_t     cpl_beat,
 
  // Context RAM: address out, data back ONE CYCLE LATER.
  output logic [TAG_W-1:0] ctx_raddr,
  input  logic [15:0]      ctx_owner_q,     // registered RAM outputs
  input  logic [LEN_W-1:0] ctx_offset_q,
  input  logic [LEN_W-1:0] ctx_expected_q,
  input  logic [LEN_W-1:0] ctx_received_q,
  input  logic             ctx_valid_q,
 
  // To local buffers -- placement by context offset (§9)
  output logic             place_valid,
  input  logic             place_ready,
  output logic [LEN_W-1:0] place_offset,
  output dma_beat_t        place_beat,
  output logic [15:0]      place_owner,
 
  // Context update / retirement
  output logic             ctx_upd,
  output logic [TAG_W-1:0] ctx_upd_tag,
  output logic [LEN_W-1:0] ctx_upd_received,
  output logic             ctx_retire,
 
  output dma_err_e         err_out
);
 
  // ---- Stage 0: present the address -------------------------------------
  assign ctx_raddr = cpl_hdr.tag;
 
  // ---- Stage 1: the RAM output arrives; METADATA MUST ARRIVE WITH IT ----
  logic          s1_valid_q;
  dma_cpl_hdr_t  s1_hdr_q;
  dma_beat_t     s1_beat_q;
  dma_err_e      err_q;
  assign err_out = err_q;
 
  // The stage advances only when it is empty or being drained -- so the
  // header, the data and the RAM output stay together under backpressure.
  wire s1_will_drain = s1_valid_q && place_ready;
  assign cpl_ready = !s1_valid_q || s1_will_drain;
 
  // ==================================================================
  // EVERYTHING BELOW USES s1_hdr_q -- THE HEADER THAT REQUESTED THIS
  // RAM READ -- never cpl_hdr, which is already the NEXT Completion.
  // ==================================================================
  wire matched  = s1_valid_q && ctx_valid_q;
  wire [LEN_W-1:0] next_rcv = ctx_received_q + s1_hdr_q.bytes;
  wire overrun  = matched && (next_rcv > ctx_expected_q);
  wire failed   = matched && s1_hdr_q.error;
 
  assign place_valid  = matched && !overrun && !failed;
  assign place_offset = ctx_offset_q + ctx_received_q;   // PLACEMENT BY OFFSET
  assign place_beat   = s1_beat_q;
  assign place_owner  = ctx_owner_q;
 
  assign ctx_upd          = place_valid && place_ready;
  assign ctx_upd_tag      = s1_hdr_q.tag;
  assign ctx_upd_received = next_rcv;
  // Retire on the exact byte count -- 20.3 §19 measured the alternative at
  // 100% failure to retire.
  assign ctx_retire       = ctx_upd && (next_rcv == ctx_expected_q);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      s1_valid_q <= 1'b0; s1_hdr_q <= '0; s1_beat_q <= '0; err_q <= ERR_NONE;
    end else begin
      if (cpl_valid && cpl_ready) begin
        // Capture header AND data together with the RAM read they issued.
        s1_valid_q <= 1'b1;
        s1_hdr_q   <= cpl_hdr;
        s1_beat_q  <= cpl_beat;
      end else if (s1_will_drain || (s1_valid_q && (overrun || failed || !ctx_valid_q))) begin
        s1_valid_q <= 1'b0;
      end
 
      // Errors are REPORTED and terminate the context; they never
      // accumulate bytes (20.3 §16).
      if (s1_valid_q) begin
        if (!ctx_valid_q)   err_q <= ERR_UNKNOWN_TAG;   // 20.3 §1's requirement
        else if (overrun)   err_q <= ERR_CPL_OVERRUN;
        else if (failed)    err_q <= ERR_CPL_STATUS;
      end
    end
  end
 
endmodule

import dma_top_pkg::*;
 
// SYNTHESIZABLE. Software/hardware meeting point.
// A NORMALIZED register model -- NOT a universal map (§1). Its purpose is
// to show where the ownership boundaries sit, not to specify a product.
module dma_csr #(parameter int EW = 4) (
  input  logic clk,
  input  logic rst_n,
 
  // Host MMIO write strobes (already in this clock domain, or safely
  // crossed -- see section 5; this block does NOT perform the crossing).
  input  logic        wr_control,
  input  logic [31:0] wr_data,
  input  logic        wr_doorbell,        // ONE-CYCLE strobe
  input  logic [31:0] doorbell_value,
 
  input  logic        job_taken,          // the engine consumed the work
  input  logic        job_done,
  input  dma_err_e    job_err,
  input  logic [31:0] bytes_completed,
 
  output logic        go,
  output logic [31:0] producer_index,
  output logic        work_pending,
  output logic [31:0] status,
  output dma_err_e    sticky_err
);
  logic        pend_q, go_q;
  logic [31:0] prod_q;
  dma_err_e    err_q;
 
  assign work_pending    = pend_q;
  assign go              = go_q;
  assign producer_index  = prod_q;
  assign sticky_err      = err_q;
  assign status          = {24'd0, 3'd0, err_q, go_q};
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      pend_q <= 1'b0; go_q <= 1'b0; prod_q <= '0; err_q <= ERR_NONE;
    end else begin
      if (wr_control) go_q <= wr_data[0];
 
      // ==============================================================
      // THE DOORBELL IS A ONE-CYCLE MMIO STROBE AND MUST BE LATCHED.
      //
      // The descriptor engine may be busy -- fetching, walking, or
      // draining a previous job. A pulse wired straight into its start
      // condition is lost, and software waits forever for work it
      // believes it submitted (section 14, mutation 2).
      //
      // This is Chapter 20.2 section 7's publication boundary: the
      // doorbell IS the handoff.
      // ==============================================================
      if (wr_doorbell) begin
        prod_q <= doorbell_value;
        pend_q <= 1'b1;
      end else if (job_taken) begin
        pend_q <= 1'b0;                   // consumed exactly once
      end
 
      // ==============================================================
      // FIRST-FAILURE STICKY. A later success must NOT clear it
      // (mutation 25) -- the first error is the one that explains the
      // run, and a self-clearing status is worse than none.
      // ==============================================================
      if (job_done && (job_err != ERR_NONE) && (err_q == ERR_NONE))
        err_q <= job_err;
    end
  end
endmodule

import dma_top_pkg::*;
 
// SYNTHESIZABLE. THE FLAGSHIP BLOCK OF THIS CHAPTER.
// One cleanup path for every terminal outcome (section 11). Section 14
// measured the alternative: an error path that frees the Tag but not the
// reservation violates the resource invariant in 99.9% of sequences and
// wedges the engine after 8 errors.
module ctx_cleanup #(
  parameter int TAGS = N_TAGS,
  parameter int CW   = 16
) (
  input  logic clk,
  input  logic rst_n,
 
  // Per-context ownership, set when the request was admitted.
  input  logic [TAGS-1:0]  tag_owned,
  input  logic [TAGS-1:0]  buffer_reserved,
  input  logic [TAGS-1:0]  desc_owned,
 
  // Terminal outcomes -- ALL of them arrive here.
  input  logic             done_success,
  input  logic             done_error,
  input  logic             abort,          // link-down, reset request, job abort
  input  logic [TAG_W-1:0] done_tag,
  input  logic [CW-1:0]    done_bytes,
 
  // Release strobes -- consumed by the pool, the reservation and the walker
  output logic             rel_tag,
  output logic [TAG_W-1:0] rel_tag_idx,
  output logic             rel_buffer,
  output logic [CW-1:0]    rel_bytes,
  output logic             rel_desc,
 
  output logic             err_double_release
);
  logic [TAGS-1:0] released_q;
  logic            dbl_q;
  assign err_double_release = dbl_q;
 
  // ==================================================================
  // ONE PATH, ALL OUTCOMES.
  //
  // success, error and abort are DIFFERENT REASONS and the SAME cleanup.
  // Writing three separate release paths is how one of them ends up
  // missing a resource -- which is exactly section 11's failure.
  // ==================================================================
  wire terminal = done_success || done_error || abort;
 
  assign rel_tag     = terminal && tag_owned[done_tag]       && !released_q[done_tag];
  assign rel_tag_idx = done_tag;
  assign rel_buffer  = terminal && buffer_reserved[done_tag] && !released_q[done_tag];
  assign rel_bytes   = done_bytes;
  assign rel_desc    = terminal && desc_owned[done_tag]      && !released_q[done_tag];
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      released_q <= '0; dbl_q <= 1'b0;
    end else begin
      if (terminal) begin
        // EXACTLY ONCE. A second terminal event for the same context --
        // an error arriving after an abort, say -- is reported rather
        // than releasing twice (mutation 6).
        if (released_q[done_tag]) dbl_q <= 1'b1;
        else                      released_q[done_tag] <= 1'b1;
      end
      // The marker clears when the context is re-allocated, not here.
      if (!tag_owned[done_tag]) released_q[done_tag] <= 1'b0;
    end
  end
endmodule

// SVA over the composed engine. LOCAL contract only. Nothing asserts that
// Completions arrive, that software consumes status, that the Link is
// available, or that a job ever finishes.
//
// NOTE (section 16): these run in simulation and formal. They are NOT in
// the bitstream -- section 10's sticky status registers are what exist in
// silicon.
 
// ---- CONTROL BOUNDARY -------------------------------------------------
 
// P1: A ONE-CYCLE DOORBELL IS NEVER LOST. The engine may be busy; the
// publication is the ownership handoff (20.2 §7).
property p_doorbell_latched;
  @(posedge clk) disable iff (!rst_n)
  wr_doorbell |=> (work_pending || $past(job_taken));
endproperty
a_db : assert property (p_doorbell_latched);
 
// P1b: and it is consumed exactly once.
property p_doorbell_once;
  @(posedge clk) disable iff (!rst_n)
  (work_pending && job_taken && !wr_doorbell) |=> !work_pending;
endproperty
a_db1 : assert property (p_doorbell_once);
 
// P2: A NEW DOORBELL CANNOT OVERWRITE AN ACTIVE JOB'S OWNERSHIP.
property p_no_job_overwrite;
  @(posedge clk) disable iff (!rst_n)
  (job_active && wr_doorbell) |-> $stable(active_job_id);
endproperty
a_ovw : assert property (p_no_job_overwrite);
 
// P3: FIRST-FAILURE STICKY -- a later success must not clear it (§10).
property p_error_sticky;
  @(posedge clk) disable iff (!rst_n)
  (sticky_err != ERR_NONE) |=> ((sticky_err == $past(sticky_err)) || !rst_n);
endproperty
a_sticky : assert property (p_error_sticky);
 
// ---- COMPLETION PIPELINE -- THE CENTRAL PROPERTIES --------------------
 
// P4: THE CONTEXT USED IS THE ONE THE HEADER REQUESTED. Section 14
// measured the alternative at 98.5% misassociation.
property p_context_paired;
  @(posedge clk) disable iff (!rst_n)
  (place_valid) |-> (s1_hdr_q.tag == $past(ctx_raddr));
endproperty
a_pair : assert property (p_context_paired);
 
// P4b: THE WHOLE STAGE STALLS TOGETHER -- header, data and context.
// Holding the data while the context advances reproduces the bug one
// cycle later (mutation 4).
property p_stage_atomic;
  @(posedge clk) disable iff (!rst_n)
  (s1_valid_q && !place_ready) |=> (s1_valid_q && $stable(s1_hdr_q)
                                               && $stable(s1_beat_q));
endproperty
a_stage : assert property (p_stage_atomic);
 
// P5: DATA IS PLACED BY CONTEXT OFFSET, never by arrival order (§9).
// Section 14: 40,000 shuffled, fragmented read jobs -- 0 image mismatches.
property p_placement_by_offset;
  @(posedge clk) disable iff (!rst_n)
  place_valid |-> (place_offset == (ctx_offset_q + ctx_received_q));
endproperty
a_place : assert property (p_placement_by_offset);
 
// P6: AN UNMATCHED, ERRORED OR OVERRUNNING COMPLETION IS REPORTED and
// never placed. 20.3 §1 sources the unmatched-Tag requirement.
property p_bad_cpl_reported;
  @(posedge clk) disable iff (!rst_n)
  (s1_valid_q && (!ctx_valid_q || s1_hdr_q.error || overrun))
    |-> (!place_valid);
endproperty
a_badcpl : assert property (p_bad_cpl_reported);
 
// ---- DATA PATH --------------------------------------------------------
 
// P7: NO SOURCE UNDERFLOW -- a beat is never emitted from an empty FIFO.
property p_no_underflow;
  @(posedge clk) disable iff (!rst_n)
  (src_valid && src_ready) |-> (src_occupancy != '0);
endproperty
a_uf : assert property (p_no_underflow);
 
// P8: NO DESTINATION OVERFLOW -- capacity is checked before acceptance.
property p_no_overflow;
  @(posedge clk) disable iff (!rst_n)
  dst_occupancy <= DST_CAPACITY;
endproperty
a_of : assert property (p_no_overflow);
 
// P9: A READ DESCRIPTOR RETIRES ONLY WHEN ITS DATA HAS LANDED, not when
// its requests were issued (20.1 §19: 99.5% early otherwise).
property p_read_done_on_data;
  @(posedge clk) disable iff (!rst_n)
  read_desc_done |-> (bytes_placed >= bytes_expected);
endproperty
a_rdone : assert property (p_read_done_on_data);
 
// P10: request metadata is stable under transmit stall.
property p_req_stable;
  @(posedge clk) disable iff (!rst_n)
  (rq_valid && !rq_ready) |=> (rq_valid && $stable(rq_desc));
endproperty
a_req : assert property (p_req_stable);
 
// ---- RESOURCE CLEANUP -------------------------------------------------
 
// P11: EVERY TERMINAL OUTCOME RELEASES EVERY OWNED RESOURCE. Section 14
// measured the incomplete error path: 99.9% invariant violation, wedged
// after 8 errors.
property p_cleanup_complete;
  @(posedge clk) disable iff (!rst_n)
  (done_success || done_error || abort)
    |-> (rel_tag == tag_owned[done_tag])
     && (rel_buffer == buffer_reserved[done_tag])
     && (rel_desc == desc_owned[done_tag]);
endproperty
a_clean : assert property (p_cleanup_complete);
 
// P11b: and EXACTLY ONCE -- a second terminal event is reported, not
// released again (mutation 6).
property p_release_once;
  @(posedge clk) disable iff (!rst_n)
  (terminal && released_q[done_tag]) |=> err_double_release;
endproperty
a_once : assert property (p_release_once);
 
// P11c: CONSERVATION -- reserved capacity always matches owned contexts.
property p_resource_conservation;
  @(posedge clk) disable iff (!rst_n)
  reserved_bytes == ($countones(buffer_reserved) * BYTES_PER_CTX);
endproperty
a_cons : assert property (p_resource_conservation);
 
// ---- PUBLICATION ORDER ------------------------------------------------
 
// P12: THE INTERRUPT NEVER PRECEDES THE STATUS IT ANNOUNCES (§13).
property p_publish_then_notify;
  @(posedge clk) disable iff (!rst_n)
  irq_event_valid |-> status_write_accepted;
endproperty
a_order : assert property (p_publish_then_notify);
 
// P12b: and the interrupt event is HELD if the controller is busy
// (19.5 §16's rule).
property p_irq_held;
  @(posedge clk) disable iff (!rst_n)
  (irq_event_valid && !irq_event_ready) |=> irq_event_valid;
endproperty
a_irqheld : assert property (p_irq_held);
 
// ---- RESET ------------------------------------------------------------
 
// P13: RESET DEASSERT DOES NOT ENABLE TRAFFIC. Release is not readiness
// (18.10 §11) -- contexts must be initialized first (mutation 29).
property p_no_traffic_before_ready;
  @(posedge clk) disable iff (!rst_n)
  rq_valid |-> (contexts_initialized && !reset_abort_active);
endproperty
a_rst : assert property (p_no_traffic_before_ready);
 
// P14: reset clears every ownership; no stale context, Tag, reservation
// or prefetched descriptor survives.
property p_reset_clears;
  @(posedge clk)
  !rst_n |=> ((ctx_valid_map == '0) && (reserved_bytes == '0)
                                    && !irq_event_valid && !work_pending);
endproperty
a_rstclr : assert property (p_reset_clears);

performance = correct ownership
            + enough concurrency
            + enough buffering
            + resource-aware scheduling