The Sequence Item — Fields, Constraints and Direction

   txn = seq.next();          // we decide: write 0xA5 to register 3
   driver.send(txn);          // the driver puts that on the bus, and writes ack back
   scoreboard.expect(txn);    // ... the SAME handle
   observed = monitor.get();
   scoreboard.compare(observed);

      constraint c_addr_legal {
         addr inside {[7'h08:7'h77]};
      }

   // -----------------------------------------------------------------------------
   // i2c_seq_item.sv
   // TWO transaction classes, because there are two kinds of object.
   //
   // NOT EXECUTED -- see i2c_if.sv.
   //
   // Chapter 20.3 made the argument with packed structs: an INTENT exists before the bus
   // and contains nothing measured; an OBSERVATION exists only after the bus and contains
   // nothing chosen. The reason to carry that distinction into a class hierarchy rather
   // than quietly merge it is that a single class makes this line natural to write:
   //
   //     driver.send(txn);  scoreboard.expect(txn);     // the SAME handle
   //
   // and that comparison holds with the DUT removed. Two classes make it a type error.
   //
   // A UVM-specific hazard that the struct version did not have: the two classes must NOT
   // be related by inheritance. `i2c_txn extends i2c_seq_item` would compile, would let an
   // observation be passed anywhere an intent is expected, and -- because the factory and
   // `$cast` both accept a derived handle for a base type -- would put the circular
   // comparison back exactly where the type split was meant to remove it.
   // -----------------------------------------------------------------------------

   // ============================================================================
   // WHAT WAS ASKED FOR. Constructed by a sequence; consumed by a driver.
   // ============================================================================
   class i2c_seq_item extends uvm_sequence_item;

      // Every field is a CHOICE. Randomised because the environment picks them, and every
      // protocol field is `rand` deliberately: a non-rand field in a sequence item is
      // silently never randomised, so a constrained-random run quietly exercises one value
      // for the lifetime of the project.
      rand bit [6:0] addr;
      rand bit       read;
      rand int unsigned n_bytes;
      rand bit [7:0] data [];
      rand bit       restart_first;   // open with a repeated START rather than a START
      rand bit       hold_bus;        // decline to send the trailing STOP

      // Abandon the transfer after this many BITS of the current byte, then frame a STOP.
      // Zero means complete it normally.
      //
      // This field is here rather than in a derived error item, and the reason is worth
      // stating: abandoning a transfer is something a REAL CONTROLLER DOES -- a driver
      // whose software timed out, a master that lost arbitration. It is legal controller
      // behaviour producing an illegal-looking bus event, so it belongs on the ordinary
      // item. Violations a controller CANNOT produce -- SDA moving while SCL is high
      // mid-byte, a line held down forever -- are not driver modes at all: they are a third
      // participant on the bus, which is i2c_error_injector.
      rand int unsigned abort_after_bits;

      // There is NO acknowledge field, and its absence is the design. Whether the target
      // acknowledges is the TARGET's decision, taken from a contract this object knows
      // nothing about. A sequence cannot choose it, so an intent cannot carry it -- and a
      // single merged class would have to either misreport every NACK or ignore
      // acknowledgement entirely. Chapter 20.3's T8 is the concrete case.

      `uvm_object_utils_begin(i2c_seq_item)
         `uvm_field_int(addr,          UVM_ALL_ON)
         `uvm_field_int(read,          UVM_ALL_ON)
         `uvm_field_int(n_bytes,       UVM_ALL_ON)
         `uvm_field_array_int(data,    UVM_ALL_ON)
         `uvm_field_int(restart_first, UVM_ALL_ON)
         `uvm_field_int(hold_bus,      UVM_ALL_ON)
         `uvm_field_int(abort_after_bits, UVM_ALL_ON)
      `uvm_object_utils_end

      function new(string name = "i2c_seq_item");
         super.new(name);
      endfunction

      // Keep the payload and its length in step. Without this the array can be one size
      // and `n_bytes` another, and the driver then either sends garbage or walks off the
      // end -- a defect that shows up as an intermittent, length-dependent failure.
      constraint c_len {
         n_bytes inside {[1:8]};
         data.size() == n_bytes;
      }

      // Complete transfers by default. An error has to be asked for explicitly, or random
      // traffic quietly becomes mostly-illegal traffic and every failure is the
      // environment's fault.
      constraint c_no_abort_by_default { soft abort_after_bits == 0; }

      // A 7-bit address space has reserved regions (0x00 general call, 0x01-0x07 and
      // 0x78-0x7F). Excluded by default so that ordinary random traffic is legal; the
      // error sequences in Chapter 21.10 override this deliberately, which is why it is a
      // named constraint rather than a hard-coded range.
      constraint c_addr_legal {
         addr inside {[7'h08:7'h77]};
      }

   endclass

   // ============================================================================
   // WHAT THE WIRE CARRIED. Produced by a monitor; consumed by a scoreboard.
   // Deliberately NOT derived from i2c_seq_item -- see the header.
   // ============================================================================
   class i2c_txn extends uvm_sequence_item;

      // Measured, every one of them.
      bit [6:0] addr;
      bit       read;
      bit       addr_acked;          // <-- no intent counterpart: the target decided this
      bit [7:0] data [];
      bit       acks [];             // <-- nor this, one per data byte
      bit       began_with_restart;  // the framing that actually opened the transfer
      bit       ended_by_restart;    // <-- no intent counterpart for THIS transfer: the
      bit       ended_by_stop;       //     NEXT transfer's opening decides it
      bit       truncated;           // framing arrived mid-byte; those bits are not data

      `uvm_object_utils_begin(i2c_txn)
         `uvm_field_int(addr,               UVM_ALL_ON)
         `uvm_field_int(read,               UVM_ALL_ON)
         `uvm_field_int(addr_acked,         UVM_ALL_ON)
         `uvm_field_array_int(data,         UVM_ALL_ON)
         `uvm_field_array_int(acks,         UVM_ALL_ON)
         `uvm_field_int(began_with_restart, UVM_ALL_ON)
         `uvm_field_int(ended_by_restart,   UVM_ALL_ON)
         `uvm_field_int(ended_by_stop,      UVM_ALL_ON)
         `uvm_field_int(truncated,          UVM_ALL_ON)
      `uvm_object_utils_end

      function new(string name = "i2c_txn");
         super.new(name);
      endfunction

      // The difference between an intent and an observation, field by field -- and it
      // returns a MASK rather than a bit, because collapsing a comparison to pass-or-fail
      // discards the only information that makes a failure diagnosable.
      //
      // `defined` is low for a READ, and refusing is the correct answer: a read's payload
      // came from the TARGET, so no field of the intent predicts it. Comparing them would
      // not be a weak check, it would be a comparison of two unrelated quantities that
      // happens to be expressible. A read's payload has to be checked against the device
      // contract, which is the predictor's job and not this function's.
      function void diff(i2c_seq_item w,
                         output bit defined,
                         output bit d_addr, d_dir, d_nbytes, d_data, d_framing);
         defined = 1'b0;
         d_addr = 1'b0; d_dir = 1'b0; d_nbytes = 1'b0; d_data = 1'b0; d_framing = 1'b0;
         if (w == null) return;
         if (w.read) return;                       // UNDEFINED for a read -- see above
         defined   = 1'b1;
         d_addr    = (w.addr != addr);
         d_dir     = (w.read != read);
         d_nbytes  = (w.n_bytes != data.size());
         d_framing = (w.restart_first != began_with_restart);
         if (!d_nbytes)
            foreach (data[i]) if (w.data[i] != data[i]) d_data = 1'b1;
      endfunction

      // Address and direction compare in EVERY direction, so a read whose payload cannot
      // be compared still has two fields that can be. Losing them because the payload
      // check is impossible would give up more than the situation requires.
      function bit framing_only_differs(i2c_seq_item w);
         if (w == null) return 1'b0;
         return (w.addr != addr) || (w.read != read);
      endfunction

   endclass