Performance and Debug Review

// ---------------------------------------------------------------------
// perfreview_pkg -- the seven deferred thresholds of Chapter 26.1
// Section 12, the four outcomes a threshold can be in, and the latency
// constants Sections 6 to 12 derive.
//
// Times are in nanoseconds unless a name says otherwise. Areas are in
// BCE, one bit of usable on-die SRAM, 0.35 gate-equivalents, twenty to
// a flip-flop -- the unit Chapter 19.7 Section 19 established.
// ---------------------------------------------------------------------
package perfreview_pkg;

  // The seven. Each one has a default in the RTL and an owner who is
  // not on the design team.
  typedef enum logic [2:0] {
    TH_BUFFER,      // the burst distribution      -- the deployment
    TH_TABLE,       // the address population      -- the deployment
    TH_AGEING,      // the address recycle rate    -- the orchestrator
    TH_REPLAY,      // the fabric's path skew      -- the topology
    TH_STORM,       // the legitimate flood rate   -- the deployment
    TH_FLAP,        // the legitimate move rate    -- the site
    TH_WATERMARK    // the link's dead time        -- the cable plant
  } threshold_e;

  localparam int N_THRESH = 7;

  typedef enum logic [1:0] {
    OWN_DESIGN,       // derivable here
    OWN_STRUCTURAL,   // follows from the topology of the design itself
    OWN_EXTERNAL,     // somebody outside the room
    OWN_SILICON       // nobody, until first bring-up -- Section 17
  } owner_e;

  typedef enum logic [1:0] {
    TH_UNSET,       // no value at all
    TH_DEFAULT,     // a value, chosen by an implementer, not exposed
    TH_DEFERRED,    // owner named, parameter exposed
    TH_BOUND        // owner answered, value recorded
  } th_state_e;

  // Latency constants, from Chapter 26.1 Section 8's reconciliation.
  localparam int HOP_FLOOR_NS      = 913;      // 912.88, rounded
  localparam int HOPS              = 5;
  localparam int FIVE_HOP_FLOOR_NS = 4564;     // 4.564 us
  localparam int DESIGN_OWNED_NS   = 80;       // lookup 30 + fabric 50
  localparam int DESIGN_OWNED_PPM  = 87623;    // 8.7623 per cent

  // The buffer, from Chapter 23.3 Section 9. One port claiming its
  // dynamic-threshold share is 108 616 cells of 256 octets.
  localparam int  CELL_OCTETS        = 256;
  localparam int  MAX_CELLS_ONE_PORT = 108616;
  localparam int  MAX_QUEUE_US       = 2224;

  // Percentiles are an index into a distribution, not a unit, so this
  // package carries the window alongside every one of them. Section 12.
  typedef struct packed {
    logic [31:0] value_ns;
    logic [19:0] percentile_ppm;   // 999900 is p99.99
    logic [31:0] window_samples;
  } latency_claim_t;

  // The rule Section 12 derives: a window of W samples can support a
  // percentile no finer than 1 - 1/W. Expressed as the minimum window
  // for ten expected exceedances, which is the usable form.
  function automatic int unsigned min_window(int unsigned pct_ppm);
    if (pct_ppm >= 1000000) return 32'hFFFF_FFFF;
    return (10 * 1000000) / (1000000 - pct_ppm);
  endfunction

  // Observability, Section 10, in BCE at 64 ports.
  localparam int PORTS             = 64;
  localparam int DATAPATH_BCE      = 283320;
  localparam int SWITCH_BCE_DIV1K  = 562000;   // 5.62e8 / 1000

endpackage

// ---------------------------------------------------------------------
// threshold_model -- one threshold in, its state and its owner out.
//
// The module's whole value is the DEFAULT state. A threshold with a
// value looks identical to one with a derivation in every report this
// track has examined, and the difference is whether anybody could
// change it in the field.
// ---------------------------------------------------------------------
module threshold_model
  import perfreview_pkg::*;
