Contracts in classes

Three ways to declare the methods a caller needs

Lesson 4.4 showed the core rule. A call through a handle runs the method of the object, if the method is virtual. SystemVerilog gives you three ways to build on that rule, and they differ in what they force on the receiver.

An abstract class is a class declared virtual class. It cannot be constructed, and it may hold pure virtual methods: declarations with no body. Our sink_base has one pure method, kind(), plus a default describe() and a plain plain().

An interface class contains only pure virtual methods, types and parameters. A class lists it after implements. A class extends at most one class but may implement any number of interface classes, which is why logger can be a sink_base, a put_if and a reset_if at once.

A caller that holds only an interface handle

The example builds the smallest possible port by hand. mini_port has one member, put_if #(T) target, and a put task that calls target.put(t). It has never heard of loggers or counters.

1. producer: port.put(#1) at 0 ns

   The producer calls its port. The port is an ordinary object, so this is an ordinary task call.

2. port: target.put(#1)

   The handle type is put_if; the object is a logger. Dynamic dispatch runs logger::put.

3. logger.put: stored #1 at 5 ns

   The logger waits 5 ns and stores the packet. The producer's thread is inside this task for all 5 ns.

4. producer: put(#1) returned at 5 ns

   Control comes back the way it went. The packet travelled with the call, from caller to receiver.

Then the test connects the counter instead and sends #2. The counter has no base class, yet it receives the packet through the same producer code. Trace lines 4 to 6 show it in the same time step, because the counter's put does not wait.

One logger object can be seen through three handle types. Through sink_base the example calls kind() and describe(), and through reset_if it calls on_reset(). Each handle shows only its own methods: r.put(t) does not compile, even though the object has a put.

What breaks, and when you find out

These declarations move mistakes to compile time where they can. These are the errors this tool reports for the three common slips.

The silent case is in the example on purpose. plain() is not virtual, so s.plain() prints sink_base.plain although the object is a logger with its own plain(). An interface class cannot have this bug: every method in it is pure virtual, so every implementation is reached by dispatch.

Going back from an interface handle to a class takes a checked cast. $cast(back, s) succeeds only when the object really is a logger, and returns 0 otherwise. Use it rarely: a caller that casts to the concrete class depends on that class again.

Why UVM is built on this

A UVM port must call a method in a component that someone else will write, perhaps years later. That is the producer problem at library scale, and UVM solves it with two techniques at once.

The port side is your mini_port, with uvm_tlm_if_base in the role of put_if. It is an abstract class whose methods have bodies that report UVM TLM interface task not implemented, rather than an interface class.

The imp side is different. The imp class takes the component's type as a parameter, uvm_blocking_put_imp #(pkt, consumer), and calls m_imp.put(t) on a consumer handle. The component needs no special base class, and a missing put is a compile error in the imp. That adapter is what lets any uvm_component receive TLM calls.

Try it

Lines 1 to 6 are two trips through the same producer and port, first to a logger that takes 5 ns, then to a counter that takes none. Line 7 shows dispatch at work for kind(), a default for describe(), and the silent non-virtual trap for plain().

Try it: delete the put task from counter and rebuild to see the missing-implementation error. Then make plain() virtual in sink_base and watch line 7 change to logger.plain.

Check yourself

interface class put_if;
  pure virtual task put(int x);
endclass

virtual class sink_base;
  pure virtual function string kind();
  function string plain(); return "base"; endfunction
endclass

class logger extends sink_base implements put_if;
  int total;
  virtual task put(int x); total += x; endtask
  virtual function string kind(); return "logger"; endfunction
  function string plain(); return "logger"; endfunction
endclass

// Implements put by passing twice the value on to another put_if.
class doubler implements put_if;
  put_if next;
  virtual task put(int x); next.put(2 * x); endtask
endclass

module tb;
  initial begin
    logger    lg = new;
    doubler   d  = new;
    put_if    p;
    sink_base s  = lg;
    d.next = lg;
    p = d;
    p.put(3);
    p.put(4);
    lg.put(1);
    $display("%s %s %0d", s.kind(), s.plain(), lg.total);
  end
endmodule

function void accept(pkt t); endfunction

virtual function void accept(pkt t); dropped++; endfunction

virtual function void accept(pkt t); endfunction

pure virtual function void accept(pkt t);