Address Decoding Inside a Slave

   if      (must_not_ack)   -> do NOT respond           <-- FIRST, always
   else if (own_match)      -> respond, latch direction
   else if (gen_call_match) -> respond as a broadcast receiver
   else                     -> stay silent

   Why the prohibition is first:

     [Chapter 6.3] established that two Table 3 footnotes forbid responding --
     the START byte and the CBUS address -- and that neither makes an exception
     for a device that happens to hold that address. A device strapped to the
     CBUS address by a board error, or assigned it deliberately under the
     specification's escape hatch, still must not answer it.

     So `own_match` being true is NOT sufficient to respond. Checking the match
     first and the prohibition afterwards produces a device that is compliant in
     every ordinary case and non-compliant in exactly the case the footnote was
     written for.

   Why the general call is last:

     It is the broadest condition -- it matches an address no device owns -- so it
     must not shadow a specific match. It cannot in practice, because the general
     call address and a device's own address are different addresses, but keeping
     the specific case ahead of the broad one is the habit that survives a future
     edit adding a third broad case.

   // The slave-side address decoder: shift, classify, compare, decide, respond.
   // It is ASSEMBLED from the two blocks built earlier in this module rather than
   // reimplementing them -- i2c_address_byte_capture and i2c_address_classifier.
   module i2c_address_decoder #(
       parameter logic [6:0] OWN_ADDR        = 7'h48,
       // General call support is OPTIONAL in the specification (Table 2), so it is
       // a build-time decision and not something every device must implement.
       parameter bit         ANSWER_GEN_CALL = 1'b1
   )(
       input  logic clk,
       input  logic rst_n,
       input  logic scl_in,             // observed bus level
       input  logic sda_in,             // observed bus level
       input  logic frame_start,        // pulse: S or Sr observed (Module 5)
       input  logic frame_stop,         // pulse: P observed (Module 5)
       output logic       addressed,       // this transfer is for this device
       output logic       direction,       // 1 = master READS from us
       output logic       gen_call_active, // selected by the general call, not by address
       output logic       ack_request,     // pulse: acknowledge the address byte
       output logic [6:0] last_addr        // the address seen, for software and debug
   );
       localparam logic [3:0] CLS_GENERAL_CALL = 4'd1;

       // ---- stage 1: get the byte off the wire ----
       logic [6:0] cap_addr;
       logic       cap_rw, cap_valid, capturing;

       i2c_address_byte_capture u_capture (
           .clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
           .frame_start(frame_start), .frame_stop(frame_stop),
           .addr(cap_addr), .rw(cap_rw), .addr_valid(cap_valid), .capturing(capturing)
       );

       // ---- stage 2: decide what kind of address it is ----
       logic       cls_reserved, cls_must_not_ack;
       logic [3:0] cls_class;

       i2c_address_classifier u_classify (
           .addr(cap_addr), .rw(cap_rw),
           .is_reserved(cls_reserved), .addr_class(cls_class), .must_not_ack(cls_must_not_ack)
       );

       // ---- stage 3: compare and decide ----
       logic own_match, gen_call_match;
       assign own_match      = (cap_addr == OWN_ADDR);
       assign gen_call_match = (cls_class == CLS_GENERAL_CALL) && ANSWER_GEN_CALL;

       always_ff @(posedge clk) begin
           if (!rst_n) begin
               addressed       <= 1'b0;
               direction       <= 1'b0;
               gen_call_active <= 1'b0;
               ack_request     <= 1'b0;
               last_addr       <= 7'h00;
           end else begin
               ack_request <= 1'b0;

               if (frame_stop) begin
                   // A STOP releases this device unconditionally.
                   addressed       <= 1'b0;
                   gen_call_active <= 1'b0;
               end else if (frame_start) begin
                   // S or Sr: stop being addressed until the new address says otherwise.
                   // A device that stayed selected across an Sr would answer a transfer
                   // aimed at somebody else.
                   addressed       <= 1'b0;
                   gen_call_active <= 1'b0;
               end else if (cap_valid) begin
                   last_addr <= cap_addr;

                   // The prohibition WINS over a match. Two Table 3 footnotes forbid
                   // responding at all, and they do not make an exception for a device
                   // that happens to have been given that address.
                   if (cls_must_not_ack) begin
                       addressed       <= 1'b0;
                       gen_call_active <= 1'b0;
                   end else if (own_match) begin
                       addressed       <= 1'b1;
                       direction       <= cap_rw;
                       gen_call_active <= 1'b0;
                       ack_request     <= 1'b1;
                   end else if (gen_call_match) begin
                       // The general call is a broadcast WRITE: there is no readable
                       // direction, because every device would be transmitting at once.
                       addressed       <= 1'b1;
                       direction       <= 1'b0;
                       gen_call_active <= 1'b1;
                       ack_request     <= 1'b1;
                   end else begin
                       addressed       <= 1'b0;
                       gen_call_active <= 1'b0;
                   end
               end
           end
       end
   endmodule

   module i2c_address_decoder_tb;
       logic clk = 1'b0, rst_n, scl_in, sda_in, frame_start, frame_stop;
       int errors = 0;

       // THREE devices, to separate three different decisions:
       //   G  -- an ordinary part at 0x48 that answers the general call
       //   N  -- the same part with general call support NOT built
       //   C  -- a part mis-assigned the CBUS address, to prove the prohibition wins
       logic addrG, dirG, gcG, ackG; logic [6:0] laG;
       logic addrN, dirN, gcN, ackN; logic [6:0] laN;
       logic addrC, dirC, gcC, ackC; logic [6:0] laC;

       i2c_address_decoder #(.OWN_ADDR(7'h48), .ANSWER_GEN_CALL(1'b1)) dutG
           (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
            .frame_start(frame_start), .frame_stop(frame_stop),
            .addressed(addrG), .direction(dirG), .gen_call_active(gcG),
            .ack_request(ackG), .last_addr(laG));

       i2c_address_decoder #(.OWN_ADDR(7'h48), .ANSWER_GEN_CALL(1'b0)) dutN
           (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
            .frame_start(frame_start), .frame_stop(frame_stop),
            .addressed(addrN), .direction(dirN), .gen_call_active(gcN),
            .ack_request(ackN), .last_addr(laN));

       i2c_address_decoder #(.OWN_ADDR(7'b0000001), .ANSWER_GEN_CALL(1'b0)) dutC
           (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
            .frame_start(frame_start), .frame_stop(frame_stop),
            .addressed(addrC), .direction(dirC), .gen_call_active(gcC),
            .ack_request(ackC), .last_addr(laC));

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

       int nG = 0, nN = 0, nC = 0;
       always @(posedge clk) if (rst_n) begin
           if (ackG) nG++;
           if (ackN) nN++;
           if (ackC) nC++;
       end

       task automatic send_bit(input logic b);
           scl_in = 1'b0;             repeat (2) @(negedge clk);
           sda_in = b;                repeat (2) @(negedge clk);
           scl_in = 1'b1;             repeat (2) @(negedge clk);
           scl_in = 1'b0;             repeat (1) @(negedge clk);
       endtask
       task automatic pulse_start(); frame_start = 1'b1; @(negedge clk); frame_start = 1'b0; endtask
       task automatic pulse_stop();  frame_stop  = 1'b1; @(negedge clk); frame_stop  = 1'b0; endtask

       // A full addressing phase: framing START then the eight-bit address byte.
       task automatic address_phase(input logic [6:0] a, input logic dir);
           pulse_start();
           for (int i = 6; i >= 0; i--) send_bit(a[i]);
           send_bit(dir);
           repeat (2) @(negedge clk);
       endtask

       task automatic chk(input logic got, input logic want, input int step);
           if (got !== want) begin
               $display("FAIL: step %0d -- signal was %0b, expected %0b", step, got, want);
               errors++;
           end
       endtask

       initial begin
           rst_n = 1'b0; scl_in = 1'b1; sda_in = 1'b1; frame_start = 1'b0; frame_stop = 1'b0;
           repeat (3) @(negedge clk);
           chk(addrG, 1'b0, 0); chk(gcG, 1'b0, 0);
           rst_n = 1'b1; @(negedge clk);

           // 1 -- our own address, WRITE.
           nG = 0;
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 1); chk(dirG, 1'b0, 1); chk(gcG, 1'b0, 1);
           if (nG != 1) begin $display("FAIL: expected exactly one ACK for our address, saw %0d", nG); errors++; end
           if (laG !== 7'h48) begin $display("FAIL: last_addr = 0x%02h", laG); errors++; end

           // 2 -- our own address, READ. Same match, opposite direction.
           pulse_stop();
           nG = 0;
           address_phase(7'h48, 1'b1);
           chk(addrG, 1'b1, 2); chk(dirG, 1'b1, 2);
           if (nG != 1) begin $display("FAIL: read address not acknowledged once"); errors++; end

           // 3 -- somebody else's address. No ACK, and not addressed.
           pulse_stop();
           nG = 0;
           address_phase(7'h49, 1'b0);
           chk(addrG, 1'b0, 3);
           if (nG != 0) begin $display("FAIL: acknowledged another device's address"); errors++; end

           // 4 -- THE GENERAL CALL. The device that supports it answers; the device
           //      built without support stays silent. Both are compliant, because the
           //      specification makes general call OPTIONAL.
           pulse_stop();
           nG = 0; nN = 0;
           address_phase(7'b0000000, 1'b0);
           chk(addrG, 1'b1, 4); chk(gcG, 1'b1, 4); chk(dirG, 1'b0, 4);
           chk(addrN, 1'b0, 4); chk(gcN, 1'b0, 4);
           if (nG != 1) begin $display("FAIL: general call not acknowledged by the supporting device"); errors++; end
           if (nN != 0) begin $display("FAIL: a device without general call support acknowledged it"); errors++; end

           // 5 -- THE START BYTE. Same seven address bits as the general call, R/W = 1.
           //      "No device is allowed to acknowledge at the reception of the START
           //      byte" -- so the direction bit alone flips a broadcast into a
           //      must-not-answer.
           pulse_stop();
           nG = 0; nN = 0;
           address_phase(7'b0000000, 1'b1);
           chk(addrG, 1'b0, 5); chk(gcG, 1'b0, 5);
           if (nG != 0 || nN != 0) begin
               $display("FAIL: the START byte was acknowledged (G=%0d N=%0d)", nG, nN); errors++; end

           // 6 -- THE PROHIBITION WINS OVER A MATCH. Device C was given the CBUS
           //      address. It matches, and it must still not respond.
           pulse_stop();
           nC = 0;
           address_phase(7'b0000001, 1'b0);
           chk(addrC, 1'b0, 6);
           if (nC != 0) begin
               $display("FAIL: a device assigned the CBUS address responded to it"); errors++; end

           // 7 -- a STOP releases the device.
           pulse_stop();
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 7);
           pulse_stop();
           repeat (2) @(negedge clk);
           chk(addrG, 1'b0, 7);

           // 8 -- Sr TO A DIFFERENT ADDRESS must release us. A device that stayed
           //      selected across a repeated START would answer somebody else's
           //      transfer -- and Module 5 established that Sr does not release the bus,
           //      so nothing else would tell it to let go.
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 8);
           address_phase(7'h49, 1'b0);              // Sr, then another device's address
           chk(addrG, 1'b0, 8);

           // 8b -- THE DEVICE MUST LET GO AT THE Sr ITSELF, not merely once the new
           //       address resolves eight clocks later. Between the Sr and the end of
           //       the new address byte, a device that is still reporting `addressed`
           //       is claiming a transfer that may belong to somebody else -- and
           //       anything downstream acting on that flag acts on a stale claim.
           pulse_stop();
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 82);
           pulse_start();                       // the Sr alone -- no address byte yet
           repeat (2) @(negedge clk);
           chk(addrG, 1'b0, 82);                // released already, mid-address-phase

           // 9 -- Sr back to US re-selects, with the new direction.
           address_phase(7'h48, 1'b1);
           chk(addrG, 1'b1, 9); chk(dirG, 1'b1, 9);

           if (errors == 0)
               $display("PASS: own address matched both directions, general call optional, prohibitions win, Sr releases");
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   // The slave-side address decoder: shift, classify, compare, decide, respond.
   // ASSEMBLED from the two blocks built earlier in this module rather than
   // reimplementing them -- i2c_address_byte_capture and i2c_address_classifier.
   module i2c_address_decoder #(
       parameter [6:0] OWN_ADDR        = 7'h48,
       // General call support is OPTIONAL in the specification (Table 2).
       parameter       ANSWER_GEN_CALL = 1'b1
   )(
       input  wire clk,
       input  wire rst_n,
       input  wire scl_in,             // observed bus level
       input  wire sda_in,             // observed bus level
       input  wire frame_start,        // pulse: S or Sr observed (Module 5)
       input  wire frame_stop,         // pulse: P observed (Module 5)
       output reg        addressed,       // this transfer is for this device
       output reg        direction,       // 1 = master READS from us
       output reg        gen_call_active, // selected by the general call
       output reg        ack_request,     // pulse: acknowledge the address byte
       output reg  [6:0] last_addr        // the address seen, for software and debug
   );
       localparam [3:0] CLS_GENERAL_CALL = 4'd1;

       // ---- stage 1: get the byte off the wire ----
       wire [6:0] cap_addr;
       wire       cap_rw, cap_valid, capturing;

       i2c_address_byte_capture u_capture (
           .clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
           .frame_start(frame_start), .frame_stop(frame_stop),
           .addr(cap_addr), .rw(cap_rw), .addr_valid(cap_valid), .capturing(capturing)
       );

       // ---- stage 2: decide what kind of address it is ----
       wire       cls_reserved, cls_must_not_ack;
       wire [3:0] cls_class;

       i2c_address_classifier u_classify (
           .addr(cap_addr), .rw(cap_rw),
           .is_reserved(cls_reserved), .addr_class(cls_class), .must_not_ack(cls_must_not_ack)
       );

       // ---- stage 3: compare and decide ----
       wire own_match      = (cap_addr == OWN_ADDR);
       wire gen_call_match = (cls_class == CLS_GENERAL_CALL) && ANSWER_GEN_CALL;

       always @(posedge clk) begin
           if (!rst_n) begin
               addressed       <= 1'b0;
               direction       <= 1'b0;
               gen_call_active <= 1'b0;
               ack_request     <= 1'b0;
               last_addr       <= 7'h00;
           end else begin
               ack_request <= 1'b0;

               if (frame_stop) begin
                   addressed       <= 1'b0;
                   gen_call_active <= 1'b0;
               end else if (frame_start) begin
                   // S or Sr: stop being addressed until the new address says otherwise.
                   addressed       <= 1'b0;
                   gen_call_active <= 1'b0;
               end else if (cap_valid) begin
                   last_addr <= cap_addr;

                   // The prohibition WINS over a match: the footnotes forbidding a
                   // response make no exception for a device given that address.
                   if (cls_must_not_ack) begin
                       addressed       <= 1'b0;
                       gen_call_active <= 1'b0;
                   end else if (own_match) begin
                       addressed       <= 1'b1;
                       direction       <= cap_rw;
                       gen_call_active <= 1'b0;
                       ack_request     <= 1'b1;
                   end else if (gen_call_match) begin
                       // The general call is a broadcast WRITE: there is no readable
                       // direction, because every device would be transmitting at once.
                       addressed       <= 1'b1;
                       direction       <= 1'b0;
                       gen_call_active <= 1'b1;
                       ack_request     <= 1'b1;
                   end else begin
                       addressed       <= 1'b0;
                       gen_call_active <= 1'b0;
                   end
               end
           end
       end
   endmodule

   module i2c_address_decoder_tb;
       reg clk, rst_n, scl_in, sda_in, frame_start, frame_stop;
       integer errors;

       // THREE devices, to separate three different decisions:
       //   G  -- an ordinary part at 0x48 that answers the general call
       //   N  -- the same part with general call support NOT built
       //   C  -- a part mis-assigned the CBUS address, to prove the prohibition wins
       wire addrG, dirG, gcG, ackG; wire [6:0] laG;
       wire addrN, dirN, gcN, ackN; wire [6:0] laN;
       wire addrC, dirC, gcC, ackC; wire [6:0] laC;

       i2c_address_decoder #(.OWN_ADDR(7'h48), .ANSWER_GEN_CALL(1'b1)) dutG
           (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
            .frame_start(frame_start), .frame_stop(frame_stop),
            .addressed(addrG), .direction(dirG), .gen_call_active(gcG),
            .ack_request(ackG), .last_addr(laG));

       i2c_address_decoder #(.OWN_ADDR(7'h48), .ANSWER_GEN_CALL(1'b0)) dutN
           (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
            .frame_start(frame_start), .frame_stop(frame_stop),
            .addressed(addrN), .direction(dirN), .gen_call_active(gcN),
            .ack_request(ackN), .last_addr(laN));

       i2c_address_decoder #(.OWN_ADDR(7'b0000001), .ANSWER_GEN_CALL(1'b0)) dutC
           (.clk(clk), .rst_n(rst_n), .scl_in(scl_in), .sda_in(sda_in),
            .frame_start(frame_start), .frame_stop(frame_stop),
            .addressed(addrC), .direction(dirC), .gen_call_active(gcC),
            .ack_request(ackC), .last_addr(laC));

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

       integer nG, nN, nC, i;
       always @(posedge clk) if (rst_n) begin
           if (ackG) nG = nG + 1;
           if (ackN) nN = nN + 1;
           if (ackC) nC = nC + 1;
       end

       task send_bit; input b; begin
           scl_in = 1'b0;             repeat (2) @(negedge clk);
           sda_in = b;                repeat (2) @(negedge clk);
           scl_in = 1'b1;             repeat (2) @(negedge clk);
           scl_in = 1'b0;             repeat (1) @(negedge clk);
       end endtask
       task pulse_start; begin frame_start = 1'b1; @(negedge clk); frame_start = 1'b0; end endtask
       task pulse_stop;  begin frame_stop  = 1'b1; @(negedge clk); frame_stop  = 1'b0; end endtask

       // A full addressing phase: framing START then the eight-bit address byte.
       task address_phase; input [6:0] a; input dir; integer k; begin
           pulse_start();
           for (k = 6; k >= 0; k = k - 1) send_bit(a[k]);
           send_bit(dir);
           repeat (2) @(negedge clk);
       end endtask

       task chk; input got; input want; input integer step; begin
           if (got !== want) begin
               $display("FAIL: step %0d -- signal was %0b, expected %0b", step, got, want);
               errors = errors + 1;
           end
       end endtask

       initial begin
           errors = 0; nG = 0; nN = 0; nC = 0;
           rst_n = 1'b0; scl_in = 1'b1; sda_in = 1'b1; frame_start = 1'b0; frame_stop = 1'b0;
           repeat (3) @(negedge clk);
           chk(addrG, 1'b0, 0); chk(gcG, 1'b0, 0);
           rst_n = 1'b1; @(negedge clk);

           // 1 -- our own address, WRITE.
           nG = 0;
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 1); chk(dirG, 1'b0, 1); chk(gcG, 1'b0, 1);
           if (nG != 1) begin $display("FAIL: expected exactly one ACK for our address, saw %0d", nG); errors = errors + 1; end
           if (laG !== 7'h48) begin $display("FAIL: last_addr = 0x%02h", laG); errors = errors + 1; end

           // 2 -- our own address, READ. Same match, opposite direction.
           pulse_stop();
           nG = 0;
           address_phase(7'h48, 1'b1);
           chk(addrG, 1'b1, 2); chk(dirG, 1'b1, 2);
           if (nG != 1) begin $display("FAIL: read address not acknowledged once"); errors = errors + 1; end

           // 3 -- somebody else's address. No ACK, and not addressed.
           pulse_stop();
           nG = 0;
           address_phase(7'h49, 1'b0);
           chk(addrG, 1'b0, 3);
           if (nG != 0) begin $display("FAIL: acknowledged another device's address"); errors = errors + 1; end

           // 4 -- THE GENERAL CALL. The device that supports it answers; the device
           //      built without support stays silent. Both are compliant, because the
           //      specification makes general call OPTIONAL.
           pulse_stop();
           nG = 0; nN = 0;
           address_phase(7'b0000000, 1'b0);
           chk(addrG, 1'b1, 4); chk(gcG, 1'b1, 4); chk(dirG, 1'b0, 4);
           chk(addrN, 1'b0, 4); chk(gcN, 1'b0, 4);
           if (nG != 1) begin $display("FAIL: general call not acknowledged by the supporting device"); errors = errors + 1; end
           if (nN != 0) begin $display("FAIL: a device without general call support acknowledged it"); errors = errors + 1; end

           // 5 -- THE START BYTE. Same seven address bits as the general call, R/W = 1.
           //      "No device is allowed to acknowledge at the reception of the START
           //      byte" -- so the direction bit alone flips a broadcast into a
           //      must-not-answer.
           pulse_stop();
           nG = 0; nN = 0;
           address_phase(7'b0000000, 1'b1);
           chk(addrG, 1'b0, 5); chk(gcG, 1'b0, 5);
           if (nG != 0 || nN != 0) begin
               $display("FAIL: the START byte was acknowledged (G=%0d N=%0d)", nG, nN); errors = errors + 1; end

           // 6 -- THE PROHIBITION WINS OVER A MATCH. Device C was given the CBUS
           //      address. It matches, and it must still not respond.
           pulse_stop();
           nC = 0;
           address_phase(7'b0000001, 1'b0);
           chk(addrC, 1'b0, 6);
           if (nC != 0) begin
               $display("FAIL: a device assigned the CBUS address responded to it"); errors = errors + 1; end

           // 7 -- a STOP releases the device.
           pulse_stop();
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 7);
           pulse_stop();
           repeat (2) @(negedge clk);
           chk(addrG, 1'b0, 7);

           // 8 -- Sr TO A DIFFERENT ADDRESS must release us. A device that stayed
           //      selected across a repeated START would answer somebody else's
           //      transfer -- and Module 5 established that Sr does not release the bus,
           //      so nothing else would tell it to let go.
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 8);
           address_phase(7'h49, 1'b0);              // Sr, then another device's address
           chk(addrG, 1'b0, 8);

           // 8b -- THE DEVICE MUST LET GO AT THE Sr ITSELF, not merely once the new
           //       address resolves eight clocks later. A device still reporting
           //       `addressed` in that window is claiming a transfer that may belong
           //       to somebody else.
           pulse_stop();
           address_phase(7'h48, 1'b0);
           chk(addrG, 1'b1, 82);
           pulse_start();                       // the Sr alone -- no address byte yet
           repeat (2) @(negedge clk);
           chk(addrG, 1'b0, 82);                // released already, mid-address-phase

           // 9 -- Sr back to US re-selects, with the new direction.
           address_phase(7'h48, 1'b1);
           chk(addrG, 1'b1, 9); chk(dirG, 1'b1, 9);

           if (errors == 0)
               $display("PASS: own address matched both directions, general call optional, prohibitions win, Sr releases");
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   library ieee;
   use ieee.std_logic_1164.all;

   -- The slave-side address decoder: shift, classify, compare, decide, respond.
   -- ASSEMBLED from the two blocks built earlier in this module rather than
   -- reimplementing them -- i2c_address_byte_capture and i2c_address_classifier.
   entity i2c_address_decoder is
       generic (
           OWN_ADDR        : std_logic_vector(6 downto 0) := "1001000";   -- 0x48
           -- General call support is OPTIONAL in the specification (Table 2).
           ANSWER_GEN_CALL : boolean := true
       );
       port (
           clk             : in  std_logic;
           rst_n           : in  std_logic;
           scl_in          : in  std_logic;                    -- observed bus level
           sda_in          : in  std_logic;                    -- observed bus level
           frame_start     : in  std_logic;                    -- pulse: S or Sr
           frame_stop      : in  std_logic;                    -- pulse: P
           addressed       : out std_logic;                    -- this transfer is ours
           direction       : out std_logic;                    -- 1 = master READS
           gen_call_active : out std_logic;                    -- selected by general call
           ack_request     : out std_logic;                    -- pulse: ACK the address
           last_addr       : out std_logic_vector(6 downto 0)  -- for software and debug
       );
   end entity;

   architecture rtl of i2c_address_decoder is
       constant CLS_GENERAL_CALL : std_logic_vector(3 downto 0) := x"1";

       -- stage 1
       signal cap_addr  : std_logic_vector(6 downto 0);
       signal cap_rw    : std_logic;
       signal cap_valid : std_logic;
       signal capturing : std_logic;
       -- stage 2
       signal cls_reserved, cls_must_not_ack : std_logic;
       signal cls_class : std_logic_vector(3 downto 0);
       -- stage 3
       signal own_match, gen_call_match : std_logic;
   begin
       u_capture : entity work.i2c_address_byte_capture
           port map (clk => clk, rst_n => rst_n, scl_in => scl_in, sda_in => sda_in,
                     frame_start => frame_start, frame_stop => frame_stop,
                     addr => cap_addr, rw => cap_rw, addr_valid => cap_valid,
                     capturing => capturing);

       u_classify : entity work.i2c_address_classifier
           port map (addr => cap_addr, rw => cap_rw, is_reserved => cls_reserved,
                     addr_class => cls_class, must_not_ack => cls_must_not_ack);

       own_match      <= '1' when cap_addr = OWN_ADDR else '0';
       gen_call_match <= '1' when (cls_class = CLS_GENERAL_CALL and ANSWER_GEN_CALL) else '0';

       process (clk)
       begin
           if rising_edge(clk) then
               if rst_n = '0' then
                   addressed       <= '0';
                   direction       <= '0';
                   gen_call_active <= '0';
                   ack_request     <= '0';
                   last_addr       <= (others => '0');
               else
                   ack_request <= '0';

                   if frame_stop = '1' then
                       addressed       <= '0';
                       gen_call_active <= '0';
                   elsif frame_start = '1' then
                       -- S or Sr: stop being addressed until the new address says so.
                       addressed       <= '0';
                       gen_call_active <= '0';
                   elsif cap_valid = '1' then
                       last_addr <= cap_addr;

                       -- The prohibition WINS over a match: the footnotes forbidding a
                       -- response make no exception for a device given that address.
                       if cls_must_not_ack = '1' then
                           addressed       <= '0';
                           gen_call_active <= '0';
                       elsif own_match = '1' then
                           addressed       <= '1';
                           direction       <= cap_rw;
                           gen_call_active <= '0';
                           ack_request     <= '1';
                       elsif gen_call_match = '1' then
                           -- The general call is a broadcast WRITE: there is no readable
                           -- direction, because every device would transmit at once.
                           addressed       <= '1';
                           direction       <= '0';
                           gen_call_active <= '1';
                           ack_request     <= '1';
                       else
                           addressed       <= '0';
                           gen_call_active <= '0';
                       end if;
                   end if;
               end if;
           end if;
       end process;
   end architecture;

   library ieee;
   use ieee.std_logic_1164.all;

   entity i2c_address_decoder_tb is
   end entity;

   architecture sim of i2c_address_decoder_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 frame_start : std_logic := '0';
       signal frame_stop  : std_logic := '0';

       -- THREE devices, separating three different decisions:
       --   G -- an ordinary part at 0x48 that answers the general call
       --   N -- the same part with general call support NOT built
       --   C -- a part mis-assigned the CBUS address
       signal addrG, dirG, gcG, ackG : std_logic;
       signal addrN, dirN, gcN, ackN : std_logic;
       signal addrC, dirC, gcC, ackC : std_logic;
       signal laG, laN, laC : std_logic_vector(6 downto 0);

       signal nG, nN, nC : natural := 0;
       signal test_done  : std_logic := '0';
   begin
       dutG : entity work.i2c_address_decoder
           generic map (OWN_ADDR => "1001000", ANSWER_GEN_CALL => true)
           port map (clk => clk, rst_n => rst_n, scl_in => scl_in, sda_in => sda_in,
                     frame_start => frame_start, frame_stop => frame_stop,
                     addressed => addrG, direction => dirG, gen_call_active => gcG,
                     ack_request => ackG, last_addr => laG);

       dutN : entity work.i2c_address_decoder
           generic map (OWN_ADDR => "1001000", ANSWER_GEN_CALL => false)
           port map (clk => clk, rst_n => rst_n, scl_in => scl_in, sda_in => sda_in,
                     frame_start => frame_start, frame_stop => frame_stop,
                     addressed => addrN, direction => dirN, gen_call_active => gcN,
                     ack_request => ackN, last_addr => laN);

       dutC : entity work.i2c_address_decoder
           generic map (OWN_ADDR => "0000001", ANSWER_GEN_CALL => false)
           port map (clk => clk, rst_n => rst_n, scl_in => scl_in, sda_in => sda_in,
                     frame_start => frame_start, frame_stop => frame_stop,
                     addressed => addrC, direction => dirC, gen_call_active => gcC,
                     ack_request => ackC, last_addr => laC);

       clk <= not clk after 5 ns;

       watchdog : process
       begin
           wait for 80 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)
       begin
           if rising_edge(clk) then
               if rst_n = '1' then
                   if ackG = '1' then nG <= nG + 1; end if;
                   if ackN = '1' then nN <= nN + 1; end if;
                   if ackC = '1' then nC <= nC + 1; end if;
               end if;
           end if;
       end process;

       stim : process
           variable errs : natural := 0;
           variable bG, bN, bC : 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 send_bit (b : in std_logic) is
           begin
               scl_in <= '0';   waitn(2);
               sda_in <= b;     waitn(2);
               scl_in <= '1';   waitn(2);
               scl_in <= '0';   waitn(1);
           end procedure;

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

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

           procedure address_phase (a : in std_logic_vector(6 downto 0); dir : in std_logic) is
           begin
               pulse_start;
               for k in 6 downto 0 loop send_bit(a(k)); end loop;
               send_bit(dir);
               waitn(2);
           end procedure;

           procedure chk (got, want : in std_logic; step : in natural) is
           begin
               if got /= want then
                   report "step " & integer'image(step) & ": signal mismatch" severity error;
                   errs := errs + 1;
               end if;
           end procedure;
       begin
           waitn(3);
           chk(addrG, '0', 0); chk(gcG, '0', 0);
           rst_n <= '1'; waitn(1);

           -- Our own address, WRITE.
           bG := nG;
           address_phase("1001000", '0');
           chk(addrG, '1', 1); chk(dirG, '0', 1); chk(gcG, '0', 1);
           if (nG - bG) /= 1 then
               report "expected exactly one ACK for our address" severity error; errs := errs + 1; end if;
           if laG /= "1001000" then
               report "last_addr wrong" severity error; errs := errs + 1; end if;

           -- Our own address, READ.
           pulse_stop; bG := nG;
           address_phase("1001000", '1');
           chk(addrG, '1', 2); chk(dirG, '1', 2);
           if (nG - bG) /= 1 then
               report "read address not acknowledged once" severity error; errs := errs + 1; end if;

           -- Somebody else's address.
           pulse_stop; bG := nG;
           address_phase("1001001", '0');
           chk(addrG, '0', 3);
           if (nG - bG) /= 0 then
               report "acknowledged another device's address" severity error; errs := errs + 1; end if;

           -- THE GENERAL CALL: optional, so both behaviours are compliant.
           pulse_stop; bG := nG; bN := nN;
           address_phase("0000000", '0');
           chk(addrG, '1', 4); chk(gcG, '1', 4); chk(dirG, '0', 4);
           chk(addrN, '0', 4); chk(gcN, '0', 4);
           if (nG - bG) /= 1 then
               report "general call not acknowledged by the supporting device" severity error;
               errs := errs + 1; end if;
           if (nN - bN) /= 0 then
               report "a device without general call support acknowledged it" severity error;
               errs := errs + 1; end if;

           -- THE START BYTE: same seven address bits, R/W = 1, must never be acked.
           pulse_stop; bG := nG; bN := nN;
           address_phase("0000000", '1');
           chk(addrG, '0', 5); chk(gcG, '0', 5);
           if (nG - bG) /= 0 or (nN - bN) /= 0 then
               report "the START byte was acknowledged" severity error; errs := errs + 1; end if;

           -- THE PROHIBITION WINS OVER A MATCH.
           pulse_stop; bC := nC;
           address_phase("0000001", '0');
           chk(addrC, '0', 6);
           if (nC - bC) /= 0 then
               report "a device assigned the CBUS address responded to it" severity error;
               errs := errs + 1; end if;

           -- A STOP releases the device.
           pulse_stop;
           address_phase("1001000", '0');
           chk(addrG, '1', 7);
           pulse_stop; waitn(2);
           chk(addrG, '0', 7);

           -- Sr TO A DIFFERENT ADDRESS must release us.
           address_phase("1001000", '0');
           chk(addrG, '1', 8);
           address_phase("1001001", '0');
           chk(addrG, '0', 8);

           -- THE DEVICE MUST LET GO AT THE Sr ITSELF, not merely once the new address
           -- resolves eight clocks later. A device still reporting `addressed` in that
           -- window is claiming a transfer that may belong to somebody else.
           pulse_stop;
           address_phase("1001000", '0');
           chk(addrG, '1', 82);
           pulse_start;                        -- the Sr alone -- no address byte yet
           waitn(2);
           chk(addrG, '0', 82);                -- released already, mid-address-phase

           -- Sr back to US re-selects, with the new direction.
           address_phase("1001000", '1');
           chk(addrG, '1', 9); chk(dirG, '1', 9);

           if errs = 0 then
               report "i2c_address_decoder self-check complete: own address matched both "
                    & "directions, general call optional, prohibitions win, Sr releases"
                    severity note;
           else
               report "i2c_address_decoder self-check FAILED" severity error;
           end if;
           test_done <= '1';
           wait;
       end process;
   end architecture;

   // The strongest single property in this chapter: whatever else is true, a byte
   // the specification forbids answering is never answered. Note it does NOT
   // mention own_match -- that is exactly the point. No matching condition, now or
   // added later, may create an exception.
   property prohibition_always_wins;
       @(posedge clk) disable iff (!rst_n)
       (addr_valid && must_not_ack) |=> !ack_request;
   endproperty
   assert property (prohibition_always_wins)
       else $error("acknowledged a byte the specification forbids answering");

   // And the pulse property, for the same reason it mattered in Chapter 6.1: a
   // consumer in the byte-transfer layer counts acknowledge requests.
   property ack_request_is_a_pulse;
       @(posedge clk) disable iff (!rst_n)
       ack_request |=> !ack_request;
   endproperty

   // Addressed must not survive a framing event -- section 4's window.
   property framing_releases_immediately;
       @(posedge clk) disable iff (!rst_n)
       (frame_start || frame_stop) |=> !addressed;
   endproperty

   // The agent's addressing behaviour is CONFIGURATION, not code, because the
   // whole point of a reusable slave agent is that one class models many parts.
   class i2c_slave_addr_cfg extends uvm_object;
       `uvm_object_utils(i2c_slave_addr_cfg)
       bit [6:0] own_addr        = 7'h48;
       bit       answer_gen_call = 1'b0;   // OPTIONAL per Table 2 -- default off
       bit       ten_bit_mode    = 1'b0;
       bit [9:0] own_addr_10     = 10'h000;
       // The escape hatch of Chapter 6.4, as an explicit opt-in rather than an
       // absent check -- so an agent at a reserved address is a deliberate test,
       // not an accident nobody notices.
       bit       allow_reserved  = 1'b0;
       function new(string name = "i2c_slave_addr_cfg"); super.new(name); endfunction
   endclass

   // The responder mirrors the RTL's ORDERING, deliberately. A model that checked
   // the match first would disagree with a correct DUT on exactly the case the
   // prohibition exists for -- and a disagreeing model reports a DUT bug.
   function bit i2c_slave_responder::should_ack(bit [6:0] a, bit rw);
       if (is_start_byte(a, rw) || is_cbus(a)) return 0;          // FIRST
       if (a == cfg.own_addr)                  return 1;
       if (cfg.answer_gen_call && a == 7'h00 && rw == 1'b0) return 1;
       return 0;
   endfunction