(
  input  logic        clk,
  input  logic        rst_n,

  input  logic        th_valid,
  input  threshold_e  th_id,
  input  logic        has_value,        // the RTL has a number
  input  logic        is_exposed,       // the number is a register
  input  logic        owner_named,      // somebody is accountable
  input  logic        owner_answered,   // and they supplied a value
  input  logic        needs_measurement,// only silicon can supply it

  output logic        out_valid,
  output th_state_e   state,
  output owner_e      owner,
  output logic        became_a_default, // the failure Section 4 names
  output logic        deferred_correctly
);

  // Which owner each threshold has. Six external, one structural, and
  // Section 17's one that no conversation can close.
  function automatic owner_e owner_of(threshold_e t, logic meas);
    if (meas) return OWN_SILICON;
    case (t)
      TH_BUFFER, TH_TABLE, TH_STORM : return OWN_EXTERNAL;
      TH_AGEING, TH_FLAP            : return OWN_EXTERNAL;
      TH_REPLAY                     : return OWN_STRUCTURAL;
      TH_WATERMARK                  : return OWN_EXTERNAL;
      default                       : return OWN_DESIGN;
    endcase
  endfunction

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      out_valid          <= 1'b0;
      state              <= TH_UNSET;
      owner              <= OWN_DESIGN;
      became_a_default   <= 1'b0;
      deferred_correctly <= 1'b0;
    end else begin
      out_valid <= th_valid;
      if (th_valid) begin
        owner <= owner_of(th_id, needs_measurement);

        if (owner_answered && has_value) begin
          state              <= TH_BOUND;
          became_a_default   <= 1'b0;
          deferred_correctly <= 1'b0;
        end else if (owner_named && is_exposed) begin
          // The correct handling: named, exposed, awaiting an answer.
          state              <= TH_DEFERRED;
          became_a_default   <= 1'b0;
          deferred_correctly <= 1'b1;
        end else if (has_value) begin
          // A number, no owner, not exposed. This is the state every
          // one of the opening table's four defaults was in.
          state              <= TH_DEFAULT;
          became_a_default   <= 1'b1;
          deferred_correctly <= 1'b0;
        end else begin
          state              <= TH_UNSET;
          became_a_default   <= 1'b0;
          deferred_correctly <= 1'b0;
        end
      end
    end
  end

endmodule

// ---------------------------------------------------------------------
// deferral_register -- the seven thresholds as live, writable state,
// each with its owner, its default, whether it has been answered, and
// whether the design exposes it.
//
// The module is the artefact Chapter 26.1 Section 12 said an
// architecture review should produce. Here it is, as registers.
// ---------------------------------------------------------------------
module deferral_register
  import perfreview_pkg::*;
