Who Acknowledges When — Slave ACK and Master ACK

   // Who drives the eight data bits, and who drives the ninth slot, for ONE byte.
   // The rule is one sentence: the RECEIVER of a byte acknowledges it. Everything
   // below is that sentence applied to the three kinds of byte on this bus.
   module i2c_ack_role_resolver (
       input  logic is_master,         // 1 = this device is the controller
       input  logic addressed,         // slave only: is this transfer for me?
       input  logic byte_is_address,   // 1 = the address byte, 0 = a data byte
       input  logic transfer_is_read,  // the latched R/W of this transfer
       output logic we_transmit,       // do we drive the eight data bits?
       output logic we_acknowledge     // do we drive the ninth slot?
   );
       // The address byte is ALWAYS transmitted by the master and received by the
       // slaves -- which is why the direction bit does not change who acknowledges it.
       // The specification says so directly: "This first acknowledge is still
       // generated by the slave. The master generates subsequent acknowledges."
       logic slave_is_receiver;
       assign slave_is_receiver = byte_is_address ? 1'b1 : ~transfer_is_read;

       // The transmitter is whoever is NOT the receiver.
       assign we_transmit    =  is_master ?  slave_is_receiver
                                          : (~slave_is_receiver && addressed);

       // And the receiver is the one that acknowledges.
       assign we_acknowledge =  is_master ? ~slave_is_receiver
                                          : ( slave_is_receiver && addressed);
   endmodule

   module i2c_ack_role_resolver_tb;
       logic is_master, addressed, byte_is_address, transfer_is_read;
       logic we_transmit, we_acknowledge;
       int errors = 0;
       int both_count = 0;

       i2c_ack_role_resolver dut (.*);

       initial begin #20000; $display("FAIL: watchdog expired"); $finish; end

       // INDEPENDENT reference model, written as the SPECIFICATION'S ENGLISH rather
       // than as boolean algebra: name the receiver first, then derive the two roles.
       // A model written as the same algebra as the design would agree with it even
       // when both were wrong about who receives an address byte.
       function automatic bit master_receives(input bit is_addr, input bit rd);
           if (is_addr) return 1'b0;        // the master SENDS the address byte
           else         return rd;          // on a read, data flows to the master
       endfunction

       function automatic bit ref_tx(input bit m, input bit ad, input bit is_addr, input bit rd);
           // The transmitter is whoever is not the receiver.
           if (m) return !master_receives(is_addr, rd);
           else   return  master_receives(is_addr, rd) && ad;
       endfunction

       function automatic bit ref_ack(input bit m, input bit ad, input bit is_addr, input bit rd);
           // "The receiver acknowledges" -- so the acknowledger IS the receiver.
           if (m) return  master_receives(is_addr, rd);
           else   return !master_receives(is_addr, rd) && ad;
       endfunction

       bit e_tx, e_ack;

       initial begin
           // Exhaustive: four one-bit inputs is sixteen combinations. Walk all of them.
           for (int v = 0; v < 16; v++) begin
               is_master        = v[3];
               addressed        = v[2];
               byte_is_address  = v[1];
               transfer_is_read = v[0];
               #1;
               e_tx  = ref_tx (v[3], v[2], v[1], v[0]);
               e_ack = ref_ack(v[3], v[2], v[1], v[0]);
               if (we_transmit !== e_tx) begin
                   $display("FAIL: m=%0b ad=%0b addr=%0b rd=%0b -- we_transmit %0b, expected %0b",
                            v[3], v[2], v[1], v[0], we_transmit, e_tx);
                   errors++;
               end
               if (we_acknowledge !== e_ack) begin
                   $display("FAIL: m=%0b ad=%0b addr=%0b rd=%0b -- we_acknowledge %0b, expected %0b",
                            v[3], v[2], v[1], v[0], we_acknowledge, e_ack);
                   errors++;
               end
               // THE INVARIANT: no device is ever both the transmitter and the
               // acknowledger of the SAME byte. A design that allowed it would have a
               // device answering its own byte, which the wired-AND would hide.
               if (we_transmit && we_acknowledge) begin
                   $display("FAIL: m=%0b ad=%0b addr=%0b rd=%0b -- transmit AND acknowledge",
                            v[3], v[2], v[1], v[0]);
                   both_count++;
                   errors++;
               end
           end

           // The four rows of the table every engineer should be able to recite.
           // Address byte, master: the master sends, the slave answers.
           is_master=1; addressed=0; byte_is_address=1; transfer_is_read=0; #1;
           if (we_transmit !== 1'b1 || we_acknowledge !== 1'b0) begin
               $display("FAIL: master must SEND the address byte and not acknowledge it"); errors++; end
           // Address byte on a READ transfer -- still the slave that answers.
           transfer_is_read=1; #1;
           if (we_transmit !== 1'b1 || we_acknowledge !== 1'b0) begin
               $display("FAIL: the address byte's acknowledge must not depend on R/W"); errors++; end
           // Data byte on a WRITE: the slave receives, so the slave answers.
           is_master=0; addressed=1; byte_is_address=0; transfer_is_read=0; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b1) begin
               $display("FAIL: an addressed slave must acknowledge a written data byte"); errors++; end
           // Data byte on a READ: the MASTER receives, so the MASTER answers.
           is_master=1; addressed=0; byte_is_address=0; transfer_is_read=1; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b1) begin
               $display("FAIL: the master must acknowledge a data byte it read"); errors++; end
           // ... and the slave transmits it.
           is_master=0; addressed=1; #1;
           if (we_transmit !== 1'b1 || we_acknowledge !== 1'b0) begin
               $display("FAIL: an addressed slave must transmit on a read and not acknowledge"); errors++; end
           // An UNADDRESSED slave does nothing at all, in either direction.
           addressed=0; byte_is_address=0; transfer_is_read=0; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b0) begin
               $display("FAIL: an unaddressed slave must neither transmit nor acknowledge"); errors++; end
           transfer_is_read=1; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b0) begin
               $display("FAIL: an unaddressed slave must stay silent on a read too"); errors++; end

           if (errors == 0)
               $display("PASS: all 16 combinations match an independent model; transmit and acknowledge never coincide");
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   // Who drives the eight data bits, and who drives the ninth slot, for ONE byte.
   // The rule is one sentence: the RECEIVER of a byte acknowledges it.
   module i2c_ack_role_resolver (
       input  wire is_master,         // 1 = this device is the controller
       input  wire addressed,         // slave only: is this transfer for me?
       input  wire byte_is_address,   // 1 = the address byte, 0 = a data byte
       input  wire transfer_is_read,  // the latched R/W of this transfer
       output wire we_transmit,       // do we drive the eight data bits?
       output wire we_acknowledge     // do we drive the ninth slot?
   );
       // The address byte is ALWAYS transmitted by the master and received by the
       // slaves -- which is why the direction bit does not change who acknowledges it.
       // "This first acknowledge is still generated by the slave. The master generates
       // subsequent acknowledges."
       wire slave_is_receiver = byte_is_address ? 1'b1 : ~transfer_is_read;

       // The transmitter is whoever is NOT the receiver.
       assign we_transmit    = is_master ?  slave_is_receiver
                                         : (~slave_is_receiver & addressed);

       // And the receiver is the one that acknowledges.
       assign we_acknowledge = is_master ? ~slave_is_receiver
                                         : ( slave_is_receiver & addressed);
   endmodule

   module i2c_ack_role_resolver_tb;
       reg  is_master, addressed, byte_is_address, transfer_is_read;
       wire we_transmit, we_acknowledge;
       integer errors, both_count, v;

       i2c_ack_role_resolver dut (.is_master(is_master), .addressed(addressed),
           .byte_is_address(byte_is_address), .transfer_is_read(transfer_is_read),
           .we_transmit(we_transmit), .we_acknowledge(we_acknowledge));

       initial begin #20000; $display("FAIL: watchdog expired"); $finish; end

       // INDEPENDENT reference model, written as the SPECIFICATION'S ENGLISH rather
       // than as boolean algebra: name the receiver first, then derive the two roles.
       // A model written as the same algebra as the design would agree with it even
       // when both were wrong about who receives an address byte.
       function master_receives; input is_addr; input rd; begin
           if (is_addr) master_receives = 1'b0;   // the master SENDS the address byte
           else         master_receives = rd;     // on a read, data flows to the master
       end endfunction

       function ref_tx; input m; input ad; input is_addr; input rd; begin
           // The transmitter is whoever is not the receiver.
           if (m) ref_tx = !master_receives(is_addr, rd);
           else   ref_tx =  master_receives(is_addr, rd) && ad;
       end endfunction

       function ref_ack; input m; input ad; input is_addr; input rd; begin
           // "The receiver acknowledges" -- so the acknowledger IS the receiver.
           if (m) ref_ack =  master_receives(is_addr, rd);
           else   ref_ack = !master_receives(is_addr, rd) && ad;
       end endfunction

       reg e_tx, e_ack;

       initial begin
           errors = 0; both_count = 0;
           // Exhaustive: four one-bit inputs is sixteen combinations. Walk all of them.
           for (v = 0; v < 16; v = v + 1) begin
               is_master        = v[3];
               addressed        = v[2];
               byte_is_address  = v[1];
               transfer_is_read = v[0];
               #1;
               e_tx  = ref_tx (v[3], v[2], v[1], v[0]);
               e_ack = ref_ack(v[3], v[2], v[1], v[0]);
               if (we_transmit !== e_tx) begin
                   $display("FAIL: m=%0b ad=%0b addr=%0b rd=%0b -- we_transmit %0b, expected %0b",
                            v[3], v[2], v[1], v[0], we_transmit, e_tx);
                   errors = errors + 1;
               end
               if (we_acknowledge !== e_ack) begin
                   $display("FAIL: m=%0b ad=%0b addr=%0b rd=%0b -- we_acknowledge %0b, expected %0b",
                            v[3], v[2], v[1], v[0], we_acknowledge, e_ack);
                   errors = errors + 1;
               end
               // THE INVARIANT: no device is ever both the transmitter and the
               // acknowledger of the SAME byte. A design that allowed it would have a
               // device answering its own byte, which the wired-AND would hide.
               if (we_transmit && we_acknowledge) begin
                   $display("FAIL: m=%0b ad=%0b addr=%0b rd=%0b -- transmit AND acknowledge",
                            v[3], v[2], v[1], v[0]);
                   both_count = both_count + 1;
                   errors = errors + 1;
               end
           end

           // The four rows of the table every engineer should be able to recite.
           // Address byte, master: the master sends, the slave answers.
           is_master=1; addressed=0; byte_is_address=1; transfer_is_read=0; #1;
           if (we_transmit !== 1'b1 || we_acknowledge !== 1'b0) begin
               $display("FAIL: master must SEND the address byte and not acknowledge it"); errors = errors + 1; end
           // Address byte on a READ transfer -- still the slave that answers.
           transfer_is_read=1; #1;
           if (we_transmit !== 1'b1 || we_acknowledge !== 1'b0) begin
               $display("FAIL: the address byte's acknowledge must not depend on R/W"); errors = errors + 1; end
           // Data byte on a WRITE: the slave receives, so the slave answers.
           is_master=0; addressed=1; byte_is_address=0; transfer_is_read=0; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b1) begin
               $display("FAIL: an addressed slave must acknowledge a written data byte"); errors = errors + 1; end
           // Data byte on a READ: the MASTER receives, so the MASTER answers.
           is_master=1; addressed=0; byte_is_address=0; transfer_is_read=1; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b1) begin
               $display("FAIL: the master must acknowledge a data byte it read"); errors = errors + 1; end
           // ... and the slave transmits it.
           is_master=0; addressed=1; #1;
           if (we_transmit !== 1'b1 || we_acknowledge !== 1'b0) begin
               $display("FAIL: an addressed slave must transmit on a read and not acknowledge"); errors = errors + 1; end
           // An UNADDRESSED slave does nothing at all, in either direction.
           addressed=0; byte_is_address=0; transfer_is_read=0; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b0) begin
               $display("FAIL: an unaddressed slave must neither transmit nor acknowledge"); errors = errors + 1; end
           transfer_is_read=1; #1;
           if (we_transmit !== 1'b0 || we_acknowledge !== 1'b0) begin
               $display("FAIL: an unaddressed slave must stay silent on a read too"); errors = errors + 1; end

           if (errors == 0)
               $display("PASS: all 16 combinations match an independent model; transmit and acknowledge never coincide");
           else $display("FAIL: %0d error(s)", errors);
           $finish;
       end
   endmodule

   library ieee;
   use ieee.std_logic_1164.all;

   -- Who drives the eight data bits, and who drives the ninth slot, for ONE byte.
   -- The rule is one sentence: the RECEIVER of a byte acknowledges it.
   entity i2c_ack_role_resolver is
       port (
           is_master        : in  std_logic;   -- 1 = this device is the controller
           addressed        : in  std_logic;   -- slave only: is this transfer for me?
           byte_is_address  : in  std_logic;   -- 1 = the address byte, 0 = a data byte
           transfer_is_read : in  std_logic;   -- the latched R/W of this transfer
           we_transmit      : out std_logic;   -- do we drive the eight data bits?
           we_acknowledge   : out std_logic    -- do we drive the ninth slot?
       );
   end entity;

   architecture rtl of i2c_ack_role_resolver is
       -- The address byte is ALWAYS transmitted by the master and received by the
       -- slaves -- which is why the direction bit does not change who acknowledges it.
       -- "This first acknowledge is still generated by the slave. The master generates
       -- subsequent acknowledges."
       signal slave_is_receiver : std_logic;
   begin
       slave_is_receiver <= '1' when byte_is_address = '1' else (not transfer_is_read);

       -- The transmitter is whoever is NOT the receiver.
       we_transmit <= slave_is_receiver when is_master = '1'
                      else ((not slave_is_receiver) and addressed);

       -- And the receiver is the one that acknowledges.
       we_acknowledge <= (not slave_is_receiver) when is_master = '1'
                         else (slave_is_receiver and addressed);
   end architecture;

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

   entity i2c_ack_role_resolver_tb is
   end entity;

   architecture sim of i2c_ack_role_resolver_tb is
       signal is_master, addressed, byte_is_address, transfer_is_read : std_logic := '0';
       signal we_transmit, we_acknowledge : std_logic;
       signal test_done : std_logic := '0';
   begin
       dut : entity work.i2c_ack_role_resolver
           port map (is_master => is_master, addressed => addressed,
                     byte_is_address => byte_is_address, transfer_is_read => transfer_is_read,
                     we_transmit => we_transmit, we_acknowledge => we_acknowledge);

       watchdog : process
       begin
           wait for 20 us;
           if test_done = '0' then
               report "watchdog expired -- the sweep never completed" severity failure;
           end if;
           wait;
       end process;

       stim : process
           variable errs : natural := 0;

           -- INDEPENDENT reference model, written as the specification's English rather
           -- than as boolean algebra: name the receiver first, then derive both roles.
           function master_receives (is_addr, rd : std_logic) return boolean is
           begin
               if is_addr = '1' then return false;        -- the master SENDS the address
               else                  return rd = '1';     -- on a read, data flows to it
               end if;
           end function;

           function ref_tx (m, ad, is_addr, rd : std_logic) return std_logic is
           begin
               if m = '1' then
                   if master_receives(is_addr, rd) then return '0'; else return '1'; end if;
               else
                   if master_receives(is_addr, rd) and ad = '1' then return '1';
                   else return '0'; end if;
               end if;
           end function;

           function ref_ack (m, ad, is_addr, rd : std_logic) return std_logic is
           begin
               if m = '1' then
                   if master_receives(is_addr, rd) then return '1'; else return '0'; end if;
               else
                   if (not master_receives(is_addr, rd)) and ad = '1' then return '1';
                   else return '0'; end if;
               end if;
           end function;

           variable bits : std_logic_vector(3 downto 0);
       begin
           -- Exhaustive: four one-bit inputs is sixteen combinations.
           for v in 0 to 15 loop
               bits := std_logic_vector(to_unsigned(v, 4));
               is_master        <= bits(3);
               addressed        <= bits(2);
               byte_is_address  <= bits(1);
               transfer_is_read <= bits(0);
               wait for 1 ns;

               if we_transmit /= ref_tx(bits(3), bits(2), bits(1), bits(0)) then
                   report "combination " & integer'image(v) & ": we_transmit disagrees"
                       severity error; errs := errs + 1;
               end if;
               if we_acknowledge /= ref_ack(bits(3), bits(2), bits(1), bits(0)) then
                   report "combination " & integer'image(v) & ": we_acknowledge disagrees"
                       severity error; errs := errs + 1;
               end if;
               -- THE INVARIANT: never both the transmitter and the acknowledger of the
               -- same byte.
               if we_transmit = '1' and we_acknowledge = '1' then
                   report "combination " & integer'image(v) & ": transmit AND acknowledge"
                       severity error; errs := errs + 1;
               end if;
           end loop;

           -- The four rows every engineer should be able to recite.
           is_master <= '1'; addressed <= '0'; byte_is_address <= '1'; transfer_is_read <= '0';
           wait for 1 ns;
           if we_transmit /= '1' or we_acknowledge /= '0' then
               report "master must SEND the address byte and not acknowledge it" severity error;
               errs := errs + 1; end if;
           transfer_is_read <= '1'; wait for 1 ns;
           if we_transmit /= '1' or we_acknowledge /= '0' then
               report "the address byte's acknowledge must not depend on R/W" severity error;
               errs := errs + 1; end if;
           is_master <= '0'; addressed <= '1'; byte_is_address <= '0'; transfer_is_read <= '0';
           wait for 1 ns;
           if we_transmit /= '0' or we_acknowledge /= '1' then
               report "an addressed slave must acknowledge a written data byte" severity error;
               errs := errs + 1; end if;
           is_master <= '1'; addressed <= '0'; transfer_is_read <= '1'; wait for 1 ns;
           if we_transmit /= '0' or we_acknowledge /= '1' then
               report "the master must acknowledge a data byte it read" severity error;
               errs := errs + 1; end if;
           is_master <= '0'; addressed <= '1'; wait for 1 ns;
           if we_transmit /= '1' or we_acknowledge /= '0' then
               report "an addressed slave must transmit on a read and not acknowledge"
                   severity error; errs := errs + 1; end if;
           addressed <= '0'; transfer_is_read <= '0'; wait for 1 ns;
           if we_transmit /= '0' or we_acknowledge /= '0' then
               report "an unaddressed slave must neither transmit nor acknowledge"
                   severity error; errs := errs + 1; end if;
           transfer_is_read <= '1'; wait for 1 ns;
           if we_transmit /= '0' or we_acknowledge /= '0' then
               report "an unaddressed slave must stay silent on a read too" severity error;
               errs := errs + 1; end if;

           if errs = 0 then
               report "i2c_ack_role_resolver self-check complete: all 16 combinations match an "
                    & "independent model; transmit and acknowledge never coincide" severity note;
           else
               report "i2c_ack_role_resolver self-check FAILED" severity error;
           end if;
           test_done <= '1';
           wait;
       end process;
   end architecture;

   slave_is_receiver = byte_is_address ? 1 : !transfer_is_read

     address byte  ->  1, ALWAYS. The master addresses; the slaves listen. The
                       direction bit describes the DATA, not this byte.
     data, write   ->  1. Data flows master -> slave.
     data, read    ->  0. Data flows slave -> master.

   then, because the receiver acknowledges and the other one transmits:

     we_transmit    = is_master ?  slave_is_receiver : (!slave_is_receiver && addressed)
     we_acknowledge = is_master ? !slave_is_receiver : ( slave_is_receiver && addressed)
                                  ^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^
                                  exact complements -- which is what guarantees no
                                  device is ever both, for any input combination

   The `addressed` term appears only in the slave branch, because an unaddressed
   slave does nothing at all: it neither transmits nor answers. A master has no
   equivalent term because a master is always a participant in its own transfer.

   // A reusable agent should not have separate master and slave acknowledge logic.
   // The rule is symmetric: the receiver answers. So the SAME function serves both
   // agents, with is_master as configuration -- and a disagreement between the two
   // agents about who should answer becomes impossible by construction.
   typedef enum { BYTE_ADDRESS, BYTE_DATA } i2c_byte_kind_e;

   function bit i2c_agent::should_i_acknowledge(i2c_byte_kind_e kind, bit transfer_is_read);
       bit slave_receives;
       // The address byte is always master -> slave, whatever the direction bit says.
       slave_receives = (kind == BYTE_ADDRESS) ? 1'b1 : !transfer_is_read;
       if (cfg.is_master) return !slave_receives;
       else               return  slave_receives && this.addressed;
   endfunction

   // The invariant, as an assertion rather than as a comment. It is the one property
   // that no amount of role confusion can satisfy.
   property never_transmitter_and_acknowledger;
       @(posedge clk) disable iff (!rst_n)
       !(we_transmit && we_acknowledge);
   endproperty
   assert property (never_transmitter_and_acknowledger)
       else $error("this device is both transmitting and acknowledging the same byte");