Benchmark Interpretation — What Was Actually Measured?

// SYNTHESIZABLE. Benchmark instrumentation types.
package bench_pkg;
 
  parameter int CNT_W  = 48;
  parameter int RUN_W  = 16;
  parameter int BYTES_W = 13;
 
  typedef enum logic [2:0] {
    RUN_IDLE   = 3'd0,
    RUN_ACTIVE = 3'd1,
    RUN_FROZEN = 3'd2               // result readable, immutable
  } run_state_e;
 
  function automatic logic [CNT_W-1:0] sat_add(input logic [CNT_W-1:0] v,
                                               input logic [CNT_W-1:0] inc);
    logic [CNT_W:0] wide;
    wide = {1'b0, v} + {1'b0, inc};
    return wide[CNT_W] ? {CNT_W{1'b1}} : wide[CNT_W-1:0];
  endfunction
 
endpackage

import bench_pkg::*;
 
// SYNTHESIZABLE. Benchmark run controller with EPOCH ISOLATION (§10).
// A result is frozen at stop and cannot be mutated by anything that
// happens afterwards. Without this, a late transfer or a late error from
// run N lands in run N+1's result and neither run is trustworthy.
module benchmark_run_controller (
  input  logic clk,
  input  logic rst_n,
 
  input  logic               start,
  input  logic               stop,
  input  logic               xfer_valid,      // an ACCEPTED transfer
  input  logic [BYTES_W-1:0] xfer_bytes,
  input  logic               error_event,
  input  logic               replay_event,
 
  output run_state_e         state,
  output logic [RUN_W-1:0]   run_id,
  output logic               running,
  output logic [CNT_W-1:0]   run_cycles,
  output logic [CNT_W-1:0]   run_bytes,
  output logic [CNT_W-1:0]   run_transactions,
  output logic [31:0]        run_errors,
  output logic [31:0]        run_replays,
  output logic               result_valid,
  output logic               result_dirty     // errors or replay occurred
);
  run_state_e      st_q;
  logic [RUN_W-1:0] id_q;
  logic [CNT_W-1:0] cyc_q, byt_q, txn_q;
  logic [31:0]      err_q, rep_q;
 
  assign state            = st_q;
  assign run_id           = id_q;
  assign running          = (st_q == RUN_ACTIVE);
  assign run_cycles       = cyc_q;
  assign run_bytes        = byt_q;
  assign run_transactions = txn_q;
  assign run_errors       = err_q;
  assign run_replays      = rep_q;
  assign result_valid     = (st_q == RUN_FROZEN);
  // A run with errors or replay is NOT a clean-link result (§4). It is
  // reported, never silently discarded -- discarding is how a flaky link
  // becomes an impressive average.
  assign result_dirty     = (err_q != '0) || (rep_q != '0);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      st_q<=RUN_IDLE; id_q<='0; cyc_q<='0; byt_q<='0; txn_q<='0;
      err_q<='0; rep_q<='0;
    end else begin
      unique case (st_q)
        RUN_IDLE, RUN_FROZEN: begin
          if (start) begin
            // ZERO EVERYTHING at start. A snapshot-difference scheme leaks
            // whatever happened between runs into the new one.
            st_q  <= RUN_ACTIVE;
            id_q  <= id_q + RUN_W'(1);
            cyc_q <= '0; byt_q <= '0; txn_q <= '0; err_q <= '0; rep_q <= '0;
          end
        end
        RUN_ACTIVE: begin
          cyc_q <= sat_add(cyc_q, CNT_W'(1));
          if (xfer_valid) begin
            byt_q <= sat_add(byt_q, CNT_W'(xfer_bytes));
            txn_q <= sat_add(txn_q, CNT_W'(1));
          end
          if (error_event  && !(&err_q)) err_q <= err_q + 32'd1;
          if (replay_event && !(&rep_q)) rep_q <= rep_q + 32'd1;
          // SAME-CYCLE RULE (§11): a transfer ON the stop cycle is INSIDE
          // the run. The counters above have already taken it this cycle.
          if (stop) st_q <= RUN_FROZEN;
        end
        default: st_q <= RUN_IDLE;
      endcase
    end
  end
endmodule

import bench_pkg::*;
 
// SYNTHESIZABLE. First/last transfer tracker (§7).
// A run's REQUESTED duration and its ACTIVE interval are different
// numbers. §12 Model 14: a short run is dominated by fixed overhead, so
// dividing bytes by requested duration understates the streaming rate.
module active_interval_tracker (
  input  logic clk,
  input  logic rst_n,
  input  logic             running,
  input  logic             start,
  input  logic             xfer_valid,
  input  logic [CNT_W-1:0] run_cycles,
 
  output logic [CNT_W-1:0] first_xfer_cycle,
  output logic [CNT_W-1:0] last_xfer_cycle,
  output logic             any_transfer,
  output logic [CNT_W-1:0] active_span      // last - first, inclusive
);
  logic [CNT_W-1:0] f_q, l_q; logic seen_q;
 
  assign first_xfer_cycle = f_q;
  assign last_xfer_cycle  = l_q;
  assign any_transfer     = seen_q;
  // Guarded so an empty run reports 0, never a wrapped difference.
  assign active_span = seen_q ? (l_q - f_q + CNT_W'(1)) : '0;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin f_q<='0; l_q<='0; seen_q<=1'b0; end
    else if (start) begin f_q<='0; l_q<='0; seen_q<=1'b0; end
    else if (running && xfer_valid) begin
      if (!seen_q) begin f_q <= run_cycles; seen_q <= 1'b1; end  // FIRST, once
      l_q <= run_cycles;                                          // LAST, every time
    end
  end
endmodule

import bench_pkg::*;
 
// SYNTHESIZABLE. Per-cause stall snapshot, captured in the SAME epoch as
// the throughput result (§9). Chapter 22.1 §9 owns the classification;
// this block only ensures the attribution and the bytes describe the same
// run -- a result without a "why" is a number, not a finding.
module benchmark_stall_snapshot (
  input  logic clk,
  input  logic rst_n,
  input  logic             start,
  input  logic             stop,
  input  logic [RUN_W-1:0] run_id,
 
  // live counters from the 22.1 attribution block
  input  logic [CNT_W-1:0] c_transfer,
  input  logic [CNT_W-1:0] c_stalled,
  input  logic [CNT_W-1:0] c_no_credit,
  input  logic [CNT_W-1:0] c_no_work,
  input  logic [CNT_W-1:0] c_link_down,
 
  output logic [CNT_W-1:0] base_transfer,
  output logic [CNT_W-1:0] snap_transfer,
  output logic [CNT_W-1:0] snap_stalled,
  output logic [CNT_W-1:0] snap_no_credit,
  output logic [CNT_W-1:0] snap_no_work,
  output logic [CNT_W-1:0] snap_link_down,
  output logic [RUN_W-1:0] snap_run_id,
  output logic             snap_valid
);
  logic [CNT_W-1:0] b_t, b_s, b_c, b_w, b_l;
 
  assign base_transfer = b_t;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      b_t<='0; b_s<='0; b_c<='0; b_w<='0; b_l<='0;
      snap_transfer<='0; snap_stalled<='0; snap_no_credit<='0;
      snap_no_work<='0; snap_link_down<='0; snap_run_id<='0; snap_valid<=1'b0;
    end else begin
      if (start) begin
        // Rebase, so the snapshot is a DELTA over this run only.
        b_t<=c_transfer; b_s<=c_stalled; b_c<=c_no_credit;
        b_w<=c_no_work;  b_l<=c_link_down; snap_valid<=1'b0;
      end else if (stop) begin
        snap_transfer  <= c_transfer  - b_t;
        snap_stalled   <= c_stalled   - b_s;
        snap_no_credit <= c_no_credit - b_c;
        snap_no_work   <= c_no_work   - b_w;
        snap_link_down <= c_link_down - b_l;
        snap_run_id    <= run_id;                 // the epoch, carried along
        snap_valid     <= 1'b1;
      end
    end
  end
endmodule

import bench_pkg::*;
 
// SYNTHESIZABLE. Result record. Everything a consumer needs to decide
// whether this result may be compared with another one (§3) -- including
// the fields that say it MAY NOT be.
module benchmark_result_record (
  input  logic clk,
  input  logic rst_n,
  input  logic             freeze,
  input  logic [RUN_W-1:0] run_id,
  input  logic [CNT_W-1:0] bytes,
  input  logic [CNT_W-1:0] cycles,
  input  logic [CNT_W-1:0] active_span,
  input  logic [CNT_W-1:0] transactions,
  input  logic             dirty,
  input  logic             saturated,
  input  logic [5:0]       negotiated_width,     // read from the LINK, not the datasheet
  input  logic [2:0]       negotiated_speed,
  input  logic [1:0]       direction,
  input  logic [1:0]       measure_point,
 
  output logic             rec_valid,
  output logic [RUN_W-1:0] rec_run_id,
  output logic [CNT_W-1:0] rec_bytes,
  output logic [CNT_W-1:0] rec_cycles,
  output logic [CNT_W-1:0] rec_active_span,
  output logic [CNT_W-1:0] rec_transactions,
  output logic             rec_dirty,
  output logic             rec_saturated,
  output logic [5:0]       rec_width,
  output logic [2:0]       rec_speed,
  output logic [1:0]       rec_direction,
  output logic [1:0]       rec_measure_point
);
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      rec_valid<=1'b0; rec_run_id<='0; rec_bytes<='0; rec_cycles<='0;
      rec_active_span<='0; rec_transactions<='0; rec_dirty<=1'b0;
      rec_saturated<=1'b0; rec_width<='0; rec_speed<='0;
      rec_direction<='0; rec_measure_point<='0;
    end else if (freeze) begin
      // ONE cycle, ALL fields -- the atomicity rule of 22.5 §11, applied
      // to a benchmark record. A record assembled by successive reads can
      // describe two different runs.
      rec_valid        <= 1'b1;
      rec_run_id       <= run_id;
      rec_bytes        <= bytes;
      rec_cycles       <= cycles;
      rec_active_span  <= active_span;
      rec_transactions <= transactions;
      rec_dirty        <= dirty;
      rec_saturated    <= saturated;
      rec_width        <= negotiated_width;
      rec_speed        <= negotiated_speed;
      rec_direction    <= direction;
      rec_measure_point<= measure_point;
    end
  end
endmodule

import bench_pkg::*;
 
// VERIFICATION-ONLY. Guards the arithmetic software is about to do.
// A result that fails any of these must not be normalized (§6).
module benchmark_result_monitor (
  input logic             rec_valid,
  input logic [CNT_W-1:0] rec_bytes,
  input logic [CNT_W-1:0] rec_cycles,
  input logic [CNT_W-1:0] rec_active_span,
  input logic             rec_saturated,
  input logic [5:0]       rec_width,
 
  output logic err_zero_duration,
  output logic err_span_exceeds_run,
  output logic err_width_zero,
  output logic err_unusable
);
  always_comb begin
    // Dividing by a zero duration is the first thing software does wrong.
    err_zero_duration    = rec_valid && (rec_cycles == '0) && (rec_bytes != '0);
    err_span_exceeds_run = rec_valid && (rec_active_span > rec_cycles);
    // Normalizing against a zero or unknown negotiated width (§6).
    err_width_zero       = rec_valid && (rec_width == '0);
    err_unusable         = err_zero_duration || err_span_exceeds_run
                        || err_width_zero || rec_saturated;
  end
endmodule

// ==================================================================
// RUN LIFECYCLE AND EPOCH ISOLATION (§10).
// ==================================================================
 
// P1: a run begins only on start, and only from a non-active state.
property p_start_from_non_active;
  @(posedge clk) disable iff (!rst_n)
    $rose(running) |-> $past(start && (state != RUN_ACTIVE));
endproperty
 
// P2: run_id advances exactly once per accepted start.
property p_run_id_once_per_start;
  @(posedge clk) disable iff (!rst_n)
    (run_id != $past(run_id)) |-> $past(start && (state != RUN_ACTIVE));
endproperty
 
// P3: every counter is ZERO at the start of a run. A snapshot-difference
// scheme leaks whatever happened between runs into the new one.
property p_counters_zero_at_start;
  @(posedge clk) disable iff (!rst_n)
    (start && (state != RUN_ACTIVE)) |=>
      ((run_bytes == '0) && (run_transactions == '0) && (run_errors == '0));
endproperty
 
// P4: a transfer on the start cycle belongs to the NEW run.
property p_start_cycle_transfer_new_run;
  @(posedge clk) disable iff (!rst_n)
    (start && (state != RUN_ACTIVE) && xfer_valid) |=> (run_transactions <= CNT_W'(1));
endproperty
 
// P5: nothing is counted while not running.
property p_no_count_when_idle;
  @(posedge clk) disable iff (!rst_n)
    (!running) |=> ($stable(run_bytes) && $stable(run_transactions));
endproperty
 
// P6: stop while idle publishes nothing.
property p_stop_while_idle_noop;
  @(posedge clk) disable iff (!rst_n)
    (stop && (state == RUN_IDLE)) |=> (state == RUN_IDLE);
endproperty
 
// ==================================================================
// FREEZING (§10) -- a result must be immutable.
// ==================================================================
 
// P7: a transfer on the stop cycle is INSIDE the closing run.
property p_stop_cycle_transfer_counted;
  @(posedge clk) disable iff (!rst_n)
    (running && stop && xfer_valid) |=>
      (run_transactions == $past(run_transactions) + CNT_W'(1));
endproperty
 
// P8: stop freezes; the result becomes readable exactly once.
property p_stop_freezes;
  @(posedge clk) disable iff (!rst_n)
    (running && stop) |=> (result_valid && (state == RUN_FROZEN));
endproperty
 
// P9: a frozen result cannot be mutated by later events.
property p_frozen_result_immutable;
  @(posedge clk) disable iff (!rst_n)
    ((state == RUN_FROZEN) && !start) |=>
      ($stable(run_bytes) && $stable(run_cycles) && $stable(run_errors));
endproperty
 
// P10: an error after stop belongs to no run.
property p_late_error_not_attributed;
  @(posedge clk) disable iff (!rst_n)
    ((state == RUN_FROZEN) && error_event && !start) |=> $stable(run_errors);
endproperty
 
// P11: errors and replays are STICKY within a run -- a dirty run is
// reported as dirty, never quietly cleaned up.
property p_dirty_sticky_within_run;
  @(posedge clk) disable iff (!rst_n)
    (running && result_dirty) |=> (result_dirty || start);
endproperty
 
// ==================================================================
// ACTIVE INTERVAL (§7) -- requested duration is not active duration.
// ==================================================================
 
// P12: the first-transfer cycle is captured exactly once per run.
property p_first_transfer_once;
  @(posedge clk) disable iff (!rst_n)
    ($rose(any_transfer)) |-> $past(running && xfer_valid);
endproperty
 
// P13: the last-transfer cycle updates on every accepted transfer.
property p_last_transfer_updates;
  @(posedge clk) disable iff (!rst_n)
    (running && xfer_valid) |=> (last_xfer_cycle == $past(run_cycles));
endproperty
 
// P14: the active span never exceeds the run, and an empty run reports 0
// rather than a wrapped difference.
property p_span_bounded;
  @(posedge clk) disable iff (!rst_n)
    (active_span <= run_cycles) && (!any_transfer |-> (active_span == '0));
endproperty
 
// ==================================================================
// ATTRIBUTION AND RECORD (§9, §10).
// ==================================================================
 
// P15: the stall snapshot carries the run_id of the run it describes --
// an attribution from a different epoch is worse than none.
property p_snapshot_epoch_matches;
  @(posedge clk) disable iff (!rst_n)
    snap_valid |-> (snap_run_id == $past(run_id));
endproperty
 
// P16: the record is assembled from ONE cycle (22.5 §11's atomicity rule).
property p_record_atomic;
  @(posedge clk) disable iff (!rst_n)
    rec_valid && $rose(rec_valid) |->
      ((rec_bytes == $past(bytes)) && (rec_cycles == $past(cycles))
        && (rec_run_id == $past(run_id)));
endproperty
 
// P17: the harness never drives the datapath. A benchmark controller that
// throttles is measuring a system that does not otherwise exist.
property p_harness_does_not_drive;
  @(posedge clk) disable iff (!rst_n)
    $stable(xfer_valid) or !$stable({run_bytes, run_cycles});
endproperty
 
// P18: reset clears run state and publishes nothing.
property p_reset_clears_run;
  @(posedge clk)
    (!rst_n) |=> (!running && !result_valid && (run_bytes == '0));
endproperty
 
// P19: a zero-duration run with bytes is flagged before software divides.
property p_zero_duration_flagged;
  @(posedge clk) disable iff (!rst_n)
    (rec_valid && (rec_cycles == '0) && (rec_bytes != '0)) |-> err_zero_duration;
endproperty
 
// P20: a result normalized against an unknown width is rejected (§6).
property p_width_required_for_normalization;
  @(posedge clk) disable iff (!rst_n)
    (rec_valid && (rec_width == '0)) |-> err_unusable;
endproperty