Handles, objects and constructors

A class describes objects

A class is a type that bundles data with the code that works on it. Its variables are called properties, and its functions and tasks are called methods.

A transaction class for the read scoreboard might hold an ID, an address and the expected data, plus methods to print and compare them. Each transaction in the test is then one object of that class.

Declaring a class creates no objects. You create each object while the test runs, as many as the traffic needs.

A handle names an object

A variable of class type is a handle: a reference to an object, not the object itself. axi_txn tr; declares a handle whose starting value is null, which means it refers to nothing.

tr = new(5, 'h40); allocates an object, runs its constructor with those arguments, and makes tr refer to it. Only then does tr.id have somewhere to live.

Using a null handle is a run-time error. Reading or writing tr.id while tr is null stops the simulation with a message such as Null pointer dereferenced, so test tr == null wherever a handle might not have been set yet.

The constructor sets the starting state

The constructor is a function named new with no return type. It runs once for each object, right after allocation, and its job is to leave the object in a valid state. Unlike other methods, new cannot be declared virtual.

Give it arguments for the values every object must have, with defaults where a sensible default exists. Inside it, this.id names the property when an argument has the same name, as in this.id = id;.

A class without a constructor still gets one. That implicit constructor leaves every property at its declared initial value, or at the default for its type: 0 for int, x for logic, null for a handle.

Assignment copies the handle

Assigning one handle to another copies the reference and nothing else. After b = a;, both names refer to the same object, so a change made through b is visible through a.

1. a = new(7, 'h40);

   One object exists, and a refers to it.

   a	object 1 (id 7)

2. b = a;

   No new object. Both handles refer to object 1.

   a	object 1 (id 7)
   b	object 1

3. b.id = 9;

   The change goes to object 1, so a.id reads 9 as well.

   a	object 1 (id 9)
   b	object 1

4. b = new(3, 'h80);

   A second object. Now the handles refer to different objects.

   a	object 1 (id 9)
   b	object 2 (id 3)

5. a = null;

   No handle refers to object 1 any more, so the simulator frees it automatically.

   a	null
   b	object 2 (id 3)

The == operator on handles asks whether they refer to the same object. Two separate objects with identical properties still compare unequal; comparing their contents needs a method of your own.

Handles in queues and arrays

A queue such as axi_txn exp_q [$]; holds handles, not objects. Pushing tr stores a second reference to the object tr refers to, and the queue does not get a copy of its own.

So a change made through tr after the push is visible through the queue entry, and a change made through the entry is visible through tr. The scoreboard and the generator are sharing one object.

An array of handles starts with every element null, and you must create an object for each element before using it. A mailbox, covered in Module 3, also passes handles in exactly this way.

One object per transaction

The generator in the opening story called new once, outside its loop. Every push stored another handle to that single object, and the queue ended up with four names for one transaction.

tr = new();
for (int i = 0; i < 4; i++) begin
  tr.id = i;
  exp_q.push_back(tr);   // same object every time
end

for (int i = 0; i < 4; i++) begin
  tr = new(i);
  exp_q.push_back(tr);   // a new object each time
end

The same rule applies to everything that hands a transaction to someone else, such as a mailbox put or a scoreboard write. Once you have handed over a handle, build a new object for the next transaction instead of editing the old one.

Try it

Changing b.id changed a.id, because both handles referred to one object. Two separate objects with the same field values still compare unequal, because == compares handles.

The first queue holds four handles to one object, so it shows the last ID four times. Add tr.id = 99; after the second loop and predict which queue changes.

Check yourself

class c;
  int v;
  function new(int v = 1);
    this.v = v;
  endfunction
endclass

module tb;
  c x, y;
  initial begin
    x = new();
    y = x;
    x = new(5);
    y.v++;
    $display("%0d %0d", x.v, y.v);
  end
endmodule

for (int i = 0; i < 4; i++) begin
  tr = new(i);
  exp_q.push_back(tr);
end

for (int i = 0; i < 4; i++) begin
  tr = new();
  tr.id = i;
  exp_q.push_back(tr);
end

for (int i = 0; i < 4; i++) begin
  exp_q.push_back(null);
  exp_q[i] = new(i);
end

tr = new();
for (int i = 0; i < 4; i++) begin
  tr.id = i;
  exp_q.push_back(tr);
end

Practice

• Construct a valid packet Implement · Easy