Performance Checklist — Closing a Number You Declared Earlier

A performance gate is not a benchmark. Benchmarks produce a number; a gate settles whether a declared target was met, and if not, which term of the derivation was wrong.

That distinction decides everything about how the review runs. A gate with no declared target degenerates into an argument about whether the number is good, which has no resolution. A gate with a declared target and a written derivation is arithmetic, and arithmetic ends.

1. What This Gate Owns — and What It Must Not Steal

It owns closure of declared performance contracts. Nothing else.

Module 22 owns the measurements. 27.4 owns the isolation method. This gate owns neither — it owns the decision, and it consumes both as evidence.

What it must not steal. It must not re-derive throughput definitions, re-explain credits, or re-teach bottleneck isolation. If a reviewer needs those explained during the gate, the gate is being run too early.

And what it must not become. A performance gate that turns into a tuning session has failed. Tuning happens before the gate; the gate records whether the target was met and what was traded.

2. Disposition Semantics

The same three verdicts the architecture gate uses, with performance-specific evidence requirements.

Three readings, and the third is specific to performance.

"Met the target" requires the workload to be named. A result measured under a workload nobody declared is not evidence about the declared target. §5 is the workload contract.

A conditional pass must state what was traded. "Throughput 14 of 16 GB/s; accepted because the deficit appears only at 64-byte payloads which this product does not generate; owner: systems" is a conditional pass. "Close enough" is not.

And "the target was missed and we do not know why" is always a FAIL, even if the shortfall is small. A performance gate's product is causal understanding, not a number — an unexplained 5% shortfall is an unexplained mechanism, and unexplained mechanisms do not stay 5%.

3. The Derivation This Gate Closes

Every declared throughput target implies an outstanding requirement, and the implication is one line.

outstanding_bytes ≥ target_rate × round_trip_time
tags              = outstanding_bytes ÷ bytes_per_request

Define the terms, because each is a place the gate can fail:

Worked example, DERIVED:

16 GB/s × 1 µs = 16,000 bytes in flight
16,000 ÷ 256 B = 62.5 → 64 tags

Three things this equation does not say, and a gate that forgets them produces a confident wrong pass:

It does not say the requester will achieve the rate. It says the rate is impossible below that many tags. The bound is necessary, not sufficient — 27.4 §14 measured six causes of low throughput and only two of them are in this formula.

It does not cover posted writes. A device whose traffic is predominantly Memory Writes consumes credit rather than tags (12.2), and its limit is a credit-pool question (22.3) rather than a tag question.

And it assumes the round trip is stable. §12 measured what happens when it is not.

4. Why the Gate Demands the Derivation, Not the Number

§12 perturbed one term at a time, and the result is the argument for this section:

Two of these happen without anyone deciding to.

MPS is negotiated at enumeration and a platform may settle on a smaller value than the device supports (22.4). The device is unchanged; its tag requirement has doubled.

And round trip grows when topology changes — a switch added between the sizing exercise and the shipping product (21.1). Again the device is unchanged.

A recorded number cannot detect either. A recorded derivation can, because the terms are named and someone can substitute the deployed values. That is the entire reason this gate asks for rate × latency ÷ payload and refuses 64.

The checklist question that follows is §13's item 4, and it is the highest-value question in the chapter: what are the deployed values of the three terms, and does the derivation still hold at them?

5. The Workload Contract

A measurement without a declared workload settles nothing, because the reviewer and the implementer can each pick a workload that supports their position.

Four things must be pinned before any number is discussed:

The fourth is the one most often skipped and it invalidates results silently. 26.5 §17's model needed a drain phase before its numbers meant anything, and 28.3 §12 measured a system whose mean latency was a property of the observation window rather than of the design. A measurement taken before steady state describes the measurement.

The gate's question is not "is this fast". It is: "is this the declared workload, and is the system in steady state?" Only then does the number mean anything.

6. Efficiency Is Not One Number

"Efficiency" is used for at least four different ratios, and a gate that does not say which one is being reported will accept a number that answers a different question.

