DMA over PCIe — When the Endpoint Becomes the Requester

Memory Space Enable  →  the Function DECODES requests aimed at it     (Completer)
Bus Master Enable    →  the Function ISSUES requests aimed elsewhere  (Requester)

write engine:   issue  →  done with it
read engine:    issue  →  remember  →  match Completions  →  account bytes  →  retire

command / descriptor            what to transfer          20.2
      ↓
validate                        length, address, permission
      ↓
reserve transfer context        one per active transfer
      ↓
choose a chunk                  bounded by device and protocol limits
      ↓
build a PCIe request            MemWr (device→host) or MemRd (host→device)
      ↓
common TX ownership             credits, arbitration, Link state
      ↓
track completions               READS ONLY -- the hard half (§7)
      ↓
account bytes                   issued vs completed, separately (§10)
      ↓
retire the transfer             at a declared boundary (§6)
      ↓
report                          → interrupt event → Module 19 (§12)

DMA transfer retires
      ↓
normalized completion EVENT        (this chapter, §13)
      ↓
interrupt controller               (Module 19)
      ↓
MSI / MSI-X                        (19.2 / 19.3)
      ↓
routing                            (19.4)

// SYNTHESIZABLE. Normalized DMA types.
// DIRECTION SEMANTICS ARE THE CANONICAL PART (section 4): device-to-host
// is a Memory WRITE, host-to-device is a Memory READ. Everything else here
// -- field widths, the command shape -- is internal normalization.
package dma_pkg;
 
  parameter int ADDR_W = 64;
  parameter int LEN_W  = 32;
 
  typedef enum logic {
    DMA_TO_HOST   = 1'b0,   // device -> host : Memory WRITE  (posted)
    DMA_FROM_HOST = 1'b1    // host -> device : Memory READ   (non-posted)
  } dma_dir_e;
 
  typedef struct packed {
    logic             valid;
    dma_dir_e         dir;
    logic [ADDR_W-1:0] addr;   // DEVICE-VISIBLE address (section 11)
    logic [LEN_W-1:0]  len;
  } dma_cmd_t;
 
  typedef enum logic [1:0] {
    DMA_OK       = 2'd0,
    DMA_ERR_LEN  = 2'd1,   // zero length -- local contract says invalid
    DMA_ERR_ABORT= 2'd2
  } dma_status_e;
 
endpackage

import dma_pkg::*;
 
