Capstone: the generic link bug hunt

// link_sink.sv: the target of the generic link (read-only in this lesson).
// A DEPTH-entry FIFO behind valid/ready. It takes a beat at every rising edge where valid and
// ready are both 1, and hands beats on to its consumer at every edge where drain and out_valid
// are both 1. ready is 1 while the FIFO has room: it never waits for valid.
module link_sink #(parameter int DEPTH = 4, parameter int WIDTH = 8) (
  input  logic             clk,
  input  logic             rst_n,
  input  logic             valid,
  input  logic [WIDTH-1:0] data,
  input  logic             last,
  output logic             ready,
  input  logic             drain,       // the consumer behind the FIFO takes a beat while 1
  output logic             out_valid,
  output logic [WIDTH-1:0] out_data,
  output logic             out_last,
  output int               count        // beats held right now
);
  logic [WIDTH:0] mem [DEPTH];          // {last, data}
  int wr = 0, rd = 0;
  assign ready     = (count < DEPTH);
  assign out_valid = (count > 0);
  assign {out_last, out_data} = mem[rd];
  wire push = valid && ready;
  wire pop  = drain && out_valid;
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      wr <= 0; rd <= 0; count <= 0;
    end else begin
      if (push) begin mem[wr] <= {last, data}; wr <= (wr + 1) % DEPTH; end
      if (pop) rd <= (rd + 1) % DEPTH;
      count <= count + (push ? 1 : 0) - (pop ? 1 : 0);
    end
  end
endmodule

// link_checker.sv: the rules of the generic link, checked at every rising edge (read-only).
// Each broken rule is named with the edge where it was seen:
//   reset   valid is 0 while reset is active;
//   hold    once valid is 1 and ready is 0, valid is still 1 at the next edge (an offer is not withdrawn);
//   stable  while an offer waits, data and last do not change;
//   known   data is not x while valid is 1.
// The one rule no checker can see on the wires, "valid must not wait for ready", is the stimulus's
// own responsibility (lesson P1.3).
// It also counts transfers and stalled edges, and prints one summary line at the end of the run.
module link_checker #(parameter int WIDTH = 8) (
  input logic             clk,
  input logic             rst_n,
  input logic             valid,
  input logic             ready,
  input logic [WIDTH-1:0] data,
  input logic             last
);
  int cycle = -1, transfers = 0, stalls = 0, broken = 0;
  logic             pv = 0, pr = 0, pl = 0;
  logic [WIDTH-1:0] pd = 'x;
  always @(posedge clk) begin
    cycle++;
    if (!rst_n) begin
      if (valid === 1) report("reset", "valid is 1 during reset");
    end else begin
      if (pv && !pr && valid !== 1) report("hold", "valid dropped before ready: the offer was withdrawn");
      if (pv && !pr && valid === 1 && data !== pd) report("stable", "data changed while the offer waited");
      if (pv && !pr && valid === 1 && last !== pl) report("stable", "last changed while the offer waited");
      if (valid === 1 && $isunknown(data)) report("known", "data is x while valid is 1");
      if (valid === 1 && ready === 1) transfers++;
      if (valid === 1 && ready !== 1) stalls++;
    end
    pv = (valid === 1); pr = (ready === 1); pd = data; pl = last;
  end
  function void report(input string rule, input string what);
    broken++;
    $display("RULE %s broken at edge %0d: %s", rule, cycle, what);
  endfunction
  final $display("checker: %0d transfers, %0d stalled edges, %0d rules broken", transfers, stalls, broken);
endmodule

// link_tasks.svh: the source side of the generic link, as tasks for the stimulus (read-only).
// Every task returns one time unit after the rising edge where its last beat transferred, so the
// next call starts driving in the following cycle. `cycle` counts rising edges from 0.
int cycle = -1;
always @(posedge clk) cycle = cycle + 1;

// Offer one beat and hold it until the sink takes it.
task automatic send(input logic [7:0] d, input logic is_last = 0);
  valid = 1; data = d; last = is_last;
  do @(posedge clk); while (!ready);
  #1 $display("edge %0d: beat %02h taken", cycle, d);
  valid = 0; data = 'x; last = 0;
endtask

// A burst of n beats with consecutive values; last marks the final beat.
task automatic send_burst(input logic [7:0] first, input int n);
  for (int i = 0; i < n; i++) begin
    valid = 1; data = first + i[7:0]; last = (i == n - 1);
    do @(posedge clk); while (!ready);
    #1 $display("edge %0d: beat %02h taken%s", cycle, first + i[7:0], last ? " (last)" : "");
  end
  valid = 0; data = 'x; last = 0;
endtask

// Drive nothing for n cycles.
task automatic idle(input int n);
  repeat (n) @(posedge clk);
  #1;
endtask

// faulty_link.sv: a source and a sink for the generic link, each with selectable faults
// (read-only). fault 0 is correct behaviour.
//   1  hold      the source drops valid for one cycle during a stall, then offers the same beat again
//   2  stable    the source changes data once while an offer waits
//   3  reset     the source drives valid during reset
//   4  overflow  the sink keeps ready at 1 when it is full and overwrites its oldest beat
//   5  repeat    the sink moves its read pointer late once, so the consumer gets a beat twice
module faulty_source #(parameter int N = 4) (
  input  logic       clk,
  input  logic       rst_n,
  input  int         fault,
  input  logic       go,        // 1: offer N beats, then stop
  input  logic       ready,
  output logic       valid,
  output logic [7:0] data,
  output int         sent
);
  int i;
  logic misbehaved;
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      valid <= (fault == 3); data <= 8'h10; i <= 0; sent <= 0; misbehaved <= 0;
    end else if (!valid) begin
      if (go && i < N) begin valid <= 1; data <= 8'h10 + i[7:0]; end
    end else if (ready) begin                       // a transfer at this edge
      sent <= sent + 1; i <= i + 1;
      if (i + 1 < N) data <= 8'h10 + i[7:0] + 8'd1; else valid <= 0;
    end else if (!misbehaved) begin                 // stalled at this edge
      if (fault == 1) begin valid <= 0; misbehaved <= 1; end
      if (fault == 2) begin data <= data + 8'd1; misbehaved <= 1; end
    end
  end
endmodule

module faulty_sink #(parameter int DEPTH = 2) (
  input  logic       clk,
  input  logic       rst_n,
  input  int         fault,
  input  logic       valid,
  input  logic [7:0] data,
  output logic       ready,
  input  logic       drain,
  output logic       out_valid,
  output logic [7:0] out_data,
  output int         count
);
  logic [7:0] mem [DEPTH];
  int wr = 0, rd = 0;
  logic misbehaved;
  assign ready     = (fault == 4) ? 1'b1 : (count < DEPTH);
  assign out_valid = (count > 0);
  assign out_data  = mem[rd];
  wire push = valid && ready;
  wire pop  = drain && out_valid;
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      wr <= 0; rd <= 0; count <= 0; misbehaved <= 0;
    end else begin
      if (push) begin mem[wr] <= data; wr <= (wr + 1) % DEPTH; end
      if (pop) begin
        if (fault == 5 && !misbehaved) misbehaved <= 1;   // this pop forgets to move rd
        else rd <= (rd + 1) % DEPTH;
      end
      if (push && count == DEPTH) count <= count - (pop ? 1 : 0);   // full: the write lands on the oldest beat
      else count <= count + (push ? 1 : 0) - (pop ? 1 : 0);
    end
  end
endmodule