The fourth is the one that matters at a gate and the one least often reported. 26.4 §14 measured a NIC moving 96 bytes of PCIe traffic per 64-byte frame — descriptor and status overhead the payload figure does not contain. A design that met its "throughput" target while moving 1.5× the payload has met a number that does not describe what the system needed.

The gate question is §13 item 9: which ratio is this, what is in the numerator, and what is in the denominator?

7. Reading a Shortfall

When the target is missed, the gate's job is to name the term. 27.4 §3 owns the method; this section is the gate's use of it.

The first read is always outstanding occupancy, because it splits the space in one number:

27.4 §14 measured two causes producing identical throughput — 12% of baseline — separated only by occupancy: 31.9 versus 4.0. That single number is the most useful evidence a performance gate can require, and §13 item 6 requires it.

And one warning the gate must carry, because it produces confident wrong conclusions: 27.4 §15 measured 239,580 credit stalls with throughput at 99% of baseline. A nonzero credit-stall counter is not evidence that credits are the bottleneck — it is evidence only when occupancy is simultaneously below the pool size.

8. Headroom Is a Claim, Not a Number

"We have 30% headroom" is not reviewable. Headroom against what workload, at what payload distribution, with what concurrency?

A reviewable headroom claim has three parts:

1. the measured operating point, with its workload
2. the limit, and which term produces it
3. what changes first as load increases

The third is the one that makes it useful. A design at 70% of a tag-limited ceiling degrades gracefully as load rises; one at 70% of a buffer-limited ceiling may fall off a cliff when the buffer saturates, because a full buffer stops absorbing bursts entirely (26.4 §15 measured occupancy pinning at capacity and the drop rate becoming simply the difference between arrival and drain).

The gate question: what is the first thing to saturate, and is the degradation gradual or abrupt?

9. RTL — Making the Claim Measurable

Block 1 — the attribution counters. The minimum set that makes §7's split possible.