(
  input  logic            clk,
  input  logic            rst_n,

  // The management write port -- this is the exposure.
  input  logic            wr_en,
  input  threshold_e      wr_id,
  input  logic [31:0]     wr_value,

  // The review's annotations, loaded at configuration time.
  input  logic            cfg_en,
  input  threshold_e      cfg_id,
  input  logic            cfg_owner_named,
  input  logic            cfg_exposed,
  input  logic            cfg_needs_silicon,

  input  logic [31:0]     defaults [N_THRESH],

  output logic [31:0]     value      [N_THRESH],
  output logic            answered   [N_THRESH],
  output logic            exposed    [N_THRESH],
  output logic            owner_named[N_THRESH],
  output logic            silicon_gated [N_THRESH],

  output logic [3:0]      n_bound,
  output logic [3:0]      n_deferred,
  output logic [3:0]      n_defaulted,
  output logic [3:0]      n_silicon_gated,
  output logic            all_thresholds_disposed
);

  integer i;

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (i = 0; i < N_THRESH; i = i + 1) begin
        value[i]         <= defaults[i];
        answered[i]      <= 1'b0;
        exposed[i]       <= 1'b0;
        owner_named[i]   <= 1'b0;
        silicon_gated[i] <= 1'b0;
      end
    end else begin
      if (cfg_en) begin
        owner_named[cfg_id]   <= cfg_owner_named;
        exposed[cfg_id]       <= cfg_exposed;
        silicon_gated[cfg_id] <= cfg_needs_silicon;
      end
      // A write is the owner answering. It is the ONLY way answered
      // becomes high, which is why exposure and accountability are the
      // same mechanism rather than two.
      if (wr_en && exposed[wr_id]) begin
        value[wr_id]    <= wr_value;
        answered[wr_id] <= 1'b1;
      end
    end
  end

  // The four counts of Section 4, recomputed combinationally so a
  // management read always sees the current disposition.
  always_comb begin
    n_bound         = '0;
    n_deferred      = '0;
    n_defaulted     = '0;
    n_silicon_gated = '0;
    for (int j = 0; j < N_THRESH; j = j + 1) begin
      if (silicon_gated[j] && !answered[j])
        n_silicon_gated = n_silicon_gated + 4'd1;
      else if (answered[j])
        n_bound = n_bound + 4'd1;
      else if (owner_named[j] && exposed[j])
        n_deferred = n_deferred + 4'd1;
      else
        n_defaulted = n_defaulted + 4'd1;
    end
    // Disposed means every threshold is in a state somebody chose.
    // A defaulted threshold is the one state nobody chose.
    all_thresholds_disposed = (n_defaulted == 4'd0);
  end

endmodule

// ---------------------------------------------------------------------
// latency_percentile -- estimate a percentile from a stream of measured
// latencies, and REFUSE to report one the window cannot support.
//
// The refusal is the module's reason for existing. Section 12 shows a
// 1024-sample window reporting a p99.99 that is really a p99.902,
// biased low by 24.88 per cent, with no indication that anything is
// wrong with the number.
// ---------------------------------------------------------------------
module latency_percentile
  import perfreview_pkg::*;
#(
  parameter int unsigned WINDOW    = 1024,
  // Log-spaced buckets, so the tail is resolved without storing samples.
  parameter int unsigned N_BUCKETS = 32,
  parameter int unsigned BUCKET_SHIFT = 6    // 64 ns per bucket at the base
)(
  input  logic          clk,
  input  logic          rst_n,
  input  logic          clear,

  input  logic          sample_valid,
  input  logic [31:0]   sample_ns,

  // What the caller wants, in parts per million: 999900 is p99.99.
  input  logic [19:0]   want_ppm,

  output logic [31:0]   estimate_ns,
  output logic [31:0]   samples_seen,
  output logic [31:0]   window_required,
  output logic          estimate_is_supported,   // the refusal
  output logic [19:0]   best_supported_ppm,
  output logic [31:0]   observed_max_ns,
  output latency_claim_t claim                   // value, percentile, window
);

  logic [31:0] bucket [N_BUCKETS];
  logic [31:0] total;

  // Log-spaced bucket index: the leading one of the sample, floored.
  function automatic int unsigned bucket_of(logic [31:0] ns);
    int unsigned b;
    b = 0;
    for (int k = 31; k >= 0; k = k - 1)
      if (ns[k]) begin b = k; break; end
    if (b < BUCKET_SHIFT) return 0;
    if ((b - BUCKET_SHIFT) >= N_BUCKETS) return N_BUCKETS - 1;
    return b - BUCKET_SHIFT;
  endfunction

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n || clear) begin
      for (int i = 0; i < N_BUCKETS; i = i + 1) bucket[i] <= '0;
      total           <= '0;
      observed_max_ns <= '0;
    end else if (sample_valid) begin
      bucket[bucket_of(sample_ns)] <= bucket[bucket_of(sample_ns)] + 32'd1;
      total <= total + 32'd1;
      if (sample_ns > observed_max_ns) observed_max_ns <= sample_ns;
    end
  end

  // Walk the buckets from the top until the requested tail mass is
  // accounted for. The answer is a bucket boundary, which is why the
  // buckets are log-spaced: a linear scale would resolve the median
  // beautifully and the tail not at all.
  logic [31:0] target_tail;
  logic [31:0] running;
  logic [31:0] est;

  always_comb begin
    samples_seen    = total;
    window_required = min_window(want_ppm);
    // The refusal: ten expected exceedances, or the number is a maximum
    // wearing a percentile's name.
    estimate_is_supported = (total >= window_required) && (total != 0);

    // The finest percentile this window can actually support.
    best_supported_ppm = (total == 0) ? 20'd0
                       : 20'(1000000 - (10 * 1000000) / int'(total));

    target_tail = 32'((longint'(total) *
                       longint'(1000000 - int'(want_ppm))) / 1000000);
    running = '0;
    est     = observed_max_ns;
    for (int i = N_BUCKETS - 1; i >= 0; i = i - 1) begin
      running = running + bucket[i];
      if (running >= target_tail) begin
        est = 32'(32'd1 << (i + BUCKET_SHIFT));
        break;
      end
    end
    estimate_ns = est;

    claim.value_ns       = est;
    claim.percentile_ppm = want_ppm;
    claim.window_samples = total;
  end

endmodule

// ---------------------------------------------------------------------
// incast_model -- the regime Section 8 separates from Section 6. No
// percentiles here, because there is no steady state: an incast has a
// fill time, a peak and a recovery time.
//
// The module's output that matters is regime_is_overload, because every
// queueing statistic computed while it is high is meaningless.
// ---------------------------------------------------------------------
module incast_model
  import perfreview_pkg::*;