// SYNTHESIZABLE. Own one DMA command, and keep issued/completed separate.
// SECTION 10: bytes_issued and bytes_completed are DIFFERENT QUANTITIES,
// and for reads they are fundamentally so (section 7).
module dma_context #(
  parameter int MAX_CHUNK = 256      // normalized local limit (section 9)
) (
  input  logic clk,
  input  logic rst_n,
 
  // ---- Command interface -------------------------------------------------
  input  dma_cmd_t cmd,
  output logic     cmd_ready,
 
  // ---- Permission and availability (section 5) ---------------------------
  input  logic bus_master_enable,
  input  logic link_ok,
 
  // ---- Request issue handshake, from sections 15/16 ----------------------
  output logic [LEN_W-1:0]  issue_bytes,
  output logic              issue_valid,
  input  logic              issue_ready,
 
  // ---- Completion accounting ---------------------------------------------
  // For a write this is driven by the declared retirement boundary; for a
  // read it is driven by Completion data actually received (section 7).
  input  logic              complete_valid,
  input  logic [LEN_W-1:0]  complete_bytes,
 
  output logic              active,
  output dma_dir_e          dir,
  output logic [ADDR_W-1:0] cur_addr,
  output logic [LEN_W-1:0]  bytes_total,
  output logic [LEN_W-1:0]  bytes_issued,
  output logic [LEN_W-1:0]  bytes_completed,
  output logic              xfer_done,
  output dma_status_e       xfer_status
);
 
  logic              act_q;
  dma_dir_e          dir_q;
  logic [ADDR_W-1:0] addr_q;
  logic [LEN_W-1:0]  tot_q, iss_q, cpl_q;
  dma_status_e       st_q;
 
  assign active          = act_q;
  assign dir             = dir_q;
  assign cur_addr        = addr_q;
  assign bytes_total     = tot_q;
  assign bytes_issued    = iss_q;
  assign bytes_completed = cpl_q;
  assign xfer_status     = st_q;
  assign cmd_ready       = !act_q;
 
  // ==================================================================
  // THE CHUNK. Bounded by what remains and by the local maximum.
  //
  // Section 15 verified the arithmetic exhaustively over totals 0..199
  // and maximums 1..16: chunks always sum to the total, never zero while
  // bytes remain, and never exceed the maximum.
  // ==================================================================
  wire [LEN_W-1:0] remaining = tot_q - iss_q;
  assign issue_bytes = (remaining > LEN_W'(MAX_CHUNK)) ? LEN_W'(MAX_CHUNK)
                                                       : remaining;
 
  // EVERY CONDITION MUST HOLD. Bus Master Enable is necessary and not
  // sufficient (section 5).
  assign issue_valid = act_q && (remaining != '0)
                    && bus_master_enable && link_ok;
 
  // ==================================================================
  // DONE IS BASED ON COMPLETED BYTES, NEVER ON ISSUED BYTES.
  //
  // Section 15 measured the alternative: `done = all requests issued`
  // declares a read transfer complete early in 99.5% of cases, and
  // software then reads a buffer that is mostly stale (section 7).
  // ==================================================================
  assign xfer_done = act_q && (cpl_q >= tot_q) && (tot_q != '0);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      act_q <= 1'b0; dir_q <= DMA_TO_HOST; addr_q <= '0;
      tot_q <= '0; iss_q <= '0; cpl_q <= '0; st_q <= DMA_OK;
    end else begin
      if (!act_q && cmd.valid) begin
        if (cmd.len == '0) begin
          // ZERO LENGTH IS EXPLICITLY INVALID under this local contract,
          // and reported rather than silently accepted -- an accepted
          // zero-length command with `done` gated on tot_q != 0 would
          // never retire (section 17, mutation 4).
          st_q <= DMA_ERR_LEN;
        end else begin
          // CAPTURED ATOMICALLY, in one assignment. Nothing re-reads the
          // command interface afterwards -- Chapter 19.2 section 13's
          // rule, and software may rewrite its registers immediately.
          act_q  <= 1'b1;
          dir_q  <= cmd.dir;
          addr_q <= cmd.addr;
          tot_q  <= cmd.len;
          iss_q  <= '0;
          cpl_q  <= '0;
          st_q   <= DMA_OK;
        end
      end else if (act_q) begin
        // ============================================================
        // bytes_issued ADVANCES ON THE HANDSHAKE, NEVER ON valid.
        //
        // Section 15: advancing on `valid` exceeded the total in 79.5%
        // of randomized cases -- a stalled request counted repeatedly,
        // so the engine believes it sent data it never sent.
        // ============================================================
        if (issue_valid && issue_ready) begin
          iss_q  <= iss_q + issue_bytes;
          addr_q <= addr_q + ADDR_W'(issue_bytes);
        end
 
        if (complete_valid) cpl_q <= cpl_q + complete_bytes;
 
        if (xfer_done) act_q <= 1'b0;
      end
    end
  end
 
endmodule

import dma_pkg::*;
 
// SYNTHESIZABLE. Device -> host: build posted Memory Writes (section 6).
// THE WRITE PATH IS THE SIMPLE ONE because a posted write creates no
// outstanding state -- issue and forget. The payload buffering contract is
// explicit: this block asserts valid only when the payload for the chunk
// is available, so a stall never strands a half-built request.
module dma_write_engine (
  input  logic clk,
  input  logic rst_n,
 
  input  logic              ctx_active,
  input  dma_dir_e          ctx_dir,
  input  logic [ADDR_W-1:0] ctx_addr,
  input  logic [LEN_W-1:0]  issue_bytes,
  input  logic              issue_valid,
  output logic              issue_ready,
 
  input  logic              payload_available,
 
  // To the common PCIe transmit path
  output logic              tx_valid,
  output logic [ADDR_W-1:0] tx_addr,
  output logic [LEN_W-1:0]  tx_len,
  input  logic              tx_ready,
 
  // Section 6: a posted write has no Completion. The retirement boundary
  // used here is acceptance by the transmit path -- DECLARED, not implied.
  output logic              wr_retire_valid,
  output logic [LEN_W-1:0]  wr_retire_bytes
);
 
  wire is_write = (ctx_dir == DMA_TO_HOST);
 
  assign tx_valid = ctx_active && is_write && issue_valid && payload_available;
  assign tx_addr  = ctx_addr;
  assign tx_len   = issue_bytes;
 
  // The context advances only when the transmit path accepts.
  assign issue_ready = is_write && tx_ready && payload_available;
 
  // ==================================================================
  // THE DECLARED RETIREMENT BOUNDARY for writes (section 6).
  //
  // This design retires on acceptance by the transmit path. A design
  // that retires later -- on Data Link acknowledgement, say -- is also
  // valid; what is NOT valid is retiring on `tx_valid`, which reports
  // transfers the path never took (section 17, mutation 1).
  // ==================================================================
  assign wr_retire_valid = tx_valid && tx_ready;
  assign wr_retire_bytes = issue_bytes;
 
endmodule

import dma_pkg::*;
 
// SYNTHESIZABLE. Host -> device: one outstanding Memory Read (section 7).
//
// DELIBERATELY BOUNDED TO A SINGLE OUTSTANDING REQUEST, and this is a
// teaching limitation, stated plainly: a production engine maintains a
// pool of Tags and many outstanding reads, with Completions returning out
// of order and possibly split. TAG POOLS AND COMPLETION REORDERING ARE
// NOT OWNED BY THIS CHAPTER -- see Chapters 20.3 and 13.3.
//
// What this model DOES show correctly is the property that matters most:
// a read transfer retires on RECEIVED bytes, never on issued ones.
module dma_read_tracker (
  input  logic clk,
  input  logic rst_n,
 
  input  logic              ctx_active,
  input  dma_dir_e          ctx_dir,
  input  logic [ADDR_W-1:0] ctx_addr,
  input  logic [LEN_W-1:0]  issue_bytes,
  input  logic              issue_valid,
  output logic              issue_ready,
 
  output logic              tx_valid,
  output logic [ADDR_W-1:0] tx_addr,
  output logic [LEN_W-1:0]  tx_len,
  input  logic              tx_ready,
 
  // Completion data returning (Chapter 12.3). Simplified: bytes only.
  input  logic              cpl_valid,
  input  logic [LEN_W-1:0]  cpl_bytes,
 
  output logic              rd_retire_valid,
  output logic [LEN_W-1:0]  rd_retire_bytes,
  output logic              err_unexpected_cpl,
  output logic              err_overrun
);
 
  logic              outstanding_q;
  logic [LEN_W-1:0]  expected_q, received_q;
  logic              unexp_q, over_q;
 
  wire is_read = (ctx_dir == DMA_FROM_HOST);
 
  assign err_unexpected_cpl = unexp_q;
  assign err_overrun        = over_q;
 
  // ONE AT A TIME. A second request cannot be issued while one is
  // outstanding -- which is the whole bound of this model.
  assign tx_valid    = ctx_active && is_read && issue_valid && !outstanding_q;
  assign tx_addr     = ctx_addr;
  assign tx_len      = issue_bytes;
  assign issue_ready = is_read && tx_ready && !outstanding_q;
 
  // RETIREMENT ON RECEIVED BYTES (section 7).
  assign rd_retire_valid = cpl_valid && outstanding_q;
  assign rd_retire_bytes = cpl_bytes;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      outstanding_q <= 1'b0; expected_q <= '0; received_q <= '0;
      unexp_q <= 1'b0; over_q <= 1'b0;
    end else begin
      if (tx_valid && tx_ready) begin
        outstanding_q <= 1'b1;
        expected_q    <= issue_bytes;
        received_q    <= '0;
      end else if (cpl_valid) begin
        if (!outstanding_q) begin
          // ==========================================================
          // A COMPLETION WITH NO OUTSTANDING REQUEST IS REPORTED, never
          // accounted. Consuming it would credit the transfer with data
          // it did not request (section 17, mutation 9).
          // ==========================================================
          unexp_q <= 1'b1;
        end else if ((received_q + cpl_bytes) > expected_q) begin
          // More data than was asked for. Reported, and NOT accumulated.
          over_q <= 1'b1;
        end else begin
          received_q <= received_q + cpl_bytes;
          // Retire this request only when its expected bytes have all
          // arrived. The CONTEXT then decides whether the whole transfer
          // is done -- which is section 14's xfer_done, on completed
          // bytes.
          if ((received_q + cpl_bytes) == expected_q) outstanding_q <= 1'b0;
        end
      end
    end
  end
 
endmodule

import dma_pkg::*;
 
// SYNTHESIZABLE. Hand a retired transfer to the interrupt subsystem.
// SECTION 12: this block knows NOTHING about MSI addresses, MSI-X tables
// or CPU destinations. It produces a normalized event with a queue/vector
// IDENTITY, and Module 19 owns everything after that.
module dma_completion_event #(parameter int VEC_W = 11) (
  input  logic clk,
  input  logic rst_n,
 
  input  logic              xfer_done,
  input  dma_status_e       xfer_status,
  input  logic [LEN_W-1:0]  bytes_completed,
  input  logic [VEC_W-1:0]  queue_id,
 
  output logic              done_valid,
  input  logic              done_ready,
  output dma_status_e       done_status,
  output logic [LEN_W-1:0]  done_bytes,
  output logic [VEC_W-1:0]  done_queue,
 
  output logic              event_overflow
);
 
  logic              v_q, ovf_q;
  dma_status_e       st_q;
  logic [LEN_W-1:0]  by_q;
  logic [VEC_W-1:0]  q_q;
 
  assign done_valid     = v_q;
  assign done_status    = st_q;
  assign done_bytes     = by_q;
  assign done_queue     = q_q;
  assign event_overflow = ovf_q;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      v_q <= 1'b0; ovf_q <= 1'b0; st_q <= DMA_OK; by_q <= '0; q_q <= '0;
    end else begin
      // ==============================================================
      // THE EVENT IS HELD UNTIL THE CONSUMER TAKES IT.
      //
      // A one-cycle pulse would be lost whenever the interrupt
      // controller is busy -- coalescing a previous batch, waiting on
      // credits, or blocked by the Link (Chapter 19.5 section 8). And a
      // lost DMA completion event means software is never told the
      // transfer finished: the ring stalls with the data already in
      // memory (section 17, mutation 11).
      // ==============================================================
      if (xfer_done && !v_q) begin
        v_q  <= 1'b1;
        st_q <= xfer_status;      // captured whole
        by_q <= bytes_completed;
        q_q  <= queue_id;
      end else if (v_q && done_ready) begin
        v_q <= 1'b0;
      end
 
      // A second completion while one is unconsumed is REPORTED. With a
      // single context it cannot happen; with a command queue it can, and
      // silence would lose a transfer's notification.
      if (xfer_done && v_q) ovf_q <= 1'b1;
    end
  end
 
endmodule

// SVA over the DMA blocks. LOCAL contract only. Nothing asserts that
// Completions arrive, that the Link becomes available, that credits are
// returned, or that software ever issues a command.
 
// ---- ENVIRONMENT ------------------------------------------------------
assume property (@(posedge clk) disable iff (!rst_n)
  (cmd.valid && !cmd_ready) |=> (cmd.valid && $stable(cmd)));
assume property (@(posedge clk) disable iff (!rst_n)
  cpl_valid |-> (cpl_bytes != '0));
 
// ---- COMMAND OWNERSHIP ------------------------------------------------
 
// P1: the command is captured ATOMICALLY and its fields are stable while
// owned. Software may rewrite its registers the next cycle.
property p_cmd_stable;
  @(posedge clk) disable iff (!rst_n)
  (active && !xfer_done) |=> ($stable(bytes_total) && $stable(dir));
endproperty
a_cmd : assert property (p_cmd_stable);
 
// P2: a zero-length command is refused explicitly, not accepted.
property p_zero_len;
  @(posedge clk) disable iff (!rst_n)
  (cmd.valid && cmd_ready && (cmd.len == '0)) |=> (!active && (xfer_status == DMA_ERR_LEN));
endproperty
a_zero : assert property (p_zero_len);
 
// ---- BYTE ACCOUNTING -- THE CENTRAL PROPERTIES ------------------------
 
// P3: bytes_issued NEVER EXCEEDS the total. Section 15 measured the
// violation: advancing on `valid` overshoots in 79.5% of cases.
property p_issued_bounded;
  @(posedge clk) disable iff (!rst_n)
  active |-> (bytes_issued <= bytes_total);
endproperty
a_iss : assert property (p_issued_bounded);
 
// P3b: and it advances ONLY on a request handshake.
property p_issued_on_fire;
  @(posedge clk) disable iff (!rst_n)
  (bytes_issued > $past(bytes_issued))
    |-> ($past(issue_valid) && $past(issue_ready));
endproperty
a_issfire : assert property (p_issued_on_fire);
 
// P4: THE TRANSFER RETIRES ON COMPLETED BYTES, NEVER ON ISSUED BYTES.
// The most important property in this chapter -- section 15 measured the
// alternative at 99.5% early completion for reads.
property p_done_on_completed;
  @(posedge clk) disable iff (!rst_n)
  xfer_done |-> (bytes_completed >= bytes_total);
endproperty
a_done : assert property (p_done_on_completed);
 
// P4b: stated the other way, so a design cannot satisfy P4 by making
// bytes_completed track bytes_issued.
property p_completed_bounded;
  @(posedge clk) disable iff (!rst_n)
  active |-> (bytes_completed <= bytes_total);
endproperty
a_cplb : assert property (p_completed_bounded);
 
// P5: the chunk is bounded and never zero while bytes remain.
property p_chunk_valid;
  @(posedge clk) disable iff (!rst_n)
  issue_valid |-> ((issue_bytes != '0)
                && (issue_bytes <= LEN_W'(MAX_CHUNK))
                && (issue_bytes <= (bytes_total - bytes_issued)));
endproperty
a_chunk : assert property (p_chunk_valid);
 
// ---- PERMISSION AND AVAILABILITY --------------------------------------
 
// P6: NO REQUEST IS ISSUED WITHOUT BUS MASTER ENABLE. Section 1: "when
// this field is clear, the function is not allowed to issue any memory or
// I/O requests."
property p_bme_required;
  @(posedge clk) disable iff (!rst_n)
  (tx_valid) |-> bus_master_enable;
endproperty
a_bme : assert property (p_bme_required);
 
// P7: nor while the Link cannot carry normal traffic.
property p_link_required;
  @(posedge clk) disable iff (!rst_n) tx_valid |-> link_ok;
endproperty
a_link : assert property (p_link_required);
 
// P8: LINK-DOWN OR BME CLEAR DOES NOT DISCARD AN OWNED COMMAND. The
// declared contract (section 18): new REQUESTS stop; owned work is
// retained.
property p_command_retained;
  @(posedge clk) disable iff (!rst_n)
  (active && (!bus_master_enable || !link_ok) && !xfer_done) |=> active;
endproperty
a_retain : assert property (p_command_retained);
 
// ---- DIRECTION --------------------------------------------------------
 
// P9: device-to-host issues WRITES; host-to-device issues READS (section 4).
property p_direction_write;
  @(posedge clk) disable iff (!rst_n)
  (tx_valid && (dir == DMA_TO_HOST)) |-> dut_tx.is_memory_write;
endproperty
a_dirw : assert property (p_direction_write);
 
property p_direction_read;
  @(posedge clk) disable iff (!rst_n)
  (tx_valid && (dir == DMA_FROM_HOST)) |-> dut_tx.is_memory_read;
endproperty
a_dirr : assert property (p_direction_read);
 
// ---- READ TRACKING ----------------------------------------------------
 
// P10: NEVER TWO OUTSTANDING READS in this bounded model.
property p_single_outstanding;
  @(posedge clk) disable iff (!rst_n)
  (outstanding_q && !cpl_valid) |-> !(tx_valid && tx_ready);
endproperty
a_single : assert property (p_single_outstanding);
 
// P11: A COMPLETION WITH NO OUTSTANDING READ IS REPORTED, NOT ACCOUNTED.
property p_unexpected_cpl;
  @(posedge clk) disable iff (!rst_n)
  (cpl_valid && !outstanding_q) |=> (err_unexpected_cpl && $stable(received_q));
endproperty
a_unexp : assert property (p_unexpected_cpl);
 
// P12: received bytes never exceed expected bytes.
property p_no_overrun;
  @(posedge clk) disable iff (!rst_n) received_q <= expected_q;
endproperty
a_over : assert property (p_no_overrun);
 
// ---- COMPLETION EVENT -------------------------------------------------
 
// P13: the completion event is HELD until the consumer takes it.
property p_event_held;
  @(posedge clk) disable iff (!rst_n)
  (done_valid && !done_ready) |=> (done_valid && $stable(done_bytes)
                                              && $stable(done_queue));
endproperty
a_evheld : assert property (p_event_held);
 
// P14: and it reports the bytes that actually completed.
property p_event_truthful;
  @(posedge clk) disable iff (!rst_n)
  $rose(done_valid) |-> (done_bytes == $past(bytes_completed));
endproperty
a_evtrue : assert property (p_event_truthful);
 
// P15: THE DMA ENGINE DOES NOT FORMAT INTERRUPTS. Structural: its only
// interrupt-facing output is a normalized event (section 12).
property p_no_msix_knowledge;
  @(posedge clk) disable iff (!rst_n)
  done_valid |-> (done_queue < VEC_W'(1 << VEC_W));
endproperty
a_layer : assert property (p_no_msix_knowledge);
 
// P16: reset.
property p_reset;
  @(posedge clk)
  !rst_n |=> (!active && !tx_valid && !done_valid && (bytes_issued == '0));
endproperty
a_reset : assert property (p_reset);

xfer_done        did the transfer retire?          -> §14, P4
done_valid       was a completion event raised?    -> §16
done_ready       did the interrupt subsystem take it? -> Module 19
                 ...and was the event HELD?        -> P13, mutation 11
irq sent         was a notification transmitted?   -> 19.2/19.3
routing          did it reach a destination?       -> 19.4