// The gate's evidence, generated by the design rather than inferred later.
// Each stall reason is SEPARATE because 27.4 §14 measured six causes of one
// symptom, and merging the counters destroys exactly the distinction the
// gate needs.
module perf_evidence #(
  parameter int unsigned NTAG = 64
)(
  input  logic clk,
  input  logic rst_n,
  // transfer events
  input  logic                                  req_issued,
  input  logic [15:0]                           req_bytes,
  input  logic                                  cpl_retired,
  input  logic [15:0]                           cpl_bytes,
  // the outstanding pool, observed rather than owned here
  input  logic [$clog2(NTAG+1)-1:0]             occupancy,
  // mutually exclusive stall reasons, one-hot by construction upstream
  input  logic                                  stall_no_tag,
  input  logic                                  stall_no_credit,
  input  logic                                  stall_no_work,
  input  logic                                  stall_host,
  input  logic                                  clear,
  output logic [63:0]                           bytes_issued, bytes_retired,
  output logic [31:0]                           c_no_tag, c_no_credit, c_no_work, c_host,
  output logic [31:0]                           occ_accum,      // for a mean
  output logic [31:0]                           occ_samples,
  output logic [$clog2(NTAG+1)-1:0]             occ_max,
  output logic                                  stall_overlap   // a reporting error
);
 
  // If two stall reasons assert together the attribution is ambiguous, and a
  // gate reading those counters would draw a wrong conclusion. Report it
  // rather than silently priority-encoding (mutation 7).
  assign stall_overlap = ($countones({stall_no_tag, stall_no_credit,
                                      stall_no_work, stall_host}) > 1);
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n || clear) begin
      bytes_issued <= '0; bytes_retired <= '0;
      c_no_tag <= '0; c_no_credit <= '0; c_no_work <= '0; c_host <= '0;
      occ_accum <= '0; occ_samples <= '0; occ_max <= '0;
    end else begin
      // Counted on the TRANSFER, never on valid alone. A counter incremented
      // on valid overstates throughput exactly when the sink is stalling,
      // which is the condition the gate is investigating (mutation 1).
      if (req_issued  && bytes_issued  != '1) bytes_issued  <= bytes_issued  + 64'(req_bytes);
      if (cpl_retired && bytes_retired != '1) bytes_retired <= bytes_retired + 64'(cpl_bytes);
 
      if (stall_no_tag    && c_no_tag    != '1) c_no_tag    <= c_no_tag + 1'b1;
      if (stall_no_credit && c_no_credit != '1) c_no_credit <= c_no_credit + 1'b1;
      if (stall_no_work   && c_no_work   != '1) c_no_work   <= c_no_work + 1'b1;
      if (stall_host      && c_host      != '1) c_host      <= c_host + 1'b1;
 
      // Mean occupancy needs an accumulator and a sample count, not a
      // running average — a running average cannot be reset-consistent and
      // cannot be re-based over a window the reviewer chooses.
      if (occ_accum   != '1) occ_accum   <= occ_accum + 32'(occupancy);
      if (occ_samples != '1) occ_samples <= occ_samples + 1'b1;
      if (occupancy > occ_max) occ_max <= occupancy;
    end
  end
 
endmodule

Block 2 — the steady-state detector. §5's fourth requirement, made observable rather than assumed.

// A measurement taken before steady state describes the measurement window.
// This block reports whether occupancy has stopped trending, which is the
// cheapest available proxy for "the system has settled".
module steady_state_gate #(
  parameter int unsigned NTAG   = 64,
  parameter int unsigned WIN    = 32'd65536,   // IMPLEMENTATION POLICY
  parameter int unsigned TOLER  = 2            // occupancy units
)(
  input  logic clk,
  input  logic rst_n,
  input  logic [$clog2(NTAG+1)-1:0] occupancy,
  output logic                      steady,
  output logic [$clog2(NTAG+1)-1:0] win_mean_prev, win_mean_cur
);
 
  logic [31:0] cnt, accum;
  logic        have_prev;
 
  always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n) begin
      cnt <= '0; accum <= '0; have_prev <= 1'b0;
      win_mean_prev <= '0; win_mean_cur <= '0; steady <= 1'b0;
    end else begin
      accum <= accum + 32'(occupancy);
      cnt   <= cnt + 32'd1;
      if (cnt == WIN-1) begin
        win_mean_prev <= win_mean_cur;
        win_mean_cur  <= ($clog2(NTAG+1))'(accum / WIN);
        // Steady means two consecutive windows agree within a tolerance.
        // One window proves nothing: a system filling monotonically has a
        // perfectly stable mean WITHIN any single window (26.5 §17's drain
        // requirement, expressed in hardware).
        steady    <= have_prev &&
                     (((win_mean_cur > win_mean_prev) ?
                       (win_mean_cur - win_mean_prev) :
                       (win_mean_prev - win_mean_cur)) <= TOLER);
        have_prev <= 1'b1;
        accum     <= '0;
        cnt       <= '0;
      end
    end
  end
 
endmodule

Block 3 — the derivation checker. §4's requirement, evaluated against deployed values rather than design-time ones.

// COMPILE-TIME + SYNTHESIZABLE. The tag requirement is recomputed from the
// values actually in force — negotiated payload and observed round trip —
// rather than from the numbers used when the design was sized (§4).
module tag_sizing_check #(
  parameter int unsigned NTAG_IMPL = 64          // what the RTL provides
)(
  input  logic clk,
  input  logic rst_n,
  input  logic [15:0] negotiated_payload_bytes,  // from enumeration, not capability
  input  logic [31:0] observed_rtt_ns,           // measured, not declared
  input  logic [31:0] target_rate_mbps,          // the DECLARED target
  output logic [31:0] required_tags,
  output logic        undersized,
  output logic        payload_is_zero
);
 
  logic [63:0] bytes_in_flight;
 
  always_comb begin
    // Guard the divide. A negotiated payload of zero is impossible in a
    // working link and catastrophic in a divider, and treating it as "use
    // the capability instead" would silently restore the design-time
    // assumption this block exists to question (mutation 12).
    payload_is_zero = (negotiated_payload_bytes == 16'd0);
 
    // rate[MB/s] * rtt[ns] / 1000 = bytes in flight
    bytes_in_flight = (64'(target_rate_mbps) * 64'(observed_rtt_ns)) / 64'd1000;
 
    required_tags = payload_is_zero ? 32'hFFFF_FFFF
                  : 32'((bytes_in_flight + 64'(negotiated_payload_bytes) - 64'd1)
                        / 64'(negotiated_payload_bytes));   // ceiling
 
    undersized = !payload_is_zero && (required_tags > NTAG_IMPL);
  end
 
endmodule

10. Same-Cycle Audit

11. Invariants

// P1 — counters advance on TRANSFERS, never on valid alone. A counter
// incremented on valid overstates throughput exactly when the sink stalls,
// which is the condition the gate is investigating.
// Catches: mutation 1. Assumption: req_issued is a qualified transfer.
property p1_count_on_transfer;
  @(posedge clk) disable iff (!rst_n)
    (bytes_issued != $past(bytes_issued)) |-> $past(req_issued);
endproperty
 
// P2 — issue and retire are independent; both may advance in one cycle.
// Catches the if/else of §10 audit A, whose symptom is a divergent
// in-flight estimate rather than a wrong total.
property p2_issue_retire_independent;
  @(posedge clk) disable iff (!rst_n)
    (req_issued && cpl_retired) |=>
      ((bytes_issued  == $past(bytes_issued)  + $past(req_bytes)) &&
       (bytes_retired == $past(bytes_retired) + $past(cpl_bytes)));
endproperty
 
// P3 — stall reasons are mutually exclusive. If they are not, the
// attribution the gate depends on is ambiguous and the overlap must be
// reported rather than resolved by priority.
property p3_stall_reasons_exclusive;
  @(posedge clk) disable iff (!rst_n)
    $onehot0({stall_no_tag, stall_no_credit, stall_no_work, stall_host});
endproperty
 
// P4 — a stall and a transfer never coincide. Their coincidence means the
// stall signal is generated from stale state (§10 audit B).
property p4_no_stall_during_transfer;
  @(posedge clk) disable iff (!rst_n)
    req_issued |-> !(stall_no_tag || stall_no_credit);
endproperty
 
// P5 — the counters are non-functional. A performance counter that gates
// behaviour has stopped being an instrument, and the gate would then be
// measuring its own instrumentation.
property p5_counters_nonfunctional;
  @(posedge clk) disable iff (!rst_n)
    $changed(c_no_tag) |-> $stable(req_issued_next_qualifier);
endproperty
 
// P6 — occupancy never exceeds the pool. Catches the drifting-counter bug
// 27.4 §17 measured, whose symptom here is a mean occupancy above NTAG —
// an impossible reading that invalidates every conclusion drawn from it.
property p6_occupancy_bounded;
  @(posedge clk) disable iff (!rst_n) (occupancy <= NTAG);
endproperty
 
// P7 — steady requires TWO agreeing windows. One window is stable for a
// system filling monotonically, which is exactly the case §5 warns about.
property p7_steady_needs_two_windows;
  @(posedge clk) disable iff (!rst_n) steady |-> have_prev;
endproperty
 
// P8 — the tag requirement is computed from the NEGOTIATED payload. Falling
// back to the capability restores the design-time assumption the block
// exists to question.
property p8_sizing_uses_negotiated;
  @(posedge clk) disable iff (!rst_n)
    !payload_is_zero |->
      (required_tags == ((bytes_in_flight + negotiated_payload_bytes - 1)
                         / negotiated_payload_bytes));
endproperty

12. Measured — The Derivation's Sensitivity

Sensitivity, relative to a design sized at 64 tags:

Three readings.

Payload and round trip are equally powerful and pull in the same direction. Halving one or doubling the other both double the requirement.

Two of the perturbations require no design change at all. MPS is negotiated (22.4); topology is a deployment decision. The RTL is identical and the sizing is wrong.

And the ceiling function matters at these magnitudes. 62.5 rounds to 64 with 2.4% margin; 93.8 rounds to 96, which a 64-tag design misses by 50%. A gate that accepts "we have 64 tags, the requirement was 62.5" has accepted a design with no margin against either term moving.

13. The Performance Checklist — 24 Questions

Workload (§5)

1. What is the declared workload — transfer size distribution, read/write mix, concurrency? (evidence: the declaration)
2. Was the measurement taken under that workload? (evidence: the run configuration)
3. Was the system in steady state? (evidence: two agreeing windows, §9 Block 2)

Derivation (§3, §4)

4. What are the deployed values of rate, round trip and negotiated payload? (evidence: enumeration readback and a measured RTT)
5. Does the derivation still hold at those values? (evidence: the recomputation)
6. What is the mean and maximum outstanding occupancy? (evidence: the counters)
7. Is the tag pool sized with margin against a payload halving? (evidence: the sensitivity, §12)
8. For write-dominated traffic, what is the credit-pool derivation? (evidence: the equivalent arithmetic)

Efficiency (§6)

9. Which efficiency ratio is being reported — numerator and denominator? (evidence: the definition)
10. What is the useful-work ratio, including descriptor and status traffic? (evidence: byte counters at both levels)
11. Does the reported rate exclude encoding overhead and retries? (evidence: the measurement basis)

Attribution (§7)

12. When the target is missed, which stall reason dominates? (evidence: the separate counters)
13. Is occupancy pinned or starving? (evidence: the occupancy statistics)
14. If credit stalls are nonzero, is occupancy simultaneously below the pool? (evidence: both counters together)
15. Is the stall_overlap count zero? (evidence: the instrument's own health, §9 Block 1)

Headroom (§8)

16. What is the measured operating point as a fraction of the limit? (evidence: both numbers)
17. Which term produces the limit? (evidence: the attribution)
18. What saturates first as load rises, and is the degradation gradual or abrupt? (evidence: a load sweep)

Instrumentation

19. Do the counters advance on transfers rather than on valid? (evidence: P1)
20. Are the stall reasons mutually exclusive? (evidence: P3)
21. Do any counters feed a functional path? (evidence: P5 — the answer must be no)
22. Can the counters be cleared and re-based over a window the reviewer chooses? (evidence: the clear path)

Closure

23. For every conditional pass, what was traded and who owns it? (evidence: the written trade)
24. If the target was missed, is the cause named? (evidence: §7's attribution — an unnamed cause is a FAIL, §2)

14. Misconceptions

"Performance closure means running a benchmark." Why it sounds plausible: a benchmark produces the number the gate is about. What really happens: a gate settles a declared contract (§1). A number with no declared target and no named workload cannot be passed or failed — it can only be argued about. What it causes: review meetings that end without a disposition, and a performance question that reappears at integration.

"We have 64 tags, the requirement was 62.5, so we pass." Why it sounds plausible: 64 ≥ 62.5. What really happens: the margin is 2.4% against two terms that move without a design change (§12). A negotiated MPS halving takes the requirement to 125. What it causes: a design that passes the gate and misses the target in a platform nobody re-derived for.

"Credit stalls are nonzero, so credits are the bottleneck." Why it sounds plausible: the counter is counting the thing that stopped the request. What really happens: 27.4 §15 measured 239,580 credit stalls at 99% of baseline throughput — the engine was tag-limited anyway. What it causes: a credit-pool increase that changes nothing, and a gate that records a fix which did not fix anything.

"Throughput is the number that matters." Why it sounds plausible: it is the declared target. What really happens: the useful-work ratio can be far worse (§6). 26.4 §14 measured 1.50× PCIe bytes per payload byte at small frames. What it causes: a link sized from payload throughput that saturates in deployment.

"We measured for long enough." Why it sounds plausible: long runs feel more trustworthy than short ones. What really happens: duration is not steadiness. A monotonically filling system has a perfectly stable mean within any single window (§9 Block 2), and 28.3 §12 measured a mean latency that was a property of the observation window. What it causes: a number that changes when someone runs it longer, and a gate that has to be re-run.

"More outstanding tags is always better." Why it sounds plausible: the derivation says a shortfall means too few. What really happens: the bound is necessary, not sufficient (§3). Beyond the requirement, additional tags add queueing latency and buy nothing — 28.1 §12 measured credit pools above the bandwidth-delay product delivering 99% either way. What it causes: latency-sensitive traffic degraded to raise a throughput number that was already at its limit.

15. Understanding Check

Q1. A design was sized at 64 tags from a 16 GB/s, 1 µs, 256-byte derivation. It ships into a platform that negotiates a 128-byte MPS. What is the new requirement, what changed in the RTL, and what should the gate have asked?

The requirement doubles to 125 tags; nothing in the RTL changed (§4, §12). Halving the payload halves the bytes each outstanding request carries, so twice as many are needed to keep the same bytes in flight. The gate should have asked question 4 — what are the deployed values of the three terms — rather than accepting the design-time derivation. This is exactly why the checklist demands rate × latency ÷ payload and refuses 64: a recorded number cannot be re-evaluated when a term moves, and MPS is negotiated at enumeration rather than chosen by the device.

Q2. Throughput is 60% of target. Occupancy is 4.0 against a 64-tag pool. Name the hypothesis this eliminates and the one it supports.

It eliminates the tag pool and supports a starving requester (§7). Occupancy far below the pool means the requester is not filling it, so adding tags cannot help — the pool is not the constraint. 27.4 §14 measured this exact signature separating two causes that produced identical throughput: a size-limited design ran at occupancy 31.9 and a depth-limited one at 4.0. The next questions are upstream: is software submitting work, is descriptor supply adequate, and is a resource blocking issue — checklist items 12 and 13.

Q3. A reviewer reports 239,580 credit stalls and proposes doubling the credit pool. What do you require before agreeing?

The occupancy reading, taken over the same window (§7, checklist item 14). 27.4 §15 measured 239,580 credit stalls with throughput at 99% of baseline — a design that was tag-limited regardless, so the credit stalls were real events with no throughput consequence. A credit stall is evidence only when occupancy is simultaneously below the pool size. If occupancy is pinned, the engine had no spare tags to use the credits with, and doubling the pool changes nothing.

Q4. Why does §9's steady-state detector require two agreeing windows rather than one stable window?

Because a monotonically filling system has a stable mean within any single window (§5, §9 Block 2, P7). A queue that is still growing produces a perfectly consistent average over any interval you measure — the average simply keeps rising from window to window. One window cannot distinguish "settled" from "settling"; two consecutive windows agreeing within a tolerance can. 28.3 §12 measured a system whose mean latency was 122,473 against a 128-step service interval, a ratio of nearly a thousand, purely because the queue never drained — the number described the observation window.

Q5. A gate is asked to accept "throughput met target, 30% headroom." What three things make that claim reviewable, and which one matters most?

The operating point with its workload, the limit and which term produces it, and what saturates first as load rises (§8). The third matters most, because it decides whether the headroom is real. A design at 70% of a tag-limited ceiling degrades gradually; one at 70% of a buffer-limited ceiling can fall off a cliff, since a saturated buffer stops absorbing bursts entirely — 26.4 §15 measured occupancy pinning at capacity, after which the drop rate is simply arrival minus drain. "30% headroom" without the failure mode is a number, not a margin.

16. What Comes Next

This gate closed a number. The next asks what to do when the number is not the problem.

A performance gate assumes the system works and asks whether it works fast enough. When it does not work at all — no traffic, wrong data, a link that will not stay up — the question changes from which term of the derivation broke to which check answers the most, soonest.

That ordering is not obvious, and the next gate measures it: 30.6 compares check orders and finds that the instinct to reach for a protocol analyzer first costs more than twice the mean effort of the cheapest-first order — and still leaves four of seven fault classes unresolved, because the analyzer sees the Link and most faults do not live there.