#(
  // Octets per second per sender at 100 Gb/s, in units of 1e6 oct/s.
  parameter int unsigned LINE_MOCT_S = 12500,
  parameter int unsigned CAP_OCTETS  = 27800000    // 108 616 cells
)(
  input  logic          clk,
  input  logic          rst_n,

  input  logic          eval,
  input  logic [7:0]    n_senders,
  input  logic [31:0]   burst_octets_per_sender,

  output logic          regime_is_overload,
  output logic [31:0]   fill_rate_moct_s,
  output logic [31:0]   fill_time_us,
  output logic [31:0]   drain_time_us,
  output logic [31:0]   asymmetry,        // drain / fill, which is N-1
  output logic          buffer_overflows,
  output logic [31:0]   octets_dropped,
  output logic [31:0]   peak_queue_octets
);

  logic [63:0] offered;
  logic [63:0] peak;

  always_comb begin
    // Overload is a comparison of rates, not a probability. One sender
    // into one port is rho = 1 exactly and never builds a queue; two
    // is the first overload case.
    regime_is_overload = (n_senders > 8'd1);

    fill_rate_moct_s = regime_is_overload
                     ? 32'((int'(n_senders) - 1) * int'(LINE_MOCT_S))
                     : 32'd0;

    // Microseconds to reach the cap, at the fill rate. Units: octets
    // divided by 1e6 octets per second gives microseconds directly.
    fill_time_us = (fill_rate_moct_s == 0) ? 32'hFFFF_FFFF
                 : 32'(CAP_OCTETS / fill_rate_moct_s);

    // Drain is always one line rate, whatever N is. This is the row
    // of Section 8's table that does not move.
    drain_time_us = 32'(CAP_OCTETS / LINE_MOCT_S);

    asymmetry = (fill_time_us == 0) ? 32'd0
              : 32'(drain_time_us / fill_time_us);

    // How much the senders actually offer, against what fits.
    offered = 64'(n_senders) * 64'(burst_octets_per_sender);
    peak    = (offered > 64'(CAP_OCTETS)) ? 64'(CAP_OCTETS) : offered;

    peak_queue_octets = 32'(peak);
    buffer_overflows  = (offered > 64'(CAP_OCTETS));
    octets_dropped    = buffer_overflows
                      ? 32'(offered - 64'(CAP_OCTETS)) : 32'd0;
  end

endmodule

// ---------------------------------------------------------------------
// obs_bank -- the instruments Section 10 prices, as one block: a
// log-spaced latency histogram, a per-queue maximum watermark, and the
// regime bit that says which histogram a sample belongs in.
//
// The watermark is the structure Section 4 argues for over a sampled
// occupancy: a 35-microsecond peak is invisible to a poll seconds apart.
// ---------------------------------------------------------------------
module obs_bank
  import perfreview_pkg::*;
#(
  parameter int unsigned N_QUEUES  = 512,
  parameter int unsigned N_BUCKETS = 32,
  parameter int unsigned BUCKET_SHIFT = 6
)(
  input  logic          clk,
  input  logic          rst_n,

  // Latency samples, tagged with the regime they were taken in.
  input  logic          lat_valid,
  input  logic [31:0]   lat_ns,
  input  logic          in_overload,       // from Section 9

  // Queue occupancy, sampled every cycle rather than polled.
  input  logic          occ_valid,
  input  logic [8:0]    occ_queue,
  input  logic [31:0]   occ_cells,

  // Management read, which clears the watermark it returns.
  input  logic          rd_en,
  input  logic [8:0]    rd_queue,

  output logic [31:0]   rd_watermark,
  output logic [31:0]   hist_steady  [N_BUCKETS],
  output logic [31:0]   hist_overload[N_BUCKETS],
  output logic [31:0]   n_steady,
  output logic [31:0]   n_overload,
  output logic [19:0]   overload_share_ppm
);

  logic [31:0] watermark [N_QUEUES];

  function automatic int unsigned bucket_of(logic [31:0] ns);
    int unsigned b;
    b = 0;
    for (int k = 31; k >= 0; k = k - 1)
      if (ns[k]) begin b = k; break; end
    if (b < BUCKET_SHIFT) return 0;
    if ((b - BUCKET_SHIFT) >= N_BUCKETS) return N_BUCKETS - 1;
    return b - BUCKET_SHIFT;
  endfunction

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      for (int i = 0; i < N_BUCKETS; i = i + 1) begin
        hist_steady[i]   <= '0;
        hist_overload[i] <= '0;
      end
      for (int q = 0; q < N_QUEUES; q = q + 1) watermark[q] <= '0;
      n_steady     <= '0;
      n_overload   <= '0;
      rd_watermark <= '0;
    end else begin
      // Two histograms, switched by the regime bit. Section 9's
      // production note: a percentile over a mixture is a percentile
      // of nothing.
      if (lat_valid) begin
        if (in_overload) begin
          hist_overload[bucket_of(lat_ns)] <=
            hist_overload[bucket_of(lat_ns)] + 32'd1;
          n_overload <= n_overload + 32'd1;
        end else begin
          hist_steady[bucket_of(lat_ns)] <=
            hist_steady[bucket_of(lat_ns)] + 32'd1;
          n_steady <= n_steady + 32'd1;
        end
      end

      // The watermark: maximum since last read, updated every cycle.
      if (occ_valid && (occ_cells > watermark[occ_queue]))
        watermark[occ_queue] <= occ_cells;

      // Read-and-clear, so consecutive reads are disjoint intervals
      // rather than a running maximum that saturates at the first peak.
      if (rd_en) begin
        rd_watermark        <= watermark[rd_queue];
        watermark[rd_queue] <= '0;
      end
    end
  end

  always_comb begin
    overload_share_ppm = ((n_steady + n_overload) == 0) ? 20'd0
                       : 20'((longint'(n_overload) * 1000000)
                             / longint'(n_steady + n_overload));
  end

