Repeated START — Holding the Bus Between Phases

   state          what the controller does              why it must be here
   -----          ------------------------              -------------------
   1. SCL low     release SDA (SDA goes high)           SDA must be high to fall
                                                        later; doing this while
                                                        SCL is HIGH would be a STOP

   2. SCL low     ensure SDA has settled high           the next step samples it

   3. release SCL (SCL goes high)                       the framing edge needs a
                                                        HIGH phase to occur in

   4. wait the setup interval                           this is the tSU;STA margin
                                                        of Chapter 5.5

   5. drive SDA low  <-- THIS EDGE IS THE Sr            SDA falls while SCL is high

   6. wait the hold interval                            tHD;STA, same as for a
                                                        first START

   7. drive SCL low                                     the first clock pulse of
                                                        the new phase

   Steps 1 and 5 are BOTH SDA transitions, in opposite directions, and only one
   of them is framing. The difference is step 3: what SCL was doing. Move step 1
   after step 3 and the controller emits a STOP -- ending the transfer it was
   trying to continue, and then emitting a START into a bus-free interval it
   never waited out.

   Question 1:  "did an SDA fall occur while SCL was high?"
                                  |
                  depends only on:  scl[n-1], scl[n], sda[n-1], sda[n]
                                  |
                  -> answerable from two samples. NO state required.
                     This is Chapter 5.2's detector, and it is complete.

   Question 2:  "was that fall an S or an Sr?"
                                  |
                  depends on:  everything above, PLUS
                               "was a transfer already in progress?"
                                  |
                  -> that last term is a FUNCTION OF HISTORY, not of the
                     current samples. It is set by an earlier framing event
                     and cleared by a later one.
                  -> requires ONE BIT of state. And one bit is enough.

   The minimum state for classification is therefore a single flag:

       set   by any framing fall  (S or Sr -- both make the bus busy)
       clear by a framing rise    (P -- the bus is released)

   Read BEFORE it is updated, that flag is exactly the discriminator:
       flag == 0 at the edge  ->  S
       flag == 1 at the edge  ->  Sr

   module i2c_framing_classifier (
       input  logic clk,
       input  logic rst_n,
       input  logic scl_in,                  // observed bus level, not drive intent
       input  logic sda_in,                  // observed bus level, not drive intent
       output logic start_pulse,             // S  -- first START of a transfer
       output logic repeated_start_pulse,    // Sr -- START while the bus was busy
       output logic stop_pulse,              // P
       output logic bus_busy
   );
       logic scl_q, sda_q;
       logic saw_fall, saw_rise;

       // The two framing edges. Both require SCL HIGH on BOTH samples, so an SDA
       // change coincident with an SCL edge is not claimed as framing.
       always_comb begin
           saw_fall = scl_q && scl_in &&  sda_q && !sda_in;
           saw_rise = scl_q && scl_in && !sda_q &&  sda_in;
       end

       always_ff @(posedge clk) begin
           if (!rst_n) begin
               scl_q <= 1'b1; sda_q <= 1'b1;
               start_pulse          <= 1'b0;
               repeated_start_pulse <= 1'b0;
               stop_pulse           <= 1'b0;
               bus_busy             <= 1'b0;
           end else begin
               // Default every event output low: these are pulses, not levels.
               start_pulse          <= 1'b0;
               repeated_start_pulse <= 1'b0;
               stop_pulse           <= 1'b0;

               // S and Sr are the SAME EDGE. Nothing in the waveform distinguishes
               // them -- only whether a transfer was already in progress does. That
               // is why a classifier needs state and an edge detector does not.
               if (saw_fall) begin
                   if (bus_busy) repeated_start_pulse <= 1'b1;
                   else          start_pulse          <= 1'b1;
                   bus_busy <= 1'b1;
               end else if (saw_rise) begin
                   // UM10204 defines STOP by the edge itself, so the edge is
                   // classified as STOP whatever the tracked state was.
                   stop_pulse <= 1'b1;
                   bus_busy   <= 1'b0;
               end

               scl_q <= scl_in;
               sda_q <= sda_in;
           end
       end
   endmodule

   module i2c_framing_classifier_tb;
       logic clk = 1'b0, rst_n, scl_in, sda_in;
       logic s_p, sr_p, p_p, busy;
       int   errors = 0;
       int   n_s = 0, n_sr = 0, n_p = 0;

       i2c_framing_classifier dut (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
           .start_pulse(s_p), .repeated_start_pulse(sr_p), .stop_pulse(p_p), .bus_busy(busy));

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

       always @(posedge clk) if (rst_n) begin
           if (s_p)  n_s++;
           if (sr_p) n_sr++;
           if (p_p)  n_p++;
           // The three classifications are mutually exclusive by construction; an
           // edge that produced two of them would be a classifier that cannot
           // decide, which is worse than one that is wrong.
           if ((s_p + sr_p + p_p) > 1) begin
               $display("FAIL: %0t -- more than one framing class asserted at once", $time);
               errors++;
           end
       end

       task automatic expect_counts(input int es, input int esr, input int ep, input int step);
           if (n_s !== es || n_sr !== esr || n_p !== ep) begin
               $display("FAIL: step %0d -- S/Sr/P = %0d/%0d/%0d, expected %0d/%0d/%0d",
                        step, n_s, n_sr, n_p, es, esr, ep);
               errors++;
           end
       endtask

       // SDA falls while SCL is HIGH. From idle this is S; while busy it is Sr.
       task automatic sda_fall_while_high();
           sda_in = 1'b1; scl_in = 1'b1;   repeat (2) @(negedge clk);
           sda_in = 1'b0;                  repeat (2) @(negedge clk);
           scl_in = 1'b0;                  repeat (2) @(negedge clk);
       endtask

       // Bring SDA back HIGH during the LOW phase, so the next rise-while-high is
       // available. This is ordinary data movement and must classify as nothing.
       task automatic release_sda_during_low();
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
           sda_in = 1'b1;                  repeat (2) @(negedge clk);
       endtask

       task automatic sda_rise_while_high();
           scl_in = 1'b0; sda_in = 1'b0;   repeat (2) @(negedge clk);
           scl_in = 1'b1;                  repeat (2) @(negedge clk);
           sda_in = 1'b1;                  repeat (2) @(negedge clk);
       endtask

       task automatic do_bit(input logic v);
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
           sda_in = v;                     repeat (1) @(negedge clk);
           scl_in = 1'b1;                  repeat (2) @(negedge clk);
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
       endtask

       // BOUNDARY: SDA moves in the same interval SCL rises -- not framing.
       task automatic coincident_fall();
           scl_in = 1'b0; sda_in = 1'b1;   repeat (2) @(negedge clk);
           sda_in = 1'b0; scl_in = 1'b1;   repeat (2) @(negedge clk);
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
       endtask

       initial begin
           rst_n = 1'b0; scl_in = 1'b1; sda_in = 1'b1;
           repeat (2) @(negedge clk);
           if (busy !== 1'b0) begin $display("FAIL: bus_busy set after reset"); errors++; end
           rst_n = 1'b1; @(negedge clk);

           // 1 -- ordinary data must classify as nothing at all.
           do_bit(1'b0); do_bit(1'b1);
           expect_counts(0, 0, 0, 1);

           // 2 -- a fall while high from an IDLE bus is S, not Sr.
           sda_fall_while_high();
           expect_counts(1, 0, 0, 2);
           if (busy !== 1'b1) begin $display("FAIL: S did not set bus_busy"); errors++; end

           // 3 -- data, then the SAME EDGE again while busy, is Sr, not S.
           do_bit(1'b1);
           release_sda_during_low();
           sda_fall_while_high();
           expect_counts(1, 1, 0, 3);
           if (busy !== 1'b1) begin $display("FAIL: Sr cleared bus_busy"); errors++; end

           // 4 -- a second Sr also classifies as Sr: repeatable, not a one-shot.
           do_bit(1'b0);
           release_sda_during_low();
           sda_fall_while_high();
           expect_counts(1, 2, 0, 4);

           // 5 -- a rise while high is P, and releases the bus.
           sda_rise_while_high();
           expect_counts(1, 2, 1, 5);
           if (busy !== 1'b0) begin $display("FAIL: P did not clear bus_busy"); errors++; end

           // 6 -- THE KEY REGRESSION: after a P, the next fall must be S again.
           //      A classifier whose busy flag is sticky reports Sr here forever.
           sda_fall_while_high();
           expect_counts(2, 2, 1, 6);

           // 7 -- boundary case stays unclassified.
           coincident_fall();
           expect_counts(2, 2, 1, 7);

           if (errors == 0)
               $display("PASS: S=%0d Sr=%0d P=%0d -- same edge classified by bus state, exclusively",
                        n_s, n_sr, n_p);
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   module i2c_framing_classifier (
       input  wire clk,
       input  wire rst_n,
       input  wire scl_in,                  // observed bus level, not drive intent
       input  wire sda_in,                  // observed bus level, not drive intent
       output reg  start_pulse,             // S  -- first START of a transfer
       output reg  repeated_start_pulse,    // Sr -- START while the bus was busy
       output reg  stop_pulse,              // P
       output reg  bus_busy
   );
       reg  scl_q, sda_q;
       wire saw_fall, saw_rise;

       // Both framing edges require SCL HIGH on BOTH samples.
       assign saw_fall = scl_q & scl_in &  sda_q & ~sda_in;
       assign saw_rise = scl_q & scl_in & ~sda_q &  sda_in;

       always @(posedge clk) begin
           if (!rst_n) begin
               scl_q <= 1'b1; sda_q <= 1'b1;
               start_pulse          <= 1'b0;
               repeated_start_pulse <= 1'b0;
               stop_pulse           <= 1'b0;
               bus_busy             <= 1'b0;
           end else begin
               // Pulses, not levels: default low every cycle.
               start_pulse          <= 1'b0;
               repeated_start_pulse <= 1'b0;
               stop_pulse           <= 1'b0;

               // S and Sr are the SAME EDGE; only the tracked state separates them.
               if (saw_fall) begin
                   if (bus_busy) repeated_start_pulse <= 1'b1;
                   else          start_pulse          <= 1'b1;
                   bus_busy <= 1'b1;
               end else if (saw_rise) begin
                   stop_pulse <= 1'b1;
                   bus_busy   <= 1'b0;
               end

               scl_q <= scl_in;
               sda_q <= sda_in;
           end
       end
   endmodule

   module i2c_framing_classifier_tb;
       reg  clk, rst_n, scl_in, sda_in;
       wire s_p, sr_p, p_p, busy;
       integer errors, n_s, n_sr, n_p;

       i2c_framing_classifier dut (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
           .start_pulse(s_p), .repeated_start_pulse(sr_p), .stop_pulse(p_p), .bus_busy(busy));

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

       always @(posedge clk) if (rst_n) begin
           if (s_p)  n_s  = n_s  + 1;
           if (sr_p) n_sr = n_sr + 1;
           if (p_p)  n_p  = n_p  + 1;
           // Mutually exclusive by construction.
           if ((s_p + sr_p + p_p) > 1) begin
               $display("FAIL: %0t -- more than one framing class asserted at once", $time);
               errors = errors + 1;
           end
       end

       task expect_counts;
           input integer es; input integer esr; input integer ep; input integer step;
       begin
           if (n_s !== es || n_sr !== esr || n_p !== ep) begin
               $display("FAIL: step %0d -- S/Sr/P = %0d/%0d/%0d, expected %0d/%0d/%0d",
                        step, n_s, n_sr, n_p, es, esr, ep);
               errors = errors + 1;
           end
       end endtask

       task sda_fall_while_high; begin
           sda_in = 1'b1; scl_in = 1'b1;   repeat (2) @(negedge clk);
           sda_in = 1'b0;                  repeat (2) @(negedge clk);
           scl_in = 1'b0;                  repeat (2) @(negedge clk);
       end endtask

       task release_sda_during_low; begin
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
           sda_in = 1'b1;                  repeat (2) @(negedge clk);
       end endtask

       task sda_rise_while_high; begin
           scl_in = 1'b0; sda_in = 1'b0;   repeat (2) @(negedge clk);
           scl_in = 1'b1;                  repeat (2) @(negedge clk);
           sda_in = 1'b1;                  repeat (2) @(negedge clk);
       end endtask

       task do_bit; input v; begin
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
           sda_in = v;                     repeat (1) @(negedge clk);
           scl_in = 1'b1;                  repeat (2) @(negedge clk);
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
       end endtask

       task coincident_fall; begin
           scl_in = 1'b0; sda_in = 1'b1;   repeat (2) @(negedge clk);
           sda_in = 1'b0; scl_in = 1'b1;   repeat (2) @(negedge clk);
           scl_in = 1'b0;                  repeat (1) @(negedge clk);
       end endtask

       initial begin
           errors = 0; n_s = 0; n_sr = 0; n_p = 0;
           rst_n = 1'b0; scl_in = 1'b1; sda_in = 1'b1;
           repeat (2) @(negedge clk);
           if (busy !== 1'b0) begin $display("FAIL: bus_busy set after reset"); errors = errors + 1; end
           rst_n = 1'b1; @(negedge clk);

           do_bit(1'b0); do_bit(1'b1);
           expect_counts(0, 0, 0, 1);

           sda_fall_while_high();
           expect_counts(1, 0, 0, 2);
           if (busy !== 1'b1) begin $display("FAIL: S did not set bus_busy"); errors = errors + 1; end

           do_bit(1'b1);
           release_sda_during_low();
           sda_fall_while_high();
           expect_counts(1, 1, 0, 3);
           if (busy !== 1'b1) begin $display("FAIL: Sr cleared bus_busy"); errors = errors + 1; end

           do_bit(1'b0);
           release_sda_during_low();
           sda_fall_while_high();
           expect_counts(1, 2, 0, 4);

           sda_rise_while_high();
           expect_counts(1, 2, 1, 5);
           if (busy !== 1'b0) begin $display("FAIL: P did not clear bus_busy"); errors = errors + 1; end

           // Sticky-busy regression: after P the next fall must be S again.
           sda_fall_while_high();
           expect_counts(2, 2, 1, 6);

           coincident_fall();
           expect_counts(2, 2, 1, 7);

           if (errors == 0)
               $display("PASS: S=%0d Sr=%0d P=%0d -- same edge classified by bus state, exclusively",
                        n_s, n_sr, n_p);
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   library ieee;
   use ieee.std_logic_1164.all;

   entity i2c_framing_classifier is
       port (
           clk                  : in  std_logic;
           rst_n                : in  std_logic;
           scl_in               : in  std_logic;   -- observed bus level, not drive intent
           sda_in               : in  std_logic;   -- observed bus level, not drive intent
           start_pulse          : out std_logic;   -- S  -- first START of a transfer
           repeated_start_pulse : out std_logic;   -- Sr -- START while the bus was busy
           stop_pulse           : out std_logic;   -- P
           bus_busy             : out std_logic
       );
   end entity;

   architecture rtl of i2c_framing_classifier is
       signal scl_q : std_logic := '1';
       signal sda_q : std_logic := '1';
       signal busy  : std_logic := '0';
       signal saw_fall, saw_rise : std_logic;
   begin
       -- Both framing edges require SCL HIGH on BOTH samples.
       saw_fall <= scl_q and scl_in and sda_q and (not sda_in);
       saw_rise <= scl_q and scl_in and (not sda_q) and sda_in;

       process (clk)
       begin
           if rising_edge(clk) then
               if rst_n = '0' then
                   scl_q <= '1'; sda_q <= '1';
                   start_pulse          <= '0';
                   repeated_start_pulse <= '0';
                   stop_pulse           <= '0';
                   busy                 <= '0';
               else
                   -- Pulses, not levels: default low every cycle.
                   start_pulse          <= '0';
                   repeated_start_pulse <= '0';
                   stop_pulse           <= '0';

                   -- S and Sr are the SAME EDGE; only the tracked state separates them.
                   if saw_fall = '1' then
                       if busy = '1' then
                           repeated_start_pulse <= '1';
                       else
                           start_pulse <= '1';
                       end if;
                       busy <= '1';
                   elsif saw_rise = '1' then
                       stop_pulse <= '1';
                       busy       <= '0';
                   end if;

                   scl_q <= scl_in;
                   sda_q <= sda_in;
               end if;
           end if;
       end process;

       bus_busy <= busy;
   end architecture;

   library ieee;
   use ieee.std_logic_1164.all;

   entity i2c_framing_classifier_tb is
   end entity;

   architecture sim of i2c_framing_classifier_tb is
       signal clk    : std_logic := '0';
       signal rst_n  : std_logic := '0';
       signal scl_in : std_logic := '1';
       signal sda_in : std_logic := '1';
       signal s_p, sr_p, p_p, busy : std_logic;

       -- Driven by the counting process, read by the checker.
       signal n_s, n_sr, n_p : natural := 0;
       signal excl_err       : natural := 0;
       -- Set by the checker just before it suspends, so the watchdog can tell a
       -- finished run from a stalled one.
       signal test_done : std_logic := '0';
   begin
       dut : entity work.i2c_framing_classifier
           port map (clk => clk, rst_n => rst_n, scl_in => scl_in, sda_in => sda_in,
                     start_pulse => s_p, repeated_start_pulse => sr_p,
                     stop_pulse => p_p, bus_busy => busy);

       clk <= not clk after 5 ns;

       -- Watchdog. A broken design must produce a REPORTED FAILURE, not a silent
       -- stop: without this, a `wait until` against a stalled DUT simply runs to the
       -- simulator's time limit and prints nothing that identifies the problem.
       watchdog : process
       begin
           wait for 40 us;
           if test_done = '0' then
               report "watchdog expired -- the design never reached the expected state"
                   severity failure;
           end if;
           wait;
       end process;

       count : process (clk)
           variable hits : natural;
       begin
           if rising_edge(clk) then
               if rst_n = '1' then
                   hits := 0;
                   if s_p  = '1' then n_s  <= n_s  + 1; hits := hits + 1; end if;
                   if sr_p = '1' then n_sr <= n_sr + 1; hits := hits + 1; end if;
                   if p_p  = '1' then n_p  <= n_p  + 1; hits := hits + 1; end if;
                   -- The three classifications are mutually exclusive by construction.
                   if hits > 1 then excl_err <= excl_err + 1; end if;
               end if;
           end if;
       end process;

       stim : process
           variable errs : natural := 0;

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

           procedure expect_counts (es, esr, ep, step : in natural) is
           begin
               if n_s /= es or n_sr /= esr or n_p /= ep then
                   report "step " & integer'image(step) & ": S/Sr/P = " &
                          integer'image(n_s) & "/" & integer'image(n_sr) & "/" & integer'image(n_p) &
                          ", expected " & integer'image(es) & "/" & integer'image(esr) &
                          "/" & integer'image(ep) severity error;
                   errs := errs + 1;
               end if;
           end procedure;

           procedure sda_fall_while_high is
           begin
               sda_in <= '1'; scl_in <= '1'; waitn(2);
               sda_in <= '0';                waitn(2);
               scl_in <= '0';                waitn(2);
           end procedure;

           procedure release_sda_during_low is
           begin
               scl_in <= '0';   waitn(1);
               sda_in <= '1';   waitn(2);
           end procedure;

           procedure sda_rise_while_high is
           begin
               scl_in <= '0'; sda_in <= '0'; waitn(2);
               scl_in <= '1';                waitn(2);
               sda_in <= '1';                waitn(2);
           end procedure;

           procedure do_bit (v : in std_logic) is
           begin
               scl_in <= '0';   waitn(1);
               sda_in <= v;     waitn(1);
               scl_in <= '1';   waitn(2);
               scl_in <= '0';   waitn(1);
           end procedure;

           procedure coincident_fall is
           begin
               scl_in <= '0'; sda_in <= '1';  waitn(2);
               sda_in <= '0'; scl_in <= '1';  waitn(2);
               scl_in <= '0';                 waitn(1);
           end procedure;
       begin
           waitn(2);
           if busy /= '0' then
               report "bus_busy set after reset" severity error; errs := errs + 1; end if;
           rst_n <= '1'; waitn(1);

           do_bit('0'); do_bit('1');
           expect_counts(0, 0, 0, 1);

           sda_fall_while_high;
           expect_counts(1, 0, 0, 2);
           if busy /= '1' then report "S did not set bus_busy" severity error; errs := errs + 1; end if;

           do_bit('1');
           release_sda_during_low;
           sda_fall_while_high;
           expect_counts(1, 1, 0, 3);
           if busy /= '1' then report "Sr cleared bus_busy" severity error; errs := errs + 1; end if;

           do_bit('0');
           release_sda_during_low;
           sda_fall_while_high;
           expect_counts(1, 2, 0, 4);

           sda_rise_while_high;
           expect_counts(1, 2, 1, 5);
           if busy /= '0' then report "P did not clear bus_busy" severity error; errs := errs + 1; end if;

           -- Sticky-busy regression: after P the next fall must be S again.
           sda_fall_while_high;
           expect_counts(2, 2, 1, 6);

           coincident_fall;
           expect_counts(2, 2, 1, 7);

           if excl_err /= 0 then
               report "more than one framing class asserted simultaneously" severity error;
               errs := errs + 1;
           end if;

           if errs = 0 then
               report "i2c_framing_classifier self-check complete: S=" & integer'image(n_s) &
                      " Sr=" & integer'image(n_sr) & " P=" & integer'image(n_p) &
                      " -- same edge classified by bus state, exclusively" severity note;
           else
               report "i2c_framing_classifier self-check FAILED" severity error;
           end if;
           test_done <= '1';
           wait;
       end process;
   end architecture;

   // Counting how many STARTs a test produced answers nothing useful. What
   // matters is which TRANSITIONS were exercised, because the classifier's whole
   // job is to be correct about position in this sequence.
   covergroup framing_sequence_cg @(posedge clk);
       option.per_instance = 1;

       // The classification actually produced this cycle.
       cp_class : coverpoint framing_class iff (framing_event) {
           bins s  = { CLASS_S  };
           bins sr = { CLASS_SR };
           bins p  = { CLASS_P  };
       }

       // The transitions -- this is the part that finds real holes. A suite that
       // never produced sr => sr has not tested a multi-phase combined transfer;
       // one that never produced p => s has not tested the step-6 regression.
       cp_seq : coverpoint framing_class iff (framing_event) {
           bins s_then_sr  = ( CLASS_S  => CLASS_SR );
           bins sr_then_sr = ( CLASS_SR => CLASS_SR );
           bins sr_then_p  = ( CLASS_SR => CLASS_P  );
           bins s_then_p   = ( CLASS_S  => CLASS_P  );
           bins p_then_s   = ( CLASS_P  => CLASS_S  );   // <- section 7, step 6
       }
   endgroup