Día 8RAL, el golden model y el segundo capstone

// The register map of spec.md, written as a UVM register model.
//
// The table of the spec maps one to one onto this file, and that is the check
// worth doing out loud: four registers, six fields, four addresses. Nothing here
// knows that the bus is APB -- swap the adapter and the same model drives AHB.
//
// The access string of every field IS the specification. Get it wrong and the
// built-in sequences of the last file catch it; see the +MAL run of run.sh.

// 0x00 -- CTRL. EN is an ordinary bit. CLR is not: writing a 1 clears ACC and
// OVF, and the bit always reads back 0.
class ctrl_reg extends uvm_reg;
   `uvm_object_utils(ctrl_reg)

   rand uvm_reg_field EN;
   rand uvm_reg_field CLR;

   function new(string name = "ctrl_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   // configure(parent, size, lsb_pos, access, volatile, reset, has_reset,
   //           is_rand, individually_accessible)
   virtual function void build();
      EN = uvm_reg_field::type_id::create("EN");
      EN.configure(this, 1, 0, "RW", 0, 'h0, 1, 1, 0);

      // "WC" is the name UVM has for exactly this: the write clears the field,
      // the mirror drops to zero, and the read returns that zero. Modelling it as
      // "RW" is the classic mistake, and it is what +MAL does. "WOC" also passes,
      // for the wrong reason: any WO* access takes the field out of bit_bash and
      // out of do_check, so nobody looks at it. See the RAL unit slides.
      CLR = uvm_reg_field::type_id::create("CLR");
      CLR.configure(this, 1, 1, $test$plusargs("MAL") ? "RW" : "WC", 0, 'h0, 1, 1, 0);
   endfunction : build

endclass : ctrl_reg

// 0x04 -- SCRATCH. A plain RW register. That every write to it also adds to ACC
// is a side effect the model does not know about, and does not need to.
class scratch_reg extends uvm_reg;
   `uvm_object_utils(scratch_reg)

   rand uvm_reg_field VALUE;

   function new(string name = "scratch_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   virtual function void build();
      VALUE = uvm_reg_field::type_id::create("VALUE");
      VALUE.configure(this, 32, 0, "RW", 0, 'h0, 1, 1, 1);
   endfunction : build

endclass : scratch_reg

// 0x08 -- ACC. Read-only, and volatile: the DUT changes it behind the model's
// back, on every write to SCRATCH. See the comment on set_compare() below.
class acc_reg extends uvm_reg;
   `uvm_object_utils(acc_reg)

   uvm_reg_field VALUE;

   function new(string name = "acc_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   virtual function void build();
      VALUE = uvm_reg_field::type_id::create("VALUE");
      VALUE.configure(this, 32, 0, "RO", 1, 'h0, 1, 0, 1);
   endfunction : build

endclass : acc_reg

// 0x0C -- STATUS. Two read-only bits, and both are volatile for the same reason
// as ACC: EN is a copy of CTRL.EN, and OVF turns on when the accumulator
// overflows -- neither of them happens on a write to STATUS.
class status_reg extends uvm_reg;
   `uvm_object_utils(status_reg)

   uvm_reg_field EN;
   uvm_reg_field OVF;

   function new(string name = "status_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   virtual function void build();
      EN = uvm_reg_field::type_id::create("EN");
      EN.configure(this, 1, 0, "RO", 1, 'h0, 1, 0, 0);
      OVF = uvm_reg_field::type_id::create("OVF");
      OVF.configure(this, 1, 1, "RO", 1, 'h0, 1, 0, 0);
   endfunction : build

endclass : status_reg

class apb_reg_block extends uvm_reg_block;
   `uvm_object_utils(apb_reg_block)

   rand ctrl_reg    CTRL;
   rand scratch_reg SCRATCH;
   acc_reg          ACC;
   status_reg       STATUS;

   function new(string name = "apb_reg_block");
      super.new(name, UVM_NO_COVERAGE);
   endfunction : new

   // Not build_phase: a uvm_reg_block is a uvm_object, not a component. Nobody
   // calls this for you -- the test does, right after the create().
   virtual function void build();
      // create_map(name, base_addr, n_bytes, endian, byte_addressing)
      default_map = create_map("default_map", 'h0, 4, UVM_LITTLE_ENDIAN, 1);

      CTRL = ctrl_reg::type_id::create("CTRL");
      CTRL.configure(this, null, "");
      CTRL.build();
      default_map.add_reg(CTRL, CTRL_ADDR, "RW");

      SCRATCH = scratch_reg::type_id::create("SCRATCH");
      SCRATCH.configure(this, null, "");
      SCRATCH.build();
      default_map.add_reg(SCRATCH, SCRATCH_ADDR, "RW");

      ACC = acc_reg::type_id::create("ACC");
      ACC.configure(this, null, "");
      ACC.build();
      default_map.add_reg(ACC, ACC_ADDR, "RO");

      STATUS = status_reg::type_id::create("STATUS");
      STATUS.configure(this, null, "");
      STATUS.build();
      default_map.add_reg(STATUS, STATUS_ADDR, "RO");

      // The honest line of the whole unit. ACC and STATUS have an address, but
      // they are not registers: their value is produced by writes to OTHER
      // addresses. A register model predicts "what I wrote is what I will read",
      // and for these two that sentence is false, so mirror(UVM_CHECK) is turned
      // off on them. Reads still update the mirror -- a read is a prediction --
      // and the accumulator itself stays where it was in the capstone: in the
      // scoreboard, which is the thing that does know how to add.
      ACC.VALUE.set_compare(UVM_NO_CHECK);
      STATUS.EN.set_compare(UVM_NO_CHECK);
      STATUS.OVF.set_compare(UVM_NO_CHECK);

      lock_model();
   endfunction : build

endclass : apb_reg_block

// The only class in the unit that knows the bus exists. Twenty lines, and they
// are the whole reason the register model is portable: a generic uvm_reg_bus_op
// in, an apb_transaction out.
//
// Written once per protocol, not once per project. This is the file you would
// get with a commercial APB VIP.
class apb_reg_adapter extends uvm_reg_adapter;
   `uvm_object_utils(apb_reg_adapter)

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

   // Downstream: the model asks for a register access, this builds the bus item
   // the sequencer will hand to the driver.
   virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
      apb_transaction t = apb_transaction::type_id::create("t");
      t.write = (rw.kind == UVM_WRITE);
      t.addr  = rw.addr[7:0];
      t.wdata = rw.data[31:0];
      return t;
   endfunction : reg2bus

   // Upstream: a bus item comes back -- from the driver's response, or from the
   // monitor when prediction is explicit -- and this fills the generic operation
   // the model understands.
   //
   // PSLVERR is what makes status meaningful: an access to an unmapped address
   // comes back UVM_NOT_OK, and the write()/read() call reports it.
   virtual function void bus2reg(uvm_sequence_item bus_item, ref uvm_reg_bus_op rw);
      apb_transaction t;
      if (!$cast(t, bus_item)) `uvm_fatal("REG ADAPTER", "Not an apb_transaction")
      rw.kind   = t.write ? UVM_WRITE : UVM_READ;
      rw.addr   = t.addr;
      rw.data   = t.write ? t.wdata : t.rdata;
      rw.status = t.slverr ? UVM_NOT_OK : UVM_IS_OK;
   endfunction : bus2reg

endclass : apb_reg_adapter

// The structure, and nothing else. It is the capstone's active agent with three
// objects on top: the register model, the adapter, and the predictor.
virtual class ral_base_test extends uvm_test;
   `uvm_component_abstract_utils(ral_base_test)

   apb_agent        agent_h;
   apb_agent_config agent_cfg_h;

   apb_reg_block    model;
   apb_reg_adapter  adapter;

   // Parameterised by the BUS item, not by the register: the predictor's job is
   // to turn what the monitor saw into a prediction on the model.
   uvm_reg_predictor #(apb_transaction) predictor;

   function new(string name, uvm_component parent);
      super.new(name, parent);
   endfunction : new

   function void build_phase(uvm_phase phase);
      virtual apb_if bfm;

      if (!uvm_config_db#(virtual apb_if)::get(this, "", "bfm", bfm))
         `uvm_fatal("RAL BASE TEST", "Failed to get bfm")

      agent_cfg_h = new(.bfm(bfm), .is_active(UVM_ACTIVE));
      uvm_config_db#(apb_agent_config)::set(this, "agent_h*", "config", agent_cfg_h);
      agent_h = apb_agent::type_id::create("agent_h", this);

      // A uvm_reg_block is a uvm_object: create() does not call build(), the way
      // the component build_phase would. Forgetting this line leaves a model
      // with zero registers and an error that says nothing.
      model = apb_reg_block::type_id::create("model");
      model.build();

      adapter   = apb_reg_adapter::type_id::create("adapter");
      predictor = uvm_reg_predictor #(apb_transaction)::type_id::create("predictor", this);
   endfunction : build_phase

   function void connect_phase(uvm_phase phase);
      // The three lines that turn a model into a testbench component: which
      // sequencer carries the accesses, which adapter translates them, and where
      // the truth about the DUT comes from.
      model.default_map.set_sequencer(agent_h.sequencer_h, adapter);
      model.default_map.set_auto_predict(0);

      predictor.map     = model.default_map;
      predictor.adapter = adapter;
      agent_h.ap.connect(predictor.bus_in);
   endfunction : connect_phase

   // The reset the driver does at time 0 happens on the wire; the model has to
   // be told, or its mirror starts out as "unknown" instead of as the reset
   // values of the spec.
   task reset_model();
      model.reset();
   endtask : reset_model

   // The model printed back as the table it came from. One line per field, in
   // the order of the map, with the four things the spec says about it: where it
   // lives, how wide it is, and how it is accessed.
   //
   // It is worth doing once out loud, because a register model is the only
   // document in a project that is both the spec and the code -- and this is
   // the diff between the two.
   function void print_map();
      uvm_reg   regs[$];
      uvm_reg_field fields[$];
      model.get_registers(regs);
      foreach (regs[i]) begin
         fields.delete();   // get_fields() APPENDS: without this, register i
         regs[i].get_fields(fields);   // prints the fields of 0..i as well
         foreach (fields[j])
            `uvm_info("MAPA", $sformatf("%-8s @0x%02h  %-7s [%0d+:%0d]  %s",
                      regs[i].get_name(), regs[i].get_offset(model.default_map),
                      fields[j].get_name(), fields[j].get_lsb_pos(),
                      fields[j].get_n_bits(), fields[j].get_access()), UVM_NONE)
      end
   endfunction : print_map

   function void start_of_simulation_phase(uvm_phase phase);
      if ($test$plusargs("MAPA")) print_map();
   endfunction : start_of_simulation_phase

endclass : ral_base_test

// What the register layer buys, in ten lines of stimulus: not one PADDR, not one
// PWDATA, not one wait state. The same driver as the capstone is doing all of
// that underneath.
class ral_test extends ral_base_test;
   `uvm_component_utils(ral_test)

   function new(string name, uvm_component parent);
      super.new(name, parent);
   endfunction : new

   task run_phase(uvm_phase phase);
      uvm_status_e   status;
      uvm_reg_data_t data;

      phase.raise_objection(this);
      reset_model();

      // --- the frontdoor -----------------------------------------------------
      // write() puts the value on the wire through the sequencer. There is no
      // second argument for the address: the address is in the map.
      model.CTRL.write(status, 'h1);              // EN = 1
      model.CTRL.read(status, data);
      `uvm_info("RAL", $sformatf("CTRL read back 0x%08h (status %s)", data, status.name()),
                UVM_MEDIUM)

      // --- prediction --------------------------------------------------------
      // Nothing above updated the mirror by hand. The monitor saw the two
      // transfers, the predictor turned them into predictions, and the model
      // knows -- with set_auto_predict(0), which is the honest setting: what the
      // model believes comes from the BUS, not from what the test meant to send.
      if (model.CTRL.EN.get_mirrored_value() != 1)
         `uvm_error("RAL", "the predictor did not update CTRL.EN")
      `uvm_info("RAL", $sformatf("mirrored CTRL.EN = %0d, and nobody assigned it",
                model.CTRL.EN.get_mirrored_value()), UVM_MEDIUM)

      // --- mirror(UVM_CHECK): the read that checks itself --------------------
      model.SCRATCH.write(status, 'h1000_0000);
      model.SCRATCH.mirror(status, UVM_CHECK);

      // --- and the part RAL does not do --------------------------------------
      // ACC changed because of the write to SCRATCH, at another address. The
      // model never predicted that and never will: mirror(UVM_CHECK) is off on
      // ACC (see the reg block). The read still updates the mirror, so after
      // this line the model agrees with the DUT again.
      model.ACC.read(status, data);
      `uvm_info("RAL", $sformatf("ACC = 0x%08h -- predicted by the SCOREBOARD, not by the model",
                data), UVM_MEDIUM)
      if (data != 'h1000_0000)
         `uvm_error("RAL", $sformatf("ACC read 0x%08h, expected 0x10000000", data))

      // CLR is "WC": the write clears the accumulator, the mirror drops to zero
      // and the bit reads 0, so the mirror(UVM_CHECK) right after really compares
      // it -- which is the point of getting the access policy right.
      model.CTRL.write(status, 'h3);             // EN = 1, CLR = 1
      model.CTRL.mirror(status, UVM_CHECK);
      model.ACC.read(status, data);
      if (data != 0) `uvm_error("RAL", $sformatf("after CLR, ACC = 0x%08h", data))

      // STATUS.EN is a copy of CTRL.EN, and it got there through a transfer to a
      // DIFFERENT address. Without the set_compare(UVM_NO_CHECK) of the reg
      // block this line fails -- and the failure would be the model's fault, not
      // the DUT's. Knowing which of the two is lying is the whole skill.
      //
      // The two UVM_WARNING it prints (UVM/FLD/GET_MIRRORED_VAL/VOL) are the
      // library saying the same thing on its own: a volatile field's mirror is
      // not evidence. They are the expected output of this line, not noise.
      `uvm_info("RAL", "the two VOL warnings below are the point, not a problem",
                UVM_MEDIUM)
      model.STATUS.mirror(status, UVM_CHECK);

      // --- the status that only a bus can give -------------------------------
      // Every call returns a status, and it is not decoration: PSLVERR comes back
      // through bus2reg as UVM_NOT_OK. A pure software model could not tell you
      // that the slave refused the access -- it is the one thing in this file
      // that could only come from the wire.
      if (status != UVM_IS_OK)
         `uvm_error("RAL", $sformatf("the mapped accesses came back %s", status.name()))

      phase.drop_objection(this);
   endtask : run_phase

endclass : ral_test

// The argument for RAL that survives a code review: tests you did not write.
//
// Both sequences below ship with uvm-core. They read the register model -- the
// addresses, the field positions, the access strings -- and generate the
// stimulus and the checks from it. Nothing here is specific to this DUT.
//
//   uvm_reg_hw_reset_seq   reads every register after reset and compares it
//                          against the reset value declared in configure()
//   uvm_reg_bit_bash_seq   writes and reads back every writable bit of every
//                          register, one at a time, in both directions
//
// Run it with +MAL and the register model declares CTRL.CLR as "RW" instead of
// "WC" -- one wrong word in one string. bit_bash catches it without anyone
// writing a test for CTRL.
class builtin_test extends ral_base_test;
   `uvm_component_utils(builtin_test)

   function new(string name, uvm_component parent);
      super.new(name, parent);
   endfunction : new

   task run_phase(uvm_phase phase);
      uvm_reg_hw_reset_seq rst_seq;
      uvm_reg_bit_bash_seq bash_seq;

      phase.raise_objection(this);
      reset_model();

      rst_seq = uvm_reg_hw_reset_seq::type_id::create("rst_seq");
      rst_seq.model = model;
      rst_seq.start(null);

      bash_seq = uvm_reg_bit_bash_seq::type_id::create("bash_seq");
      bash_seq.model = model;
      bash_seq.start(null);

      phase.drop_objection(this);
   endtask : run_phase

endclass : builtin_test

// The register map of spec.md, written as a UVM register model.
//
// The table of the spec maps one to one onto this file, and that is the check
// worth doing out loud: four registers, six fields, four addresses. Nothing here
// knows that the bus is APB -- swap the adapter and the same model drives AHB.
//
// The access string of every field IS the specification. Get it wrong and the
// built-in sequences of the last file catch it; see the +MAL run of run.sh.

// 0x00 -- CTRL. EN is an ordinary bit. CLR is not: writing a 1 clears ACC and
// OVF, and the bit always reads back 0.
class ctrl_reg extends uvm_reg;
   `uvm_object_utils(ctrl_reg)

   rand uvm_reg_field EN;
   rand uvm_reg_field CLR;

   function new(string name = "ctrl_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   // configure(parent, size, lsb_pos, access, volatile, reset, has_reset,
   //           is_rand, individually_accessible)
   virtual function void build();
      EN = uvm_reg_field::type_id::create("EN");
      EN.configure(this, 1, 0, "RW", 0, 'h0, 1, 1, 0);

      // "WC" is the name UVM has for exactly this: the write clears the field,
      // the mirror drops to zero, and the read returns that zero. Modelling it as
      // "RW" is the classic mistake, and it is what +MAL does. "WOC" also passes,
      // for the wrong reason: any WO* access takes the field out of bit_bash and
      // out of do_check, so nobody looks at it. See the RAL unit slides.
      CLR = uvm_reg_field::type_id::create("CLR");
      CLR.configure(this, 1, 1, $test$plusargs("MAL") ? "RW" : "WC", 0, 'h0, 1, 1, 0);
   endfunction : build

endclass : ctrl_reg

// 0x04 -- SCRATCH. A plain RW register. That every write to it also adds to ACC
// is a side effect the model does not know about, and does not need to.
class scratch_reg extends uvm_reg;
   `uvm_object_utils(scratch_reg)

   rand uvm_reg_field VALUE;

   function new(string name = "scratch_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   virtual function void build();
      VALUE = uvm_reg_field::type_id::create("VALUE");
      VALUE.configure(this, 32, 0, "RW", 0, 'h0, 1, 1, 1);
   endfunction : build

endclass : scratch_reg

// 0x08 -- ACC. Read-only, and volatile: the DUT changes it behind the model's
// back, on every write to SCRATCH. See the comment on set_compare() below.
class acc_reg extends uvm_reg;
   `uvm_object_utils(acc_reg)

   uvm_reg_field VALUE;

   function new(string name = "acc_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   virtual function void build();
      VALUE = uvm_reg_field::type_id::create("VALUE");
      VALUE.configure(this, 32, 0, "RO", 1, 'h0, 1, 0, 1);
   endfunction : build

endclass : acc_reg

// 0x0C -- STATUS. Two read-only bits, and both are volatile for the same reason
// as ACC: EN is a copy of CTRL.EN, and OVF turns on when the accumulator
// overflows -- neither of them happens on a write to STATUS.
class status_reg extends uvm_reg;
   `uvm_object_utils(status_reg)

   uvm_reg_field EN;
   uvm_reg_field OVF;

   function new(string name = "status_reg");
      super.new(name, 32, UVM_NO_COVERAGE);
   endfunction : new

   virtual function void build();
      EN = uvm_reg_field::type_id::create("EN");
      EN.configure(this, 1, 0, "RO", 1, 'h0, 1, 0, 0);
      OVF = uvm_reg_field::type_id::create("OVF");
      OVF.configure(this, 1, 1, "RO", 1, 'h0, 1, 0, 0);
   endfunction : build

endclass : status_reg

class apb_reg_block extends uvm_reg_block;
   `uvm_object_utils(apb_reg_block)

   rand ctrl_reg    CTRL;
   rand scratch_reg SCRATCH;
   acc_reg          ACC;
   status_reg       STATUS;

   function new(string name = "apb_reg_block");
      super.new(name, UVM_NO_COVERAGE);
   endfunction : new

   // Not build_phase: a uvm_reg_block is a uvm_object, not a component. Nobody
   // calls this for you -- the test does, right after the create().
   virtual function void build();
      // create_map(name, base_addr, n_bytes, endian, byte_addressing)
      default_map = create_map("default_map", 'h0, 4, UVM_LITTLE_ENDIAN, 1);

      CTRL = ctrl_reg::type_id::create("CTRL");
      CTRL.configure(this, null, "");
      CTRL.build();
      default_map.add_reg(CTRL, CTRL_ADDR, "RW");

      SCRATCH = scratch_reg::type_id::create("SCRATCH");
      SCRATCH.configure(this, null, "");
      SCRATCH.build();
      default_map.add_reg(SCRATCH, SCRATCH_ADDR, "RW");

      ACC = acc_reg::type_id::create("ACC");
      ACC.configure(this, null, "");
      ACC.build();
      default_map.add_reg(ACC, ACC_ADDR, "RO");

      STATUS = status_reg::type_id::create("STATUS");
      STATUS.configure(this, null, "");
      STATUS.build();
      default_map.add_reg(STATUS, STATUS_ADDR, "RO");

      // The honest line of the whole unit. ACC and STATUS have an address, but
      // they are not registers: their value is produced by writes to OTHER
      // addresses. A register model predicts "what I wrote is what I will read",
      // and for these two that sentence is false, so mirror(UVM_CHECK) is turned
      // off on them. Reads still update the mirror -- a read is a prediction --
      // and the accumulator itself stays where it was in the capstone: in the
      // scoreboard, which is the thing that does know how to add.
      ACC.VALUE.set_compare(UVM_NO_CHECK);
      STATUS.EN.set_compare(UVM_NO_CHECK);
      STATUS.OVF.set_compare(UVM_NO_CHECK);

      lock_model();
   endfunction : build

endclass : apb_reg_block

package vtalu_pkg;
   import uvm_pkg::*;
   `include "uvm_macros.svh"

   // The reference model lives in vtalu_golden.c and is called from here. This
   // is all that is needed on the SystemVerilog side: one declaration per
   // function, with the LRM types that cross the boundary.
   //
   //   input int  -> int          output int -> int *
   //   function   -> returns      task       -> may consume time (not here)
   //
   // The name after "DPI-C" is the symbol the linker looks for, so it has to
   // match the one in the .c letter by letter.
   import "DPI-C" function int  vtalu_golden(input int op, input int a,
                                             input int b, output int ovf);
   import "DPI-C" function void vtalu_golden_bug(input int on);

   typedef enum bit [2:0] {
      no_op  = 3'b000,
      add_op = 3'b001,
      sub_op = 3'b010,
      and_op = 3'b011,
      xor_op = 3'b100,
      mul_op = 3'b101,
      rst_op = 3'b111
   } operation_t;

   // Configs first: the driver and the monitors use them.
   `include "env_config.svh"
   `include "vtalu_agent_config.svh"

   `include "command_transaction.svh"
   `include "add_transaction.svh"
   `include "result_transaction.svh"

   // The sequencer is not extended: it is parameterized and given a name.
   // It goes AFTER command_transaction and BEFORE the driver and the agent.
   typedef uvm_sequencer #(command_transaction) sequencer;

   // Sequences are uvm_object: they go before the tests that start them.
   `include "reset_sequence.svh"
   `include "random_sequence.svh"
   `include "maxmult_sequence.svh"
   `include "fibonacci_sequence.svh"
   `include "full_sequence.svh"

   `include "coverage.svh"
   `include "scoreboard.svh"
   `include "driver.svh"
   `include "command_monitor.svh"
   `include "result_monitor.svh"

   `include "vtalu_agent.svh"
   `include "env.svh"

   `include "base_test.svh"
   `include "full_test.svh"
   `include "fibonacci_test.svh"
   `include "add_test.svh"
   `include "default_seq_test.svh"
   `include "no_objection_test.svh"

endpackage : vtalu_pkg

/* The VTALU reference model, in C. This is the whole point of the example:
 * the scoreboard does NOT predict in SystemVerilog -- it asks this file.
 *
 * Why it matters: for a DUT with real arithmetic -- a DSP, a codec, a crypto
 * engine -- the reference model already exists in C, written by the algorithm
 * team, and it is the thing the specification was signed off against.
 * Rewriting it in SystemVerilog means maintaining two models and debugging the
 * difference between them, which is not verification.
 *
 * Verilator compiles to C++, so this file is linked straight into the
 * simulation: no IPC, no socket, no FLI. One `import "DPI-C"` on the
 * SystemVerilog side (vtalu_pkg.sv) and one function call on this side.
 *
 * The `extern "C"` guard is not decoration: Verilator hands user sources to
 * the C++ compiler, and without it the symbol gets mangled and the link fails
 * with an undefined reference that names a function that is obviously there.
 */
#include <svdpi.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Same opcodes as operation_t in vtalu_pkg.sv. Keeping the two in sync by hand
 * is the tax of DPI, and it is the first thing to check when every comparison
 * fails at once. */
enum { NO_OP = 0, ADD_OP = 1, SUB_OP = 2, AND_OP = 3, XOR_OP = 4, MUL_OP = 5, RST_OP = 7 };

/* A deliberate mutation, switched on with +GOLDEN_BUG. A scoreboard that never
 * saw an error is not tested: this is what proves the DPI path is actually
 * wired, and it is the same idea as the +BUG=1 of the day 7 capstone. */
static int mutar = 0;

void vtalu_golden_bug(int on) { mutar = on; }

/* op, a and b arrive as SystemVerilog `int` (32-bit signed). The result goes
 * back as the return value and the borrow through a pointer, which is how an
 * `output int` argument crosses the boundary. */
int vtalu_golden(int op, int a, int b, int *ovf) {
   int r;

   a &= 0xff;
   b &= 0xff;
   *ovf = 0;

   switch (op) {
      case ADD_OP: r = a + b; break;
      /* 8-bit operands into a 16-bit result: a - b wraps, and the borrow is
       * the second half of the answer the scoreboard has to check. */
      case SUB_OP: r = a - b; *ovf = (a < b); break;
      case AND_OP: r = a & b; break;
      case XOR_OP: r = a ^ b; break;
      case MUL_OP: r = mutar ? (a * b) & 0xff : a * b; break;
      default:     r = 0; break;   /* no_op and rst_op do not answer */
   }

   return r & 0xffff;
}

#ifdef __cplusplus
}
#endif

class scoreboard extends uvm_subscriber #(result_transaction);
   `uvm_component_utils(scoreboard);

   uvm_tlm_analysis_fifo #(command_transaction) cmd_f;

   function new(string name, uvm_component parent);
      super.new(name, parent);
   endfunction : new

   function void build_phase(uvm_phase phase);
      cmd_f = new("cmd_f", this);
   endfunction : build_phase

   // The ONLY difference with the sequences scoreboard, and it is the whole
   // section: there is no case with the arithmetic of the spec here. The
   // prediction is asked of the C reference model, the one that signed it.
   //
   // What does not change: the monitor, the analysis port, the FIFO, the
   // do_compare and the uvm_error. The golden model replaces SIX LINES -- the
   // ones that predict -- and no other piece of the testbench finds out.
   function result_transaction predict_result(command_transaction cmd);
      result_transaction predicted;
      int                ovf;

      predicted = result_transaction::type_id::create("predicted");

      predicted.result = vtalu_golden(int'(cmd.op), int'(cmd.A), int'(cmd.B), ovf);
      predicted.ovf    = (ovf != 0);

      return predicted;

   endfunction : predict_result

   function void write(result_transaction t);
      string data_str;
      command_transaction cmd;
      result_transaction predicted;

      do
      if (!cmd_f.try_get(cmd))
         `uvm_fatal("SELF CHECKER", "Missing command in self checker")
      while ((cmd.op == no_op) || (cmd.op == rst_op));

      predicted = predict_result(cmd);

      data_str = {
         cmd.convert2string(),
         " ==>  Actual ",
         t.convert2string(),
         "/Predicted ",
         predicted.convert2string()
      };

      if (!predicted.compare(t)) `uvm_error("SELF CHECKER", {"FAIL: ", data_str})
      else `uvm_info("SELF CHECKER", {"PASS: ", data_str}, UVM_HIGH)

   endfunction : write
endclass : scoreboard