endmodule

// ---------------------------------------------------------------------
// window_auditor -- given a latency claim, decide whether the window
// it was measured over can support the percentile it names, and say
// which percentile it can support instead.
//
// This is the module that would have stopped a 1024-sample maximum from
// being published as a p99.99 for the life of a product.
// ---------------------------------------------------------------------
module window_auditor
  import perfreview_pkg::*;
#(
  // Expected exceedances required for an estimate to be supported.
  parameter int unsigned EXCEEDANCES = 10
)(
  input  logic             clk,
  input  logic             rst_n,

  input  logic             claim_valid,
  input  latency_claim_t   claim,
  input  logic             from_histogram,   // counts, not samples

  output logic             out_valid,
  output logic             supported,
  output logic [19:0]      supportable_ppm,
  output logic [31:0]      window_required,
  output logic [31:0]      window_shortfall,
  output logic [15:0]      n_claims,
  output logic [15:0]      n_unsupported,
  output logic [15:0]      n_histogram_claims,
  output logic             any_unsupported_claim
);

  logic [31:0] need;
  logic [19:0] best;

  always_comb begin
    // The window a claimed percentile needs.
    need = (claim.percentile_ppm >= 20'd1000000) ? 32'hFFFF_FFFF
         : 32'((EXCEEDANCES * 1000000) /
               (1000000 - int'(claim.percentile_ppm)));

    // The finest percentile this window supports. A histogram is not
    // window-limited in the same way: it accumulates counts, so its
    // limit is the total sample count rather than a stored depth.
    best = (claim.window_samples == 0) ? 20'd0
         : 20'(1000000 - (EXCEEDANCES * 1000000)
                         / int'(claim.window_samples));
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      out_valid          <= 1'b0;
      supported          <= 1'b0;
      supportable_ppm    <= '0;
      window_required    <= '0;
      window_shortfall   <= '0;
      n_claims           <= '0;
      n_unsupported      <= '0;
      n_histogram_claims <= '0;
    end else begin
      out_valid <= claim_valid;
      if (claim_valid) begin
        n_claims        <= n_claims + 16'd1;
        window_required <= need;
        supportable_ppm <= best;

        if (from_histogram)
          n_histogram_claims <= n_histogram_claims + 16'd1;

        if (claim.window_samples >= need) begin
          supported        <= 1'b1;
          window_shortfall <= '0;
        end else begin
          supported        <= 1'b0;
          window_shortfall <= need - claim.window_samples;
          n_unsupported    <= n_unsupported + 16'd1;
        end
      end
    end
  end

  always_comb begin
    any_unsupported_claim = (n_unsupported != 16'd0);
  end

endmodule

// ---------------------------------------------------------------------
// perf_telemetry -- the numbers a performance review reads at any
// moment, and six flags that each name a sentence somebody must write.
// ---------------------------------------------------------------------
module perf_telemetry
  import perfreview_pkg::*;
(
  input  logic          clk,
  input  logic          rst_n,
  input  logic          clear,

  // From the deferral register, Section 5.
  input  logic [3:0]    n_bound,
  input  logic [3:0]    n_deferred,
  input  logic [3:0]    n_defaulted,
  input  logic [3:0]    n_silicon_gated,

  // From the percentile estimator and the auditor, Sections 7 and 13.
  input  logic          claim_valid,
  input  logic          claim_supported,
  input  latency_claim_t claim,

  // From the observability bank, Section 11.
  input  logic [31:0]   n_steady,
  input  logic [31:0]   n_overload,
  input  logic [31:0]   watermark_peak_cells,

  // Alarm configuration, for prohibition 6.
  input  logic [19:0]   alarm_threshold_ppm,
  input  logic [19:0]   metric_ceiling_ppm,

  output logic [19:0]   thresholds_disposed_ppm,
  output logic [19:0]   overload_share_ppm,
  output logic [19:0]   buffer_peak_share_ppm,
  output logic [15:0]   c_unsupported_claims,
  output logic [15:0]   c_claims,
  output logic          v_threshold_defaulted,
  output logic          v_claim_without_window,
  output logic          v_claim_unsupported,
  output logic          v_percentile_over_mixture,
  output logic          v_alarm_unreachable,
  output logic          v_awaiting_silicon
);

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n || clear) begin
      c_unsupported_claims <= '0;
      c_claims             <= '0;
    end else if (claim_valid) begin
      c_claims <= c_claims + 16'd1;
      if (!claim_supported)
        c_unsupported_claims <= c_unsupported_claims + 16'd1;
    end
  end

  always_comb begin
    thresholds_disposed_ppm =
      20'((int'(N_THRESH - n_defaulted) * 1000000) / N_THRESH);

    overload_share_ppm = ((n_steady + n_overload) == 0) ? 20'd0
                       : 20'((longint'(n_overload) * 1000000)
                             / longint'(n_steady + n_overload));

    buffer_peak_share_ppm =
      20'((longint'(watermark_peak_cells) * 1000000)
          / longint'(MAX_CELLS_ONE_PORT));

    // Six flags, each naming a specific prohibition of Section 14.
    v_threshold_defaulted     = (n_defaulted != 4'd0);
    v_claim_without_window    = claim_valid && (claim.window_samples == 0);
    v_claim_unsupported       = (c_unsupported_claims != 16'd0);
    // A percentile is being quoted over an interval that contained an
    // overload event. Prohibition 4.
    v_percentile_over_mixture = claim_valid && (n_overload != 32'd0)
                                            && (n_steady   != 32'd0);
    // Prohibition 6, and it needs no measurement -- just a comparison.
    v_alarm_unreachable       = (alarm_threshold_ppm > metric_ceiling_ppm);
    v_awaiting_silicon        = (n_silicon_gated != 4'd0);
  end

endmodule

// ---------------------------------------------------------------------
// perf_conformance -- the sign-off gate for Section 2's twenty items.
//
// Same design rule as Chapter 26.2 Section 16: every check must be able
// to fail on a design somebody would really submit, and the gate says
// so about itself.
// ---------------------------------------------------------------------
module perf_conformance
  import perfreview_pkg::*;
(
  input  logic          clk,
  input  logic          rst_n,
  input  logic          evaluate,

  // Section 5.
  input  logic [3:0]    n_defaulted,
  input  logic [3:0]    n_silicon_gated,
  input  logic          silicon_items_documented,

  // Sections 6, 7 and 13.
  input  logic          latency_has_percentile,
  input  logic          latency_has_load,
  input  logic          latency_has_window,
  input  logic [15:0]   n_unsupported_claims,

  // Sections 8 and 9.
  input  logic          overload_regime_reported,
  input  logic [19:0]   overload_share_ppm,

  // Section 14, prohibition 6.
  input  logic [19:0]   alarm_threshold_ppm,
  input  logic [19:0]   metric_ceiling_ppm,

  // Section 10.
  input  logic [31:0]   observability_bce,
  input  logic          observability_budgeted,

  output logic          c1_thresholds_disposed,
  output logic          c2_latency_complete,
  output logic          c3_claims_supported,
  output logic          c4_regime_separated,
  output logic          c5_alarm_reachable,
  output logic          c6_observability_budgeted,
  output logic          c7_silicon_items_named,
  output logic [2:0]    n_failures,
  output logic          conformant,
  output logic          gate_can_fail
);

  logic [2:0] fails;

  always_comb begin
    // 1. No threshold sits at a value nobody chose.
    c1_thresholds_disposed = (n_defaulted == 4'd0);

    // 2. Every latency figure carries a percentile, a load and a
    //    window. Section 1's rule three, as a conjunction.
    c2_latency_complete    = latency_has_percentile &&
                             latency_has_load &&
                             latency_has_window;

    // 3. No published claim exceeds what its window supports.
    c3_claims_supported    = (n_unsupported_claims == 16'd0);

    // 4. The two regimes are reported separately, or the share is zero.
    c4_regime_separated    = overload_regime_reported ||
                             (overload_share_ppm == 20'd0);

    // 5. Every alarm threshold is inside its metric's range.
    c5_alarm_reachable     = (alarm_threshold_ppm <= metric_ceiling_ppm);

    // 6. The instruments are in the area budget rather than added
    //    during implementation. Section 10 is 0.2569 per cent.
    c6_observability_budgeted = observability_budgeted &&
                                (observability_bce != 32'd0);

    // 7. Items that cannot be closed before silicon are NAMED rather
    //    than guessed. Section 17.
    c7_silicon_items_named = (n_silicon_gated == 4'd0) ||
                             silicon_items_documented;

    fails = 3'(!c1_thresholds_disposed)    + 3'(!c2_latency_complete)
          + 3'(!c3_claims_supported)       + 3'(!c4_regime_separated)
          + 3'(!c5_alarm_reachable)        + 3'(!c6_observability_budgeted)
          + 3'(!c7_silicon_items_named);

    // A design that supplies no latency claims and no thresholds would
    // pass every check above. It is not conformant; it is empty.
    gate_can_fail = latency_has_percentile || (n_defaulted != 4'd0) ||
                    (observability_bce != 32'd0);
  end

  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      n_failures <= '0;
      conformant <= 1'b0;
    end else if (evaluate) begin
      n_failures <= fails;
      conformant <= (fails == 3'd0) && gate_can_fail;
    end
  end

endmodule

// 1. A threshold with an answer is BOUND, whatever else is true.
p_answered_is_bound: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && $past(owner_answered) && $past(has_value))
    |-> (state == TH_BOUND));

// 2. Naming an owner without exposing the parameter does not defer it.
p_named_not_exposed: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && $past(owner_named) && !$past(is_exposed) &&
   $past(has_value) && !$past(owner_answered))
    |-> (state == TH_DEFAULT && became_a_default));

// 3. Correct deferral needs both, and is exactly both.
p_deferred_needs_both: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && deferred_correctly) |-> (state == TH_DEFERRED));

// 4. No value at all is UNSET, which is honest and rare.
p_no_value_unset: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && !$past(has_value) && !$past(owner_named))
    |-> (state == TH_UNSET));

// 5. became_a_default and deferred_correctly are mutually exclusive.
p_default_xor_deferred: assert property (@(posedge clk) disable iff (!rst_n)
  out_valid |-> !(became_a_default && deferred_correctly));

// 6. A threshold needing a measurement is owned by silicon, whatever
//    its identity. Section 17.
p_measurement_is_silicon: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && $past(needs_measurement)) |-> (owner == OWN_SILICON));

// 7. The replay window is the one structural member of the seven.
p_replay_structural: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && $past(th_id) == TH_REPLAY && !$past(needs_measurement))
    |-> (owner == OWN_STRUCTURAL));

c_default_seen: cover property (@(posedge clk) out_valid && became_a_default);
c_silicon_seen: cover property (@(posedge clk) out_valid && owner == OWN_SILICON);

// 8. A write only lands if the parameter is exposed. Exposure and
//    accountability are one mechanism, not two.
p_write_needs_exposure: assert property (@(posedge clk) disable iff (!rst_n)
  (wr_en && !exposed[wr_id]) |-> ##1 (value[$past(wr_id)] ==
                                      $past(value[wr_id])));

