Multi-Byte I²C Writes — Timing, Throughput and Waveforms

   // A passive instrument that measures what a write burst actually costs. It exists so
   // the arithmetic in this chapter is CHECKED rather than asserted: for a write of n
   // payload bytes the closed forms are
   //
   //     bytes on the wire  = n + 1        (the address byte plus the payload)
   //     SCL pulses         = 9(n + 1)     (nine per byte, from Chapter 7.1)
   //     payload bits       = 8n           (the address byte carries none)
   //     overhead pulses    = 9(n+1) - 8n  = n + 9
   //
   // and a testbench can compare every one of them against a hand calculation.
   module i2c_write_burst_metrics #(
       parameter int CNT_W = 16
   )(
       input  logic clk,
       input  logic rst_n,
       input  logic scl_in,             // observed bus level
       input  logic frame_start,        // pulse: S or Sr
       input  logic frame_stop,         // pulse: P
       input  logic byte_done,          // pulse: a byte AND its ninth slot completed

       output logic [CNT_W-1:0] scl_pulses,       // SCL rising edges in this transfer
       output logic [CNT_W-1:0] bytes_seen,       // bytes INCLUDING the address byte
       output logic [CNT_W-1:0] payload_bits,     // 8 x (bytes_seen - 1), floored at zero
       output logic [CNT_W-1:0] overhead_pulses,  // pulses that carried no payload
       output logic             transfer_active,
       output logic             metrics_valid     // pulse: a STOP closed the transfer
   );
       logic scl_q;
       logic scl_rise;
       assign scl_rise = !scl_q && scl_in;

       // The address byte carries no payload, so it is excluded -- and the subtraction is
       // guarded, because bytes_seen is zero before the first byte completes and an
       // unguarded 8 x (0 - 1) would wrap to a very large number rather than to zero.
       assign payload_bits    = (bytes_seen == '0) ? '0
                                                   : ((bytes_seen - 1'b1) << 3);
       assign overhead_pulses = (scl_pulses >= payload_bits) ? (scl_pulses - payload_bits)
                                                            : '0;

       always_ff @(posedge clk) begin
           if (!rst_n) begin
               scl_q           <= 1'b1;    // idle bus: SCL released, therefore high
               scl_pulses      <= '0;
               bytes_seen      <= '0;
               transfer_active <= 1'b0;
               metrics_valid   <= 1'b0;
           end else begin
               metrics_valid <= 1'b0;
               scl_q         <= scl_in;

               if (frame_stop) begin
                   // The counters are deliberately NOT cleared here: a consumer reads them
                   // AFTER the transfer, so clearing on the STOP would empty them before
                   // anything could look. The next frame_start clears them instead.
                   if (transfer_active) metrics_valid <= 1'b1;
                   transfer_active <= 1'b0;
               end else if (frame_start) begin
                   // A repeated START begins a new measurement: the bytes after it belong
                   // to a new addressing, so counting them with the previous phase's
                   // totals would misreport both.
                   scl_pulses      <= '0;
                   bytes_seen      <= '0;
                   transfer_active <= 1'b1;
               end else if (transfer_active) begin
                   if (scl_rise)  scl_pulses <= scl_pulses + 1'b1;
                   if (byte_done) bytes_seen <= bytes_seen + 1'b1;
               end
           end
       end
   endmodule

   module i2c_write_burst_metrics_tb;
       localparam int CNT_W = 16;

       logic clk = 1'b0, rst_n, scl_in, frame_start, frame_stop, byte_done;
       logic [CNT_W-1:0] scl_pulses, bytes_seen, payload_bits, overhead_pulses;
       logic transfer_active, metrics_valid;

       int errors = 0;

       i2c_write_burst_metrics #(.CNT_W(CNT_W)) dut (.*);

       always #5 clk = ~clk;
       initial begin #200000; $display("FAIL: watchdog expired"); $finish; end

       // One SCL pulse. The metrics block counts rising edges, so this is the unit.
       task automatic scl_pulse();
           scl_in = 1'b0; repeat (1) @(negedge clk);
           scl_in = 1'b1; repeat (1) @(negedge clk);
           scl_in = 1'b0; repeat (1) @(negedge clk);
       endtask

       // One byte: nine SCL pulses, then the byte_done the engine of Chapter 7.1 emits.
       task automatic wire_byte();
           for (int i = 0; i < 9; i++) scl_pulse();
           byte_done = 1'b1; @(negedge clk); byte_done = 1'b0; @(negedge clk);
       endtask

       task automatic pulse_start(); frame_start = 1'b1; @(negedge clk); frame_start = 1'b0; @(negedge clk); endtask
       task automatic pulse_stop();  frame_stop  = 1'b1; @(negedge clk); frame_stop  = 1'b0; @(negedge clk); endtask

       // Drive a complete write of n payload bytes: address byte plus n data bytes.
       task automatic write_burst(input int n);
           pulse_start();
           wire_byte();                              // the address byte
           for (int b = 0; b < n; b++) wire_byte();  // the payload
           pulse_stop();
       endtask

       // The hand calculation, written as arithmetic on n and compared against the
       // hardware. Two independent routes to the same four numbers.
       task automatic check_burst(input int n);
           automatic int exp_bytes    = n + 1;
           automatic int exp_pulses   = 9 * (n + 1);
           automatic int exp_payload  = 8 * n;
           automatic int exp_overhead = n + 9;
           if (bytes_seen !== exp_bytes[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- bytes_seen %0d, expected %0d", n, bytes_seen, exp_bytes);
               errors++; end
           if (scl_pulses !== exp_pulses[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- scl_pulses %0d, expected 9(n+1) = %0d", n, scl_pulses, exp_pulses);
               errors++; end
           if (payload_bits !== exp_payload[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- payload_bits %0d, expected 8n = %0d", n, payload_bits, exp_payload);
               errors++; end
           if (overhead_pulses !== exp_overhead[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- overhead %0d, expected n+9 = %0d", n, overhead_pulses, exp_overhead);
               errors++; end
       endtask

       int snap_pulses, snap_bytes, snap_valid;
       int n_valid = 0;
       always @(posedge clk) if (rst_n && metrics_valid) n_valid++;

       initial begin
           rst_n = 1'b0; scl_in = 1'b1; frame_start = 1'b0; frame_stop = 1'b0; byte_done = 1'b0;
           repeat (3) @(negedge clk);
           if (transfer_active !== 1'b0) begin $display("FAIL: active out of reset"); errors++; end
           if (payload_bits !== '0) begin
               $display("FAIL: payload_bits = %0d before any byte -- the guarded subtraction wrapped",
                        payload_bits); errors++; end
           rst_n = 1'b1; @(negedge clk);

           // ---- the closed forms, across a range of burst lengths ----
           write_burst(1); check_burst(1);
           write_burst(2); check_burst(2);
           write_burst(4); check_burst(4);
           write_burst(8); check_burst(8);

           // ---- an ADDRESS-ONLY transfer: one byte, nine pulses, and ZERO payload.
           //      The guarded subtraction is what stops this reporting a huge number.
           write_burst(0);
           if (bytes_seen !== 16'd1) begin
               $display("FAIL: an address-only transfer saw %0d bytes", bytes_seen); errors++; end
           if (scl_pulses !== 16'd9) begin
               $display("FAIL: an address-only transfer took %0d pulses, expected 9", scl_pulses); errors++; end
           if (payload_bits !== '0) begin
               $display("FAIL: an address-only transfer reported %0d payload bits", payload_bits); errors++; end
           if (overhead_pulses !== 16'd9) begin
               $display("FAIL: overhead was %0d, expected all 9 pulses", overhead_pulses); errors++; end

           // ---- the metrics must SURVIVE the STOP, because that is when anything reads them.
           if (transfer_active !== 1'b0) begin $display("FAIL: still active after the STOP"); errors++; end
           if (bytes_seen === '0) begin
               $display("FAIL: the counters were cleared by the STOP"); errors++; end

           // ---- a repeated START starts a NEW measurement rather than accumulating.
           pulse_start();
           wire_byte(); wire_byte();          // address + one payload byte
           if (bytes_seen !== 16'd2) begin
               $display("FAIL: mid-phase bytes_seen = %0d, expected 2", bytes_seen); errors++; end
           pulse_start();                     // Sr
           if (bytes_seen !== '0) begin
               $display("FAIL: a repeated START did not restart the measurement (%0d)", bytes_seen);
               errors++; end
           wire_byte(); wire_byte(); wire_byte();
           pulse_stop();
           check_burst(2);                     // the post-Sr phase: address + 2 payload

           // ---- an IDLE BUS must not be measured. Between transfers SCL keeps moving --
           //      another master's traffic, a monitor probing, a stuck clock -- and
           //      counting any of it would corrupt the very totals a consumer reads
           //      after the STOP. The snapshot is taken rather than assuming a value,
           //      because the point is that NOTHING changes.
           snap_pulses = scl_pulses; snap_bytes = bytes_seen;
           repeat (6) scl_pulse();
           wire_byte();                       // and a byte_done with no transfer open
           if (scl_pulses !== snap_pulses || bytes_seen !== snap_bytes) begin
               $display("FAIL: idle-bus clocking was counted -- %0d/%0d, expected %0d/%0d",
                        scl_pulses, bytes_seen, snap_pulses, snap_bytes); errors++; end
           if (transfer_active !== 1'b0) begin
               $display("FAIL: clocking an idle bus opened a transfer"); errors++; end

           // ---- a STOP that closed NOTHING must not announce a measurement. A bus sees
           //      plenty of P's that end somebody else's transfer; a consumer woken by
           //      one of those would read a stale total as if it were fresh.
           snap_valid = n_valid;
           pulse_stop();
           if (n_valid !== snap_valid) begin
               $display("FAIL: a STOP that closed nothing produced metrics_valid"); errors++; end

           // ---- one metrics_valid per completed transfer: 5 bursts + 1 Sr transfer = 6.
           if (n_valid != 6) begin
               $display("FAIL: %0d metrics_valid pulses, expected 6", n_valid); errors++; end

           if (errors == 0)
               $display("PASS: 9(n+1) pulses, 8n payload bits and n+9 overhead confirmed for n = 0,1,2,4,8");
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   // A passive instrument that measures what a write burst actually costs. It exists so
   // the arithmetic in this chapter is CHECKED rather than asserted: for a write of n
   // payload bytes the closed forms are
   //
   //     bytes on the wire  = n + 1        (the address byte plus the payload)
   //     SCL pulses         = 9(n + 1)     (nine per byte, from Chapter 7.1)
   //     payload bits       = 8n           (the address byte carries none)
   //     overhead pulses    = 9(n+1) - 8n  = n + 9
   //
   // and a testbench can compare every one of them against a hand calculation.
   module i2c_write_burst_metrics #(
       parameter integer CNT_W = 16
   )(
       input  wire clk,
       input  wire rst_n,
       input  wire scl_in,             // observed bus level
       input  wire frame_start,        // pulse: S or Sr
       input  wire frame_stop,         // pulse: P
       input  wire byte_done,          // pulse: a byte AND its ninth slot completed

       output reg   [CNT_W-1:0] scl_pulses,       // SCL rising edges in this transfer
       output reg   [CNT_W-1:0] bytes_seen,       // bytes INCLUDING the address byte
       output wire  [CNT_W-1:0] payload_bits,     // 8 x (bytes_seen - 1), floored at zero
       output wire  [CNT_W-1:0] overhead_pulses,  // pulses that carried no payload
       output reg               transfer_active,
       output reg               metrics_valid     // pulse: a STOP closed the transfer
   );
       reg  scl_q;
       wire scl_rise = ~scl_q & scl_in;

       // The address byte carries no payload, so it is excluded -- and the subtraction is
       // guarded, because bytes_seen is zero before the first byte completes and an
       // unguarded 8 x (0 - 1) would wrap to a very large number rather than to zero.
       assign payload_bits    = (bytes_seen == {CNT_W{1'b0}}) ? {CNT_W{1'b0}}
                                                              : ((bytes_seen - 1'b1) << 3);
       assign overhead_pulses = (scl_pulses >= payload_bits) ? (scl_pulses - payload_bits)
                                                            : {CNT_W{1'b0}};

       always @(posedge clk) begin
           if (!rst_n) begin
               scl_q           <= 1'b1;    // idle bus: SCL released, therefore high
               scl_pulses      <= {CNT_W{1'b0}};
               bytes_seen      <= {CNT_W{1'b0}};
               transfer_active <= 1'b0;
               metrics_valid   <= 1'b0;
           end else begin
               metrics_valid <= 1'b0;
               scl_q         <= scl_in;

               if (frame_stop) begin
                   // The counters are deliberately NOT cleared here: a consumer reads them
                   // AFTER the transfer, so clearing on the STOP would empty them before
                   // anything could look. The next frame_start clears them instead.
                   if (transfer_active) metrics_valid <= 1'b1;
                   transfer_active <= 1'b0;
               end else if (frame_start) begin
                   // A repeated START begins a new measurement: the bytes after it belong
                   // to a new addressing, so counting them with the previous phase's
                   // totals would misreport both.
                   scl_pulses      <= {CNT_W{1'b0}};
                   bytes_seen      <= {CNT_W{1'b0}};
                   transfer_active <= 1'b1;
               end else if (transfer_active) begin
                   if (scl_rise)  scl_pulses <= scl_pulses + 1'b1;
                   if (byte_done) bytes_seen <= bytes_seen + 1'b1;
               end
           end
       end
   endmodule

   module i2c_write_burst_metrics_tb;
       localparam integer CNT_W = 16;

       reg clk, rst_n, scl_in, frame_start, frame_stop, byte_done;
       wire [CNT_W-1:0] scl_pulses, bytes_seen, payload_bits, overhead_pulses;
       wire transfer_active, metrics_valid;

       integer errors, n_valid, i, b;
       integer snap_pulses, snap_bytes, snap_valid;
       integer exp_bytes, exp_pulses, exp_payload, exp_overhead;

       i2c_write_burst_metrics #(.CNT_W(CNT_W)) dut (.clk(clk), .rst_n(rst_n), .scl_in(scl_in),
           .frame_start(frame_start), .frame_stop(frame_stop), .byte_done(byte_done),
           .scl_pulses(scl_pulses), .bytes_seen(bytes_seen), .payload_bits(payload_bits),
           .overhead_pulses(overhead_pulses), .transfer_active(transfer_active),
           .metrics_valid(metrics_valid));

       initial clk = 1'b0;
       always #5 clk = ~clk;
       initial begin #200000; $display("FAIL: watchdog expired"); $finish; end

       // One SCL pulse. The metrics block counts rising edges, so this is the unit.
       task scl_pulse; begin
           scl_in = 1'b0; repeat (1) @(negedge clk);
           scl_in = 1'b1; repeat (1) @(negedge clk);
           scl_in = 1'b0; repeat (1) @(negedge clk);
       end endtask

       // One byte: nine SCL pulses, then the byte_done the engine of Chapter 7.1 emits.
       task wire_byte; begin
           for (i = 0; i < 9; i = i + 1) scl_pulse();
           byte_done = 1'b1; @(negedge clk); byte_done = 1'b0; @(negedge clk);
       end endtask

       task pulse_start; begin frame_start = 1'b1; @(negedge clk); frame_start = 1'b0; @(negedge clk); end endtask
       task pulse_stop;  begin frame_stop  = 1'b1; @(negedge clk); frame_stop  = 1'b0; @(negedge clk); end endtask

       // Drive a complete write of n payload bytes: address byte plus n data bytes.
       task write_burst; input integer n; begin
           pulse_start();
           wire_byte();                              // the address byte
           for (b = 0; b < n; b = b + 1) wire_byte();  // the payload
           pulse_stop();
       end endtask

       // The hand calculation, written as arithmetic on n and compared against the
       // hardware. Two independent routes to the same four numbers.
       task check_burst; input integer n; begin
           exp_bytes    = n + 1;
           exp_pulses   = 9 * (n + 1);
           exp_payload  = 8 * n;
           exp_overhead = n + 9;
           if (bytes_seen !== exp_bytes[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- bytes_seen %0d, expected %0d", n, bytes_seen, exp_bytes);
               errors = errors + 1; end
           if (scl_pulses !== exp_pulses[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- scl_pulses %0d, expected 9(n+1) = %0d", n, scl_pulses, exp_pulses);
               errors = errors + 1; end
           if (payload_bits !== exp_payload[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- payload_bits %0d, expected 8n = %0d", n, payload_bits, exp_payload);
               errors = errors + 1; end
           if (overhead_pulses !== exp_overhead[CNT_W-1:0]) begin
               $display("FAIL: n=%0d -- overhead %0d, expected n+9 = %0d", n, overhead_pulses, exp_overhead);
               errors = errors + 1; end
       end endtask

       always @(posedge clk) if (rst_n && metrics_valid) n_valid = n_valid + 1;

       initial begin
           errors = 0; n_valid = 0;
           rst_n = 1'b0; scl_in = 1'b1; frame_start = 1'b0; frame_stop = 1'b0; byte_done = 1'b0;
           repeat (3) @(negedge clk);
           if (transfer_active !== 1'b0) begin $display("FAIL: active out of reset"); errors = errors + 1; end
           if (payload_bits !== {CNT_W{1'b0}}) begin
               $display("FAIL: payload_bits = %0d before any byte -- the guarded subtraction wrapped",
                        payload_bits); errors = errors + 1; end
           rst_n = 1'b1; @(negedge clk);

           // ---- the closed forms, across a range of burst lengths ----
           write_burst(1); check_burst(1);
           write_burst(2); check_burst(2);
           write_burst(4); check_burst(4);
           write_burst(8); check_burst(8);

           // ---- an ADDRESS-ONLY transfer: one byte, nine pulses, and ZERO payload.
           //      The guarded subtraction is what stops this reporting a huge number.
           write_burst(0);
           if (bytes_seen !== 16'd1) begin
               $display("FAIL: an address-only transfer saw %0d bytes", bytes_seen); errors = errors + 1; end
           if (scl_pulses !== 16'd9) begin
               $display("FAIL: an address-only transfer took %0d pulses, expected 9", scl_pulses); errors = errors + 1; end
           if (payload_bits !== {CNT_W{1'b0}}) begin
               $display("FAIL: an address-only transfer reported %0d payload bits", payload_bits); errors = errors + 1; end
           if (overhead_pulses !== 16'd9) begin
               $display("FAIL: overhead was %0d, expected all 9 pulses", overhead_pulses); errors = errors + 1; end

           // ---- the metrics must SURVIVE the STOP, because that is when anything reads them.
           if (transfer_active !== 1'b0) begin $display("FAIL: still active after the STOP"); errors = errors + 1; end
           if (bytes_seen === {CNT_W{1'b0}}) begin
               $display("FAIL: the counters were cleared by the STOP"); errors = errors + 1; end

           // ---- a repeated START starts a NEW measurement rather than accumulating.
           pulse_start();
           wire_byte(); wire_byte();          // address + one payload byte
           if (bytes_seen !== 16'd2) begin
               $display("FAIL: mid-phase bytes_seen = %0d, expected 2", bytes_seen); errors = errors + 1; end
           pulse_start();                     // Sr
           if (bytes_seen !== {CNT_W{1'b0}}) begin
               $display("FAIL: a repeated START did not restart the measurement (%0d)", bytes_seen);
               errors = errors + 1; end
           wire_byte(); wire_byte(); wire_byte();
           pulse_stop();
           check_burst(2);                     // the post-Sr phase: address + 2 payload

           // ---- one metrics_valid per completed transfer: 5 bursts + 1 Sr transfer = 6.
           // ---- an IDLE BUS must not be measured. Between transfers SCL keeps moving --
           //      another master's traffic, a monitor probing, a stuck clock -- and
           //      counting any of it would corrupt the very totals a consumer reads
           //      after the STOP. The snapshot is taken rather than assuming a value,
           //      because the point is that NOTHING changes.
           snap_pulses = scl_pulses; snap_bytes = bytes_seen;
           for (i = 0; i < 6; i = i + 1) scl_pulse;
           wire_byte;                         // and a byte_done with no transfer open
           if (scl_pulses !== snap_pulses[CNT_W-1:0] || bytes_seen !== snap_bytes[CNT_W-1:0]) begin
               $display("FAIL: idle-bus clocking was counted -- %0d/%0d, expected %0d/%0d",
                        scl_pulses, bytes_seen, snap_pulses, snap_bytes); errors = errors + 1; end
           if (transfer_active !== 1'b0) begin
               $display("FAIL: clocking an idle bus opened a transfer"); errors = errors + 1; end

           // ---- a STOP that closed NOTHING must not announce a measurement. A bus sees
           //      plenty of P's that end somebody else's transfer; a consumer woken by
           //      one of those would read a stale total as if it were fresh.
           snap_valid = n_valid;
           pulse_stop;
           if (n_valid !== snap_valid) begin
               $display("FAIL: a STOP that closed nothing produced metrics_valid"); errors = errors + 1; end

           if (n_valid != 6) begin
               $display("FAIL: %0d metrics_valid pulses, expected 6", n_valid); errors = errors + 1; end

           if (errors == 0)
               $display("PASS: 9(n+1) pulses, 8n payload bits and n+9 overhead confirmed for n = 0,1,2,4,8");
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   library ieee;
   use ieee.std_logic_1164.all;
   use ieee.numeric_std.all;

   -- A passive instrument that measures what a write burst actually costs. It exists so
   -- the arithmetic in this chapter is CHECKED rather than asserted: for a write of n
   -- payload bytes the closed forms are
   --
   --     bytes on the wire  = n + 1        (the address byte plus the payload)
   --     SCL pulses         = 9(n + 1)     (nine per byte, from Chapter 7.1)
   --     payload bits       = 8n           (the address byte carries none)
   --     overhead pulses    = 9(n+1) - 8n  = n + 9
   entity i2c_write_burst_metrics is
       generic (
           CNT_W : positive := 16
       );
       port (
           clk         : in std_logic;
           rst_n       : in std_logic;
           scl_in      : in std_logic;                -- observed bus level
           frame_start : in std_logic;                -- pulse: S or Sr
           frame_stop  : in std_logic;                -- pulse: P
           byte_done   : in std_logic;                -- pulse: a byte and its slot ended

           scl_pulses      : out unsigned(CNT_W - 1 downto 0);
           bytes_seen      : out unsigned(CNT_W - 1 downto 0);
           payload_bits    : out unsigned(CNT_W - 1 downto 0);
           overhead_pulses : out unsigned(CNT_W - 1 downto 0);
           transfer_active : out std_logic;
           metrics_valid   : out std_logic            -- pulse: a STOP closed the transfer
       );
   end entity;

   architecture rtl of i2c_write_burst_metrics is
       constant ZERO : unsigned(CNT_W - 1 downto 0) := (others => '0');
       signal scl_q    : std_logic := '1';    -- idle bus: SCL released, therefore high
       signal pulses   : unsigned(CNT_W - 1 downto 0) := (others => '0');
       signal nbytes   : unsigned(CNT_W - 1 downto 0) := (others => '0');
       signal active   : std_logic := '0';
       signal scl_rise : std_logic;
       signal pay      : unsigned(CNT_W - 1 downto 0);
   begin
       scl_rise <= (not scl_q) and scl_in;

       scl_pulses      <= pulses;
       bytes_seen      <= nbytes;
       transfer_active <= active;

       -- The address byte carries no payload, so it is excluded -- and the subtraction is
       -- guarded, because nbytes is zero before the first byte completes and an unguarded
       -- 8 x (0 - 1) would wrap to a very large number rather than to zero.
       pay          <= ZERO when nbytes = ZERO else shift_left(nbytes - 1, 3);
       payload_bits <= pay;
       overhead_pulses <= (pulses - pay) when pulses >= pay else ZERO;

       process (clk)
       begin
           if rising_edge(clk) then
               if rst_n = '0' then
                   scl_q         <= '1';
                   pulses        <= (others => '0');
                   nbytes        <= (others => '0');
                   active        <= '0';
                   metrics_valid <= '0';
               else
                   metrics_valid <= '0';
                   scl_q         <= scl_in;

                   if frame_stop = '1' then
                       -- The counters are deliberately NOT cleared here: a consumer reads
                       -- them AFTER the transfer. The next frame_start clears them.
                       if active = '1' then metrics_valid <= '1'; end if;
                       active <= '0';
                   elsif frame_start = '1' then
                       -- A repeated START begins a new measurement.
                       pulses <= (others => '0');
                       nbytes <= (others => '0');
                       active <= '1';
                   elsif active = '1' then
                       if scl_rise = '1'  then pulses <= pulses + 1; end if;
                       if byte_done = '1' then nbytes <= nbytes + 1; end if;
                   end if;
               end if;
           end if;
       end process;
   end architecture;

   library ieee;
   use ieee.std_logic_1164.all;
   use ieee.numeric_std.all;

   entity i2c_write_burst_metrics_tb is
   end entity;

   architecture sim of i2c_write_burst_metrics_tb is
       constant CNT_W : positive := 16;

       signal clk         : std_logic := '0';
       signal rst_n       : std_logic := '0';
       signal scl_in      : std_logic := '1';
       signal frame_start : std_logic := '0';
       signal frame_stop  : std_logic := '0';
       signal byte_done   : std_logic := '0';
       signal scl_pulses, bytes_seen, payload_bits, overhead_pulses : unsigned(CNT_W - 1 downto 0);
       signal transfer_active, metrics_valid : std_logic;

       -- Owned solely by the counting process; the stimulus snapshots it instead of
       -- clearing it, because VHDL permits one driver per signal.
       signal n_valid   : natural := 0;
       signal test_done : std_logic := '0';
   begin
       dut : entity work.i2c_write_burst_metrics
           generic map (CNT_W => CNT_W)
           port map (clk => clk, rst_n => rst_n, scl_in => scl_in, frame_start => frame_start,
                     frame_stop => frame_stop, byte_done => byte_done,
                     scl_pulses => scl_pulses, bytes_seen => bytes_seen,
                     payload_bits => payload_bits, overhead_pulses => overhead_pulses,
                     transfer_active => transfer_active, metrics_valid => metrics_valid);

       clk <= not clk after 5 ns;

       watchdog : process
       begin
           wait for 200 us;
           if test_done = '0' then
               report "watchdog expired -- the design never reached the expected state"
                   severity failure;
           end if;
           wait;
       end process;

       counter : process (clk)
       begin
           if rising_edge(clk) then
               if rst_n = '1' and metrics_valid = '1' then n_valid <= n_valid + 1; end if;
           end if;
       end process;

       stim : process
           variable errs : natural := 0;
           variable snap_pulses, snap_bytes : unsigned(CNT_W - 1 downto 0);
           variable snap_valid : natural;

           procedure waitn (n : in positive) is
           begin
               for i in 1 to n loop wait until falling_edge(clk); end loop;
           end procedure;

           procedure scl_pulse is
           begin
               scl_in <= '0'; waitn(1);
               scl_in <= '1'; waitn(1);
               scl_in <= '0'; waitn(1);
           end procedure;

           -- One byte: nine SCL pulses, then the byte_done the engine of Chapter 7.1 emits.
           procedure wire_byte is
           begin
               for i in 1 to 9 loop scl_pulse; end loop;
               byte_done <= '1'; waitn(1); byte_done <= '0'; waitn(1);
           end procedure;

           procedure pulse_start is
           begin
               frame_start <= '1'; waitn(1); frame_start <= '0'; waitn(1);
           end procedure;

           procedure pulse_stop is
           begin
               frame_stop <= '1'; waitn(1); frame_stop <= '0'; waitn(1);
           end procedure;

           procedure write_burst (n : in natural) is
           begin
               pulse_start;
               wire_byte;                                  -- the address byte
               for b in 1 to n loop wire_byte; end loop;   -- the payload
               pulse_stop;
           end procedure;

           -- The hand calculation, as arithmetic on n, compared against the hardware.
           procedure check_burst (n : in natural) is
               variable exp_bytes, exp_pulses, exp_payload, exp_overhead : natural;
           begin
               exp_bytes    := n + 1;
               exp_pulses   := 9 * (n + 1);
               exp_payload  := 8 * n;
               exp_overhead := n + 9;
               if bytes_seen /= to_unsigned(exp_bytes, CNT_W) then
                   report "n=" & integer'image(n) & ": bytes_seen wrong" severity error;
                   errs := errs + 1; end if;
               if scl_pulses /= to_unsigned(exp_pulses, CNT_W) then
                   report "n=" & integer'image(n) & ": scl_pulses is not 9(n+1)" severity error;
                   errs := errs + 1; end if;
               if payload_bits /= to_unsigned(exp_payload, CNT_W) then
                   report "n=" & integer'image(n) & ": payload_bits is not 8n" severity error;
                   errs := errs + 1; end if;
               if overhead_pulses /= to_unsigned(exp_overhead, CNT_W) then
                   report "n=" & integer'image(n) & ": overhead is not n+9" severity error;
                   errs := errs + 1; end if;
           end procedure;
       begin
           waitn(3);
           if transfer_active /= '0' then
               report "active out of reset" severity error; errs := errs + 1; end if;
           if payload_bits /= to_unsigned(0, CNT_W) then
               report "payload_bits nonzero before any byte -- the guarded subtraction wrapped"
                   severity error; errs := errs + 1; end if;
           rst_n <= '1'; waitn(1);

           -- the closed forms, across a range of burst lengths
           write_burst(1); check_burst(1);
           write_burst(2); check_burst(2);
           write_burst(4); check_burst(4);
           write_burst(8); check_burst(8);

           -- an ADDRESS-ONLY transfer: one byte, nine pulses, ZERO payload.
           write_burst(0);
           if bytes_seen /= to_unsigned(1, CNT_W) then
               report "an address-only transfer saw the wrong byte count" severity error;
               errs := errs + 1; end if;
           if scl_pulses /= to_unsigned(9, CNT_W) then
               report "an address-only transfer took the wrong number of pulses" severity error;
               errs := errs + 1; end if;
           if payload_bits /= to_unsigned(0, CNT_W) then
               report "an address-only transfer reported payload bits" severity error;
               errs := errs + 1; end if;
           if overhead_pulses /= to_unsigned(9, CNT_W) then
               report "overhead should be all nine pulses" severity error; errs := errs + 1; end if;

           -- the metrics must SURVIVE the STOP.
           if transfer_active /= '0' then
               report "still active after the STOP" severity error; errs := errs + 1; end if;
           if bytes_seen = to_unsigned(0, CNT_W) then
               report "the counters were cleared by the STOP" severity error; errs := errs + 1; end if;

           -- a repeated START starts a NEW measurement rather than accumulating.
           pulse_start;
           wire_byte; wire_byte;
           if bytes_seen /= to_unsigned(2, CNT_W) then
               report "mid-phase byte count wrong" severity error; errs := errs + 1; end if;
           pulse_start;                          -- Sr
           if bytes_seen /= to_unsigned(0, CNT_W) then
               report "a repeated START did not restart the measurement" severity error;
               errs := errs + 1; end if;
           wire_byte; wire_byte; wire_byte;
           pulse_stop;
           check_burst(2);

           -- an IDLE BUS must not be measured. Between transfers SCL keeps moving --
           -- another master's traffic, a monitor probing, a stuck clock -- and counting
           -- any of it would corrupt the very totals a consumer reads after the STOP.
           -- The snapshot is taken rather than assuming a value, because the point is
           -- that NOTHING changes.
           snap_pulses := scl_pulses; snap_bytes := bytes_seen;
           for i in 1 to 6 loop scl_pulse; end loop;
           wire_byte;                       -- and a byte_done with no transfer open
           if scl_pulses /= snap_pulses or bytes_seen /= snap_bytes then
               report "idle-bus clocking was counted" severity error; errs := errs + 1; end if;
           if transfer_active /= '0' then
               report "clocking an idle bus opened a transfer" severity error;
               errs := errs + 1; end if;

           -- a STOP that closed NOTHING must not announce a measurement. A bus sees
           -- plenty of P's that end somebody else's transfer; a consumer woken by one of
           -- those would read a stale total as if it were fresh.
           snap_valid := n_valid;
           pulse_stop;
           if n_valid /= snap_valid then
               report "a STOP that closed nothing produced metrics_valid" severity error;
               errs := errs + 1; end if;

           -- one metrics_valid per completed transfer: 5 bursts + 1 Sr transfer = 6.
           if n_valid /= 6 then
               report "wrong number of metrics_valid pulses" severity error; errs := errs + 1; end if;

           if errs = 0 then
               report "i2c_write_burst_metrics self-check complete: 9(n+1) pulses, 8n payload "
                    & "bits and n+9 overhead confirmed for n = 0,1,2,4,8" severity note;
           else
               report "i2c_write_burst_metrics self-check FAILED" severity error;
           end if;
           test_done <= '1';
           wait;
       end process;
   end architecture;

   $ iverilog -g2012 -o c1 i2c_write_burst_metrics.sv i2c_write_burst_metrics_tb.sv && ./c1
   PASS: 9(n+1) pulses, 8n payload bits and n+9 overhead confirmed for n = 0,1,2,4,8
   i2c_write_burst_metrics_tb.sv:138: $finish called at 8040 (1s)

   $ iverilog -g2005 -o c2 i2c_write_burst_metrics.v i2c_write_burst_metrics_tb.v && ./c2
   PASS: 9(n+1) pulses, 8n payload bits and n+9 overhead confirmed for n = 0,1,2,4,8
   i2c_write_burst_metrics_tb.v:144: $finish called at 8040 (1s)

   $ nvc -a i2c_write_burst_metrics.vhd i2c_write_burst_metrics_tb.vhd
   $ nvc -e i2c_write_burst_metrics_tb && nvc -r i2c_write_burst_metrics_tb --stop-time=250us
   ** Note: 8040ns+0: i2c_write_burst_metrics self-check complete: 9(n+1) pulses,
      8n payload bits and n+9 overhead confirmed for n = 0,1,2,4,8

   covergroup i2c_burst_cg with function sample(int n, bit nacked, bit stretched);
      // The bins are chosen from section 3's curve, not arbitrarily. The interesting
      // region is small n, where efficiency changes fast; past 16 the curve is flat
      // and one bin covers it. Coverage bins should follow the shape of the thing
      // being covered.
      burst_len: coverpoint n {
         bins probe     = {0};            // address-only: the scan primitive
         bins single    = {1};            // 44% efficient -- the case to find in a driver
         bins short     = {[2:4]};
         bins medium    = {[5:16]};
         bins long      = {[17:255]};
      }

      // A NACK partway through a burst is a distinct scenario from a clean one,
      // because it is where the partial-write semantics of Chapter 8.1 apply.
      nack_in_burst: coverpoint nacked;

      // Clock stretching changes the TIME without changing the pulse count, so a
      // throughput measurement that never saw a stretched burst has not been
      // validated against the dominant real-world cost.
      stretch: coverpoint stretched;

      // The cross is the point. A long burst that was never NACKed and a short one
      // that always was would fill both coverpoints while leaving the interesting
      // combinations -- a NACK late in a long burst -- entirely untried.
      len_x_nack: cross burst_len, nack_in_burst;
      len_x_stretch: cross burst_len, stretch;
   endgroup

   // The formulas of section 2, checked against what the monitor observed. Written
   // as arithmetic on n rather than as a table of expected values, so this is a
   // check on the FORMULA and not on a transcription of it.
   function void check_burst_cost(int n, int observed_pulses, int observed_payload);
      int exp_pulses   = 9 * (n + 1);
      int exp_payload  = 8 * n;
      int exp_overhead = n + 9;

      if (observed_pulses !== exp_pulses)
         `uvm_error("COST", $sformatf("n=%0d: %0d SCL pulses, expected 9(n+1)=%0d",
                    n, observed_pulses, exp_pulses))

      if (observed_payload !== exp_payload)
         `uvm_error("COST", $sformatf("n=%0d: %0d payload bits, expected 8n=%0d",
                    n, observed_payload, exp_payload))

      // The identity that ties them together. Checking it as well as the two
      // parts catches a monitor whose two counters are individually plausible
      // and mutually inconsistent -- which a check on each part alone cannot.
      if ((observed_pulses - observed_payload) !== exp_overhead)
         `uvm_error("COST", $sformatf("n=%0d: overhead %0d, expected n+9=%0d",
                    n, observed_pulses - observed_payload, exp_overhead))
   endfunction