Stuck Bus — Diagnosis and Recovery

   // -----------------------------------------------------------------------------
   // i2c_bus_clear.sv
   // Chapter 23.6's instrument, and the only recovery mechanism I2C has.
   //
   // Chapter 15.4 established the mechanism: a target that was interrupted part-way
   // through transmitting a byte is holding SDA low because it is waiting for the
   // clock pulses that will shift the rest of its byte out. Give it those pulses and
   // it finishes, releases, and the bus is usable again. Chapter 17.11 built it into
   // a master's error path.
   //
   // This version adds what a DIAGNOSTIC needs, which is not more recovery but more
   // evidence about what happened:
   //
   //   result        which of three distinguishable outcomes occurred
   //   pulses_used   how many clock pulses the line needed before it let go
   //
   // WHY pulses_used IS THE INTERESTING OUTPUT. A target interrupted mid-byte needs
   // at most nine more pulses -- one per remaining bit, plus the acknowledge slot --
   // and the number it actually needs says HOW FAR INTO A BYTE it was when the
   // transfer was interrupted. Two pulses means it was almost finished. Eight means
   // it had barely started. And a recovery that succeeds after ZERO pulses did not
   // recover anything: the line was already released and something else was wrong.
   //
   // THE THREE OUTCOMES, and only one of them is a success:
   //
   //   R_OK        SDA released within MAX_PULSES, and a STOP was then generated so
   //               every device on the bus resets its framing state.
   //
   //   R_SCL_HELD  SCL is being held low by something other than this block. This is
   //               NOT RECOVERABLE by this mechanism and it is important to say so
   //               rather than to keep trying: the recovery works by clocking, and
   //               a master that cannot raise SCL cannot clock. Chapter 15.4 says
   //               the same thing from the specification's side.
   //
   //   R_SDA_HELD  MAX_PULSES were delivered and SDA is still low. Whatever is
   //               holding it is not a target waiting for clocks -- a stuck pad, a
   //               device held in reset with its output asserted, a short, or a
   //               target whose state machine is genuinely wedged rather than
   //               merely paused.
   //
   // WHY THE STOP IS PART OF THE RECOVERY AND NOT AN AFTERTHOUGHT. When SDA comes
   // free, every device that was mid-transfer is in an arbitrary framing state, and
   // some of them will interpret the next START as a continuation. A STOP is the one
   // event that returns every conforming device to idle, and a recovery that omits
   // it leaves a bus that is electrically fine and logically inconsistent.
   //
   // OPEN-DRAIN THROUGHOUT. This block pulls low or releases. It never drives high,
   // including during recovery -- a recovery that drove SDA high to "unstick" it
   // would be contention with whatever is holding the line down, which is the one
   // thing an I2C participant must never do.
   // -----------------------------------------------------------------------------

   module i2c_bus_clear #(
      // Clock pulses to deliver before giving up. Nine is the specification's
      // figure and the arithmetic behind it is eight data bits plus the
      // acknowledge slot -- the most a target can still be waiting for.
      parameter integer MAX_PULSES = 9,
      // Sample clocks per half-period of the recovery clock. The recovery clock
      // should be no faster than the bus's normal rate, because a target that was
      // interrupted is not obliged to be fast.
      parameter integer PHASE = 4,
      // How long to wait for SCL to actually read HIGH after releasing it, before
      // concluding that somebody is holding it.
      //
      // This parameter exists because of a bug. The first version checked that SCL
      // had risen IN THE SAME CYCLE it released it -- and reported "SCL is held" on
      // a perfectly healthy bus, every time, because a released line does not read
      // high until at least the next sample and on a real bus not until tr has
      // elapsed. It is the same "released means high" error that Chapter 19.1's
      // DebugLab is about, arriving inside the block whose job is to recover from a
      // bus that is genuinely held.
      //
      // The allowance also has to cover CLOCK STRETCHING, because a target that was
      // interrupted mid-byte is entitled to hold SCL while it catches up (Chapter
      // 12.2). A recovery that treats a legal stretch as a stuck clock abandons
      // exactly the case it was built for.
      parameter integer STRETCH_LIMIT = 64
   ) (
      input  wire clk,
      input  wire rst_n,

      input  wire start,          // one-cycle request

      // The resolved bus, read back.
      input  wire scl_in,
      input  wire sda_in,

      // This block's contribution to the wired-AND.
      output reg  scl_drive_low,
      output reg  sda_drive_low,

      output reg  busy,
      output reg  done,           // one cycle when a result is available
      output reg  [3:0] pulses_used,
      output reg  [1:0] result
   );

      localparam [1:0] R_OK = 2'd0, R_SCL_HELD = 2'd1, R_SDA_HELD = 2'd2;

      localparam [3:0] S_IDLE     = 4'd0,
                       S_CHECK    = 4'd1,
                       S_CLK_LOW  = 4'd2,
                       S_CLK_RISE = 4'd3,
                       S_CLK_HIGH = 4'd4,
                       S_STOP_A   = 4'd5,
                       S_STOP_B   = 4'd6,
                       S_STOP_C   = 4'd7,
                       S_DONE     = 4'd8;

      reg [3:0] state;
      reg [15:0] ph;
      reg [15:0] wait_cnt;

      wire phase_done = (ph + 1) >= PHASE[15:0];

      always @(posedge clk) begin
         if (!rst_n) begin
            state         <= S_IDLE;
            ph            <= 16'd0;
            scl_drive_low <= 1'b0;
            sda_drive_low <= 1'b0;
            busy          <= 1'b0;
            done          <= 1'b0;
            pulses_used   <= 4'd0;
            result        <= R_OK;
         end else begin
            done <= 1'b0;

            case (state)
               S_IDLE: begin
                  scl_drive_low <= 1'b0;
                  sda_drive_low <= 1'b0;
                  busy          <= 1'b0;
                  if (start) begin
                     busy        <= 1'b1;
                     pulses_used <= 4'd0;
                     ph          <= 16'd0;
                     wait_cnt    <= 16'd0;
                     state       <= S_CHECK;
                  end
               end

               // Before anything else: can this block clock at all? It is not
               // driving SCL, so a low SCL means somebody else is holding it, and
               // no number of attempted pulses will change that. Reporting it
               // immediately is the difference between a diagnosis and a hang.
               // Before anything else: can this block clock at all? It is not
               // driving SCL, so a low SCL means somebody else is holding it. The
               // wait is bounded and generous: the line may simply still be rising,
               // or a target may be stretching.
               S_CHECK: begin
                  if (!scl_in) begin
                     if (wait_cnt >= STRETCH_LIMIT[15:0]) begin
                        result <= R_SCL_HELD;
                        state  <= S_DONE;
                     end else wait_cnt <= wait_cnt + 16'd1;
                  end else if (sda_in) begin
                     // Already free. Still issue the STOP: the reason for recovery
                     // was a bus believed to be stuck, and the framing state of
                     // every device on it is unknown regardless of the line level.
                     state <= S_STOP_A;
                  end else begin
                     state <= S_CLK_LOW;
                     ph    <= 16'd0;
                  end
               end

               S_CLK_LOW: begin
                  scl_drive_low <= 1'b1;
                  if (phase_done) begin
                     ph       <= 16'd0;
                     wait_cnt <= 16'd0;
                     state    <= S_CLK_RISE;
                  end else ph <= ph + 16'd1;
               end

               // Release SCL and wait for the line to actually read HIGH before the
               // high phase begins to count. This is clock synchronisation (Chapter
               // 13.2) rather than a delay: the high time a target gets is measured
               // from when the clock is high on the WIRE, not from when this block
               // stopped pulling.
               S_CLK_RISE: begin
                  scl_drive_low <= 1'b0;
                  if (scl_in) begin
                     ph    <= 16'd0;
                     state <= S_CLK_HIGH;
                  end else if (wait_cnt >= STRETCH_LIMIT[15:0]) begin
                     result <= R_SCL_HELD;
                     state  <= S_DONE;
                  end else wait_cnt <= wait_cnt + 16'd1;
               end

               S_CLK_HIGH: begin
                  scl_drive_low <= 1'b0;
                  if (phase_done) begin
                     ph          <= 16'd0;
                     pulses_used <= pulses_used + 4'd1;
                     // SDA is sampled at the END of the high phase, after the line
                     // has had a full phase to rise. Sampling at the start would
                     // read a line released in this pulse as still held, and the
                     // recovery would deliver pulses it did not need -- harmless
                     // for the bus, and it destroys `pulses_used` as evidence.
                     if (sda_in)                                 state <= S_STOP_A;
                     else if (pulses_used + 4'd1 >= MAX_PULSES[3:0]) begin
                        result <= R_SDA_HELD;
                        state  <= S_DONE;
                     end else                                    state <= S_CLK_LOW;
                  end else begin
                     ph <= ph + 16'd1;
                     // SCL going low again DURING its high phase is another device
                     // pulling -- a target stretching, or a second controller
                     // synchronising. Neither is an error, so the block returns to
                     // waiting for the line rather than reporting a fault, and the
                     // bounded wait in S_CLK_RISE is what stops that being a hang.
                     if (!scl_in) begin
                        wait_cnt <= 16'd0;
                        state    <= S_CLK_RISE;
                     end
                  end
               end

               // A STOP: SDA low while SCL is low, SCL released, then SDA released
               // while SCL is high.
               S_STOP_A: begin
                  scl_drive_low <= 1'b1;
                  sda_drive_low <= 1'b1;
                  if (phase_done) begin ph <= 16'd0; state <= S_STOP_B; end
                  else                  ph <= ph + 16'd1;
               end
               S_STOP_B: begin
                  scl_drive_low <= 1'b0;
                  if (phase_done) begin ph <= 16'd0; state <= S_STOP_C; end
                  else                  ph <= ph + 16'd1;
               end
               S_STOP_C: begin
                  sda_drive_low <= 1'b0;
                  if (phase_done) begin
                     ph     <= 16'd0;
                     result <= R_OK;
                     state  <= S_DONE;
                  end else ph <= ph + 16'd1;
               end

               S_DONE: begin
                  scl_drive_low <= 1'b0;
                  sda_drive_low <= 1'b0;
                  busy          <= 1'b0;
                  done          <= 1'b1;
                  state         <= S_IDLE;
               end

               default: state <= S_IDLE;
            endcase
         end
      end

   endmodule

   T2 a target interrupted mid-byte
     FAIL T2 result OK: got 1 expected 0            (1 is R_SCL_HELD)
     FAIL T2 it took exactly three pulses: got 0
     FAIL T2 a STOP was issued: got 0
   T3 a stuck pad
     FAIL T3 result is SDA STILL HELD: got 1        (R_SCL_HELD again)

   // -----------------------------------------------------------------------------
   // i2c_bus_clear_tb.sv
   // Chapter 23.6's experiment: five things that hold a bus low, one recovery, and
   // a demonstration of which of them it can and cannot clear.
   //
   // THE HOLDERS. Each models a real reason a line stays low, and each responds
   // differently to clock pulses. That difference is the whole diagnostic:
   //
   //   H_NONE      nothing is holding. Included so that a recovery reporting
   //               success has something to be compared against.
   //
   //   H_MIDBYTE   a target interrupted part-way through transmitting. It releases
   //               after N more clock pulses, where N is how many bits it still had
   //               to shift. This is the ONE case the recovery is designed for.
   //
   //   H_STUCK     a pad asserted permanently. No number of clocks changes it.
   //
   //   H_SCL       something holding SCL. The recovery cannot clock, so it cannot
   //               run at all -- and must say so rather than hang.
   //
   //   H_BOTH      both lines held. SCL is reported first, because it is the one
   //               that makes everything else moot.
   //
   // Bounded: the recovery has a pulse limit, every wait in the bench is a fixed
   // number of edges, and a watchdog terminates the run. A deliberately unclearable
   // bus must not hang the runner -- which is the specific reason the pulse limit
   // is in the design rather than in the bench.
   // -----------------------------------------------------------------------------

   `timescale 1ns/1ps

   // A holder: something on the bus that is pulling a line down, and a rule for
   // when it lets go.
   module tb_holder #(
      parameter integer KIND        = 0,   // see the localparams in the bench
      parameter integer RELEASE_AT  = 3,   // H_MIDBYTE: pulses needed before it frees
      // The shortest SCL high time this target will accept as a clock pulse. Real
      // devices have one -- it is tHIGH, UM10204 Table 10 -- and a recovery clocking
      // faster than it delivers pulses the target does not count. Modelling it is
      // what makes "the recovery must use a legal clock" testable rather than
      // assumed.
      parameter integer MIN_HIGH    = 4
   ) (
      input  wire clk,
      input  wire rst_n,
      input  wire scl,                     // resolved SCL, read back
      output wire scl_drive_low,
      output wire sda_drive_low
   );
      localparam integer H_NONE = 0, H_MIDBYTE = 1, H_STUCK = 2, H_SCL = 3, H_BOTH = 4,
                         H_SCL_LATE = 5, H_STRETCH = 6;

      reg  scl_q;
      reg  [7:0] pulses;
      // Counted on the FALLING edge, and that is not a detail.
      //
      // A target shifts its next bit onto SDA while SCL is LOW, because changing SDA
      // while SCL is high is by definition a START or a STOP. The first version of
      // this model counted rising edges and therefore released SDA during an SCL
      // high period -- which the bench's own STOP detector duly counted as a STOP,
      // reporting two where one was expected.
      //
      // That was the MODEL being non-conforming, not the design. It is also a real
      // I2C hazard worth keeping in mind: a device that changes SDA at the wrong
      // moment does not merely send a wrong bit, it manufactures framing.
      wire scl_fall = scl_q & ~scl;

      // How long SCL has been continuously high. A pulse counts only if it was high
      // for at least MIN_HIGH samples before falling.
      reg [7:0] high_run;

      always @(posedge clk) begin
         if (!rst_n) begin scl_q <= 1'b1; pulses <= 8'd0; high_run <= 8'd0; end
         else begin
            scl_q <= scl;
            if (scl) high_run <= (high_run == 8'hFF) ? high_run : high_run + 8'd1;
            else     high_run <= 8'd0;
            if (scl_fall && high_run >= MIN_HIGH[7:0] && pulses != 8'hFF)
               pulses <= pulses + 8'd1;
         end
      end

      // A mid-byte target shifts one bit per clock pulse and lets go when it has
      // shifted the last one. It is not "waiting for a timeout"; it is waiting for
      // the clock it is entitled to, which is why clocking works and nothing else
      // does.
      wire midbyte_holding = (pulses < RELEASE_AT[7:0]);

      // H_STRETCH pulls SCL low for a bounded interval that begins two samples
      // AFTER the clock has risen -- which is legal clock synchronisation (Chapter
      // 13.2) and is what a target does when it needs more time part-way through a
      // clock's high phase. A recovery that reports it as a stuck clock abandons
      // the one case it was built for, because a target interrupted mid-byte is
      // exactly the kind of device that stretches.
      //
      // Positioning it after the rise rather than after the fall is deliberate: a
      // stretch that begins while SCL is already low is absorbed by any recovery
      // that waits for the line to rise, so it cannot distinguish one that tolerates
      // a mid-high stretch from one that does not.
      // The stretch is BOUNDED -- two of them, and then the target stops needing
      // more time. An unbounded stretch is a different failure (Chapter 23.7) and it
      // would hang this test rather than exercise it: a recovery that correctly
      // waits for a stretching target would wait forever, which is the correct
      // behaviour and an unusable stimulus.
      wire scl_rise_h = ~scl_q & scl;
      reg [7:0] stretch_arm, stretch_cnt, stretch_budget;
      always @(posedge clk) begin
         if (!rst_n) begin
            stretch_arm <= 8'd0; stretch_cnt <= 8'd0; stretch_budget <= 8'd2;
         end else begin
            if (scl_rise_h && stretch_budget != 8'd0) stretch_arm <= 8'd2;
            else if (stretch_arm != 8'd0)             stretch_arm <= stretch_arm - 8'd1;
            if (stretch_arm == 8'd1) begin
               stretch_cnt    <= 8'd2;
               stretch_budget <= stretch_budget - 8'd1;
            end else if (stretch_cnt != 8'd0) stretch_cnt <= stretch_cnt - 8'd1;
         end
      end

      // H_SCL_LATE leaves SCL alone until the recovery's FIRST clock pulse and then
      // holds it forever. SCL is healthy at the moment the recovery checks it, so
      // the pre-flight check passes and the fault appears mid-recovery -- which is
      // the only way to exercise the bounded wait for the line to rise.
      reg scl_late_grab;
      always @(posedge clk) begin
         if (!rst_n)        scl_late_grab <= 1'b0;
         else if (scl_fall) scl_late_grab <= 1'b1;
      end

      assign sda_drive_low = (KIND == H_MIDBYTE) ? midbyte_holding
                           : (KIND == H_STRETCH) ? midbyte_holding
                           : (KIND == H_STUCK)    ? 1'b1
                           : (KIND == H_BOTH)     ? 1'b1
                           // Holds SDA too, or the recovery finds the bus already
                           // free at its pre-flight check and never clocks -- so the
                           // fault this holder exists to inject is never reached.
                           : (KIND == H_SCL_LATE) ? 1'b1
                                                  : 1'b0;
      assign scl_drive_low = (KIND == H_SCL)      ? 1'b1
                           : (KIND == H_BOTH)     ? 1'b1
                           : (KIND == H_SCL_LATE) ? scl_late_grab
                           : (KIND == H_STRETCH)  ? (stretch_cnt != 8'd0)
                                                  : 1'b0;
   endmodule


   module i2c_bus_clear_tb;

      localparam integer MAX_PULSES = 9, PHASE = 4;
      localparam [1:0] R_OK = 2'd0, R_SCL_HELD = 2'd1, R_SDA_HELD = 2'd2;
      localparam integer H_NONE = 0, H_MIDBYTE = 1, H_STUCK = 2, H_SCL = 3, H_BOTH = 4,
                         H_SCL_LATE = 5, H_STRETCH = 6;
      // Both lines have a rise time. Falling is immediate and rising is not, which
      // is the asymmetry of Chapter 19.7's bus model reduced to one line each. The
      // values are small enough that a release during the low phase completes
      // within it -- a longer SDA rise would finish during the following HIGH phase
      // and, on the wire, that is a STOP condition rather than a bit, which is a
      // real hazard of a bus outside its rise-time budget and not this chapter's
      // subject.
      localparam integer SDA_RISE = 2;
      localparam integer SCL_RISE = 1;

      reg clk = 1'b0;
      reg rst_n = 1'b0;
      always #5 clk = ~clk;

      integer errors = 0, checks = 0, neg_detected = 0, negative_mode = 0;

      // One bus, five holders, exactly one of which is selected at a time. All five
      // are instantiated permanently and gated by `sel`, so every run uses the same
      // netlist and the only thing that changes between cases is which holder is
      // contributing -- the same reason Chapter 23.4 used one fault-injectable
      // target rather than several targets.
      reg [2:0] sel = H_NONE;

      wire c_scl_low, c_sda_low;
      wire [6:0] h_scl_low, h_sda_low;
      wire scl_pull = c_scl_low | h_scl_low[sel];
      wire sda_pull = c_sda_low | h_sda_low[sel];

      // Falling is immediate; rising takes time. The same asymmetry as Chapter
      // 19.7's bus model, reduced to one line each.
      reg [7:0] scl_rc = 8'd0, sda_rc = 8'd0;
      always @(posedge clk) begin
         if (scl_pull)                     scl_rc <= 8'd0;
         else if (scl_rc < SCL_RISE[7:0])  scl_rc <= scl_rc + 8'd1;
         if (sda_pull)                     sda_rc <= 8'd0;
         else if (sda_rc < SDA_RISE[7:0])  sda_rc <= sda_rc + 8'd1;
      end
      wire scl = ~scl_pull && (scl_rc >= SCL_RISE[7:0]);
      wire sda = ~sda_pull && (sda_rc >= SDA_RISE[7:0]);

      genvar g;
      generate
         for (g = 0; g < 7; g = g + 1) begin : holders
            tb_holder #(.KIND(g), .RELEASE_AT(3)) h (
               .clk(clk), .rst_n(rst_n), .scl(scl),
               .scl_drive_low(h_scl_low[g]), .sda_drive_low(h_sda_low[g])
            );
         end
      endgenerate

      reg  start = 1'b0;
      wire busy, done;
      wire [3:0] pulses_used;
      wire [1:0] result;

      i2c_bus_clear #(.MAX_PULSES(MAX_PULSES), .PHASE(PHASE)) dut (
         .clk(clk), .rst_n(rst_n), .start(start),
         .scl_in(scl), .sda_in(sda),
         .scl_drive_low(c_scl_low), .sda_drive_low(c_sda_low),
         .busy(busy), .done(done), .pulses_used(pulses_used), .result(result)
      );

      // A STOP is SDA rising while SCL is high. Counted continuously, because the
      // claim "a STOP was generated" is about an event and an event needs a
      // detector, not an inspection afterwards.
      reg scl_q2, sda_q2;
      integer n_stops = 0;
      always @(posedge clk) if (rst_n) begin
         scl_q2 <= scl; sda_q2 <= sda;
         if (scl_q2 && scl && !sda_q2 && sda) n_stops = n_stops + 1;
      end
      integer stops_before;

      // ------------------------------------------------------------------ helpers
      task step; begin @(posedge clk); #1; end endtask
      task tick (input integer n); integer k; begin for (k=0;k<n;k=k+1) step; end endtask

      task chk (input [255:0] name, input integer got, input integer exp);
         begin
            checks = checks + 1;
            if (got !== exp) begin
               if (negative_mode) neg_detected = neg_detected + 1;
               else begin
                  errors = errors + 1;
                  $display("  FAIL %0s: got %0d expected %0d", name, got, exp);
               end
            end else if (negative_mode) begin
               errors = errors + 1;
               $display("  FAIL negative proof did not fire: %0s", name);
            end
         end
      endtask

      // `sel` must be set BEFORE calling this. Leaving the previous test's holder
      // active across a reset leaves each holder's own `scl_q` initialised to 1
      // against a line that holder is pulling low, so the first post-reset edge
      // looks like a falling edge and a pulse nobody delivered gets counted. That
      // is the same reset-time initial-value mismatch that Chapter 23.5's profiler
      // had to guard against, arriving in the bench instead of the design.
      task do_reset; begin rst_n = 1'b0; start = 1'b0; tick(3); rst_n = 1'b1; tick(3); end endtask

      // Run one recovery to completion, BOUNDED. The wait is a fixed number of
      // edges, not a wait on `done` -- a recovery that never finishes must fail the
      // test rather than hang it, and a bench that waits on a DUT condition cannot
      // tell those apart.
      integer timeout_hit;
      reg [1:0] r_result;
      reg [3:0] r_pulses;
      integer   r_stops_at_done;
      reg       r_scl_low_at_done, r_sda_low_at_done;
      task run_recovery; integer k;
         begin
            timeout_hit = 1;
            start = 1'b1; step; start = 1'b0;
            for (k = 0; k < 4000; k = k + 1) begin
               step;
               if (done) begin
                  r_result        = result;
                  r_pulses        = pulses_used;
                  // The STOP count AT the done strobe, not afterwards. A recovery
                  // that signals completion before its STOP has reached the wire
                  // has told the rest of the system the bus is usable while it is
                  // still mid-framing, and a count taken later cannot see that.
                  r_stops_at_done = n_stops;
                  // The block's own pull-downs AT the strobe. A block that is still
                  // pulling a line low while telling the rest of the system it has
                  // finished has handed over a bus it is itself holding -- and a
                  // check taken a few cycles later cannot see it, because the idle
                  // state releases everything on the next clock.
                  r_scl_low_at_done = c_scl_low;
                  r_sda_low_at_done = c_sda_low;
                  timeout_hit       = 0;
                  k = 4000;
               end
            end
            tick(4);
         end
      endtask

      // Did the controller ever drive a line HIGH? It must not, ever, including
      // during recovery. Checked structurally: the block has no drive-high output,
      // so this watches for the only observable proxy -- a line reading high while
      // every holder is still pulling.
      integer contention = 0;
      always @(posedge clk) if (rst_n)
         if ((h_sda_low[sel] && sda) || (h_scl_low[sel] && scl))
            contention = contention + 1;

      initial begin
         $display("i2c_bus_clear_tb");

         // ---------------------------------------------------------------------
         // T1 -- nothing is holding. The recovery still runs and still issues a
         // STOP, and it uses ZERO pulses. That zero is the control for every other
         // case: a recovery reporting success after no pulses did not recover
         // anything.
         // ---------------------------------------------------------------------
         $display("T1 an already-free bus");
         sel = H_NONE; do_reset; tick(4);
         stops_before = n_stops;
         run_recovery;
         chk("T1 completed", timeout_hit, 0);
         chk("T1 result OK", r_result, R_OK);
         chk("T1 zero pulses were needed", r_pulses, 0);
         chk("T1 a STOP was still issued", n_stops - stops_before, 1);

         // ---------------------------------------------------------------------
         // T2 -- THE CASE THE RECOVERY EXISTS FOR. A target interrupted mid-byte,
         // three bits from the end. It lets go after three pulses, and the count is
         // the evidence: it says how far into a byte the transfer was interrupted.
         // ---------------------------------------------------------------------
         $display("T2 a target interrupted mid-byte");
         sel = H_MIDBYTE; do_reset; tick(4);
         chk("T2 SDA really is held before recovery", sda, 0);
         stops_before = n_stops;
         run_recovery;
         chk("T2 completed", timeout_hit, 0);
         chk("T2 result OK", r_result, R_OK);
         chk("T2 it took exactly three pulses", r_pulses, 3);
         chk("T2 a STOP was issued", n_stops - stops_before, 1);
         chk("T2 the STOP had completed before done was asserted",
             r_stops_at_done - stops_before, 1);
         tick(6);
         chk("T2 the bus is free afterwards", sda, 1);
         chk("T2 the block is not pulling SCL", c_scl_low, 0);
         chk("T2 nor SDA", c_sda_low, 0);

         // ---------------------------------------------------------------------
         // T3 -- a stuck pad. Nine pulses, still held, and the recovery says so
         // instead of continuing. The distinction from T2 is the whole chapter:
         // same symptom, same recovery attempt, different outcome, and the outcome
         // is what identifies the cause.
         // ---------------------------------------------------------------------
         $display("T3 a stuck pad");
         sel = H_STUCK; do_reset; tick(4);
         stops_before = n_stops;
         run_recovery;
         chk("T3 completed rather than hanging", timeout_hit, 0);
         chk("T3 result is SDA STILL HELD", r_result, R_SDA_HELD);
         chk("T3 it used all nine pulses", r_pulses, MAX_PULSES);
         chk("T3 and issued NO stop", n_stops - stops_before, 0);
         chk("T3 the bus is still held", sda, 0);

         // ---------------------------------------------------------------------
         // T4 -- SCL held. The recovery cannot clock, so it must report that
         // immediately rather than attempt pulses that cannot reach the bus.
         // ---------------------------------------------------------------------
         $display("T4 SCL held low");
         sel = H_SCL; do_reset; tick(4);
         stops_before = n_stops;
         run_recovery;
         chk("T4 completed", timeout_hit, 0);
         chk("T4 result is SCL HELD", r_result, R_SCL_HELD);
         chk("T4 it did not attempt any pulses", r_pulses, 0);
         chk("T4 and issued no stop", n_stops - stops_before, 0);

         // ---------------------------------------------------------------------
         // T5 -- both lines held. SCL is reported, because it is the condition that
         // makes the SDA question unanswerable rather than merely unanswered.
         // ---------------------------------------------------------------------
         $display("T5 both lines held");
         sel = H_BOTH; do_reset; tick(4);
         run_recovery;
         chk("T5 completed", timeout_hit, 0);
         chk("T5 SCL is reported, not SDA", r_result, R_SCL_HELD);
         chk("T5 not the SDA verdict", (r_result == R_SDA_HELD) ? 1 : 0, 0);

         // ---------------------------------------------------------------------
         // T6 -- the pulse count is evidence, not decoration. Three targets
         // interrupted at three different points produce three different counts,
         // and the count is proportional to how much of the byte was left.
         // ---------------------------------------------------------------------
         $display("T6 the pulse count says how far into the byte it was");
         // The holder needs three pulses, and the recovery reports three. The
         // claims worth making about that number, each of which would be false for
         // a plausible wrong implementation:
         begin : count_claims
            integer got_pulses;
            sel = H_MIDBYTE; do_reset; tick(4);
            run_recovery;
            got_pulses = r_pulses;
            chk("T6 the count matches what the holder needed", got_pulses, 3);
            chk("T6 it is within the specification's nine", (got_pulses <= 9) ? 1 : 0, 1);
            // Not zero: a recovery reporting success after no pulses did not
            // recover anything, and would report exactly the same R_OK.
            chk("T6 it is not zero, so pulses did the work", (got_pulses > 0) ? 1 : 0, 1);
            // And not the maximum: a recovery that always delivers nine and then
            // checks would also succeed here, and would carry no information about
            // how far into the byte the transfer was interrupted.
            chk("T6 and not the maximum, so it stopped when the line came free",
                (got_pulses < MAX_PULSES) ? 1 : 0, 1);
         end

         // ---------------------------------------------------------------------
         // T9 -- SCL becomes held DURING the recovery. The pre-flight check passes,
         // because SCL is healthy at that moment, and the fault appears on the
         // first clock pulse. The bounded wait for the line to rise is the only
         // thing between this and a permanent hang.
         // ---------------------------------------------------------------------
         $display("T9 SCL grabbed after the recovery has started");
         sel = H_SCL_LATE; do_reset; tick(4);
         chk("T9 SCL is healthy before the recovery", scl, 1);
         run_recovery;
         chk("T9 completed rather than hanging", timeout_hit, 0);
         chk("T9 result is SCL HELD", r_result, R_SCL_HELD);
         chk("T9 and it got past the pre-flight check", (r_pulses <= 1) ? 1 : 0, 1);

         // ---------------------------------------------------------------------
         // T10 -- a target that STRETCHES. Holding SCL low after each pulse is
         // legal and is exactly what an interrupted target does. The recovery must
         // wait rather than report a fault, and must still succeed.
         // ---------------------------------------------------------------------
         $display("T10 a stretching target must not be reported as a stuck clock");
         sel = H_STRETCH; do_reset; tick(4);
         chk("T10 SDA is held before recovery", sda, 0);
         stops_before = n_stops;
         run_recovery;
         chk("T10 completed", timeout_hit, 0);
         chk("T10 the recovery SUCCEEDED despite the stretching", r_result, R_OK);
         chk("T10 not misreported as a stuck clock", (r_result == R_SCL_HELD) ? 1 : 0, 0);
         chk("T10 and it still took three pulses", r_pulses, 3);
         chk("T10 a STOP was issued", n_stops - stops_before, 1);

         // ---------------------------------------------------------------------
         // T7 -- NO CONTENTION, ever. Recovery is the moment an implementation is
         // most tempted to drive a line high to "unstick" it, and that is the one
         // thing an I2C participant must never do. Watched continuously across
         // every test above.
         // ---------------------------------------------------------------------
         $display("T7 the recovery never drove a line high");
         chk("T7 no instant where a held line read high", contention, 0);
         chk("T7 and the watch was actually running", (n_stops > 0) ? 1 : 0, 1);
         // And the block releases everything when it finishes, on a bus with no
         // holder at all -- so a recovery cannot leave the bus worse than it found
         // it. Checked last, when nothing else is pulling.
         sel = H_NONE; do_reset; tick(4);
         run_recovery;
         tick(8);
         chk("T7 SCL released AT the done strobe", r_scl_low_at_done, 0);
         chk("T7 SDA released AT the done strobe", r_sda_low_at_done, 0);
         chk("T7 SCL still released afterwards", c_scl_low, 0);
         chk("T7 SDA still released afterwards", c_sda_low, 0);
         chk("T7 and the bus reads idle", (scl && sda) ? 1 : 0, 1);

         // ---------------------------------------------------------------------
         // T8 -- negative proof. Eight deliberately wrong expectations.
         // ---------------------------------------------------------------------
         $display("T8 negative proof -- eight deliberately wrong expectations");
         sel = H_MIDBYTE; do_reset; tick(4);
         stops_before = n_stops;
         run_recovery;
         chk("T8 setup: recovery succeeded", r_result, R_OK);
         chk("T8 setup: three pulses", r_pulses, 3);
         negative_mode = 1;
         chk("T8a wrong result",        r_result, R_SDA_HELD);
         chk("T8b wrong pulse count",   r_pulses, 9);
         chk("T8c wrong stop count",    n_stops - stops_before, 0);
         chk("T8d wrong completion",    timeout_hit, 1);
         chk("T8e wrong line state",    sda, 0);
         chk("T8f wrong contention",    contention, 5);
         chk("T8g wrong zero-pulse claim", (r_pulses == 0) ? 1 : 0, 1);
         chk("T8h wrong verdict distinctness", (r_result == R_SCL_HELD) ? 1 : 0, 1);
         negative_mode = 0;
         chk("T8 all eight negatives detected", neg_detected, 8);

         $display("");
         $display("checks=%0d errors=%0d negatives_detected=%0d/8", checks, errors, neg_detected);
         if (errors == 0) $display("RESULT: PASS"); else $display("RESULT: FAIL");
         $finish;
      end

      initial begin
         #3000000;
         $display("RESULT: FAIL -- watchdog expired, the run did not terminate");
         $finish;
      end

   endmodule

   holder                          result       pulses   STOP issued
   nothing holding                 R_OK         0        yes
   target interrupted mid-byte     R_OK         3        yes
   stuck pad                       R_SDA_HELD   9        no
   SCL held from the start         R_SCL_HELD   0        no
   both lines held                 R_SCL_HELD   0        no
   SCL grabbed mid-recovery        R_SCL_HELD   1        no
   target that stretches           R_OK         3        yes

   FIRST CAMPAIGN       13 valid    7 KILLED   6 SURVIVED
   AFTER T7, T9, T10    13 valid   13 KILLED   0 SURVIVED