// 9. And a landed write marks the threshold answered.
p_write_answers: assert property (@(posedge clk) disable iff (!rst_n)
  (wr_en && exposed[wr_id]) |-> ##1 answered[$past(wr_id)]);

// 10. The four counts partition the seven exactly.
p_threshold_partition: assert property (@(posedge clk) disable iff (!rst_n)
  (n_bound + n_deferred + n_defaulted + n_silicon_gated == 4'(N_THRESH)));

// 11. Disposed means no defaults, and nothing else.
p_disposed_definition: assert property (@(posedge clk) disable iff (!rst_n)
  all_thresholds_disposed == (n_defaulted == 4'd0));

// 12. A silicon-gated threshold is never counted bound until answered.
p_silicon_not_bound: assert property (@(posedge clk) disable iff (!rst_n)
  (silicon_gated[0] && !answered[0]) |-> (n_silicon_gated != 4'd0));

// 13. Reset leaves every threshold at its default, which is the state
//     the chapter exists to eliminate -- so it must be visible.
p_reset_is_default: assert property (@(posedge clk)
  $rose(rst_n) |-> ##1 (n_defaulted != 4'd0 || n_silicon_gated != 4'd0));

c_all_disposed: cover property (@(posedge clk) all_thresholds_disposed);

// 14. A claim carries all three fields or it is not a claim.
p_claim_complete: assert property (@(posedge clk) disable iff (!rst_n)
  (claim.value_ns != 32'd0) |-> (claim.window_samples != 32'd0));

// 15. supported is exactly the window comparison.
p_supported_definition: assert property (@(posedge clk) disable iff (!rst_n)
  (samples_seen != 0) |->
    (estimate_is_supported == (samples_seen >= window_required)));

// 16. The finest supportable percentile rises with the window and
//     never exceeds the requested one when unsupported.
p_best_below_want: assert property (@(posedge clk) disable iff (!rst_n)
  (!estimate_is_supported && samples_seen != 0)
    |-> (best_supported_ppm < want_ppm));

// 17. The estimate never exceeds the observed maximum.
p_estimate_le_max: assert property (@(posedge clk) disable iff (!rst_n)
  (samples_seen != 0) |-> (estimate_ns <= observed_max_ns ||
                           estimate_ns == 32'(32'd1 << BUCKET_SHIFT)));

// 18. An empty window supports nothing.
p_empty_unsupported: assert property (@(posedge clk) disable iff (!rst_n)
  (samples_seen == 32'd0) |-> !estimate_is_supported);

// 19. A finer percentile never needs a smaller window.
p_window_monotone: assert property (@(posedge clk) disable iff (!rst_n)
  (want_ppm > $past(want_ppm)) |-> (window_required >= $past(window_required)));

// 20. The claim's percentile is what was asked for, never what was
//     achievable -- the module reports the gap rather than hiding it.
p_claim_reports_request: assert property (@(posedge clk) disable iff (!rst_n)
  claim.percentile_ppm == want_ppm);

c_unsupported_claim: cover property (@(posedge clk)
  samples_seen != 0 && !estimate_is_supported);
c_supported_claim: cover property (@(posedge clk) estimate_is_supported);

// 21. One sender is never an overload. rho = 1 exactly builds no queue.
p_one_sender_no_overload: assert property (@(posedge clk) disable iff (!rst_n)
  (n_senders == 8'd1) |-> !regime_is_overload);

// 22. Fill rate is (N-1) line rates, exactly.
p_fill_rate: assert property (@(posedge clk) disable iff (!rst_n)
  regime_is_overload |-> (fill_rate_moct_s ==
                          32'((int'(n_senders) - 1) * int'(LINE_MOCT_S))));

// 23. Drain time does not depend on N. This is Section 8's fixed row.
p_drain_invariant: assert property (@(posedge clk) disable iff (!rst_n)
  (drain_time_us == 32'(CAP_OCTETS / LINE_MOCT_S)));

// 24. So the asymmetry is N-1.
p_asymmetry_is_n_minus_1: assert property (@(posedge clk) disable iff (!rst_n)
  (regime_is_overload && fill_time_us != 32'd0)
    |-> (asymmetry <= 32'(int'(n_senders))));

// 25. Fill time falls as senders rise.
p_fill_monotone: assert property (@(posedge clk) disable iff (!rst_n)
  (n_senders > $past(n_senders) && $past(n_senders) > 8'd1)
    |-> (fill_time_us <= $past(fill_time_us)));

// 26. Peak queue never exceeds the cap.
p_peak_bounded: assert property (@(posedge clk) disable iff (!rst_n)
  (peak_queue_octets <= 32'(CAP_OCTETS)));

// 27. Drops occur exactly when the offer exceeds the cap.
p_drop_definition: assert property (@(posedge clk) disable iff (!rst_n)
  buffer_overflows == ((64'(n_senders) * 64'(burst_octets_per_sender))
                       > 64'(CAP_OCTETS)));

c_incast_64: cover property (@(posedge clk) n_senders == 8'd64);
c_overflow: cover property (@(posedge clk) buffer_overflows);

// 28. A sample lands in exactly one histogram.
p_one_histogram: assert property (@(posedge clk) disable iff (!rst_n)
  (lat_valid && in_overload) |-> ##1 (n_overload == $past(n_overload) + 32'd1)
                                  && (n_steady   == $past(n_steady)));

// 29. And the other way.
p_steady_histogram: assert property (@(posedge clk) disable iff (!rst_n)
  (lat_valid && !in_overload) |-> ##1 (n_steady == $past(n_steady) + 32'd1));

// 30. The watermark never falls except on a read.
p_watermark_monotone: assert property (@(posedge clk) disable iff (!rst_n)
  (!rd_en) |-> ##1 (rd_watermark == $past(rd_watermark)));

// 31. A read clears, so consecutive reads are disjoint intervals.
p_read_clears: assert property (@(posedge clk) disable iff (!rst_n)
  rd_en |-> ##2 (rd_en && rd_queue == $past(rd_queue, 2))
                 |-> (rd_watermark <= $past(rd_watermark, 2)));

// 32. Overload share is bounded.
p_share_bounded: assert property (@(posedge clk) disable iff (!rst_n)
  (overload_share_ppm <= 20'd1000000));

// 33. The auditor's shortfall is zero exactly when supported.
p_shortfall_zero: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid) |-> (supported == (window_shortfall == 32'd0)));

// 34. And an unsupported claim increments the counter, every time.
p_unsupported_counted: assert property (@(posedge clk) disable iff (!rst_n)
  (claim_valid && claim.window_samples < need)
    |-> ##1 (n_unsupported == $past(n_unsupported) + 16'd1));

// 35. supportable_ppm is below a million, always -- no window supports
//     the hundredth percentile, which is the maximum and not a
//     percentile at all.
p_supportable_below_max: assert property (@(posedge clk) disable iff (!rst_n)
  (out_valid && claim.window_samples != 32'd0)
    |-> (supportable_ppm < 20'd1000000));

c_histogram_claim: cover property (@(posedge clk) claim_valid && from_histogram);
c_both_regimes: cover property (@(posedge clk)
  n_steady != 32'd0 && n_overload != 32'd0);