Verify This! — Introduction to UVM

## How to use this course

#### *Especially if you are taking it on your own*

- **What you need to know first:** Verilog or VHDL, and having simulated
 something. Object-oriented programming is **not** required — day 2 is exactly
 that. The only thing the course takes for granted is **SystemVerilog**: if you
 come from VHDL or Verilog-2001, half an hour with
 **`docs/systemverilog-para-el-que-viene-de-vhdl.md`** (in Spanish) before starting
- It is **seven days of class**, of 4 to 5 and a quarter hours — **≈ 31 h**, and each
 agenda carries its own. Plus an **optional day 8**, after the wrap-up. On your own,
 count double: half of it goes into running the examples, and that is the half that teaches
- <kbd>s</kbd> opens the **presenter notes** in another window ·
 <kbd>n</kbd> shows them down here, without leaving the page. That is where what the
 instructor would say out loud lives: the classic trap, the reason behind the number, the
 mistake everybody makes the first time. **Do not skip them**
- Every day closes with a **review** of clickable options and with a
 **self-checking exercise**: `cd code/ejercicios/d1 && bash run.sh`. The names of
 the other eighteen are in `code/ejercicios/README.md`

Note:
If you are teaching the course, these two slides are skipped with the 1 key.
They are here because most people who open this will not have an
instructor alongside, and without the presenter notes half the material gets lost
— and that half is also the hardest one to reconstruct by reading the code.

---

## How to use this course

#### *Running it, moving around it, and where to look when something breaks*

- **Run the examples**: `make u4/tests` runs one, `make u4` the whole unit. A verification
 course that is only read is worth nothing. A UVM example takes **a minute and a half the
 first time and fifteen seconds the second**, if you have `ccache` installed — and if you
 do not have Linux, the short road is GitHub Codespaces, which already ships with it
- <kbd>0</kbd>–<kbd>8</kbd> jump to the cover and to each day ·
 <kbd>i</kbd> opens the index · <kbd>Esc</kbd> shows the whole deck · and the
 corner ribbon unfolds the cheat sheet of the day
- **If you are on your own, read the book:** `en/libro/day1.html` is this same course
 straight through, with the notes already inside the text. Keep the deck alongside for
 the reviews
- **When something does not work, go to the end:** the appendices *The debug toolbox*
 —what to look at for each symptom— and *The 21 silent traps* —everything that
 compiles, runs and lies—. Those are the two slides to print

Note:
The last two are the ones that pay off most for someone studying alone, and the
ones nobody reads until they are already stuck: the book carries these same notes
inside the text, and the appendices are written as a table of symptoms, to look
things up in rather than to read straight through.

## Agenda

#### *Day 1 · ≈ 4 h · units 1 and 2*

**Unit 1 · Why we verify**

- Trends
- What UVM is
- The VTALU spec
- The verification plan

**Unit 2 · The testbench without UVM**

- The conventional testbench
- Functional coverage
- Interfaces and BFM · the `clocking block`

**Two exercises**, and the second one is solved with the wave viewer

- **And closing the day**, going back to the first slide

**By the end of the day you can:**

- **Write** a five-column verification plan for a DUT you have not seen before
- **Prove** that your scoreboard checks something: put a bug into the DUT on
  purpose and watch it fail
- **Read** the number a `covergroup` gives, say which row of the plan is
  missing, and what to look at first when it reads 0 %
- **Explain** which race a `clocking block` avoids — and why they are optional
  anyway

Note:
The four verbs below are the contract of the day, and it is worth reading them
out loud before starting: on video they are the ten seconds in which someone
decides whether this is the one they were looking for. Three are rows 2, 4 and
5 of the closing self-assessment, brought to the front; the one about the bug
on purpose is the practice that runs through the whole course, from `make
mutante` today to `+BUG=1` in the capstone. Whoever can answer them at the end
of the day does not need to watch anything else.
And an honest warning for whoever comes from VHDL or from Verilog-2001, which is
the declared audience: day 2 levels the OOP, but **nobody levels SystemVerilog**,
and today `interface`, `logic`, `enum`, `package`, `covergroup`, `clocking` and an
`assert property` all show up. It is all on one page in
**`docs/systemverilog-para-el-que-viene-de-vhdl.md`** (in Spanish): half an hour
before starting, and day 1 stops having two steps at once.

## Six out of seven

#### *And the bug that reached silicon passed a green regression*

![How IC/ASIC projects end in 2024: 14 % get first silicon right and 75 % run late](../res/trends/en/resultado.svg)

- **14 %** of projects get first silicon right. Six out of seven go back to
  the fab, and it is the worst figure in twenty years of the survey
- Every functional bug that reached silicon went through a testbench first.
  That testbench ran, finished, and **said everything was fine**
- Nobody tapes out with a `FAILED` in the log. You tape out with a `PASS`
- Today has a single question: **how do you know you verified?** And *"I ran
  a lot of tests"* is not an answer

Note:
It is the first content slide of the course on purpose: before explaining what
UVM is and before any other chart, a question the student cannot answer yet. The
number is from the Wilson Research Group 2024 survey and it is not an
impression: only 14 % come out right on first silicon, so six out of seven need
at least one respin, and it is the worst figure in twenty years of the survey.
Asking who has done a tape-out and how it went hooks better than the chart. If
they ask where the data comes from: `res/trends/data.json`, and the figures are
regenerated with `make figs`.
The honesty worth saying out loud: not every respin is functional —there are
timing ones, analog ones, a spec that changed late—. But the one that is went
through a regression that said `PASS`, because had it said `FAILED` it would
not have been fabricated. That is the enemy of the day, and it is not the
verification engineer nor their testbench: it is a `PASS` nobody knew the
meaning of.
The question in the last bullet is thrown to the group and **not** answered.
The answers that will come are *"100 % coverage"*, *"I ran a thousand
operations"* and *"nothing failed"*, and all three come back today: the first
is the coverage section, the second is the plan, and the third is the one that
hurts most, because *nothing failed* is exactly what the respin's regression
said. The short answer arrives in the conventional testbench, when we put a bug
into the DUT on purpose; the long one is the whole day, and the last slide of
the day comes back to this question with what the student wrote.

## Trends

#### *Why they come back: what is inside a chip today*

![What is inside 2024 IC/ASICs: asynchronous clocks, embedded processor, security, AI, RISC-V and safety](../res/trends/en/complejidad.svg)

Note:
It is the first half of the answer to *why they come back*: inside there are
two asynchronous clocks in almost all of them, a processor in five out of six
and an AI accelerator in more than half. It is not that verification is done
worse than twenty years ago; it is that there is much more to verify, and the
question on the first slide is harder to answer than ever.

---

## Trends

#### *Verification is not a stage, it is half the work*

![49 % of the designer's time goes to verification; 47 % of the verification engineer's time goes to debug](../res/trends/en/esfuerzo.svg)

Note:
Here is the argument for why this course exists: the verification effort has
already caught up with design. Verifying is not the final step before tape-out: it is
half the project, with its own team and its own language.
The lower 47 % is planted today and collected twice: in the second
exercise this afternoon, when the log says `FAILED` and nothing else, and in
the reporting section on day 3, which is where the log learns to say why.

---

## Trends

#### *And it is verified, mostly, with UVM*

![What verification uses in 2024: UVM at 80 % in IC/ASIC and 50 % in FPGA](../res/trends/en/metodologia.svg)

Note:
This one answers *with what*: eight out of ten ASIC projects verify with UVM,
and half of the FPGA ones. What follows —the COBOL joke and the introduction—
is what that UVM is and why it is not scary. And one thing worth leaving said
now: UVM does not answer the question on the first slide. The testbench does;
UVM is the way to write it so that the person next to you recognizes it.

---

## Is SystemVerilog the *COBOL* of electronics?

| Language | Reserved Keywords |
| --- | --- |
| ANSI COBOL 85 | 357 |
| SystemVerilog | 248 |
| VHDL 2008 | 115 |
| Verilog 95 | 102 |
| C# | 102 |
| C++ 20 | 92 |
| Python 3 | 35 |

> *"* No academic computer scientists participated in the design of COBOL;
>  all of those on the committee came from commerce or government"* Sound familiar?

Note:
It is a joke with a moral: SystemVerilog has 248 keywords —the ones in Annex B
of IEEE 1800-2017— and nobody uses them all. In this course we are going to use about
thirty. The same thing happens with UVM: the library is enormous and with six or seven
classes you put together a complete testbench.
It is useful for lowering the anxiety of whoever arrives scared by the size of UVM.
And it is the bridge to the next section: eight out of ten verify with UVM, UVM
is written in this language, and on days 1 and 2 everything UVM will later hand
you ready-made gets written by hand. Thirty keywords are enough.

## Introduction

#### *What is UVM?*

- **U**niversal **V**erification **M**ethodology: a **class library**
  written in SystemVerilog, plus a pile of **conventions** on how to use it
- It is not a language and it is not a simulator. Everything we are going to see in the
  course can be written by hand — and on days 1 and 2 we are going to write it by hand
- It is made by **Accellera**, the same consortium that standardized SystemVerilog, and it is
  **IEEE 1800.2**. The course uses the reference implementation, `uvm-core
  2020.3.1`
- It comes from OVM (Cadence + Mentor), with ideas from VMM (Synopsys) and from eRM
  (Verisity): the methodologies of four vendors that competed, until the
  industry got tired of translating testbenches between tools
- And there is the goal, and it is a single one: **that the testbench of the person next to
  you looks like yours**

Note:
The link with what came before is one line: eight out of ten projects verify
with this. And the clarification that keeps UVM from looking like the answer
to the question of the day: it is not. The answer is a testbench with a plan, a
check and a measure; UVM is the way to write it so it scales and so someone
else recognizes it.
The sentence that orders the section is the one in the second bullet, and it is worth saying
it loudly because it lowers the anxiety of whoever arrives scared: **UVM does nothing you
could not do yourself**. There is no magic inside. There is a factory, some ports, some
phases and a lot of agreement about names.
If somebody asks why bother then: because of the last bullet. A
verification engineer who changes project —or company— opens the testbench and recognizes
the structure on day one. That is what you are buying. It is not simulation
speed and it is not fewer lines: it is that the structure is the same everywhere.
The historical note is useful for whoever comes from the industry: until 2011 every
vendor had its own, and porting a testbench from VMM to OVM meant rewriting it. UVM
exists because that was unsustainable, not because somebody had a better idea.
And one clarification that avoids a classic misunderstanding: *Open Source* here means
that the **library** is free (Apache 2.0). The **simulator** that runs it almost
always is not — except in this course, which is what all of this is about.

---

## Introduction

#### *Where it comes from*

![From eRM, VMM, AVM and OVM to UVM](../res/en/originUVM.svg)

Note:
The diagram in one sentence: six acronyms from four vendors that converge. eRM was
Verisity's (the `e` language), RVM and later VMM Synopsys', AVM Mentor's and URM
Cadence's; OVM merged AVM with URM, and it is the base UVM came out of.
What has to be pointed out is the date at the bottom and the jump it means: UVM 1.0 is
from 2011, which means this is **young**. Somebody with fifteen years of career today
started before it existed.
And the moral that gets used for the rest of the course: when they find code with
`ovm_component` instead of `uvm_component`, it is not a typo — it is a
testbench from before 2011 that nobody migrated. It happens more than it seems.

---

## Introduction

#### *A SystemVerilog testbench, from the inside*

![Anatomy of a SystemVerilog testbench](../res/en/TB.svg)

Note:
This is the testbench **we** are going to write, by hand, on days 1 and
2. It is worth saying it like that: the boxes in this diagram are not theory, they are the
files that are going to be open between today and day 4.
Point at the tester, the driver, the monitor and the scoreboard, and make the point that
none of those names is UVM's: they are the names anybody gives to the pieces of a
testbench, in any language. UVM did not invent them; it standardized them.

---

## Introduction

#### *The same testbench, with UVM structure*

![The same testbench with UVM structure](../res/en/TB_UVM.svg)

Note:
It is worth staying here a while: this diagram is the map of the rest of the course.
Point at driver, monitor, scoreboard and sequencer, and say that each one is going to be
a section. By the end of day 5 the student is going to have everything except the agent and
the sequencer, which are day 6.
The comparison worth making live is against the previous diagram: **they are
the same boxes**. What UVM adds is the tree that contains them, the ports
they talk through and the phases that build them in order. Nothing else, and that is
not little.

---

## Introduction

#### *The class tree*

![The UVM base class hierarchy](../res/en/uvm_class_diagram.svg)

Note:
This diagram is scary and that is why it is worth defusing it right away: **out of all of
this we are going to extend ten**: `uvm_component`, `uvm_test`, `uvm_env`, `uvm_agent`,
`uvm_driver`, `uvm_monitor`, `uvm_subscriber`, `uvm_sequence_item`,
`uvm_sequence` and `uvm_callback`. They are the amber ones in the drawing minus the scoreboard
—which in the course is a `uvm_subscriber`—, plus the sequence and the callback.
What does have to be marked is the split at the top, because it explains
half the course: hanging off `uvm_object` is the **data** —the transactions, the
sequences, the configs— and hanging off `uvm_component` is the **structure** —everything
that lives in the tree and has phases—. An object is created and thrown away; a component
is built once and lasts the whole simulation.
The colours say what you do with each one: the amber ones you extend yourself, the
grey ones are never touched —they are only there for the others to inherit from—
and `uvm_sequencer` is the only green one because it is the only one instantiated
without extending it, with a parameterized `typedef`. That comes on day 6; the only
time the course extends it is for the virtual sequencer on day 7.
The question to throw at the group when we get to agents: is a
`uvm_sequence` an object or a component? An object. And that is why it does not show up in
`print_topology()`.
It is the same tree that is in the printed cheat sheet, top left, as text, to
look at again when needed.

---

## Introduction

#### *Run more tests writing less code*

- That is the promise, and it has one condition: **the env and the components barely
  change** from one test to another. What changes is the stimulus
- For that to work, the testbench has to leave **hooks**: virtual
  methods, the factory and callbacks. A test hooks in there and does not touch
  the structure
- A new test is then one of these three things, and none of them touches the env:
  - adding **constraints** to reach a corner case
  - doing a factory **override** to swap one class for another
  - injecting errors or delays with **callbacks**
- And on top of all that, the lever that pays off the most: **the same test with hundreds of
  different seeds**

Note:
This is the slide you have to be able to repeat at the end of the course, because it is the
whole thesis. And it is worth being honest: *"run more tests, write less code"* is a vendor
slogan, but the verifiable part is true and you can point at it with your finger on
day 6 — the `add_test` of the sequences is **two lines**, and it changes the whole
stimulus without touching a single class of the env.
The order of the three hooks is not accidental, it goes from smallest to largest: a constraint
changes values, an override changes a class, a callback changes behaviour
at one point of the class that already exists. All three are a section of the course —*Constrained
random* on day 5, *The factory pattern* on day 2 and *Callbacks* on day 6—, so
this slide can be put up three more times.
And the last line is the most underestimated one. A test with a thousand seeds is not
"the same test a thousand times": it is a thousand different scenarios for the price of writing
one. It is literally the `d7-semillas` exercise, the one day 7 starts with.
And the close that leads to the DUT: nothing on this slide answers *how do you
know you verified?* yet. Answering it is what comes next —the spec, the plan
and a testbench that can be put to the test—, and only with that written by
hand does what UVM adds become visible.

## The VTALU spec

![VTALU protocol: start and operands stable until done](../res/diagrams/en/wave-dut.svg)

- *start* has to stay at 1 and the operands stable until 
 the operation finishes
- *done* goes up when the operation finishes: on the multiplication 
 it is a one-cycle pulse; on add/sub/and/xor it is a **level**, and it stays 
 up while *start* stays up
- *reset_n* is asynchronous and active low; the diagram starts with the DUT 
 already out of reset
- *ovf* comes out together with *done*, and it is the **borrow of the subtraction**: it is 1 
 when `A < B`. For the other operations it is always 0

Note:
The protocol is everything you have to respect: start up and operands stable
until done. Careful with the fine print: done is a pulse on the multiplication (it
turns itself off) and a level on add/sub/and/xor, where it is `start && (op != no_op)`. It is
the kind of detail that only shows up when the testbench hangs and nobody
knows why.

---

## The VTALU spec

| Operation | Opcode | Cycles | `ovf` |
| --- | --- | :--: | --- |
| no_op | 3'b000 | — | 0 |
| add_op | 3'b001 | 1 | 0 |
| sub_op | 3'b010 | 1 | **`A < B`** |
| and_op | 3'b011 | 1 | 0 |
| xor_op | 3'b100 | 1 | 0 |
| mul_op | 3'b101 | 4 | 0 |
| *free* | 3'b110 | 1 | 0 |
| rst_op | 3'b111 | — | — |

- **Cycles** counts `clk` edges with `start` up, up to and including the one
  that raises `done`: one on the single-cycle ops, four on the multiplication.
  The plan and the day 7 assertions count the same way
- `rst_op` is not decoded by the RTL — the DUT sees it as *unused*.
  It is the testbench convention for pulsing `reset_n`, and that is why it
  is in the `operation_t` of the testbench
- **`3'b110` is free on purpose**: it is today's exercise

Note:
rst_op belongs to the testbench, not to the RTL: the DUT sees 3'b111 as unused. It is in the
enum because the tester asks for the reset as if it were one more operation, and that way the
reset enters the functional coverage. A good moment to preview that the coverage
plan includes "any operation after a reset".
The ovf column is the one that gets the most discussion, and that is good: with 8-bit
operands and a 16-bit result, neither the addition nor the multiplication can overflow — the
subtraction can, and only when A < B. Which means there is an output of the DUT that for five
of the six operations is always 0. Ask out loud: how do you verify
a signal that almost never moves? The answer is today's, in functional coverage, and it is a bin.
And the free opcode: 3'b110 is not there by chance and not by oversight. It is
this afternoon's exercise, and it is worth saying now so that nobody reads it as a
design slip.

---

## The VTALU spec

#### *Single Cycle: Add - Sub - AND - XOR*

```sv
 // The two resets are deliberately different: the one on the result is
 // SYNCHRONOUS and the one on done is ASYNCHRONOUS. Not an oversight: the spec.
 always_ff @(posedge clk) begin
 if (!reset_n) begin
 result_1c <= 16'h0000;
 ovf_1c <= 1'b0;
 end else if (start) begin
 ovf_1c <= (op == 3'b010) && (A < B);
 case (op)
 3'b001: result_1c <= {8'h00, A} + {8'h00, B};
 3'b010: result_1c <= {8'h00, A} - {8'h00, B};
 3'b011: result_1c <= {8'h00, A} & {8'h00, B};
 3'b100: result_1c <= {8'h00, A} ^ {8'h00, B};
 default: ; // 3'b110 is free: it is the day 1 exercise
 endcase
 end
 end

// done goes high on the edge if start is high and the op is not no_op
 always_ff @(posedge clk or negedge reset_n) begin
 if (!reset_n) done_1c <= 1'b0;
 else done_1c <= start && (op != 3'b000);
 end
```

- Two `always_ff` and nothing else: one registers `A op B`, the other raises `done`
- The resets **are not the same**: the one on the result is **synchronous** —only `clk` in
 the sensitivity list—, the one on `done` is **asynchronous**
- `done <= start && (op != no_op)`: that is why on these four operations `done` is
 a **level** and stays up while `start` is

Note:
The asymmetry of the two resets is not an oversight: it comes from the original VHDL and is
copied as is on purpose. It is exactly the kind of detail a testbench
has to expose, and that is why the DUT was not "cleaned up" when it was translated.
Say it out loud: this contradicts the bare *asynchronous* of the spec bullet,
and no row of the plan looks at what the reset leaves on the outputs: the reset
row looks at the operation that comes after. It is a gap in the plan, and for
now it stays that way.
That `done` is a level here and a pulse on the multiplication is the fine print that
is going to hang the first testbench of the course. It is worth going back to the waveform
of the first slide and pointing at it again.
The `default: ;` of the case is what makes `no_op` and the unused opcodes not
change the result: the ALU keeps whatever it computed last.

---

## The VTALU spec

#### *Multi Cycle: Multiplication*

```sv
 // Four register stages. done is pipelined alongside the data, and each
 // stage clears itself with (& ~done_mult): that is what makes done a
 // one-cycle pulse instead of staying high for as long as start does. It is
 // subtle -- it is copied straight from the VHDL.
 always_ff @(posedge clk or negedge reset_n) begin
 if (!reset_n) begin
 done_mult <= 1'b0;
 done3 <= 1'b0;
 done2 <= 1'b0;
 done1 <= 1'b0;
 a_int <= 8'h00;
 b_int <= 8'h00;
 mult1 <= 16'h0000;
 mult2 <= 16'h0000;
 result_mult <= 16'h0000;
 end else begin
 a_int <= A;
 b_int <= B;
 mult1 <= a_int * b_int;
 mult2 <= mult1;
 result_mult <= mult2;
 done3 <= start & ~done_mult;
 done2 <= done3 & ~done_mult;
 done1 <= done2 & ~done_mult;
 done_mult <= done1 & ~done_mult;
 end
 end
```

- It is a pipeline: the operands get registered, they get multiplied, and the product
  goes through two more registers before coming out on `result_mult`: four edges
- The `done` travels down **the same chain** —`done3`, `done2`, `done1`— so it
  arrives exactly with the data and not before
- The `& ~done_mult` of each stage is what turns the chain off on its own: that is why here
  `done` is a **one-cycle pulse**, even if `start` stays up

Note:
The four-edge latency is on purpose, and it is the reason the conventional testbench exists:
it forces the testbench to **wait for `done`** instead of reading the result on the next
cycle. A combinational DUT would teach nothing.
The `& ~done_mult` is subtle and worth reading slowly: without it, while `start`
was up the chain would reload itself and `done` would stay at 1. It is
copied from the original VHDL as is.
The question that orders the slide: what happens if the testbench sends a
multiplication and reads the result on the next cycle? It reads the previous result,
and the scoreboard reports an error that is not in the DUT.

---

## The VTALU spec

#### *Top Level*

```sv
   assign es_mult = (op == 3'b101);

assign start_1c = es_mult ? 1'b0 : start;
   assign start_mult = es_mult ? start : 1'b0;
   assign result_mux = es_mult ? result_mult : result_1c;
   assign done = es_mult ? done_mult : done_1c;
```

- The top computes nothing: it instantiates the two blocks and **decodes** the opcode
- `es_mult = (op == mul_op)`. The `start` is routed to only one of them, and
  `result_mux` and `done` come out of the same side. `ovf` follows the same pattern
  right below the excerpt —`assign ovf = es_mult ? 1'b0 : ovf_1c;`— and `result_mux`
  only comes out through `result` after the `+VTALU_BUG` XOR
- That is why the bus protocol is a single one even though inside there are two different
  latencies: what the testbench sees is `start` → `done`

Note:
That both blocks share `A`, `B` and `clk` and only split on the `start`
is what makes the DUT have a single interface. Worth pointing out because it is the
shape the `vtalu_bfm` of interfaces and BFM is going to have.
The complete file, with both instances and their connections, is in
`code/vtalu_dut/vtalu.sv`. Here there are only the decode and the four lines that decide.
Worth pointing out why it is a decode and not a loose bit: with an `op[2]` the
opcodes would have to sit in tidy halves of the space, and the design
would lose the freedom to assign them as convenient. A decode costs one gate
and does not tie the spec down. And along the way, the free opcode 3'b110 falls on the
single-cycle side without anybody having to do anything. The DUT does not validate the
opcode; the one that has to catch it is the verification plan.

---

## The VTALU spec

#### *How to run it*

- The DUT lives in `code/vtalu_dut/`, in **SystemVerilog**
- The simulator of the course is **Verilator** (free, no licence):

```sh
make u4/tests          # one UVM example:  ~1 min 30 the first time
make u4/tests          # the second, with ccache:      ~15 seconds
make               # the 38 examples
```

- The ones that use UVM compile **the whole library** the first time. Install
  `ccache` before starting: the course detects it on its own and does not recompile twice
- Every example has its `run.sh`; the common flags are in
  `code/verilator/common.sh`

Note:
Here it is worth leaving the deck and running it live. The numbers on the slide are
measured on a 12-core laptop. On a 2-core machine —a free Codespaces— the
first one is 4 minutes; the second is still 15 seconds, because a ccache hit
is copying a file and that does not depend on how many cores you have. Which means
the expensive part is paid **once**.
What has to be explained is where the difference between 1 min 30 and 15
seconds comes from, because it is not magic: Verilator compiles every simulation to a native
binary, and for that it generates about 2300 C++ files —almost all of them from the UVM library—.
`ccache` stores the result of each one; the second time it does not compile again,
it copies. It is in the Dockerfile and in the devcontainer, and outside it is enough to have it
installed.
And the one to stress anyway: Verilator is free — the student takes it
home and keeps practising without asking anybody for a licence.

---

## The VTALU spec

#### *Looking at the real waves*

- The diagram on the first slide is **drawn**. The real one you generate yourself,
  and it is the tool 47 % of the work gets done with: debugging

```sh
cd code/u2/convencional
VLT_TRACE=1 bash run.sh      # compiles with --trace and dumps vtalu.vcd
gtkwave vtalu.vcd            # or surfer, or whatever viewer you use
```

- `VLT_TRACE=1` turns on two things at once: Verilator's `--trace` and the top's
  `$dumpfile`/`$dumpvars`, which without the flag would not compile
- It costs nothing and it is free, same as the simulator. When the testbench hangs
  on `while (done == 0)`, this is what is going to tell you why

Note:
It is worth opening it live once, even for thirty seconds: load
`op_set`, `start` and `done`, and show the one-cycle pulse of the multiplication
next to the level of the single-cycle ones. It is the fine print of the protocol of
slide 1, but seen.
And say it explicitly: whoever takes the course alone has their safety net here.
When an exercise does not work out, the answer is almost always in the waves before
it is in the code.

---

## The VTALU spec

#### *Summary of the unit*

- The **protocol** is a single sentence, and it has to be respected: `start` at 1 and the
  operands stable **until `done` goes up**
- The fine print that is going to hang the first testbench: `done` is a one-cycle
  **pulse** on the multiplication and a **level** on the single-cycle ones
- Inside there are **two blocks** with different latencies —one and four cycles— and the
  top **decodes** the opcode. Outside, the bus is a single one
- `ovf` is one more output, and it belongs to `sub_op` and to nobody else
- `rst_op` **does not exist for the RTL**: it is a testbench convention for
  pulsing `reset_n`, and that is why it enters the coverage
- The DUT does not validate the opcode: the free one **raises `done` all the same**,
  with the `result` of the previous operation. Catching it is the **verification
  plan's** job, not the design's
- And the tool used 47 % of the time is already installed:
  `VLT_TRACE=1` and GTKWave

Note:
Closing of the section that looks like RTL and is really about verification. The
question to close with: which of these seven facts is the most expensive one to
forget? The one about `done`, and it will show today, in the waves exercise.
Worth saying why the DUT was not "cleaned up" when it was translated from VHDL: the
asymmetry of the resets and the unvalidated opcode are **exactly** the kind of
thing a testbench has to expose. A tidy DUT teaches nothing.

## The verification plan

#### *The most professional deliverable of the discipline, and the cheapest*

- It is a **table**. It gets written **before** the testbench — if it gets written
  after, it describes what the testbench already does instead of what the spec asks for
- It comes out of the spec you have just read, not out of the testbench that does not exist yet
- And it is what gets delivered: the day 7 capstone is handed in with the plan filled,
  which is exactly what gets handed in on a project

Note:
This is the slide that orders the whole course, and that is why it comes before the first
line of testbench. Everything that comes after —the stimulus, the scoreboard, the
covergroups, the assertions— are columns of this table.
It is worth saying it head on: the plan is not bureaucracy. It is the only serious
answer to *"are you done verifying yet?"*, and it is the first thing a technical
lead asks for when they ask how the block is going.
The empty template is in `docs/en/verification-plan.md`, and it gets used twice in
the course: here to read it, and on day 7 to fill it from scratch.

---

## The verification plan

#### *The five columns*

| Column | The question it answers | What does **not** go in |
|---|---|---|
| **Feature** | which part of the spec does this row come from? | the name of a testbench file |
| **Scenario** | which concrete situation has to be provoked? | *"test the ALU"* |
| **Stimulus** | who provokes it: the random or a directed case? | *"by hand"* |
| **Check** | who says it went right? | *"you look at the wave"* |
| **Measure** | which bin gets filled when it happens? | *"you see it in the log"* |

- One row per **scenario**, not per feature: a feature with three corner cases
  is three rows, and they get closed one at a time

Note:
It is worth reading the right-hand column out loud: they are the five mistakes people
make the first time, and all five sound reasonable when you write them.
The hardest column is the measure one, because it forces you to decide *beforehand* what
you are going to count. It is the one that on day 1 still cannot be filled —the bins do not
exist until the next unit— and that is why the plan gets filled as the
testbench grows.

---

## The verification plan

#### *Two rules that come out of the columns*

- **If the check column says *"by eye"*, the scenario is not verified.**
  It is *simulated*, which is another thing
- **If the measure column is empty, nobody is going to find out that the
  scenario never happened.** A case the random never touched and that has no bin is
  indistinguishable from one that happened a thousand times
- And one distinction that orders the check column: **the scoreboard checks
  *what* the DUT computes; the assertions check *how* it is talked to**

Note:
The difference between verified and simulated is who finds out when it fails at three
in the morning in the regression. If the check is a pair of eyes, nobody
finds out: the regression passes green with the bug inside.
The third bullet is a promise the course keeps on day 7: until then
every check is a scoreboard check, and half the protocol goes unchecked.
Worth saying now so that day 7 does not look like an add-on.
A serious plan has both columns, and the VTALU table —which is seen whole in
the next unit, already with the bins— has eight scoreboard rows and four
assertion ones.

## The conventional testbench

#### *The VTALU plan, with three columns to fill*

| Feature | Scenario | Stimulus | Check | Measure |
| --- | --- | --- | --- | --- |
| ALU | the six operations | | | |
| ALU | operands at `00` and at `FF` | | | |
| reset | operate after a reset | | | |
| mult | a mult after a single-cycle one | | | |
| ALU | the same operation twice in a row | | | |
| sub | subtract too much: `A < B`, and `ovf` goes up | | | |

- Six rows that come out of the spec, and none of the right-hand columns yet.
  This section fills **two**: the stimulus provokes them and the scoreboard says
  whether the result was right
- The third one —**which bin gets filled when it happens**— is the next section
- The testbench has three parts because the plan has three columns to fill

Note:
The order matters and it is the one from the previous unit: the plan first,
the testbench after. If you write the testbench first, you end up measuring
what the testbench does instead of what the spec asks for.
Worth reading the six rows one at a time and asking which one is missing. The
answer that usually comes up —"test intermediate values"— is good for
discussing why it is not there: 256 × 256 × 5 combinations do not get
simulated, and that is where random comes in.
The last one is the one that brings today's topic: the DUT has TWO outputs, and
a row of the plan that only closes by looking at both. A scoreboard that
compares `result` and nothing else passes green with `ovf` stuck at zero.
The table comes back twice: in functional coverage with the measure column
filled in, row by row, and at the end of that whole section, with the twelve
rows and the three columns. Worth announcing now so nobody reads it as
decoration: it is the same table, filling up.

---

## The conventional testbench

#### *The stimulus: a thousand operations, and the protocol by hand*

```sv
      repeat (1000) begin
         @(negedge clk);
         op_set = get_op();
         A = get_data();
         B = get_data();
         start = 1'b1;
         case (op_set) // handle the start signal
           no_op: begin
              @(posedge clk);
              start = 1'b0;
           end
           rst_op: begin
              reset_n = 1'b0;
              start = 1'b0;
              @(negedge clk);
              reset_n = 1'b1;
           end
           default: begin
              // Wait for an EDGE with done up, not for done itself: on the
              // one-cycle ops done is a level still up from the previous op,
              // and a plain wait(done) drops this one without a sound.
              enviadas++;
              do @(negedge clk); while (done == 0);
              start = 1'b0;
           end
         endcase // case (op_set)
      end
      $finish;
```

- A thousand rounds: pick the operation, pick the operands, raise `start`, wait for
  **an edge with `done` up**, lower `start`
- The `case` is there because of the fine print of the spec: `no_op` does not raise
  `done`, `rst_op` pulses `reset_n`, and the rest wait
- `get_op()` and `get_data()` bias the random towards the edges —00 and FF— to
  reach the cases the plan asks for. It is *constrained random* written by hand
- `enviadas` gets counted here and `chequeadas` in the scoreboard, and a `final`
  demands they match: it is the testbench checking itself
- Notice who knows about the protocol here: **the tester**. In interfaces and BFM that moves
  to the BFM and in the body of the `repeat` shrinks to one line

Note:
This is the "before" slide of the whole course: the stimulus and the protocol mixed
in the same loop. Worth pointing at it, because the next five units
are successive separations of these thirty lines.
The `do … while (done == 0)` of the `default` is the one that hangs if the DUT does
not answer, and it is the place the student is going to end up in the first time they
break something. The safety net is `VLT_TRACE=1` and the waves.
And why it is not a `wait(done)`, which is the first thing anybody writes: on the
one-cycle operations `done` is a level, and on the `negedge` where the tester loads
the next operation **it is still up from the previous one**. The `wait(done)` does
not block, `start` drops at the same instant and the DUT never sees that operation.
There is no error: the scoreboard does not fire, and the coverage —which samples
`op_set`— counts it anyway. This testbench had it, and it dropped four in ten
one-cycle operations with the report in green: on `d1`, 77 shifts checked
against 130 with the fix. What catches it is the sent-versus-
checked counter, and it is the cheapest silent trap to guard against.
The bias of `get_data()` —a quarter at 00, a quarter at FF, half in the
middle— is exactly what the transactions are going to write in one line with `dist`
and `:/`. Worth naming it now so that the saving is visible later.

---

## The conventional testbench

#### *The self-checking: predict and compare*

```sv
   // Sent by the tester, compared by the scoreboard: the final block below
   // demands that the two match.
   int enviadas, chequeadas;

// Scoreboard loop: checks that everything came out right
   always @(posedge done) begin : scoreboard
      shortint predicted_result;
      bit      predicted_ovf;
      #1;
      case (op_set)
        add_op: predicted_result = A + B;
        sub_op: predicted_result = A - B;
        and_op: predicted_result = A & B;
        xor_op: predicted_result = A ^ B;
        mul_op: predicted_result = A * B;
      endcase // case (op_set)

// ovf belongs to sub and to nobody else: with 8-bit inputs and a 16-bit
 // output, neither the addition nor the multiplication can overflow.
 predicted_ovf = (op_set == sub_op) && (A < B);

if ((op_set != no_op) && (op_set != rst_op)) begin
        chequeadas++;
        if (predicted_result != result || predicted_ovf != ovf)
          $error ("FAILED: A: %0h  B: %0h  op: %s result: %0h ovf: %0b",
                  A, B, op_set.name(), result, ovf);
      end
   end : scoreboard
```

- An `always @(posedge done)`: every time the DUT says it finished, the
  scoreboard predicts the result and compares it
- The `#1` is not decoration: without it the signals get read at the same instant
  `done` goes up and a delta race can be swallowed
- `no_op` and `rst_op` do not raise `done`, so this block should not run with
  them. The `if` is defensive —with no prediction for those two it would compare
  garbage— and inside goes `chequeadas++`, the other half of the counter
- The covergroup —the third leg— is the section that follows

Note:
The reference model is four lines of `case` because the DUT is an ALU. On
a real project it can be a model in C or the RTL of the previous
generation, but the shape is always this one: **predict with something that is not the DUT, and
compare**.
That the scoreboard reads `A`, `B` and `op_set` off the wire at the moment of the result
works only because the protocol forces them to stay stable. It is fragile, and in
the analysis ports it will be replaced by a queue of commands the monitor sends.
And the `$error` here is going to be a `` `uvm_error `` from reporting on: same
concept, with a counter and a severity policy behind it.

---

## The conventional testbench

#### *How do you know the scoreboard checks anything?*

```plaintext
FAILED: A: 15  B: ce  op: xor_op result: da ovf: 0
```

- A thousand operations and not one error. Now **the same testbench with the
  DUT broken on purpose**: `VTALU_BUG=1 bash run.sh` flips bit 0 of the result
- It fails on the first comparison. That —and not the earlier `PASS`— is what
  proves the scoreboard looks at the result
- A scoreboard that **never saw an error** is not proven: it may have compared
  against itself, or compared nothing at all
- `make mutante` does this with the three testbenches of days 1 and 2, and
  fails if any of them does **not** fail. It is the first answer to the
  question of the day

Note:
Run it live, it takes seconds because there is no UVM: first `bash run.sh` —a
thousand operations, silence, and the coverage summary—, then
`VTALU_BUG=1 bash run.sh`, which ends in the line on the slide and a `$stop`.
What has to be said in so many words is what that line proves and what it does
not. It proves the scoreboard compares the bit the bug touched. It does not
prove it compares `ovf`: a bug that only touched `ovf` is another run, and that
is why the plan has a row for each output.
This is the short answer to the first slide of the day: the regression that
said `PASS` and sent the bug to the fab had never seen a `FAILED`. It did not
know whether it was checking. A `PASS` says nothing until you know what
`FAILED` would have said.
And it is not a day-1 trick: it is the practice that runs through the course.
`+BUG=1` in the day 7 capstone and `+GOLDEN_BUG` in the day 8 reference model
are this very thing, and the exercise checkers demand it.

---

## The conventional testbench

#### *Unit summary*

- The testbench has **three parts** because the plan has three columns to
  fill: stimulus, self-checking and measure. Today they are loose in one file
- The stimulus **biases the random towards the edges** —`00` and `FF`— because
  uniform randomness almost never visits them
- The `#1` before reading the signals is not decoration: without it you read in
  the very instant the DUT writes, and the result is undefined
- A `PASS` proves nothing until you have seen the `FAILED`: **`VTALU_BUG=1`** is
  the way to see it, and `make mutante` the way not to forget
- And what to look at for interfaces and BFM: **the tester knows the
  protocol**. It moves `start` and waits for `done` by hand

Note:
The last bullet is the one that orders the rest of the day: this testbench
works, it is proven, and it is badly divided. The tester knows how `start` is
wiggled and the scoreboard knows when to read `done`: the protocol lives in two
places of the same file, and the day it changes both have to be touched.
That is the whole motivation for interfaces and BFM, and it is worth leaving as
an open question instead of answering it here. Before that, the next section
fills in the third column.

## Functional coverage

#### *When are you done verifying?*

- *Code coverage* —lines, branches, toggle— the simulator gives you for free.
  It says which RTL got **executed**
- *Functional coverage* you write yourself. It says which **scenarios of the spec**
  went through the DUT
- They are not the same thing, and the first one misleads: a test that always sends `add_op`
  with `A=B=8'h01` executes almost every line of the adder and verified nothing
- Functional coverage is the *contract* between the spec and the testbench: if a
  case of the spec has no bin, nobody is going to find out it is missing

Note:
The question on the slide is the one a verification engineer gets asked in the
tape-out meeting, and it is not answered with "I ran a lot of tests".
If somebody asks why code coverage is not enough: because it measures the
DUT, not the spec. A DUT that is missing a whole feature can give 100 % of
lines — the lines nobody wrote do not show up in the report.

---

## Functional coverage

#### *From the verification plan to the covergroup*

The six rows of the plan from the previous section, translated:

| From the plan | How it gets measured |
| --- | --- |
| the six operations | `coverpoint op_set` with one bin per operation |
| operands at `00` and at `FF` | `cross` of A, B and the operation |
| operate after a reset | transition bin `rst_op => op` |
| a mult after a single-cycle one | transition bin |
| the same operation twice in a row | repetition bin `[* 2]` |
| subtract too much: `A < B`, and `ovf` goes up | `coverpoint borrow` with the `hubo_borrow` bin |

- The six rows stop being good intentions: each one is a line of
  code, and the simulator tells you which ones have not happened yet

Note:
It is worth going back to the plan of the previous section and reading it out loud before
showing this table: the point is that there is not one item of the plan left
untranslated.
The order matters — the plan first, the covergroup after. The other way round you end up
measuring what the testbench does, not what the spec asks for.

---

## Functional coverage

#### *Anatomy: it is three steps, not one*

```systemverilog
covergroup op_cov;                     // 1. WHAT gets measured
   coverpoint op_set;
endgroup

op_cov oc;                             // 2. it gets INSTANTIATED: it is a type, like a class
initial oc = new();

always @(posedge clk) oc.sample();     // 3. WHEN it gets counted
```

- A `covergroup` is a **type**: declaring it measures nothing, it has to be `new()`ed
- `sample()` is the one that counts. Without `sample()` the report reads **0 %** and the code
  compiles just the same
- *Where* to sample is a design decision. Here, the edge the **DUT reads on**,
  never the same one the tester writes on; when the TB has monitors it will be
  *"every time the monitor sees a command"*

Note:
Everybody's first-time mistake is declaring the covergroup and forgetting the
`new()` or the `sample()`. There is no warning: the report simply says 0 % and you
spend half an hour looking for the bug in the bins.
The third point is the one that holds for the rest of the course: the moment of the sample
defines what you are measuring. Sampling on the clock counts cycles; sampling on
transactions counts operations. In the analysis ports the `coverage` becomes a
subscriber and samples when a command arrives — which is the right thing.
And the edge is not a whim: sampling on the same `negedge` the tester writes
`op_set` on is a race the LRM does not define —Verilator always resolves it the
same way; another simulator may not—. It is the same rule as the day 7
assertions: you read on the opposite edge to the one that writes.

---

## Functional coverage

#### *bins: the buckets that have to be filled*

```systemverilog
coverpoint op_set;                   // automatic bins: one per value of the enum

coverpoint op_set {
   bins single_cycle[] = {[add_op : xor_op], rst_op, no_op};  // [] -> one per value
   bins multi_cycle    = {mul_op};                            // no [] -> a single one
}
```

- Without `{ }`, SystemVerilog creates one bin per value. That works for an `enum`; for an
  `int` the tool chops the range into **64** buckets —`auto_bin_max`— that
  correspond to no row of the plan
- The brackets `[]` **hand out**: one bucket per value of the range. Without them,
  every value falls into the same bucket
- A coverpoint is covered when **all** of its bins have at least one hit.
  A bin that cannot be filled pins your number down forever

Note:
The brackets are the detail most often copied wrong, and it is worth showing it with
both cases side by side: `bins x[] = {[0:3]}` is **four** buckets, and
`bins x = {[0:3]}` is **a single one** that gets filled by any of the
four values landing. The syntax differs by two characters and the number the tool
reports changes completely.
The practical consequence has to be said loudly because it is a silent trap: a
bin without `[]` over a large range **always gives 100 %**. You covered one value out of
a thousand and the tool tells you it is done. Nobody warns you.
And the last bullet is the warning that orders what comes next: a bin that
cannot be filled is not a tool problem, it is a decision somebody did not write down.
The way to write it down is called `ignore_bins`, and it has its own slide in this
section.

---

## Functional coverage

#### *The VTALU covergroup*

```sv
   //op_cov: make sure every operation, and every interaction between them, is covered
   covergroup op_cov;
      coverpoint op_set {
         bins single_cycle[] = {[add_op : xor_op], rst_op,no_op};
         bins multi_cycle = {mul_op};

// => are transitional coverage. From => To
         // Transition bins. Verilator 5.052 does NOT implement them yet: any form
         // with "=>" or "[* n]" aborts with an Internal Error. Minimal repro in
         // code/verilator/repro-cg-transition.sv. They stay because they are part
         // of the topic; when Verilator supports them, drop the ifndef, nothing else.
`ifndef VERILATOR
         bins opn_rst[] = ([add_op:mul_op] => rst_op);
         bins rst_opn[] = (rst_op => [add_op:mul_op]);

bins sngl_mul[] = ([add_op:xor_op],no_op => mul_op);
         bins mul_sngl[] = (mul_op => [add_op:xor_op], no_op);

bins twoops[] = ([add_op:mul_op] [* 2]);
         bins manymult = (mul_op [* 3:5]);
`endif
      }
   endgroup
```

- `single_cycle[]` generates six bins —one per operation—, `multi_cycle` a single one
- What is inside `` `ifndef VERILATOR `` are the transition bins, which come
  further on in this same section

Note:
This is the first real covergroup of the course, and it is worth reading it top to
bottom answering the three questions of the previous slide: **what** gets measured (the
coverpoints), **into which buckets** (the bins) and **when** it gets counted (the
`sample()`, which is further down in the same file).
That `multi_cycle` is a single bin and `single_cycle[]` is six is not broken
symmetry: it is the verification plan. The six that are not the multiplication matter
one by one; the multiplication matters as a separate case because it is the only one that takes
more than one cycle. The shape of the covergroup **is** the table of the plan, and that is why the
plan gets written first.
The `` `ifndef VERILATOR `` is worth naming now and not hiding: those bins are
a topic of the course, they are written, and today Verilator does not compile them. It is in
`docs/en/verilator.md` with the version and the date. A course that covers up what its
tool does not do is a course that lies.

---

## Functional coverage

#### *ignore_bins: saying out loud what does not get covered*

```sv
      // Check the corners where the inputs are all 0s or all 1s
      all_ops : coverpoint op_set {
         ignore_bins null_ops = {rst_op, no_op};}

a_leg: coverpoint A {
         bins zeros = {8'h00};
         bins others= {[8'h01:8'hFE]};
         bins ones  = {8'hFF};
      }

b_leg: coverpoint B {
 bins zeros = {8'h00};
 bins others= {[8'h01:8'hFE]};
 bins ones = {8'hFF};
 }
 // VTALU rev2: the borrow of the subtraction, the row of the plan that the
 // scoreboard can only close by looking at TWO outputs. Without this bin, a
 // subtraction that never went negative looks exactly like one that did.
 borrow: coverpoint ((op_set == sub_op) && (A < B)) {
 bins hubo_borrow = {1};
 ignore_bins resto = {0};
 }
```

- `all_ops` **ignores** `rst_op` and `no_op`: it makes no sense to ask for "an addition with
  the operands at 0x00" when the operation is a reset
- `a_leg` and `b_leg` bring 256 values down to the three buckets that matter:
  all zeros, the middle, all ones
- An impossible bin you leave in place keeps your coverage pinned below 100 %
  and nobody knows why. `ignore_bins` turns it into a written decision

Note:
There is a relative worth naming: `illegal_bins`. `ignore_bins` takes the bin
out of the count; `illegal_bins` takes it out of the count *and also* reports an error if
it ever happens. It is for the cases the spec forbids — a reserved opcode,
an illegal handshake.
The rule of thumb: if it cannot be covered, `ignore_bins`; if it must not happen,
`illegal_bins`; if it simply has not happened yet, leave it and write the test.

---

## Functional coverage

#### *cross: the combinations, and how not to drown*

```systemverilog
op_00_FF : cross a_leg, b_leg, all_ops;    // 3 x 3 x 5 = 45 bins, almost all meaningless
```

- A `cross` is the **cartesian product** of its coverpoints: it grows fast and
  most of the combinations are in nobody's spec
- `binsof(x) intersect {v}` reads as *"the bins of `x` that contain `v`"*
- They combine with `&&` and `||`, and what is left over gets thrown away with `ignore_bins`
- That way the 45 bins come down to the 11 the plan actually asked for

Note:
The arithmetic in the comment is what has to be done out loud, because the number
is scary and it has to be: three bins of A by three of B by five operations
is **45**, and out of those 45 the plan asked for eleven. The other 34 are not wrong — they are
surplus, and a surplus bin is as expensive as a missing one: it pins your coverage
below 100 % and nobody knows whether it is a real hole.
`binsof(x) intersect {v}` is worth reading in plain words before
writing it, because the syntax does not help: *"the bins of `x` that contain `v`"*.
Then they combine with `&&` and `||` like any condition.
The scale mistake to anticipate: on a real DUT a cross of three
coverpoints with automatic bins is thousands of buckets, and a regression never
fills them. When somebody says "the coverage is not going up", half the time
the problem is an unfiltered cross, not a missing test.
And the number to keep at hand for the "Reading the number" slide: the 45 are the
LRM count, one bin per enum member. **Verilator measures 54**, because it hands out
the automatic bins by the base type (`bit [2:0]`, 8 values minus the 2 of
`ignore_bins`, that is 3 x 3 x 6). The 9 extra are the `3'b110` crossed, and they
are exactly the 9 that stay at zero.

---

## Functional coverage

#### *The VTALU cross*

```sv
         bins mul_00 = binsof (all_ops) intersect {mul_op} &&
                       (binsof (a_leg.zeros) || binsof (b_leg.zeros));

bins mul_FF = binsof (all_ops) intersect {mul_op} &&
                       (binsof (a_leg.ones) || binsof (b_leg.ones));

bins mul_max = binsof (all_ops) intersect {mul_op} &&
                        (binsof (a_leg.ones) && binsof (b_leg.ones));

ignore_bins others_only =
                         binsof(a_leg.others) && binsof(b_leg.others);
```

- `mul_00` reads straight through: *a multiplication where A **or** B is 0x00*.
  The other eight bins of the cross are these two lines with another `op`
- `mul_max` is the only one with `&&`: it asks for **both** legs at 0xFF: the
  **maximum product**, `FF` × `FF` = `FE01`. It does not overflow — 8 bits by 8 fit in 16
- Verilator 5.052 **ignores** `binsof` / `intersect` (`%Warning-COVERIGN`) and measures
  the whole cross: that is why the number is not a commercial tool's

Note:
Worth reading `mul_00` and `mul_max` in plain words, one after the other, because the
difference between `||` and `&&` is the one that gets copied wrong, and here both bins
belong to the same operation: *"a multiplication where A **or** B is 0x00"*
against *"a multiplication with A **and** B at 0xFF"*. The first
is two cases, the second is a single one — the **maximum product**, the top corner of
the input space. And here it is worth killing the misunderstanding that comes on its own,
because it is expensive: `FF` × `FF` **does not overflow anything**. It gives `FE01`, which
fits exactly in the 16 bits of `result` —8 bits by 8 never go past 16— and that is why the
DUT forces `ovf` to 0 in every multiplication: `assign ovf = es_mult ? 1'b0 : ovf_1c;`.
The bin is called `mul_max` and not `mul_ovf` for precisely that reason: the case is worth
something for being the maximum of the input space, not for overflowing. The only operation
that overflows is the subtraction, and only when A < B.
The honesty of this slide is part of the course, so it is worth saying and not
rushing past: the 86.8 % the example reports **is not** the number Questa would give.
Verilator ignores the filter and measures the whole cross, and on top it adds a
value the enum does not have: where the LRM counts 45, Verilator counts **54** (the
9 extra are the `3'b110` crossed, and they are the 9 that stay at zero). That is why
the percentage comes out lower, and for a reason that is not the testbench's. It is
written, dated and with a version in `docs/en/verilator.md`.
The useful question for the classroom: does that invalidate the exercise? No. What gets learned
—writing the cross, filtering it, and knowing which bin belongs to which row of the plan—
is identical. The only thing that cannot be done with this tool is signing off on
coverage closure, and that is not the goal of the course.

---

## Functional coverage

#### *Transition bins: when the order matters*

```systemverilog
bins opn_rst[] = ([add_op:mul_op] => rst_op);   // A and then B
bins sngl_mul[] = ([add_op:xor_op], no_op => mul_op);
bins twoops[]  = ([add_op:mul_op] [* 2]);       // twice in a row
bins manymult  = (mul_op [* 3:5]);              // between 3 and 5 times in a row
```

- Three rows of the plan are not values, they are **sequences**: "after
  a reset", "a mult after a single-cycle one"
- Verilator 5.052 still **does not compile them** (Internal Error). In the code
  they are inside `` `ifndef VERILATOR ``: they are part of the topic and read just the same
- Minimal repro in `code/verilator/repro-cg-transition.sv`. The day Verilator
  supports them, the `ifndef` gets deleted and nothing else

Note:
It is the only place in the course where the free tool falls short, and it is worth
saying head on instead of hiding it: the concept belongs to the language, not to the
simulator, and on Questa or VCS these bins run.
There are two more cousins worth naming: `[-> n]` (goto, n times not necessarily
in a row) and `[= n]` (non-consecutive). They are in `coverage.svh` of the analysis ports.

---

## Functional coverage

#### *The knobs: when a bin counts as covered*

```systemverilog
coverpoint op_set {
   option.at_least = 10;                  // a bin only counts at 10 hits
   bins single[] = {[add_op:xor_op]};
}
coverpoint A { option.auto_bin_max = 8; } // 8 automatic buckets, not 64
```

- **`option.at_least`** is the one that matters most: by default it is **1**, so a
  bin that happened **once** already shows up as covered. The corner case that came up once
  in a thousand runs is not verified, and the 100 % says it is
- **`option.auto_bin_max`** bounds the automatic bins. Without `{ }` and without this
  knob, an 8-bit coverpoint does not give 256 buckets: it gives **64**, handed out
  by the tool and not by the spec
- **`option.weight`** changes how much a coverpoint weighs in the total, and
  **`type_option.merge_instances`** adds every instance into a single number
  instead of reporting them separately
- Verilator 5.052 honours `auto_bin_max`, and `at_least` **only written in the
  coverpoint**: in the covergroup it ignores it without warning. It is in `docs/en/verilator.md`

Note:
This is the slide that puts an asterisk on every percentage of the unit, and
that is why it only arrives now: `at_least = 1` means the tool tells you
**covered** with a single hit. For a bin that represents a value of an enum
that is perfect —either it happened or it did not—. For the bin that represents the maximum
product of the multiplier, one hit is an anecdote, not a verification.
The field rule, and it is worth giving because the question comes on its own: `at_least`
high on the bins that represent a rare case, default on the ones that represent a
value. Raising it for the whole covergroup is not rigour, it is a regression that never
closes and a number nobody looks at.
`auto_bin_max` is the flip side of the bracket trap, the one on the bins slide. There the problem was a surplus bin; here it is the other way round: if the coverpoint is
an `int` and you write it no bins, the tool invents 64 ranges that do not
correspond to any row of the plan. The number that comes out is real and means
nothing.
And the usual honesty: the four knobs are the LRM's, not Verilator's. What
this tool does with each one is measured, dated and with a repro in
`code/verilator/repro-cg-options.sv`. The `at_least` one is the worst of the four
because it is silent: in the covergroup you write it, it compiles, and it does nothing.

---

## Functional coverage

#### *Reading the number*

```sh
$ make u2/convencional
Coverage Summary:
  covergroup : 86.8% (66/76)
```

- 66 of 76 bins filled, with **1000 randomizations** and **615 operations on the
  bus** —`no_op` and `rst_op` get drawn and never sent, and the testbench prints
  that right before the Verilator report—. The other rows come out `0/0`:
  `--coverage-user` leaves code coverage out
- The 10 that are missing are **a single value**: `all_ops.auto_5` and its nine
  crosses. It is `3'b110`, which the enum **does not have** — Verilator hands out
  the automatic bins by the base type, `bit [2:0]`, and not by enum member
- Which means no row of the plan was left uncovered, and on Questa this gives 100 %.
  The number is not the goal: the question that helps is **which** bin is missing,
  and only the per-bin report says that, `obj_dir/top/coverage.dat`
- Run → look at what is missing → write the directed test → run again. That is
  called *coverage closure*, and it is what a verification engineer spends the day on

Note:
This is where it is worth running it live and opening the `coverage.dat`: the
student has to see that the ten zeros have the same name, and that the name is not
in the `operation_t`. The lesson is to read the report and not the number: the
number says 86.8 % and the report says "nothing is missing, the tool invented a
bucket". On a commercial tool the automatic bin of an enum is one per member
(IEEE 1800, 19.5) and this gives 100 % from the start; it is noted in
`docs/en/verilator.md`.
And the punchline: the exercise of the day uses precisely `3'b110` for the shift, so
the new operation fills the phantom bucket and the coverage goes from 86.8 % to
100 % — 77 out of 77, with the shift's own bin added. The one who raises it is the
same one who wrote the test, and the checker counts bins and not the percentage,
because we have just seen the percentage cannot read.

---

## Functional coverage

#### *The verification plan, whole and in one table*

| # | Feature | Scenario | Stimulus | Check | Measure |
|:--:| --- | --- | --- | --- | --- |
| 1 | ALU | the six operations | random | scoreboard | `coverpoint op_set` |
| 2 | ALU | operands at `00` and at `FF` | `dist` biased to the edges | scoreboard | cross `op_00_FF` |
| 3 | mult | maximum product: `FF` × `FF` | directed case | scoreboard, 16 bits | bin `mul_max` |
| 4 | reset | operate after a reset | `rst_op` interleaved | scoreboard | bin `rst_op => op` |
| 5 | mult | a mult after a single-cycle one | random | scoreboard | transition bin |
| 6 | ALU | the same operation twice in a row | random | scoreboard | bin `[* 2]` |
| 7 | sub | subtract too much: `A < B`, and `ovf` goes up | random | scoreboard, **two outputs** | bin `hubo_borrow` |
| 8 | sub | `A == B`: the result is 0 and `ovf` does **not** go up | random | scoreboard, two outputs | bin `sub_00`/`sub_FF` |
| 9 | ovf | `ovf` does not go up for any other operation | random | assertion | `c_ovf` |
| 10 | protocol | the operands are not touched with `start` up | random | assertion | `cover property` |
| 11 | protocol | `done` arrives, and before 5 cycles | random | assertion | `cover property` |
| 12 | protocol | `no_op` is the only one that does not answer | random | assertion | `cover property` |

- The three right-hand columns are **the three parts of the testbench** of this
  section. What ties them together is the plan, and until now you had not seen it whole
- The two subtraction rows are the ones that force the scoreboard to look at **two
  outputs**: if it only compares `result`, it passes green with `ovf` stuck at zero
- The **last four** are checked by no scoreboard: they are `ovf` and **protocol**
  rules, and get checked where they happen —the assertions
- The twelve rows are numbered the same as in **`docs/en/verification-plan.md`**,
  which also says which file each one lives in and carries the capstone template

Note:
This is the slide that answers *"and what is this for?"* for the rest of day 1, and
it is worth saying head on why it only arrives now: the three right-hand columns
are stimulus, self-checking and coverage — the three parts the previous
unit showed **loose**. The plan is the table that makes them one thing.
The row that gets the most discussion is the maximum-product one, and that is good: `FF` × `FF`
is the case a **short** test does not fill, and that is why its stimulus column says
*directed case*: the plan is decided before knowing how long the random will run.
There you see that the plan does not only measure, it also decides which test has to be written.
It is the `d5c` exercise, the last one of the day 5 afternoon, with this same row.
The three protocol rows are worth naming and moving on: they are the half the
course does not touch until day 7, and they serve to plant the idea that a scoreboard does not
check everything. A serious verification plan has both columns.
And what the student takes home: `docs/en/verification-plan.md` is the same table
as an artifact, with an empty template. The day 7 capstone is handed in with the
plan filled — which is exactly what gets handed in on a project.

---

## Functional coverage

#### *Summary of the unit*

- **Code coverage ≠ functional coverage.** The first one measures which RTL got
  executed; the second, which scenarios of the spec happened
- A `covergroup` is a **type**: it has to be instantiated with `new()` and **somebody
  has to call `sample()`**. Without that the report reads 0 % without a warning
- The **bins** are the buckets. `[]` hands out one per value; without brackets,
  the whole range goes into a single one
- **`ignore_bins` is executable documentation**: it says out loud what does not get
  covered and why. An impossible bin you leave in place pins your number down
- A **`cross`** is the cartesian product and grows extremely fast: without bounding it, the
  coverage never closes
- **`option.at_least` is 1 by default**: a bin that happened once already
  shows up as covered, and a rare case with one hit is not verified
- The number is not the goal. The goal is the **plan**; the coverage only says how much
  of the plan was met

Note:
Closing of the most misunderstood concept of the course. The sentence to take home:
**coverage does not tell you the design is right, it tells you that you tested it**.
A DUT that is missing a whole feature gives 100 % of code coverage and 0 %
of the functional coverage nobody wrote.
And the operational mistake that repeats the most, to leave it burned in: the missing
`sample()`. It compiles, it runs, and the report reads zero.

## Interfaces and BFM

#### *First: the signals stop being loose*

```sv
interface vtalu_bfm;
   // brings in operation_t. e.g. (no_op  = 3'b000)
   import vtalu_pkg::*;

byte unsigned        A;
   byte unsigned        B;
   bit                  clk;
   bit                  reset_n;
   wire          [ 2:0] op;
   bit                  start;
   wire                 done;
   wire          [15:0] result;
   wire                 ovf;
   operation_t          op_set;

assign op = op_set;

// The BFM is a first step towards modularity
   // It takes care of driving every low-level signal
   // and keeps the protocol in one single place

// DUT clock
   initial begin
      clk = 0;
      forever begin
         #10;
         clk = ~clk;
      end
   end
```

- An `interface` is a **bundle** of signals with a name of its own. Nine wires that
  used to be declared in the `top` now live together
- The clock gets generated inside: the interface is not a wire, it is a model of the bus
- Connecting the DUT becomes `.A(bfm.A)`, `.clk(bfm.clk)`… and a new signal gets
  declared **once**: the modules that use it see it appear without touching their ports
- What is not needed here and you will see in somebody else's RTL: the **`modport`**, which is
  the same interface with the directions set for one side of the wire

Note:
First step towards UVM and it does not have a single line of UVM.
The immediate gain is a maintenance one and it is worth measuring: with loose
signals, splitting the testbench into modules forces every one of them through every
port list, and a new signal gets wired in all of them. Here it gets declared in the
interface, and the only port that changes is the DUT's.
One detail of types that costs you: `op` is a `wire [2:0]` and `op_set` is the
`operation_t`. The `assign op = op_set` is the bridge between the testbench enum and
the DUT wires. It is the only place in the course where the seam between the
two worlds is visible.
And the `modport`, which does not show up in the rest of the course and does in anybody
else's RTL: it is a view of the interface with the directions declared —`modport dut (input
A, input B, output result)`—, and the module asks for it in its port list
(`vtalu_bfm.dut bus`). It is good for two things, and both are worth it: it lets the compiler
stop the DUT if it writes a signal that was an input as far as it is concerned, and it lets whoever reads the
interface know who drives what without opening the RTL. It is not here because the BFM belongs
to the testbench and drives everything; at work the interface almost always comes with
two or three modports and what you need to know is which one to ask for.

---

## Interfaces and BFM

#### *Then: the protocol hides inside a task*

```sv
   // The protocol handling can now be changed in one single place.
   // Fix it here once, and the fix propagates through the rest of the code
   task send_op(input byte iA, input byte iB, input operation_t iop,
                output shortint alu_result);

op_set = iop;

if (iop == rst_op) begin
         @(posedge clk);
         reset_n = 1'b0;
         start = 1'b0;
         @(posedge clk);
         #1;
         reset_n = 1'b1;
      end else begin
         @(negedge clk);
         A = iA;
         B = iB;
         start = 1'b1;
         if (iop == no_op) begin
            @(posedge clk);
            #1;
            start = 1'b0;
         end else begin
            do @(negedge clk); while (done == 0);
            start = 1'b0;
         end
      end

endtask : send_op
```

- `send_op(A, B, op, result)` translates *"do an addition"* into the signal wiggling
  the DUT expects. That is a **Bus Functional Model**
- Inside it is all the fine print of the spec: the `reset_n` pulse, the
  `no_op` that does not wait for `done`, and the `do ... while (done == 0)` of the rest
- From here on **nobody moves `bfm.start` by hand**. Whoever wants an
  operation asks for it

Note:
The sentence that orders the section: the protocol gets written **once**. If tomorrow
the DUT asks for two cycles of `start`, this task gets touched and nothing else.
The `#1` after the `@(posedge clk)` is the same precaution as the scoreboard of the conventional testbench: moving the signals one delta after the edge, not on the edge.
And the hook for day 4: the `driver` of the put and get ports is exactly this task,
but inside a class and fed by a port. The operation —hiding the
wire— is the same; what changes is where the data comes from.

---

## Interfaces and BFM

#### *The top, with the BFM in the middle*

- The testbench is still split into the same three pieces —tester, scoreboard and
  coverage—, and not one of them changed its name
- What changed is **how they connect to the DUT**: there are no loose signals
  travelling any more, there is a single interface the three of them share

```sv
module top;
   vtalu_bfm bfm ();
   // Tester: generates the stimulus
   tester tester_i (bfm);
   // Coverage: provides functional coverage
   coverage coverage_i (bfm);
   // ScoreBoard: checks the results
   scoreboard scoreboard_i (bfm);

vtalu DUT (
       .A(bfm.A),
       .B(bfm.B),
       .op(bfm.op),
       .clk(bfm.clk),
       .reset_n(bfm.reset_n),
       .start(bfm.start),
       .done(bfm.done),
       .ovf(bfm.ovf),
       .result(bfm.result)
   );
endmodule : top
```

Note:
It is worth reading this `top.sv` next to the previous section's, because the diff is
the whole section: where there was a list of `logic` declared in the top and
wired by hand to the DUT, now there is **one line** that instantiates the BFM and one that
plugs it in.
What has to be pointed out, because it is what repeats for the rest of the course: the DUT
connects to `bfm.A`, `bfm.B`, `bfm.op`… The interface is not an abstract object,
it is the same old wires grouped under a name. Nothing became slower
or stranger — it became harder to connect wrong.
And the detail that pays for itself the day the DUT grows: adding a signal to the
protocol means touching the interface, and everyone who uses it sees it appear. In the
previous version you had to remember to wire it in every instance.

---

## Interfaces and BFM

#### *Scoreboard: the same check, now talking to the BFM*

```sv
module scoreboard (
    vtalu_bfm bfm
);
   import vtalu_pkg::*;

always @(posedge bfm.done) begin
      shortint predicted_result;
      bit      predicted_ovf;
      #1;
      case (bfm.op_set)
         add_op: predicted_result = bfm.A + bfm.B;
         sub_op: predicted_result = bfm.A - bfm.B;
         and_op: predicted_result = bfm.A & bfm.B;
         xor_op: predicted_result = bfm.A ^ bfm.B;
         mul_op: predicted_result = bfm.A * bfm.B;
      endcase  // case (op_set)

// ovf belongs to sub and to nobody else: with 8-bit inputs and a 16-bit
 // output, neither the addition nor the multiplication can overflow.
 predicted_ovf = (bfm.op_set == sub_op) && (bfm.A < bfm.B);

if ((bfm.op_set != no_op) && (bfm.op_set != rst_op))
         if (predicted_result != bfm.result || predicted_ovf != bfm.ovf)
            $error(
                "FAILED: A: %0h  B: %0h  op: %s result: %0h ovf: %0b",
                bfm.A,
                bfm.B,
                bfm.op_set.name(),
                bfm.result,
                bfm.ovf
            );

end
endmodule : scoreboard
```

- It is the conventional testbench's `scoreboard`: it predicts and compares with the
  same logic
- The only thing that changed is where it gets the signals from: they used to be variables of the
  same module, now they are `bfm.A`, `bfm.B`, `bfm.op_set`
- And that is why it is a **separate module** now: it can live in its own file
  because it shares nothing with the tester except the interface

Note:
What has to be pointed out is what did **not** change. The verification logic is
identical; what got modularized is the wiring. That is the whole section.
The `bfm.` in front of every signal is the first time the student sees an interface
hierarchy, and it is worth writing it on the board: `top.bfm.A`. In the tests that
same reference is going to arrive through the config_db into a class, and there the prefix will
be a handle instead of an instance name.
The debt that stays open: the scoreboard still watches the signals
directly. Only in the analysis ports is it going to receive *transactions* from a monitor and
stop knowing that a `clk` exists.

---

## Interfaces and BFM

#### *Tester: it asks for operations, it does not move wires*

```sv
   initial begin
      byte unsigned iA;
      byte unsigned iB;
      operation_t   op_set;
      shortint      result;

bfm.reset_alu();
      repeat (1000) begin : random_loop
         op_set = get_op();
         iA = get_data();
         iB = get_data();
         bfm.send_op(iA, iB, op_set, result);
      end : random_loop
      $finish;
   end  // initial begin
```

- The tester no longer touches `start` or waits for `done`: it calls `bfm.send_op(...)` and
  forgets about the protocol
- The handshake ended up **written once**, inside the BFM. If tomorrow the
  DUT asks for two cycles of `start`, one file gets touched
- That is the definition of *Bus Functional Model*: the task translates *"do an
  addition"* into the signal wiggling the DUT expects

Note:
The comparison with the conventional testbench is the slide: over there the `tester` raised `start`,
waited for `done` and lowered `start`, mixed in with the stimulus generation. Here
it only generates stimulus.
Worth counting how many places of the conventional testbench knew about the protocol
—the tester and the scoreboard— and how many move `start` now: one, the `send_op`.
The scoreboard still waits for `done` on its own; that debt gets paid by the monitor
of the analysis ports.
And the hook for day 4: in the put and get ports this same tester is going to be a class with
a `put_port`, and the BFM is going to end up on the other side of a driver. The operation is
the same one we did here —hiding the wire— repeated one level up.

---

## Interfaces and BFM

#### *The protocol rule, written in the simulator's language*

```systemverilog
// IMMEDIATE: a statement. It checks the present, where the thread goes by.
assert (op_set != no_op || done == 0)
   else $error("no_op should not raise done");

// CONCURRENT: a declaration with a clock. It plugs itself in once and
// checks EVERY edge of the simulation, on its own, forever.
a_operandos_estables :
assert property (@(negedge clk) start |=> $stable(A) && $stable(B));
```

- The rule —*while `start` is up, the operands are not touched*— is already
  written **twice**: in prose in the spec, and wrapped inside
  `send_op()` here
- An **assertion** is that same sentence a third time, but **executable**: it does not
  merely comply with the rule, it **checks** it
- And it checks it where it happens —in the interface, on the exact edge— and not at the end,
  comparing results

Note:
This is a hook, not the section: the syntax must not be explained here, and least of all
the `|=>` or the edge. The only thing that has to stick is that the protocol rule
can be written in a form the simulator understands.
Worth pointing out the asymmetry that opens up: the BFM **complies with** the protocol, and that
is enough while all the stimulus goes through the BFM. As soon as a legacy module,
a VIP from another team or a driver written in a hurry shows up, complying stops
being the same as checking.
If somebody asks why one says `negedge` and the other does not, the short answer
is *"because the BFM writes on the negedge, and that is only fully visible in the assertions"*. That is the question we want to plant.

---

## Interfaces and BFM

#### *Where each thing gets checked*

- The conventional testbench's **scoreboard** checks the **result**: `A op B` against what
  the DUT returned. It is the half this course develops to the end
- An **assertion** checks the **protocol**: who moves, when, and for
  how many cycles. It is the other half
- A DUT that returns `result` correctly but drops `done` one cycle early **passes
  every test** of the next six days. Nobody is watching it
- It is seen whole in **the assertions section**, with the same VTALU and the same `run.sh`

Note:
The sentence worth leaving on the board for the whole course: *the scoreboard
checks what the DUT computes; the assertions, how it is talked to.* What is
left of day 1 and the six days that follow are the first half;
the second arrives at the end, and it arrives on this same example.
There is no need to promise more than that. The assertions come back with the property of this
slide, write it for real, and show why the edge chosen is not a
detail.

---

## Interfaces and BFM

#### *The hole the BFM leaves: the timing*

```sv
      // 1. Sample AT the edge. The DUT always_ff updates d_out with a
      //    nonblocking assignment, which lands after this initial already ran:
      //    you read the OLD value.
      @(posedge clk);
      en_el_flanco = d_out;

// 2. The same edge, one delta later. The nonblocking assignment landed
      //    already and you read the NEW value. That "#1" is visible nowhere and
      //    changes the result.
      @(posedge clk);
      #1;
      un_delta_despues = d_out;

// 3. The opposite edge: the trick the whole course BFM uses. It works,
      //    but it asks whoever reads it to know why.
      @(negedge clk);
      en_el_flanco_opuesto = d_out;
```

- The BFM wrapped **the protocol**. What it did **not** wrap is *when* it
  drives and *when* it samples: that is still decided task by task
- Three ways of reading the same data: `0`, `11` and `11`. Two values, but **three
  mechanisms**, and the middle one depends on a `#1` that is visible nowhere
- The `@(negedge clk)` of our BFM is the third one. It works — and it asks whoever
  reads it to know why

Note:
Run this live, it takes two seconds: `make u2/clocking`. The three lines
it prints are the whole slide.
The first one is the surprising one and it is worth explaining slowly: sampling **on**
the `posedge` gives the **old** value, because the DUT's `always_ff` updates with
a nonblocking assignment and that one lands after this `initial` already
ran. It is not a Verilator bug and not an oddity: it is the LRM region order,
and it is the same on Questa.
The second one is the worst of the three, and it is the one to mark as a silent trap:
it works, and it works **by accident**. The `#1` does not say which problem it solves,
it is not documented, and the day somebody deletes it because "it did nothing" the
testbench keeps compiling and starts lying. It is the same `#1` as the scoreboard of
the conventional testbench, and the difference is a single one: there the slide says
which race it avoids. An explained `#1` is a patch that knows it is a patch; a loose
`#1` is the trap.
And the third is ours. Worth being honest with the group: the course drives on
`negedge` and samples on `posedge` because it is the trick you can understand without having
seen clocking blocks, not because it is what gets written on a project.

---

## Interfaces and BFM

#### *Why the edge alone is not enough: the regions*

![The regions of an edge: Preponed, Active and NBA, and the three samples that give different values](../res/diagrams/en/interfaces-bfm_regiones.svg)

- An edge is not an indivisible instant: inside it there are **regions**, in a fixed order
- The `<=` of the `always_ff` **lands in NBA**: whoever reads in *Active* reads the old value
- The `#1` crosses the NBA, the opposite edge crosses it with room to spare, and
 SVA needs neither of the two: it samples in *preponed*, before everything

Note:
This figure is the one to leave on screen while reading the three samples of the
previous slide. Without it the explanation is *"the old value"*, which sounds like
a quirk of the simulator; with it, it is a consequence of the order, and the order
is in the LRM.
The scheduler has more regions than the four in the drawing —`docs/clocking-blocks.md`
(in Spanish) lists them all— but these are enough to explain the three cases, and adding the
others changes no answer.
The question worth asking the group before showing the answer: if the DUT writes in
NBA and your `initial` wakes up in Active, which one runs first? That is where it
shows on its own why sampling **on** the edge gives the value from before.
And the hook with day 7: the amber bar on the left is the region where SVA samples.
It is the same figure that explains why an assertion does not check what happened
but what it saw, and why the `@()` you give it changes the result.

---

## Interfaces and BFM

#### *The clocking block: the edge and the delta, declared once*

```sv
interface reg_bfm (input bit clk);
   byte unsigned d_in, d_out;

// The only two timing lines in the testbench:
   //   input  #1step  samples the STABLE value right before the edge, which is
   //                  what the hardware sees. Never what the nonblocking
   //                  assignment just wrote on that same edge.
   //   output #0      drives ON the edge, in the nonblocking region, so the DUT
   //                  does not see it until the next edge.
   clocking cb @(posedge clk);
      default input #1step output #0;
      output d_in;
      input  d_out;
   endclocking

modport tb (clocking cb);
endinterface : reg_bfm
```

- `input #1step` — sample the value **stable just before** the edge, which is
 the one the hardware sees. Never the one the nonblocking assignment just wrote
- `output #0` — drive **on** the edge, with the nonblocking assignments, so the DUT does not
 see it until the next edge
- Driving becomes `cb.d_in <= value`; sampling, reading `cb.d_out`; waiting,
 `@(cb)`. **No `#1` in any task**
- And the value read is the same at any point of the cycle: the race got
 closed by declaration, not by habit

Note:
This is the slide you have to be able to repeat in an interview, because
`clocking block` is one of the first things people get asked and the good answer
is not "it synchronizes": it is **it declares the sampling and driving instant once,
in the interface, so that no task picks it again**.
The detail that confuses and is worth previewing: in the example you need **three**
`@(cb)` to see the 11, and not two. One for the `output #0` to put the data,
another for the DUT to take it, and the third because the `input #1step` samples what is
stable **before** the edge. The arithmetic is in plain sight in the code and does not
depend on the simulator — which is exactly the difference with the `#1`.
If somebody asks why the course does not use it from day 1: because to
understand which problem it solves you have to have had the problem. Only now,
with the BFM written and the three lines running, does the question make sense.
Verilator supports it since 5.x and the example ends in `$fatal` if the
sampling stops giving 11: it is the safety net that warns if a release changes the semantics.

---

## Interfaces and BFM

#### *Are they mandatory? No — and it is worth knowing why*

| The question | The answer |
| --- | --- |
| Can a correct TB be written **without** clocking blocks? | **Yes.** With NBA in the driver and scheduler discipline, there is no race |
| What should **a team** use? | **Use them** on synchronous interfaces — it is what the lowRISC/OpenTitan style guide says |

- They are not UVM's: they are **SystemVerilog's**. UVM neither asks for them nor knows them
- **Dave Rich** —the reference at Verification Academy— has held since 2014 that
  they are *optional*: what avoids the race is understanding the scheduler, not the
  clocking block
- The two positions answer different questions: one is **language
  correctness**, the other is **team policy**. Both are right

Note:
This slide is the one that keeps the course from lying by simplifying, and it is worth
spelling out: *"always use clocking blocks"* is a style rule,
not a theorem. Whoever repeats it as if it were the latter is in for an
uncomfortable argument with the first senior they run into.
Dave Rich's sentence that orders the topic —and it is worth quoting verbatim— is from 2014:
*"If you are already familiar with Verilog testbenches, then you probably don't
need them."* He held it in 2022 and in 2024. It does not say they are wrong: it says they are not
a **necessary condition**.
And on the other side is lowRISC, which in OpenTitan's DV Coding Style Guide makes them
mandatory for synchronous signals. They do not contradict each other: Dave answers
*"can I?"* and lowRISC answers *"what do we all do here?"*. It is exactly the
difference between well-used `malloc`/`free` and a style guide that mandates
smart pointers — an expert being able to manage memory by hand does not make
RAII useless.
Where they really move the needle, and this is what to retain: **reusable** agents and VIP
—whoever writes them is far from whoever uses them—, gate-level
with SDF, and protocols where the spec defines setup/hold. There they stop being style.
The long material, with the sources, is in `docs/clocking-blocks.md` (in Spanish).

---

## Interfaces and BFM

#### *The price: two names for the same wire*

```sv
      // The two reads, at the SAME instant, on the SAME wire.
      por_cb = bfm.cb.d_out;
      crudo  = bfm.d_out;

$display("at the same instant, on the same wire:");
      $display("  bfm.cb.d_out (what the clocking block sampled) : %0d", por_cb);
      $display("  bfm.d_out    (the live wire)                   : %0d", crudo);
      $display("");
      $display("They differ by one cycle, and no warning says so. A monitor that");
      $display("reads through the clocking block and a scoreboard that reads the");
      $display("raw wire do not fail every time: they fail when the data changes.");
```

- With the signal inside a clocking block there are **two** ways of reading it:
  `bfm.d_out` is the live wire, `bfm.cb.d_out` is what got sampled
  `#1step` before the edge
- On a signal that changes every cycle they **differ by one cycle**: the example
  prints `3` and `4`, at the same instant and on the same wire
- Nobody warns you. It compiles, it runs, and the scoreboard fails **only when the data
  changes**
- The rule: if a signal went into the clocking block, **the whole protocol reads it
  through there** — and you wait on `@(bfm.cb)`, not on `@(posedge bfm.clk)`

Note:
This is the flip side of the previous slide and the reason the course does not use
them in its BFM: used badly they are **worse** than not using them, because
the failure mode is intermittent and the waveform looks fine.
The real mistake, the one that shows up in the forums, has two shapes and it is worth
naming both. One is mixing the event: `@(posedge vif.clk)` and then reading
`vif.cb.foo`. The other is mixing the access: the monitor reads `vif.cb.data` and the
scoreboard —or an assertion, or a debug `$display`— reads `vif.data`. Both
end the same way: two temporal views of the same wire, and a mismatch that
shows up once every twenty runs.
Worth running the example and leaving the number in plain sight: `3` and `4`. Nobody argues
with a `3` and a `4` on the same wire.
And the moral that hooks into the silent traps appendix, where this one
is written down: in verification the expensive error is not the one that breaks, it is the one that
lies. A half-done clocking block lies.

---

## Interfaces and BFM

#### *Summary of the unit*

- An `interface` is a **bundle of named signals**: adding a wire stops
  being touching six port lists
- A **BFM** is the interface **plus the protocol**: `send_op(A, B, op, result)`
  translates *"do an addition"* into the signal wiggling
- All the fine print of the spec —the reset pulse, waiting for `done`, the
  `no_op` that does not answer— ends up written **once**
- From here on **nobody moves `bfm.start` by hand**. Whoever wants an operation
  asks for it
- The tester, the scoreboard and the coverage become **separate modules**, each
  one in its file, connected by the BFM
- And this does not get abandoned: the agent's driver keeps calling
  **this same task**
- The rule the BFM **complies with** can also be **checked**, with an assertion
  that lives in this same interface. That is the assertions section
- And the **`clocking block`** closes the last hole: the edge and the delta
  stop being decided task by task and get declared **once**

Note:
This is the most important section of day 1 and the one that looks least like it. Everything that
comes after —classes, factory, agents, sequences— rearranges pieces **above**
this line. The line itself never gets touched again.
The short way to say it: from here on the testbench stops talking in
wires and starts talking in operations. That is the first step towards UVM, and it is
already taken, without having written a single class.
If the group comes from RTL, the analogy closes on its own: the BFM is to the testbench what
a device driver is to the operating system.

## Review · Day 1

#### *1 of 7 · The question of the day*

**A thousand random operations, the scoreboard reported no error and the log ends in `PASS`. What are you missing to say the DUT is verified?**

- [ ] Nothing: a thousand operations without an error is a verified DUT
- [ ] Running more seeds until code coverage reaches 100 %
- [x] Knowing what the log would have said with a bug inside: run it with the mutated DUT
- [ ] Replacing the scoreboard with assertions, which check the protocol on the exact edge and not at the end

> **Watch it fail** — the `PASS` of a scoreboard that never saw an error says nothing: it may not have compared. `VTALU_BUG=1` flips one bit of the result and the testbench has to fail; `make mutante` demands it for the three testbenches of days 1 and 2.

---

## Review · Day 1

#### *2 of 7 · The ALU spec*

**While the VTALU is running an operation, what do `start` and the operands have to do?**

- [ ] `start` drops right away: it is a start pulse, and the DUT already latched everything
- [ ] It makes no difference: the DUT registers them on the first edge
- [ ] The operands have to change on every cycle
- [x] `start` at 1 and the operands still until `done` goes up

> **Stable until `done`** — it is the DUT protocol, and it is exactly the reason the BFM exists: to wrap that rule in a single place so that no test forgets it. The first distractor describes a real protocol —pulse start, latched operands— that this DUT does not have.

---

## Review · Day 1

#### *3 of 7 · Functional coverage*

**The test runs 1000 random operations and the *code* coverage reads 100 %. What does that tell you about the verification?**

- [ ] That the DUT is verified and the verification plan can be closed
- [ ] That the testbench has no bugs
- [ ] That few scenarios are missing: 100 % already walked the whole design
- [x] Very little: it measures the RTL that ran, not the spec

> **Very little** — code coverage measures the DUT; functional coverage measures the spec. A feature the designer never wrote gives 100 % of lines and 0 % of what matters, and the report is not going to tell you.

---

## Review · Day 1

#### *4 of 7 · covergroup*

**You declare a `covergroup`, you `new()` it, you run a thousand operations and the report reads 0 %. What is the first thing to look at?**

- [x] That nobody is calling `sample()`
- [ ] That the bins are badly defined and match no value at all
- [ ] That the DUT is not answering
- [ ] That `ignore_bins` are missing

> **The `sample()`** — a covergroup does not sample itself: somebody has to call it, on the edge or when a transaction arrives. Without that call the code compiles, runs, and the report reads 0 without a single warning.

---

## Review · Day 1

#### *5 of 7 · Interfaces and BFM*

**What does the testbench gain when the protocol moves into a BFM?**

- [x] It stops talking in signals and starts talking in operations
- [ ] It simulates faster: one BFM task costs the simulator less than moving wires
- [ ] The testbench becomes synthesizable
- [ ] You save having to declare a `clk`

> **It stops talking in signals** — the BFM translates *one operation* into *a handshake of signals*. The tester never touches a wire again; the scoreboard and the coverage keep reading them, through the interface, until a monitor sends them transactions. It is the first step towards UVM.

---

## Review · Day 1

#### *6 of 7 · The verification plan*

**In the verification plan, what goes in the *Measure* column?**

- [ ] How long the scenario takes to run, so the regression can be estimated
- [ ] The name of the testbench file that covers that row
- [x] Which bin gets filled when the scenario happens
- [ ] How many times the test has to be run to call it covered

> **Which bin gets filled** — the five columns are *Feature*, *Scenario*, *Stimulus*, *Check* and *Measure*, and this is the one that costs the most: it forces you to decide **beforehand** what is going to be counted. If it is left empty, nobody is going to find out that the scenario never happened — a case the random never touched and that has no bin is indistinguishable from one that happened a thousand times.

---

## Review · Day 1

#### *7 of 7 · clocking block*

**Are clocking blocks needed to write a UVM testbench without races?**

- [ ] Yes: without a clocking block, driver and DUT always compete on the same edge
- [ ] Yes, and they are also part of the UVM library
- [x] No: NBA in the driver plus scheduler discipline is enough
- [ ] No: the `uvm_driver` replaces them, since it already samples in the right region

> **They are not needed, and they are worth using anyway** — they belong to **SystemVerilog**, not to UVM, and no `uvm_driver` samples for you. What avoids the race is understanding the scheduler: a driver that drives with `<=` against a DUT that registers with `<=` is already deterministic. The clocking block does not replace that understanding, it **wraps** it — and that is where it pays off: reusable agents, VIP, gate-level and protocols with setup/hold in the spec.

## Exercise · Day 1 · 1 of 2

#### *A new operation, end to end*

`cd code/ejercicios/d1 && bash run.sh`

- The VTALU has a **free opcode**, `3'b110`. Teach it to shift, and
  teach the TB that it has to verify it too
- It gets touched in **three** places: the RTL, the stimulus with its check, and **the
  measure** — the bin that does not exist today
- The `run.sh` fails until it prints `EXERCISE OK` **and the report closes with
  77 covered bins**; the solution is right next to it

Note:
Half an hour, and it is worth leaving them alone: the statement and the README are enough.
The guaranteed stumble is the width: the hardware shifts by `B[2:0]`, not by
the whole `B`, so with `B = 8'h20` it shifts zero places and not thirty-two. The
scoreboard model has to do the same or the TB they wrote themselves
is going to accuse them. It is warned about in the README, and it still happens.
The third step is the most skipped one and the only one that fails **silently**:
`bins single_cycle[]` covers the range `[add_op : xor_op]`, which reaches up to
`3'b100`. `shr_op` falls outside every bin, the simulation passes green and
— here is the worst part — the report still says **100 %**: 76 out of 76. The
missing bin does not lower the percentage because it never made it into the
denominator. There is the lesson that holds for the rest of the course: an opcode
nobody measures is an opcode nobody verified, and the percentage is precisely the
metric that cannot see it.
With the solution it is 77 out of 77, starting from 86.8 % (66 out of 76). The ten
that were missing were a single one: the bucket Verilator invents for `3'b110`, the
value the enum did not have — and the shift is precisely `3'b110`, so it fills it
along the way. Worth showing both numbers and not only the percentage: that is why
the `run.sh` demands, on top of the 100 %, that `single_cycle` has one more bin: a
half-done job reaches the 100 % too.

## Exercise · Day 1 · 2 of 2

#### *The waves: when the log is not enough*

`cd code/ejercicios/d1b && bash run.sh`

- The run aborts with **a single line**: `FAILED: A: e5  B: 0  op: mul_op
  result: fe01 ovf: 0`. `e5 * 00` is `0`, not `fe01`. The scoreboard is right,
  and so is the DUT: what got it wrong is the BFM's **handshake**
- That is where what the log gives you ends. The `run.sh` leaves **`ondas.vcd`** next to it:
  `gtkwave ondas.vcd`
- **Stage 1:** two times that only exist in the viewer, in `respuesta.txt`.
  **Stage 2:** the line of the BFM that explains them
- It is the only exercise of the course that is **not solved by reading the log**

Note:
Half an hour, and it is the exercise that justifies the debug appendix: there it says that
the waves are the tool 47 % of the work gets done with, and up to here
the course had not made them use one even once.
The bug is a protocol one and it is the same one that comes back in the capstone: `send_op`
**counts edges** instead of waiting for the handshake. For single-cycle operations it
makes no difference; the multiplication takes four, so `send_op` returns too
early, the next stimulus overwrites `A` and `B`, and when `done` finally goes up the
scoreboard compares the new operands against the old result.
That is why the two times stage 1 asks for are not bureaucracy: the second is the
`done` of the first multiplication, and whoever looks for it in the viewer **sees** that
`A` and `B` have already changed. That is the answer to the *why*, and there is no way to
read it in the log.
The question to throw at the group when they finish: if the multiplier went
from four edges to five, which of the two versions of `send_op` finds out?
Neither counts right; only the one that waits for `done` keeps working. It is literally the
clue of the APB wait state of day 7.
And this is the 47 % from the trends slide, seen up close: the log says
*failed* and for the *why* you have to go somewhere else. Today that somewhere
else is the waves; on day 3, in reporting, it is the log that learns to say it.

## Six out of seven, again

#### *Closing the day*

- The regression that sent the bug to the fab said `PASS`. Today you have three
  ways of knowing whether that `PASS` was worth anything, and all three are
  columns of one table
- **What had to be tested?** A plan: one row per scenario, written before the
  testbench, from the spec
- **Who said it was right?** A scoreboard that predicts and compares — and that
  you watched fail with a bug inside
- **How much of the plan passed?** A `covergroup` with one bin per row, and the
  per-bin report, not the percentage
- The tester already asks for operations instead of moving wires: that was the
  BFM. What you still cannot do is **change the stimulus without editing the
  file**. Tomorrow is that

Note:
Thirty seconds, and they are the ones that close the arc of the day: the first
slide asked a question and this one answers it with what the student wrote,
not with theory. If the group is tired, put the 14 % slide back up for a second
before this one: the question was *"how do you know you verified?"*, and the
short answer is *"I have the plan, I watched it fail and I know which bin is
missing"*.
What not to over-promise: this does not prevent the respin. What it prevents
is sending to the fab a `PASS` nobody knew the meaning of.
The last bullet is the one day 2 opens with *"Yesterday we left…"*: a tester
that only multiplies is copying the file and deleting five lines. That is the
problem classes solve, and it is worth leaving as a problem and not as a
promise.

## Yesterday we left…

#### *Where the testbench stands*

- A testbench that **works**: it sends stimulus, checks the result and measures
  functional coverage. The verification plan says which row each thing closes
- The BFM took the signals inside an `interface`, and the testbench went on to
  call `send_op()` instead of moving wires
- And one problem was left open: **changing the stimulus means editing the
  file**. A tester that only multiplies is copying the one that is there and
  deleting five lines

Note:
Thirty seconds, and they are not filler: day 2 is the most abstract of the course
and it starts without touching the VTALU all morning. The student has to walk in
knowing this is the answer to something that already happened to them yesterday.
The bullet to underline is the third one, because it is the problem the whole
unit solves. If the group comes from a previous class, it is enough to ask *"how
did you make a tester that only multiplies yesterday?"* and wait for the answer
—copy and delete— before moving on to the agenda.
If it is taught on video, this is the slide that replaces the week of distance
between one chapter and the next.

---

## Agenda

#### *Day 2 · ≈ 4 h · unit 3 · the OOP UVM takes for granted*

- Classes and extensions
- Polymorphism
- Static variables and methods
- Parameterized classes
- The factory pattern
- A testbench without a single module

**By the end of the day you can:**

- **Extend** a class and change its behaviour **without copying it**, and say
  what `super` does
- **Change** the class a testbench uses **without touching** the code that uses
  it, with a factory
- **Write** the day 1 testbench without a single module

Note:
Day 2 is the only one that does not touch the VTALU all morning, and that is why
it is worth putting the three verbs up front: they are the answer to *"what is
this for?"*, which is the question that shows up half an hour in.
The third one is the one that closes the day and the one practised in the
exercise. The first two are rows 6 and 7 of the closing self-assessment.

## Classes and extensions

#### *Why OOP in a testbench?*

- The conventional testbench is a **module**: it gets elaborated once, it exists from
  `time 0` until the `$finish`, and it is always the same one
- A stimulus looks nothing like that: it shows up, it travels through the testbench,
  it gets compared and it gets thrown away. That is not a module, it is an **object**
- Modules = *structure*, they get elaborated. Classes = *data and behaviour*, they
  get created and destroyed while the simulation runs
- And it is not optional: **UVM is a class library**. `uvm_test`,
  `uvm_component`, `uvm_object`. Without this, the rest of the course cannot be read

Note:
Here is the real wall of the course, and it is not UVM: it is OOP. Whoever arrives
from RTL has never written a class, and from the tests on everything is classes.
If the group comes from software, this unit goes fast and you gain time for
day 3. If it comes from RTL, it is the unit where you spend whatever time is
left over, even if you have to take it from somewhere else.
The question that orders everything: does this exist all the time or does it show up
and leave? The first is a module; the second, an object.

---

## Classes and extensions

#### *What a `struct` cannot do*

```sv
typedef struct {
   int length;
   int width;
} rectangle_struct;

typedef struct {int side;} square_struct;

module top_struct;
   rectangle_struct rectangle_s;
   square_struct    square_s;
   initial begin
      rectangle_s.length = 50;
      rectangle_s.width = 20;
      $display("rectangle area: %0d", rectangle_s.length * rectangle_s.width);
      square_s.side = 50;
      $display("square area: %0d", square_s.side ** 2);
   end
endmodule
```

- The `struct` holds data and **nothing else**: the area calculation has to be written
  outside, and again in every place where it is needed
- `square_struct` has no relationship at all with `rectangle_struct`, even though a
  square is a particular case of a rectangle
- It does not randomize itself, it does not compare itself, it does not print itself

Note:
It is worth starting by asking what is wrong with the `struct`, because the spontaneous
answer is "nothing" — and they are right: for holding three fields it works perfectly. The
course is not here to say the `struct` is wrong, it is here to say where it falls
short.
The three bullets are three different things and it is worth separating them. The first one
is **cohesion**: the data is here and the operation on the data is in another file,
so nothing forces them to agree. The second is **inheritance**: a
square *is* a rectangle and the language has no way of saying so, so it gets
copied and pasted. The third is the one you pay for on day 5: a `command_s` does not
know how to randomize itself or compare itself against itself, and all of that has to be
written outside, once for every place that uses it.
The honest punchline, so that nobody leaves with a religious idea: the `command_s` of the
conventional testbench **is** a struct, it works, and it was fine while the
testbench was a module. What changes is the scale.

---

## Classes and extensions

#### *The first class: data, methods and constructor*

```sv
class rectangle;
   int length;
   int width;

function new(int l, int w);
      length = l;
      width = w;
   endfunction

function int area;
      return length * width;
   endfunction
endclass : rectangle

module top_rectangle;

rectangle rectangle_h;

initial begin

rectangle_h = new(.l(50), .w(20));

$display("rectangle area: %0d", rectangle_h.area());

end
endmodule : top_rectangle
```

- The class puts the **data** (`length`, `width`) together with **what gets done with
  it** (`area()`). The area gets computed in a single place
- `new()` is the *constructor*: it runs once, when the object gets created
- `.l(50)` is argument passing **by name**. UVM uses it all the time

Note:
The comparison with the previous slide is the whole class: the same two fields,
plus a function that used to live loose. Worth pointing at `area()` and saying that that is
the entire difference — the data and what gets done with the data travel together.
`new()` is worth presenting without mystery: it is an ordinary function, with a
reserved name, that the simulator calls on its own when the object gets created. It returns
the handle. It does nothing magic and there is no destructor on the other side.
Passing by name looks cosmetic and it is not: when the constructor has
five arguments —and `uvm_component`'s has two that are **always** the same—
`.l(50)` is what makes the call readable without going to look up the signature.
The whole of `code/` in the course is written that way.
And the question to leave hanging, the one the next slide answers: if I
declare `rectangle r;` and I never call `new()`, how many objects are there?

---

## Classes and extensions

#### *A handle and an object are not the same thing*

```systemverilog
rectangle rectangle_h;               // 1. a HANDLE. No object yet: it is null
rectangle_h = new(.l(50), .w(20));   // 2. new() creates the OBJECT and returns its handle
```

- Declaring a handle **creates nothing**. Until the `new()` it is `null`, and using it
  there blows up at simulation time, not at compile time
- The handle looks like a pointer, but it takes no arithmetic: there is no `h + 1`
- The memory of a `struct` the simulator reserves the moment it sees it; that of an
  object, only at the `new()`
- And there is no `free()`: when no handle is left pointing at it, the object gets
  collected on its own

Note:
The null pointer is THE mistake of the first week, and Verilator's message does not
help: it tells you that you dereferenced null, not where the `new()` was missing.
It is worth writing the two lines on the board and asking how many objects there
are after each one. The answer is zero and one.
This comes back twice more in the course: in the class hierarchies, when `obj1_h = obj2_h`
copies the handle and not the object; and in the tests, when the virtual interface that was
not read from the config_db is left at null.

---

## Classes and extensions

#### *Extending: `extends` and `super`*

```sv
class rectangle;
   // Data members
   int length;
   int width;

function new(int l, int w);
      length = l;
      width = w;
   endfunction

function int area();
      return length * width;
   endfunction
endclass

// Extending classes!
class square extends rectangle;
   // Override Constructor
   function new(int side);
      // super: the call to the parent method
      super.new(.l(side), .w(side));
   endfunction

endclass
```

- `square extends rectangle` inherits `length`, `width` and `area()` **without copying
  a single line**. A square is a rectangle with a constraint, and the code says it
  that way
- The child's constructor calls `super.new()`: the top part of the object
  also has to be built, and it goes **first**
- Extending is not copying: if tomorrow `area()` changes, it changes for both

Note:
The constructor order is the first thing to nail down, because it is mandatory and
it fails badly: `super.new()` goes **before** anything else of the child. The reason
is physical — the object is a single one, and the part the base class contributes has to
be built before touching anything. If you forget it, SystemVerilog calls it on its own
when the base constructor takes no arguments, and it does not compile when it does
take them. On day 3, `uvm_component`'s takes them.
The last bullet is the whole argument of the unit and it is worth saying with an
example: if `area()` changes tomorrow, in the `struct` version you have to remember
both places; here it changes in one and the other finds out on its own. That "finds out
on its own" is what inheritance buys you, and it is the same promise the `env` makes
to the tests on day 3.
And the warning about where this is heading, so that the word does not turn up cold on the
next slide: inheriting lets the child *use* what belongs to the parent. What still cannot
be done is for the parent to call the child's version — that is polymorphism, and it is the
section that follows.

---

## Classes and extensions

#### *Where all of this comes back*

| What you have just seen | What it is called in UVM |
| --- | --- |
| class with data and methods | `uvm_object` — the *transactions* of day 5 |
| class that also lives in the TB tree | `uvm_component` — driver, monitor, scoreboard |
| `new()` | the constructor, with `name` (and `parent` if it is a component) |
| `extends` | every test, every tester, every agent of the course |
| `super.new()` | the mandatory first line of every UVM constructor |

- One piece is missing: storing a `square` object in a `rectangle` variable.
  That is the unit that follows

Note:
Close with the table and not with the example: the student has to leave knowing that
this was not a programming detour, it was the vocabulary of the rest of the course.
The last bullet leaves the door open to polymorphism, which is the only thing
missing before a factory can be read.
And one single thing more before moving on: **declaring a handle creates
nothing**. Until the `new()` it is `null`, and using it there is the mistake that
repeats the most in the whole week. It comes back three times —here, in the tests
with the virtual interface that was not read from the `config_db`, and in the
hierarchies when `obj1_h = obj2_h` copies the handle and not the object— so it is
worth naming it all three.

## Polymorphism

#### *A `trago` variable, a `fernet` object: which `servir()` runs?*

![trago, fernet and mojito: which servir() lives in which class](../res/diagrams/en/uml-poli.svg)

- A `fernet` **is** a `trago`, so storing it in a `trago` variable
  compiles and is legal
- The question is the other one: when you call the method through that variable, does
  SystemVerilog look at the **type of the variable** or at the **type of the object**?
- The default answer is the one you do not want, and the word that changes it is
  a single one

Note:
It is the concept that holds up everything that comes: the factory, the overrides, the
transactions. Whoever gets lost here loses the rest of the course, so it is not worth
moving on until everybody sees why the variable can be of the base class.
It is worth taking a vote before showing the code: "what does it print?". Half the
room says *"Fernet"*, and seeing that they are wrong is what fixes the concept.
And warn about it before they ask: in SystemVerilog `virtual` is
overloaded — virtual method, virtual class and virtual interface are three different
things. Here it is the first one.

---

## Polymorphism

#### *The three classes: a `trago` that does not know how to serve itself*

```sv
class trago;
   int hielos = -1;

function new(int a);
      hielos = a;
   endfunction : new

function void servir();
      $fatal(1, "A generic trago cannot be served: order a real one.");
   endfunction : servir

endclass : trago

class fernet extends trago;

function new(int hielos);
      super.new(hielos);
   endfunction : new

function void servir();
      $display("Fernet: 70/30, and the coke last");
   endfunction : servir

endclass : fernet
```

- `trago` defines `servir()` with a `$fatal`: the base class does not know what it
  gets served with, and it says so loudly
- `fernet` and `mojito` extend `trago` and **redefine** `servir()`, each one
  with its own
- `mojito` —which does not fit on the screen— is the same as `fernet`, with another
  `$display`

Note:
The `$fatal` in the base class is a pattern you see a lot and that in this same section
we are going to replace with something better: if the method cannot be implemented here, the
right thing is not to explode in simulation, it is not to let it compile.
That the three classes have a method with the same name and the same signature is what
makes everything that follows possible. Now it remains to decide **which one runs**, and that
is not yet said anywhere in the code.
The whole file is in `code/u3/polimorfismo/01-sin-virtual/not_virtual.sv`.

---

## Polymorphism

#### *Without `virtual` the variable rules, and that breaks*

```sv
      fernet_h = new(15);
      fernet_h.servir();
      $display("The fernet has %0d ice cubes", fernet_h.hielos);

mojito_h = new(1);
      mojito_h.servir();
      $display("The mojito has %0d ice cubes", mojito_h.hielos);

// The variable is trago, the object is fernet.
      trago_h = fernet_h;
      trago_h.servir();  // ** Fatal: A generic trago cannot be served
      $display("The trago has %0d ice cubes", trago_h.hielos);

trago_h = mojito_h;
      trago_h.servir();
      $display("The trago has %0d ice cubes", trago_h.hielos);
```

- The first two calls work: the variable `fernet_h` is of type `fernet` and so is
  the object
- The third one **explodes**. `trago_h` points at a `fernet`, but since the method is
  not virtual, SystemVerilog resolves at **compile time** by the type of the
  variable, and calls `trago`'s `servir()`
- It is called *static binding*: the decision of which code to run is already taken
  before the object exists

Note:
This is worth running: `bash code/u3/polimorfismo/01-sin-virtual/run.sh`. The example
ends in `$fatal` on purpose, and the `run.sh` gives PASS precisely when that
message shows up.
The question that always comes: "and why does `hielos` come out right?". Because
fields are never virtual: the variable sees the fields of its own type, and
`hielos` is in `trago`. Methods are the only thing that can be resolved by
object, and only if you ask for it.

---

## Polymorphism

#### *Virtual methods: one word, and now the object rules*

```sv
   virtual function void servir();
      $fatal(1, "A generic trago cannot be served: order a real one.");
   endfunction : servir
```

- It is the **only** difference between `01-sin-virtual` and `02-virtual`: the keyword
  `virtual` on the method of the base class
- With that the call gets resolved at **simulation time**, looking at the object inside
  the variable — *dynamic binding*
- `trago_h.servir()` now serves a fernet or a mojito, without whoever wrote
  that line knowing which one they are going to get
- That is the whole idea: **whoever uses the object stops being the one who picks the type**

Note:
Worth running the two examples one after the other and showing the diff: one word.
A detail that always gets asked: `fernet` and `mojito` do **not** write `virtual`
on their `servir()`, and they are virtual all the same. Once the method is virtual in
the base, it is virtual for all of its descendants. Writing it anyway does no harm and plenty
of people do it out of tidiness.
The rule of thumb for the rest of the course: in verification, **every method you might
want to redefine goes virtual**. UVM does it that way — `build_phase`,
`run_phase`, `do_copy`, `do_compare` are all virtual, and that is why the override
of the env works.
The cost exists and it is real —a method table and an indirect jump— but in a
testbench you are never going to measure it. In synthesizable RTL there are no classes, so
the discussion does not apply.

---

## Polymorphism

#### *Abstract classes: moving the error to compile time*

- The `$fatal` of `trago` finds out **late**: it compiles, it runs, and it explodes in the
  middle of the simulation. In an overnight regression that is a lost run
- SystemVerilog allows declaring an **abstract class** —`virtual class`—: it only
  serves as a base, **it cannot be instantiated**
- Inside it can declare **pure virtual methods**: methods with no body
- Extending the class **forces** you to redefine them. If not, it is a **compile
  error**
- The error did not go away: it moved to a moment where it comes out cheap

Note:
This is the slide to leave clear, because the criterion repeats through the whole
course: *the sooner it fails, the better*. Compile time better than simulation,
simulation better than silicon.
In verification a compile error is **good news**: the overnight regression
does not get lost, and whoever broke something finds out in a minute.
Where it is going to show up again: `uvm_object` and `uvm_component` are declared
`virtual class` in the library, so they are abstract by right. What `` `uvm_component_utils ``
does **not** do is force you to implement anything: the other way round, it *provides*
`get_type_name()` and the registry's `type_id`. The real `pure virtual` in UVM is
`uvm_subscriber::write()`, which you are going to have to write no matter what on day 4.
And in the day 3 exercise, the `virtual class base_tester`.

---

## Polymorphism

#### *`pure virtual`: the same example, with no `$fatal` possible*

```sv
// Abstract class: it only works as a base, it cannot be instantiated.
virtual class trago;
   int hielos = -1;

function new(int a);
      hielos = a;
   endfunction : new

// pure virtual: no body. Extending it forces you to redefine it.
   pure virtual function void servir();

endclass : trago
```

- `virtual class trago` no longer has a `servir()` that explodes: **it has no
  body**, and that is why there is nothing that can run wrong
- The commented-out line of the `top` —`trago_h = new(3)`— does not compile: an
  abstract class does not get instantiated
- If you delete `mojito`'s override, the compiler says *"Class 'mojito' extends
  'trago' but is missing implementation for 'servir'"* and that is the end of it

Note:
The point is not the `$fatal`, it is **when you find out**: without an abstract class it
explodes in the middle of the simulation, with pure virtual it does not compile.
Worth doing live: comment out `mojito`'s `servir()` and compile. The
compiler message is the one that teaches.
And the hook forward: the factory uses this to create, and the `env` for the
overrides. What today is a fernet and a mojito, tomorrow is going to be a
`base_tester` and the testers that extend it — same mechanics, another vocabulary.

---

## Polymorphism

#### *Summary of the unit*

- **Without `virtual` the variable rules**, and it is decided at compile time.
  **With `virtual` the object rules**, and it gets resolved during simulation.
  One word, and it changes everything
- The underlying idea, the one that comes back in every section that follows: **whoever
  uses the object stops being the one who picks the type**
- In SystemVerilog `virtual` is **overloaded**: virtual method, virtual
  class and virtual interface are three different things — and in UVM you are
  going to write all three

Note:
It is the unit that unlocks the next half of the course, and it is worth saying so:
without polymorphism there is no factory, there is no `uvm_component` that can serve as a
base, and there is no override. Everything else is plumbing.
Forgetting `virtual` is also the trap of the day 2 exercise —`get_op()`
is declared without `virtual` on purpose—, so if somebody asks about it here,
do not give it away: it is understood much better by suffering it.

## Static variables

#### *The global variable you can actually defend*

- In a testbench there is always something there is **only one of**: the error counter,
  the list of in-flight transactions, the handle to the configuration
- The easy answer is a global variable, and it is the one nobody can debug
  afterwards: you do not know who wrote it, or from where, or when
- `static` is the same idea, but with a last name attached. The variable lives **in the class**, not
  in the object, and to touch it you have to name the class: `bandeja_de_fernet::vasos`
- That `::` is the whole argument. The day the value looks odd, a grep tells you
  exactly who put it there
- And it is not a loose OOP topic: the **factory** and the **`uvm_config_db`** are the
  two most important static variables of a UVM testbench

Note:
The question that orders the unit: what is there only one of in a testbench? The
factory, the configuration database, the error counter. All of that in UVM
is `static`, and that is why you write `uvm_config_db#(T)::set(...)` with a double
colon and without instantiating anything.
And the second half, which is the one you take to work: `static` solves the
"where it lives", not the "who touches it". That one is solved by `protected` plus access
methods, which is the third slide. A public `static` is a global variable
with a longer prefix.

---

## Static variables

- `bandeja_de_fernet` has no methods and no constructor: it is a class that exists **only**
  to be the place where the queue lives
- Nobody instantiates it. It gets named with the `::` operator, which tells the
  compiler *"look this variable up in the namespace of that class"*
- And there is the advantage over the global: `bandeja_de_fernet::vasos` says where it is
  declared. A loose `vasos` does not

```sv
class bandeja_de_fernet;
   // Static queue
   static fernet vasos[$];

endclass : bandeja_de_fernet

module top;
   initial begin
      fernet fernet_h;
      fernet_h = new(2, "the one at table 7");
      // :: operator
      //----------------
      //   The variable in the bandeja_de_fernet class is reached by
      //   naming the class and putting the :: operator before the name
      //   That tells the compiler we want a static variable inside
      //   the namespace of the class
      bandeja_de_fernet::vasos.push_back(fernet_h);
      fernet_h = new(3, "the one at table 4");
      bandeja_de_fernet::vasos.push_back(fernet_h);
      fernet_h = new(15, "the one at the bar");

// class::static_variable. You know right away where it is declared
      bandeja_de_fernet::vasos.push_back(fernet_h);

$display("Fernets on the tray:");
      foreach (bandeja_de_fernet::vasos[i]) $display(bandeja_de_fernet::vasos[i].get_name());
   end
endmodule : top
```

Note:
Put plainly: static is the global variable you can actually defend in a code
review. It lives in the class, not in the object.
The second slide shows why it has to be encapsulated with static methods: if
you leave it public, the day you swap the queue for another structure you have to
touch the whole testbench.

---

## Static variables

- There is **a single** copy in memory, no matter how many objects get instantiated
- And it exists even if none gets instantiated: the `static` does not wait for the `new()`

```sv
class pepe;
   static    int    cant;
   int    val = -1;

function new(int a);
      // Static Variable
      cant++;
      val = a;
   endfunction : new

endclass : pepe

//----------------------------------------
module top_pepes;
   initial begin
      pepe pepe1_h, pepe2_h;

pepe1_h = new(10);
      pepe2_h = new(254654);

$display("PEPE1 VAL = %0d", pepe1_h.val);
      $display("PEPE2 VAL = %0d", pepe2_h.val);

// There is only one copy of a static variable in memory,
      // no matter how many instances of the class exist
      $display("NUMBER OF PEPES = %0d", pepe::cant);

end
endmodule : top_pepes
```

***And what about encapsulation?***

Note:
`pepe::cant` counts how many objects got created, and the detail to point out is
that **the counter exists even if there is not one object**. A `static` does not
wait for the `new()`: it is there from the moment the simulation starts. That is why it
works for counting instances, and that is why it cannot be initialized with anything that
depends on an object.
A good question to throw out: if `cant` gets incremented in the constructor, what happens
if somebody extends `pepe` and forgets the `super.new()`? It does not count. It is the same
topic as classes and extensions seen from another side.
The question on the slide is on purpose: `cant` is public, and anybody in the
testbench can write it. Leaving that discomfort hanging in the air for a while is what
makes the next slide make sense.

---

## Static variables

#### *Static methods*

- In the two previous examples the queue was out in the open, so the day it gets
  swapped for another structure you have to go and fix the whole testbench
- The version that survives a code review is two words: the variable
  `protected`, and **static access methods** that are the only door
- It is the same thing UVM does with the factory: nobody touches the type dictionary, you
  ask it with `type_id::create()`

```sv
class bandeja_de_fernet;

protected static fernet vasos[$];

static function void bandeja_fernet(fernet l);
      vasos.push_back(l);
   endfunction : bandeja_fernet

static function void lista_fernets();
      $display("Fernets on the tray:");
      foreach (vasos[i]) $display(vasos[i].get_name());
   endfunction : lista_fernets

endclass : bandeja_de_fernet

module top;

initial begin
      fernet fernet_h;
      fernet_h = new(2, "the one at table 7");
      bandeja_de_fernet::bandeja_fernet(fernet_h);
      fernet_h = new(3, "the one at table 4");
      bandeja_de_fernet::bandeja_fernet(fernet_h);
      fernet_h = new(15, "the one at the bar");
      bandeja_de_fernet::bandeja_fernet(fernet_h);
      bandeja_de_fernet::lista_fernets();
   end

endmodule : top
```

Note:
The difference between the two versions is two words —`protected` in front
of the queue and `static function` on the accessors— and it changes who can break what.
In the first one, any line of the testbench can `push_back` onto the
queue; in this one, only `bandeja_fernet()`.
The argument is not purism: it is that now `vasos` can be swapped for an associative
array, for a `uvm_tlm_fifo` or for whatever, without going out to fix the whole
testbench. Encapsulating is being able to change your mind later.
A syntax detail that confuses: a `static` method **cannot** touch
instance variables, only `static` ones. It makes sense —it gets called without an object,
so there is no `this`—, but the simulator's error message does not put it that way.
And the hook: UVM's `type_id::create()`, which they are going to write a hundred times
from the env on, is exactly this — a static access method to a static
structure.

---

## Static variables

#### *Summary of the unit*

- **A single copy** no matter how many objects you instantiate, **it exists even
  if you instantiate none**, and to touch it you have to name the class with `::`
- That `::` is the whole argument: the day the value looks odd, a `grep` tells you
  who put it there. But `static` solves *where it lives*, not *who touches it* —
  that one is `protected` plus static access methods
- Where it comes back: `uvm_config_db#(T)::set(...)` and `type_id::create()`, the
  two most important static variables of a UVM testbench

Note:
The hook worth leaving served: `uvm_config_db#(T)::set(...)` gets written
with a double colon and without instantiating anything, and now they know why. Same for
`type_id::create()`, which they are going to write a hundred times from the env on — it is
exactly a static access method to a static structure.
The question that orders the unit and works as a review: what is there only one of in a
testbench? The factory, the configuration database, the error counter.
All of that is `static`, and not by accident.

## Parameterized classes

#### *It is not a class: it is a mould*

- The `bandeja_de_fernet` of the previous section works for fernets. For mojitos you have to
  write another one just like it, with one word changed
- You already solved that in RTL and you do not call it OOP: a FIFO does not get copied for
  every data width, it gets parameterized. `#(.awidth(8), .dwidth(16))`
- A parameterized class is the same thing, with **types** instead of numbers:
  `bandeja #(fernet)` and `bandeja #(mojito)`
- And there is a consequence that surprises: every different `#(...)` is a **different
  class**, generated at compile time. They share nothing, not even the `static`
- Why it matters: every `#(...)` you see in the rest of the course is this.
  `uvm_analysis_port #(T)`, `uvm_subscriber #(T)`, `uvm_sequence #(T)`

Note:
Starting from Verilog's `parameter` is deliberate: the RTL student already knows how to
parameterize, only with widths. Here the parameter is a type, and the rest is
the same.
What has to be left crystal clear before moving on is the third bullet, because
it is question 6 of the review and because it is the base of all of UVM:
`bandeja#(fernet)` and `bandeja#(mojito)` are **not the same class with a
different field**. SystemVerilog generates a whole class for every combination of
parameters, at compile time. That is why each one has its own `static` queue.
The short way of saying it: the parameterized class is not a class, it is the recipe
for manufacturing classes. The class appears when you write the `#(...)`.
And a limit worth naming now so that it does not surprise them: since it gets
resolved at compile time, the type has to be known there. You cannot pick the
parameter at runtime. Picking at runtime is what the factory solves, which is the
unit that follows.

---

## Parameterized classes

- Before the new syntax, the parameter you already know: a RAM that does not get
  copied for every width, it gets instantiated with `#(.awidth(8), .dwidth(16))`
- Every instantiation with different parameters produces **different hardware**, and
  nobody argues about it
- *Parameterized class definitions* are that same thing on the software side, with
  one difference: the parameter can be a **type**

```sv
module RAM #(
    awidth,
    dwidth
) (
    input wire [awidth-1:0] address,
    inout wire [dwidth-1:0] data,
    input we
);

initial $display("awidth: %0d  dwidth %0d", awidth, dwidth);
   // code to implement RAM

//...

endmodule  // RAM

module top;
   wire [ 7:0] address;
   wire [15:0] data;
   wire        write_enable;
   RAM #(
       .awidth(8),
       .dwidth(16)
   ) my_ram (
       address,
       data,
       write_enable
   );
endmodule  // top
```

Note:
It is worth saying what we are going to use them for, otherwise it looks like a loose OOP
topic: `uvm_analysis_port#(T)`, `uvm_subscriber#(T)`, `uvm_tlm_fifo#(T)`. Every `#(...)`
that shows up in the rest of the course is this.

---

## Parameterized classes

- Version with static methods: the tray does not get instantiated, you ask it with `::`
- The queue is `static` and even so there are **two**: `bandeja#(fernet)` and
  `bandeja#(mojito)` are two different classes, each one with its own

```sv
// Parameterized class
// the T (type) parameter is what says which
// kind of queue this is.
class bandeja #(
    type T
);

protected static T vasos[$];

static function void bandeja_trago(T l);
      vasos.push_back(l);
   endfunction : bandeja_trago

static function void lista_tragos();
      $display("Drinks on the tray:");
      foreach (vasos[i]) $display(vasos[i].get_name());
   endfunction : lista_tragos

endclass : bandeja

module top;

initial begin
      fernet fernet_h;
      mojito mojito_h;
      fernet_h = new(15, "the one at the bar");
      bandeja#(fernet)::bandeja_trago(fernet_h);
      fernet_h = new(15, "the one at table 4");
      bandeja#(fernet)::bandeja_trago(fernet_h);

mojito_h = new(1, "the one at table 7");
      bandeja#(mojito)::bandeja_trago(mojito_h);
      mojito_h = new(1, "the one at the counter");
      bandeja#(mojito)::bandeja_trago(mojito_h);

$display("-- Fernets --");
      bandeja#(fernet)::lista_tragos();
      $display("-- Mojitos --");
      bandeja#(mojito)::lista_tragos();
   end

endmodule : top
```

Note:
This is the slide where the mould thing gets demonstrated, and it is worth doing it by
running the example: two fernets and two mojitos go in, and each `lista_tragos()` prints
only its own. The queue is `static` and even so there are two.
The question for the board: how many queues are there in memory? Two. And how many
would there be with three drinks? Three. Every `bandeja#(X)` the compiler sees in
the code generates its class, with its own `static`. The ones nobody uses do not exist.
A detail that always gets asked: `T` is not declared anywhere as
"trago or derivatives". SystemVerilog has no such constraint — the check is
by use. If you put in a type that has no `get_name()`, the error shows up when
compiling the specialization, not when declaring the class, and the message points
inside `bandeja`. It is confusing the first time.

---

## Parameterized classes

#### *Variables with parameters*

- Here the tray gets instantiated like any object and you have to have the handle to
  use it — it stops being visible from the whole testbench
- It does exactly the same thing as the previous version. What changes is the scope,
  and that is the decision: **`static` when there really is only one, instantiated
  when there can be more than one**

```sv
module top;

// Since bandeja is not static, it has to be instantiated
   // the parameter is a variable type
   // Using a type that does not have the get_name()
   // method is a syntax error
   fernet fernet_h;
   mojito mojito_h;

bandeja #(fernet) bandeja_de_fernet;
   bandeja #(mojito) bandeja_de_mojito;

initial begin
      bandeja_de_fernet = new();
      fernet_h = new(15, "the one at the bar");
      bandeja_de_fernet.bandeja_trago(fernet_h);
      fernet_h = new(15, "the one at table 4");
      bandeja_de_fernet.bandeja_trago(fernet_h);

bandeja_de_mojito = new();
      mojito_h = new(1, "the one at table 7");
      bandeja_de_mojito.bandeja_trago(mojito_h);

mojito_h = new(1, "the one on the sidewalk");
      bandeja_de_mojito.bandeja_trago(mojito_h);

$display("-- Fernets --");
      bandeja_de_fernet.lista_tragos();
      $display("-- Mojitos --");
      bandeja_de_mojito.lista_tragos();
   end

endmodule : top
```

Note:
The two versions do exactly the same thing and the difference is one of design, not of
syntax: in the previous one the tray is global —anybody in the testbench sees it—; in
this one you have to have the handle to be able to use it.
The rule you take to work: **static when there really is only one in the
whole testbench, instantiated when there can be more than one**. And when in doubt,
instantiated: it is easier to add a second object than to take the `static` off
something half the testbench already uses.
With that in hand, place UVM: the `uvm_config_db` is static because there is only
one. A `uvm_analysis_port#(command_transaction)` is instantiated because each
monitor has its own. The student already has the criterion to read both.

---

## Parameterized classes

#### *Summary of the unit*

- A parameterized class **is not a class**: it is the recipe. And every different
  `#(...)` is a **different class**, which shares nothing with the others —
  **not even the `static`**
- The limit: it gets resolved **at compile time**, so the type has to be known
  there. Picking at runtime is the section that follows
- Where it comes back: `uvm_analysis_port #(T)`, `uvm_subscriber #(T)`,
  `uvm_sequence #(T)` — every `#(...)` in the rest of the course is this

Note:
The bullet about the different classes is the one to leave nailed down, because it is
the review question and because it is the base of all of UVM. `bandeja#(fernet)` and
`bandeja#(mojito)` are not the same class with a different field: they are two
whole classes, each one with its own `static`.
And the last bullet places the section: the `uvm_config_db` is static because there is
only one; a `uvm_analysis_port#(command_transaction)` is instantiated because
each monitor has its own. With that they can already read both.

## The factory pattern

#### *Who decides the type?*

- Every `new()` you write is a **hardcoded** decision: that line is always going
  to build that class, and to change it you have to edit it and recompile
- In a testbench that does not scale. You want the same `env` sending additions today and
  multiplications tomorrow, picked from the command line
- The parameterized classes of the previous unit are not enough either: the `#(...)` gets
  resolved at compile time, and here the decision has to happen **at runtime**
- The factory is the answer: instead of building it yourself, you **ask** for the object
  from somebody who knows which type to hand over
- It is the most visible pattern of UVM, and with it you understand `type_id::create()` and
  `set_type_override()`, which are going to be in every file of the rest of the course

Note:
The sentence that orders the unit: **whoever uses the object stops being the one who picks
the type**. Everything else is implementation detail.
It is worth saying up front where this ends, because otherwise it looks like a programming
detour: the `+UVM_TESTNAME=add_test` of the tests, tomorrow, is going to be a factory —
UVM reads a string from the command line and builds the class that corresponds.
Here you see the mechanism from the inside.
And for whoever comes from software: yes, it is the GoF Factory Method, and we
invented nothing. The Python version that closes the section is there precisely for that.

---

## The factory pattern

- A design pattern, not a language feature: a class whose only job
  is to **build objects for you**
- You ask it for an object by describing which one you want —a string, an enum— and it
  hands it back already built, of whichever subtype corresponds
- Before the solution, the problem. Look at what happens when the `new()` is
  written in the place where the object gets used:

```sv
// ILLUSTRATION -- not compiled. In the previous example, new() gets called every
// time an object is needed: building a new set of drinks means editing the source.
bandeja_de_fernet = new();
fernet_h = new(15, "the one at the bar");
bandeja_de_fernet.bandeja_trago(fernet_h);
fernet_h = new(15, "the one at table 4");
bandeja_de_fernet.bandeja_trago(fernet_h);

bandeja_de_mojito = new();
mojito_h = new(1, "the one at table 7");
bandeja_de_mojito.bandeja_trago(mojito_h);

mojito_h = new(1, "the one on the sidewalk");
bandeja_de_mojito.bandeja_trago(mojito_h);

// Consider the case where a set of random drinks has to be read from a file
// dynamically.
//    --> Doing that with NON hardcoded code is impossible
//        You would need a script that generates the source, recompile it...
```

> *The idea is to create data of random types without changing the code.*

Note:
The problem first, the pattern after: I want to change the type of object that gets
created without touching the code that creates it. With that in your head, UVM's factory
—the env— is the same idea wrapped in macros.
The Python version is next to it on purpose: it shows whoever comes from software
that we invented nothing.

---

## The factory pattern

![cantina builds fernet and mojito, and returns a trago handle](../res/diagrams/en/factory_diagram.svg)

- **The factory** is the method at the top: it takes an argument and returns an object
  of the type that argument asks for
- **Polymorphism** is what makes it possible: `fernet` and `mojito` extend
  `trago`, so both fit in a `trago` variable
- Without the second there is nowhere to put what the first returns. They are the two
  halves of the same tool

Note:
The factory **does not work without polymorphism**, and it is worth saying it
that way: if `hacer_trago()` could not return a `fernet` stored in a `trago`
variable, there would be nothing to manufacture. They are the two halves of the same thing.
The useful question about the diagram: what type is the thing `hacer_trago()`
returns? `trago`, always. What changes is which object comes
inside. The caller never finds out, and that is exactly the point.
And the limit you see right away: if the caller needs something only `fernet` has
—the `sin_hielo` of the example— the comfort is over and you have to cast.
That is the next slide, and it is the reason UVM's factory is better than
this one.

---

## The factory pattern

- `virtual` is enough as long as you use methods the base class already declares. But
  `fernet` adds a field of its own —`sin_hielo`— that `trago` knows nothing about
- To reach it you have to bring the handle down to its real type, and that is `$cast`:
  it converts the variable of the second argument to the class of the first
- It checks **at runtime** and returns 0 if it does not work, so it never goes alone: always
  inside an `if` with its `$fatal`

```sv
//*********************************************************************
// Part of the factory Class!
//*********************************************************************
class cantina;

// Static method that builds the drinks
   static function trago hacer_trago(string pedido, int hielos, string name);
      mojito nuevo_mojito;
      fernet nuevo_fernet;
      case (pedido)
         "fernet": begin
            nuevo_fernet = new(hielos, name);
            return nuevo_fernet;
         end

"mojito": begin
            nuevo_mojito = new(hielos, name);
            return nuevo_mojito;
         end

default: begin
            $fatal(1, {"No such drink: ", pedido});
            return null;
         end

endcase  // case (pedido)

endfunction : hacer_trago

endclass : cantina
```

- And `$cast` in use, in the `top`: the factory always returns a `trago`, and
  to reach `sin_hielo` you have to bring it down to `fernet`

```sv
      // Using the factory!
      trago_h = cantina::hacer_trago("fernet", 15, "the one at the bar");
      trago_h.servir();

// Reaching a member of fernet (derived from trago) through a trago variable
      // requires casting it to fernet.
      if (!$cast(fernet_h, trago_h)) $fatal(1, "Could not cast trago_h to fernet_h");

if (fernet_h.sin_hielo) $display("And on top of that it comes warm!");
      bandeja#(fernet)::bandeja_trago(fernet_h);

if (!$cast(fernet_h, cantina::hacer_trago("fernet", 2, "the one at table 4")))
         $fatal(1, "Could not cast the cantina drink to fernet_h");
```

Note:
Two things about this code, and both come back in UVM.
The first: `$cast` **checks at runtime and returns 0**, it does not abort. That is why in the
example every call goes inside an `if (!$cast(...)) $fatal(...)`. A `$cast`
without a check is the `assert(randomize())` of the transactions in another disguise: if
it fails, you carry on with a handle at `null` and the error shows up three lines later, in
another place.
The second: look at the `case (pedido)` of `hacer_trago()`. To add a new drink
you have to **edit the factory**. In other words we took the hardcoding out of whoever uses it
and put it in a single place — better, but it is still there.
There is what UVM solves, and it is worth saying so: `` `uvm_component_utils ``
registers the class **on its own**, so UVM's factory has no `case` to
maintain, and `type_id::create()` returns the right type without anybody casting.
Both annoyances of this slide disappear in the env.

---

## The factory pattern

#### *Python Style*

```python
class Trago:
    """Factory class that builds a Trago."""

@staticmethod
    def factory(kind):
        """Factory Method."""
        if kind == "CubaLibre":
            return CubaLibre()
        if kind == "Fernet":
            return Fernet()
        if kind == "Mojito":
            return Mojito()
        if kind == "Whiscola":
            return Whiscola()
        raise ValueError("No such trago: " + kind)
```

- The same factory, in a language that has nothing to do with hardware: a
  static method with an `if` per type and a `raise` for what does not exist
- And the same annoyance: adding a drink forces you to **edit the factory**
- The whole file is in `code/u3/factory/factory.py` and it runs with `python3`:
  it generates twenty drinks at random and serves them all the same way

Note:
It is there on purpose and the moral is short: this is not a verification oddity,
it is a design pattern from 1994 that in Python takes ten lines.
The bottom part of the file is worth opening if there is time left: `Trago.__subclasses__()`
asks the language which classes inherit from `Trago`, and with that the generator no
longer needs a hand-written list. It is exactly what UVM's factory registration does
with `` `uvm_component_utils ``, but from the top down instead of
each class signing itself up.
The punchline: the final loop treats the twenty drinks the same, without asking what
type they are. That is polymorphism, and it is what makes a factory
worth anything.
The slide works for two opposite audiences. For whoever comes from software it lowers
the suspicion —"ah, it is the same old factory"—. For whoever comes from RTL it shows
that what they are learning is not "weird SystemVerilog stuff": it is
programming, and you can go and read about it outside the EDA world.

---

## The factory pattern

#### *Summary of the unit*

- Every `new()` is a **hardcoded decision**. The factory moves it to runtime:
  instead of building, you **ask** for the object from somebody who knows which
  type to hand over
- **It does not work without polymorphism** —somebody who manufactures and a base
  variable to store it in are both needed— and the **`$cast` returns 0** instead
  of aborting, so it never goes alone: always inside an `if` with its `$fatal`
- Where it comes back: `` `uvm_component_utils `` **registers the class on its
  own** —the `case` you have just written by hand— and `+UVM_TESTNAME` picks it
  from the command line

Note:
Closing of the most abstract section of day 2, and it is worth landing it with what
is coming: the `+UVM_TESTNAME=add_test` of the tests **is a factory** —
UVM reads a string from the command line and builds the class that corresponds.
Here they saw the mechanism from the inside, a day early.
The sentence that sums up the whole section: **whoever uses the object stops being the
one who picks the type.** Everything else is implementation detail.
And for whoever comes from software: it is the GoF Factory Method, from 1994, and in
Python it takes ten lines. We invented nothing, and that is good news.

## A testbench without a single module

#### *The same testbench, without a single module*

- This section **adds no functionality**:
  it verifies the same as the interfaces and BFM testbench
- What changes is what it is made of. The three modules —tester, scoreboard,
  coverage— become three **classes**, and the `initial` becomes a method
- The piece that binds them appears: a `testbench` class that instantiates the others,
  hands them the BFM and launches their threads. Nobody instantiates it for you
- It is the **last version without UVM**, and that is why it is worth looking at closely: everything
  this class does by hand, from the tests on the library is going to do
- The question to walk out of the section with: *which part replaces which?*

Note:
The real goal of the section is not to teach anything new, it is to leave a point of
comparison. If the student can look at `testbench.svh` and say "this is the env,
this is the build_phase, this is the run_phase", day 3 starts downhill.
It is worth writing the table on the board before showing the code, and coming back to it
at the end of day 3:

And say out loud what can be seen on its own: there is not a single `module` in the classes of the
testbench. The modules were left for the DUT, the clock and the interface — which is
precisely what gets synthesized.

---

## A testbench without a single module

- A testbench of modules works until it has to be reused: to change the
  stimulus you have to edit the module, and to have two versions you have to copy it
- With classes, changing the stimulus is **extending a class**, and the two versions
  live side by side. That is all OOP buys you here

#### *The VTALU TB, piece by piece*

- top: Instantiates the testbench class
- testbench: Top-Level Class
- tester: Generates the stimulus
- scoreboard: Checks that the VTALU is working
- coverage: Captures the functional coverage information

![The object tree of the testbench without modules: top elaborates, and inside live the testbench class and its three pieces](../res/diagrams/en/tb-en-objetos_arbol.svg)

Note:
It is the same testbench as interfaces and BFM, but in objects: what changes is the shape, not
what it does. If possible, show them side by side.
The drawing is the one to be able to redraw from memory at the end of the day, and
the line that splits it in half is the one that matters: above, what gets
**elaborated** —the module, the DUT, the interface—; below, what somebody has to
**create**. An object nobody creates is a null handle, and that is the mistake of
the first afternoon.
It is the last version without UVM. From the tests on the same thing gets assembled by UVM, and the
student has to be able to say which part replaces which.

---

## A testbench without a single module

#### *The top: the only thing that is still a module*

- The `top` is still a module, and it is going to stay that way until the end of the
  course: classes do not get elaborated, somebody has to exist before time 0
- It imports the package with the classes, instantiates the DUT and the BFM, and declares the
  handle to the `testbench`
- Inside the `initial`, two lines: `new(bfm)` and `execute()`

```sv
module top;

// Class definitions and shared resources are kept in a package
   import vtalu_pkg::*;
   // The macros are defined in common too. UVM does this as well
   `include "vtalu_macros.svh"

// The DUT and the BFM get instantiated
   vtalu DUT (
       .A(bfm.A),
       .B(bfm.B),
       .op(bfm.op_set),
       .clk(bfm.clk),
       .reset_n(bfm.reset_n),
       .start(bfm.start),
       .done(bfm.done),
       .ovf(bfm.ovf),
       .result(bfm.result)
   );

vtalu_bfm bfm ();

// A variable to hold our TB
   testbench testbench_h;

initial begin
      // The testbench object gets built and launched
      testbench_h = new(bfm);
      testbench_h.execute();
   end

endmodule : top
```

Note:
The `top` is still a module and it is going to stay that way until the end of the course,
even with UVM. The reason is that **classes do not get elaborated**: somebody has to
exist before time 0 to instantiate the DUT, the interface and the clock.
The detail to point a finger at is how the BFM gets passed: here it gets
handed to the constructor, `new(bfm)`, and it works because the `top` knows the class.
In UVM that line is not going to exist — the test gets created by the factory and nobody can
pass it arguments. That is why the `uvm_config_db` shows up in the tests.
A good question to leave hanging: why is the package `import` before
everything else? Because the classes live in a package and the module has to see them. It is the
first time the compilation order matters, and it will not be the last.

---

## A testbench without a single module

#### *The `testbench` class: the one that assembles and starts*

- There is **one** object above everything else that instantiates the others, hands them what
  they need and launches their threads. Every OOP testbench has one
- Here we write it by hand: three `new()` and a `fork ... join_none`
- From the `env` on that class is going to be called `uvm_env`, the `new()` are going to be
  `type_id::create()` in the `build_phase`, and the `fork` UVM is going to do on its own

```sv
class testbench;

// virtual: the object-world equivalent of a module's port list. It tells
   // the compiler that this variable is going to receive a handle to an
   // interface at some point in the future. See the slide in the TB-in-objects section.
   virtual vtalu_bfm bfm;

tester    tester_h;
   coverage  coverage_h;
   scoreboard scoreboard_h;

function new(virtual vtalu_bfm b);
      bfm = b;
   endfunction : new

task execute();
      tester_h = new(bfm);
      coverage_h = new(bfm);
      scoreboard_h = new(bfm);

// One thread per object. join_none: execute() returns and the three go on.
      fork
         tester_h.execute();
         coverage_h.execute();
         scoreboard_h.execute();
      join_none
   endtask : execute
endclass : testbench
```

Note:
This is the class UVM is going to replace, so it is worth reading it line by
line: `new()` on the three objects, `fork ... join_none` to start them, and
that is it. That is an `env` written by hand.
Two things to flag. The first is the `virtual vtalu_bfm bfm`: the word
`virtual` here has **nothing to do** with the virtual methods of polymorphism.
A virtual interface is a handle to an interface that is going to be assigned later
on — it is the equivalent, in the world of objects, of the port list of a
module. It is the third meaning of `virtual` in SystemVerilog and that is why it is worth
naming it out loud.
The second is the `join_none`: the three objects run in separate threads and
`execute()` returns right away. If it were `join`, the testbench would wait for the
three to finish and the scoreboard never finishes. It is the same decision UVM
takes on its own when it runs a `run_phase` per component.
And one that always gets asked: who ends the simulation? The tester's `$finish`, inside
`execute()`. It is ugly and it shows: one object decides for everybody. In
the tests that becomes an objection, which is the tidy form of the same thing.

---

## A testbench without a single module

#### *The `tester` class: the stimulus, with no wires*

- It sends a thousand random operations, with the same bias to the edges as the conventional
  testbench: the goal is still to fill the bins of the covergroup
- Against the modular version two things change and nothing else:
  - the BFM arrives through a **variable** —a *virtual interface*— instead of through a
    port list
  - the `initial` is now a method, `execute()`, that somebody has to call

```sv
   // The initial block is replaced by an execute() task
   task execute();
      byte unsigned     iA;
      byte unsigned     iB;
      shortint unsigned result;
      operation_t       op_set;
      bfm.reset_alu();
      op_set = rst_op;
      iA = get_data();
      iB = get_data();
      bfm.send_op(iA, iB, op_set, result);
      op_set = mul_op;
      bfm.send_op(iA, iB, op_set, result);
      bfm.send_op(iA, iB, op_set, result);
      op_set = rst_op;
      bfm.send_op(iA, iB, op_set, result);
      repeat (1000) begin : random_loop
         op_set = get_op();
         iA = get_data();
         iB = get_data();
         bfm.send_op(iA, iB, op_set, result);
         $display("%2h %6s %2h = %4h", iA, op_set.name(), iB, result);
      end : random_loop
      $finish;
   endtask : execute
```

Note:
There is a trap here **put in on purpose** and it is worth not giving it away now: look at the
declaration of `get_op()`. It says `protected function`, not `protected virtual
function`. Without `virtual`, `execute()` is always going to call this class's one,
even if the object is of a derived class — which is exactly what they saw in
polymorphism with `servir()`.
That is the day 2 exercise, and it is good that they walk into it: inheritance does not
show until somebody writes `virtual`, and that is understood much better by
suffering it than by reading it.
The other thing to point out is what is **not** in this class: the protocol.
`reset_alu()` and `send_op()` still live in the BFM, the same as in interfaces and BFM,
and the tester calls them with `bfm.send_op(...)`. That is the whole point of the BFM and
that is why it holds without changes until the end of the course: the class above asks for an
operation, and it does not even know a `done` exists.
And the detail you see at the start of `execute()`: the four directed
operations before the `repeat (1000)` are not decoration. They are the reset, the
multiplication after the reset and the repeated mult — that is, three rows of the
verification plan of the conventional testbench that the random should not be left to wait for.

---

## A testbench without a single module

#### *The scoreboard: the `always` became a task*

- A sensitivity list does not exist in a class. What replaces it is a
  `forever` with the wait inside — same semantics, written as sequential
  code

```sv
   // The always @(posedge done) of the modular version, as a forever loop: an
   // object has no sensitivity list, it has a task that blocks.
   task execute();
      shortint predicted_result;
      bit      predicted_ovf;
      forever begin : self_checker
         @(posedge bfm.done) #1;
         case (bfm.op_set)
            add_op: predicted_result = bfm.A + bfm.B;
            sub_op: predicted_result = bfm.A - bfm.B;
            and_op: predicted_result = bfm.A & bfm.B;
            xor_op: predicted_result = bfm.A ^ bfm.B;
            mul_op: predicted_result = bfm.A * bfm.B;
         endcase  // case (op_set)

// ovf belongs to sub and to nobody else: with 8-bit inputs and a 16-bit
 // output, neither the addition nor the multiplication can overflow.
 predicted_ovf = (bfm.op_set == sub_op) && (bfm.A < bfm.B);

if ((bfm.op_set != no_op) && (bfm.op_set != rst_op))
            if (predicted_result != bfm.result || predicted_ovf != bfm.ovf)
               $error(
                   "FAILED: A: %0h  B: %0h  op: %s result: %0h ovf: %0b",
                   bfm.A,
                   bfm.B,
                   bfm.op_set.name(),
                   bfm.result,
                   bfm.ovf
               );

end : self_checker
   endtask : execute
```

Note:
The translation to point out: the `always @(posedge done)` of the modular
testbench is a `forever begin @(posedge bfm.done) ... end` here. It is the same
wait, written as sequential code inside a method. An object has no
sensitivity list; it has a task that blocks.
The `#1` of the first line is one of those details that get paid for dearly: without it, the
scoreboard reads the signals at the very instant `done` goes up and can
eat a delta race. With it, it reads when everything has settled. It is the
reason verification samples on the edge the design does **not** use.
And what this scoreboard still does wrong, to leave it hanging: it reads the operation
off the **wire** (`bfm.op_set`) at the moment of the result. It works because the
protocol forces the operands to stay stable, but it is fragile — the day
the DUT has several operations in flight, it breaks. In the analysis ports the scoreboard
is going to compare against a queue of commands the monitor sends it, and that does
scale.

---

## A testbench without a single module

#### *The `coverage` class: the covergroup inside an object*

```sv
  // In a class, we don't need to declare variables to hold the covergroups, but we do need
  // to call a constructor to create them.
   function new (virtual vtalu_bfm b);
     op_cov = new();
     zeros_or_ones_on_ops = new();
     bfm = b;
   endfunction : new

task execute();
      forever begin  : sampling_block
         @(negedge bfm.clk);
         A = bfm.A;
         B = bfm.B;
         op_set = bfm.op_set;
         op_cov.sample();
         zeros_or_ones_on_ops.sample();
      end : sampling_block
   endtask : execute
```

- The covergroup is **the same** as the conventional testbench's, line by line. What changed is
  where it lives
- In a module, declaring the covergroup was enough. In a class it has to be
  built: the class's `new()` does `op_cov = new()`
- The `execute()` is the `always @(negedge clk)` from before, written as a `forever`:
  it copies the BFM signals and calls `sample()`

Note:
The `op_cov = new()` inside the constructor is the trap of the slide: in a
module the covergroup gets instantiated on its own, in a class it does **not**. If you forget it, the
code compiles, it runs, and the report says 0 %. It is the same silent trap as the conventional testbench's, with one more turn of the screw.
The transition bins are still inside `` `ifndef VERILATOR ``, the same as in the conventional testbench, and for the same reason: Verilator 5.052 still does not compile them.
What has to be said before the analysis ports: here the sampling happens on the **clock
edge**, that is, cycles get counted. When the `coverage` is a subscriber it
is going to sample when **a command arrives**, and there operations get counted —
which is what the verification plan asked for from the conventional testbench on.

---

## A testbench without a single module

#### *The map of day 3: what replaces what*

| Here, by hand | From the tests on |
| --- | --- |
| `testbench.execute()` with three `new()` | the `build_phase` of the `env` |
| passing the BFM through the constructor | `uvm_config_db` |
| `fork ... join_none` | UVM runs one `run_phase` per component |
| `$finish` inside the tester | objections |
| picking the tester by editing the code | `set_type_override` of the factory |
| `$display` that gets put in and deleted | `` `uvm_info `` and the verbosity ceiling |

- This is the **complete** testbench, without UVM and with nothing missing. It works
- Everything that comes on day 3 replaces one row of this table, **and nothing else**
- We come back to this slide at the close of the day, to cross them out

Note:
This is the slide worth writing down, because it is the whole map of day 3.
The strong claim has to be made explicit: **UVM adds no functionality
here**. The testbench of this unit does everything the env's is going to do. What it adds is convention — that the left-hand column is solved
the same way in every testbench in the world.
And the honest question that is going to come up: "so what for?". So that whoever
joins the project knows where to look without reading the whole testbench, and so that the
new tester costs four lines instead of a class. Both benefits are of
scale, and that is why in a hundred-line example UVM looks like too much — it has to be
said that way, instead of selling smoke.
At the close of day 3, with the `env` and the override already seen, you come back here and read
the right-hand column straight through. That is where the day closes on its own.

---

## A testbench without a single module

#### *Summary of the unit*

- The day 1 testbench **without a single module**: the same three pieces, plus
  the class that binds them —`testbench`—, which is the direct ancestor of the
  `uvm_env`
- The `top` is still a **module** and it will be until the end, and the BFM
  arrives through a **virtual interface**: it is the only way a class has of
  touching signals
- It is the **last version without UVM**. From here on, every piece we write by
  hand has a class of the library that replaces it — `execute()` is going to be
  the `run_phase`

Note:
The slide to close the whole of day 2 with, because it leaves the bridge
built. The question to leave posed: *which part replaces which?*
Day 3 answers it piece by piece, and it starts downhill if the student walks out
of here able to draw the object tree on the board.
And the argument for why the whole day was worth it: with modules, changing the
stimulus is editing the file. With classes it is extending a class, and the two
versions live side by side. That is the exercise that follows.

## Review · Day 2

#### *1 of 8 · Handle and object*

**`rectangle rectangle_h;` — after that line, how many objects are there?**

- [x] None: `rectangle_h` is `null` until somebody calls `new()`
- [ ] One, with `length` and `width` at 0
- [ ] One half built: the fields exist but the constructor has not run
- [ ] It depends on whether the class has a constructor

> **None** — declaring a handle reserves nothing. There is the difference with a `struct`, which the simulator reserves the moment it sees it. And using the handle before the `new()` does not fail at compile time: it blows up in the middle of the simulation.

---

## Review · Day 2

#### *2 of 8 · Polymorphism*

**A variable of type `trago` holds a `fernet` object. If `servir()` is not `virtual`, what gets executed?**

- [ ] `fernet`'s `servir()`
- [ ] A compile error
- [x] `trago`'s `servir()`
- [ ] Both, the base class one first

> **`trago`'s** — without `virtual`, SystemVerilog looks at the **type of the variable**, not at the object's. It is literally what `code/u3/polimorfismo/01-sin-virtual` prints: *"A generic trago cannot be served"*.

---

## Review · Day 2

#### *3 of 8 · Abstract classes*

**What do I gain by using an abstract class with `pure virtual` methods instead of a base class whose method does `$fatal`?**

- [ ] Nothing, it is a matter of style
- [x] That the error moves from simulation to the compiler
- [ ] That the base class can be instantiated
- [ ] That the simulator can pick the most specific override at run time

> **The error moves to the compiler** — with `$fatal` you find out halfway through the simulation that an override was missing. With `pure virtual` it does not compile. Catching it earlier is always cheaper.

---

## Review · Day 2

#### *4 of 8 · Static variables*

**I instantiate 10 objects of a class that has a `static` variable. How many copies are there in memory?**

- [ ] 10, one per object
- [ ] 0 until somebody writes it: the memory is reserved on first access
- [x] 1, shared by every instance
- [ ] It depends on the simulator

> **A single one** — and it exists even if you instantiate no object at all. That is what makes it useful for global TB data, and what makes it dangerous if you leave it public.

---

## Review · Day 2

#### *5 of 8 · Static methods*

**Why is it worth declaring the static variable `protected` and exposing it with static methods?**

- [x] To be able to change the data structure without touching whoever uses it
- [ ] Because a `static` without `protected` is reserved once per instance
- [ ] So that it takes up less memory
- [ ] Because UVM demands it

> **To be able to change it later** — if the queue is out in the open, the day you swap it for another structure you have to go and fix every place that touched it. Encapsulating is being able to change your mind.

---

## Review · Day 2

#### *6 of 8 · Parameterized classes*

**`bandeja#(fernet)` and `bandeja#(mojito)` have a `static` queue inside. Do they share the queue?**

- [ ] Yes, `static` is a single one for everybody
- [ ] Yes: the parameter changes the type of the methods, not the static storage
- [ ] It depends on whether they get instantiated or not
- [x] No: each specialization is a different class, with its own queue

> **They do not share it** — SystemVerilog generates **one class per combination of parameters**. `static` is unique inside each one of those classes, not across all of them. UVM leans on this all the time.

---

## Review · Day 2

#### *7 of 8 · The factory pattern*

**What problem does the factory pattern solve?**

- [ ] Creating objects faster
- [x] Deciding at run time which subtype to build
- [ ] Avoiding having to declare classes
- [ ] Centralizing the `new()`s in one class, to be able to count and free them

> **Deciding the subtype at runtime** — without hardcoding the `new`: you ask the factory for an object and it decides which one. It is the piece that is later going to let you change the stimulus of a whole test without touching the code of the `env`.

---

## Review · Day 2

#### *8 of 8 · $cast*

**When does a `$cast(destination, source)` succeed?**

- [ ] Always: it converts any class into any other
- [ ] Only between classes with no inheritance
- [ ] When the two classes have the same fields, even if they are not related
- [x] Only if the object in `source` is of the class of `destination` or of a derived one

> **Only if the object allows it** — `$cast` checks **at runtime** and returns 0 if it does not work. That is why UVM's factory is more comfortable than the `cantina` of the section: `type_id::create()` returns the right type and saves you the cast.

## Yesterday we left…

#### *Where the testbench stands*

- The day 1 testbench **without a single module**: three classes, one that binds
  them, and a `top` that only instantiates the DUT and the BFM
- The BFM gets into the classes through a **virtual interface**, which is the
  only way a class has of touching signals
- And the factory is already written **by hand**: a `case` that has to be edited
  every time a new type shows up. Today the one you do not edit shows up

Note:
Day 3 is where UVM walks in, so the recap has an extra job: making it clear that
what is coming **replaces** pieces the student already wrote, and is not a pile
of new pieces to learn from scratch. The whole unit can be read as "this thing
you did by hand, the library brings it done".
The third bullet is the hook: the `case` of `060` is exactly what
`` `uvm_component_utils `` does on its own, and saying it here stops the macro
from being a magic formula.

---

## Agenda

#### *Day 3 · ≈ 4 h 30 · unit 4 · UVM walks in*

- Tests
- Components and phases
- The env: structure and stimulus
- Reporting: verbosity and *actions*

**By the end of the day you can:**

- **Explain** why a UVM simulation ends at `t=0` if nobody raises an objection
- **Say** why `build_phase` runs top-down and `connect_phase` the other way round
- **Make** a scoreboard that fails say **something more** than "it failed"

Note:
The third one is the one that pays off the most in the long run and the one most
underestimated: it is row 10 of the closing self-assessment and the one aiming at
the 47 % of day 1. A `uvm_error` that prints *"FAIL"* leaves whoever is debugging
where they were; one that prints the transaction, the prediction and the time
saves them half a morning.
The first two are library mechanics and they are the ones most often answered
with an *"it rings a bell"*. The second exercise of the day exists so that they
stop ringing and start having been suffered.

## Tests

#### *Compile once, pick the test from the command line*

- The object-based testbench has the stimulus **inside**: changing test means
  changing code and compiling again
- A thousand tests at five minutes of compilation each are **5000 minutes**: three
  and a half days of machine time to run nothing new
- UVM turns the order around: the testbench gets compiled **once**, and the test that
  runs is picked when the simulation starts

```sh
$ ./obj_dir/top/sim +UVM_TESTNAME=random_test
$ ./obj_dir/top/sim +UVM_TESTNAME=add_test     # the same binary
```

- That is what this unit buys, and what gets paid with the ceremony that
  comes: registration in the factory, a constructor with a fixed signature and phases

Note:
The arithmetic is UVM's commercial argument, and it is worth saying it with the numbers
in hand: it is not that the modular testbench is wrong, it is that it does not scale.
If possible, live: compile once and run the two lines above. Let them
see that the second one compiles nothing.
What gets collected from the object-based testbench: the testbench is already split into tester,
coverage and scoreboard, and that is why you can change the tester alone. What gets
paid up front: in the components those three classes stop being loose objects that
the test `new()`s and become components of the tree.

---

## Tests

#### *The top: instantiate, publish the interface, start*

```sv
   initial begin
      // null and "*": from the root and visible to the whole tree. See the
      // uvm_config_db slide.
      uvm_config_db#(virtual vtalu_bfm)::set(null, "*", "bfm", bfm);

// UVM reads +UVM_TESTNAME, and builds THAT test with the factory.
      run_test();
```

- The `top` is still a **module**: it instantiates the BFM and the DUT the same as
  before. The only new thing is these two lines
- `run_test()` with no argument means *"whichever `+UVM_TESTNAME` says"*. With an
  argument —`run_test("random_test")`— that one becomes the **default**, and
  `+UVM_TESTNAME` still overrides it from the command line
- Before `run_test()` there is not a single UVM object alive: that is why the `set` goes here

Note:
The virtual interface gets passed through the config_db because classes do not see the
signals of the module: `bfm` lives in `top`, and `random_test` is an object that gets
created at simulation time. There is no way to hand it over through the constructor —
`uvm_component`'s constructor only accepts `name` and `parent`.
It is worth pointing at the order: first the `set`, then `run_test()`. The other way round
the test gets built before the data is in the database and the `get` fails with
the fatal. It is a mistake you rarely see because almost nobody writes the top the wrong way
round, but it explains why the `set` cannot go in a separate `initial`.
The slide that follows is the one to explain well: it is mistake number one of
whoever starts with UVM.

---

## Tests

#### *uvm_config_db: the testbench's mailbox*

- A global and **typed** database: the `#(...)` is part of the key
- Four arguments: *scope* (`cntxt`, `inst_name`), *name* and *data*
- The **scope** is a hierarchical path, and that is where the whole point is

```sv
// ILLUSTRATION -- not compiled. The two halves of the config_db, side by side:
// the set() lives in top.sv and the get() in tb_classes/driver.svh.
// -- IN THE TOP -- top is a module, not a uvm_component ---------------------
//   cntxt = null : the scope starts at the UVM root
//   inst  = "*"  : visible to the whole component tree
uvm_config_db #(virtual vtalu_bfm)::set(null, "*", "bfm", bfm);

// -- IN A COMPONENT -- always inside build_phase ----------------------------
//   cntxt = this : the scope is the hierarchical path of THIS component
//   inst  = ""   : with no suffix, the path is exactly the component's
if (!uvm_config_db #(virtual vtalu_bfm)::get(this, "", "bfm", bfm))
  `uvm_fatal("DRIVER", "Failed to get BFM")

// The 3rd argument ("bfm") is the NAME of the datum inside the database.
// If the string in the set and the one in the get are not identical, this still
// compiles and blows up at run time with a null pointer.
```

Note:
The first two arguments are *where*, the third is *what*. In the `set` of the
top it is `null, "*"` because `top` is a module, it is not in the UVM tree: the
translation is "from the root, visible to everybody".
In the `get` it is `this, ""`, that is, "me". It is worth writing on the board the
path that comes out: `uvm_test_top.env_h.driver_h`.
And the shortcut to warn against from the start: `get(null, "*", ...)` also
compiles and also works — it searches the whole tree and keeps the first thing it
finds. With a single interface you never notice. The day the testbench
has two, the driver of bus A can end up driving bus B, and it does not fail:
it lies. It is one of those mistakes that get paid for three months later.

---

## Tests

#### *A test in three parts: 1 · register it*

```sv
class random_test extends uvm_test;
   `uvm_component_utils(random_test);

virtual vtalu_bfm bfm;
```

- `random_test` extends `uvm_test`, which extends `uvm_component`: it is a node
  of the tree, not a loose object
- The `` `uvm_component_utils `` macro **enrols it in the factory**. Without that
  line, `+UVM_TESTNAME=random_test` finds nothing and UVM aborts
- The handle to the virtual interface gets **declared** here and **filled in** in the
  `build_phase`: they are two different moments

Note:
It is the first time the factory shows up for real, and you still cannot see what it is
for: here it only acts as a directory of names. The second half —creating by type
and being able to substitute it from outside— arrives in the env with the overrides.
The semicolon after the macro is redundant and UVM tolerates it. It is in the code of the
book and we left it the same so that whoever compares does not get dizzy, but if somebody
asks: it is not needed.

---

## Tests

#### *2 · the constructor and the `build_phase`*

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

// The get goes in build_phase and not in the constructor: when the
   // constructor runs, the tree does not exist yet.
   function void build_phase(uvm_phase phase);
      if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "bfm", bfm))
         `uvm_fatal("RANDOM TEST", "Failed to get BFM")
   endfunction : build_phase
```

- The constructor of a `uvm_component` has a **fixed signature**: `name` and `parent`,
  in that order, and `super.new(name, parent)` as the first line
- The `get` of the config_db goes in `build_phase`, **not** in the constructor: when
  the constructor runs the tree is still being assembled
- `if (!get(...)) uvm_fatal`: the `get` returns a bit. Ignoring it leaves the handle
  at `null` and the failure shows up a hundred lines later, in another file

Note:
The fixed signature is the first thing everybody breaks: a constructor with one
argument too many and the factory cannot create it, because it always calls with
`(name, parent)`.
`build_phase` is a phase, not a function you call yourself: UVM walks it
top-down over the already assembled tree. In this test you cannot tell yet, because the
tree is a single node; in the components, when the env builds its children, the
top-down order is what makes the parent exist before the child.
The fatal is not paranoia: without it, a typo in the name of the data —"bfm" against
"BFM"— gives a simulation that runs, sends not one stimulus and finishes with 0
errors.

---

## Tests

#### *3 · the `run_phase`: this is where the simulation happens*

```sv
   task run_phase(uvm_phase phase);
      random_tester random_tester_h;
      coverage      coverage_h;
      scoreboard    scoreboard_h;

phase.raise_objection(this);

random_tester_h = new(bfm);
      coverage_h = new(bfm);
      scoreboard_h = new(bfm);

fork
         coverage_h.execute();
         scoreboard_h.execute();
      join_none

random_tester_h.execute();

phase.drop_objection(this);
   endtask : run_phase
```

- It is the same body as the `execute()` of the object-based testbench: tester, coverage and
  scoreboard, with the two observers in `fork ... join_none`
- What changes is **who calls it**: before it was called by the `top` module, now
  it is called by UVM when the run phase's turn comes
- The two new lines are the `raise` and the `drop` of the objection, which are the ones
  that decide when everything ends

Note:
It is worth showing it next to the `tb.execute()` of the object-based testbench: the stimulus did not
change by one line. The only thing we did was move it inside a class that
UVM knows how to create and call. That is the whole job of this unit.
`join_none` and not `join`: coverage and scoreboard are infinite loops that watch
the signals. If we waited for them to finish, it never finishes.
And the one people miss: the simulation does not last as long as the `run_phase` lasts, it lasts as
long as the objections last. That is what comes now.

---

## Tests

#### *Objections: who decides when it ends*

```systemverilog
task run_phase(uvm_phase phase);
   phase.raise_objection(this);    // "I still have work"
   ...                             // the stimulus
   phase.drop_objection(this);     // "done, as far as I am concerned it can end"
endtask
```

- Every `run_phase` runs **in parallel**: none of them can decide on its own
  when to finish. UVM counts, and the phase ends when the **last**
  objection drops
- Without `raise_objection` the simulation ends at **time 0**, and the test
  passes with 0 errors without having sent a single stimulus
- Without `drop_objection` it never ends: there is no error, the simulation just
  keeps running
- Both symptoms are **silent**, and that is why two plusargs exist:
  `+UVM_OBJECTION_TRACE` says who raised it and who dropped it, and `+UVM_TIMEOUT`
  puts a ceiling on the run

Note:
It is the mechanism that decides how long the simulation lasts, and it is the one that produces the
two classic hangs of the first week. Worth writing the two failures on the
board, because the student is going to see them before any DUT bug.
The rule of thumb: the objection gets raised by **whoever has work**, and dropped
by **the same one**. In this course it is always the test. Never raise it in a
component and drop it in another one — that is how a real testbench hangs.
And a third participant is missing, which is the next slide: the objection knows
when the test finished **sending**, not when the scoreboard finished
**comparing**. That is the difference the `drain_time` pays for.
And the day 6 hook: `set_automatic_phase_objection(1)` is this same thing, done
by the sequencer instead of by the test.

---

## Tests

#### *The end that is not the end: `drain_time`*

- The objection says *"I finished **sending**"*. It does not say *"I finished
  **comparing**"*: between the two there is a scoreboard with a FIFO inside and
  results the DUT has not answered yet
- When the last objection drops the phase cuts **at that instant**: what
  was left in flight does not arrive, nobody compares it, and the summary says `UVM_ERROR : 0`

```systemverilog
task run_phase(uvm_phase phase);
   phase.get_objection().set_drain_time(this, 200ns);  // a cushion after the last drop
   phase.raise_objection(this);
   ...                                                 // the stimulus
   phase.drop_objection(this);
endtask
```

- The `drain_time` is a number picked by eye. The version with a criterion is
  **`phase_ready_to_end()`**: UVM calls it when the last objection dropped, and the
  component that still has work raises one more and the phase carries on
- It is **the** bug of the second week, and it is silent: no error, no hang, and
  the last transactions were never compared

Note:
It is the flip side of the previous slide and it is worth saying it in those words: the
objection measures **the stimulus**, not the analysis. The test knows when it finished
sending; the scoreboard is the one that knows when it finished comparing, and nobody
asked it.
The `drain_time` is the cheap answer and it is enough for 90 % of the cases: a
fixed cushion after the last `drop_objection`, in the order of what the
DUT takes to answer. In this course it would be a couple of cycles; on a bus with latency,
whatever the spec says.
`phase_ready_to_end()` is the expensive answer and the one used in a serious
testbench, because it is not a number: the scoreboard looks at its own FIFO, and if it has
items left it raises one more objection. The shape is always the same —check
`phase.get_name() == "run"`, and raise only if something really is missing—, and the
trap has to be said: if whoever implements it never drops it, they hung the phase.
The third piece, for whoever wants to hook in at exactly that instant, is
`all_dropped`: a callback of the objection object that fires when the count
reaches zero.
And the hook forward: the scoreboard with a FIFO of the analysis ports is
exactly the case of this slide, and the capstone steps on it again.

---

## Tests

#### *The timeline, end to end*

![Timeline of an objection: raise, stimulus, drop, drain_time and the end of the phase, with the transactions still in flight](../res/diagrams/en/tests_objections.svg)

- `raise` and `drop` mark **the stimulus**, and nothing but the stimulus
- What is left in flight is not in that count: the three empty boxes of the drawing
- The `drain_time` is the time given away so those answers arrive and get compared
- Without `raise` nothing sits between the marks; without `drop`, the line never ends

Note:
The figure is there to be paused on, asking where the simulation ends. The answer
almost everybody gives the first time —*"when the test finished sending"*— is
exactly the one that produces the bug: that is where the last objection drops, and
that is where the phase cuts if nobody asked for a cushion.
It is worth pointing at the three empty boxes: they are transactions the DUT has
not answered yet. They are not lost through anybody's mistake, they are in flight,
which is the normal state of any pipeline. What decides whether they get compared
or not is how much longer the phase lives.
The detail worth saying out loud: the `drain_time` is measured from the last
`drop`, not from the beginning. If the test sends a thousand operations and the DUT
takes two cycles to answer, the cushion is two cycles and not two thousand.
And the version with a criterion —`phase_ready_to_end()`— is this same figure with
one difference: the length of the cushion gets decided by the scoreboard looking at
its FIFO, instead of being decided up front by whoever wrote the test.

---

## Tests

#### *The second test: the same thing, with another tester*

```sv
   task run_phase(uvm_phase phase);
      add_tester add_tester_h;
      coverage   coverage_h;
      scoreboard scoreboard_h;

phase.raise_objection(this);

add_tester_h = new(bfm);
      coverage_h = new(bfm);
      scoreboard_h = new(bfm);

fork
         coverage_h.execute();
         scoreboard_h.execute();
      join_none

add_tester_h.execute();
      phase.drop_objection(this);
   endtask : run_phase
```

- `add_test` is `random_test` with **one different line**: `add_tester` instead
  of `random_tester`. Everything else repeats exactly as it is
- That repetition is real and it is ugly, and it is the debt the components pay: when
  the testbench is a tree of components, the test is going to build an `env` and it is not
  going to touch the stimulus
- For now it is worth seeing it copied: it is the problem that motivates what
  follows

Note:
The duplication should not be apologized for, it should be pointed at. The student has to
finish this slide with the feeling of "this cannot be right", because that
feeling is exactly the reason for the components and the env.
If somebody jumps ahead and proposes a base class with the common `run_phase` and a
virtual method to pick the tester: that is fine, and it is more or less what
`base_test` does in the sequences. Tell them so and move on.

---

## Tests

#### *How it gets run, and what it prints*

```bash
set -e
. "$(dirname "${BASH_SOURCE[0]}")/../../verilator/common.sh"
vlt_uvm top --coverage-user -Wno-fatal -f dut.f -f tb.f
run_sim +UVM_TESTNAME=random_test
run_sim +UVM_TESTNAME=add_test
cov_report
```

```plaintext
UVM_INFO @ 0: reporter [RNTST] Running test random_test...
UVM_INFO $UVM_HOME/src/base/uvm_report_server.svh(1009) @ 46340: reporter [UVM/REPORT/SERVER] 
--- UVM Report Summary ---
** Report counts by severity
UVM_INFO :    1
UVM_WARNING :    0
UVM_ERROR :    0
UVM_FATAL :    0
** Report counts by id
[RNTST]     1
- $UVM_HOME/src/base/uvm_root.svh:633: Verilog $finish
- S i m u l a t i o n   R e p o r t: Verilator 5.052 2026-09-05
- Verilator: $finish at 46ns
```

- A single `vlt_uvm`, two `run_sim`: **one compilation, two tests**. That is all
  the unit promises, and here it is done
- `[RNTST] Running test random_test...` is UVM saying what it found in the
  factory under the name you passed it
- The *Report Summary* with `UVM_ERROR : 0` is the verdict: reporting takes it
  apart and explains where each row comes from

Note:
Worth running it live and timing it: the compilation takes minutes, the two
`run_sim` take seconds. That is the number that justifies all the ceremony of
the unit.
The `$finish at 46ns` at the bottom is from the first test; `add_test` ends at 41 ns.
Both send the same number of operations, but the multiplication takes more cycles
than the addition, so the time depends on what came out of the random.
And a useful warning: `UVM_ERROR : 0` means "nobody called
`uvm_error`", not "the DUT is fine". Here the scoreboard does report with
`` `uvm_error ``, so the count is worth something — but a scoreboard that never receives
anything gives exactly the same zero. Reporting shows how to tell them apart.

---

## Tests

#### *Summary of the unit*

- The testbench gets compiled **once** and the test gets picked from the command line:
  `+UVM_TESTNAME=random_test`. That is the whole business of the section
- The arithmetic that justifies it: a thousand tests at five minutes of compilation each are
  **three and a half days** of waiting for it to compile
- The `top` is still a module. It publishes the BFM in the `uvm_config_db` **before**
  `run_test()`, because before that line there is not a single UVM object alive
- The **`uvm_config_db`** is a global and **typed** database: the `#(...)`
  is part of the key, and the scope is a **hierarchical path**
- A test gets registered with `` `uvm_component_utils ``. Without that line, the factory
  does not find it and UVM aborts
- The virtual interface gets **declared** in the class and **filled in** in the
  `build_phase`: they are two different moments, and confusing them leaves a `null`
- The objection says when the test finished **sending**, not when the scoreboard
  finished **comparing**. That difference is paid for with `drain_time`, or else with
  `phase_ready_to_end()`

Note:
Closing of the first real UVM unit. It is worth acknowledging the discomfort out
loud: today they put in a lot of ceremony to do the same thing they were already doing. What
they bought is the first bullet, and it does not pay out until there are two tests — which is the env.
The mistake they are going to walk into and it is worth anticipating: the `get()` that forgets to
check the return value. It does not fail, it **lies**: it leaves the virtual interface at
`null` and the testbench falls over three layers further down. That is why every `get` of the
course goes inside an `if` with its `uvm_fatal`.

## Components and phases

#### *A component is what is in the tree, and the tree is walked by UVM*

- A testbench has three different things: the **structure** —what parts there are and
  how they connect—, the **sequences** —which commands, in what order— and the
  **data**. This unit is the first one; the data is day 5 and the sequences day 6
- In the tests the test did `new()` on three loose objects and called them
  itself. That is not a structure: it is a long function
- A `uvm_component` is a **node with a name and a parent**. UVM assembles the whole
  tree and then walks all of it calling **phases**, in an order it
  guarantees
- Turning a class into a component is four steps, always the same ones:

1. extend `uvm_component` or one of its daughters
  2. register it with `` `uvm_component_utils() ``
  3. the minimum constructor: `(string name, uvm_component parent)`
  4. override the phases it needs

Note:
The sentence on the slide is the one that orders the unit: *a component is what is in
the tree*. Everything else —the name, the parent, the phases, the `print_topology` of
the agents— comes out of there.
The practical consequence that has to be said out loud: if something is not a
component, UVM does not see it. It does not build it, it does not call phases on it and it does not show up in the
topology. Later on we are going to have objects that on purpose are **not**
components —the transactions— and that is where the distinction buys you something.
The three axes —structure, sequences, data— work as a map of the rest of the
course: components and `env` are structure, transactions are data, sequences are
sequences.

---

## Components and phases

#### *Intro UVM phases*

- Every uvm component has these phase methods by inheritance
- UVM creates the TB and goes calling these methods in order
- The phases are *methods*: they get overridden like any other virtual method.
  Whether it is also worth calling `super` is the topic of the next slide

- *function void build_phase(uvm_phase phase):* UVM creates the TB (top-down). UVM components get instantiated in this method. If you try to instantiate them anywhere else it is an error
- *function void connect_phase(uvm_phase phase):* Connecting components
- *function void end_of_elaboration_phase(uvm_phase phase):* UVM calls it once it has created and connected every component
- *task run_phase(uvm_phase phase):* UVM runs this task in its own thread. Every run_phase runs simultaneously
- *function void report_phase(uvm_phase phase):* It runs when the last objection of the test drops. It shows Results

Note:
Three things that have to be said no matter what: build_phase is top-down, connect_phase is
bottom-up, and every run_phase runs in parallel, each one in its thread.
And the classic mistake: creating components **after** build has ended. UVM does warn
you, and well: `ILLCRT` tells you which component and under which parent.

---

## Components and phases

#### *The tree, twice: one walk goes down and the other goes up*

![The tree walked twice: build_phase goes down and connect_phase goes up, and the real order in which a child gets built](../res/diagrams/en/components_fases.svg)

- `build_phase` goes down because a parent has to exist to create its children
- `connect_phase` goes up for the opposite reason: the other end has to be there
- The child gets **created** inside the parent build; its own build runs later
- That is why the `config_db` `set()` goes **before** the `create()` that builds it

Note:
The drawing answers two questions that in the table read like an arbitrary
convention. The first one: why `build_phase` is top-down. Because a parent has to
exist in order to create its children, and there is no other way to assemble a
tree; the ones in the middle need the opposite, that the children are already there.
The second one is the one asked under one's breath: if the parent creates the
child inside its own `build_phase`, when does the `build_phase` of the child run?
Later, and that is the part that has to be said slowly: `create()` calls the
**constructor**, not the phase. UVM walks the tree calling the phase on the
components that showed up along the way, so the child gets built in two steps.
The practical consequence is the one in the last bullet, and it is the one that
buys you something: a `uvm_config_db::set()` written **after** the `create()` of the child
arrives late, the child already read, and the field stays at its default without
anybody warning. It is the same asymmetric failure mode as the next slide.
If somebody asks about the code: `uvm_topdown_phase::traverse` runs the phase on
the component and only then walks its children —`get_first_child()`—, which by
then already exist.

---

## Components and phases

#### *And what about `super.build_phase()`?*

```systemverilog
// uvm_component.svh:2385-2393 -- uvm-core 2020.3.1, with the return; elided
function void uvm_component::build_phase(uvm_phase phase);
   build();            // -> apply_config_settings(): the automatic config
endfunction

function void uvm_component::connect_phase(uvm_phase phase);
   connect();          // -> return;  it is empty, like all the others
endfunction
```

- `build_phase` is the **only** phase that does anything in `uvm_component`: it applies
  the fields registered with `` `uvm_field_* ``. The course does not use those macros
- Careful, there are **two different `super`s**: that one, and the one of a base
  class of **yours**, which builds what you wrote. The second one the course **does** call
- Out there: **always put it in, unless you can name why in your case it is a
  no-op**. Adding it costs nothing; skipping it when it mattered —a
  `` `uvm_field_* ``, or inheriting from `uvm_agent`— leaves the field at its
  default and **nobody warns you**
- And the order matters: whatever has to be decided *before* the children get
  built goes before the `super`. The `set_type_override` of `add_test` is that

Note:
This slide exists because the student is going to see `super.build_phase(phase)` in every
piece of material on the internet and in most of the course's `build_phase` it is not
there. The honest answer is not "they forgot": it is that without the field macros the
call to `uvm_component`'s does nothing.
The numbers, so that nobody has to take our word for it:
`grep -rn 'super\.build_phase' code/ --include='*.sv' --include='*.svh' --exclude-dir=.uvm`
gives 15 real calls —plus 6
comments that talk about them— over 306 `build_phase`. Those
15 call the `super` of a
`base_test` or a `random_test` of **ours**, which builds the env. None of them calls
`uvm_component`'s, which is what the slide is about.
The other underlying difference: there are two ways of configuring a component. The
automatic one (`` `uvm_field_* `` + config_db, magic by macros) and the manual one
(`uvm_config_db::get()` in the build_phase, which is the one the course uses). The
manual one is more code and vastly easier to debug — the field macros generate
hundreds of lines you are never going to read.
Why the recommendation for out there is the opposite of what the course does: the
failure mode is asymmetric. Putting it in for nothing has zero effect. Leaving it out
when it was needed is silence: the field stays at its default and the simulation runs.
This course can name why in its case it is a no-op —there is not a single
`` `uvm_field_* `` macro in `code/` outside the vendored library —there are
0, and the build counts them—; whoever walks into somebody else's
testbench cannot. `uvm_agent` is the counterexample we have at hand: besides
`uvm_component`, it is implemented by `uvm_agent` —which reads `is_active` there—
and by the two sequencer bases (`seq/uvm_sequencer_base.svh:122`, which reads
`wait_for_sequences_count` from the config_db, and
`seq/uvm_sequencer_param_base.svh:236`). It comes back on day 6.
The same goes for the other phases, cheaper still: in `uvm_component` they are
`return;`, but `uvm_driver::end_of_elaboration_phase` checks that the `seq_item_port`
is connected, and that one we do extend.

---

## Components and phases

#### *The full picture: there are nine, not five*

| Phase | What for | Order |
| --- | --- | --- |
| `build_phase` | instantiate the components | **top-down** |
| `connect_phase` | connect the ports | bottom-up |
| `end_of_elaboration_phase` | hierarchy ready, before simulating | bottom-up |
| `start_of_simulation_phase` | last call before time 0 | bottom-up |
| `run_phase` | **task**: this is where the simulation happens | one thread each |
| `extract_phase` | gather the data from the run | bottom-up |
| `check_phase` | decide whether it passed | bottom-up |
| `report_phase` | print the verdict | bottom-up |
| `final_phase` | close files and exit | **top-down** |

- The course uses five. The other four exist, they are empty, and you are going to see them

Note:
The table is there so that nobody leaves believing UVM has five phases: it has
nine common ones and twelve runtime ones. The course uses five because with a single agent
that is enough, and that has to be said — it is not that the others do not matter.
The three you are most likely to run into outside: `start_of_simulation_phase` is where
people print the configuration banner of the test; `check_phase` is where a
tidy scoreboard decides the verdict, instead of counting errors along the
way; and `report_phase` is the one they have already seen.
That `extract` / `check` / `report` are separate has a concrete reason: they are
bottom-up, so a child scoreboard finishes extracting before the parent env
decides. If you do the three things in `report_phase`, you lose that guarantee.
The question that orders the table: why is `build_phase` top-down?
Because a parent has to exist in order to create its children. The ones in the
middle need the opposite — that the children are already there. The other
top-down one is `final_phase`, which closes the tree in the same order it was built.

---

## Components and phases

#### *And inside the `run_phase`, a schedule*

![The twelve runtime phases running in parallel with run_phase, and where the default_sequence hooks in](../res/diagrams/en/components_runtime.svg)

- The twelve are `task`s, they run **in parallel** with `run_phase`, and they are
  there to coordinate components from different teams without hand-made flags
- The course uses `run_phase` and nothing else — with a single agent there is nothing
  to coordinate. But the `default_sequence` of day 6 hooks into **`main_phase`**

Note:
This slide exists so that `main_phase` does not show up for the first time on day 6.
The exact distinction, which confuses everybody: `run_phase` and the schedule
`reset → configure → main → shutdown` run **at the same time**, not one inside the
other. A component can implement either of the two paths; what is not
advisable is mixing them in the same testbench, because then nobody knows what
runs when.
The honest question is "so which one do I use?". For a testbench of a single
block, `run_phase`, which is what the course does. The schedule earns its
keep in integration: the agent of the configuration bus finishes its `configure`
and only then does the data one start its `main`, without either of the two teams
having had to write a `uvm_event` or a shared flag.

---

## Components and phases

#### *The scoreboard, now as a component*

```sv
// The scoreboard of the TB in objects, now as a uvm_component. The four steps
// --extend, register, constructor, phases-- are in the slides of the components section.
class scoreboard extends uvm_component;
   `uvm_component_utils(scoreboard);

virtual vtalu_bfm bfm;

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

// Self-sufficient: the component asks the config_db for the BFM. Before, the
   // test passed it in through the constructor, and the test had to receive it
   // only to hand it out.
   function void build_phase(uvm_phase phase);
      if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "bfm", bfm))
         `uvm_fatal("SCOREBOARD", "Failed to get BFM")
   endfunction : build_phase
```

- The four steps, in order: it extends `uvm_component`, it registers itself, constructor
  `(name, parent)`, and an override of `build_phase`
- The underlying change does not show in the diff: before, the **test** received the BFM and
  handed it to the scoreboard through the constructor. Now the scoreboard **asks for it
  itself** from the config_db
- The `run_phase` is the `execute()` of the object-based testbench without touching a comma: the
  check did not change, what changed is who starts it

Note:
The point of the slide is self-sufficiency. A component that needs somebody
to hand it its dependencies forces that somebody to know them, and the test
ends up being a delivery service for handles it does not use. With the config_db, the test does not
know that the scoreboard needs a BFM.
That is exactly what makes the `env` able to exist: if
every component configures itself, the parent only has to build it.
The price has to be said too: the dependency stopped being in the
constructor, where it could be seen, and moved into a string. A misspelt `"bfm"` compiles. That
is why the `if (!get(...)) uvm_fatal` is not optional.

---

## Components and phases

#### *The test builds the tree and steps aside*

```sv
class random_test extends uvm_test;
   `uvm_component_utils(random_test);

random_tester tester_h;
   coverage      coverage_h;
   scoreboard    scoreboard_h;

// Components get instantiated in build_phase, never in the constructor.
   function void build_phase(uvm_phase phase);
      tester_h = new("tester_h", this);
      coverage_h = new("coverage_h", this);
      scoreboard_h = new("scoreboard_h", this);
   endfunction : build_phase

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

// No run_phase: the test's job ends once the tree is built.

endclass
```

- The three `new("name", this)` are what creates the tree: `this` is the parent, and
  the string is the name that is going to come out in `print_topology` and in every message
- They go in `build_phase` **and nowhere else**. In the constructor there is no
  hierarchy yet; after `build_phase`, UVM has already moved on
- `random_test` **has no `run_phase`**: its job finished when the tree
  was assembled. The three children have theirs, and they run in parallel

Note:
It is the change of mindset of the unit, and it is worth saying it in these words:
the test stopped *doing* the test. Now it assembles it and steps aside.
The objection also moved: it is no longer raised by the test, it is raised by the
components that have work — or, in this example, by the tester. Worth showing
`random_tester.svh` for a second so that it can be seen.
And the trap that is going to show up on its own: `new()` works here because the type is
written in the declaration. In the env that gets replaced by
`type_id::create()`, and that is the change that enables the overrides. Not yet,
but it is worth planting.

---

## Components and phases

#### *The second test: it inherits, and it copies anyway*

```sv
// add_test extends random_test, redeclares tester_h with another type and
// REWRITES the whole build_phase. That duplication is the problem the env section solves
// with the factory override.

class add_test extends random_test;
   `uvm_component_utils(add_test);

add_tester tester_h;

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

function void build_phase(uvm_phase phase);
      tester_h = new("tester_h", this);
      coverage_h = new("coverage_h", this);
      scoreboard_h = new("scoreboard_h", this);
   endfunction

endclass
```

- `add_test` extends `random_test`, so it inherits `coverage_h` and
  `scoreboard_h`. It only redeclares `tester_h`, with another type
- But the `build_phase` is **written out again in full**, and the three lines are
  identical except for one. Inheriting the class was not enough to inherit the structure
- And there is something worse hidden: `add_tester tester_h;` **shadows** the `tester_h` of
  the base class. They are two different variables with the same name
- It is the same problem as the tests, in disguise. The env solves it for
  real: **one** structure, and the factory substitutes the piece that changes

Note:
This is the slide that has to be left uncomfortable. If the student walks out thinking "this
is still wrong", the env explains itself.
The shadowing of the handle deserves a minute: in the base class there is a
`random_tester tester_h` and here an `add_tester tester_h`. Any method
inherited from `random_test` that uses `tester_h` is going to see the base one, which stayed at
`null`. Here it does no harm because there is none, but it is a time bomb and it is
exactly the kind of silent mistake the course goes after.
The hook: in the `env` there are not two tests, there is one; and `add_test` becomes a
line of `set_type_override_by_type`.

---

## Components and phases

#### *Summary of the unit*

- A `uvm_component` is a **node with a name and a parent**. UVM assembles the tree
  with those two pieces of data and then walks it on its own
- Turning a class into a component is **four steps, always the same ones**:
  extend, register with the macro, the two-argument constructor, and the
  phases
- The **phases** are virtual methods that UVM calls **in order**: `build_phase`
  (top-down), `connect_phase`, `end_of_elaboration_phase`, `run_phase`,
  `report_phase`
- Components get instantiated **in the `build_phase` and nowhere else**
- Every `run_phase` runs **in parallel**, each one in its thread. None of them
  decides on its own when the simulation ends: that is the **objections**
- There are **two `super.build_phase()`**: `uvm_component`'s and your base class's.
  **Always put it in, unless you can name why in your case it is a no-op**

Note:
The unit that turns the testbench into something UVM can walk, and with that
the tools that did not exist before show up: `print_topology()` shows the
tree, and the `uvm_config_db` can use paths because now there are paths.
The `super.build_phase()` deserves the pass we gave it because it is the most
repeated question in the forums. What has to be said out loud is the asymmetry: not
calling it switches off the automatic assignment of the fields registered with
`` `uvm_field_* ``, and that does not give an error, it gives a default. This course
does not use those macros and that is why it can skip it; the student who lands in
somebody else's testbench does not know whether they can, so they put it in. What is
not valid is doing half of each.

## The env: structure and stimulus

#### *Two things that change for different reasons*

- A testbench has **structure** —which components there are and how they connect— and
  **stimulus** —what gets sent to the DUT—
- They change for different reasons and at different rates: the structure changes
  when the design changes; the stimulus, every time you write a test
- Up to the components they are glued together: `add_test` is a copy of `random_test` with
  one line changed. Ten tests are ten copies, and one change in the structure
  is ten edits
- This section splits them into two classes: the **`uvm_env`** keeps the
  structure, the **`uvm_test`** keeps the stimulus
- And the piece that makes it possible is the **factory**: the `env` asks for a
  generic `base_tester`, and each test tells the factory which one to hand over

Note:
Hinge section of the course, and the sentence to leave behind is this one: **what changes
together goes together, what changes separately goes separately.** Everything that comes
afterwards —agents, sequences— is this same operation applied to
something else.
If the group is going slowly, this is the unit where it is worth spending whatever time is
left over, even if it has to be taken from somewhere else. A student who does not understand why the
env and the test are two classes is not going to be able to read any production testbench,
because they are all built like this.
The question to start with, before showing one line of code: if tomorrow the
design adds a second interface, how many of your ten tests have to be touched?
None, if the structure lives in a single place. All ten, if each test assembles it.

---

## The env: structure and stimulus

#### *Intractable vs. adaptable*

> "Playing football is very simple, but playing simple football
> is the hardest thing there is." — **Johan Cruyff**

![The same move: tangled and simple](../res/funs/en/simple-es-dificil.svg)

- *Intractable* is the code that comes out fast and afterwards will not let itself be touched. The
  criterion is not aesthetic: **somebody else is going to modify it**, and that somebody is going
  to be you a year from now, remembering nothing
- Three rules to turn the VTALU TB around: **one class, one thing**; **nothing
  hardcoded**; **program against the interface**, not against the implementation

Note:
Swap *football* for *testbench* and Cruyff's line is the whole unit.
The three rules sound like an office poster until you measure them, so it is
worth landing them on the testbench in front of them:
One class, one thing — the `random_test` of the components does two: it assembles
the structure and it picks the stimulus. That is why it has to be copied to make `add_test`.
Nothing hardcoded — `tester_h = new(...)` nails the type into that line. The
`type_id::create()` does not.
Against the interface — the `env` is going to ask for a `base_tester`, which is an abstract
class: it neither knows nor cares which one arrives.
And an honest warning, because at work this gets abused: adaptable
code does **not** mean code prepared for everything. Every point of
flexibility is paid for in indirection, and the indirection is paid for at three in the
morning. What gets separated is what has already been shown to change — and here it has been shown: there are two
tests and there is already copy and paste.

---

## The env: structure and stimulus

#### *The problem: two tests, the same `build_phase()` twice*

![random_test and add_test write the same build_phase()](../res/diagrams/en/env_intract_sol_1.svg)

- Today there are two tests: `random_test` builds a `random_tester`, `add_test` an
  `add_tester`. Everything else —coverage and scoreboard— they build the same way
- `add_test` **inherits** from `random_test` and **rewrites its whole
  `build_phase()`**: the three `new()` calls are identical and written twice
- The testers, on the other hand, duplicate nothing: `add_tester extends
  random_tester` and only overrides `get_op()`. The `run_phase()` is written **once**,
  in `random_tester`, and it is inherited
- Which means: the inheritance ladder is already solved well below, in the testers,
  and solved badly above, in the tests. The next two slides show how it came out
  below; the rest of the section applies it above
- Duplicating the `build_phase` is not ugly, it is expensive: ten tests are ten
  copies, and one change in the structure is ten edits

Note:
This is the problem slide, and it is worth not jumping ahead to the solution: let the
duplication be seen first, and let it be seen **where it is**. It is not in the
testers —those already inherit properly— but in the tests, which is where nobody
looks for it.
The question that orders the next two slides: which part of a tester is *the test*,
and which part is
*infrastructure*? The `get_op()` is the test —four lines—; all the rest is
infrastructure that has nothing to do with what you want to prove.
And the general criterion, which holds for any language: when two sibling
classes share an identical method, the method is in the wrong place.
It goes to the parent.

---

## The env: structure and stimulus

#### *The way out: an abstract class, and the stimulus in the daughters*

![abstract base_tester with a shared run_phase() and pure virtual methods](../res/diagrams/en/env_using_virtual_class.svg)

- `base_tester` is an **abstract** class: it writes the `run_phase()` a single time
  —a thousand operations— and assembles it by calling `get_op()` and `get_data()`
- Those two methods are `pure virtual`, so the class cannot be instantiated and
  every daughter is **forced** to define them. The one that forgets does not compile
- But there is still repeated code: both testers randomize the operands the
  same way, and that is a sign that a step is missing in the hierarchy

Note:
This is where polymorphism gets collected: `base_tester` is an **abstract class with
`pure virtual` methods**, that is, the `run_phase()` is written a single time and the
daughters are *forced* to define `get_op()` and `get_data()`. If one forgets, it does not
compile — which is the whole argument of that unit.
And along the way the trap of the day 2 exercise gets fixed: here `get_op()` **is**
virtual, because it is pure virtual. Worth going back two days and showing it.
The bullet that matters is the last one, and it is the one that pushes into the next slide: the
two testers still randomize the operands the same way. Two sisters sharing
code is a sign that a step is missing in the hierarchy — and the step is that
`add_tester` should not inherit from `base_tester` but from `random_tester`.

---

## The env: structure and stimulus

#### *The result: the three-storey hierarchy*

![random_tester as the base and add_tester inheriting from it](../res/diagrams/en/env_adaptable_sol.svg)

- `base_tester` puts in the `run_phase()` and declares `get_op()` and `get_data()` as
  `pure virtual`. Nobody instantiates it
- `random_tester` goes down one step and defines both: random operation, random
  operands
- `add_tester` **inherits from `random_tester`**, not from `base_tester`: it keeps
  the random operands and only redefines `get_op()`
- And the same step works for all the ones that come: `xor_tester`,
  `mult_tester`, `maxmult_tester`. Each one, one useful line

Note:
The jump to point out is the third arrow: `add_tester` does not inherit
from the abstract one, it inherits from the concrete one. It is counter-intuitive the first time and it is the
decision that makes a new test cost four lines.
The rule, said in a way that sticks: **you inherit from whoever has what you do not
want to write again.** Not from the one that "conceptually corresponds".
And the hook backwards: this is polymorphism used for real. `pure virtual` in
the parent is what guarantees that no tester forgets to define `get_op()` —
and if it forgets, it does not compile.

---

## The env: structure and stimulus

#### *add_tester*

- The result is that *add_tester* is very simple: it inherits from *random_tester* and only redefines *get_op()*

```sv
class add_tester extends random_tester;
   `uvm_component_utils(add_tester)

function operation_t get_op();
      return add_op;
   endfunction : get_op

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

endclass : add_tester
```

Note:
This is the slide of the section worth leaving on screen for a while: a whole test
of the VTALU is **four useful lines**. Everything else —sending a thousand
operations, randomizing operands, talking to the BFM— is already written and does not get
touched.
The rule you take away: if adding a test costs four lines, you are going to write
many. If it costs copying a class of sixty, you are going to write three and then
invent excuses. The coverage of the project is decided here, not in the covergroup.
And the question that orders the hierarchy: why does `add_tester` inherit from
`random_tester` and not from `base_tester`? Because it wants the random operands and only
changes the operation. Inheritance is not chosen by conceptual likeness, it is chosen
by **what you do not want to write again**.

---

## The env: structure and stimulus

#### *The other half: who instantiates whom*

- The testers are already well distributed. The other half is missing: **who
  instantiates them**
- The obvious way out is a family of `uvm_test`, one per tester. And it is the bad one:
  look at the `random_test` below
- It instantiates the three components **and** it picks the tester. Every new test copies that
  whole structure to change one line

```sv
class random_test extends uvm_test;
   `uvm_component_utils(random_test);

random_tester tester_h;
   coverage      coverage_h;
   scoreboard    scoreboard_h;

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

// No run_phase: the test's job ends once the tree is built.

endclass
```

- The `random_test` does **two** things: it assembles the structure of the testbench *and* it picks
  which stimulus to send. They are two reasons to change in a single class
- UVM splits that in two: the structure moves to a `uvm_env`, and the test is left
  only with picking the stimulus
- A typical `env` defines **two** methods and nothing else: `build_phase` to
  instantiate and `connect_phase` to connect

Note:
It is worth doing the arithmetic out loud, because the problem is easier to see with numbers than
with the design argument: if every test instantiates its three components, with ten
tests there are ten `build_phase` saying the same thing. The day a fourth
component is added to the testbench, that is ten edits — and the one you forget does not fail at
compile time, it simply runs without that component.
`uvm_env` is not magic and it does not bring new behaviour: it is a `uvm_component` with
another name. What it contributes is **convention**: when somebody opens a testbench
that is not theirs, they know the structure is in the env. That is half the value of
UVM and it is worth saying it that bluntly — it is not the library, it is that everybody puts the
things in the same place.
Good question: why does the env almost never have a `run_phase`? Because it neither sends nor
watches anything; it only builds and connects. If your env has a `run_phase`, it is a sign
that test logic got inside the structure.

---

## The env: structure and stimulus

#### *The map after splitting*

![The class diagram before and after splitting structure from stimulus with uvm_env](../res/diagrams/en/env_struct_level.svg)

- Two parallel hierarchies, and that is the whole section: on the left the tests
  —the stimulus—, on the right the `env` and its components —the structure—
- The `env` is **a single one** and it does not get touched. The tests are many and they change all the time
- The only thing that binds them is the factory: the test says *"when they ask for a
  `base_tester`, give them this one"*

Note:
Worth leaving the diagram on screen and asking them to place where each class of
the components ended up. The exercise makes it obvious what disappeared: there is no longer a
`build_phase` per test instantiating three components.
The control question: if tomorrow the testbench adds a fourth component,
how many files get touched? One, the `env`. With the structure of the components it was
as many as there were tests.

---

## The env: structure and stimulus

#### *The `env` class: instantiate and connect, nothing else*

- The `env` defines the structure of the testbench: it instantiates the components and
  then connects them. It is **a single one**, and it does not change from one test to another
- The tests, on the other hand, are many and they change all the time. That is the whole division
- The `build_phase()` does not use `new()`: each component gets asked for with
  `type_id::create()`, which is the factory formula of the next slide

```sv
// The structure of the TB, and nothing else: it instantiates the components and
// connects them. Which tester arrives is the test's call, with a factory override.
class env extends uvm_env;
   `uvm_component_utils(env);

base_tester tester_h;
   coverage    coverage_h;
   scoreboard  scoreboard_h;

function void build_phase(uvm_phase phase);
      // base_tester is abstract and this works anyway: create() does not build
      // it, it asks the factory what to hand out when somebody asks for a base_tester.
      tester_h = base_tester::type_id::create("tester_h", this);
      coverage_h = coverage::type_id::create("coverage_h", this);
      scoreboard_h = scoreboard::type_id::create("scoreboard_h", this);
   endfunction : build_phase

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

endclass
```

Note:
Hinge section of the course: separating WHAT structure the testbench has (env) from
WHAT stimulus gets sent (test). Everything that comes afterwards —agents, sequences— is
this same idea taken further.
If the group is going slowly, this is the slide where it is worth spending whatever time is
left over.

---

## The env: structure and stimulus

#### *UVM's factory: the class signs itself up*

- The factory had two annoyances: the result had to be cast, and
  the `case` of the factory had to be edited to add a type
- UVM's has neither of the two. A class registers **itself**, with a
  macro on its first line:
  - `` `uvm_component_utils() `` for what goes in the tree
  - `` `uvm_object_utils() `` for what does not —the transactions—
- And it returns an object **of the right type**, without casting: `type_id` is a
  different class for every registered class, so the type is put in by the compiler

Note:
The macro is what replaces the `case` of the hand-written factory: each class signs itself up in the dictionary, and adding a type does not force you to
edit the factory.
The difference between the two macros is the one that gets collected in the transactions, and it is worth
planting now: `uvm_component_utils` is for what lives in the tree and receives
phases; `uvm_object_utils` is for what travels —a piece of data— and receives none.
Picking the wrong one compiles and gives strange errors later.
Not having to cast is not cosmetic: the `$cast` of the factory could be
forgotten, and forgetting it was a null pointer in simulation.

---

## The env: structure and stimulus

#### *The formula, read from left to right*

![Anatomy of the line type::type_id::create(name, this)](../res/diagrams/en/env_uvm_incantation.svg)

- It is the *static member/method* pattern of the static variables, exactly as it is: `type_id` is a
  static member of the class, and `create()` a static method of that member
- The two arguments are the usual ones: the **name** that is going to come out in the
  topology, and the **parent** that hangs it from the tree
- The misspelt class and the one that does not exist show at **compile time**. The one
  that forgot the `` `uvm_component_utils `` only if **no ancestor** is registered: if it
  extends a registered one, the `type_id` is **inherited** and there is no error

Note:
Worth reading the formula out loud once, slowly, because it is going to be written
fifty times in what is left of the course:
*"class, colon colon, type_id, colon colon, create, name,
this"*.
The last bullet is the one that is **not** reassuring, and it should be said that way.
If `base_tester` was not registered and nothing above it was either,
`base_tester::type_id` does not exist and it does not compile: that is the good case.
But in this very section's hierarchy —the three of them registered— forgetting the
macro in `add_tester` **breaks nothing**: the `type_id` and the `get_type()` are
inherited from `random_tester`, the testbench compiles clean, and the `set_type_override`
of `add_test` ends up registering `random_tester`. Measured:
`add_tester::get_type().get_type_name()` returns `random_tester`, the env builds a
`random_tester`, and the test runs with `UVM_ERROR : 0`. It belongs to the "does not
break, lies" family of the silent-traps appendix: the only case where it does fail to
compile is if the handle is declared of the derived type, and here the handle is
`base_tester tester_h;`.
The name of the first argument is not decorative: it is the path of the component, the
one the config_db uses and the one `print_topology` prints. Giving it a name other than
the handle's is a cheap way of losing half an hour in the agents.

---

## The env: structure and stimulus

#### *The objection that comes on its own: `base_tester` is abstract*

- Now the objection that comes on its own: `tester_h` is of type `base_tester`, which is
  an **abstract** class. And this compiles, runs and works. Why?

```sv
   function void build_phase(uvm_phase phase);
      // base_tester is abstract and this works anyway: create() does not build
      // it, it asks the factory what to hand out when somebody asks for a base_tester.
      tester_h = base_tester::type_id::create("tester_h", this);
      coverage_h = coverage::type_id::create("coverage_h", this);
      scoreboard_h = scoreboard::type_id::create("scoreboard_h", this);
   endfunction : build_phase
```

- Because `base_tester` here is not a mould: it is an **order form**. The
  `env` does not build a `base_tester`, it asks the factory for one
- The factory returns an object of some **derived** class, and which one is decided by
  a `set_type_override` done **before** the `build_phase` runs
- That override is done by the **test**, which is the one that instantiates the `env`. The
  structure never finds out which tester it got

Note:
The objection on the slide is correct and it has to be taken seriously, because otherwise it
looks like a dirty trick: `base_tester` **is** abstract and that code **does**
compile and run. The explanation in one line: `type_id::create()` does not build a
`base_tester`; it asks the factory what to build when somebody asks for a
`base_tester`, and returns that.
The analogy that works: `base_tester` here is not a mould, it is an **order
form**. Nobody instantiates the form.
The corollary, which is the one paid for later: if no test did the override, the
factory really does try to build the abstract class and there it really does explode — and the message
does not say "you were missing the override", it says something about an abstract class. Worth
showing it once by commenting out the `set_type_override` of `random_test`.

---

## The env: structure and stimulus

#### *The override: changing the part without touching the plan*

- In the components, `add_test` was `random_test` copied with one line changed.
  The copy was the problem, not the solution
- An `add_tester` **is** a `base_tester`, so it works anywhere the
  code asks for a `base_tester` — that is polymorphism
- So there is no need to touch the `env`: it is enough to tell the factory *"when
  they ask you for a `base_tester`, hand over an `add_tester`"*
- That is the **factory override**, and it is the only thing a test has to do

Note:
The sentence that orders the slide: the override does not change the code, it changes what the
factory returns. The `env` still says exactly the same thing.
It is worth naming the two forms that exist, because both show up in code
that is not yours: `set_type_override` changes **every** request for that type in the whole
testbench; `set_inst_override` changes only the ones on one path —
`"uvm_test_top.env_h.tester_h"`, absolute—. The course uses the first because there is a
single tester; with two agents, the second is the one that helps, and it has its slide two
further on.
And the hook forward: it is exactly the mechanism that in the transactions is going
to replace a `command_transaction` with a `maxmult_transaction`. Same
call, another type.

---

## The env: structure and stimulus

#### *The factory override*

![Anatomy of the factory override with set_type_override()](../res/diagrams/en/env_uvm_incantation_2.svg)

- The static method *set_type_override()* tells the factory that when it sees a request for a *base_class_name* it should return an object of type *new_class_name*
- This feature is the one that lets us separate the structure of the TB (*uvm_env*) from the type of stimulus generated (*uvm_test*)

Note:
The override is what makes the env never change: the test asks for a
base_tester and the factory returns whichever one that test wants.
When somebody asks whether this is not black magic: it is a dictionary of types, and
that is why everything has to be registered with `` `uvm_component_utils ``. If you forget it,
the factory does not find the class and the error message does not help at all.

---

## The env: structure and stimulus

#### *The factory override, in the test*

```sv
class random_test extends uvm_test;
   `uvm_component_utils(random_test);

env env_h;

function void build_phase(uvm_phase phase);
      base_tester::type_id::set_type_override(random_tester::get_type());
      env_h = env::type_id::create("env_h", this);
   endfunction : build_phase

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

endclass
```

- We can see that this version is more adaptable
- Every test does an override of base_tester depending on the tester it needs for its stimulus
- The env class creates the object; running it is UVM's job
- Now the test class does one thing well (generating stimulus) and the env class does another thing very well (creating the structure)

Note:
The whole test is **two lines**: the override and the `create()` of the env. Worth
showing it next to the `random_test` of the components, which instantiated three
components by hand. That is the result of the section, measured.
And there is a detail of order that is paid for dearly and that is worth saying now, because it
comes back as question 5 of the review: the `set_type_override()` goes **before** the
`create()` of the env. The factory decides what to build at the moment of the `create()`,
not before and not after. If the override arrives late, there is no error — the env has already
built the base class and the test runs with the wrong stimulus. The same thing
again: it does not break, it lies.
With that the arc is said: the env never changes, the test always changes, and the
only thing that binds them is a type string in the factory.

---

## The env: structure and stimulus

#### *By instance, and the knob for seeing what got set*

```systemverilog
base_tester::type_id::set_type_override(add_tester::get_type());          // ALL of them
base_tester::type_id::set_inst_override(mult_tester::get_type(),
                                        "uvm_test_top.env_h.t2_h");      // just one

uvm_coreservice_t::get().get_factory().print(0);   // which overrides are in place
```

```
Instance Overrides:
 Requested Type Override Path Override Type
 base_tester uvm_test_top.env_h.t2_h mult_tester
 base_tester env_h.t3_h mult_tester <- registered and did NOT apply
Type Overrides:
 base_tester add_tester
```

- `set_inst_override` changes **one path**, not a type. And where the two coincide,
  the instance one wins
- The path is **absolute and starts at `uvm_test_top`**. Measured: `"env_h.t3_h"` gets
  registered all the same, gives no error, and `t3_h` comes out an `add_tester`
- `factory.print(0)` is the counterpart of `uvm_top.print_topology()`: one says what you
  **asked for**, the other what **came out**. When they do not match, the bug is in between
- With `*` it works: `"*.env_h.t4_h"` applies. It is the workaround when the test does not know where
  it is going to be instantiated

Note:
It is the second half of the override and the one that shows up as soon as there are two agents of the
same type: you do not want to change both, you want to change one.
The path trap has to be said with the measurement's number, because it is
exactly the way this mechanism fails: **the override with the badly written path
gets registered all the same**. `factory.print(0)` shows it in the table, tidy,
as if it were working. There is no warning, there is no error, and the component comes out
of the base type. It is the same family as the late `set_type_override` of the traps
appendix: the factory does not validate paths because it cannot — when the
override is registered, the component does not exist yet.
The practical rule: the path is the one `uvm_top.print_topology()` prints, without the `<unnamed>` at the
top. If the tree says `uvm_test_top.env_h.t2_h`, that is what goes between
quotes. And if you do not want to depend on where they instantiate you, `*.env_h.t2_h`,
which is also measured and also applies.
The pair of tools is what to take home: `factory.print(0)` says what
the factory has written down, `print_topology()` says what actually got built. An
override that shows up in the first and is not visible in the second is a badly written path
or a `create()` that arrived first.

---

## The env: structure and stimulus

#### *Summary of the unit*

- A testbench has **structure** —which components there are and how they connect— and
  **stimulus** —what gets sent—. They change for different reasons and at different rates
- Up to the components they were glued together: `add_test` was a copy of `random_test`
  with one line changed. Duplicating the loop is not ugly, it is **expensive**
- The **`uvm_env`** keeps the structure; the **test** only says which
  stimulus it wants. A new test stops touching the env
- The piece that makes it possible is the **factory**: the env asks for a `base_tester` and
  the test decides which one arrives, with `set_type_override`
- The abstract class `base_tester` has the `run_phase` **written a single time**;
  the only thing each tester redefines is `get_op()` and `get_data()`
- The three rules for writing adaptable code: **one class, one thing**; no
  copying and pasting structure; and programming against the **base class**

Note:
It is the unit where all of day 2 gets collected. It is worth making it explicit by pointing at
the `add_test`: it is **two lines** —the override and nothing else—, and it changes the whole
stimulus without touching the env. That could not be done in the object-based testbench.
The *intractable* / *adaptable* distinction is the one to leave as
vocabulary, because it comes back with the agent and with the sequences.
Intractable code is the one that comes out fast and afterwards will not let itself be touched: almost
always it is duplicated structure.

## Reporting

#### *47 % of the time goes here*

- The day-1 trends chart said that almost half of a verification engineer's time
  goes into **debug**. This section is about that half
- A scoreboard that only says `FAIL` leaves you right there: you know something is wrong and
  you do not know which component, at what moment, or with what data
- The natural reaction is to fill the code with `$display`, and then delete them.
  And put them back next week
- UVM solves it the other way round: the messages **stay in** and get filtered. Each
  one brings along the time, the hierarchical path of the component and the file
- And there are two different knobs, which get confused all the time: **verbosity**
  filters `` `uvm_info ``; the **actions** control warnings, errors and fatals

Note:
It is worth going back to the day 1 chart before starting, because this section looks
like plumbing and it is the one that returns the most hours. The argument is not "nice
messages": it is that a message that brings along the hierarchical path saves you the question
"who said it?", which is half of any debug.
The second idea, which is the one that costs: debug messages **do not get deleted**. A
`` `uvm_info `` at UVM_HIGH costs nothing when the ceiling is at UVM_MEDIUM, and
the day you need it, it is there. That the day 5 exercise gets solved by raising
the verbosity is no coincidence — it is set up so that they live it.
And the distinction on the last line is worth writing on the board from the start,
because it is question 6 of the review: verbosity and info on one side, actions and
error/warning/fatal on the other. They never cross.

---

## Reporting

#### *What `$display` cannot do*

- A thousand operations per test, dozens of tests per regression: one `$display` per
  transaction and the log stops being readable before the first coffee
- And with `$display` the only way of lowering the noise is **deleting lines**, that is,
  losing exactly what you are going to need next time
- UVM replaces the `$display` with four macros that bring two things for free:
  context —time, component, file— and a **filter** that is driven from
  outside

Note:
The question that orders the slide, and it is worth throwing it at the group before the
answer: *what is wrong with `$display`?* The answer that always comes is "it is
ugly", and it is not that one. `$display` prints **or does not exist**: the decision of whether a
message comes out is taken at the moment of writing it, by editing the code.
What UVM adds is not format, it is that the decision moves to the moment of
**running**, and it is taken from outside with a plusarg. That change of moment is the whole
section: that is why the messages can be left in place, and that is why the log of a
regression and the log of a debug can come out of the same binary.
The piece of context, for whoever comes from VHDL or plain Verilog: none of this
is simulator magic. `` `uvm_info `` is a macro that assembles a string and hands it
to an object —the *report server*— that decides what to do. Everything that follows in
the section is configuring that object.

---

## Reporting

#### *The reporting macros*

- There are four and they differ by **severity**: `` `uvm_info ``,
  `` `uvm_warning ``, `` `uvm_error `` and `` `uvm_fatal ``. **All four** are counted
  in the *Report Summary*; what changes is the default **action** — `` `uvm_error ``
  comes with `UVM_DISPLAY|UVM_COUNT` and `` `uvm_fatal `` also kills the simulation
- The **ID** is the first argument: a string that says who is talking. It is what you filter
  with afterwards, so it is worth making it the name of the component and always the
  same one
- The **message** is the second, and it gets assembled with `$sformatf` when it carries data
- The **verbosity** is the third, and **only** `` `uvm_info `` has it: it is the one
  that decides whether the message comes out or not

```sv
// ILLUSTRATION -- not compiled. The signature of each macro, not a call.
`uvm_info   (Message ID String, Message String, Verbosity)
`uvm_warning(Message ID String, Message String)
`uvm_error  (Message ID String, Message String)
`uvm_fatal  (Message ID String, Message String)
```

Note:
The usual confusion: verbosity filters `` `uvm_info ``, and nothing else. The
warnings, errors and fatals have no verbosity — they are controlled with actions, which
is the last part of the section.

---

## Reporting

#### *The reporting macros: what each one does*

- This is how it looks in the scoreboard: a `` `uvm_error `` when the comparison fails, with
  the message assembled with `$sformatf`
- And this is how it comes out in the log. Look at what the line brings **without anybody asking
  for it**: the time, the file and the line, and the hierarchical path of the component that spoke

```sv
      data_str = $sformatf(
          " %2h %0s %2h = %4h (%4h predicted)",
          cmd.A,
          cmd.op.name(),
          cmd.B,
          t,
          predicted_result
      );

if (predicted_result != t) `uvm_error("SCOREBOARD", {"FAIL: ", data_str})
      else `uvm_info("SCOREBOARD", {"PASS: ", data_str}, UVM_HIGH)
```

```plaintext
UVM_ERROR tb_classes/scoreboard.svh(39) @ 290: uvm_test_top.env_h.scoreboard_h [SCOREBOARD] FAIL:  5b add_op ff = 015a (015b predicted)
```

Note:
Worth stopping on the log line and reading it out loud from left to right,
field by field, because it is the one the student is going to look at a thousand times and nobody ever
explains it: severity, time, file and line of the `` `uvm_error ``, and then
`uvm_test_top.env_h.scoreboard_h` — the instance path. Only then comes the ID
and the message.
The pedagogical point is what is **not** in the code: the scoreboard did not print
the time or its own name. The macro put them in. That is the whole argument in
favour of never writing a `$display` in a testbench again.
And the honest comparison with the `$error` of day 2: that scoreboard also
made the test fail, but the context had to be written by hand — and there nobody
writes the hierarchical path, because they do not know it.

---

## Reporting

#### *The six levels, and why the message stays*

- The usual cycle: you fill the code with `$display`, you find the bug, you delete
  everything — and next week you write it again
- With verbosity the messages **stay in place** and do not get in the way. It is two steps,
  and the second one does not touch the code:
  - put a verbosity on each `` `uvm_info ``, according to how much noise it is
  - set the **ceiling** of the run: global, or per branch of the tree
- A message comes out if its verbosity is **less than or equal to** the ceiling. That is why
  `UVM_NONE` always comes out

```sv
// ILLUSTRATION -- not compiled. uvm_object_globals.svh:382-390, uvm-core 2020.3.1,
// copied verbatim: code/.uvm/ is downloaded and gitignored, so the slide cannot
// pull the enum straight out of the library.
typedef enum {
   UVM_NONE   = 0,
   UVM_LOW    = 100,
   UVM_MEDIUM = 200,  // the default: with nothing set, UVM_MEDIUM is what you get
   UVM_HIGH   = 300,
   UVM_FULL   = 400,
   UVM_DEBUG  = 500
} uvm_verbosity;

// Any message above the verbosity that was set does not get printed
```

Note:
The six levels, from least to most noisy: `UVM_NONE`, `UVM_LOW`, `UVM_MEDIUM`
—the default one—, `UVM_HIGH`, `UVM_FULL` and `UVM_DEBUG`. `UVM_FULL` is the one
nobody uses and the one that shows up in the enum on the slide, so it is worth
naming. A message gets printed if its
verbosity is **less than or equal to** the ceiling, so `UVM_NONE` always comes out.
The rule of thumb worth handing down, because otherwise everybody invents their own:
`UVM_LOW` for what you want to see in a regression —which test ran, how many
transactions—; `UVM_MEDIUM` for the summary of a component; `UVM_HIGH` for
every transaction that goes past. The monitors of the course are `UVM_HIGH` precisely for
that: in a normal run they are not seen, and when something fails they get switched on with a
plusarg.
The formal detail that gets copied wrong: the verbosity is the **third** argument of the
`` `uvm_info ``, and if you forget it, it does not compile. The ID —the first one— is a free
string, but do not pick it at random: it is the key you are going to filter with afterwards.
Make it the name of the component, in capitals, and always the same one.

---

## Reporting

#### *The global ceiling: a plusarg, without recompiling*

- It gets set in two ways, and the first one is the one used every day: a
  **plusarg** on the command line
- No code to touch and no recompiling. The same binary gives the log of the
  regression and the log of the debug
- The problem shows up with the team: if there are ten people with their own debug
  messages, raising the global ceiling brings you everybody's
- That is why it has to be possible to ask for it **per component**, which is the next slide

```plaintext
./obj_dir/top/sim +UVM_TESTNAME=random_test +UVM_VERBOSITY=UVM_HIGH
```

Note:
Worth running it live, because it is the cheapest demonstration of the section:
the same line above —`./obj_dir/top/sim +UVM_TESTNAME=random_test`— with and without
`+UVM_VERBOSITY=UVM_HIGH`, and the log goes from 7 `uvm_info` to 22. With `make` they are
6 and 21, because `run_sim` adds `+UVM_NO_RELNOTES` and that takes the banner away. Without recompiling anything — it is the same binary. They look
like few because this example sends **ten** operations on purpose, so the transcript fits
on the screen; with the thousand of the other sections the difference is three orders of
magnitude.
The detail that has to be said so that it does not surprise anybody later: the plusarg sets the
ceiling of the **whole tree**, from `uvm_top` down. There is no way of asking for
"high, but only the monitor" from the command line with this flag; for that
there is `+uvm_set_verbosity`, which is longer to type and almost nobody remembers.
The honest way out, and the one the next slide teaches, is setting it from the
code in the component you care about.
And the underlying argument, in case the group underrates it: this is the mechanism that
makes a regression log of a thousand tests readable. It is not classroom cosmetics.

---

## Reporting

#### *`uvm_cmdline_processor`: the command line, whole*

- `+UVM_VERBOSITY` and `+UVM_TESTNAME` are not read by magic: they are read by **a class**, and
  it is available for your own plusargs

```systemverilog
uvm_cmdline_processor clp = uvm_cmdline_processor::get_inst();
string valor;

if (clp.get_arg_value("+COUNT=", valor)) count = valor.atoi();
```

- It is a **singleton**: `get_inst()` from any class, without building anything and
  without passing it through the `config_db`
- `get_arg_value` returns **how many times the argument appeared**, not the value:
  the value comes out through the `ref`. If it appeared twice you find out — `$value$plusargs`
  keeps quiet with the first one
- And there are `get_args()`, `get_plusargs()` and `get_uvm_args()`, which return the
  whole command line in a queue: it is how you print under what conditions
  a regression from three months ago ran

Note:
The course uses `$value$plusargs` and `$test$plusargs` in the `base_test` because they are
one line and they read themselves. Worth saying why in a production testbench
this class always shows up: `$value$plusargs` is a system task, so it cannot
be inherited, it cannot be substituted by the factory and it cannot be tested. The
`uvm_cmdline_processor` is an object, and that is enough for the three things.
The argument that pays off most is the last bullet and it is not the one you would expect:
`get_args()` printing the whole line in the `start_of_simulation_phase` is what
turns an old log into something reproducible. Without that, the log says what happened
but not what it was run with, and a regression from three months ago cannot be repeated.
The difference in the second bullet is worth an anecdote: two `+COUNT=` on the same
line —because the script adds them and the user does too— is a real case, and
`$value$plusargs` takes one without saying which. The `uvm_cmdline_processor` returns 2,
so at least you can notice. It is the kind of thing you pay for once and remember.

---

## Reporting

#### *The ceiling per branch: two methods and a tree*

- Every `uvm_component` comes with methods to set its own ceiling, in two flavours:
  only itself, or itself **and everything hanging below** (`_hier`)
- Careful about which hierarchy it is: it is **not** the DUT's module one. It is the tree that UVM
  assembles by calling `build_phase()` from the top down
- It is the same tree the prefix of each message comes out of, and the same one the
  `uvm_config_db` uses as a scope

![Instance hierarchy UVM builds in build_phase](../res/diagrams/en/UVM-hierarchy.svg)

Note:
This diagram is worth more than it looks, because it explains where that
very long prefix each message brings comes from: `uvm_test_top.env_h.scoreboard_h`. It is not
decoration — it is the **instance path** of the component that spoke.
And it is the same path the `uvm_config_db` uses for the scope. Worth saying it
explicitly: when in the tests we said "the scope is a hierarchical path", it was
literally this path. A single tree serves both purposes.
The clarification in the bullet is not a detail: this hierarchy **is not the DUT's**. A
scoreboard is not inside any module. It is the tree UVM assembles by calling
`build_phase` from the top down, and it exists only in the testbench.
Classroom trick: `uvm_top.print_topology()` prints this tree for real, written by
the library. It is the best way of showing that it is not a drawing.
`+UVM_CONFIG_DB_TRACE` is a different thing and it is better not to mix them: it does
not draw the tree, it traces every `set()` and every `get()` of the `config_db` with
the scope that was used — which is the knob for the other problem, the scope that
does not match.

---

## Reporting

#### *The ceiling per branch: where the call goes*

- The call goes **after** the hierarchy exists —otherwise the component
  is not there yet— and **before** the simulation starts
- That window has a name and it is one of the nine phases: `end_of_elaboration_phase`
- `set_report_verbosity_level_hier()` reaches the component **and its children**;
  `set_report_verbosity_level()`, only it

```sv
   // To use the UVM hierarchy to control verbosity, the reporting methods have to
   // be called after the UVM hierarchy has been built, but BEFORE the simulation
   // starts. That is what end_of_elaboration_phase is for
   function void end_of_elaboration_phase(uvm_phase phase);
      //scoreboard_h.set_report_severity_action_hier(UVM_ERROR, UVM_NO_ACTION);
      scoreboard_h.set_report_verbosity_level_hier(UVM_HIGH);
   endfunction : end_of_elaboration_phase
```

Note:
The window is what has to be left burned in, because the mistake gets made in both
directions. If the call goes in the `build_phase`, the component whose ceiling you want
to raise **does not exist yet** —its parent builds it further down— and the
call finds nobody. If it goes in the `run_phase`, the simulation has already started and
you missed the messages of the earlier phases.
`end_of_elaboration_phase` is exactly the gap between the two things: the whole
tree, and the time still at zero. It is the first time in the course that it gets
used for anything, and it is worth saying it that way — in the table of the nine
phases of day 3 it was not decoration.
The `_hier` suffix is the one that gets forgotten, and it fails silently: you set the ceiling of the
`env` without `_hier`, the `env` prints nothing anyway, and the monitor you
wanted to hear stays quiet. Rule of thumb: if you are aiming at a branch, `_hier`;
if you are aiming at a class, without.

---

## Reporting

#### *Switching off warnings, errors and fatal messages*

- A real situation: the DUT is fine, the scoreboard predicts the addition wrong, and the class
  is being fixed by somebody else. You need to carry on working in the meantime
- Lowering the verbosity ceiling **does not help**: it only affects `` `uvm_info ``, and what
  has to be silenced is a `` `uvm_error ``
- Another knob is needed

```plaintext
UVM_INFO @ 0: reporter [RNTST] Running test random_test...
UVM_INFO tb_classes/scoreboard.svh(40) @ 150: uvm_test_top.env_h.scoreboard_h [SCOREBOARD] PASS:  43 and_op ff = 0043 (0043 predicted)
UVM_ERROR tb_classes/scoreboard.svh(39) @ 290: uvm_test_top.env_h.scoreboard_h [SCOREBOARD] FAIL:  5b add_op ff = 015a (015b predicted)
...
--- UVM Report Summary ---
** Report counts by severity
UVM_INFO :    4
UVM_WARNING :    0
UVM_ERROR :    2
UVM_FATAL :    0
** Report counts by id
[RNTST]     1
[SCOREBOARD]     5
- $UVM_HOME/src/base/uvm_root.svh:633: Verilog $finish
- S i m u l a t i o n   R e p o r t: Verilator 5.052 2026-09-05
- Verilator: $finish at 820ps
```

Note:
The log on the slide is that of a scoreboard that adds wrong on purpose, and it is worth
looking at the *Report Summary* at the end before the error: `UVM_ERROR : 2`, one for each
`add_op` that came up in the ten operations of the example. That is the sum to do out loud:
with the thousand operations of the other sections it is **a hundred-odd errors**, one per
addition. That is the real problem the section comes to solve — not "the
message is annoying", but that **the log stops being any use for looking for something else**.
The question to throw at the group, because the wrong answer is the intuitive one:
*"I lower the verbosity ceiling and that is it?"*. No. A `` `uvm_error `` has no
verbosity; the ceiling does not touch it. It is the same distinction as the first slide, and
here it gets collected for the first time.
And the honest clarification before teaching how to switch off errors, because otherwise it
sounds odd: this is not so that the regression comes out green. It is to be able to work
half an afternoon while somebody else fixes their class, and it comes out the same day.

---

## Reporting

#### *Switching off messages: where it gets done*

- Warnings, errors and fatals are **immune** to the verbosity ceiling, and it is right
  that they should be: nobody wants to switch off an error by accident
- The knob that does reach them is called **actions**, and it answers another question:
  not *"does it get printed?"* but *"what gets done with this message?"*
- Printing is only one of the seven possible things

```sv
// ILLUSTRATION -- not compiled. uvm_object_globals.svh:354-364, uvm-core 2020.3.1,
// copied verbatim: code/.uvm/ is downloaded and gitignored, so the slide cannot
// pull the enum straight out of the library.
typedef enum {
   UVM_NO_ACTION = 'b0000000,
   UVM_DISPLAY   = 'b0000001,
   UVM_LOG       = 'b0000010,
   UVM_COUNT     = 'b0000100,
   UVM_EXIT      = 'b0001000,
   UVM_CALL_HOOK = 'b0010000,
   UVM_STOP      = 'b0100000,
   UVM_RM_RECORD = 'b1000000
} uvm_action_type;
```

Note:
The seven actions are a bitwise OR, not a list of mutually exclusive options: the
same message can be printed **and** written to a file **and** counted towards the
summary. That is why they combine with `|`.
`UVM_COUNT` is the one most often explained wrong, and it is worth saying it in full:
it is already switched on by default on every `` `uvm_error ``, and what it increments
is **a global counter** for the run, not one per ID. On its own it kills nothing,
because the default maximum is 0, which means "no limit". The one that cuts is
`+UVM_MAX_QUIT_COUNT=N` (`uvm_root.svh:1187`) —or `set_report_max_quit_count(N)`,
`uvm_report_object.svh:578`—, and
that one really is the answer to the four-gigabyte log when a scoreboard fails on
every transaction: you find out anyway, and in thirty seconds instead of in twenty
minutes.
`UVM_NO_ACTION` is the one the next slide uses to switch off the errors, and it has to be
said out loud what it is **not** for: it is not so that the regression comes out green.
It is to carry on working while somebody else fixes their class, and it comes out the same day.
A `UVM_NO_ACTION` that survives a commit is a bug waiting to happen.
And the pair worth naming: `set_report_severity_action` is by severity,
`set_report_id_action` is by that ID string you picked when writing the
message. That is where the discipline of having always used the same one gets paid back.

---

## Reporting

#### *Switching off messages: the complete example, and the log you are left with*

- `set_report_severity_action_hier(UVM_ERROR, UVM_NO_ACTION)` on the scoreboard:
  when an error shows up in there, do nothing
- It goes in the `end_of_elaboration_phase` of the `env`, for the same reason as the
  hierarchical verbosity
- And the log below is the result: same DUT, same broken scoreboard, zero
  errors in the *Report Summary*
- In `code/u4/reporting` the line is written and **commented out**: you uncomment it
  to reproduce this log, and comment it back. That it lives commented out in the repo
  is part of the lesson

```plaintext
UVM_INFO @ 0: reporter [RNTST] Running test random_test...
--- UVM Report Summary ---
** Report counts by severity
UVM_INFO :    1
UVM_WARNING :    0
UVM_ERROR :    0
UVM_FATAL :    0
** Report counts by id
[RNTST]     1
- $UVM_HOME/src/base/uvm_root.svh:633: Verilog $finish
- S i m u l a t i o n   R e p o r t: Verilator 5.052 2026-09-05
- Verilator: $finish at 820ps
```

Note:
Say it out loud: switching off errors is for carrying on working while somebody else
fixes their class, not so that the regression comes out green.
And showing the *Report Summary* of the second log next to the first one is the best
warning the section gives: the testbench says **0 UVM_ERROR** and the DUT is still
exactly as broken as it was when we broke it. That is the reason a
`UVM_NO_ACTION` cannot survive a commit — it is a silent trap, and it is in
the appendix.
The scoreboard of this section adds too much ON PURPOSE, it is the bug we are
showing. That is why `code/u4/reporting/run.sh` exports UVM_ERRORS_OK=1: by
default a uvm_error makes the run fail, and here the error is the example.

---

## Reporting

#### *`uvm_report_catcher`: demoting the error you were expecting*

- `UVM_NO_ACTION` switches off **every** error of a branch. When the test
  verifies the error path on purpose —a `PSLVERR` that has to arrive— what
  has to be silenced is **one single one**, and the rest has to carry on shouting

```systemverilog
class demotar_pslverr extends uvm_report_catcher;
   virtual function action_e catch();
      if (get_severity() == UVM_ERROR && get_id() == "PSLVERR")
         set_severity(UVM_INFO);      // stops counting as an error
      return THROW;                   // and carries on, already downgraded
   endfunction
endclass

demotar_pslverr c = new();
uvm_report_cb::add(null, c);          // null = the whole testbench; or a component
```

- The catcher gets in **before** the report: it sees every message and can change its
  severity, its ID, its text or its action
- `THROW` lets it carry on already modified; `CAUGHT` makes it disappear
- And the difference that matters: the summary prints *Number of demoted UVM_ERROR
  reports : 1*. **The blackout leaves a trace**, which is what `UVM_NO_ACTION` does not do

Note:
It is the right answer to the previous slide, and the difference is one of honesty,
not of syntax. `UVM_NO_ACTION` on the scoreboard switches off the error and the log ends up
identical to that of a healthy testbench: nobody reading that log finds out. The catcher
downgrades **that** message, lets all the others through, and on top of that counts it on a
line of its own in the *UVM Report catcher Summary*. A reviewer who opens the log sees that there was an
error and that somebody decided it was fine.
When it really gets used: in the negative tests, which are half of a serious verification
plan. Writing to a read-only register has to give
`PSLVERR`; the test that proves it **expects** the error, and without a catcher that test
can never come out green. It is exactly the case of the capstone.
The implementation detail that surprises: a catcher is a `uvm_callback`, that
is, the same piece as the callbacks of day 6. That is why it gets registered with
`uvm_report_cb::add` and not with a `set_` of the component.
And the trap: if the catcher is too wide —by severity and nothing else— you have switched off
every error of the testbench with more ceremony than `UVM_NO_ACTION`. The
`get_id()` of the `if` is not optional.

---

## Reporting

#### *Summary of the unit*

- Two knobs, and they do not cross: **verbosity** filters `` `uvm_info ``; **actions**
  decides what gets done with warnings, errors and fatals
- Both can be set per component or per branch, in `end_of_elaboration_phase`
- And there is a third one for the **expected** error: the `uvm_report_catcher` demotes it
  and leaves it counted in the summary, instead of switching it off without a trace
- With that, debug messages get written once and stay in place for
  ever — which is the only thing that makes debug cheap
- And it arrives here, at the end of day 3, on purpose: it is the tool the
  exercises of days 4 and 5 get debugged with — the day 5 one is solved by
  **raising the verbosity**, and there is no other way of finding it

Note:
Close the day by going back to the 47 %: of everything seen today —tests, components,
phases, env— this is the section used **every day**, and the only one you
notice when it is missing. A testbench without reporting works just the same; debugging it costs
double.
The control question, which is also number 6 of the review: *"I lowered the verbosity
ceiling and the `` `uvm_error `` still shows up, why?"*. If the group
answers it without hesitating, the section closed.
And the warning for the day 5 exercise, worth giving now and not when they are
stuck: the bug is not visible in the default log. It is printed, at `UVM_HIGH`. Whoever
does not remember this section is going to read the code for half an hour before raising
the verbosity.

## Review · Day 3

#### *1 of 7 · `uvm_test`*

**What does `+UVM_TESTNAME=add_test` let you do that you could not do before?**

- [x] Pick the test on an already compiled testbench
- [ ] Run the simulation faster
- [ ] Change the DUT without recompiling: UVM re-elaborates on start-up
- [ ] Lower the verbosity of the messages

> **Pick the test without recompiling** — UVM reads that plusarg and asks the **factory** for the test by name. It is the difference between 1000 tests × 5 minutes of compilation and a single compilation.

---

## Review · Day 3

#### *2 of 7 · UVM Phases*

**In what order does UVM walk the hierarchy in `build_phase` and in `connect_phase`?**

- [ ] Both from the top down
- [ ] Both from the bottom up
- [x] `build_phase` top-down, `connect_phase` bottom-up
- [ ] In the order the components were declared, from the top down

> **Build top-down, connect bottom-up** — and it makes sense: you cannot connect a component that does not exist yet, so first the whole hierarchy gets built and only then does it get connected.

---

## Review · Day 3

#### *3 of 7 · Objections*

**What are `raise_objection()` / `drop_objection()` for in the `run_phase`?**

- [ ] For reporting scoreboard errors
- [x] For keeping the simulation alive while there is work
- [ ] For synchronizing two threads
- [ ] So that the `run_phase`s of every component start at the same time

> **So that the phase does not end early** — every `run_phase` runs in parallel, each one in its thread, and the phase ends when **the last objection drops**. Without raising it, the simulation ends on you at time 0.

---

## Review · Day 3

#### *4 of 7 · The env*

**What does each one get: `uvm_env` and `uvm_test`?**

- [ ] `env` generates the stimulus; `test` assembles the structure
- [ ] Both do the same thing, `env` is optional
- [ ] `env` runs the DUT; `test` runs the scoreboard
- [x] `env` assembles the structure; `test` picks the stimulus

> **Structure vs. stimulus** — each class does **one single thing well**. That is why the `env` almost always has only `build_phase` and `connect_phase`, and the test almost always has only a factory override.

---

## Review · Day 3

#### *5 of 7 · Factory override*

**`set_type_override()` replaces `base_tester` with `add_tester`. When does it have to be called?**

- [x] Before the `build_phase` that creates the object runs
- [ ] At any moment: the factory applies it retroactively to what is already built
- [ ] After the `connect_phase`
- [ ] Inside the `run_phase` of the tester

> **Before the `build_phase`** — the factory decides what to build **at the moment of the `create()`**. If the override arrives late, the `env` has already instantiated the base class and it does nothing.

---

## Review · Day 3

#### *6 of 7 · Verbosity*

**The verbosity ceiling (`+UVM_VERBOSITY=UVM_HIGH`), which macros does it act on?**

- [ ] On all four: info, warning, error and fatal
- [x] Only on `` `uvm_info ``
- [ ] On error and fatal only
- [ ] On none: it only changes the format of the message

> **Only on `` `uvm_info ``** — warnings, errors and fatals are **immune** to the verbosity ceiling, and it is right that they should be: nobody wants to switch off an error by accident. For those you need the *actions* mechanism.

---

## Review · Day 3

#### *7 of 7 · Report actions*

**You want to silence the `` `uvm_error `` of a scoreboard somebody else is fixing. Where does the `set_report_severity_action_hier()` go?**

- [ ] In the `build_phase` of the `env`
- [ ] In the `run_phase` of the test, before raising the objection
- [ ] In the constructor of the scoreboard
- [x] In the `end_of_elaboration_phase` of the `env`

> **In `end_of_elaboration_phase`** — it has to be **after** the hierarchy is built (otherwise the component does not exist yet) and **before** the simulation starts. That phase is exactly that window.

## Exercise · Day 3 · 1 of 2

#### *A new test without touching the structure*

`cd code/ejercicios/d3 && bash run.sh`

- Write `mult_tester` and `mult_test`, with `set_type_override`
- **Without touching `env.svh`**: the structure never finds out that the stimulus changed
- The `env` brings a `chequeo` component that marks the exercise on its own

Note:
Before turning them loose on the exercise, go back to the slide *"The map of day 3: what
replaces what"* of the object-based testbench and read the right-hand column straight through: the
`build_phase` of the env, the config_db, the `run_phase`, the objections and the
`set_type_override` and the `$display` that became `uvm_info`. The six rows are
crossed out, and the day closes there.
It is the day 2 exercise again, but with the factory. Worth having them
compare the two: on day 2 the type was picked in the code of the testbench, here
the factory picks it and the testbench does not change one line.
And have them look at the coverage at the end: with nothing but multiplications it drops to 26 %. A
focused test covers less, and that is the reason many are needed — and
the reason adding one has to be cheap.

## Exercise · Day 3 · 2 of 2

#### *The `uvm_error` that says nothing*

`cd code/ejercicios/d3b && bash run.sh`

- The scoreboard is **right** —it catches every mismatch— and when it fails it
  says `FAILED` and nothing else: even less than the line of the day-1 waves
  exercise
- Make the `uvm_error` say **which one** failed: `A`, `B`, the operation, the
  DUT's result and the one you predicted
- And make the one that **passes** get printed too, at `UVM_HIGH`, so that it
  does not show up in the everyday log
- The checker watches the same bus you do and knows which was the first that
  failed

Note:
It is the short exercise of day 3 and it closes the arc the day-1 waves
exercise opened: there the student was the one reading the `FAILED`, here they
are the one writing it. Ten minutes of typing, and the point is not the `$sformatf`.
The point is the second request, which is the one that surprises: the `PASS`
**also** gets written. The typical reaction is *"what do I want a thousand PASS
lines for?"*, and the answer is that you do not want them today: you want them
the day operation 700 fails and you need to know what happened in 699. That is
why it gets written **and** hidden behind `UVM_HIGH`. That is the difference
between severity and verbosity, told with your hands.
The checker runs the same testbench three times, and it is worth telling because
it is how a log gets tested: one with the DUT broken —`+VTALU_BUG`— so the error
fires and can be read, one with the usual verbosity to demand that the `PASS` is
**not** there, and one with `+UVM_VERBOSITY=UVM_HIGH` to demand that it is there
once per comparison. A message that was not tested all three ways is a message
that is going to lie in the nightly regression.

## Yesterday we left…

#### *Where the testbench stands*

- UVM walked in: `run_test()`, the test, the phases, the `env` and the
  scoreboard, and the `+UVM_TESTNAME` that picks the class from the command line
- The **objection** is what keeps the simulation alive, and the reporting already
  tells verbosity from *action*
- And one bottleneck was left: the scoreboard is **one** and it is wired to the
  monitor. The day there are two listeners, the one that publishes has to be
  edited

Note:
The day 4 recap has to leave the observer problem served, because the whole unit
is that: a producer that does not know its listeners.
It is worth asking the question and waiting: *"if tomorrow they want to measure
coverage as well as compare, where do they touch?"*. The natural answer —"I add a
call in the monitor"— is exactly the one the unit comes to take apart.

---

## Agenda

#### *Day 4 · ≈ 4 h · unit 5 · how the components talk*

- One producer, many listeners
- A single place that watches the wire
- When somebody has to wait
- Who waits for whom

**By the end of the day you can:**

- **Hang** a new subscriber off an analysis port **without touching the one that
  publishes**
- **Choose** between an analysis port and a TLM FIFO, and say which of the two
  blocks
- **Remove** the `#500` at the end of a test and replace it with the objection
  that belongs there

Note:
The first one is row 11 of the closing self-assessment and it is what defines the
unit: the observer exists so that adding a listener does not touch the one that
publishes.
The third one is the second exercise of the day and it stands as an objective on
its own: the `#500` is the patch everybody writes the first time, and taking it
out forces you to understand what keeps the simulation alive.

## One producer, many listeners

#### *Two ways of talking between objects*

- The structural paradigm asks *which steps to follow*. OOP asks **what objects
  there are and how they talk to each other** — and that is where the
  single-`initial` testbench ends
- And talking, between objects, is exactly two things. The difference is whether
  the two run in **the same thread** or not
- **Same thread:** one calls the other's method and comes straight back. It is
  the `write()` of a `uvm_analysis_port` — the first two sections of the day
- **Different threads:** the two run at the same time and they have to be
  **coordinated**, which means somebody is going to have to wait. It is
  `put` / `get` and the TLM FIFOs — the last two
- The whole of day 4 is those two columns. We start with the left-hand one

Note:
This slide is the map of the day: the four sections that follow are the two
columns below, in order.
It is worth writing the two columns on the board and coming back to them every
time a new port shows up, because the question to ask yourself in front of any
UVM port is always the same: **can this block?** If it runs in my thread, no; if
it runs in another one, yes, and then it has to be a `task`.
That is also the criterion that orders the vocabulary of the day: `write()` is a
`function` —it consumes no time—, `put()` and `get()` are `task`. The signature
tells you which side of the divide you are on before you read a line of the
implementation.

---

## One producer, many listeners

#### *The one who publishes does not know who reads it*

- A piece of testbench data almost never has **one** addressee: every command the
  monitor sees is wanted by the scoreboard, the coverage and, tomorrow, the log
- The obvious solution is for the producer to keep a handle to every consumer and
  call their method. It works, and adding a consumer forces you to **touch the
  producer**
- It is the same problem the BFM solved in interfaces and BFM, one level up:
  there we hid the wire, here we want to hide **the list of addressees**
- The answer is an old pattern: the producer publishes on a port and does not
  know —nor care— who is on the other side
- The section builds it by hand with dice first, and only then replaces it with
  `uvm_analysis_port`. The example is deliberately foreign to hardware

Note:
The dice example is deliberate and it is worth defending if somebody asks why we
do not start with the VTALU: you see the pattern without the noise of the
protocol. When it shows up on the DUT in the analysis ports, the student is no
longer learning two things at once.
The question that orders the section: which is the only line that has to be
written to add a fourth observer? A `connect()`. None in the producer. That is
the criterion to look at every line of code from here on with.
And it is worth anticipating the limit, because it is inter-thread communication:
this is communication inside **a single thread**. `write()` is a `function`, it
consumes no time, and it runs in the thread of the one publishing. To talk
between threads something else is needed.

---

## One producer, many listeners

#### *The problem: two dice, three things to count*

- Write a program that simulates rolling two dice (2d6) 20 times and reports the following
  - The average of the values the dice gave
  - A histogram with the frequency of values
  - A coverage report that shows whether every possible value from 2 to 12 came up

![Rolling 2d6: the sum goes from 2 to 12 and 7 is the most likely](../res/funs/en/dados.svg)

Note:
It is worth posing it as a programming problem before showing a single line: they
are three consumers of the same piece of data, and each one does something
different with it. Nobody thinks about hardware here, which is exactly the idea.
The three reports have something in common that is worth pointing out now: none
of them can be worked out from a single roll. The three accumulate and only
report at the end, and that is why the three are going to need two methods, not
one.
And a quick question for the classroom, one that gets collected later: if
tomorrow they ask for a fourth report —the most repeated roll, say—, which files
have to be touched?

---

## One producer, many listeners

#### *The three observers: the same shape, three bodies*

```sv
class average extends uvm_component;
   `uvm_component_utils(average);

protected real dice_total;
   protected real count;

function new(string name, uvm_component parent = null);
      super.new(name, parent);
      dice_total = 0.0;
      count = 0.0;
   endfunction : new

function void write(int t);
      dice_total = dice_total + t;
      count++;
   endfunction : write

function void report_phase(uvm_phase phase);
      `uvm_info("AVERAGE", $sformatf("DICE AVERAGE: %2.1f", dice_total / count), UVM_NONE)
   endfunction : report_phase

endclass : average
```

- `average` is the simplest one: a `write(int t)` that accumulates, and a
  `report_phase()` that divides and reports at the end
- That is the **shape** the three of them are going to have: they receive one
  roll at a time, and the result only exists once everything is over

Note:
It is worth showing the whole class only once —this one— and after that only the
`write()`s, because what matters is that the shape repeats.
Two details that get collected later: the `report_phase` runs **after** the
`run_phase` —and after `extract` and `check`—, not inside it, and that is why the
average comes out complete. And `dice_total` and `count` are `protected`: the one
publishing cannot touch them, only call `write()`.
When this is the VTALU, in the analysis ports, `average` is going to be the
scoreboard and the `report_phase` the verdict of the run. Same shape.

---

## One producer, many listeners

#### *The other two: the body changes, not the shape*

```sv
   function void write(int t);
      rolls[t]++;
   endfunction : write
```

```sv
   function void write(int t);
      the_roll = t;
      dice_cg.sample();
   endfunction : write
```

- `histogram` keeps the rolls in an associative array and draws the bars in the
  `report_phase`
- `coverage` copies the roll into `the_roll` and calls `sample()`: it is the
  covergroup of the conventional testbench, with the sampling tied to the data
  instead of to the clock
- The three `write()`s are different on the inside and **identical on the
  outside**: same name, same argument. That is what is going to let us treat them
  the same

Note:
The point of the slide is the last bullet: three classes that look nothing alike
expose the same door. When `uvm_subscriber` shows up, that door is going to be a
contract of the language instead of a convention.
The `coverage` here is the answer to a question left open in the conventional
testbench: *where do I sample?* Here the `sample()` is not tied to a clock edge,
it is tied to **a piece of data having arrived**. That is the right thing, and it
is what the `coverage` of every testbench of the course does from here on.
The whole file of each one is in
`code/u5/varios-objetos/01-sin-analysis-port/`: what is not shown is the
`report_phase`, which only formats.

---

## One producer, many listeners

#### *The producer: it rolls the dice and returns a number*

```sv
class dice_roller extends uvm_component;
   `uvm_component_utils(dice_roller);

rand byte die1;
   rand byte die2;

constraint d6 {
 die1 >= 1;
 die1 <= 6;
 die2 >= 1;
 die2 <= 6;
 }

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

function byte two_dice();
      byte the_roll;
      void'(randomize());
      the_roll = die1 + die2;
      return the_roll;
   endfunction : two_dice

endclass : dice_roller
```

- `dice_roller` randomizes two bytes with a `constraint` that keeps them between
  1 and 6, and returns the sum
- That is all it does, and it is right that it should be all: **it produces the
  data and knows nothing about who uses it**
- Look at what it does **not** have: not a handle to `coverage_h`, nor to
  `histogram_h`, nor to `average_h`. That list lives somewhere else, and that is
  where the problem is

Note:
It is worth stopping on the absence: the producer is already well written. It
does not need fixing, and in fact in the version with an analysis port it barely
changes.
The `void'(randomize())` deserves a comment in passing: it throws away the return
value on purpose. In the transactions we are going to see why that is a bad habit
—a `randomize()` that fails and nobody finds out— and how it gets written
properly.
The question to leave hanging: if the producer does not have the list, who does?
The slide that follows.

---

## One producer, many listeners

#### *The one handing it out: the test, and it should not be*

- The `dice_test` extends `uvm_test`, instantiates the four components and starts
- It works. But look at the `run_phase`, and in particular at what is inside the
  `repeat (20)`

```sv
   task run_phase(uvm_phase phase);
      int the_roll;
      phase.raise_objection(this);
      // This part needs attention.
      // What belongs here is:
      //	the Observer design pattern
      //	a UVM analysis port
      // Otherwise none of the OOP magic is being used:
      // these are plain functions passing data along
      repeat (20) begin
         the_roll = dice_roller_h.two_dice();
         coverage_h.write(the_roll);
         histogram_h.write(the_roll);
         average_h.write(the_roll);
      end
      phase.drop_objection(this);
   endtask : run_phase
```

Note:
This slide is the "before", and it has to be allowed to look ugly. Look at the
`repeat (20)`: three `write()`s written out by hand, one per observer. Adding a
fourth means touching this class; removing one, too.
Worse still, and it is what is worth pointing at: the one left in charge of
handing out the data is **the test**. Which means the `dice_roller` produces and
the test distributes — two responsibilities that have no reason to be together,
and the distributing one is the one that is going to change all the time.
The question to throw out before moving on to the next one: if this were the
VTALU, who would the `dice_roller` be and who the three `write()`s? The monitor,
and the scoreboard plus the coverage. The analysis ports are literally this slide
with other names.

---

## One producer, many listeners

#### *Observer Design Pattern*

- Whoever publishes a tweet does not know who reads it or what they do with it,
  and yet it reaches everybody. That is the **Observer**
- An object produces a piece of data and publishes it. The ones who need that
  data subscribe. The producer **does not keep the list**
- Here the observed one is `dice_roller_h`; the observers —*subscribers*— are
  `coverage_h`, `histogram_h` and `average_h`
- The property that buys everything: adding a fourth observer **does not touch
  one line** of the one producing

![Observer: one sender publishes and N observers receive](../res/funs/en/observer-broadcast.svg)

Note:
The analogy works better the other way round: the one who publishes does not know
who reads them, and that is exactly the property you want in a monitor. Adding a
new subscriber —another coverage, a log— does not touch one line of the one
producing the data.
The dice example is deliberately foreign to hardware: you see the pattern without
the noise of the protocol.

---

## One producer, many listeners

#### *The pattern, ready-made: the two ends of the wire*

- UVM brings the pattern ready-made, in two classes that are the two ends of the wire:
  - *uvm_analysis_port:* Sends data to a set of subscribers (observers)
  - *uvm_subscriber:* An extension of uvm_component that lets the component subscribe to a uvm_analysis_port

![Notation: diamond = uvm_analysis_port, circle = analysis_export](../res/diagrams/en/varios-objetos_ports.svg)

Note:
The names cost a minute and save half an hour later: **port** is the end of the
one producing, **export** the end of the one consuming, and the `connect()` is
always called on the port.
`uvm_analysis_port` is a *broadcast*: it does not care whether it has zero, one
or ten subscribers, and writing to an unconnected port is not an error — the data
is lost in silence. It is one of the silent traps of the course, and the symptom
is a scoreboard that never reports anything.
`uvm_subscriber` is the other end and it is a parameterized class: `#(int)` here,
`#(command_transaction)` in the analysis ports. The connection ends up **typed**
by the compiler, not by a string.

---

## One producer, many listeners

#### *uvm_analysis_port*

- We declare a variable of type *uvm_analysis_port* that states the type of data it is going to carry
- We instantiate the analysis port in *build_phase*
- We write data into the port through the *.write()* method
- Once we write data into the port, it goes to all of its subscribers
- We use the *connect()* method to connect the subscribers to the port. This method takes a single argument, and it is the subscriber's **export** (`analysis_export`), not another port

```sv
// Same as version 01, but publishing: instead of returning the number it writes
// it to an analysis port, and stops knowing who reads it.
class dice_roller extends uvm_component;
   `uvm_component_utils(dice_roller);

rand byte die1;
   rand byte die2;

constraint d6 {
 die1 >= 1;
 die1 <= 6;
 die2 >= 1;
 die2 <= 6;
 }

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

// 1) declare the port, with the data type it will carry
   uvm_analysis_port #(int) roll_ap;

// 2) instantiate it in build_phase, with new(): ports do not go through the factory
   function void build_phase(uvm_phase phase);
      roll_ap = new("roll_ap", this);
   endfunction : build_phase

task run_phase(uvm_phase phase);
      int the_roll;
      phase.raise_objection(this);
      repeat (20) begin
         void'(randomize());
         the_roll = die1 + die2;
         // 3) write: the port calls write() on every subscriber
         roll_ap.write(the_roll);
      end
      phase.drop_objection(this);
   endtask : run_phase

endclass : dice_roller
```

Note:
Three steps and no more: declare the port, instantiate it in build_phase, write
with write(). On the other side the subscriber implements write() and gets
connected in connect_phase.
The detail that surprises: ports are not created with the factory, they are
instantiated with new().

---

## One producer, many listeners

#### *uvm_subscriber*

- We extend the *uvm_subscriber* class parametrically, so that it knows what type of data it is going to read
- The class gives us an object called *analysis_export*
- The class requires us to write a method called *write()* that takes a single argument *t*, of the same type as the extension of the class
- In our example, we have 3 subscribers (average, coverage and histogram)

```sv
// uvm_subscriber:
//    extends the uvm_component class and lets you hook onto an analysis port
//    It is a parameterizable class!
//    The class gives you something and asks for something in return
//       * It gives you an object called analysis_export
//       * It asks you to write a write() method that handles the data

class coverage extends uvm_subscriber #(int);
   `uvm_component_utils(coverage);
   int the_roll;

covergroup dice_cg;
      coverpoint the_roll {bins twod6[] = {2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};}
   endgroup

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

function void write(int t);
      the_roll = t;
      dice_cg.sample();
   endfunction : write

function void report_phase(uvm_phase phase);
      `uvm_info("COVERAGE", $sformatf("COVERAGE: %2.0f%%", dice_cg.get_inst_coverage()),
                UVM_NONE)
   endfunction : report_phase

endclass : coverage
```

Note:
`uvm_subscriber` is a deal in two parts and it is worth stating it that way: **I
give you an `analysis_export`, you give me back a `write()`**. Nothing else. The
`analysis_export` is neither declared nor instantiated — it comes with the class.
The `#(int)` of the `extends` is the parameterized classes getting collected
again: it defines what type the `t` of the `write()` is, and the compiler takes
care that a port of `int` cannot be connected to a subscriber of something else.
The connection is **typed**, it is not a string.
Comparing it with the previous version of this same class is worth it: the
`write()` is identical. The only thing that changed is who it inherits from and
who calls it. That is the entire point of the section — the observer never finds
out that it is now an observer.
And a detail that shows up in the output: here the coverage is read with
`get_inst_coverage()`, not with `get_coverage()`. It is a Verilator limitation
—the type-wide one always returns 0— and it is in `docs/en/verilator.md`.

---

## One producer, many listeners

#### *The producer, publishing now*

```sv
   // 1) declare the port, with the data type it will carry
   uvm_analysis_port #(int) roll_ap;

// 2) instantiate it in build_phase, with new(): ports do not go through the factory
   function void build_phase(uvm_phase phase);
      roll_ap = new("roll_ap", this);
   endfunction : build_phase

- The three numbered steps are everything that changed with respect to the
  previous version: declare the port, instantiate it in `build_phase`, write with
  `write()`
- `roll_ap = new(...)`: ports are **not** created with the factory. They are the
  wiring of the testbench, not interchangeable pieces
- The `two_dice()` that returned a number is gone: now the roll gets published
  and the producer carries straight on

Note:
The comparison with the previous version is the whole slide: the `dice_roller`
did not gain a handle to anybody. It gained **one** port.
Why ports go with `new()` and not with `type_id::create()`: the factory is there
to substitute types, and a port never gets substituted. It is a question that
always comes up and that is the short answer.
And the `write()` here is worth looking at with inter-thread communication in
mind: it is a `function`, so it **consumes no time** and it runs in the
producer's thread. When the one consuming needs to make the one producing wait,
this is not enough.

---

## One producer, many listeners

#### *connect_phase(): where the wiring gets assembled*

- We need to link the producer with the consumer
- UVM provides a phase method (*connect_phase()*) to connect the objects
- UVM calls the build_phase method TOPDOWN, and once it is done with every object in the hierarchy, UVM calls the connect_phase method BottomUP
- The connection process has 2 fundamental parts
  - uvm_subscribers contain an object called analysis_export, which we must not instantiate since it comes along when we extend the uvm_subscriber class
  - The uvm_analysis_port class provides a method called connect()

Note:
The order of the two phases is not an implementation detail, it is what makes
this work: you cannot connect what does not exist yet. That is why `build_phase`
is top-down and finishes **entirely** before the first `connect_phase` starts.
That `connect_phase` is bottom-up matters less in practice, but it has its
reason: a composite component connects its children to each other only once every
child has connected its own. In the agents, when the agent connects driver and
sequencer inside itself and the env connects the agent outwards, it will show.
The `analysis_export` that shows up on its own is one of the few things in UVM
that come free: it comes with the class, and forgetting to instantiate it is not
a mistake because there is nothing to instantiate.

---

## One producer, many listeners

#### *connect_phase(): where the wiring gets assembled*

- A single line of `connect_phase()` hooks the subscriber up to the analysis
  port: `ap.connect(sub_h.analysis_export)`

```sv
   // build_phase: UVM calls it TOP-DOWN, the parent first.
   function void build_phase(uvm_phase phase);
      dice_roller_h = new("dice_roller_h", this);
      coverage_h = new("coverage_h", this);
      histogram_h = new("histogram_h", this);
      average_h = new("average_h", this);
   endfunction : build_phase

// connect_phase: BOTTOM-UP, and always port.connect(export).
   function void connect_phase(uvm_phase phase);
      dice_roller_h.roll_ap.connect(coverage_h.analysis_export);
      dice_roller_h.roll_ap.connect(histogram_h.analysis_export);
      dice_roller_h.roll_ap.connect(average_h.analysis_export);
   endfunction : connect_phase
```

Note:
This is the "after", and it has to be put next to the "before", the version
without the analysis port. The `run_phase` of the test is left without the three `write()`s: now it
only raises the objection and starts the producer. The distribution moved to the
`connect_phase`, which is where the structure goes.
The line to read slowly is
`dice_roller_h.roll_ap.connect(coverage_h.analysis_export)`, and the direction
matters: **the port connects to the export, never the other way round**. It is
the mantra that comes back in threads, in put and get and in agents, and the
compiler does not always catch you.
Pocket rule to remember the direction, and it has to be said this way because the
easy version breaks straight away: the one that calls `connect()` is **the one
that has the port**, and it hands it the other one's export. Here the one with the
port is the producer; in put and get the `uvm_get_port` belongs to the
**consumer**, and there it is the consumer that connects. "The producer connects"
works on this slide and fails in the next section.
And the acid test of the section: to add a fourth observer you have to write the
class and **one** line here. Not one in `dice_roller`.

---

## One producer, many listeners

#### *The solution, wired up*

- In the connection diagram we can see that the dice_roller class has a uvm_analysis_port object called roll_ap
- Each subscriber has an analysis_export object
- The connection between the two is made through the connect() method

![Wiring of the dice example: roll_ap against the three analysis_export](../res/diagrams/en/varios-objetos_spicy.svg)

Note:
It is the first TLM diagram of the course and it is worth teaching how to read it
now, because the ones from the rest of the day and the one from the agents use
the same convention: **diamond** is analysis port, **square** is put/get port,
**circle** is export. The arrow goes from the one producing to the one consuming.
What has to be pointed out about the drawing is that three arrows come out of the
`roll_ap` and **a single line of code** comes out of the `dice_roller`: the
`write()`. The multiplicity is not in the producer, it is in the wiring.
And the closing of the section, which links to the next one: all of this happened
inside a single thread. `write()` is a `function`, it cannot have an `@` or a
`#`, and it came back before time moved. When the one producing and the one
consuming have to wait for each other, this is not enough — and that is
inter-thread communication.

---

## One producer, many listeners

#### *Summary of the unit*

- Two objects talk to each other in **exactly two ways**, and the difference is
  whether they run in the same thread or not
- **Same thread**: one calls the other's method and comes straight back. It is a
  `function`, **it cannot block**. It is the `write()` of an analysis port
- **Different threads**: they have to be coordinated and somebody is going to
  wait. It is a `task`, **it can block**. It is `put`/`get`, and they are the
  last two sections
- The question in front of any UVM port is always the same: **can this block?**
  The signature tells you before you read the implementation
- The **analysis port** solves the underlying problem: the one who publishes
  **does not know who reads it**, and adding a reader does not touch one line
- It is the same old *observer* pattern, and it is the same move the BFM made in
  interfaces and BFM: one level up

Note:
The slide to open and close day 4 with, because it is the map. Write the two
columns on the board and come back to them every time a new port shows up.
And the criterion that orders the whole vocabulary: `write()` is a `function` —it
consumes no time—, `put()` and `get()` are `task`. In SystemVerilog that is not a
naming convention, it is the language telling you which side you are on.

## A single place that watches the wire

#### *A single place that watches the wire*

- Today the scoreboard and the coverage each watch **the signals** on their own:
  both wait for `done`, both read `op_set`, both know the protocol
- That is the same code written twice, and the day the protocol changes you have
  to remember both places
- The missing piece has a name in the industry: the **monitor**. A single one
  watches the bus, assembles the transaction and publishes it
- The scoreboard and the coverage become **subscribers**, like the dice of the
  previous unit: they never touch a wire again
- In UVM jargon those two form the *analysis layer*, and that is where the name
  `uvm_analysis_port` comes from

Note:
It is the same pattern as the dice, now on the DUT — and that is the whole section.
What has to be stressed is where the dividing line of the testbench runs, because
it is the one that orders everything that comes after: **on one side of the
monitor you speak in signals, on the other in transactions.** The BFM of
interfaces and BFM did that for the stimulus; the monitor does it for the
analysis.
The practical consequence is worth saying out loud: from here on, any analysis
component can be written without knowing anything about the protocol. A new
subscriber does not need to know that a `done` exists.
And the one that only shows up in the agents: if everything that knows how to
speak the protocol is together —BFM, monitors, driver—, that box can be
instantiated twice. That is the agent, and this section is the one that gathers
the pieces.

---

## A single place that watches the wire

#### *Which pieces show up*

- **`command_monitor`** — watches the start of every operation and publishes what was asked for
- **`result_monitor`** — watches the `done` and publishes what the DUT answered
- The **BFM** stops being only signals: it gains three `always` and a handle to each monitor
- The **scoreboard** and the **coverage** stop waiting for edges and get a
  `write()` instead
- The **`tester`** never finds out about any of it: it goes on sending stimulus just like yesterday

Note:
The slide is the inventory of the section and it is worth using it as a map:
there are five pieces and only two are new. It is worth saying out loud which
ones, because the student tends to believe that a new topic rewrites the whole
testbench.
That there are **two** monitors and not one is the decision that gets asked about
the most, so better to get ahead of it: they watch different things and at
different moments. The `command_monitor` watches when an operation starts; the
`result_monitor`, when the DUT answers. Between those two instants there are
cycles in the middle, so they cannot be the same `always`.
And the last bullet is the one to underline, because it is the promise the
section keeps: the `tester` **does not get touched**. All the work of this
section happens on the analysis side, and the stimulus side never finds out. It
is the first time the course separates the two halves of the testbench, and in
the section that follows the other one gets done.

---

## A single place that watches the wire

#### *Testbench diagram*

![VTALU testbench with analysis ports](../res/diagrams/en/analysis-ports_fig102.svg)

---

## A single place that watches the wire

#### *The handles the BFM keeps*

- Up to now the class read the interface. Here it flips around: **the interface
  keeps a handle to the class** and it is the interface that calls the method

```sv
interface vtalu_bfm;
   import vtalu_pkg::*;

// These handles get assigned in the build_phases of the classes
   command_monitor        command_monitor_h;
   result_monitor         result_monitor_h;

byte unsigned          A;
   byte unsigned          B;
   bit                    clk;
   bit                    reset_n;
   bit                    start;
   wire                   done;
   wire            [15:0] result;
   wire                   ovf;
   operation_t            op_set;
```

- These handles are set by each monitor in its `build_phase`, right after pulling
  the BFM out of the config_db

```sv
   function void build_phase(uvm_phase phase);
      virtual vtalu_bfm bfm;

if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "bfm", bfm))
         `uvm_fatal("COMMAND MONITOR", "Failed to get BFM")

bfm.command_monitor_h = this;

ap = new("ap", this);

endfunction : build_phase
```

Note:
This slide holds the inversion that costs the most in the section and it is worth
saying it slowly: up to now **the class read the interface**. Here it is the
other way round — the interface has a handle to the class
(`bfm.command_monitor_h = this`) and it is the interface that calls the method.
The reason is that an `always` of the interface **can** have a sensitivity list,
and a class function cannot. We need the hardware to give notice; for that the
hardware has to know who to give notice to.
The line that does everything is `bfm.command_monitor_h = this`, and it goes in
the `build_phase`. If you forget it, the monitor compiles, runs, and never
publishes: the scoreboard is left without commands and the `uvm_fatal` shows up
on the other side, in a class that is not to blame. It is one of those errors
that get hunted in the wrong place.
A detail that helps: the handle is to the class, not `virtual`. That is why the
`always` can call `write_to_monitor()` directly without the Verilator hole that
affects tasks — here the one declaring the task is the class, not the interface.

---

## A single place that watches the wire

#### *Monitoring the VTALU commands*

- Three `always` in the BFM: the command one fires when an operation starts, the
  reset one on the falling edge of `reset_n`, and the result one when the DUT
  raises `done`

```sv
   // Here is the first monitor (commands)
   // A very simple FSM. If start is up, check whether this is a new command
   // If it is, send it to the TB with commands_monitor.write_to_monitor()
   always @(posedge clk) begin : cmd_monitor
      bit new_command;
      if (!start) new_command = 1;
      else if (new_command) begin
         command_monitor_h.write_to_monitor(A, B, op_set);
         new_command = (op_set == 3'b000);  // handle no_op
      end
   end : cmd_monitor

always @(negedge reset_n) begin : rst_monitor
      if (command_monitor_h != null)  //guard against VCS time 0 negedge
         command_monitor_h.write_to_monitor(A, B, rst_op);
   end : rst_monitor

always @(posedge clk) begin : rslt_monitor
      if (done) result_monitor_h.write_to_monitor(result);
   end : rslt_monitor
```

- And on the other side, the method they give notice to: it packs the `command_s`
  up and publishes it on the analysis port

```sv
   function void write_to_monitor(byte A, byte B, bit [2:0] op);
      command_s cmd;
      cmd.A = A;
      cmd.B = B;
      cmd.op = op2enum(op);
      `uvm_info("COMMAND MONITOR", $sformatf("A:0x%2h B:0x%2h op: %s", A, B, cmd.op.name()
                ), UVM_HIGH)
      ap.write(cmd);
   endfunction : write_to_monitor
```

Note:
The three `always` are the seam between the hardware and the classes, and it is
worth reading the condition of each one: the command one fires when `start` goes
up and there was no command in flight; the reset one, on the falling edge of
`reset_n`; the result one, when the DUT raises `done`.
The guard `if (command_monitor_h != null)` is not paranoia: at time 0 the UVM
tree does not exist yet and the `negedge reset_n` has already arrived. Without
the guard it is a null pointer from the simulator.
The `write_to_monitor()` is short on purpose: it assembles the `command_s`, logs
it with `UVM_HIGH` —which means it is only visible with
`+UVM_VERBOSITY=UVM_HIGH`— and calls `ap.write()`. Everything else happens on the
other side of the port, and the monitor does not know who is over there.
And the detail that gets collected in the transactions: what travels is still a
`struct`. The day it is a transaction, this same line is going to be a
`create()`.

---

## A single place that watches the wire

#### *The VTALU Coverage Class as a Subscriber*

- With the `command_monitor` there is **a single place** in the whole testbench
  that knows what a command looks like on the wire
- Whoever needs to know which operation ran subscribes to its analysis port and
  implements `write()`. They never look at a signal again

```sv
   // With the analysis port this is far simpler,
   // because nothing here has to know about the ALU signals:
   // what arrives is a command_s struct that wraps the command
   //
   function void write(command_s t);
         A = t.A;
         B = t.B;
         op_set = t.op;
         op_cov.sample();
         zeros_or_ones_on_ops.sample();
   endfunction : write
```

Note:
It is worth opening the `coverage` class of the object-based testbench alongside
and comparing: over there was a `forever` waiting for edges; here there is a
`write()` and nothing else. The coverage stopped having any notion of time.
And that is not cosmetic, it is the answer to the question left open in the
conventional testbench: **where the sampling happens**. Before, it sampled on the
clock, which means cycles got counted; now it samples when the monitor sees a
command, which means **operations** get counted. That is the right thing, and the
coverage number changes meaning.
The question for the group: if the DUT sat ten cycles doing nothing, how many
samples did the old version take and how many does this one? Ten and zero. The
old one was filling bins with nothing.

---

## A single place that watches the wire

#### *Subscribing to multiple analysis ports*

- The basic UVM analysis port mechanism lets a uvm_subscriber grab a single analysis_port
- However, in cases like a scoreboard, we need one and the same component to receive data from 2 analysis ports
- The reason for the limit: `uvm_subscriber` gives you **a single** `write()`, and
  that is the method the port calls. Two ports have nowhere to come in
- UVM solves it without splitting the component, with the *uvm_tlm_analysis_fifo* class,
  which is **unbounded by construction**: its constructor passes `size = 0`
  (`tlm1/uvm_tlm_fifos.svh:281`, with the comment "analysis fifo must be unbounded")
- And `write()` is a `function` that does `void'(this.try_put(t))`: it throws the
  return value away. A bounded FIFO would drop **without warning** — which is why
  this one is built with no cap
- It is parameterized and it has two faces: an *analysis_export* on one side
  —which gets connected like any subscriber— and a `try_get()` on the other
- `try_get()` takes an element out and returns 0 if the FIFO is empty, without blocking
- Which means: it turns *"they tell me when it arrives"* into *"I go and get it when I need it"*

Note:
The scoreboard needs two sources —the command and the result— and a
uvm_subscriber can listen to only one. The FIFO turns "they tell me when it
arrives" into "I go and get it when I want", which is what it needs in order to
compare in pairs.

---

## A single place that watches the wire

#### *Subscribing to multiple analysis ports*

- Scoreboard class:

```sv
   uvm_tlm_analysis_fifo #(command_s) cmd_f;

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

// Every time the DUT hands a result to the analysis port, this method
   // gets triggered
   function void write(shortint t);
      shortint  predicted_result;
      command_s cmd;
      cmd.op = no_op;

// Here is where the prediction happens: look in our FIFO for the command
      // that was sent, skipping the resets and the no_ops with the
      // do....while
      // since whenever there is a result there must be an operation,
      // a result with no operation behind it is an error
      do
      if (!cmd_f.try_get(cmd)) `uvm_fatal("SCOREBOARD", "No command in self checker")
      while ((cmd.op == no_op) || (cmd.op == rst_op));

case (cmd.op)
         add_op: predicted_result = cmd.A + cmd.B;
         sub_op: predicted_result = cmd.A - cmd.B;
         and_op: predicted_result = cmd.A & cmd.B;
         xor_op: predicted_result = cmd.A ^ cmd.B;
         mul_op: predicted_result = cmd.A * cmd.B;
      endcase  // case (op_set)

if (predicted_result != t)
         `uvm_error("SCOREBOARD", $sformatf(
                    "FAILED: A: %2h  B: %2h  op: %s actual result: %4h   expected: %4h",
                    cmd.A,
                    cmd.B,
                    cmd.op.name(),
                    t,
                    predicted_result
                    ))
   endfunction : write
```

Note:
The scoreboard is asymmetric and that is where the whole point is: the **result**
reaches it through `write()` —it gets pushed— and the **command** it goes and
fetches itself with `try_get()` from the FIFO. One is push, the other is pull.
Why like this and not two `write()`s: a `uvm_subscriber` has a single `write()`,
and besides the order matters. The scoreboard does not want to be told about the
command when it arrives; it wants it at the moment the result appears, so that it
can compare in pairs. The FIFO turns "they tell me" into "I go and get it when I
want".
The `do ... while` that skips `no_op` and `rst_op` is the part that gets copied
wrong: those two operations **produce no result**, so if they are not thrown
away, the comparison shifts by one place and from there on everything fails. The
symptom is a scoreboard that screams on every line, and it is exactly the day 5
exercise.
And the `uvm_fatal` of the `try_get()` is not paranoia: if there is a result and
there is no command, the broken one is the testbench, not the DUT. Better to die
there than to report a thousand false errors.

---

## A single place that watches the wire

#### *The other way: `` `uvm_analysis_imp_decl ``*

```systemverilog
`uvm_analysis_imp_decl(_cmd)        // makes the class uvm_analysis_imp_cmd
`uvm_analysis_imp_decl(_result)

class scoreboard extends uvm_component;
   uvm_analysis_imp_cmd    #(command_s, scoreboard) cmd_imp;
   uvm_analysis_imp_result #(shortint,  scoreboard) result_imp;

function void write_cmd(command_s t);    ... endfunction   // one write per port
   function void write_result(shortint t);  ... endfunction
endclass
```

- The macro **generates a class** for each suffix, and each one calls a different
  `write_`: that way a component receives from two ports without a FIFO
- It is what you are going to see in most production code, so **you have to be
  able to read it**
- The course uses the FIFO anyway, for an underlying reason: `write_cmd()` runs
  **when the command arrives**, and the scoreboard needs it **when the result
  arrives**. The FIFO gives it that control; the macro forces it to keep the data
  by hand

Note:
Same treatment as the `` `uvm_field_* `` macros of the components and as
`` `uvm_do `` of the sequences: they get named, they get explained, and it gets
said why the course does not use them. The rule of the course, once again:
**read them all, write the explicit ones.**
What the macro hides and is worth saying: `uvm_analysis_imp` is a class that
already exists in UVM; the only thing `` `uvm_analysis_imp_decl `` does is
manufacture variants with a different name, because SystemVerilog does not let
you have two `write()`s in the same class. Which means the macro adds no
mechanism, it adds names.
Where it goes: in the package, **outside** every class, and only once per suffix
in the whole testbench. Declaring it twice with the same suffix is a compilation
error that shows up far from the place where you wrote it.
And the honest comparison: with the macro the scoreboard comes out shorter and
more coupled —it has to carry the command by hand until the result arrives—; with
the FIFO it comes out one line longer and it decides the order itself. For a
scoreboard that matches things up in pairs, the FIFO wins. For a component that
only counts things from two ports, the macro is better.

---

## A single place that watches the wire

#### *Subscribing to the monitors*

- We connect the analysis ports to the monitors using the connect_phase() method in the env class:

```sv
class env extends uvm_env;
   `uvm_component_utils(env);

random_tester   random_tester_h;
   coverage        coverage_h;
   scoreboard      scoreboard_h;
   command_monitor command_monitor_h;
   result_monitor  result_monitor_h;

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

function void build_phase(uvm_phase phase);
      random_tester_h = random_tester::type_id::create("random_tester_h", this);
      coverage_h = coverage::type_id::create("coverage_h", this);
      scoreboard_h = scoreboard::type_id::create("scoreboard_h", this);
      command_monitor_h = command_monitor::type_id::create("command_monitor_h", this);
      result_monitor_h = result_monitor::type_id::create("result_monitor_h", this);

endfunction : build_phase

function void connect_phase(uvm_phase phase);

result_monitor_h.ap.connect(scoreboard_h.analysis_export);
      command_monitor_h.ap.connect(scoreboard_h.cmd_f.analysis_export);
      command_monitor_h.ap.connect(coverage_h.analysis_export);

endfunction : connect_phase

endclass
```

Note:
Three `connect()`s and there is the whole testbench. Worth reading them out loud
as sentences: *the result goes to the scoreboard*, *the command goes to the
scoreboard's FIFO*, *the command also goes to the coverage*.
The surprising one is the second:
`command_monitor_h.ap.connect(scoreboard_h.cmd_f.analysis_export)`.
The export does not belong to the scoreboard, it belongs to **the FIFO the
scoreboard has inside it**. A `uvm_analysis_port` can have several destinations
—the `ap` of the command_monitor feeds two— and it costs it nothing: `write()`
walks through all of them.
And the detail that gets forgotten and gives no warning: `cmd_f` is instantiated
with `new()`, not with the factory. The FIFO **is** registered —`` `uvm_component_param_utils ``
in `tlm1/uvm_tlm_fifos.svh:256`— but the course builds it with `new()` because it
passes the `size` through the constructor and `create()` cannot. What is not in the
factory are the *ports* and the *exports*: they extend `uvm_port_base` with no utils
macro. If you forget the `new()` the `connect()` blows up with a null, and that one
at least is an honest error.

---

## A single place that watches the wire

#### *When the DUT does not answer in order*

- The scoreboard of this section does a `try_get()` from a FIFO: the first command
  that went in is the one that matches the first result that came out. That holds
  because **the VTALU answers in order**, one operation at a time
- A real bus does not. In AXI every transfer carries an **ID** and the responses
  can come back crossed over: the FIFO starts comparing the response of one with
  the request of another, and screams on every one

```systemverilog
transaccion esperado [int];              // associative, indexed by whatever pairs them up

function void write_cmd(transaccion c);  esperado[c.id] = c;  endfunction

function void write_result(respuesta r);
   if (!esperado.exists(r.id)) `uvm_error("SB", "a response nobody asked for")
   else begin comparar(esperado[r.id], r); esperado.delete(r.id); end
endfunction
```

- The pattern is always the same: **a table indexed by whatever pairs them up**, a
  `delete` once it has been compared, and at the end of the run the table **has to
  be left empty**
- That check at the end is half the value: what stayed inside are the requests the
  DUT never answered

Note:
The question that opens the slide is the one to ask of anybody else's scoreboard
before trusting it: *"and what if the DUT answers out of order?"*. The one in
this section falls over, and it is fine that it falls over — the VTALU does not
do that. What is not fine is not knowing it.
The symptom when it happens is cruel and worth anticipating, because it sends you
hunting in the wrong place: it is not **one** comparison that fails, it is
**every** one after the first crossed-over one. The testbench says a thousand
errors and the DUT has zero. It is the row *"the scoreboard screams on every
one"* of the debug appendix, with another cause.
The associative array is the canonical answer and there is no mystery to it; what
always gets forgotten is the `check_phase` that verifies it was left empty.
Without that, a DUT that stops answering passes green: there is never a bad
comparison, there are simply comparisons that were not made. It is the same hole
as the `drain_time` of the tests, seen from the other side.
And the variant that shows up when there is no ID: pairing by content. You keep a
queue of expected ones and look for the one that matches, instead of the first.
It is more expensive and it has a trap of its own —two identical transactions—,
and that is why the ID exists.

---

## A single place that watches the wire

#### *On one side of the monitor you speak in signals, on the other in transactions*

- The **monitor** is the only class that knows a `clk` exists. Coverage and
  scoreboard receive data and have no idea where it came from
- The Observer of talking to several objects, applied to the DUT: the monitor
  publishes and does not keep the list. Adding an observer is one line in the
  `connect_phase`
- And the limit, which is the section that follows: all of this happens in **a
  single thread**. The `always` of the BFM calls `write_to_monitor()`, which
  calls `ap.write()`, which calls the `write()`s of the subscribers — a chain of
  functions, without time moving

Note:
The sentence in the title is the real summary of the section and it is worth
leaving it written up: **on one side of the monitor you speak in signals, on the
other in transactions.** That border is what makes it possible for the scoreboard
of the transactions to exist without looking at a wire.
The third bullet is the hinge towards inter-thread communication: since it is all
a chain of `function`s, no link can wait. If the one consuming needs to make the
one producing wait —or the other way round—, something else is needed, and that
is the `uvm_tlm_fifo`.
Worth asking the question before moving on: what would happen if the `write()` of
a subscriber had an `@(posedge clk)` inside it? It does not compile. A `function`
cannot consume time, and that is the whole limitation.

---

## A single place that watches the wire

#### *Summary of the unit*

- Up to yesterday the scoreboard and the coverage each watched **the signals** on
  their own: the same protocol code written twice
- The piece that was missing has a name in the industry: the **monitor**. A single
  one watches the wire and **publishes** what it saw
- There are two: **`command_monitor`** publishes what was asked for,
  **`result_monitor`** publishes what the DUT answered
- The scoreboard and the coverage become **subscribers**: they stop waiting for
  edges and only implement `write()`
- That pair —monitors that publish, subscribers that analyse— is the **analysis
  layer**, and that is where the name of the port comes from
- The `tester` **never finds out about any of it**. That is the proof the split
  came out right: changing the analysis does not touch the stimulus
- And the scoreboard with a FIFO holds **as long as the DUT answers in order**.
  When it does not, the pattern is a table by ID that has to be left empty at the end

Note:
Closing of the unit where the testbench takes the shape it is going to have until
the end. Worth saying it like this: from here on, every time something new has to
be analysed —one more coverage, one more checker— the answer is always going to
be the same, **hang a subscriber off it**, and never touch the monitor.
It is literally the exercise of the day, and it is also what is going to be left
outside the agent in the agents.

## When somebody has to wait

#### *You were already doing this, with modules*

- The name is scary and you have been using the mechanism forever: two modules
  with ports, each one with its `always`, passing data to each other

```sv
// Sends the data through the shared variable and signals it by toggling get_it
// Then the producer blocks on the put_it signal
module producer (
    output byte shared,
    input  bit  put_it,
    output bit  get_it
);
   initial
      repeat (3) begin
         $display("Sent %0d", ++shared);
         get_it = ~get_it;
         @(put_it);
      end
endmodule : producer

// The consumer blocks on the get_it signal, waiting for data from the producer
// when the producer toggles that signal, it processes the data and toggles put_it
// when done, to unblock the producer
module consumer (
    input  byte shared,
    output bit  put_it,
    input  bit  get_it
);
   initial
      forever begin
         @(get_it);
         $display("Received: %0d", shared);
         put_it = ~put_it;
      end
endmodule : consumer
```

- That **is** communication between threads. The only thing missing is doing it
  between objects, which have no ports

Note:
The slide exists to defuse the fright before the word TLM shows up. It is worth
pointing at the code and saying it that bluntly: here are two processes running
at the same time and passing data to each other over a wire, and nobody called
that "inter-thread communication" in twenty years of Verilog. It is the same
thing.
The only thing that changes in the rest of the section is **where each process
lives**: instead of two `always` in two modules, two `run_phase()` in two
objects. And since an object has no port list, the wire has to be replaced by
something.
The question to leave hanging, which is exactly the one on the next slide: what
does the wire get replaced with? The answers that are going to come out —a shared
variable, a semaphore, a mailbox— are all correct, and that is precisely the
problem UVM comes to solve.

---

## When somebody has to wait

#### *An object has no port list*

- What SystemVerilog does have is shared handles, semaphores and mailboxes
- That is enough to solve it, and that is the problem: **everybody solves it
  differently**, and afterwards nobody can read the testbench of the person next
  to them
- UVM standardizes a single way, in two pieces:
  - *Ports*: they get instantiated in a `uvm_component` so that its `run_phase()`
    can talk to another thread. *Put port* to send, *get port* to receive
  - *TLM FIFO*: the object that joins a put port to a get port. `new()` creates it
    with **size 1** by default —`new(name, parent, size = 1)`—, and with `0` it
    would be unbounded. The one in the example uses the default
- With size 1 the FIFO is not a buffer, it is a **meeting point**: the one putting
  waits for the other one to take out

Note:
What has to be taken away from the slide is that size 1 is not a limitation of
the class: it is the default argument of the constructor. With
`new("f", this, 0)` the FIFO is unbounded, and there the one putting never
blocks.
Size 1 is the one that synchronizes: it blocks the producer until the consumer
takes out, and that replaces the semaphore and the flag everybody used to write
by hand. It is the same `start`/`done` handshake of the BFM, but between objects.

---

## When somebody has to wait

#### *The producer as an object*

- The producer declares a `uvm_put_port` and calls `put()`. That is all: no signal
  handshake, no shared flag, no semaphore

```sv
// UVM solution to interthread communication
//	It has 2 parts:
//		*	Ports-Objects: instantiated in our uvm_components so that
//				run_phase can talk to other threads
//		*	TLM Fifos (they hold only 1 element)

class producer extends uvm_component;
   `uvm_component_utils(producer);

int shared;
   // uvm_put_port is a parameterized class
   // this class takes care of the whole synchronization mess around
   // get_it and put_it
   uvm_put_port #(int) put_port_h;

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

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

task run_phase(uvm_phase phase);
      phase.raise_objection(this);
      repeat (3) begin
         put_port_h.put(++shared);
         `uvm_info("PRODUCER", $sformatf("Sent %0d", shared), UVM_MEDIUM)
      end
      phase.drop_objection(this);
   endtask : run_phase
endclass : producer
```

Note:
What has to be pointed out is what is **not** in this class: there is no
`@(posedge something)`, there is no `wait`, there is no variable saying "ready".
The producer puts and carries on; if the other one has not taken it out yet, the
`put()` stops it on its own.
The detail of form, which is the one that gets copied wrong: the port gets
**instantiated** in the `build_phase` like any other component, with
`new("name", this)`. It is not a data field: it takes a parent, and that is why it
shows up in `print_topology()`. But it is not a `uvm_component` either —
`uvm_put_port` extends `uvm_port_base #(IF)`, and what hangs off the tree is an
internal `uvm_port_component` the port builds for itself
(`uvm_port_base.svh:137`). The FIFO on the next slide really is a component.
And the parameter: `uvm_put_port #(T)`. That `T` has to be the same in the port,
in the get port and in the FIFO. If they do not match it does not compile, which
is the good news —it is one of the few UVM connection errors you see at compile
time and not at three in the morning—.

---

## When somebody has to wait

#### *The consumer as an object*

- On the other side, `uvm_get_port` and a `get()`. With the FIFO empty, `get()`
  **blocks** and the thread stays there
- When the producer puts a piece of data in, the `get()` unblocks and carries on
  with the data already read. Nobody wrote the synchronization: the FIFO gives it

```sv
class consumer extends uvm_component;
   `uvm_component_utils(consumer);

// uvm_get_port handles all the interthread coordination
   uvm_get_port #(int) get_port_h;
   int shared;

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

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

task run_phase(uvm_phase phase);
      forever begin
         get_port_h.get(shared);
         `uvm_info("CONSUMER", $sformatf("Received: %0d", shared), UVM_MEDIUM)
      end
   endtask : run_phase
endclass : consumer
```

Note:
`get()` is a **task**, and that word is the whole section. A `function` cannot
have an `@` or a `#`, so it cannot wait for anybody; a `task` can. If somebody
wonders why the analysis ports of the previous section did not block, the answer
is right there: `write()` is a `function`.
The argument by reference is also worth naming: `get(t)` does not return the
data, it **writes** it into the variable you hand it. It is the TLM convention
and it surprises you the first time, because you expect a `t = get()`.
And the practical warning: a `get()` on a FIFO that never fills up is a thread
hung forever. There is no error and no warning — the simulation ends when the
objection drops and that consumer simply never ran. It is a sibling of the
forgotten `item_done()` of day 6.

---

## When somebody has to wait

#### *Instantiating the three: two components and a FIFO*

- The `uvm_tlm_fifo` takes **the same parameter** as the two ports: if they do not
  match, it does not compile
- The three get instantiated in the `build_phase` of the test, like any component.
  The FIFO is a `uvm_component` too
- And the order is the usual one: UVM calls every `build_phase` from the top down,
  and only once it has finished does it start the `connect_phase` from the bottom
  up

```sv
class communication_test extends uvm_test;
   `uvm_component_utils(communication_test)

producer producer_h;
   consumer consumer_h;
   uvm_tlm_fifo #(int) fifo_h;

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

function void build_phase(uvm_phase phase);
      producer_h = new("producer_h", this);
      consumer_h = new("consumer_h", this);
      fifo_h = new("fifo_h", this);
   endfunction : build_phase

// Connect phase: the two ports and the fifo already exist -- build_phase
   // runs first, top-down -- so this is where they get wired together.
   function void connect_phase(uvm_phase phase);
      producer_h.put_port_h.connect(fifo_h.put_export);
      consumer_h.get_port_h.connect(fifo_h.get_export);
   endfunction : connect_phase

endclass : communication_test
```

Note:
It is worth saying again why the order is that one, because here you see what it
is for: the `connect_phase` connects a port to an export, and for that both
objects have to exist. If `connect` were top-down, the test would try to connect
children that had not been built yet.
The classic error of this slide, which compiles and fails at run time: creating
the FIFO in the `connect_phase` instead of the `build_phase`. UVM catches it with
an `ILLCRT` fatal —*"It is illegal to create a component ('x' under 'y') after the
build phase has ended"* (`uvm_component.svh:1721`)—, and at least it warns you with
the name. Forgetting the `connect()` of a `put`/`get` port **also** warns, and
well: `resolve_bindings()` reports a `UVM_ERROR [Connection Error] connection count
of 0 does not meet required minimum of 1` with the name of the port, in
`end_of_elaboration` and before a single cycle runs (`uvm_port_base.svh:886`).
The one that stays quiet is the **analysis port**, because its minimum is 0: a
`write()` into an unconnected port is legal and prints nothing. It is the same
asymmetry as the previous section, and it is the one to remember.
And one worth pointing out in passing: here the producer and the consumer are
children of the **test**, not of an env. It is on purpose, because the section is
about the mechanism. In the real testbench this goes inside the agent, with the
sequencer on one side and the driver on the other.

---

## When somebody has to wait

#### *Connecting them: `put_export` and `get_export`*

- It is the same `connect()` as the analysis ports: on one side the **port**, on
  the other the **export** the FIFO provides
- `uvm_tlm_fifo` exposes twelve handles; the two that get used are `put_export` for
  the one that puts and `get_export` for the one that takes out —which is an alias of
  `get_peek_export`, and that is the name you are going to see in `print_topology()`—
- The rule that holds for all of TLM: **the port connects to the export**, never
  two ports to each other

```sv
   // Connect phase: the two ports and the fifo already exist -- build_phase
   // runs first, top-down -- so this is where they get wired together.
   function void connect_phase(uvm_phase phase);
      producer_h.put_port_h.connect(fifo_h.put_export);
      consumer_h.get_port_h.connect(fifo_h.get_export);
   endfunction : connect_phase
```

```plaintext
UVM_INFO @ 0: reporter [RNTST] Running test communication_test...
UVM_INFO producer.svh(28) @ 0: uvm_test_top.producer_h [PRODUCER] Sent 1
UVM_INFO consumer.svh(19) @ 0: uvm_test_top.consumer_h [CONSUMER] Received: 1
UVM_INFO producer.svh(28) @ 0: uvm_test_top.producer_h [PRODUCER] Sent 2
UVM_INFO consumer.svh(19) @ 0: uvm_test_top.consumer_h [CONSUMER] Received: 2
UVM_INFO producer.svh(28) @ 0: uvm_test_top.producer_h [PRODUCER] Sent 3
UVM_INFO consumer.svh(19) @ 0: uvm_test_top.consumer_h [CONSUMER] Received: 3
UVM_INFO $UVM_HOME/src/base/uvm_report_server.svh(1009) @ 0: reporter [UVM/REPORT/SERVER] 
--- UVM Report Summary ---
** Report counts by severity
UVM_INFO :    7
UVM_WARNING :    0
UVM_ERROR :    0
UVM_FATAL :    0
** Report counts by id
[CONSUMER]     3
[PRODUCER]     3
[RNTST]     1
- $UVM_HOME/src/base/uvm_root.svh:633: Verilog $finish
- S i m u l a t i o n   R e p o r t: Verilator 5.052 2026-09-05
- Verilator: $finish at 0s
```

Note:
Two things about the output, which do not belong to this section but are seen
here first.
The messages come out with `` `uvm_info ``, not with `$display`: that is why
every line brings the time, the hierarchical path of the component and the file
along on its own. That is free, and it is reporting, which they already saw
closing day 3.
And the other one: every `@` says 0. In this example there is not a single
`#delay` —the blocking handshake suspends and resumes within the same instant—,
so the synchronization of the two threads does not come from the clock: it comes
from the one-element FIFO. In the example that follows the clocks show up and the
numbers stop being 0.

---

## When somebody has to wait

#### *NON-blocking communication*

- Blocking is fine as long as the one waiting has nothing better to do. With a
  clock in the middle, standing there waiting means losing an edge
- That is what the non-blocking versions are for: `try_put()` and `try_get()`
- They return 1 if they could and **0 if they could not**, and carry on. That is
  why they are `function` and not `task`: they consume no time

```sv
class consumer extends uvm_component;
   `uvm_component_utils(consumer);

uvm_get_port #(int) get_port_h;
   virtual clk_bfm clk_bfm_i;
   int shared;

function void build_phase(uvm_phase phase);
      get_port_h = new("get_port_h", this);
      clk_bfm_i = example_pkg::clk_bfm_i;
   endfunction : build_phase

// Consumer and producer run on different clocks
   // The consumer has its first positive edge at 7ns
   //    and then checks the data every 14ns, because it uses bfm.clk (= 14ns)
   // The producer produces one datum every 17ns
   task run_phase(uvm_phase phase);
      forever begin
         @(posedge clk_bfm_i.clk);
         if (get_port_h.try_get(shared))
            `uvm_info("CONSUMER", $sformatf("Received: %0d", shared), UVM_MEDIUM)
      end
   endtask : run_phase

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

endclass : consumer
```

```plaintext
UVM_INFO @ 0: reporter [RNTST] Running test communication_test...
UVM_INFO producer.svh(18) @ 17: uvm_test_top.producer_h [PRODUCER] Sent 1
UVM_INFO consumer.svh(21) @ 21: uvm_test_top.consumer_h [CONSUMER] Received: 1
UVM_INFO producer.svh(18) @ 34: uvm_test_top.producer_h [PRODUCER] Sent 2
UVM_INFO consumer.svh(21) @ 35: uvm_test_top.consumer_h [CONSUMER] Received: 2
UVM_INFO producer.svh(18) @ 51: uvm_test_top.producer_h [PRODUCER] Sent 3
UVM_INFO consumer.svh(21) @ 63: uvm_test_top.consumer_h [CONSUMER] Received: 3
UVM_INFO $UVM_HOME/src/base/uvm_report_server.svh(1009) @ 68: reporter [UVM/REPORT/SERVER] 
--- UVM Report Summary ---
** Report counts by severity
UVM_INFO :    7
UVM_WARNING :    0
UVM_ERROR :    0
UVM_FATAL :    0
** Report counts by id
[CONSUMER]     3
[PRODUCER]     3
[RNTST]     1
- $UVM_HOME/src/base/uvm_root.svh:633: Verilog $finish
- S i m u l a t i o n   R e p o r t: Verilator 5.052 2026-09-05
- Verilator: $finish at 68ns
```

Note:
try_get() returns 0 and carries on: it does not wait. It is the difference
between a consumer that hangs until there is data and one that can do something
else in the meantime. Careful, in `results.txt` the zeros are not visible —the
consumer only prints when it gets data—: they are in the timeline of the slide
that follows.
The time on each line is not printed by the message: UVM puts it in the `@`, and
that is why here you can read the race between the two clocks without having
written a single line of formatting.

---

## When somebody has to wait

#### *NON-blocking communication: the timeline*

![Timeline of the non-blocking example: at 7 ns and 49 ns the FIFO is empty and try_get() returns 0](../res/diagrams/en/threads_nonblocking.svg)

- The producer puts a piece of data in every 17 ns and the consumer looks every
  14 ns: the clocks run differently, and on two edges the FIFO is empty
- There `try_get()` returns 0 and the consumer carries on. With `get()` it stayed
  waiting

Note:
The numbers are not from a drawing: they are the `@` of the `Sent` and `Received`
of `results.txt`, the previous slide.
The edge to make them see is the one at 49 ns. Data 3 only gets put in at 51, so
the consumer arrives a little early, leaves empty-handed and comes back 14 ns
later. With `get()` that thread was left blocked right there, and in a testbench
with a clock that is a lost edge.

---

## When somebody has to wait

#### *How TLM diagrams are read*

![Interthread communication with put port, get port and uvm_tlm_fifo](../res/diagrams/en/threads_fig124.svg)

- The convention holds for all the UVM material you are going to read afterwards:
  - *Square:* put port / get port — the one that **starts** the call
  - *Circle:* export — the one that **receives** it and implements it
  - *Diamond:* analysis port — the one from the two previous sections

Note:
It is worth the student taking the convention home, because it is the same one in
the *UVM User Guide*, in the Verification Academy and in any testbench diagram
they get handed at work. It does not belong to this course.
The rule that orders the three figures, and the one that makes a TLM diagram
readable without a legend: **the square end always points at the circle**. The
one with the square is the one that calls; the one with the circle is the one
that has the method written. That is why a port connects to an export and never
to another port.
The diamond is the special case they have already seen: an analysis port can
point at many circles at once, and that is why it is drawn differently. The other
two are one to one.

---

## When somebody has to wait

#### *`fork`: the three ways of starting in parallel*

```systemverilog
fork  wait_done();  count_cycles();  join        // goes on when BOTH have finished
fork  wait_done();  count_cycles();  join_any    // goes on with THE FIRST; the other stays alive
fork  wait_done();  count_cycles();  join_none   // goes on NOW; both stay running
```

| Variant | The parent goes on… | What it is used for |
| --- | --- | --- |
| `join` | when **all** of them finish | two checks that both have to close |
| `join_any` | when **the first** one finishes | response against a timeout |
| `join_none` | **right away** | launching threads that live for the whole test |

- The difference between the three is not how they start —all three start everything at
  once— but **when the one that started them goes on**
- You have used `join_none` already: it is the `fork` of the day 2 `testbench` class, and it is
  what UVM does on its own with one `run_phase()` per component
- The branch left alive after a `join_any` **does not die on its own**. It goes on
  until it finishes — or until somebody kills it, which is the next slide

Note:
It is the unit called *threads* and up to here the threads were put there by UVM. This
slide and the next two are the three words of the language any production monitor
or driver is written with, and the three fit in one table.
The point worth repeating, because it is where everybody gets confused the
first time: **all three start the same**. The `fork` processes are all launched
at the same instant in the three variants. The only thing that changes is what the
parent process does immediately afterwards, and that is why the middle column is the one
to read.
One example per variant is enough to make it stick. `join`: send the stimulus and
count the cycles, and do not go on until both have finished. `join_any`: wait for the
DUT's response **or** for a timeout to expire, whichever happens first. `join_none`:
the monitor's `run_phase`, which starts and stays watching forever while
the rest of the testbench goes on.
And the hook back to day 2, worth making explicit: the hand-written `testbench`
class used `fork ... join_none` to start the three objects. It was not
a coincidence nor a trick — it is exactly what UVM does when it runs the
`run_phase` of a hundred components at once.

---

## When somebody has to wait

#### *`disable fork` and `wait fork`: turning off what stayed on*

```systemverilog
// The response-against-timeout idiom. The outer fork ISOLATES
fork begin
   fork
      begin  wait_done();          `uvm_info("BFM", "it arrived", UVM_LOW)  end
      begin  repeat (100) @(posedge clk);  `uvm_error("BFM", "timeout")        end
   join_any
   disable fork;      // kills the sister that lost, and nobody else
end join

wait fork;            // kills nobody: it waits for ALL the children of this thread
```

- `disable fork` kills **every child process of the thread that executes it**. That
  is why the outer `fork begin ... end join`: without it, it also takes down
  whatever was already running
- `wait fork` is the opposite: it kills nothing, it **waits** for the children to finish.
  It is what a test uses so as not to close with transactions in flight
- The `join_any` + `disable fork` pair is the timeout of every production BFM. It gets
  written once and copied forever
- Whichever finishes first wins: if `done` arrives before the 100 edges, the
  timeout `uvm_error` is not printed; if it does not, the `uvm_info` of `"it arrived"`
  is not printed. The `disable fork` kills the loser

Note:
The `disable fork` without the isolating `fork ... join` is the classic bug of this
construct and is worth drawing: it kills **every** child of the current thread, not
those of the `fork` next door. If the `run_phase` had already launched a monitor with
`join_none` and then does a bare `disable fork`, the monitor dies and the
testbench goes on running blind. There is no error, there is no warning: there is a log that
stops having lines.
The way to remember it is to think about the scope: `disable fork` does not say *which*
fork. It says "the children of this process". The outer `fork begin ... end join`
creates a new process whose only children are the two of the `join_any`, and that is why the
`disable` cannot reach any further.
`wait fork` is the quiet partner and gets used far less than it should: it is
what is needed at the end of a sequence or of a `run_phase` that launched things
with `join_none` and does not want the phase to end with half the stimulus in the
air. In UVM the same problem is solved with objections — but inside a
task, `wait fork` is the answer.

---

## When somebody has to wait

#### *⚠ The trap: the `for` index inside the `fork`*

```sv
 // A -- a single variable, shared by the three threads. A join_none runs
 // nothing: it schedules. By the time the three run, the for is over.
 for (i = 0; i < 3; i++)
 fork got = {got, $sformatf("%0d", i)}; join_none
 wait fork;
 check("int i outside the for, no copy", "333");

// B -- declared inside the for: one per pass, and nothing to copy.
 for (int j = 0; j < 3; j++)
 fork got = {got, $sformatf("%0d", j)}; join_none
 wait fork;
 check("int j declared in the for", "012");

// C -- the slide's one: the automatic as the first line of a begin/end.
 // Here the copy is NOT made when the fork is scheduled, so k reads the same
 // i that A does and gives the same answer as A. This is the finding.
 for (i = 0; i < 3; i++)
 fork begin
 automatic int k = i;
 got = {got, $sformatf("%0d", k)};
 end join_none
 wait fork;
 check("fork begin automatic k = i; end (the slide's)", "333");

// D -- the LRM 9.3.2 one: the automatic declared in the fork, no begin/end.
 // Same workaround, written where the LRM puts it, and this one does copy.
 for (i = 0; i < 3; i++)
 fork
 automatic int k = i;
 got = {got, $sformatf("%0d", k)};
 join_none
 wait fork;
 check("fork automatic k = i; no begin/end (LRM 9.3.2)", "012");
```

- A `join_none` **does not execute anything yet**: it leaves the thread ready and goes on. By
  the time the thread runs, the `for` has already finished and the variable holds the last value
- If the variable is declared **inside** the `for`, each pass has its own and there
  is no problem. It is what the LRM says and what Verilator does
- If it comes from outside —an `int` of the `run_phase`, a field of the class— it has to be
  **copied** with an `automatic`, and **where** the copy is written changes the
  result: inside a `fork begin ... end` it **does not copy**; declared in the
  `fork` itself, with no `begin`/`end` —which is the LRM 1800-2017 §9.3.2 form— it does
- Measured on Verilator 5.052, and the file ends in `$fatal` the day any of it changes
  (`make repros`): the four variants print `3 3 3`, `0 1 2`, **`3 3 3`** and
  `0 1 2`

Note:
It is the most expensive threads bug and the hardest to see when reading the code,
because the three versions look very much alike. It is worth asking the question before
showing the answer: *"what does the first one print?"*. Almost everybody says
`0 1 2`.
The explanation to leave behind is a single sentence: **`join_none` does not run the
thread, it schedules it**. The `for` walks straight to the end, and only then does the
scheduler give the three threads their turn — and they read the variable *now*, not
when they were launched. With `i` outside there is a single variable, and now it holds 3.
The version with `for (int j …)` works and it is worth saying why, so it does not
look like magic: the LRM declares automatic the variable of a `for` that declares it,
so each pass has its own copy. It is measured here, it is not theory.
The case where the `automatic` is needed anyway is the one that shows up in real life:
the index is not the `for`'s, it is a field of the class or an argument of the task.
There is no copy per pass there and it has to be made by hand — and here is the part
this slide used to get wrong: **the `automatic` as the first line of a
`fork begin ... end` does not copy**. On Verilator 5.052 variant C prints `3 3 3`,
just like A. The one that copies is D, the LRM §9.3.2 one: the declaration inside the
`fork`, with no `begin`/`end`. The two look so alike that it is easy to write the one
that does not work.
The practical rule to take home: **if a thread launched with `join_none` reads a
variable from outside, declare the copy in the `fork`, not inside a `begin`.**

---

## When somebody has to wait

#### *Summary of the unit*

- **Inter**-thread communication between objects is the equivalent of what ports
  do between modules: passing data from one thread to another
- UVM provides it with *uvm_put_port*, *uvm_get_port* and *uvm_tlm_fifo*
- Any object that wants to communicate with another thread has to instantiate a
  port and connect it to a FIFO
- Careful with the pair of names: the *analysis ports* of the two previous sections
  are **intra**-thread —`write()` is a `function` and runs in the thread of the
  one publishing—; this is **inter**-thread, and that is why `put()` and `get()`
  are `task`
- And underneath it all there is `fork`: `join` waits for all, `join_any` for the first,
  `join_none` for none. `disable fork` kills the children and `wait fork` waits for them
- Now we have to use this to wire our TB: we are going to separate the stimulus
  generation from the driver of the DUT

Note:
Worth closing with the two-column table that one producer, many listeners opened
with, because it is the one that orders the four units of the day:
Intra-thread — `uvm_analysis_port` + `uvm_subscriber`, `write()` is a `function`,
it consumes no time, a single thread, and it is for the *analysis layer*.
Inter-thread — `uvm_put_port` / `uvm_get_port` + `uvm_tlm_fifo`, `put()` and
`get()` are `task`, they block, two threads, and they are for handing stimulus to
a driver.
The short way of telling them apart, and it is question 3 of the review: **if it
is a `function`, it is intra-thread.** A function cannot have an `@` or a `#`, so
it cannot wait for anybody. The word `task` is the one that gives away that there
are two threads.

## Who waits for whom

#### *What to send and how to send it*

- The analysis ports split the analysis: the monitor watches, the subscribers
  interpret. The same is still missing on the stimulus side
- Today the `base_tester` does **two** things: it picks the operation *and* it
  applies it on the BFM cycle by cycle. They are two jobs that change for
  different reasons
- The **what** changes with every test. The **how** changes only if the protocol
  of the DUT changes — which means, almost never
- Separating them leaves the protocol written in a single place: the **driver**.
  Every new test writes what to send and never looks at an `@(negedge clk)` again
- And since the two run in different threads, the joint is the one from
  inter-thread communication: `uvm_put_port`, `uvm_get_port` and a
  `uvm_tlm_fifo` in the middle

Note:
It is the third time the course does the same operation, and it is worth saying
it that explicitly because it is what has to be taken home: in interfaces and BFM
we took the protocol out of the test and put it in the BFM; in the analysis ports
we took the observing out of the analysers and put it in the monitor; here we
take the applying of the stimulus out of the generator and put it in the driver.
The question that orders everything: does this change when the test changes, or
when the design changes? If it changes with the test, it is stimulus. If it
changes with the design, it is structure. They do not go in the same class.
And the notice of where this is heading: in the agents this put/get pair is
called a sequencer and comes already in place, and the tester is called a
sequence. What we are assembling by hand here is exactly what UVM gives you
ready-made — that is why it gets assembled by hand first.

---

## Who waits for whom

#### *The tester does two jobs, and one of them is not its own*

- This is how the `base_tester` of the analysis ports was left, and it does
  **two** jobs:
  - it picks which operation to send
  - and it applies it on the BFM, cycle by cycle
- The second one is the one that should not be there: it is protocol, and the
  protocol does not change when the test changes
- The class that takes that job away is called a **driver**: it takes a piece of
  data from the testbench and turns it into signals

```sv
   task run_phase(uvm_phase phase);
      byte unsigned iA;
      byte unsigned iB;
      operation_t   op_set;

phase.raise_objection(this);
      bfm.reset_alu();
      repeat (1000) begin : random_loop
         op_set = get_op();
         iA = get_data();
         iB = get_data();
         bfm.send_op(iA, iB, op_set);
      end : random_loop
      #500;
      phase.drop_objection(this);
   endtask : run_phase
```

Note:
It is worth reading the code pointing a finger at where one job ends and the
other starts: `get_op()` and `get_data()` are the **what**; everything that
follows —the `bfm.send_op()`, the wait, the cycle— is the **how**. They are glued
together in the same task and that is why they cannot be changed separately.
The proof that they are wrongly together is a question: if tomorrow the DUT adds
a signal to the protocol, how many classes have to be touched? Every one that
inherits from `base_tester`, even though none of them knows anything about
protocol. That is coupling, and the classic symptom is exactly this one — a class
that changes for two different reasons.
The name **driver** is worth saying already, even though the class does not exist
yet, so that the word does not show up for the first time on day 6. A driver is
what turns a piece of data into signals. Nothing more than that, and that is why
it is the only class of the testbench that has the right to write an
`@(negedge clk)`.

---

## Who waits for whom

#### *How it ends up split*

- The result: one class decides **what** to send and another one knows **how** to
  send it, and between the two there is a FIFO instead of a method call

![The VTALU tester and driver separated by a uvm_tlm_fifo](../res/diagrams/en/put-get_fig125.svg)

Note:
The box in the middle is the one to point at, because it is the one that
surprises: between the tester and the driver **there is no arrow**. There is a
FIFO. The tester does not call the driver, and it does not even have a handle to
it.
It is worth making the comparison with the diagram of the analysis ports, which
is two sections back: over there the monitor did not know its listeners either.
It is the same idea applied on the other side of the testbench, and it is the
reason why on day 6 every sequence can be changed without touching the driver.
And the difference between the two diagrams that does matter, because it is
question 3 of the review: that one was **intra**-thread —`write()` is a function
and does not wait for anybody—, this one is **inter**-thread. Here the one
putting can be left waiting, and that is precisely the synchronization that used
to have to be written by hand.

---

## Who waits for whom

#### *The `env`: seven objects and five `connect()`*

- Mantra: "Ports connect to exports"

```sv
   function void build_phase(uvm_phase phase);
      command_f = new("command_f", this);
      random_tester_h = random_tester::type_id::create("random_tester_h", this);
      driver_h = driver::type_id::create("driver_h", this);

coverage_h = coverage::type_id::create("coverage_h", this);
      scoreboard_h = scoreboard::type_id::create("scoreboard_h", this);
      command_monitor_h = command_monitor::type_id::create("command_monitor_h", this);
      result_monitor_h = result_monitor::type_id::create("result_monitor_h", this);
   endfunction : build_phase

function void connect_phase(uvm_phase phase);
      // PORTS CONNECT TO EXPORTS!
      driver_h.command_port.connect(command_f.get_export);
      random_tester_h.command_port.connect(command_f.put_export);

result_monitor_h.ap.connect(scoreboard_h.analysis_export);

command_monitor_h.ap.connect(scoreboard_h.cmd_f.analysis_export);
      command_monitor_h.ap.connect(coverage_h.analysis_export);
   endfunction : connect_phase
```

Note:
Count the objects of this `build_phase`: there are **seven**, plus five
`connect()`. That number is the one to remember, because in the agents this same
testbench is going to have one agent and two subscribers. Worth writing it on the
board so you can come back to it.
The two new lines of the `connect_phase` are a pair and get read together: the
tester puts into the `put_export` of the FIFO, the driver takes out of the
`get_export`. Nobody connects the tester to the driver — **they do not know each
other**, and that is the point.
The mantra has a reason worth giving instead of repeating it like a parrot: the
*port* is the one that asks for the service, the *export* is the one that offers
it. The FIFO offers both ends, so it has two exports. If you write it the other
way round it does not compile, and the compiler message is one of the worst in
UVM.
And the detail that gets forgotten: `command_f = new(...)`, not `create()`. It is
not that the FIFO is missing from the factory —it is registered,
`tlm1/uvm_tlm_fifos.svh:62`—: it is that the `size` goes through the constructor and
`create()` does not know how to pass it. The ones that really are not in the factory
are the ports and the exports.

---

## Who waits for whom

#### *The `base_tester`, without a single signal*

- Only one thing changes: where there was a handle to the BFM there is now a
  `uvm_put_port #(command_s)` called `command_port`
- `random_tester` and `add_tester` **do not get touched**. They only define
  `get_op()` and `get_data()`, and neither of the two knew how the stimulus was
  applied
- That is the return on having separated things properly in the env: the change
  stopped at the base class

```sv
virtual class base_tester extends uvm_component;

`uvm_component_utils(base_tester)

// the handle to the BFM is replaced by a uvm_put_port
   uvm_put_port #(command_s) command_port;

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

pure virtual function operation_t get_op();

pure virtual function byte get_data();

task run_phase(uvm_phase phase);
      byte unsigned iA;
      byte unsigned iB;
      operation_t   op_set;
      command_s     command;

phase.raise_objection(this);
      command.op = rst_op;
      command_port.put(command);
      repeat (1000) begin : random_loop
         command.op = get_op();
         command.A = get_data();
         command.B = get_data();
         command_port.put(command);
      end : random_loop
      #500;
      phase.drop_objection(this);
   endtask : run_phase
```

Note:
What matters about this class is what **disappeared**: there is not a single
`@(negedge clk)`, nor a `bfm.start`, nor the wait for the `done`. The tester was
reduced to picking what to send and putting it on the port.
And yet `random_tester` and `add_tester` **were not touched**: they only define
`get_op()` and `get_data()`, and neither of the two knew how the stimulus was
applied. That is what separating properly buys you — the change stopped at the
base class.
The `put()` is a `task` and it blocks: if the driver is still handling the
previous operation, the tester waits there. The one-element FIFO of inter-thread
communication is what synchronizes the two threads, without a single semaphore.
And there is a `#500` at the end, before the `drop_objection`, worth pointing out
as what it is: a patch. It is there so that the objection does not drop while the
last operation is still travelling. In the sequences it disappears, because
`finish_item()` only comes back when the operation has really finished. An
eyeballed `#500` in a testbench is always an unanswered question.

---

## Who waits for whom

#### *The driver: the only one that touches the wire*

- A `forever` with two lines: `get()` a command —which blocks until there is one—
  and apply it with `send_op()`. The whole protocol lives here

```sv
class driver extends uvm_component;
   `uvm_component_utils(driver)

virtual vtalu_bfm bfm;

uvm_get_port #(command_s) command_port;

function void build_phase(uvm_phase phase);
      if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "bfm", bfm))
         `uvm_fatal("DRIVER", "Failed to get BFM")
      command_port = new("command_port", this);
   endfunction : build_phase

task run_phase(uvm_phase phase);
      command_s command;

forever begin : command_loop
         // Blocking: if there are no commands to send, it waits
         command_port.get(command);
         bfm.send_op(command.A, command.B, command.op);
      end : command_loop
   endtask : run_phase
```

Note:
This division is the one UVM formalizes in the agents: the tester decides WHAT to
send, the driver knows HOW to send it.
In a real agent the tester is going to be called a sequence and this put/get is
going to be called get_next_item / item_done. Anticipating it here makes day 6
start downhill.

---

## Who waits for whom

#### *Summary of the unit*

- The testbench ended up split into three layers that change for different
  reasons: the **stimulus** (tester), the **protocol** (driver and monitors) and
  the **analysis** (scoreboard and coverage)
- None of them knows the insides of the others: between them only commands and
  results travel
- What is still missing is for the testbench to know how to **tell what is going
  on**, which is the unit that follows

Note:
It is worth closing the day with the three layers written on the board, because
it is the map that orders everything that comes: stimulus, protocol, analysis.
The four sections of today were about building that separation, and tomorrow's do
not add layers — they put UVM names on the ones already there.
The control question, which besides answers itself if the day closed properly: in
which of the three layers does an `@(negedge clk)` live? In one only, the
protocol. If it shows up in another one, something got separated wrong.
And the notice about what is missing, worth giving now: between the tester and
the driver travel `command_s`, which are structs. They work, but they do not
randomize themselves, they do not compare themselves and they do not print
themselves — and that is exactly what day 5 is going to fix by turning them into
transactions.

## Review · Day 4

#### *1 of 5 · Observer Pattern*

**In the Observer pattern, what does the observed object know about its observers?**

- [ ] How many there are and of what type
- [ ] Only the first one that subscribed
- [ ] It knows them because they get handed to it in the constructor, one by one
- [x] Nothing: not how many there are, not who they are

> **It knows nothing** — and that ignorance is the whole point. Adding a fourth subscriber does not force you to touch one line of the one publishing.

---

## Review · Day 4

#### *2 of 5 · Analysis Ports*

**A `uvm_subscriber` needs data from two different analysis ports. How does that get solved?**

- [ ] By implementing the `write()` method twice
- [x] With a `uvm_tlm_analysis_fifo` for the second port
- [ ] By registering the component twice in the factory, once per port
- [ ] By connecting both ports to the same `analysis_export`

> **With a `uvm_tlm_analysis_fifo`** — a `uvm_subscriber` has a single `write()`, so it can only listen to one port. The FIFO gives an `analysis_export` on one side and a `try_get()` on the other. It is what the VTALU scoreboard does. The other way is `` `uvm_analysis_imp_decl ``, which manufactures one `write_` per suffix: they are not two `write()` in the same class, which SystemVerilog does not allow.

---

## Review · Day 4

#### *3 of 5 · Intra vs. inter thread*

**When the monitor publishes and the `write()`s of the subscribers run, how many threads are involved?**

- [ ] One per subscriber
- [ ] Two: the publisher's and the subscriber's
- [x] Only one: `write()` is a function call
- [ ] One per subscriber plus the monitor's, and UVM syncs them at the end of the delta

> **Only one, and it is intra-thread communication** — `write()` is a `function`, not a `task`: it consumes no time and runs in the thread of the one publishing. That is precisely why **another** mechanism (put/get + FIFO) is needed to talk between threads.

---

## Review · Day 4

#### *4 of 5 · Put and get ports*

**The consumer calls `get()` and the `uvm_tlm_fifo` is empty. What happens?**

- [x] It blocks until the producer puts a piece of data in
- [ ] It returns 0 and carries on
- [ ] A UVM fatal error
- [ ] It returns the last piece of data read, which stays in the FIFO until overwritten

> **It blocks** — `get()` is blocking, and that is why it is declared `task` and not `function`. That is the whole synchronization: no hand-written signal handshake is needed.

---

## Review · Day 4

#### *5 of 5 · try_get()*

**And `try_get()` with the FIFO empty?**

- [ ] It blocks just like `get()`
- [ ] It returns 1 with a garbage value
- [ ] It waits one clock cycle and tries again, up to the timeout of the phase
- [x] It returns 0 immediately, without blocking

> **It returns 0 and carries on** — it is the non-blocking version, and that is why it can be a `function`. Notice that the scoreboard uses it in a `do ... while` to skip over the `no_op`s and the `rst_op`s.

## Exercise · Day 4 · 2 of 2

#### *The `#500` is a patch*

`cd code/ejercicios/d4b && bash run.sh`

- The *put and get* testbench with **one line changed**: the `env`'s FIFO comes
  unbounded
- The tester empties its thousand commands at `t = 0`, waits the usual `#500`,
  drops the objection — and the simulation ends **in green with 13 commands on
  the bus**
- It gets fixed in the driver: an objection **while there is a command in flight**
- `env.svh` does not get touched: the unbounded FIFO is the DUT of this exercise

Note:
It is the exercise that puts hands on the two things the section claims and does
not demonstrate: that `put()` blocks, and that the tester's `#500` is a patch.
The number is measured and is worth saying: with the size-1 FIFO the testbench
sends the thousand operations; with the unbounded FIFO, **13**. Nobody touched
the DUT, nobody touched the stimulus, and the difference is a constructor's
default argument.
What the back-pressure was doing without anybody having designed it that way:
keeping the tester in step with the bus. Take it away and the tester is left
talking to itself.
The fix has to be discussed, because the obvious answer —raise the `#500`— is the
one to reject. The question that orders it: **who knows when the bus is done?**
Not the tester, which knows when it is done *putting*. It is the driver, which is
the one driving. That is why the objection goes there, and that is why it is the
pattern of any real UVM driver.
And the detail that decides whether the exercise works, which is also from the
field: the `raise`/`drop` pair goes **after** the `get()`, not around it. Around
it, the driver holds an objection waiting for work that is never coming, and the
test never ends — which is the other failure mode of the debug appendix table.

## Yesterday we left…

#### *Where the testbench stands*

- The monitor **publishes** and knows nobody: the scoreboard and the coverage
  hang off it, and adding a third does not touch the one that publishes
- The TLM FIFOs settled who waits for whom, and `fork`/`join` who runs with whom
- But the data is still **three loose fields**: `A`, `B` and `op` travel
  separately, they get copied by hand, and comparing them means writing the whole
  comparison

Note:
The day 5 recap has to install the discomfort of the loose data, because that is
what justifies a whole unit about objects that do nothing but carry data.
The third bullet is literal: in yesterday's testbench, copying a command is three
assignments, and comparing it is three `==`. With two more fields it is five and
five. Today that becomes `copy()` and `compare()`, written once.

---

## Agenda

#### *Day 5 · ≈ 4 h 30 · unit 6 · the data*

- Copying an object that contains another
- Transactions
- Constrained random

**By the end of the day you can:**

- **Write** a constraint that reaches a corner case, and **measure** whether the
  `dist` does what it says
- **Close** a bin that was left open, with a directed case asked for through
  `randomize() with {}`
- **Explain** the difference between copying the handle and copying the object,
  and what happens when the object contains another

Note:
The second one is the novelty of the day and the one that pays off the most at
work: measuring is half of it, closing is the other half. The last two exercises
of the afternoon are two thirds of that cycle —measure the `dist`, close the
bin— and day 7 closes it by accumulating seeds.
Row 12 of the self-assessment says **measure**, not **write**, and that is on
purpose: a `dist` with the weights right can give a histogram that lies, and
whoever never measured it has no way of knowing.

## Copying an object that contains another

#### *The handle is not the object*

- From the transactions on, the testbench data stops being a `struct` and becomes
  **objects that travel**: the monitor creates them, the scoreboard compares them
- And there a problem appears that a `struct` did not have. A `struct` gets copied
  when you assign it; an object does **not**: `obj1_h = obj2_h` copies the handle,
  not the data
- Which means two parts of the testbench can be looking at the same object without
  knowing it. If one modifies it, the other sees the change halfway through
- Copying it for real has to be written, and written **at every level of the
  hierarchy**, or the fields from above get lost in silence
- This section is the OOP that is missing so that the transactions can be copied,
  compared and printed without lying

Note:
It is an OOP section in the middle of UVM, and it is worth saying why it is here
and not on day 2: because only now is it needed. Up to reporting —the closing of
day 3— the data was a `struct` and copied itself.
The bug in the second bullet gets written by everybody once, and the symptom is
horrible: you send a transaction to the scoreboard, you go on using the same
handle for the next one, you modify it, and the scoreboard compares against data
that changed after it received it. It does not fail every time, and when it does
it looks like a DUT bug.
The other half —the `super` at every level— has a different and more treacherous
symptom: the day somebody puts a new class in the middle of the hierarchy, the
`convert2string()` stops printing half the fields and **nobody finds out**,
because it goes on printing something.
The question to start with: if `handle_a = handle_b`, how many objects are there?
One. It is the same question as in classes and extensions, now with consequences.

---

## Copying an object that contains another

#### *Never duplicate code*

> "If we find ourselves copying code and making small modifications to it inside our program, we are doing things wrong. Code must never be duplicated."

In OOP, instead of copying code...

***we extend classes***

---

## Copying an object that contains another

#### *`convert2string()`: the problem*

![The four levels of the hierarchy](../res/diagrams/en/jerarquias_convert2string.svg)

- The hierarchy goes from the general to the particular, and each class adds
  fields of its own
- We want two things from it: to be able to **copy** a whole object and to
  **print** it whole, without anything from the levels above getting lost
- This first version works. Count how many times the name of a field of the base
  class shows up

```sv
// ILLUSTRATION -- not compiled. The WRONG way to write convert2string!
// The classes are drawn as comments: only the methods are on screen.
//class trago;
   virtual function string convert2string();
      return $sformatf("Hielos: %0d", hielos);
   endfunction : convert2string
//class fernet extends trago;
   function string convert2string();
      string coca_s;
      coca_s = (con_coca) ? "si" : "no";
      return $sformatf("Hielos: %0d  Coca: %s", hielos, coca_s);
   endfunction : convert2string

//class fernet_doble extends fernet;
   function string convert2string();
      return {$sformatf("hielos: %0d  coca: %0b  mesa: %s",
      	       hielos, con_coca, mesa) };
   endfunction : convert2string
```

Note:
This version works, and that is the problem: it looks fine and it is wrong. Every
`convert2string()` prints every field by hand, including the ones it inherited.
Go to the `$sformatf` of the bottom-most class and count how many times the name
of a field of the class above is repeated. Every one of those repetitions is a
line you have to remember to touch the day a field gets added.
The question that sets up the next slide: what happens if tomorrow somebody puts
a new class **in the middle** of the hierarchy? The ones below go on printing
what they knew, the one in the middle does not show up, and there is no error.
The method still returns a string.

---

## Copying an object that contains another

#### *`convert2string()`: the deep version*

![A new level in the hierarchy breaks convert2string(): graduacion does not appear in the string](../res/diagrams/en/jerarquias_convert2string_deep.svg)

- The day somebody puts a class **in the middle**, the ones below go on printing
  what they knew and the one in the middle does not show up. And there is no
  error: the method still returns a string
- The rule that fixes it: each class prints **only what is its own** and asks
  `super` for the rest
- Nobody knows what is further up, so inserting a level breaks nothing

```sv
// ILLUSTRATION -- not compiled. The same three methods written deep, with the
// classes drawn as comments. The version that does compile is deep.sv.
//virtual class trago;
   virtual function string convert2string();
      return $sformatf("Hielos: %0d", hielos);
   endfunction : convert2string

//class con_alcohol extends trago;

function string convert2string();
      return {super.convert2string(),
              $sformatf("\ngraduacion: %0d",graduacion)};
   endfunction : convert2string

//class fernet extends con_alcohol;

function string convert2string();
      string coca_s;
      coca_s = (con_coca) ? "si" : "no";
      return {super.convert2string(), "\nCoca: ",coca_s};
   endfunction : convert2string
```

Note:
The rule, short: **every method of the hierarchy takes care only of its own
fields and asks `super` for the rest.** Nobody knows what is further up, and that
is why inserting a class in the middle breaks nothing.
The pattern repeats in the same way in the three methods of the section
—`convert2string()`, `do_copy()`, `do_compare()`— and in the three of UVM too. If
you get into the habit of writing the call to `super` **first**, before touching
your own fields, you never forget it.
It is worth pointing out the parallel with something they have already seen: it
is exactly the same argument as the `super.new()` of classes and extensions. The
top part of the object has to be built too — and it also has to be printed,
copied and compared.

---

## Copying an object that contains another

#### *The equals sign copies nothing*

- `obj1_h = obj2_h` **copies nothing**: it leaves two handles pointing at the same
  object
- If you modify it through one, the other sees it. There is no notice, there is no
  warning
- With a `struct` that did not happen: it gets copied when you assign it. It is
  the difference to keep in mind from here to the end of the course

Note:
It copies the handle, not the object. It is the bug everybody writes once: you
modify the transaction you already sent to the scoreboard and the scoreboard sees
the change halfway through. This is where the clone() of the transactions comes
from.

---

## Copying an object that contains another

#### *Copying for real is two steps*

Copying for real is two steps, and they have to be written: **instantiate** a new
object and **hand it the data** field by field

```sv
// ILLUSTRATION -- not compiled. The initial block of deep.sv:110-118, on its own.
initial begin
   fernet_hielo1_h =
       new(.hielos(2), .con_coca(1), .graduacion(2), .mesa("mesa 4"), .medidas(2));
   $display("\n--- Fernet 1 ---\n", fernet_hielo1_h.convert2string());
   fernet_hielo2_h = new();
   $display("\n--- Fernet 2 before the copy ---\n", fernet_hielo2_h.convert2string());
   // do_copy is a method that copies member by member
   // it suffers from the same problem already seen with convert2string()
   // Each class can copy the variables defined in that class
   // super.do_copy() has to be used to copy the inherited ones
   fernet_hielo2_h.do_copy(fernet_hielo1_h);
   $display("\n--- Fernet 2 after the copy ---\n", fernet_hielo2_h.convert2string());
end
```

- The `new()` is the first step and it is not optional: without a new object on
  the other side, there is nowhere to copy to
- The second step is by hand, field by field. SystemVerilog has no built-in deep
  copy
- And field by field means **the fields of the classes above too**, which is
  exactly what gets forgotten

Note:
It is worth making the comparison with the assignment of the previous slide out
loud: `a = b` is one line and copies nothing; copying for real is two steps and
both have to be remembered.
That the language does not bring a deep copy is not an oversight by the
committee: there is no general answer. If the class has a handle to another
object, do you copy the handle or the object? It depends, and that is why you
have to decide it yourself in every `do_copy()`.
It is exactly the same dilemma the transactions are going to have if some day
they carry an array of objects inside. In this course it does not happen, but it
is worth leaving the question on the table.

---

## Copying an object that contains another

#### *`do_copy()`: each class touches what is its own*

*do_copy():* Every class in the hierarchy has to call its parent class, and therefore every do_copy() method needs the same type of argument. But we have different classes... We use *polymorphism*

```sv
class fernet_con_hielo extends fernet_doble;
   byte medidas;

function new(int hielos = 0, bit con_coca = 0, int graduacion = 0,
                string mesa = "", byte medidas = 0);
      super.new(hielos, graduacion, con_coca, mesa);
      this.medidas = medidas;
   endfunction : new

function string convert2string();
      return {super.convert2string(), "\n", $sformatf("medidas: %0d", medidas)};
   endfunction : convert2string

//do_copy passes the argument up to its parent class
   function void do_copy(trago copia);
      fernet_con_hielo copia_fernet_con_hielo;
      super.do_copy(copia);
      // Then the copy gets cast to a variable of its own class type
      $cast(copia_fernet_con_hielo, copia);
      this.medidas = copia_fernet_con_hielo.medidas;
   endfunction : do_copy

endclass : fernet_con_hielo
```

Note:
Here is the detail that looks bureaucratic and is not: **every** `do_copy()` of
the hierarchy takes an argument of the **base** class, not of its own. If each one
took its own type, the call to `super.do_copy(rhs)` would not compile — the types
would not match.
The price is that inside every method you have to `$cast` in order to read your
own fields. And as we saw in the factory, that `$cast` checks at run time: if
somebody tries to copy a `mojito` onto a `fernet`, it returns 0 and it has to be
caught.
It is the first time a signature convention shows up that exists only so that
polymorphism can work. In UVM it is going to be the same and with more rules: the
argument has to be a `uvm_object` —and by convention it is called `rhs`—,
`do_compare()` also takes a `uvm_comparer`, and so on. When those signatures show up in the transactions, the answer to "why like
this?" is this slide.

---

## Copying an object that contains another

#### *Summary: the terrible solution*

```sv
   function string convert2string();
      return {
         $sformatf(
             "hielos: %0d  coca: %0b  mesa: %s  medidas: %0d",
             hielos,
             con_coca,
             mesa,
             medidas
         )
      };
   endfunction : convert2string
```

- It is the `convert2string()` of `fernet_con_hielo`, the bottom-most class: it
  prints **all four fields by hand**, including the three it inherited
- It works, and that is why it is dangerous. The day `fernet` gains a field, this
  method goes on compiling and goes on printing — less than it should
- The whole file is in `code/u6/jerarquias/wrong.sv`. The three `do_copy()`s in
  there do call `super`; the one with the vice is `bad_copy()`, at the very bottom

Note:
The rule to leave behind: **a class only writes on its own fields.** Everything
else it asks `super` for.
It is worth counting on screen: `hielos` shows up in four different `convert2string()`
of this file and `con_coca` in three. Seven places to remember, and not one of them
fails if you forget one.
There is a `bad_copy()` a little further down the file worth opening if there is
time to spare: it takes a `fernet_con_hielo` as an argument instead of a `trago`.
It compiles and it works... until somebody calls it through a handle of the base
class, and there no polymorphism can help.

---

## Copying an object that contains another

#### *Summary: the deep solution*

```sv
   function string convert2string();
      string coca_s;
      coca_s = (con_coca) ? "si" : "no";
      return {super.convert2string(), "\nCoca: ", coca_s};
   endfunction : convert2string

function void do_copy(trago copia);
      fernet copia_fernet;
      super.do_copy(copia);
      $cast(copia_fernet, copia);
      this.con_coca = copia_fernet.con_coca;
   endfunction : do_copy
```

- The same two methods, written the way they should be: each one calls `super` and
  then touches **a single field**, its own
- `convert2string()` **concatenates** what the one above returned; `do_copy()`
  **calls the one above first** and then copies what is its own
- With that shape, putting a new class in the middle of the hierarchy works on its
  own: the chain of `super` includes it without anybody editing anything

Note:
Closing of the section, and it is worth saying where all of this is going: the
three methods they have just written by hand are **exactly** the three UVM asks
for in a transaction. `do_copy()`, `do_compare()` and `convert2string()`, with
the same rules about `super` and `$cast`.
The difference is that in UVM they do not get called directly: you write
`do_copy()` and the testbench calls `copy()`, which is the one that lives in
`uvm_object` and takes care of the rest. Same idea as the phases — you write the
bottom part, the library handles the protocol.
And the question to walk out of the day with: if writing this properly costs
three methods per class, why does nobody generate it? Somebody does: they are the
`` `uvm_field_* `` macros. The course does not use them, and the reason is on the
`super.build_phase()` slide of the components — they generate hundreds of lines
nobody reads and that show up in the stack when something fails. Read them yes,
write them no.

---

## Copying an object that contains another

#### *Summary of the unit*

- `obj1_h = obj2_h` **copies nothing**: it leaves two handles pointing at the same
  object. If you touch it through one, the other sees it, and there is not even a
  warning
- With a `struct` that did not happen —it gets copied when you assign it—, and
  that is the difference to keep in mind until the end of the course
- **Copying for real is two steps**: instantiate a new object and hand it the
  data. That is where the `clone()` of the transactions comes from
- In a hierarchy, each class has to touch **a single field, its own**, and call
  `super`. Writing the four fields by hand is the terrible solution
- For that to work, the `do_copy()` / `do_compare()` all take **the same type of
  argument**, the base class. It is polymorphism, once again
- The day somebody puts a class **in the middle** of the hierarchy, the deep
  version goes on working by itself. The other one you have to go out and fix

Note:
The handle bug is the one everybody writes once: you modify the transaction you
already sent to the scoreboard, and the scoreboard sees the change halfway
through. It does not fail at the time; it fails later, and somewhere else.
The short way to close: **the `=` copies the slip of paper with the address, not
the house.** And that is why UVM brings `copy()`, `clone()` and `compare()`
ready-made — which is exactly the unit that follows.

## Transactions

#### *The testbench is well divided up, and the data is not*

- The testbench is already well divided up, but **the data is still a `struct`**:
  `command_s` for the commands and a bare `shortint` for the results
- A `struct` does nothing by itself. Printing a command is a `$sformatf` written
  by hand, and it is written **three times**: the two monitors and the
  scoreboard
- The same with randomizing and with comparing: every component builds its own,
  and the day the `struct` gains a field you have to remember all three
- And the result is not even a `struct`: it is a **bare** `shortint`, so the `ovf`
  of the VTALU —the second output— has nowhere to travel
- A class, on the other hand, has methods: the data and what gets done with it
  live together, and the rest of the testbench shrinks

Note:
The honest question from the student is "and why not a struct?". The answer: the
struct does not randomize itself, does not compare itself and does not print
itself. Everything the testbench used to do by hand with command_s becomes a
method of the class, and the rest of the testbench shrinks.
The fourth bullet is the most concrete argument and it is worth leaning on it: up
to here the analysis port of the result carries a `shortint`, that is to say **a
number**. The VTALU has two outputs —`result` and `ovf`— and that is why the
scoreboard of the previous units checks half the DUT and lets the other half
through. With a `result_transaction` with two fields, the check of the `ovf`
shows up on its own. It is the first time in the course that the class is not
tidiness: it is the only way.

---

## Transactions

#### *A transaction is data with the methods that operate on that data*

- It is the word the industry uses, and there is no magic class behind it: a
  **transaction** is that and nothing more
- The methods are four, and they are always the same:
  - `randomize()` — it fills itself in, respecting its `constraint`s
  - `convert2string()` — it prints itself
  - `do_copy()` — it copies itself
  - `do_compare()` — it compares itself
- What changes is not the data: it is **who knows things about it**. The `tester`
  used to know which values were legal; now it only says *"randomize yourself"*
- And the rest of the testbench shrinks: the three hand-written `$sformatf` become
  one call to `convert2string()`

Note:
The sentence on the slide is the definition to leave written on the board: **data
with the methods that operate on that data**.
The third bullet is the shift in the division of responsibilities of the section:
until today the `tester` knew which values were legal —it had a `get_data()` with
the bias written by hand—. From today that lives in the transaction, in a
`constraint`.
The question to throw out: if tomorrow the DUT accepts 16-bit operands, how many
classes have to be touched? One.

---

## Transactions

#### *Defining a transaction: which class it extends*

- Transactions are defined by extending the *uvm_sequence_item* base class and writing the following methods:
  - do_copy()
  - do_compare()
  - convert2string()
- What follows is turning the old `command_s` structure into a class,
  `command_transaction`, method by method

```sv
// ILLUSTRATION -- not compiled. The struct as it is in code/u5/put-get/vtalu_pkg.sv,
// the one this section turns into a class.
typedef struct {
   byte unsigned A;
   byte unsigned B;
   operation_t   op;
} command_s;
```

Note:
Careful with the base class, because the old material says something else. The
chain is `uvm_sequence_item` → `uvm_transaction` → `uvm_object`, and it is always
the first one that gets extended.
Two reasons. The small one: in IEEE 1800.2 `uvm_transaction` is a *virtual
class*, it cannot be instantiated on its own. The big one: a `uvm_sequence` only
knows how to send `uvm_sequence_item`. If the transaction extends plain
`uvm_transaction`, everything from day 6 —`start_item` / `finish_item`— does not
compile.
Which means the base class we pick today is the one that lets us go on tomorrow.

---

## Transactions

#### *The randomized fields: the "before"*

- Today the stimulus gets built with two hand-written functions, `get_op()` and
  `get_data()`, which draw the values with `$random` — the Verilog-95 one, with a
  global seed
- The legal range of `A` and `B` and the bias to the edges are properties **of the
  data**, not of the test — and yet they live in the tester
- SystemVerilog already brings this ready-made, and there is no need to write a
  single `$urandom`

```sv
// ILLUSTRATION -- not compiled. The two functions as they are in
// code/u5/put-get/tb_classes/random_tester.svh, the section this one replaces.
//
// This function handles the fact that
// the operation bus has 8 possible values,
// but only 6 of them are valid operations
virtual function operation_t get_op();
  bit [2:0] op_choice;
  op_choice = $random;
  case (op_choice)
          3'b000 : return no_op;
          3'b001 : return add_op;
          3'b010 : return sub_op;
          3'b011 : return and_op;
          3'b100 : return xor_op;
          3'b101 : return mul_op;
          3'b110 : return rst_op;
          3'b111 : return rst_op;
  endcase // case (op_choice)
endfunction : get_op

// This function was meant to spread out
// the probability of getting all zeros (prob = 1/3),
// biasing the randomness a little so the prob is not 1/256,
// since that would make our coverage goal hard to reach
virtual    function byte get_data();
  bit [1:0]   zero_ones;
  zero_ones = $random;
  if (zero_ones == 2'b00)
    return 8'h00;
  else if (zero_ones == 2'b11)
    return 8'hFF;
  else
    return $random;
endfunction : get_data
```

Note:
It is worth reading this code as the "before" and asking the question before
giving the answer: which part of this belongs to *the test* and which part
belongs to *the data*? The legal range of A and B, and the bias to the edges, are
properties of the data — they have nothing to do with what you want to test.
The hand-written `$random` is the symptom: every component that wants a valid
command has to repeat it. And if the DUT changes, all of them have to be
remembered.
A detail that gets charged for in the seeds slide: `$random` is the Verilog-95
one and has a **global seed**, so two threads calling it step on each other and
the run is not reproducible. `$urandom` has a per-thread seed. The `randomize()`
of the next slide uses the second one.
The punchline for the next slide: SystemVerilog already brings this ready-made,
and there is no need to write a single `$urandom`.

---

## Transactions

#### *The randomized fields: the "after"*

- Every SystemVerilog class brings an implicit `randomize()`, which picks values
  for the fields marked `rand`
- `get_op()` disappears: an `enum` randomizes itself over its legal values
- `get_data()` too, and it gets replaced by a `constraint` with `dist`, which is
  where the bias to the edges gets declared

```sv
class command_transaction extends uvm_sequence_item;
   `uvm_object_utils(command_transaction)
   rand byte unsigned A;
   rand byte unsigned B;
   rand operation_t   op;

// :/ and NOT :=  ---  this is the line that reproduces the bias towards the
   // corner cases that get_data() of the Functional coverage section did by hand (1/4 at 00, 1/4 at FF,
   // 1/2 in the middle). With ":=" the weight applies to EVERY value of the range, so the
   // middle takes 254 out of 256 and 00 comes up once every 256: the distribution
   // ends up almost uniform and the corner bins never fill.
   // The Constrained Random unit has the experiment with the numbers.
   constraint data {
      A dist {
         8'h00 :/ 1,
         [8'h01 : 8'hFE] :/ 2,
         8'hFF :/ 1
      };
      B dist {
         8'h00 :/ 1,
         [8'h01 : 8'hFE] :/ 2,
         8'hFF :/ 1
      };
   }
```

Note:
Three things about this code, in the order in which they get forgotten.
`rand` in front of every field: without that the field does not enter the draw
and `randomize()` leaves it as it was, **without warning**. It is the first place
to look when a value always comes out the same.
The `dist` with `:/` and not `:=`: it reproduces the bias to the edges that the
`get_data()` of the conventional testbench did by hand. The difference between
the two operators is a whole unit of the course, and it is not a style detail —
with `:=` the `00` bin comes up 1 time in 256 and the corner cases never get
filled.
And the `op` with no constraint: an `enum` randomizes over its values, so `no_op`
and `rst_op` are going to come out too. That is on purpose — the verification
plan asks for operations after a reset.

---

## Transactions

#### *The constructor: a `uvm_object` has no parent*

- *uvm_sequence_item* extends *uvm_transaction*, and that one *uvm_object* — which means a transaction is **not** a *uvm_component*. It therefore has a simpler constructor
- A transaction **does not live in the tree of the testbench**: that tree is made
  of *uvm_components*, and it is the one UVM walks in `build_phase`. With no place
  in the tree there is no parent, and that is why the constructor only asks for a
  `name`
- Objects get created and destroyed all the time while the simulation runs;
  components get built once, before it starts, and they stay
- It is still worth giving them a name: it is the one that shows up in the UVM
  messages

```sv
   // Constructor of a uvm_object: dead simple, it only takes a name. A
   // transaction has no parent because it does not live in the component tree.
   function new(string name = "");
      super.new(name);
   endfunction : new
```

Note:
It is the distinction that has to be left clear: *component* is structure —it is
in the tree, it has a parent, it has phases—; *object* is data —it gets created,
it travels around the testbench and it gets thrown away—. Both are UVM classes,
but only one of them builds the hierarchy.
A trick to remember it: if you can draw it in the block diagram of the testbench,
it is a component. If it travels along an arrow of the diagram, it is an object.

---

## Transactions

#### *`do_copy()`: copy the object, not the handle*

- `uvm_object` brings two ready-made methods: `copy()`, which pours the data onto
  another object **that already exists**, and `clone()`, which also creates the
  new object
- Both work only if the class implements `do_copy()`: the library knows how to
  copy, but it does not know **which fields** your transaction has
- It is the same pattern as the rest of the section: `copy()` is the one that gets
  called, `do_copy()` is the one that gets written
- The only difference is the argument: it has to be a `uvm_object` —hence the `$cast`—. UVM calls it *rhs* (*right hand side*) by convention, not by requirement

```sv
   function void do_copy(uvm_object rhs);
      command_transaction copied_transaction_h;

// Checks that make DEBUG easier
      if (rhs == null)
         `uvm_fatal("COMMAND TRANSACTION", "Tried to copy from a null pointer")

if (!$cast(copied_transaction_h, rhs))
         `uvm_fatal("COMMAND TRANSACTION", "Tried to copy wrong type.")

super.do_copy(rhs);  // copy all parent class data

A = copied_transaction_h.A;
      B = copied_transaction_h.B;
      op = copied_transaction_h.op;

endfunction : do_copy
```

Note:
The pattern is the one from the class hierarchies, with two UVM rules on top.
The first one, the one that makes it compile: the argument has to be of type
`uvm_object` —the base class of everything—, because what SystemVerilog demands for
the virtual override to work is that the type and the direction match, not the
name. `rhs` is the identifier used in the signature of `uvm_object::do_copy` and
that is why everybody copies it, but you can call it whatever you like. The first
thing to do is cast it. And since the `$cast` checks at run time, it goes with its
`uvm_fatal`: if somebody tries to copy a `result_transaction` onto a
`command_transaction`, you want to find out right there and not three components
further on.
The second one: the `super.do_copy(rhs)` goes **before** touching your own
fields. It is the same discipline as in the class hierarchies and here it matters
more, because `uvm_transaction` —two levels up— has fields of its own that you do
not see: `accept_time`, `begin_time`, `end_time` and `initiator`.
And the detail that confuses everybody: you write `do_copy()`, but you **never
call it**. The testbench calls `copy()`, which lives in `uvm_object`, and that one
takes care of invoking your `do_copy()`. It is the same division as the phases —
you put in the bottom part, the library handles the protocol.

---

## Transactions

#### *The MOOCOW rule: sharing yes, modifying no*

- Several components can see the same piece of data if they have handles to the
  same object. It is cheap and it works — as long as nobody modifies it
- The rule that holds it up is called **MOOCOW** —*Manual Obligatory Object Copy On
  Write*—, and that is how *The UVM Primer*, by Ray Salemi, christens it
- It says this: sharing a handle is fine **as long as you do not touch the
  object**. Whoever wants to modify, copies first
- It is a discipline of the team, not something the language enforces. UVM only
  puts up the tool: `clone()`, which returns a `uvm_object` and has to be cast

Note:
The name is a joke from the *UVM Primer*, but the rule is the one that
avoids the most expensive bug of the class hierarchies: you sent the transaction
to the scoreboard, you still hold the handle, you modify it for the next one, and
the scoreboard ends up comparing against data that changed after it received it.
It does not fail every time — it fails under load, which is when it suits you
worst.
The practical version, without acronyms: **whoever produces the data does not
touch it again after publishing it.** If you need to change it, clone.
Look at how the `tester` of this section complies with it: it does not reuse the
handle. Every turn of the `repeat` does a fresh `create()`. It is cheaper than
cloning and it avoids the argument.
And there is one documented exception they are going to see on day 6: the driver
writes the result inside the item the sequence lent it. It is agreed between the
two parties and it is the only place in the testbench where that gets done.

---

## Transactions

#### *`clone_me()`: the `$cast` written a single time*

- Since `clone()` returns a `uvm_object`, every component that uses it ends up
  writing its own `$cast` — the same one, repeated
- The *UVM Primer* convention is to add a `clone_me()` to the transaction
  that does both things and returns the right type already
- UVM does not bring it: it is four lines written once in the data, so that none
  of the ones who use it have to remember the cast

```sv
   function command_transaction clone_me();
      command_transaction clone;
      uvm_object tmp;

tmp = this.clone();
      $cast(clone, tmp);
      return clone;
   endfunction : clone_me
```

Note:
It is a three-line method and it exists for one reason only: `clone()` returns a
`uvm_object`, so everybody who uses it has to cast. Writing the `$cast` once
inside the class is better than writing it fifty times outside.
The name is not in the standard: `clone_me()` is a *UVM Primer*
convention. In somebody else's project it can be called something else or not
exist at all — and there you are going to see the `$cast` repeated in every
caller.
And the trap that has to be named: `clone()` calls `create()` and then `copy()`,
which ends up in your `do_copy()`. If `do_copy()` forgets a field, the clone comes
out incomplete and **nobody warns you**. It is the same hole as in the class
hierarchies, under another name.

---

## Transactions

#### *`do_compare()`: comparing two objects without writing an `if` per field*

- `compare()` comes with `uvm_object` and returns 1 if the two objects are equal.
  It is the one that gets called; the one that gets **written** is `do_compare()`
- It takes two arguments: the `rhs` —the other object— and a `uvm_comparer`, which
  is the comparison policy: how many differences to report and with what verbosity
- Almost nobody touches the comparer, but it has to be declared because the
  signature asks for it

```sv
   function bit do_compare(uvm_object rhs, uvm_comparer comparer);
      command_transaction compared_transaction_h;
      bit same;

if (rhs == null)
         `uvm_fatal("RANDOM TRANSACTION", "Tried to do comparison to a null pointer");

// First check whether we are comparing the same type
      if (!$cast(compared_transaction_h, rhs)) same = 0;
      else
         // Deep comparison: what the parent compares, plus the three fields of
         // this class
         same = super.do_compare(
             rhs, comparer
         ) && (compared_transaction_h.A == A) && (compared_transaction_h.B == B) &&
             (compared_transaction_h.op == op);

return same;
   endfunction : do_compare
```

Note:
Two things that get copied wrong.
The `$cast` here does **not** go with a `uvm_fatal`: if the type does not fit, the
right answer is `same = 0` —they are different, obviously, if they are not even of
the same class—, not killing the simulation. It is the difference with
`do_copy()`, where a wrong type really is a testbench bug. Worth showing them side
by side.
And the `super.do_compare()` goes **chained with `&&`**, not called and thrown
away. The classic mistake is to write `super.do_compare(rhs, comparer);` on a line
of its own and then `same = (A == rhs.A) && ...`: it compiles, it runs, and it
silently stops comparing everything from the class above.
The `uvm_comparer` of the second argument is the policy —how many differences to
report, with what verbosity—. Almost nobody touches it, but it has to be declared
because the signature asks for it.

---

## Transactions

#### *`convert2string()`: the transaction prints itself*

- It is the method that returns the object as text. It gets written **once**, and
  it is used by the scoreboard, the monitor and anybody who has to report
- `$sformatf()` builds the string with the same format specifiers as always
- And the detail that makes a log readable: an `enum` has `name()`, which returns
  `add_op` instead of `3'b001`. Without that the error says a number and nobody
  reads it

```sv
   function string convert2string();
      string s;
      // op.name() can be add_op, no_op ...
      s = $sformatf("A: %2h  B: %2h op: %s", A, B, op.name());
      return s;
   endfunction : convert2string
```

Note:
It is the most used of the three methods, and the one that gets the least
attention: every message of the scoreboard and of the monitors of the rest of the
course comes out of here.
The `.name()` of the `enum` is the detail that changes the day: without it the log
says `op: 4` and you have to go looking for the `typedef`; with it, it says
`op: mul_op`. The rule to take home: **if a field is an enum, the log gets its
name, never its value.**
Worth naming the relatives UVM brings and the course does not use: `print()` and
`sprint()`, which print the transaction on their own if you registered the fields
with the `` `uvm_field_* `` macros — or if you write `do_print()`, the manual
equivalent of `convert2string()`, which does not show up in a single slide of the
course. Careful with that: with no macros and no `do_print()`, a `t.print()` on the
transactions here prints the header and nothing else. The format **can** be
changed: the default is the `uvm_table_printer` —one row per field, with type and
radix— and there is a `uvm_line_printer` that puts the whole object on one line.
The reason to prefer `convert2string()` is simpler and should be said that way:
written by hand it fits in one line that says what you care about, and in a file of
a hundred thousand lines that matters.

---

## Transactions

#### *The field macros: reading them even if you do not write them*

```systemverilog
class command_transaction extends uvm_sequence_item;
   `uvm_object_utils_begin(command_transaction)
      `uvm_field_int (A,  UVM_DEFAULT | UVM_HEX)   // an integral field
      `uvm_field_enum(operation_t, op, UVM_DEFAULT)
      `uvm_field_object(payload, UVM_DEFAULT | UVM_REFERENCE)  // handle, not a copy
   `uvm_object_utils_end
endclass
```

- It is what you will find in **every VIP** you open. They generate `do_copy`,
  `do_compare`, `do_print`, `do_pack` and the automatic configuration, out of one
  declaration per field
- The second argument is a mask: `UVM_DEFAULT` turns on every
  operation, and `UVM_NOCOMPARE` / `UVM_NOPRINT` turn one off. The radix
  (`UVM_HEX`, `UVM_DEC`) is only for printing
- `UVM_REFERENCE` on a `uvm_field_object` copies **the handle**; without it, the copy
  is deep. It is the same decision as `do_copy()`, taken in a constant
- The course writes them by hand for the reason already given: that gets debugged, this
  does not. But reading them you do have to know

Note:
This is the *"and when you open the VIP at work"* slide. The course's decision
—writing `do_copy`, `do_compare` and `convert2string` by hand— is taken and well
taken, and it is not being reversed here: what gets added is the half that was missing,
which is **reading** what somebody else wrote.
The way to read it is always the same and is worth handing over as a recipe: the list
of `` `uvm_field_* `` **is** the definition of what "equal" means and what
"copy" means for that class. If a field is not on the list, `compare()`
does not look at it — and that is the most expensive bug these macros produce: a scoreboard
that goes green because the field that matters was left out of the declaration.
The `UVM_REFERENCE` deserves its second, because it is the `do_copy()` trap again
in another disguise: without it, copying the transaction also copies the object hanging off it, and
a `clone()` in a monitor with heavy traffic gets expensive without anybody noticing.
With it, the two transactions share the same payload — which is exactly what
MOOCOW says must not be modified.
The real cost, so the course's decision does not look like taste: the macros
expand into hundreds of lines per class, and when something goes wrong the error points
inside the expansion. A hand-written four-line `do_compare` reads
on the spot.

---

## Transactions

#### *The seven steps, and why there are seven*

What it costs to change the data type of a TB that already exists. We look at
**2, 3, 6 and 7**; **1, 4 and 5** are a direct port and are in the repo:

| # | What | Where |
| --: | --- | --- |
| 1 | a `result_transaction` for the trip back | `result_transaction.svh` |
| 2 | an `add_transaction`, additions only | `add_transaction.svh` |
| 3 | the two testers merge into one | `tester.svh` |
| 4 | the `command_monitor` publishes objects | `command_monitor.svh` |
| 5 | the `result_monitor`, the same | `result_monitor.svh` |
| 6 | the `scoreboard` uses `compare()` | `scoreboard.svh` |
| 7 | `add_test` overrides the **data** | `add_test.svh` |

Note:
The seven steps are the most boring part of the section and also the most honest,
so it is worth framing them instead of rushing through them: **this is what it
costs to change the data type of a testbench that already exists.** The real
advice is to do it from the start.
The one to keep an eye on is number 3, because it is the only one that **deletes**
a class: `add_tester` disappears. That is where the result of the section is, and
it is worth announcing it — moving the decision into the data made a whole
structural class redundant.
If the group is going fast, steps 4 and 5 get opened in the editor and compared
with the ones from the analysis ports: the difference is that instead of filling a
`struct` there is a `create()` and fields get filled. Nothing else.

---

## Transactions

#### *Step 2 · an `add_transaction` that only adds*

- `add_transaction` extends `command_transaction` and adds **a single**
  constraint to it: `op == add_op`
- That is enough to change the stimulus, and the `tester_h` never finds out: it
  uses the child class exactly as it used the mother
- Constraints **are inherited and they accumulate**: the bias to the edges of `A`
  and `B` is still there, because the one in the base class does not go away

```sv
class add_transaction extends command_transaction;
   `uvm_object_utils(add_transaction)

constraint add_only {op == add_op;}

function new(string name = "");
      super.new(name);
   endfunction
endclass : add_transaction
```

Note:
Eight lines, and out of those only one does anything:
`constraint add_only {op == add_op;}`. It is worth putting it next to the
`add_tester` of the env, which did the same thing by redefining a method. Two ways
of saying "additions only", and today's does not touch behaviour code — it only
describes which values are legal.
The conceptual point, which is the one that orders the day: **constraints are
inherited and they accumulate.** `add_transaction` does not replace `data`, it
adds to it. The solver has to satisfy both at once, so there is still bias to the
edges in `A` and `B` — and that is exactly what we want.
From there comes the warning: two inherited constraints that contradict each other
do not give a compilation error, they give a `randomize()` that returns 0. It is
case 1 of the Constrained random experiment.

---

## Transactions

#### *Step 3 · two testers become one*

```sv
   task run_phase(uvm_phase phase);
      command_transaction command;

phase.raise_objection(this);

// ALL transactions come out of the factory, the directed ones too.
      // A new() here would compile and work just the same, but it would skip
      // add_test's set_type_override: the factory never hears about what you
      // build by hand. See the slide "the new() that eats the override".
      command = command_transaction::type_id::create("command");
      command.op = rst_op;
      command_port.put(command);

repeat (1000) begin : random_loop
         command = command_transaction::type_id::create("command");
         // randomize() returns 0 if the constraints have no solution, and aborts
         // nothing. A bare assert() lets an unrandomized transaction through in
         // silence: the TB carries on, sending garbage.
         if (!command.randomize()) `uvm_fatal("TESTER", "randomize() failed")
         command_port.put(command);
      end : random_loop

// Directed: the multiplier overflow case, which 1000 random operations
      // might never touch. It comes out of the factory like the others, but
      // since it is not randomized, add_transaction's constraint does not run:
      // the factory picks the TYPE, constraints only act inside randomize().
      command = command_transaction::type_id::create("command");
      command.op = mul_op;
      command.A = 8'hFF;
      command.B = 8'hFF;
      command_port.put(command);

#500;
      phase.drop_objection(this);
   endtask : run_phase
```

- The testbench of the env had `base_tester` and `add_tester`: two classes for two
  kinds of stimulus
- Now there is **only one**. The `repeat` creates a transaction and tells it
  `randomize()`; what comes out of that is decided by the **data**, not by the
  tester
- That is the line that deletes a class: the decision moved from the structure to
  the type of the transaction

Note:
It is the result of the section, measured in files: `add_tester.svh` stops
existing. It is worth saying out loud, because the env had spent a while
justifying that hierarchy and now half of it is redundant.
And it is not that the env was wrong: it was the right answer while the data was a
mute `struct`. When the data knows how to randomize itself, that step of the
hierarchy runs out of work. It is a good example of abstractions being justified
against the problem of the moment, not forever.
The `if (!command.randomize()) uvm_fatal` is the line to copy properly:
`randomize()` returns 0 if the constraints have no solution and it aborts nothing.
There is a whole slide on that further on.

---

## Transactions

#### *Step 6 · the scoreboard compares objects, not numbers*

- Both sides of the comparison are now `result_transaction`: the one that arrives
  from the `result_monitor` and the one the predictor builds
- The `write()` takes the result `t`, looks for the command that corresponds to it
  in the `command_monitor` queue, and asks `predict_result()` for the prediction
- The comparison comes down to one line —`predicted.compare(t)`— and the error
  message builds itself out of the `convert2string()` of the three transactions

```sv
   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
```

Note:
Comparing this `write()` with the one from the analysis ports is the best way to
close the section: over there was a `case` with the prediction written inside it
and a hand-written comparison; here there is a `predict_result()` that returns an
object and a `predicted.compare(t)`.
What was gained is concrete: the error message is now built with
`convert2string()` of the three transactions, so it says what was sent, what came
out and what was expected, all with the enums by name. And the day the transaction
gains a field, the log shows it on its own.
A detail that has to be pointed out because it is the rule of the section applied:
the `predicted` comes from `type_id::create()`, not from `new()`. It is a
transaction that travels —even if it only travels as far as the `compare()` on the
next line—, so it comes out of the factory like all the others.
And the `do ... while` that skips `no_op` and `rst_op` is still the same as in the
analysis ports: those operations produce no result, and if they are not thrown
away the comparison shifts by one and everything fails.

---

## Transactions

#### *Step 7 · the override, now on the data*

```sv
class add_test extends random_test;
   `uvm_component_utils(add_test);

function void build_phase(uvm_phase phase);
      command_transaction::type_id::set_type_override(add_transaction::get_type());
      super.build_phase(phase);
   endfunction : build_phase

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

endclass
```

- The whole test is **two lines**: the override and the `super.build_phase()`
- And the override no longer changes a **component** —the tester— but a **piece of
  data** —the transaction—. The structure of the testbench stopped having an
  opinion about the test
- `super.build_phase(phase)` goes **after** the override, and that order is not
  negotiable: the env gets built in there

Note:
It is worth putting this slide next to the `add_test` of the env and counting
lines: the same idea, one level further down. Before, what generates was
substituted; now, what is generated is.
The order of the `super` is the trap of the slide, and it is a sibling of the one
in the env: the factory decides what to build at the moment of the `create()`. If
the override arrives afterwards, there is no error — the testbench runs with
`command_transaction` and the "additions" test sends random operations. It does
not break, it lies.
And a question that always comes up: why does `add_test` call `super.build_phase()`
here if the course says it is not needed? Because its base is `random_test`, a
class of **ours** that has a `build_phase` with real work in it. The rule from the
components was talking about `uvm_component`, which does not have one.

---

## Transactions

#### *The `new()` that eats the override*

```systemverilog
command = new("command");                                   // NO
command.op = rst_op;

command = command_transaction::type_id::create("command");  // YES
command.op = rst_op;
```

- `set_type_override()` talks **to the factory**, and the factory only finds out
  about what goes through `type_id::create()`
- A `new()` builds the type that line says and nothing else: the override **does
  not reach it**. It compiles, it runs, and it does not fail — that object simply
  got left out
- It is the worst kind of bug: it does not break, it **lies**. With one test and
  one transaction it never shows; the day the override really mattered, it is
  already too late
- The rule, short: **every `uvm_object` that travels around the testbench comes
  out of `type_id::create()`** — the transactions of the tester, and also the ones
  the monitors build and the `predicted` of the scoreboard
- The *ports* and the *exports* are the exception: they are not in the factory and
  they get instantiated with `new()`, as we saw in one producer, many listeners.
  The *TLM FIFO* is registered, but the course builds it with `new()` anyway
  because the `size` goes through the constructor and `create()` cannot pass it

Note:
This slide comes out of a bug this very course had: the tester created the two
directed operations —the reset and the FF x FF multiplication— with `new()`, so
under `add_test` those two were NOT `add_transaction`. Nobody noticed because the
testbench works just the same.
The question to throw at the group, which is the one that orders everything: if
the reset now comes out of the factory and under `add_test` it is an
`add_transaction`, why does the constraint `op == add_op` not turn it into an
addition? Because we do not randomize it. **The factory picks the type;
constraints only act on `randomize()`.**

---

## Transactions

#### *And `randomize()` never goes on its own*

```systemverilog
assert (command.randomize());                                  // NO
if (!command.randomize()) `uvm_fatal("TESTER", "randomize() failed")  // YES
```

- `randomize()` returns **0** when the constraints have no solution. It does not
  abort, it prints nothing on its own: it returns 0 and carries on
- A bare `assert()` reports outside UVM: it does not go into the *Report Summary*
  —the same one we learned to read in reporting— and in many simulators execution
  carries on with the transaction **unrandomized**
- And if the project compiles with assertions turned off, there are simulators
  that do not even evaluate the expression: `randomize()` simply **never gets
  called**
- With `` `uvm_fatal `` the error brings component, time and file, and it stops the
  run right there

Note:
It is one extra line that pays for itself the first time somebody adds a
contradictory constraint. Without the `else`, the symptom is a scoreboard failing
on transactions with absurd values and half an afternoon spent looking for it in
the DUT.
The `` `uvm_fatal `` is not an exaggeration: an unrandomized transaction is not
bad stimulus, it is stimulus you did not choose. Better for the run to die with a
message than to tell somebody that last night's regression meant nothing.

---

## Transactions

#### *Summary of the unit*

- We saw how to use *transactions* to move data around the TB
- That lets us simplify the components of the TB and even remove a class from our initial TB (add_tester)
- The unit that follows groups the classes that talk to one and the same interface
  into a single reusable block: the `uvm_agent`

Note:
Closing of day 5, and it is worth saying what is missing: today the stimulus is
generated by a tester you wrote yourself; in modern UVM that is a uvm_sequence
running on a sequencer, and the set of driver + monitor + sequencer is packed into
an agent. That is day 6.

## Constrained random

#### *The other half of the pincer*

- The functional coverage of the conventional testbench tells you **what is
  missing**. It does not tell you how to get there: that is the stimulus
- Writing a directed test per bin does not scale — there are 76 of them in the
  VTALU, and a real chip has thousands
- The industry recipe is the other way round: **random for the bulk, directed for
  the holes**. And the random has to be *legal*, or the DUT complains about things
  that are never going to happen in silicon
- *Constrained random* is writing the rules of the stimulus **once, in the
  transaction**, and letting the solver build the cases

Note:
It is the half of the pair that was missing: up to here the course measured
coverage and built the transactions, but the stimulus still came out of a
`get_op()` with a hand-written `case`.
The sentence that orders the section: **a constraint does not pick a value, it
describes the set of legal values.** The one that picks is the solver, and it
picks differently from what you expect more often than you would like. The whole
section is about measuring that instead of assuming it.

---

## Constrained random

#### *`rand` and `randomize()`: what you have already seen*

```systemverilog
class command_transaction extends uvm_sequence_item;
   rand byte unsigned A;      // rand  -> it enters the draw
   rand byte unsigned B;
   rand operation_t   op;     // an enum randomizes over its values

constraint data { ... }    // the rules, in a block of their own
endclass
```

- `randomize()` comes from SystemVerilog, not from UVM: **every** class has it
- It picks values for the `rand` fields that **satisfy every active constraint at
  once**
- A `constraint` **is not sequential code**: it does not run from top to bottom, it
  has no order. It is a set of relations the solver satisfies together
- That is why two constraints that contradict each other do not give a compilation
  error: they give a `randomize()` that returns 0

Note:
The bullet to say slowly is the third one, because it is the wrong mental model
everybody brings along: a `constraint` **does not run**. It is not a long `if`, it
does not go from top to bottom, and the order they are written in makes no
difference. It is a system of equations, and `randomize()` hands it to a solver
—in this course, z3— so that it returns a random solution out of all the ones that
satisfy it.
From there comes the consequence of the last bullet, and it is the most expensive
trap of the section: two incompatible constraints compile perfectly. The error
shows up at simulation time, `randomize()` returns 0, and **if nobody checks the
return value the class is left with the values it had**. The testbench goes on
running and sends garbage.
The rule to take away from here, and one the course keeps everywhere in `code/`: a
`randomize()` always goes inside an `if` that checks the return value. Never on its own.

---

## Constrained random

#### *The other three words: `randc` and the two hooks*

```systemverilog
class command_transaction extends uvm_sequence_item;
   rand  byte unsigned A;       // it can repeat: 3 3 6 1 3 4 6 2 ...
   randc bit [2:0]     indice;  // it walks the 8 and only then repeats

function void pre_randomize();   // runs BEFORE the draw
      if (!primera) A = A_anterior; // …with the values still old
   endfunction

function void post_randomize();  // runs AFTER, with the new values
      checksum = A ^ B;             // what is not drawn gets computed here
   endfunction
endclass
```

- `randc` is **cyclic**: it exhausts every value before repeating one. Measured on
  Verilator 5.052: `4 2 1 7 5 6 3 0` and only then does it start over
- It is for walking a small space —an opcode, a register index— without
  waiting for chance to cover it. Only on **small** integral types: the LRM
  guarantees 8 bits and simulators usually stop at 16
- `pre_randomize()` / `post_randomize()` are the two hooks `randomize()`
  calls on its own. The **derived** field —a checksum, a parity— gets computed in the
  second one, it does not get drawn
- And a warning: whatever gets computed in `post_randomize()` does **not** take part in the
  solver. If it has to satisfy a constraint, it is a `rand` field

Note:
They are the three words of the language that are missing for the student to read any
foreign transaction without stopping. None is hard; what is needed is knowing
when each one is used.
`randc` is the answer to *"I want to go through every opcode"*, and the argument
is efficiency: with `rand` over eight values it takes some twenty-two
draws to see all eight —the coupon collector's problem—, and with
`randc` eight are enough. And the width limit has a concrete reason: the solver
has to carry the list of what has already come out, so a 32-bit `randc` would be
a table of four billion entries.
The two hooks are best explained by what they solve. `post_randomize()` is
for the field that **derives** from the drawn ones: a CRC, a parity, the
length of a payload that has already been drawn. Making it `rand` with a constraint
tying it to the rest is asking the solver to solve a problem that is done with
an XOR.
`pre_randomize()` gets used less and has a trap worth naming: it runs **before**
the draw, which means the fields still have the values of the previous
transaction. That makes it useful for whatever depends on the past —keeping the previous
address to ask for a contiguous access— and dangerous if you believe the new ones
are already there.
And the underlying warning, which is the same as the whole section's: a field computed in
`post_randomize()` is **outside** the system of equations. The solver does not see it,
the constraints do not restrict it, and `randomize()` will never return 0 because of it.

---

## Constrained random

#### *`dist`: `:=` is not the same as `:/`*

```systemverilog
A dist {8'h00 := 1, [8'h01 : 8'hFE] := 1, 8'hFF := 1};   // the weight goes to EACH value
A dist {8'h00 :/ 1, [8'h01 : 8'hFE] :/ 2, 8'hFF :/ 1};   // the weight gets SPLIT
```

- `dist` sets **weights**: it does not change which values are legal, it changes
  how often they come up
- With `:=` the weight is applied **to each value of the range**: the middle range
  weighs 254 and the edges 1 each. `A=00` comes up **1 time in 256**
- With `:/` the weight belongs to **the whole range**: 1 – 2 – 1 gives 25 % on
  `00`, 50 % in the middle, 25 % on `FF`. Which is exactly the bias the
  `get_data()` of the conventional testbench did by hand
- Both lines compile, both run, and **one of the two never fills the edge bins**

Note:
The arithmetic has to be done on the board, because read out loud it does not sink
in: with `:=` the weights are 1, 1 and 1, but the middle one is applied to **each
one** of its 254 values. A total of 256 equal parts, and `A=00` comes up one time
in 256. With `:/` the parts are three —1, 2 and 1— and `A=00` comes up one time in
four. Sixty-four times more often, for two characters.
And now the part that makes it dangerous: **both versions work**. Neither gives a
warning, neither fails, the testbench runs the thousand transactions just the
same. The only thing that changes is that with `:=` the `a_00` bin of the
covergroup takes an eternity to fill, and whoever looks at the report concludes
that a test is missing.
It is exactly the kind of bug the course calls a silent trap, and that is why the
next slide does not explain: it **measures**. The practical rule to hand down: if
you write a `dist`, run a histogram before believing it.

---

## Constrained random

#### *Do not assume it: measure it*

```sv
   // The weight goes to EVERY value of the range: the middle takes 254 of 256.
   class por_valor;
      rand byte unsigned A;
      constraint data {A dist {8'h00 := 1, [8'h01 : 8'hFE] := 1, 8'hFF := 1};}
   endclass

// The weight is SPLIT inside the range: 1/4 at 00, 1/2 in the middle, 1/4 at FF.
   // It is the same bias get_data() of the Functional coverage section did by hand.
   class por_rango;
      rand byte unsigned A;
      constraint data {A dist {8'h00 :/ 1, [8'h01 : 8'hFE] :/ 2, 8'hFF :/ 1};}
   endclass
```

```sh
$ cd code/u6/transactions/constraints && bash run.sh
400 randomizations of each version
  :=   A=00   0.2%   A=FF   0.2%   the weight goes to each value
  :/   A=00  23.2%   A=FF  27.0%   the weight gets split
```

![Measured histogram: with := the edge bins come out 0.2 %; with :/ they come out 23 % and 27 %](../res/diagrams/en/constrained-random_dist.svg)

Note:
This experiment came out of a bug in this very course: `command_transaction` had
the `dist` written with `:=`, which means the bias to the corner cases the
transactions claimed to have **did not exist**. The distribution was practically
uniform and nobody found out, because the testbench passed just the same.
That is the underlying point of the section, and it is worth saying it that
bluntly: a badly written constraint **does not fail, it lies**. There is no
warning, there is no compilation error, there is no test in red. The only thing
that gives it away is the coverage that does not go up — and that is only noticed
weeks later.
A practical rule to take home: every time you write a `dist`, run a few thousand
randomizations and print the histogram **once**. It costs ten minutes and it is
the difference between believing and knowing.

---

## Constrained random

#### *`inside` and `randomize() with {}`*

```sv
   class comando;
      rand byte unsigned A;
      rand byte unsigned B;
      rand operation_t   op;

constraint data {
         A dist {8'h00 :/ 1, [8'h01 : 8'hFE] :/ 2, 8'hFF :/ 1};
         B dist {8'h00 :/ 1, [8'h01 : 8'hFE] :/ 2, 8'hFF :/ 1};
      }

// inside is a set of legal values. Without it the random also asks for
      // no_op and rst_op, which compute nothing.
      constraint utiles {op inside {add_op, and_op, xor_op, mul_op};}
   endclass
```

```sv
      // The portable workaround meanwhile: turn off the split, which for a
      // directed case makes no sense anyway.
      c.data.constraint_mode(0);
      if (!c.randomize() with {
            op == mul_op;
            A  == 8'hFF;
            B  == 8'hFF;
          })
         $fatal(1, "randomize() with failed even with the constraint turned off");
      $display("with with: 1 try,      A=%2h %s B=%2h", c.A, c.op.name(), c.B);
```

- `inside {a, b, c}` is the set of legal values: without it, the random also asks
  for `no_op` and `rst_op`, which compute nothing. Here it also leaves out `sub_op`,
  so that the draw comes out uniform among four
- `randomize() with { ... }` adds constraints **for that call only**: the directed
  case gets asked for at the point of use, without touching the class and without
  writing a new tester. It is the tool of *coverage closure*

Note:
The number that comes out of running `02_with.sv` is the whole argument of the section: 400 random attempts
fill `mul_max` a handful of times —6 with the default seed, between 2 and 8
depending on which one you use— **because the `dist` biases towards the edges**.
The arithmetic is worth doing out loud: `op` comes out uniform among four and each
leg lands on `FF` one time in four, that is 1/4 × 1/4 × 1/4 = **1 in 64**, which
over 400 attempts is six and a bit. With the badly written `dist` of the previous
slide, the probability of both legs landing on `FF` is 1/65536 per operation: you
never touch it.
The mental sequence is always the same: I run random, I look at which bin was left
empty, I write a three-line `with {}`, I run again. Never "I write 76 tests".
The Verilator limitation the section states is there on purpose, and it
is worth stating it properly because it is not a matter of "it works or it does
not". Verilator resolves the `dist` **by picking a concrete value first** and only
then checks the rest: if the one drawn does not satisfy the `with`, it returns 0
instead of looking for another. The success rate is therefore the probability of
the bin. Measured: `with {A == 8'hFF}` resolves 25 % of the time —the weight of
that bin—, `with {A inside {[1:10]}}` 2 %, and a field with no `dist` 100 %.
Why it matters more than it looks: the symptom is **an intermittent directed
case**, which works when you try it and fails in the overnight regression. The
numbers are in `code/verilator/repro-dist-with.sv`, and the workaround —turning
the constraint off— is the same `constraint_mode()` you see further on.

---

## Constrained random

#### *`soft`: the default a `with {}` can override*

```systemverilog
class command_transaction extends uvm_sequence_item;
   rand byte unsigned A;
   constraint por_defecto { soft A == 8'h00; }   // "zero, unless somebody asks otherwise"
endclass

t.randomize();                          // A = 00
t.randomize() with { A inside {[1:10]}; };   // A between 1 and 10: the soft drops on its own
```

- A `soft` constraint is a **wish**, not a rule: if it clashes with another, the
  solver **drops** it instead of returning 0
- It is the modern way of writing a default value in the transaction without
  forcing anybody to call `constraint_mode(0)` to override it
- The **hard** constraint wins, and between two clashing `soft` ones the one declared
  **later** wins — the order does matter here, and only here
- Measured on Verilator 5.052: with the `with {}` it comes out between 1 and 10; without it, `00`

Note:
This is the piece that makes the previous slide scale to a real testbench.
The `randomize() with {}` is for asking for a directed case, but if the class already
has a hard constraint saying otherwise, the `with` does not override it: it contradicts it,
and `randomize()` returns 0. The old way out was `constraint_mode(0)` — which forces
whoever writes the test to know the name of a constraint in a class they did not
write.
The design rule to leave behind, because it is the one used in every modern
VIP: **what is a rule of the protocol goes hard; what is a preference
of the stimulus goes `soft`**. An address aligned to 4 is hard, because the DUT does not
accept anything else. That `burst_len` defaults to 1 is `soft`, because the test
that wants long bursts has the right to ask for them without permission.
The tie-break between two `soft` ones is worth saying and not using: the last one
declared wins, and if that matters to you for anything, the constraint was badly written.
They came in with IEEE 1800-2012, so any simulator of the last decade has
them — and Verilator too, measured right up there.

---

## Constrained random

#### *The order of resolution biases without warning*

```systemverilog
rand bit           es_reset;
rand byte unsigned A;
constraint c {es_reset -> A == 8'h00;}   // "if I ask for a reset, the operands at zero"
```

- It looks harmless. **It is not**: the solver picks among the *solutions*, not
  among the values of each field
- With `es_reset = 1` there is **one**; with `es_reset = 0`, **256**. You asked for
  a reset half the time and you will see it **1 time in 257**
- The *"any operation after a reset"* bin of the plan does not get filled, and the
  report does not tell you why
- The answer from the language is `solve es_reset before A`: pick the control field
  first

![One cell against a 16 by 16 block: the 257 solutions, and only one has the reset](../res/diagrams/en/constrained-random_solve.svg)

Note:
The sentence that dismantles the intuition is the one in the first bullet, and it
is worth repeating it word for word: **the solver picks uniformly among the
solutions, not among the values of each field**. Nobody wrote that `es_reset` was
going to come out 1 half the time; that came from assuming each field gets drawn
separately, and it does not.
It is worth counting the 257 solutions out loud, because the number convinces more
than the argument: `es_reset=1` forces `A=00`, that is to say a single
combination; `es_reset=0` leaves `A` free, that is to say 256. The draw is over the
257, and the reset takes one of them.
The connection with the verification plan is what makes this slide worth it: the
row *"any operation after a reset"* does not get filled, the coverage stays pinned
down, and the report does not say **why**. A student without this slide adds
random tests for an afternoon.
And the warning about the cure, so that it does not get overused: `solve ... before`
does not change which solutions are legal, only the order in which the solver
picks. It is a distribution knob, not a correctness one — and it costs solver
time, so it goes where it is needed and not out of habit.

---

## Constrained random

#### *Measured, with the workaround that Verilator does honour*

```sv
   class sesgada;
      rand bit           es_reset;
      rand byte unsigned A;
      constraint c {es_reset -> A == 8'h00;}
   endclass

// The language's answer is "solve es_reset before A": pick the control field
   // FIRST and then solve the rest. Verilator 5.052 accepts the syntax and does
   // NOT honour it -- it leaves es_reset stuck at 0, which is worse than
   // ignoring it. Repro in code/verilator/repro-solve-before.sv.
   //
   // The workaround that IS portable: ask explicitly for the split of the
   // control field. It says the same and does not rely on the solver ordering well.
   class pareja extends sesgada;
      constraint reparto {es_reset dist {1'b0 :/ 1, 1'b1 :/ 1};}
   endclass
```

```sh
2000 randomizations of each version
  as written             es_reset=1 in   0.3%   (1 in 257)
  with dist on es_reset  es_reset=1 in  51.7%
```

- Verilator 5.052 **accepts `solve ... before` and does not honour it**: it leaves
  the field pinned at 0, which is worse than ignoring it. Repro in
  `code/verilator/repro-solve-before.sv`
- The portable workaround: ask for the spread of the control field with a `dist`.
  It says the same thing and it does not depend on the solver getting the order
  right

Note:
It is the second Verilator hole of the course, alongside the transition bins, and
it gets treated the same way: it gets said head on, with a minimal repro and with
a workaround that works. The concept belongs to the language, not to the simulator.
What does have to be stressed is the asymmetry: the **biased** constraint gives
0.3 %, which is exactly what the theory predicts — which means the Verilator
solver is fine; what is missing is the ordering directive.
And the general moral, which holds for any tool: if the stimulus has a control
field (a mode, a kind of operation, an "inject an error"), do not trust it to come
out even. Measure it.

---

## Constrained random

#### *When there is no solution*

```sv
 class comando;
 rand byte unsigned A;
 constraint chico {A < 8'h10;}
 constraint grande {A > 8'hF0;} // contradicts the previous one: no solution
 endclass

initial begin
      comando c;
      c = new();

// 1. Both constraints active: there is no A that satisfies the two.
      if (!c.randomize()) $display("1. randomize() returned 0: the constraints do not close");
      else $display("1. randomize() gave %2h  (should not get here)", c.A);

// 2. constraint_mode(0) turns a constraint off at run time.
      c.grande.constraint_mode(0);
      if (!c.randomize()) $display("2. randomize() returned 0  (should not get here)");
      else $display("2. with 'grande' turned off: A=%2h, and it honours 'chico'", c.A);

// 3. rand_mode(0) takes the field out of the draw: it keeps its current value.
      c.A.rand_mode(0);
      if (!c.randomize()) $display("3. randomize() returned 0  (should not get here)");
      else $display("3. with A out of the draw: A=%2h, the same as before", c.A);

$finish;
```

```sh
1. randomize() returned 0: the constraints do not close
2. with 'grande' turned off: A=06, and it honours 'chico'
3. with A out of the draw: A=06, the same as before
```

- `constraint_mode(0)` turns **one constraint** off at run time; `rand_mode(0)`
  takes **one field** out of the draw and leaves it with the value it had — and if
  that value does not satisfy the constraints that name it, `randomize()` returns 0
- They are for the test that needs to break a rule on purpose — injecting an
  illegal opcode, for instance — without touching the class everybody else uses

Note:
Here the circle closes with the `assert(randomize())` slide: case 1 is precisely
what happens when two constraints contradict each other, and without the `else`
the testbench goes on sending the previous transaction.
And the pairing with the `soft` slide, worth closing here: a `soft` constraint is
the one the solver drops **on its own** when it gets in the way. `constraint_mode(0)`
is the same thing asked for **by hand and from the outside**, and it is what is left when the
constraint in the way is hard and the class is not yours.

---

## Constrained random

#### *How a constraint that does not close gets debugged*

```systemverilog
// 1. Make the testbench say so. Without this there is no bug: there is silence
if (!t.randomize()) `uvm_fatal("RAND", "the constraint did not close")

// 2. Bisection: turn them off one at a time until it closes. The last one you turned off is it
foreach (nombres[i]) begin
   t.chico.constraint_mode(0);
   if (t.randomize()) `uvm_info("RAND", "it closes without 'chico'", UVM_LOW)
   t.chico.constraint_mode(1);
end

// 3. Take the field out of the draw and see which value was blocking it
t.A.rand_mode(0);
```

- The symptom is never *"it does not close"*: it is a `randomize()` that returns 0 and a
  transaction with **the previous one's values**. First it has to be made noisy
- The method is **bisection**, just like with `git bisect`: `constraint_mode(0)` one
  at a time until it closes. The one you had not turned off yet is the culprit
- The other cut is by field: `rand_mode(0)` leaves the value it had and shows whether
  the conflict was that one
- The cause is almost always the same: a constraint of the **base** class that the
  test's `with {}` contradicts. There the design answer is `soft`

Note:
It is the half hour everybody loses once, and there is a way of losing it
only once. It is worth saying the order out loud because it is the one that works.
Step zero, and the one people skip: **make it noisy**. A `randomize()`
without an `if` does not produce a visible bug, it produces stale stimulus. The course asks for it in
all of `code/` and the traps appendix has it catalogued; here is where it gets collected.
Step one: bisection. A commercial simulator prints the set of conflicting
constraints —Questa says `Constraint solver failed` and lists the blocks—, but
Verilator returns 0 and says nothing, so bisection by hand is the tool
there is. It is boring and takes two minutes, which is exactly why it is worth
having the reflex instead of staring at the code.
Step two, when bisection is not enough: the conflict is not between two
constraints but between a constraint and a field that already has a value. There
`rand_mode(0)` on the suspect freezes it and the message changes.
And the design moral, which is the one that avoids the problem instead of solving it: if
a base class defines hard constraints that a reasonable test is going to want to override,
those constraints should have been `soft`. A hard constraint is a rule of the
DUT, not a preference of whoever wrote the class first.

---

## Constrained random

#### *This is how coverage gets closed*

![The closure cycle: randomize, read the report, fill the missing bin, another seed](../res/diagrams/en/constrained-random_closure.svg)

- No step asks for a new class: `dist` and `inside` in the transaction, three
  lines of `with {}`, and `rand_mode(0)` or `constraint_mode(0)` to break a rule
- That is *coverage closure*, and it is what a verification engineer spends the day on
- What it is **not**: writing one test per bin. Nor looking at the total percentage
- The stimulus still comes out of a `tester` you wrote yourself. In modern UVM
  that is a `uvm_sequence` — and that is day 6

Note:
Close by going back to the conventional testbench: the 86.8 % of `u2/convencional`
comes out of 1000 random operations with the bias to the edges put in by hand. Now
the student knows how to write that same bias in a constraint, measure it, and add
the `with {}` for the cases that are missing.
And leave the day 6 question hanging: if the stimulus is constraints and not code,
what does a `tester` class with a `run_phase` go on existing for? It does not go on
existing. It is called a sequence.

---

## Constrained random

#### *"Another seed, and again": what it moves and what it does not*

```sh
$ SEED=7 bash run.sh    # u6/transactions/constraints, 400 randomizations
    seed: 7
  :/   A=00  25.0%   A=FF  22.0%   # with SEED=8: 20.8% and 27.0%
$ SEED=7 bash run.sh    # u2/convencional, and again with SEED=8
  covergroup : 86.8% (66/76)       # both times. And the merge, the same
```

- `SEED=N` passes `+verilator+seed+N`, and `run_sim` **prints the one it used**: a
  failure that comes up once every ten runs does not get debugged, it gets repeated
- It **does** move the percentages of a `dist` measured with few samples: 400
  randomizations give 25 % or 21 % depending on the draw. It is a sample, not the
  distribution
- It does **not** move the 10 bins that are missing. With 1000 operations the
  random already got as far as it can, and another seed is tossing the coin
  expecting a different result
- That is why *"another seed"* is the **last** step of the previous cycle and not
  the first: the `with {}` comes first

Note:
This slide exists to defuse a misunderstanding the previous cycle invites: *"if I
do not close, I run another seed"*. It was measured, and no: `code/u2/convencional`
gives 66 out of 76 with the default seed, with 7 and with 8, and the merge of the
three gives 66. The 10 that are missing are not missing out of luck — they are
missing because Verilator generates the enum's automatic bins over the **base
type**: `3'b110` does not exist in `operation_t`, so `auto_5` stays at 0 forever,
with its nine crosses. No seed is going to touch them.
The seed is good for two other things, and both are matters of craft. First:
**reproducing**. An intermittent bug does not get debugged, it gets repeated; and
to repeat it you have to know which seed it came up with, which is exactly why
`run_sim` prints it on every run.
Second: **accumulating**, when the stimulus has not saturated yet. A real
regression is the same test over a hundred seeds overnight, and the coverage gets
merged — `verilator_coverage --write` does in Verilator what the ucdb merge does in
Questa. Here it does not show because the example is small; on a chip it is half
the work.
And the `+verilator+rand+reset+2` that shows up in the documentation is something
else and it is worth not mixing them up: it does not touch `randomize()`, it decides
what the **uninitialized** signals of the DUT start with. With `2` they start at
random instead of at zero, which is the way to discover the register nobody reset
and that in silicon does not start at zero.

---

## Constrained random

#### *Summary of the unit*

- The coverage tells you **what is missing**; constrained random is **how to get
  there**. They are the two halves of the same pincer
- Writing a directed test per bin does not scale: there are **76 bins** in the
  VTALU. The recipe is the other way round — **random for the bulk, directed for
  what is left**
- A `constraint` **is not sequential code**: it does not run from top to bottom. It
  is a system of equations the solver resolves all together
- That is why two constraints that contradict each other **do not give a
  compilation error**: they give a `randomize()` that returns 0
- `dist` sets **weights**, not legality. And `:=` is not `:/`: the first weighs
  **each value** of the range, the second **the whole range**
- `randomize()` returns 0 and carries on. That is why it **always** goes inside an
  `if` with `` `uvm_fatal `` — it is the most expensive silent trap of the course

Note:
The last bullet is the one to leave burned in and the one that connects with the
appendix of the traps. An unchecked `randomize()` does not break: it leaves the
fields with the previous value and the testbench goes on sending stimulus that is
not the one you think. The coverage is going to tell you three days later.
And the tool notice that is needed from today: without `z3` installed, Verilator
resolves `randomize()` by returning 0 **in silence**. It is in
`docs/en/verilator.md`, and it is the reason day 5 asks for the solver.

## Review · Day 5

#### *1 of 8 · Deep copy*

**`obj1_h = obj2_h`. What did I copy?**

- [x] Nothing: both handles point at the same object
- [ ] Every field of `obj2_h` into `obj1_h`
- [ ] Only the `rand` fields
- [ ] A shallow copy: the first level is copied and the handles inside get shared

> **Nothing** — there is no copy, there is a second name for the same object. If you modify it through one handle, the other one sees it. Out of that comes the *MOOCOW* rule: if you are going to modify, copy first.

---

## Review · Day 5

#### *2 of 8 · super.do_copy()*

**Why does every `do_copy()` in the hierarchy have to call `super.do_copy()`?**

- [ ] Because UVM demands it in order to register the class
- [ ] So that the object ends up registered in the factory
- [x] Because otherwise the fields of the classes above do not get copied
- [ ] Because `do_copy()` is `pure virtual` and the base class has no implementation

> **Otherwise the fields above get lost** — it is the same problem as `convert2string()`: the day somebody puts a new level in the middle, the method stops seeing half the data and nobody warns you.

---

## Review · Day 5

#### *3 of 8 · clone()*

**`clone()` returns a `uvm_object`. Why is it recommended to also write a `clone_me()`?**

- [x] To wrap the `$cast` in a single place
- [ ] Because `clone()` does not copy the data
- [ ] Because `clone()` is deprecated in IEEE 1800.2 and `copy()` replaces it
- [ ] To be able to clone components as well as transactions

> **So as not to repeat the `$cast`** — without it, every place that clones ends up writing its own cast. It is the same idea as always: if you are going to repeat it, wrap it.

---

## Review · Day 5

#### *4 of 8 · `dist`: `:=` against `:/`*

**`A dist {8'h00 := 1, [8'h01:8'hFE] := 1, 8'hFF := 1};` — how often does `A = 8'h00` come out?**

- [ ] A third of the time: they are three entries with the same weight
- [ ] Half: the edges share it between the two of them
- [ ] Never: `:=` only takes single values, not ranges, and the range is dropped
- [x] Once every 256: with `:=` the weight goes to **each value**

> **1 in 256** — `:=` gives weight 1 to *each one* of the 254 values in the middle, so the range weighs 254 against the 1 and 1 of the edges. To spread the weight *inside* the range you need `:/`. Both spellings compile and run: the difference only shows up in the coverage that does not go up.

---

## Review · Day 5

#### *5 of 8 · `randomize() with {}`*

**`cmd.randomize() with { A == 8'hFF; }` — what happens to the constraints the class already had?**

- [ ] They get replaced: for that call only what is inside the braces counts
- [x] They add up: both have to be satisfied
- [ ] They stay switched off until the next `randomize()` without a `with`
- [ ] It depends on the declaration order: the one lower in the file wins

> **They add up** — the `with {}` adds constraints **for that call only**, and erases nothing. That is why it is the tool for closing a bin without writing a new class: three lines at the point of use, and the rest of the stimulus stays what it always was. And that is also why it clashes with a `dist` that already biases the same field: both have to hold at once.

---

## Review · Day 5

#### *6 of 8 · constraint_mode()*

**`randomize() with { A == 8'hFF; }` on a field the class spreads with a `dist` returns 0 three times out of four. What is the workaround?**

- [ ] Retry in a `do ... while` until it returns 1
- [x] `constraint_mode(0)` on the `dist` constraint, for that object
- [ ] Raise the weight of the `8'hFF` bin in the `dist` of the class
- [ ] `rand_mode(0)` on the field: it takes the `dist` out and lets the `with` rule

> **Switch off the constraint that gets in the way** — Verilator solves the `dist` by **picking a value first** and only then checking the rest, so the probability of success is the probability of the bin: measured, `with {A == 8'hFF}` solves 25 % of the time. `constraint_mode(0)` switches it off for that object alone and touches nobody else. It is exactly the line the `d5c` exercise asks for.

---

## Review · Day 5

#### *7 of 8 · rand_mode()*

**What does `cmd.A.rand_mode(0)` do?**

- [ ] It switches off every constraint that mentions that field
- [ ] It randomizes it once and freezes it afterwards
- [ ] It makes the solver resolve it last, after all the other fields
- [x] It takes the field out of the draw and leaves it the value it had

> **It stops being `rand`** — they are the two run-time knobs and they get mixed up often: `rand_mode(0)` takes **a field** out of the draw, `constraint_mode(0)` switches off **a constraint**. One picks *what gets drawn*, the other *which rules hold*. It is what you use to pin one operand by hand and go on randomizing the rest.

---

## Review · Day 5

#### *8 of 8 · The order of resolution*

**`rand bit es_reset; rand byte unsigned A;` with `constraint c { es_reset -> A == 8'h00; }`. How often does `es_reset = 1` come out?**

- [ ] Half the time: it is a `rand` bit and nothing forbids it
- [ ] Never: the implication forces it to 0
- [x] 1 in 257: the solver draws among the **solutions**
- [ ] It depends on the seed, and over enough runs it averages out to half

> **1 in 257** — the solver picks uniformly among the *solutions*, not among the values of each field: `es_reset=1` leaves a single combination (`A = 00`) and `es_reset=0` leaves 256. The *"any operation after a reset"* bin of the plan does not get filled, and the report does not say why. The answer in the language is `solve es_reset before A`; Verilator accepts it and **does not honour it**, so the portable workaround is to ask for the spread of the control field with a `dist`.

## Exercise · Day 5 · 1 of 3

#### *The scoreboard screams and the DUT is healthy*

`cd code/ejercicios/d5 && bash run.sh`

- The TB of the transactions reports `FAIL` on almost every operation
- The DUT is the same one that has been passing since the spec. The bug belongs to the TB
- The messages that give it away are `UVM_HIGH`: turn the verbosity up
- If you get stuck, the **debug toolbox** appendix has the row for this symptom;
  the **silent traps** one has the cause

Note:
It is the exercise that looks most like a day at work: the scoreboard screams and
you have to decide who to believe.
Let them start without the hint. Almost all of them are going to look at the RTL
first — that is already half the lesson. When they get stuck, the hint is the
verbosity: the `uvm_info` of the monitor are UVM_HIGH and they show what the
monitor says it saw, which does not match what the scoreboard compares.
The bug is a single line of `command_monitor.svh`: the monitor copies one of
the two operands wrong.

## Exercise · Day 5 · 2 of 3

#### *Measure your `dist`*

`cd code/ejercicios/d5b && bash run.sh`

- One class, one `dist` and a histogram. No UVM, no DUT, no testbench
- The weights **already say 10, 80 and 10**. Run it first, and look at what comes out
- What is asked is that the three buckets give 10 / 80 / 10, with ±2 points of tolerance
- The difference between what is there and the solution is **one character**

Note:
It is the short exercise of the course and the one to leave for whoever ran out of
time: it compiles and runs on its own, without UVM.
The point is in the order: it gets run **before** touching anything. The file says
10, 80 and 10, the output says 0.1 % on the edges, and there the question of the
section appears on its own — if the numbers are right, what is wrong? The operator
is wrong, and there is no warning to say so.
It is worth asking them to run it two or three times with different `SEED=` before
calling it closed: with 4000 samples the 10 % bucket moves a good point between
runs, between 9 and 11 — that is why the checker accepts ±2. A measured percentage is a sample, not the distribution — which is the other
half of the rule of the section.
An infrastructure detail worth mentioning if somebody asks why a program with no
DUT takes twenty seconds: Verilator resolves every `randomize()` that has
constraints by calling **z3** from outside, so that is 4000 calls to an external
process. And if they do not have it installed, `randomize()` returns 0 and every
bucket gives zero — another one that does not break, it lies.

## Exercise · Day 5 · 3 of 3

#### *Closing a bin*

`cd code/ejercicios/d5c && bash run.sh`

- The test sends a reset and **60 random operations**, and the report shows the bin
  *"both legs at `FF`, multiplying"* empty
- Write the directed case that closes it. But **ask for it with
  `randomize() with {}`**, not by assigning the fields, which is what this
  section's `tester` does three lines above
- It is graded by comparing the coverage before and after: it has to go up
- It is **row 3** of the verification plan of day 1: the only one of the twelve whose
  stimulus column says *directed case*

Note:
It is the exercise the course was missing, because *coverage closure* shows up twice
as a noun and never as a verb. Here the student does the whole cycle:
run, look at which bin was left empty, write three lines, run again.
The trap is set on purpose and it is the one from constrained random: `command_transaction`
has a `dist` on `A` and on `B`, and Verilator resolves the `dist` by choosing
a value **before** looking at the `with`. With the distribution active, `with {A == 8'hFF}`
resolves one out of every four times and the rest returns 0. Whoever does not read the hint
is going to see an exercise that sometimes passes and sometimes does not — which is exactly the
symptom the section describes.
The workaround is `constraint_mode(0)`, and it is worth defending it as a design decision and
not as a patch for the simulator: a **directed** case does not want a distribution of
probabilities, it wants a value.
The seed of the `run.sh` is fixed. Without fixing it, some runs would fill the
bin on their own with the 60 random ones — and that is the exercise day 7 starts
with.

## Yesterday we left…

#### *Where the testbench stands*

- The data is an **object**: `command_transaction` with `do_copy`, `do_compare`
  and `convert2string`, and the scoreboard compares objects, not fields
- The stimulus is asked for instead of written: `randomize()`, `constraint`,
  `dist`, and the histogram that says whether the distribution does what it
  promises
- And **two** things are left stuck together that do not belong together: the
  `tester` is structure and stimulus at once, and the `env` names the monitor and
  the driver one by one

Note:
The day 6 recap has to name the two separations the unit makes, because there are
two and they get confused: the **agent** separates the structure and the
**sequence** separates the stimulus. Both are the same operation —taking
something out of the component tree— applied to different things.
The third bullet is the one to leave said in the student's own words: today, to
test three stimuli and their combinations, six test classes are needed. That
grows factorially, and it is the reason the unit exists.

---

## Agenda

#### *Day 6 · ≈ 4 h 45 · unit 7 · the reusable testbench*

- Agents
- Callbacks
- Sequences

**By the end of the day you can:**

- **Say** what an agent with `is_active = UVM_PASSIVE` builds and what it does
  **not**
- **Explain** why a `uvm_sequence` does **not** show up in `print_topology()`
- **Remove** the last hard-wired line of a test, with `default_sequence` through
  `uvm_config_db`

Note:
The first two are rows 13 and 14 of the closing self-assessment. The 14th is the
question thrown on day 1, when the UVM class diagram showed up, and it gets
answered today: `uvm_object` is the **data** and `uvm_component` is the
**structure**.
The third one is what closes the unit and the day: when that line goes, no line
of the test names a component from inside the `env`, and only then is the
testbench reusable for one agent. Coordinating two is day 7.

## Agents

#### *The problem: a testbench that cannot be copied*

- The `env` we left in the transactions works, but it is a **welded block**:
  seven components and five `connect()` written by hand
- Every one of those components exists for a single reason: **it drives or
  watches the same interface**, the `vtalu_bfm`
- Ask what happens if the design brings *two* VTALU: you have to copy the seven
  objects, the five connections, and rename everything
- Copying and pasting structure is exactly what we had been avoiding since the `env`
- UVM puts a name on the solution: **`uvm_agent`**

![The env of transactions against the env with an agent](../res/diagrams/en/agents_env_antes_despues.svg)

Note:
The question that orders the whole section: what is the natural unit of reuse
in a testbench? It is not the component, and it is not the env. It is **the interface**.
Everything that knows how to speak one protocol gets packed together, and that box gets
instantiated once for every interface of the design. That is the agent, and it is nothing more.
If the group comes from RTL, the analogy works on its own: the agent is to the testbench what
a parameterizable module is to RTL. Nobody instantiates a FIFO by copying its
registers one at a time.

---

## Agents

#### *What is inside an agent*

- A `uvm_agent` is one more `uvm_component`: same tree, same phases, same
  factory
- What changes is **what it puts inside**, always the same:
  - a *sequencer*, which hands out stimulus
  - a *driver*, which turns it into signals of the BFM
  - the *monitors*, which watch the bus and publish transactions
- And it exposes outwards **two `uvm_analysis_port`**: the one that publishes commands and
  the one that publishes results
- The scoreboard and the coverage **do not go inside**: they are analysis, and they live in the
  `env` hanging off those two ports
- From this section on every piece uses **its** base class: `uvm_driver #(T)`,
  `uvm_sequencer #(T)` and `uvm_monitor` instead of a plain `uvm_component`

![Internal structure of the agent](../res/diagrams/en/agents_agent.svg)

Note:
There is a decision here that is worth saying out loud because the *UVM Primer* takes
it the other way round: it puts the scoreboard and the coverage *inside* the agent. We do not.
The reason is practical: the day you put a passive agent on an interface that
somebody else drives, you do not want a second scoreboard thrown in for free. The agent is
the **protocol** layer; the analysis belongs to the env, which is the one that knows what is being
verified.
The other reason is that if the scoreboard lives inside, the two analysis ports that
the agent exposes have nobody to serve, and half the design ends up decorative.
About the last bullet, because somebody is going to open `code/u7/agents` and see it:
up to the transactions the monitors extended `uvm_component`; from here on they extend
`uvm_monitor`. And `uvm_monitor` **does not add a single line of behaviour** — it is
`uvm_component` under another name. What it adds is intent: anybody who opens
the testbench knows what that class does without reading it, and `print_topology()` shows it
as a monitor.
It is the same economy as `uvm_env`: half the value of UVM is not in the
code of the library, it is in everybody using the same names for the same
things. `uvm_driver` and `uvm_sequencer` do bring things —the `seq_item_port` and the
arbitration—; `uvm_monitor`, `uvm_env` and `uvm_agent` are almost pure vocabulary.

---

## Agents

#### *The jump: from the tester to the sequence*

- In the put and get ports we split the stimulus in two: the `tester` chose **what**
  to send, the `driver` knew **how**
- We joined them with `uvm_put_port` / `uvm_get_port` and a `uvm_tlm_fifo` in the
  middle: three components in the tree and two `connect()`
- UVM already brings that done, and with a name: the **`uvm_sequencer`**
- The `driver` stops being a generic `uvm_component` and becomes
  `uvm_driver #(T)`, which **already comes with a `seq_item_port`**
- And the `tester` disappears: a `uvm_sequence` replaces it, and that **is not a
  component** — it is an object, it is not in the tree and it does not get connected

![From the put/get to the seq_item_port](../res/diagrams/en/agents_seq_item_port.svg)

Note:
This is the hardest jump of the course, and the reason is that there are two changes on
the same line. It is worth separating them.
Change one, structural: the FIFO is called a sequencer and comes with the driver.
Change two, conceptual: the stimulus generator **stops being a component**.
A component is built once in `build_phase` and lives the whole simulation;
a sequence is created, runs, finishes and gets thrown away — and you can run another one
right after on the same sequencer. That is what lets a test
combine stimuli without touching the structure, and that is what the sequences
section is all about.
The question to throw at the group: why does the driver of the passive agent not exist,
but the monitor does? Because driving is optional, watching is not.

---

## Agents

#### *The handshake: `get_next_item()` / `item_done()`*

- The driver no longer does `get()`: it does `get_next_item()`, which **blocks** until
  the sequence has something
- When it has finished driving the signals, it calls `item_done()`
- That second call is what the `put`/`get` pair **did not have**: it is the driver
  saying *"that is it, send me the next one"*
- Without `item_done()` the sequence hangs forever in its `finish_item()`, and
  the simulation stops advancing without a single error message
- The pair always goes complete, and in that order

```sv
   task run_phase(uvm_phase phase);
      command_transaction command;
      forever begin : command_loop
         seq_item_port.get_next_item(command);
         bfm.send_op(command.A, command.B, command.op);
         seq_item_port.item_done();
      end : command_loop
   endtask : run_phase
```

Note:
Forgetting `item_done()` is mistake number one of the first week, and the
symptom is misleading: no error, no warning, the simulation simply
stops advancing in time and the objection never gets dropped. Verilator has no
timeout by default: it keeps spinning until you kill it.
The trick to remember it: `get_next_item` / `item_done` is a **loan**, not
a copy. The sequence lends you the item and waits for you to
give it back. `put`/`get` was a delivery: the tester dropped the command and moved on.
And out of that comes the other useful difference: since the sequence still holds the
handle, the driver can write the result inside it and the sequence reads it when it
comes back from `finish_item()`. The sequences section uses that.

---

## Agents

#### *The driver, now a `uvm_driver`*

- `uvm_driver #(command_transaction)` brings the `seq_item_port` for free: it is not
  declared nor instantiated with `new()`
- The `build_phase` no longer looks for the BFM straight in the `config_db`: it asks the
  **agent config** for it
- The `run_phase` is **three lines**: ask for the item, `bfm.send_op(...)`, say
  it is done. The driver does not touch a wire
- The protocol stays where we left it in interfaces and BFM: **inside the BFM**. That is
  why the driver of an agent is so short, and why changing protocol does not
  touch it

```sv
class driver extends uvm_driver #(command_transaction);
   `uvm_component_utils(driver)

virtual vtalu_bfm bfm;

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

function void build_phase(uvm_phase phase);
      vtalu_agent_config cfg;
      // The BFM is not asked for on its own: ask for the agent config, and it comes from there.
      if (!uvm_config_db#(vtalu_agent_config)::get(this, "", "config", cfg))
         `uvm_fatal("DRIVER", "Failed to get agent config")
      bfm = cfg.bfm;
   endfunction : build_phase

task run_phase(uvm_phase phase);
      command_transaction command;
      forever begin : command_loop
         seq_item_port.get_next_item(command);
         bfm.send_op(command.A, command.B, command.op);
         seq_item_port.item_done();
      end : command_loop
   endtask : run_phase

endclass : driver
```

Note:
It is worth opening the driver of the put and get ports alongside and counting lines: they are almost
the same. The only thing that changed is where the item comes from —before a `uvm_get_port`,
now the `seq_item_port`— and that there is an `item_done()` at the end.
The question worth asking: why is the driver so short? Because the protocol
is not here. It is in the BFM since interfaces and BFM, and this class only translates
*transaction* into *call*. That is the division of labour that makes an AXI
agent have the same twenty-line driver.
And the corollary, which is the one from the bus appendix: when the protocol changes,
the BFM and the monitor change. The driver, the agent, the env and the test never find out.

---

## Agents

#### *The sequencer gets declared with a `typedef`*

- `uvm_sequencer` is a parameterized class: it is parameterized with the type of item
  it is going to hand out
- There is no need to extend it for anything: it is used as is
- A `typedef` in the package gives it a short name, and that name is the one used by
  the agent and the `create()`

```systemverilog
typedef uvm_sequencer #(command_transaction) sequencer;
```

- The `command_transaction` of the transactions already extends `uvm_sequence_item`, so
  **it does not have to be touched**: that is why we chose that base class and not
  `uvm_transaction`
- The `typedef` goes **after** the `` `include `` of the transaction and **before**
  the driver and the agent

Note:
This is the moment when the decision from the transactions gets cashed in. If that day the
transaction had extended `uvm_transaction`, today this `typedef` would not compile:
`uvm_sequencer #(T)` requires that `T` derive from `uvm_sequence_item`.
It is worth saying explicitly: it is the first time in the course that a decision from
an earlier section enables —or breaks— the next one. That is exactly what
"adaptable code" means and it is not a phrase out of a manual.
And in case somebody tries it: extending `uvm_sequencer` to add things to it is
almost always a sign that it belonged in the sequence. The sequencer is an arbiter, not
a place to put logic.

---

## Agents

#### *The minimal sequence*

- A `uvm_sequence #(T)` has a task `body()`: that is all there is to
  write
- Every item goes between `start_item()` and `finish_item()`
- `start_item()` blocks until the sequencer gives us the turn; `finish_item()`
  blocks until the driver called `item_done()`
- The `randomize()` goes **between the two**: that way the constraints get resolved at
  the moment the item is about to be handed over, not before
- This is the direct translation of the `tester` of the transactions, and nothing more than
  that — the sequences section is about what can be done in here

```sv
class command_sequence extends uvm_sequence #(command_transaction);
   `uvm_object_utils(command_sequence)

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

task body();
      command_transaction command;

// All transactions come out of the factory, the directed ones too:
      // a new() would skip add_test's set_type_override.
      command = command_transaction::type_id::create("command");
      start_item(command);
      command.op = rst_op;
      finish_item(command);

repeat (1000) begin : random_loop
         command = command_transaction::type_id::create("command");
         start_item(command);
         // The randomize() goes BETWEEN start_item and finish_item: that way the
         // constraints are solved when the item is about to be handed over, and
         // not before. Today it makes no difference; the day a constraint
         // depends on the DUT state, it will.
         if (!command.randomize()) `uvm_fatal("COMMAND SEQ", "randomize() failed")
         finish_item(command);
      end : random_loop

// Directed: the multiplier overflow, which 1000 random operations might
      // never touch. It comes out of the factory like the others, but since it
      // is not randomized, add_transaction's constraint does not run.
      command = command_transaction::type_id::create("command");
      start_item(command);
      command.op = mul_op;
      command.A  = 8'hFF;
      command.B  = 8'hFF;
      finish_item(command);
   endtask : body
```

Note:
Two things worth marking in the code, because they are the ones that get copied wrong.
First: the transaction comes out of `type_id::create()`, the reset one and the
directed multiplication one too. It is the same rule as the transactions —the factory
only finds out about what goes through `create()`— and here it matters again because the
`add_test` is still around.
Second: `randomize()` between `start_item` and `finish_item` is not a whim of
style. Randomizing before works just the same today, but it breaks the day a constraint
depends on the state of the DUT or on the previous response: by then the value
had already been chosen. Randomizing late is the correct habit and it costs nothing
to adopt it from day one.

---

## Agents

#### *`is_active`: active and passive*

- `uvm_agent` brings a field `is_active` of type `uvm_active_passive_enum`, with
  two values: `UVM_ACTIVE` and `UVM_PASSIVE`
- **Active**: the sequencer and the driver get built. The agent drives the
  interface
- **Passive**: they do not get built. The agent **only watches** an interface that somebody
  else drives
- The monitors and the two analysis ports get built **always**: a passive
  agent keeps feeding scoreboard and coverage
- It is read with `get_is_active()` and decided in the `build_phase`, with an `if`

![Active against passive](../res/diagrams/en/agents_active_passive.svg)

Note:
The honest question is "and what do I want an agent that drives nothing for?". Three
answers from the field, in order of frequency:
One, output interfaces. A port the DUT drives and you only verify does not
need a driver, and the passive agent gives you the monitor and the coverage for free.
Two, integration. When the block you verified becomes part of a
chip, the interface stops being yours: the block next door drives it. The same
agent, with one different line in the config, still works. That is the real
return on having built an agent.
Three, the one from the example: living with stimulus that is not yours — a legacy module,
a reference model, a generator from another team.

---

## Agents

#### *And it can be seen*

- `bash run.sh +TOPOLOGY` prints the tree of components UVM built

```
      clase_agent_h          vtalu_agent
        command_ap           uvm_analysis_port
        command_monitor_h    command_monitor
        driver_h             driver
          seq_item_port      uvm_seq_item_pull_port
        result_ap            uvm_analysis_port
        result_monitor_h     result_monitor
        sequencer_h          uvm_sequencer
          seq_item_export    uvm_seq_item_pull_imp
      modulo_agent_h         vtalu_agent
        command_ap           uvm_analysis_port
        command_monitor_h    command_monitor
        result_ap            uvm_analysis_port
        result_monitor_h     result_monitor
```

- Same class, two instances, and one has four components fewer
- There too are the `seq_item_port` and the `seq_item_export` that the driver and the
  sequencer bring already fitted, without anybody declaring them — against the put and get ports,
  where the `uvm_put_port` had to be declared and `new()`ed
- `print_topology()` is besides the debug tool for when a `connect()`
  points at a component that does not exist

Note:
This tree is printed by the library, not by the course, and that is the whole point: up to here
the hierarchy was a diagram on a slide, and now it is an output you can
grep. It is worth running it live — it is the `print_topology()` of the reporting
section, now with something worth looking at.
The two things to make them see, side by side: `clase_agent_h`
has `driver_h` and `sequencer_h`, and `modulo_agent_h` does **not**. That is
`is_active` in practice — the same class type, instantiated twice, and one
built two objects fewer. Both monitors are in both, because watching
is never optional.
And the one that is not there: there is no `sequence` in this tree. A sequence is a
`uvm_object`, not a `uvm_component`, so it does not live in the topology. It is the
question thrown out on day 1 with the class diagram, and here it can be answered
pointing at the screen.

---

## Agents

#### *The config object of the agent*

- The agent needs two pieces of data from outside: **which BFM** and **whether it is active**
- Both travel together in a configuration object, which is the public interface
  of the agent
- It is a **bare class**, not a `uvm_object`: that is why the constructor can
  **demand** both pieces of data, and whoever forgets one does not compile
- A `uvm_object` is created with `type_id::create()`, which only takes a `name`: the
  guarantee of the constructor is lost
- The field `is_active` goes `protected` with a getter: nobody changes it after
  the agent has been built

```sv
// The agent config is NOT a uvm_object: it is a plain class. That is why the
// constructor can DEMAND both values, and whoever forgets one does not compile.
// A uvm_object is built with type_id::create(), which only takes a name, and
// that guarantee is lost.
class vtalu_agent_config;

virtual vtalu_bfm bfm;

// protected + getter: nobody changes it after the agent was built.
   protected uvm_active_passive_enum is_active;

function new(virtual vtalu_bfm bfm, uvm_active_passive_enum is_active);
      this.bfm = bfm;
      this.is_active = is_active;
   endfunction : new

function uvm_active_passive_enum get_is_active();
      return is_active;
   endfunction : get_is_active

endclass : vtalu_agent_config
```

Note:
Here the course departs from the custom of the industry on purpose, and it is worth
saying so: most projects do `class agent_config extends uvm_object`
and register it in the factory, so it can be overridden. It is a legitimate decision and
it has its reason. The downside is the one in the bullet: you lose the constructor
that forces you.
What is not negotiable is the underlying idea, and it is the one to leave behind: **every
level of hierarchy receives its configuration through an object**. If a component
needs five pieces of data, that is not five `uvm_config_db::get()` scattered around: it is
a config. The day you add the sixth piece of data, you touch one class and not six.
Notice that the driver and the two monitors also ask for the config, not the BFM: the
agent does not hand out handles by hand.

---

## Agents

#### *The agent class: `build_phase`*

- It asks the `uvm_config_db` for its config and copies the `is_active` **by hand**:
  without `super.build_phase()`, `uvm_agent`'s, the one that would read it, never runs
- It builds sequencer and driver **only if it is active**; the monitors and the two
  analysis ports, always
- The analysis ports are ports: they get instantiated with `new()`, not with the factory

```sv
class vtalu_agent extends uvm_agent;
   `uvm_component_utils(vtalu_agent)

vtalu_agent_config cfg;

sequencer       sequencer_h;
   driver          driver_h;
   command_monitor command_monitor_h;
   result_monitor  result_monitor_h;

uvm_analysis_port #(command_transaction) command_ap;
   uvm_analysis_port #(result_transaction)  result_ap;

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

function void build_phase(uvm_phase phase);
      if (!uvm_config_db#(vtalu_agent_config)::get(this, "", "config", cfg))
         `uvm_fatal("AGENT", "Failed to get agent config")
      is_active = cfg.get_is_active();

if (get_is_active() == UVM_ACTIVE) begin : estimulo
         sequencer_h = sequencer::type_id::create("sequencer_h", this);
         driver_h    = driver::type_id::create("driver_h", this);
      end : estimulo

command_monitor_h = command_monitor::type_id::create("command_monitor_h", this);
      result_monitor_h  = result_monitor::type_id::create("result_monitor_h", this);

command_ap = new("command_ap", this);
      result_ap  = new("result_ap", this);
   endfunction : build_phase
```

Note:
A detail worth gold that nobody tells: the `build_phase` of `uvm_agent` that
the library brings **only reads `is_active` from the resource pool**. It is in
`code/.uvm/src/comps/uvm_agent.svh`, it can be opened in class.
Which means that in a testbench that calls `super.build_phase()`, a
`uvm_config_db#(int)::set(this, "mi_agent", "is_active", UVM_PASSIVE)` works
on its own, without a config object. Since this `vtalu_agent` does not call it,
that mechanism **is switched off**, and that is why we assign it by hand.
And here is where day 3 gets paid: `uvm_agent` and `uvm_sequencer` are the two
classes in the library that do real work in their `build_phase` —`uvm_agent` reads
`is_active`, and `uvm_sequencer_param_base` hooks up the response fifo
(`seq/uvm_sequencer_param_base.svh:288`)—. It is exactly the case the rule for out
there covers: if you extend either of the two and you write a `build_phase`, the
`super` is mandatory. You inherited from an intermediate class that does real
work, and skipping the `super` switches it off without a word. We can
skip it because we wrote the line that replaces it; whoever does not write that
line, cannot.
Both ways are valid. What is not valid is half of each one: putting
`is_active` in the config_db, not calling `super.build_phase()`, and then
wondering why the agent starts up active. It happens often.

---

## Agents

#### *The agent class: `connect_phase`*

- Inside: the `seq_item_port` of the driver against the `seq_item_export` of the
  sequencer — **a single line**, and only if it is active
- Outwards: the `ap` of each monitor gets connected to the analysis port **of the
  agent**
- That second `connect()` is the one that makes the agent a closed box: the
  `env` never touches `command_monitor_h`, it talks to `command_ap`
- The mantra *ports connect to exports* still holds, with one more twist: a
  port also connects **to another port of the same type, outwards**. That is
  `command_monitor_h.ap.connect(command_ap)`, and it is called *port forwarding*

Note:
*Port forwarding* is what confuses, and it is worth saying why it exists before
how it is written. The agent wants to offer outwards a piece of data produced by a child
of its own. It could expose the child —the `env` looking at `agent.command_monitor_h.ap`— and
that is where the encapsulation ends: the day the monitor changes name, the
`env` breaks.
The way out is for the agent to have **its own** analysis port and plug it into the
monitor's. From outside a single port is seen, `command_ap`, and inside there can be
whatever. It is exactly what a module does when it connects a port of its own to that of
a submodule — the same idea, with classes.
The detail that looks like it breaks the mantra: here a **port connects to another port**, not
to an export. It is not a capricious exception — the direction is still the same,
from the one who calls to the one who implements; the only thing that happens is that the agent is in
the middle and implements nothing, it only forwards.

---

## Agents

#### *How the `env` ends up*

- Four lines of structure instead of seven objects and five connections
- The `env` no longer knows there is a driver, or a sequencer, or a FIFO: it knows
  there is an agent and that it has two analysis ports
- The scoreboard and the coverage stay just as in the analysis ports: they are
  subscribers, and they find out about nothing

```sv
class env extends uvm_env;
   `uvm_component_utils(env)

vtalu_agent        agent_h;
   vtalu_agent_config agent_cfg_h;

scoreboard scoreboard_h;
   coverage   coverage_h;

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

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

if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "bfm", bfm))
         `uvm_fatal("ENV", "Failed to get BFM")

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

agent_h      = vtalu_agent::type_id::create("agent_h", this);
      scoreboard_h = scoreboard::type_id::create("scoreboard_h", this);
      coverage_h   = coverage::type_id::create("coverage_h", this);
   endfunction : build_phase

function void connect_phase(uvm_phase phase);
      agent_h.command_ap.connect(scoreboard_h.cmd_f.analysis_export);
      agent_h.command_ap.connect(coverage_h.analysis_export);
      agent_h.result_ap.connect(scoreboard_h.analysis_export);
   endfunction : connect_phase
```

- That is the `env` of a single VTALU. With two, it changes less than it looks

Note:
This is the slide for making the comparison live: open the `env.svh` of transactions
alongside. The difference is not that it is shorter —which it also is—, it is **what
disappeared**: the `env` of transactions named `command_f`, which means it knew the
internal mechanism of how the stimulus reached the driver. This one does not name
it. That is encapsulation measured objectively: count the names that
the class above has to know.
If the group is doing well on time, the question is worth it: what would have to
change in this `env` to go from a FIFO to a sequencer? Nothing. It is already
inside the agent.

---

## Agents

#### *Two agents, one single string*

- The two agents execute **the same line**:
  `uvm_config_db#(vtalu_agent_config)::get(this, "", "config", cfg)`
- And yet they have to receive **different objects**
- The second argument of the `set()` resolves it: the **scope**, which is the path
  of the component that is going to read
- `"clase_agent_h*"` reaches that agent and everything hanging off it — that is why
  the driver and the monitors find the same config without anybody passing it to them
- The `this` of the `set()` is the starting point of that path: the `env`

![The hierarchical scope of the config_db](../res/diagrams/en/agents_config_scope.svg)

Note:
Here is the classic trap of the section, and it is one of the ones that never fail. With a single
agent, everybody writes `"*"` in the scope and it works. The day the
second one shows up, the second `set()` overwrites the first and **both agents get the
same config**: the same BFM and the same `is_active`. With the order in `env.svh` —the
class first and the module after— the one left standing is the passive one, so both
start up passive, with no driver and no sequencer, and the test's `seq.start()` lands
on a `null` handle. With the order reversed they would be two drivers, but driving
**the same** interface. What is invariant, and what to take away: the last `set()`
wins, and both agents end up identical. The error does not show up in `build_phase`.
The asterisk matters: `"clase_agent_h*"` with an asterisk reaches the children;
`"clase_agent_h"` without an asterisk, only the agent. If you write it without an asterisk, the
agent finds its config and the driver does not — `uvm_fatal` in `build_phase`, which at
least is an honest error.
Short rule to take away: **the scope of the `set()` is a path, not a label.**

---

## Agents

#### *When the `config_db` does not find: `+UVM_CONFIG_DB_TRACE`*

```sh
$ bash run.sh +UVM_CONFIG_DB_TRACE
UVM_INFO ... Configuration 'config' (type vtalu_agent_config) set by env_h
UVM_INFO ... Configuration 'config' read by
             accessor=uvm_test_top.env_h.clase_agent_h.driver_h
UVM_INFO ... Configuration 'config' read by
             accessor=uvm_test_top.env_h.modulo_agent_h.command_monitor_h
```

- The `config_db` is a database by strings: when it fails, **it fails in
  silence** or with a `uvm_fatal` that does not say why
- `+UVM_CONFIG_DB_TRACE` makes UVM print **every `set()` and every `get()`**,
  with the complete hierarchical path of the component that asked for it
- It works for the two questions one asks: *did the `set()` reach this
  component?* and *which components actually exist?*
- It is a plusarg, not code: nothing has to be touched or recompiled

Note:
This is the tool that tests was missing, when we said that
`get(null, "*", ...)` "does not fail: it lies". With the trace on, lying becomes
difficult: you see who put what and who read it.
The use almost nobody discovers on their own is the second one: **since every `get()` prints the
path of the component that called it, the output is a census of the tree written by the
library.** If a component does not show up, it was not built. The exercise of the day
uses exactly that to grade itself, and that is why it cannot be cheated: the
student does not write those lines.
A close relative worth naming: `+UVM_OBJECTION_TRACE`, for the other classic
hang —the simulation that does not finish because somebody did not drop their objection—.

---

## Agents

#### *The example: two VTALU and the legacy module*

- The case that justifies all of this: two **sources of stimulus** have to be compared
  on the same design
- The `top` instantiates two VTALU and two `vtalu_bfm`
- The first one is driven by our agent, in `UVM_ACTIVE`
- The second one is driven by `vtalu_tester_module`, an ordinary module without one line
  of UVM, and we hang an agent on it in `UVM_PASSIVE` to watch it
- Two scoreboards and **two coverages**: that is what answers which of the two
  stimuli covers more

```sv
module top;
   import uvm_pkg::*;
   import vtalu_pkg::*;
   `include "vtalu_macros.svh"
   `include "uvm_macros.svh"

// The VTALU driven by the class testbench
   vtalu_bfm clase_bfm ();
   vtalu clase_dut (
       .A(clase_bfm.A), .B(clase_bfm.B), .op(clase_bfm.op_set),
       .clk(clase_bfm.clk), .reset_n(clase_bfm.reset_n), .start(clase_bfm.start),
       .done(clase_bfm.done),
       .ovf(clase_bfm.ovf), .result(clase_bfm.result)
   );

// The VTALU driven by the legacy module
   vtalu_bfm modulo_bfm ();
   vtalu modulo_dut (
       .A(modulo_bfm.A), .B(modulo_bfm.B), .op(modulo_bfm.op_set),
       .clk(modulo_bfm.clk), .reset_n(modulo_bfm.reset_n), .start(modulo_bfm.start),
       .done(modulo_bfm.done),
       .ovf(modulo_bfm.ovf), .result(modulo_bfm.result)
   );

vtalu_tester_module stim_module (modulo_bfm);

initial begin
      // The top knows nothing about agents: it leaves the two interfaces with a
      // name and walks away. Handing them out is the test's job.
      uvm_config_db#(virtual vtalu_bfm)::set(null, "*", "clase_bfm", clase_bfm);
      uvm_config_db#(virtual vtalu_bfm)::set(null, "*", "modulo_bfm", modulo_bfm);
      run_test();
   end

endmodule : top
```

- The module calls **the very same `bfm.send_op()`** as the driver: it receives the
  interface through its **port** instead of through a virtual interface, but the
  protocol it executes is exactly the same code
- That is what makes the comparison fair: both stimuli speak identically to
  the DUT. The only thing being compared is **what** each one sends, not how

Note:
This `top.sv` is the one that closes the argument of the section, and it is worth reading
looking for what did **not** change: there are two VTALU, two interfaces, two different
`config_db`, and the `vtalu_tester_module` is still the same old Verilog module
as always. Nobody touched it so it could live with UVM.
That is the real scenario the section comes to solve, and it is worth naming it like this:
you arrive at a project where there is already a stimulus written in Verilog that works and
nobody is going to rewrite. With a passive agent you can **watch** it —scoreboard,
coverage, assertions— without asking anybody's permission or touching a line of it.
The technical detail that makes the comparison fair, and that has to be pointed at with a
finger: the module calls the same `bfm.send_op()` as the driver. It receives the
interface through a port instead of through a virtual interface, but the protocol is the
same code. If each one drove the bus its own way, comparing coverages would
not mean anything.

---

## Agents

#### *The test, and what is still missing*

- The `test` takes the two BFM out of the `config_db`, builds the `env_config` and passes it down
- Then it starts the sequence **by hand**, on the sequencer of the active agent:

```systemverilog
seq = command_sequence::type_id::create("seq");
seq.start(env_h.clase_agent_h.sequencer_h);
```

- It works, but look at what that line does: the test **goes across the hierarchy**
  to reach the sequencer, and with that it knows the inside of the env again
- Everything we have just encapsulated leaks out in one line
- The sequences section fixes it: the sequence is handed to the sequencer **through the
  `config_db`**, and the test stops knowing where it is

```sv
   function void build_phase(uvm_phase phase);
      virtual vtalu_bfm clase_bfm, modulo_bfm;
      env_config env_config_h;

// The top left the two interfaces loose; the test packs them up.
      if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "clase_bfm", clase_bfm))
         `uvm_fatal("DUAL TEST", "Failed to get clase_bfm")
      if (!uvm_config_db#(virtual vtalu_bfm)::get(this, "", "modulo_bfm", modulo_bfm))
         `uvm_fatal("DUAL TEST", "Failed to get modulo_bfm")

env_config_h = new(.clase_bfm(clase_bfm), .modulo_bfm(modulo_bfm));
      uvm_config_db#(env_config)::set(this, "env_h*", "config", env_config_h);

env_h = env::type_id::create("env_h", this);
   endfunction : build_phase

// +TOPOLOGY prints the component tree. It is how to SEE that the passive
   // agent built neither a sequencer nor a driver.
   function void end_of_elaboration_phase(uvm_phase phase);
      if ($test$plusargs("TOPOLOGY")) uvm_root::get().print_topology();
   endfunction : end_of_elaboration_phase

task run_phase(uvm_phase phase);
      command_sequence seq;

phase.raise_objection(this);

// The only thing left wired by hand: the test reaches across the
      // hierarchy to get to the sequencer. The sequences section takes it out of here.
      seq = command_sequence::type_id::create("seq");
      seq.start(env_h.clase_agent_h.sequencer_h);

#500;
      phase.drop_objection(this);
   endtask : run_phase
```

Note:
This is the slide to close the day with if there is no time for the
summary: it leaves an open question and a concrete promise.
And it is honest: `seq.start(env_h.clase_agent_h.sequencer_h)` is real code that
works and that is seen in many testbenches. It is not "wrong". It is simply the
last thing in the testbench that is still hard-wired, and it is the one the section
that follows knocks over.
If somebody asks why we do not do it right from the start: because to understand the
`default_sequence` you first have to have suffered writing the `start()` by hand.

---

## Agents

#### *What this section does differently*

- **The book does not use a sequencer here.** In *The UVM Primer* the agent of this
  section still has the `tester` and the `uvm_tlm_fifo` inside, and the sequencer
  only shows up with sequences — where besides the `tester` disappears
- We build the agent **complete in one go**: it is the way it is written
  today, and it makes the sequences section be only about sequences
- **The scoreboard and the coverage stay outside the agent**, against what
  the *UVM Primer* does. A passive agent should not drag a scoreboard along
- **The config of the agent is not a `uvm_object`**: it is a bare class, so that
  the constructor forces you. The industry usually makes it a `uvm_object`
- The protocol lives in the BFM, the same as in the *UVM Primer*. Up to Verilator 5.051 this
  could not be done: an interface task called through a virtual interface did not
  propagate. It was fixed in 5.052 — `docs/en/verilator.md`

Note:
That the material says where it departs from its sources is not a detail of
tidiness: it is what lets the student read the *UVM Primer* afterwards without
believing that one of the two is broken.
And along the way it leaves the lesson most used at work: the structure of a
UVM testbench is not fixed by the standard, it is fixed by custom. IEEE 1800.2 does not say
anywhere that the scoreboard goes in the env. It says what a `uvm_agent` is and
nothing else. Everything else is convention — good, but convention.

---

## Agents

#### *Summary of the unit*

- An **agent** packs everything that knows how to speak one interface: sequencer,
  driver and monitors, wired inside a single time
- It gets instantiated **once per interface**, and it is configured with a **configuration
  object**, not with loose handles
- **`is_active`** decides whether, besides watching, it drives
- The `env` went from seven components wired by hand to **one agent and two
  subscribers**
- The `uvm_config_db` stops being a global mailbox: the **scope** is a path in
  the tree, and with more than one agent it is what makes each one receive its own
- One single thing was left hard-wired: the test still looks for the sequencer by hand to
  start the sequence. **That is the sequences section**

Note:
Close of the section and of the biggest jump of the course. It is worth saying where they ended up
standing: with today's material, the student can read the testbench of any
UVM project and recognise the structure. An agent per interface, a config per level, analysis
in the env. It is literally 80 % of what they will see on their first day.
What is missing —sequences— is what they will *write* on their first day. That is why they go
together on the same day and in this order: first the house, then what happens
inside.

## Callbacks

#### *The third hook*

- On day 1 we promised **three** ways of writing a new test without touching the env:
  **constraints**, **factory override** and **callbacks**. Two are done
- The three are the same idea at different heights: the constraint changes **values**,
  the override changes **a whole class**, the callback changes **what a class
  does at one point**
- The case that separates them: you are handed a VIP agent —from another team, or bought— and
  you need the driver to send a broken piece of data **once in a while**
- With an override you have to rewrite the whole driver to change one line. With
  a callback you hook that line and nothing else
- And there is a difference that is not a matter of style: **callbacks stack**. The
  override picks *one* class; the callbacks all run, **every one of them**, in order

Note:
This half section exists because unit 1 promises three hooks, and without it the
course delivers two. Fifteen minutes are enough: the mechanics are small and what has to be
left behind is the criterion for when it gets used.
The criterion, said in one line: **override when the what changes, callback
when the when changes**. If the new class differs from the old one in several
methods, it is an override. If it is the same class with an addition at one point, it is a
callback — and above all if the original class is not yours and you cannot touch it.
The key word in all of this is **VIP**. In a real project half of the
agents come from outside, with their licence and their support, and editing them is not an
option: the next version wipes your change. The callback is the extension
point the one who wrote the VIP left on purpose.
And that they stack is what makes it possible for two engineers to hook different
things into the same driver without stepping on each other. With overrides, the second one wins.

---

## Callbacks

#### *The hook: one class, one empty virtual method*

```sv
class driver_callback extends uvm_callback;
   `uvm_object_utils(driver_callback)

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

// A task, not a function: a callback that only edits the transaction could
   // be a function, but one that adds delay needs to consume time. Making the
   // hook a task costs nothing and leaves both open.
   virtual task pre_send(driver drv, command_transaction cmd);
   endtask : pre_send

endclass : driver_callback
```

- A `uvm_callback` **is not a component**: it is not in the tree, it has no phases and
  it does not show up in `print_topology()` — just like a sequence
- The base method is **empty on purpose**: with nobody registered, the testbench
  runs exactly as before
- It is a `task` and not a `function` because a *delay* callback has to be able
  to consume time. One that only edits the transaction could be a function

Note:
It is worth stopping on the fact that it is a normal class, extending `uvm_callback`, which
extends `uvm_object`. There is no magic: the only thing `uvm_callback` does is give it
a place in the pool UVM keeps per component instance.
The `typedef class driver;` at the top of the file is the boring and
necessary part: the callback receives the driver, and the driver registers the callback, so
one of the two has to be forward-declared. In a real testbench
this lives in its own file for that very reason.
If somebody asks why the base method is empty instead of abstract:
because `uvm_do_callbacks` walks **the whole queue**, and an empty queue has to
be legal. The empty base class is what makes "no callbacks" the normal case
and not an exception.

---

## Callbacks

#### *Two lines in the driver, and not one more*

```sv
class driver extends uvm_driver #(command_transaction);
   `uvm_component_utils(driver)
   // Declares "this component accepts callbacks of this type". Without it the
   // add() below still hooks up and the callback still runs, but with a CBUNREG
   // warning and without the type check: outside the contract, and nearly silent.
   `uvm_register_cb(driver, driver_callback)

virtual vtalu_bfm bfm;
```

```sv
   task run_phase(uvm_phase phase);
      command_transaction command;
      forever begin : command_loop
         seq_item_port.get_next_item(command);
         // Every callback registered on this driver, in the order they were
         // added. With none registered this is a loop over an empty queue.
         `uvm_do_callbacks(driver, driver_callback, pre_send(this, command))
         bfm.send_op(command.A, command.B, command.op);
         seq_item_port.item_done();
      end : command_loop
   endtask : run_phase
```

- `` `uvm_register_cb `` declares the type/callback pair. Without it the `add()`
  hooks up all the same and the callback **runs** — with a `UVM_WARNING CBUNREG`
  lost in the log, and without the type check or `add_by_name`
- `` `uvm_do_callbacks `` is the extension point: it walks the queue of **that
  instance** of driver, in order

Note:
The diff against the driver of the Agents section is exactly two lines, and
it is worth showing it with a live `diff`: `diff code/u7/agents/tb_classes/driver.svh
code/u7/callbacks/tb_classes/driver.svh`. Everything else —the `get_next_item`, the
`send_op`, the `item_done`— is the same.
The failure mode of the missing `uvm_register_cb` is not the one you expect, and it
is worth telling it with the source in hand because half the tutorials get it
backwards: `uvm_callback.svh:745` reports a `UVM_WARNING CBUNREG` and **carries
on** — the `add()` puts the callback into `m_base_inst.m_pool` all the same
(`:781-785`), and `` `uvm_do_callbacks `` reads that pool without consulting the
registry (`:964-1006`). Which means: without the macro the callback runs, and what
you lose is the type check and `add_by_name` by derived type. That is worse than an
error: it is a warning among a thousand lines, and the testbench ends up outside
the contract without anyone noticing.
That is why the `run.sh` of the example does not check the macro but the effect: it
counts how many times the callback ran and fails if it is zero. An example that
"passes" without having injected anything proves nothing, whatever the reason it
came unhooked.
Where to put the `` `uvm_do_callbacks `` is the real design decision, and it is the
same one taken by whoever writes a VIP: every hook point is a promise of
forward compatibility. That is why VIPs have three or four, not thirty.

---

## Callbacks

#### *Putting them in: the test, and nothing but the test*

```sv
   // end_of_elaboration and not build: the driver is a grandchild of the env,
   // and build_phase runs top-down -- when this test's build_phase returns, the
   // driver does not exist yet.
   function void end_of_elaboration_phase(uvm_phase phase);
      super.end_of_elaboration_phase(phase);

flip_h   = flip_bit_cb::type_id::create("flip_h");
      jitter_h = jitter_cb::type_id::create("jitter_h");

// Both on the same driver, and both run: the queue is per component
      // instance, in insertion order. The passive agent has no driver, so there
      // is nothing to hook there.
      uvm_callbacks #(driver, driver_callback)::add(env_h.clase_agent_h.driver_h, jitter_h);
      uvm_callbacks #(driver, driver_callback)::add(env_h.clase_agent_h.driver_h, flip_h);

if ($test$plusargs("CALLBACK_TRACE"))
         uvm_callbacks #(driver, driver_callback)::display(env_h.clase_agent_h.driver_h);
   endfunction : end_of_elaboration_phase
```

- The test **does not touch** the env, nor the agent, nor the driver, nor the sequence. Just
  like the override, one level further down
- `end_of_elaboration_phase` and not `build_phase`: the driver is a grandchild of the env, and
  when the `build_phase` of the test finishes **it does not exist yet**
- The two callbacks go on the **same** instance and **both** run, in the
  order in which they were added

`bash run.sh +CALLBACK_TRACE` prints the queue of the driver

Note:
The phase trap is the one that takes somebody's whole afternoon: `uvm_callbacks::add`
needs the handle of the component, and the tree is built top
down. In the `build_phase` of the test, `env_h` exists —it has just created it— but
`env_h.clase_agent_h` is `null`. `end_of_elaboration_phase` runs with the whole tree
assembled, which is exactly what is needed.
The alternative that is sometimes seen is `add_by_name("*driver_h", cb, this)`, with a
pattern instead of a handle. It is useful when you do not want to go across the hierarchy, and
it has the same phase problem.
And the passive agent does not show up in either of the two lines for a reason that is obvious
once said: it has no driver. Callbacks hang off instances, not off
types, so "the driver of the active agent" is a concrete address in the
tree.

---

## Callbacks

#### *The flipped bit the scoreboard does not see*

`cd code/u7/callbacks && bash run.sh`

- The `flip_bit_cb` flips a bit of `A` in one out of every eight transactions. The
  scoreboard **says nothing**, and both runs close at 0 `UVM_ERROR`
- It is not a hole in the checker: it is the proof that **the monitor watches the
  wire**, not what the driver thought it was going to send
- A monitor that rebuilt the transaction from the driver —or that copied it
  from the sequencer— would have given *PASS* on data the DUT never saw
- What can be seen of the `jitter_cb` is the **time**: same stimulus, more cycles

| The hook | Changes | How many at a time |
| --- | --- | :--: |
| **Constraint** | the values | as many as you like |
| **Factory override** | the whole class | **one** |
| **Callback** | what a class does at one point | as many as you like |

Note:
This is the slide of the half section, and the exercise of thinking is worth more than the
code: *"if I inject an error and the scoreboard does not scream, is the scoreboard wrong?"*
Let the group argue about it for a minute before answering.
The answer is no, and it is one of the most important things in the course: the
scoreboard predicts from what the **monitor** saw on the bus. If the driver
sends `A^1`, the DUT computes with `A^1`, the monitor sees `A^1` and the prediction gives
`A^1`. All consistent. The only testbench this callback would break is
one with a monitor that does not watch the signals — and that testbench was wrong before
the callback ever existed.
Out of that comes the rule we already saw in Agents and that now has a demonstration:
**the monitor watches the wire, always**. An injection callback is, besides a
tool, the cheapest test there is for finding out whether your monitor does it.
To inject an error the scoreboard **does** have to catch, you have to break
the DUT, not the stimulus — which is exactly what the `+BUG=1` of the capstone does.

## Sequences

#### *The only thing left hard-wired*

- The agents left the testbench encapsulated: one `agent` per interface, the
  analysis in the `env`, and nobody naming somebody else's components
- Except for one line, the one in the `run_phase` of the test:

```systemverilog
seq.start(env_h.clase_agent_h.sequencer_h);
```

- The test **goes across the hierarchy** to reach the sequencer, and along the way it gets to know
  the inside of the `env` we have just closed
- And there is something bigger behind it: that `command_sequence` is **one** class doing
  **three** things — resetting, sending a thousand random operations and one directed
- This section is about what happens inside `body()`, and about how a
  sequence gets started without wiring it

Note:
The sentence that orders the whole section: **stimulus is not structure**.
A component is built once, before the simulation starts, and it
stays there until the end. Stimulus changes from test to test, and sometimes it changes
inside the same test. Transactions, agents and sequences are the same operation repeated
on three different things: separating the **data** (transaction), separating the
**structure** (agent), separating the **stimulus** (sequence).
The question to throw at the group before going on: with the `command_sequence` of the
agents, how many classes are needed to try three stimuli and their combinations?
Six, and it grows factorially. In the *UVM Primer* that is called *explosion of tester
classes*.

---

## Sequences

#### *An object, not a component*

![The sequence lives outside the component tree; the sequencer, inside](../res/diagrams/en/sequences_donde_vive.svg)

- The `uvm_sequencer` is a `uvm_component`: **it is in the tree**, it has a parent,
  it has phases, the `build_phase` of the agent builds it
- The `uvm_sequence` is a `uvm_object`: **it is not in the tree**, it has no parent,
  it has no phases, and it gets created with a single argument — just like the transactions
- Practical consequence: it gets created, runs, finishes and is thrown away. You can run another one
  right after, or two at once, without touching the structure

Note:
There is a detail here that confuses and is worth getting ahead of, because they are going to see it in the
log: even though the sequence is not in the tree, UVM reports it **hanging off the
sequencer**, with an `@@` in the middle:
`uvm_test_top.env_h.clase_agent_h.sequencer_h@@full_seq.random_seq`
That does NOT mean it is a child of the sequencer. The `@@` is precisely the mark that
what follows is a sequence and not a component: to the left, the path of the
sequencer it runs on; to the right, the path of nested sequences. If
somebody looks for `sequencer_h.full_seq` with `uvm_root::get().find()` they are never going to
find it.
The other consequence, the one used every day: since it is not a component, a
sequence can have configurable fields that get changed **between** the `create()`
and the `start()`. That is what `full_seq.count = 200` does at the end of the
unit, and with a component it could not be done: by the time you want to change it, the
`build_phase` has already gone by.

---

## Sequences

#### *The smallest sequence there is*

```sv
// The smallest sequence there is: a single item.
//
// It is a uvm_object, not a uvm_component: it is not in the tree, it has no
// parent, it has no phases. It gets created, it runs, and it gets thrown away.
class reset_sequence extends uvm_sequence #(command_transaction);
   // `uvm_object_utils, NOT `uvm_component_utils: the constructor takes a single
   // argument and there is no parent to pass.
   `uvm_object_utils(reset_sequence)

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

// body() is a TASK, not a function: it blocks inside. Nobody calls it by
   // hand; UVM calls it when somebody starts the sequence.
   task body();
      command_transaction command;
      command = command_transaction::type_id::create("command");
      start_item(command);    // blocks until the sequencer gives us our turn
      command.op = rst_op;    // only now do we decide what to send
      finish_item(command);   // blocks until the driver calls item_done()
   endtask : body

endclass : reset_sequence
```

- It extends `uvm_sequence #(T)`, parameterized with the item it is going to send
- It gets registered with `` `uvm_object_utils `` — **not** with `` `uvm_component_utils ``
- Constructor with a single argument: `name`, without `parent`
- All the work lives in `body()`, which is a **task**: it can block
- Nobody calls `body()` by hand: UVM calls it when somebody starts the sequence

Note:
The two typing mistakes everybody makes the first time, and which give
messages that do not help:
1. `` `uvm_component_utils `` instead of `` `uvm_object_utils ``. The error talks about
   a constructor with two arguments and nobody relates it to the macro.
2. `function body()` instead of `task body()`. The declaration compiles, and then
   the `start_item()` inside does not, because a function cannot block.
And a design one worth marking: the `command` is declared **inside**
`body()`, not as a field of the class. In the *UVM Primer* it is a field. If it is a field,
two runs of the same sequence share the handle, and the day somebody
starts the same sequence twice in parallel you have two threads writing the
same object.
And a protocol one, which is what makes this sequence exist: **the first item
of every test is a reset**. The VTALU starts up with `reset_n` at 0 and never raises
`done`; the driver stays in its `while (bfm.done == 0)` and the sequence, in the
first `finish_item()`. There is no error: the simulation stops advancing. It is the same
symptom as the forgotten `item_done()`, with another cause, and it is worth showing it once
in class by deleting the `reset_sequence` from `full_sequence`.

---

## Sequences

#### *The handshake, now from the sequence side*

![Timeline of start_item, get_next_item, item_done and finish_item](../res/diagrams/en/sequences_handshake.svg)

- The same four calls as the agents, looking at the other lane:
  `start_item()` blocks the **sequence** until the sequencer gives it the turn,
  and `finish_item()` blocks it until the `item_done()` of the driver
- Simulation time advances **only** in the amber bar: filling the item does not
  cost a clock edge
- Two threads, four calls and no `#delay` in the middle

Note:
Confusion number one of the section: believing that `finish_item()` comes back when the
item **was delivered**. No: it comes back when the driver called `item_done()`, that is
when the operation **finished in the DUT**. It is the difference between "I sent it" and
"it is done", and it is what makes the Fibonacci sequence possible.
Out of that comes as well why the `#500` that the `tester` of the transactions
had at the end disappeared: it was not stimulus, it was a patch so the objection would not drop
before its time. With `finish_item()` the stimulus no longer gets cut in half. Careful,
honesty: the **last** result can still end up uncompared, because the
objection gets dropped as soon as `start()` comes back and the `result_monitor` publishes one edge
later. It can be seen in the log of the `add_test` run with `+UVM_VERBOSITY=UVM_HIGH`: 1001
commands, 1000 comparisons.
If somebody asks about the non-blocking cousin: there is `try_next_item()`, which
comes back right away with `null` if the sequencer has nothing. It is the same
`get()` / `try_get()` pair from the communication between threads and it is useful when the protocol forces you to drive
the bus even when there is no stimulus — idle cycles, refresh of a DRAM. The VTALU does not
need it: between one operation and the next the signals can stay still.

---

## Sequences

#### *What happens between `start_item()` and `finish_item()`*

```sv
   task body();
      command_transaction command;

repeat (count) begin : random_loop
         // Through the factory, same as in the Transactions section: that is what lets
         // add_test change the TYPE without touching a line of this sequence.
         command = command_transaction::type_id::create("command");

start_item(command);

// Late randomization: the values are picked AFTER getting the
         // sequencer's turn, not when the object was created.
         if (!command.randomize())
            `uvm_fatal("RANDOM SEQUENCE", "randomize() failed")

finish_item(command);
      end : random_loop
   endtask : body
```

- When `start_item()` comes back, the sequence **already has the turn** of the sequencer:
  nobody else is going to beat it to the driver
- Only then do the fields get filled, or the randomize happen. That is **late
  randomization**: the values get chosen at the last possible moment
- It is useful because by then it is already known what state the DUT is in, and a
  constraint can depend on that
- `randomize()` still goes with its `else`: it returns 0 and aborts nothing — it is the
  same thing they saw in the Constrained random unit

Note:
The honest question: "and what if I randomize before `start_item()`?". It works. On a
small testbench you do not notice the difference.
You notice it when the sequence has a thousand items queued up and a constraint depends on
something that changes during the run —an address that has already been written, a buffer
that has filled up, the previous result—. If you randomized everything at the beginning,
you decided with old information.
The other reason, more practical: between `start_item()` and `finish_item()` is where UVM
calls `pre_do()` and `mid_do()`, which are the hooks people use to
inject errors without touching the original sequence. If you fill the item before, those
hooks have nothing to do.
And the hook back to day 5: this is where the `randomize() with {}` of the coverage
closure goes. The directed case gets asked for at the point of use, without writing a new
class. The slide that follows is exactly that, with the Verilator trap included.

---

## Sequences

#### *Directed late randomization, and the Verilator hole*

```systemverilog
start_item(command);
command.data.constraint_mode(0);                       // 1. I switch off the dist
if (!command.randomize() with {A inside {[1:10]};})    // 2. I ask for the directed one
   `uvm_fatal("SEQ", "randomize() failed")
finish_item(command);
```

- Measured with Verilator 5.052, on a class with the constraints of
  `command_transaction`, 100 randomizations of each form:

```sh
with {op == mul_op}                       100 of 100   op has no dist
with {A inside {[1:10]}}                    1 of 100   A does have one
constraint_mode(0) + with {A inside ...}  100 of 100   the workaround
```

- The rule, in one line: **if the `with {}` touches a field that has a `dist`,
  switch that constraint off first**
- It is not the language, it is the tool: `repro-dist-with.sv` in
  `code/verilator/`

Note:
It is the same limitation they already saw in the Constrained random unit, but here
it shows up in the place where they are really going to use it, so it is worth measuring it
again against the real transaction.
What the measurement adds on top of what `docs/en/verilator.md` says: the trigger is
not "there is a `dist` in the class". It is **the `with {}` restricting a field that has a
`dist`**. Asking for `op == mul_op` works perfectly, even though `A` and `B` have `dist` in the
same resolution. That is why the sequences of the section do not run into this: none of them
uses `with {}`.
And the workaround is not a concession: for a directed case, switching off the distribution
constraint is the right thing anyway. The `dist` is there so the random hits the
edges; if you already know which value you want, it has nothing to contribute.
`constraint_mode(0)` is per **object**, not per class, and the object gets thrown away after
`finish_item()`: there is no need to remember to switch it back on.

---

## Sequences

#### *The item comes back with the result inside*

```sv
   task run_phase(uvm_phase phase);
      command_transaction command;
      shortint unsigned   alu_result;
      forever begin : command_loop
         seq_item_port.get_next_item(command);  // blocks until there is an item
         bfm.send_op(command.A, command.B, command.op, alu_result);
         command.result = alu_result;  // the way back
         seq_item_port.item_done();  // unblocks the finish_item()
      end : command_loop
   endtask : run_phase
```

- The driver writes `command.result` **before** calling `item_done()`
- The sequence still holds the handle to that same object: when `finish_item()`
  comes back, the result is there
- It is the way back, and that is why `command_transaction` gains a field `result`
  in this unit — the only change to the transaction since it was created
- It breaks *MOOCOW* on purpose: the driver modifies an object it did not create. It is
  agreed between the two parties, and it is the only place in the testbench where it is done

Note:
This is the subtlest point of the section and it is worth saying it slowly: **there is
no return channel at all**. There is no port, there is no FIFO. There is a shared
handle, and the two parties agreed that the driver writes and the
sequence reads, and that the safe moment to read is after `finish_item()`.
If somebody asks "wasn't the rule to clone?": yes, that is the rule of the transactions, and this is the documented exception. UVM has besides a formal
mechanism for this —the REQ/RSP pair of `uvm_sequence #(REQ, RSP)` with
`put_response()` on the driver side and `get_response()` on the sequence side—
that almost nobody uses, because writing the result into the request is enough in the
vast majority of cases. It is worth naming so they recognise it if they see it.
An implementation detail that does matter: the `send_op` reads `bfm.result` on the
same edge on which it sees `done` high. One edge later the DUT has already started the
next operation.

---

## Sequences

#### *The formal way back: `get_response()`*

```systemverilog
// The sequence declares TWO types, and the response is no longer the request
class fib_sequence extends uvm_sequence #(command_transaction, result_transaction);
   start_item(cmd);
   finish_item(cmd);
   get_response(rsp);              // blocks until the driver answers

// And the driver, on the other side:
   seq_item_port.get_next_item(req);
   rsp = result_transaction::type_id::create("rsp");
   rsp.set_id_info(req);           // without this the response does not find its sequence
   seq_item_port.item_done(rsp);   // or item_done() now and put_response(rsp) later
```

- The shared handle of the previous slide holds as long as the driver is
  **blocking and serves one at a time**. The course's one is
- A *pipelined* driver calls `item_done()` as soon as it pushes the command and the response
  arrives N cycles later: by then the sequence has already sent another item, and
  writing into `req.result` writes **to the wrong item**
- `set_id_info(req)` copies the sequence and transaction id onto the response.
  It is what makes `get_response()` know who to answer
- The other two cases where it is needed: a VIP that **clones** the item, and a
  protocol with **more than one response** per request

Note:
This is the half slide that avoids a poor answer in an interview. The
question sounds like *"how do you give the data back to the sequence?"*, and answering "I
write the `result` field into the item" is right **for this driver** and fails on
any real bus. It is worth saying both halves together.
The reasoning to leave behind: the shared handle trick is not a
technique, it is a consequence of the driver being blocking. The condition is
written in the `get_next_item()`/`item_done()` of the previous slide — as long as the
`item_done()` is **after** having the response, there is a single item in flight and
the handle is enough. The day somebody moves that `item_done()` up to
gain throughput, the testbench keeps compiling and starts lying.
The other failure mode, more treacherous: a VIP that clones the item between the
sequence and the driver. There the driver writes into its copy, the sequence reads the
original, and the result that arrives is always the previous one. There is no error, there is no
warning: there is a scoreboard shifted by one.
And the `set_id_info()` detail, which is the one that makes this fail silently the
first time: if it is missing, the response is sent anyway and `get_response()` waits
forever. A test that "hangs after the first transaction" and uses REQ/RSP is this
bug until proven otherwise.

---

## Sequences

#### *Fibonacci: when the stimulus depends on the result*

```sv
   task body();
      byte unsigned n_menos_2 = 0;
      byte unsigned n_menos_1 = 1;
      command_transaction command;

command = command_transaction::type_id::create("command");
      start_item(command);
      command.op = rst_op;
      finish_item(command);

`uvm_info("FIBONACCI", "Fib(01) = 000", UVM_MEDIUM)
      `uvm_info("FIBONACCI", "Fib(02) = 001", UVM_MEDIUM)

// Up to 14 and no further: Fib(14) = 233 and Fib(15) = 377, which does not
 // fit in the 8 bits of A and B.
 for (int ff = 3; ff <= 14; ff++) begin : fib_loop
 command = command_transaction::type_id::create("command");
 start_item(command);
 command.A = n_menos_2;
 command.B = n_menos_1;
 command.op = add_op;
 finish_item(command); // returns when the driver called item_done()

n_menos_2 = n_menos_1;
         n_menos_1 = command.result;  // the driver wrote it inside the item
         `uvm_info("FIBONACCI", $sformatf("Fib(%02d) = %03d", ff, n_menos_1),
                   UVM_MEDIUM)
      end : fib_loop
   endtask : body
```

- Every addition needs the result of the previous one: without a way back this cannot
  be written
- `finish_item()` comes back **after** the ALU has finished, so
  `command.result` is already valid
- It is the same `env`, the same agent, the same driver and the same BFM as the random
  test. Only the sequence changes

Note:
Fibonacci is not there to teach Fibonacci: it is there to force the case where the
stimulus N+1 depends on the result N. A test like that with the `tester` of the transactions
is impossible without giving the tester a handle to the monitor, that is without breaking
the separation we had been building.
Numbers for the blackboard: 0 1 1 2 3 5 8 13 21 34 55 89 144 233. It stops at 233
because the next one is 377 and `A` and `B` are 8 bits. Having the student see why the
`for` goes up to 14 and not up to 20 is worth more than the whole sequence.
And one that is seen in the real run: the whole test takes **500 units of
time**, against the 43,000 of the random test. Thirteen operations. A well-written directed
test is cheap; what is expensive is the random, and that is why it runs at night.

---

## Sequences

#### *Sequences that call sequences*

![full_sequence starting three sub-sequences on the same sequencer](../res/diagrams/en/sequences_subsequences.svg)

- A sequence can start others: it is the way of composing stimulus without
  duplicating code
- The `command_sequence` of the agents, split into three pieces that now get
  combined however you like
- The sequencer arbitrates: whatever it receives, it hands the driver **one item at a
  time**

Note:
The idea of the slide is that a sequence is not a special layer: it is an object with
a `body()`, and inside a `body()` another sequence can be started just the way
the first one is started. There is no nesting limit nor a different class for
"sequence that calls sequences".
The practical consequence, which is the one that counts: stimulus gets composed like
functions. A small sequence —"write the four registers", "send a maximum
multiplication"— gets written once and afterwards goes into any
scenario. It is exactly what in the conventional testbench was done by copying and
pasting blocks of the tester.
The last bullet is the one that avoids the most common misunderstanding: that three sequences
are composed does **not** mean that their items get mixed on the bus. The
sequencer hands over one at a time, and if two sequences compete on the same
sequencer there is an arbitration policy deciding. With sequences nested
on a single sequencer, the order is the one the `body()` says.

---

## Sequences

#### *`full_sequence`: three pieces, one single sequencer*

```sv
   task body();
      reset_sequence   reset_seq;
      random_sequence  random_seq;
      maxmult_sequence maxmult_seq;

reset_seq   = reset_sequence::type_id::create("reset_seq");
      random_seq  = random_sequence::type_id::create("random_seq");
      maxmult_seq = maxmult_sequence::type_id::create("maxmult_seq");

random_seq.count = count;

// get_sequencer() returns the sequencer start() handed us: the children run
      // on the same one. The second argument declares them CHILDREN -- without it
      // they compete with us in the arbitration instead of inheriting our turn.
      reset_seq.start(get_sequencer(), this);
      random_seq.start(get_sequencer(), this);
      maxmult_seq.start(get_sequencer(), this);
   endtask : body
```

- `get_sequencer()` returns the sequencer that `start()` handed to **this**
  sequence: the daughters run on the same one
- The second argument, `this`, declares them **daughters**. Without it they compete with
  the mother in the arbitration instead of inheriting her turn
- `random_seq.count = count` is the advantage of the sequence being an object: it gets
  configured between the `create()` and the `start()`
- To run two in parallel, `fork` / `join` around the `start()`, and the
  sequencer interleaves the items

Note:
`get_sequencer()` is the accessor of IEEE 1800.2; the field is called `m_sequencer` and
the *UVM Primer* uses it directly. Both forms work — the `get_` one is the one worth
teaching, because `m_` is the UVM convention for "this is internal".
And if somebody has already read production code they are going to ask about `p_sequencer`: it is a
**typed** handle to the sequencer, which shows up when you use
`` `uvm_declare_p_sequencer(mi_sequencer) ``. It is only useful if you extended
`uvm_sequencer` to put something of your own in it, because `m_sequencer` is of type
`uvm_sequencer_base` and does not see those fields. Since in this course the sequencer is a
bare `typedef`, `p_sequencer` contributes nothing.
The second argument of the `start()` is the one almost nobody puts in and that almost always
matters: without a parent, if mother and daughter ask for the turn at the same time the sequencer
treats them as two independent sequences. With a parent, the daughter inherits priority and
context.
If they ask about the order with `fork`/`join`: the default arbitration is
`UVM_SEQ_ARB_FIFO`, that is order of arrival. It gets changed with `set_arbitration()` of the
sequencer, and there are six modes, one of them with weights.

---

## Sequences

#### *Starting a sequence, form 1: `start()`*

```sv
   task run_phase(uvm_phase phase);
      full_sequence full_seq;
      full_seq = full_sequence::type_id::create("full_seq");

// THE TEST raises the objection, not the sequence: the sequence knows
      // nothing about phases, and has to be able to run inside another sequence.
      phase.raise_objection(this);
      full_seq.start(sequencer_h);   // does not return until body() finished
      phase.drop_objection(this);
   endtask : run_phase
```

- `start(sequencer)` hands the sequence the sequencer it is going to run on
  and **does not come back until `body()` has finished**
- The test raises the objection before and drops it after: the run lasts
  exactly as long as the stimulus lasts
- It is explicit and reads top to bottom. For a test that runs a single
  sequence, it is what suits
- And it still has the problem of the first slide: `sequencer_h` came out of
  `env_h.clase_agent_h.sequencer_h`

Note:
`start()` does three things, in this order: it saves the sequencer (it is what
`get_sequencer()` returns afterwards), it calls `pre_body()` / `body()` / `post_body()`, and it
comes back.
The detail to underline: the objection is raised by **the test**, not by the
sequence. The sequence knows nothing about phases. That is on purpose — the same
sequence has to be able to run inside another sequence, where raising an
objection would make no sense, and in fact that is what `full_sequence` does with its
three daughters.
The `sequencer_h` is resolved by `base_test` in `end_of_elaboration_phase`, not in
`build_phase`: during the `build_phase` of the test the agent has not built its
sequencer yet. It is the same reason why the connections go in `connect_phase`.

---

## Sequences

#### *Form 2: `default_sequence` through `uvm_config_db`*

```sv
   function void build_phase(uvm_phase phase);
      full_sequence full_seq;

// super.build_phase() of base_test, which is a class of OURS: it builds the
      // env. What the course never calls is uvm_component's build_phase.
      super.build_phase(phase);

full_seq = full_sequence::type_id::create("full_seq");
      full_seq.count = 200;

// WITHOUT this line main_phase ends at t=0: nobody raises the objection,
      // and a phase without an objection lasts zero. The test PASSES with no stimulus.
      full_seq.set_automatic_phase_objection(1);

// The instance name carries the "_phase" suffix: that is the phase the
      // sequencer will start it in. Notice the test no longer names the sequencer
      // as a handle: it names it as a PATH, and that is a config, not code.
      uvm_config_db#(uvm_sequence_base)::set(
          this, "env_h.clase_agent_h.sequencer_h.main_phase", "default_sequence",
          full_seq);
   endfunction : build_phase
```

- The test **has no `run_phase`**: the sequencer starts the sequence on its own, when
  the phase begins
- The instance name carries the suffix `_phase`: `"...sequencer_h.main_phase"`
  means *"in the `main_phase` of that sequencer"*
- It can be configured per **instance** (as here, with
  `uvm_config_db #(uvm_sequence_base)`) or per **type**
  (`uvm_config_db #(uvm_object_wrapper)` + `get_type()`). If both are there the
  one with the **higher precedence** wins, and at equal precedence the **last
  `set()`**
- The sequencer stopped being a handle and became a **path**: that is already
  configuration, not code

Note:
**The trap, and it is one of the ones that give no warning.** Without the line
`set_automatic_phase_objection(1)`, nobody raises the objection of the `main_phase`.
And a phase without an objection finishes as soon as it starts.
What was tried with Verilator 5.052: the run finishes at **t=0**, prints the Report
Summary with **0 UVM_ERROR / 0 UVM_FATAL**, and exits with code 0. That is: the test
PASSES without having sent a single piece of stimulus. It is in `code/u7/sequences` as
`no_objection_test`, so it can be run in class alongside the good one.
It is exactly the same kind of bug as the `new()` that eats the override of the transactions: it does not break, it **lies**. And in a regression of a thousand tests, a test that passes
in zero seconds is one nobody looks at.
Fine detail: `main_phase` is the one to use, not `run_phase`, but not because
`run_phase` does not work — `uvm_task_phase::traverse` calls
`start_phase_sequence()` on **every** task phase (`base/uvm_task_phase.svh:121`), so
`"…sequencer_h.run_phase"` works just as well. The reason is one of coexistence: the
`run_phase` runs in parallel with the schedule reset → configure → main → shutdown,
and hooking onto `main_phase` puts the sequence inside that schedule instead of
alongside it.

---

## Sequences

#### *When to use which*

| | `seq.start(sqr)` | `default_sequence` |
| --- | --- | --- |
| Where it is written | `run_phase` of the test | `build_phase` of the test, or the `top` |
| Objection | the test handles it | `set_automatic_phase_objection(1)` |
| It reads | top to bottom | you have to go looking for it |
| Several sequences in order | trivial | one per phase |
| Changing it without recompiling | no | yes, it is a config |
| Knows the inside of the `env` | yes, through the handle | no, only the path |
| Reusable third-party agent | not always possible | it is the intended mechanism |

- For the tests of the course: **`start()`**, because it shows
- For an agent you hand over to another team: `default_sequence`, because it lets them
  change the stimulus without touching your code

Note:
In the industry both live side by side and the choice is almost always political, not
technical: `start()` when the one writing the test is the owner of the testbench,
`default_sequence` when the testbench belongs to somebody else.
A third way worth naming without developing: the same `uvm_config_db` from
the `top` module, with `null` as the context. There the stimulus gets chosen from the command
line and the testbench does not even get recompiled. That is how the big
regressions work.
And the row that matters for the arc of the section is the second to last: `default_sequence`
is what finishes closing the `env` that the agents encapsulated.

---

## Sequences

#### *The `` `uvm_do `` macro and why the course does not use it*

```systemverilog
`uvm_do(command)                         // one line

command = command_transaction::type_id::create("command");   // four
start_item(command);
if (!command.randomize()) `uvm_fatal("SEQ", "randomize() failed")
finish_item(command);
```

- `` `uvm_do `` does exactly those four things: create, `start_item`,
  randomize, `finish_item`
- What it hides: the `randomize()` **without an else**, so a constraint without a
  solution goes by in silence
- What it prevents: filling fields by hand between the two calls — that is, everything on
  the previous slides
- What it breaks: the error message points at the expanded macro, not at your code
- There is a whole family (`` `uvm_do_with ``, `` `uvm_create ``,
  `` `uvm_send ``) and the same argument holds for all of them

Note:
It is the same discussion as the `` `uvm_field_* `` macros of the transactions, and the
same conclusion: they save typing and charge you in debug.
It is worth being fair: `` `uvm_do_with `` is genuinely convenient for a one-line inline
constraint, and you are going to see it in every testbench in the world. You have to
know how to read it. What the course does not do is teach it first: whoever learns with
the macro does not know what happens between `start_item()` and `finish_item()`, and that is the whole
section.
A rule of thumb for work: read them all, write the explicit ones.

---

## Sequences

#### *The override still works, and no sequence found out*

```sv
// The same add_test as the Transactions section, word for word. No sequence finds
// out: random_sequence still asks the factory for a command_transaction,
// and the factory hands it back an add_transaction.
class add_test extends full_test;
   `uvm_component_utils(add_test)

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

function void build_phase(uvm_phase phase);
      command_transaction::type_id::set_type_override(add_transaction::get_type());
      super.build_phase(phase);
   endfunction : build_phase

endclass : add_test
```

- It is the same `add_test` as the transactions, word for word
- `random_sequence` still creates `command_transaction::type_id::create()`; the
  factory hands it back an `add_transaction`
- Measured result: 1000 operations, **all** `add_op`, 0 `UVM_ERROR`
- `maxmult_sequence` still sends `mul_op` under `add_test` — because it does not
  randomize, and **the constraint only acts on `randomize()`**

Note:
It is the best proof that the separation worked: changing the **data type** did not
require touching the stimulus, and changing the **stimulus** does not require touching the data
type. Two independent axes, which in the transactions were stuck together and in the agents
still shared a class.
And the last bullet is the review of the trap of the transactions, now in a place
where it can be seen running: the factory picks the TYPE, the constraints only act on
`randomize()`.

---

## Sequences

#### *Two sequences on the same sequencer: the arbitration*

- Up to here every sequencer has had **one** sequence at a time. In a real testbench
  there are several in parallel on the same driver —background traffic, a directed
  test, an error injector— and somebody has to hand out the turns

```systemverilog
fork
   fondo_seq.start(sqr);                 // priority 100, the default one
   urgente_seq.start(sqr, null, 500);    // the third argument is the priority
join
```

| The mode, in `sqr.set_arbitration(...)` | How it hands out |
| --- | --- |
| `UVM_SEQ_ARB_FIFO` | order of arrival, and **the priority is not looked at** (default) |
| `UVM_SEQ_ARB_STRICT_FIFO` | the priority rules; at equal priority, order of arrival |
| `UVM_SEQ_ARB_WEIGHTED` | at random, with the priority as the weight |
| `UVM_SEQ_ARB_RANDOM` | at random, all equal |
| `UVM_SEQ_ARB_STRICT_RANDOM` | at random, but only among the highest priority ones |
| `UVM_SEQ_ARB_USER` | `user_priority_arbitration()`, you write it |

- The default **ignores the priority**: putting a 500 in and not changing the mode is the
  mistake of this slide, and nobody gives you a warning

Note:
The question that orders the slide is *"who decides which item goes into the driver?"*,
and until today the answer was "there is nobody to decide about". The sequencer arbitrates
**per item**, not per sequence: two sequences in a `fork` do not take turns in blocks,
they interleave item by item. It is worth saying because intuition says the opposite.
The mistake to leave engraved is in the last bullet and it is out of a manual: the
priority gets written, it gets run, and nothing happens — because `UVM_SEQ_ARB_FIFO` does not
look at it. Priority without `set_arbitration(UVM_SEQ_ARB_STRICT_FIFO)` is an
expensive comment.
`UVM_SEQ_ARB_STRICT_FIFO` is the one used 90 % of the time, and the name
confuses: *strict* is about the priority, not about the FIFO. It first orders by
priority and only within each level does it respect the order of arrival.
And the one almost nobody uses but is worth naming, because it explains what
`UVM_SEQ_ARB_USER` exists for: there are protocols where the turn depends on the state of the DUT —do
not send a write if the FIFO of the DUT is full—. That is not a priority, it is
a function, and that is what the user mode is for. The cousin of that idea is
`is_relevant()`, which keeps a sequence out of the arbitration until it
says itself that it is ready.

---

## Sequences

#### *`lock()` and `grab()`: when the arbitration is not enough*

- There are scenarios that **cannot be interleaved**: a configuration sequence,
  an atomic burst, a read-modify-write. If another sequence slips an item in the
  middle, the scenario stopped being the one you wrote

```systemverilog
task body();
   grab();                  // cuts ahead of everyone and closes the door
   ... the items of the scenario, with nobody in between ...
   unlock();                // ungrab() is the same method, under another name
endtask
```

- **`lock()` queues up**: it waits its turn like anybody else and only then closes
  the door. **`grab()` cuts in**: it goes ahead of everyone, even of the higher
  priority ones
- Both are released with `unlock()`. Without the `unlock()`, if the sequence is
  **still alive** the sequencer stays closed forever and without a single error; if its
  `body()` finishes, UVM takes it away and shouts `SEQFINERR`
- The rule: `grab()` for reset and error recovery —what cannot wait—,
  `lock()` for everything else, and the `unlock()` in the same `body()`

Note:
The difference between the two is one single word and it is worth saying it like this: `lock` is
polite, `grab` is rude. Both end up with the sequencer all to yourself; what
changes is whether you wait your turn or take it.
When it is really needed, because abusing this is a classic: only when the
scenario loses its meaning if something gets interleaved. A read-modify-write on a
register is the canonical example —if another transaction goes by between the read and the write,
the value you write is old—. Sending ten items in a row does not
need a lock: a sequence already guarantees that.
The two endings of the missing `unlock()` have to be told together, because one
warns you and the other does not. If the sequence holding the lock finishes its
`body()`, `uvm_sequencer_base::remove_sequence_from_queues`
(`seq/uvm_sequencer_base.svh:1258-1267`) takes the lock away from it and reports a
`UVM_ERROR SEQFINERR` — "should not finish before locks … are removed": annoying, but
with a name on it. The silent case is the other one: the sequence is still alive and
blocked on something else, and there the sequencer stays closed without anybody
saying a word. That is the one that sends you looking on the wrong side: the
simulation does not advance and the `+UVM_OBJECTION_TRACE` says nothing odd, because
the objection is fine — the one that is stuck is the driver, waiting for an item that
is never going to arrive. The tool that shows it is `+UVM_TIMEOUT` and then reading
who has the lock.
And the detail that saves an afternoon: `grab()` does not interrupt the item that is in
flight. It cuts in at the next arbitration, not in the middle of a handshake — which
is exactly what one wants.

---

## Sequences

#### *The testbench, complete*

![The final testbench: sequences, agent, sequencer, driver, monitors and the analysis layer](../res/diagrams/en/sequences_tb_completo.svg)

- It is the diagram drawn today in any verification project, with the
  names used today
- Everything inside the `env` is built once and does not change. What
  changes between one test and another is the cloud of sequences at the top

Note:
The diagram shows **one** agent, which is the unit of reuse; in `code/u7/sequences` there are
two, the active one and the passive one of the agents, and the bottom one is identical except that
it has neither sequencer nor driver.
It is worth doing the count out loud: the conventional testbench was an `initial`
of a hundred lines that drove signals. This one has test, env, agent, sequencer,
driver, two monitors, coverage and scoreboard, and every piece can be replaced
without touching the others. And the three layers at the top —sequences, agent, analysis—
change for different reasons: the stimulus changes per test, the structure per
design, the analysis per verification plan.

---

## Sequences

#### *Summary of the unit · the sequence and the item*

- The stimulus came out of the component tree: it is a `uvm_object`, not a
  `uvm_component`, and that is why it gets created, configured, run and thrown away
- Everything happens inside `body()`, between `start_item()` and `finish_item()`: that is where the
  item gets filled, that is where the `randomize()` goes, and that is where `pre_do` and `mid_do` hook on
- The driver writes the result **inside the item** before `item_done()`: it is
  the way back, and it is what makes a stimulus that reacts possible
- Two ways of starting: explicit `start(sequencer)`, or `default_sequence` through
  `uvm_config_db` — which besides takes the last hard-wired line out of the testbench

Note:
The first half of the summary is the mechanism: what a sequence is, where the
`randomize()` lives, and which way the result comes back. Anyone who got lost in
the unit catches up here.

---

## Sequences

#### *Summary of the unit · how they compose*

- Sequences compose: one calls others, in series or with `fork`/`join`
- And when there is **more than one sequencer**, the one that composes is a
  **virtual sequence**, which comes just as day 7 starts ↪ day 7
- With **two sequences on the same sequencer** the one who hands out is the sequencer:
  priority and `set_arbitration(...)`, and `lock()`/`grab()` for the scenario that cannot
  be interleaved
- With this the testbench of the course is complete —it is missing one single
  piece, tomorrow's— and it is the way it is written today in the industry

Note:
Close of day 6. None of the pieces we did see is magic: we built them all by hand —the
observer of talking to several objects, the FIFO of put and get, the tester of
transactions— before UVM
handed them to us done. That is the reason the course goes in this order and does not start
with the `uvm_agent`.
And the best place to go on reading is `code/.uvm/src/`: by this point
`uvm_sequence_base.svh` can be opened and understood.
What is left for tomorrow is the **virtual sequence**, and it is left out of today
on purpose: it is only understood with this unit's testbench closed, and the
morning of day 7 is where the student looks at a new DUT and has to decide which
structure it deserves.

## Review · Day 6

#### *1 of 10 · is_active*

**An agent in `UVM_PASSIVE`, what does its `build_phase` build?**

- [x] The monitors and the analysis ports; the driver and the sequencer, no
- [ ] Nothing: a passive agent is an empty shell
- [ ] Everything the same as an active one, but without connecting the driver to the sequencer
- [ ] Only the sequencer, so it can receive sequences from another agent of the same env

> **The monitors, always; the sequencer and the driver are left at `null`** — watching is never optional: a passive agent goes on feeding scoreboard and coverage. What gets skipped is what *drives* the interface, because there somebody else is already driving it.

---

## Review · Day 6

#### *2 of 10 · The handshake of the driver*

**The driver calls `get_next_item()`, drives the signals and forgets the `item_done()`. What happens?**

- [ ] Compilation error: UVM demands the complete pair
- [ ] The sequencer hands over the next item just the same, with a warning
- [ ] The item gets discarded and the scoreboard reports a mismatch on the next comparison
- [x] The sequence stays waiting in `finish_item()` and does not advance any more

> **It hangs inside `finish_item()`, and without saying anything** — it is the classic mistake of the first week, and the symptom misleads: there is no error and no warning, time stops advancing and the objection never gets dropped. `get_next_item()` is a loan; `item_done()` is giving it back.

---

## Review · Day 6

#### *3 of 10 · Scope of the config_db*

**The `env` instantiates two agents and does both `set()` with the scope `"*"`. What does each one receive?**

- [ ] Both fail with `uvm_fatal`: the string `"config"` is duplicated
- [ ] Each one receives its own, in order of creation
- [x] Both receive the same one: the second `set()` overwrites the first
- [ ] The first receives its config and the second is left with `cfg == null`

> **Both receive the same thing** — the `uvm_config_db` does not match by order nor by type: it matches by **path**. With `"*"` both entries describe the same components, so the last one wins. The scope is a path in the tree, not a label.

---

## Review · Day 6

#### *4 of 10 · The sequencer*

**`typedef uvm_sequencer #(command_transaction) sequencer;` compiles without touching the transaction of the transactions. Why?**

- [ ] Because it is registered in the factory with `` `uvm_object_utils ``
- [ ] Because `uvm_sequencer` accepts any `uvm_object`
- [ ] Because the driver does the `$cast` internally
- [x] Because `command_transaction` extends `uvm_sequence_item`

> **Because of the base class we chose in transactions** — `uvm_sequencer #(T)` requires that `T` derive from `uvm_sequence_item`. If that day the transaction had extended a plain `uvm_transaction`, this `typedef` would not compile today. A decision of one section enabling the next.

---

## Review · Day 6

#### *5 of 10 · super.build_phase()*

**Instead of the config object, you put `is_active` straight into the `uvm_config_db`. In this course the agent starts up active all the same. Why?**

- [ ] Because `is_active` is `protected` and the `config_db` cannot write it
- [ ] Because the `config_db` does not accept enumerated types, only `int` and `string`
- [ ] Because `is_active` is fixed in the constructor and `build_phase` arrives late
- [x] Because the one who reads it is `uvm_agent::build_phase`, and nobody calls `super`

> **That mechanism is switched off** — `uvm_agent::build_phase` looks for `is_active` in the resource pool (it is in `code/.uvm/src/comps/uvm_agent.svh`, it can be opened). Without `super.build_phase()` that line never runs, and nobody warns you. Both ways are valid; what does not work is half of each one.

---

## Review · Day 6

#### *6 of 10 · Object, not component*

**What is the practical difference of a `uvm_sequence` being a `uvm_object` and not a `uvm_component`?**

- [x] That it gets created, runs and is thrown away
- [ ] That it cannot be registered in the factory nor overridden
- [ ] That it cannot have `rand` fields nor constraints
- [ ] That UVM builds it in `build_phase`, like any other class of the tree

> **It gets created, runs and is thrown away** — you can start several, one after the other, on the same sequencer. A component is built once in `build_phase` and lives to the end. That is why the stimulus cannot be a component: it changes from test to test, and sometimes within the same test. Out of that comes as well that it can be configured between the `create()` and the `start()`, the way `full_seq.count = 200` does.

---

## Review · Day 6

#### *7 of 10 · start_item()*

**`start_item(command)` has just come back. What is it that this guarantees?**

- [ ] That the driver has already received the item and is driving the signals
- [x] That the sequencer gave the turn to this sequence
- [ ] That the `randomize()` has already been resolved with the constraints of the class
- [ ] That the objection of the phase is already raised by the sequencer

> **You have the turn —nobody else is going to beat you to the driver— and you have not handed anything over yet** — and that is why the `randomize()` goes *after*: it is the last possible moment to choose the values, when you already know what state the DUT is in. That is late randomization, and it is where `pre_do()` and `mid_do()` hook on.

---

## Review · Day 6

#### *8 of 10 · The way back*

**At what moment does `command.result` have a value that can be read?**

- [x] When `finish_item()` came back, because the driver wrote it before calling `item_done()`
- [ ] As soon as `start_item()` came back
- [ ] When the `result_monitor` publishes it through its analysis port
- [ ] Never: to receive a response you have to use the REQ/RSP pair of `uvm_sequence #(REQ, RSP)`

> **After `finish_item()`** — there is no return channel at all: there is a shared handle and an agreement between the two parties. The REQ/RSP pair exists and is the formal mechanism, but almost nobody uses it: writing the result into the request is enough. This is what makes Fibonacci possible.

---

## Review · Day 6

#### *9 of 10 · default_sequence*

**You configure a `default_sequence` through `uvm_config_db` and forget the `set_automatic_phase_objection(1)`. What happens?**

- [ ] `uvm_fatal` in `build_phase`: the sequence does not find the sequencer
- [ ] It runs just the same: when there is a `default_sequence`, the sequencer raises the objection on its own
- [x] The `main_phase` finishes at t=0 and the test passes with 0 errors
- [ ] The simulation hangs waiting for an objection nobody drops

> **It passes in zero seconds without sending a single piece of stimulus, and it lies** — a phase without an objection finishes as soon as it starts. It is the same kind of bug as the `new()` that eats the override: it does not break, it deceives. And in a regression of a thousand tests, the one that passes in zero seconds is one nobody looks at.

---

## Review · Day 6

#### *10 of 10 · Sub-sequences*

**`full_sequence` starts its daughters with `reset_seq.start(get_sequencer(), this)`. What is the second argument for?**

- [ ] To pass it the sequencer, because `get_sequencer()` only returns the type
- [x] To declare the daughter a sub-sequence of the mother
- [ ] So the daughter runs in a separate thread, in parallel with the mother
- [ ] To register the daughter in the factory under the name of the mother, so it can be overridden

> **It declares the mother-daughter relationship** — without it, the sequencer treats the two as independent sequences and they compete for the turn. With it, the daughter inherits the mother's turn and her priority in the arbitration. And for the parallel that is not enough: a `fork` / `join` around the `start()` is needed.

## Exercise · Day 6 · 1 of 3

#### *The agent that only watches*

`cd code/ejercicios/d6-agents && bash run.sh`

- The `env` has a single agent. Add the **passive** one on the second VTALU
- And make `is_active` actually count: today the agent builds driver and
  sequencer always
- It is graded with `+UVM_CONFIG_DB_TRACE`: the census of the tree is written by UVM, not by you

Note:
The exercise puts together the three things of the section that can be done wrong without the
compiler saying anything: `is_active`, the hierarchical scope of the `set()`, and the
`connect_phase` of the analysis ports.
The trap almost everybody is going to find is the scope: with `"*"` in both
`set()`, the second overwrites the first and both agents end up with the same
config — same BFM and same `is_active`. The
checker catches it by crossing the counts — the module sends 200 operations and the
sequence more than a thousand, so if both agents see similar numbers it means they
are watching the same interface.
And the shortcut of putting both in `UVM_PASSIVE` so it "passes" does not work either:
the checker demands that `clase_agent_h` still have a driver.

## Exercise · Day 6 · 2 of 3

#### *A sequence that only multiplies*

`cd code/ejercicios/d6-sequences && bash run.sh`

- Write `mult_sequence` and the `mult_test` that starts it
- The driver, the agent and the `env` are already there: adding stimulus **does not touch the
  structure**, which is precisely what the section came to demonstrate
- It is graded crosswise against what the `chequeo` sees on the bus, not against your count

Note:
It is the same exercise as day 2 and day 3, for the third time and with the final
tool: "I want it to only multiply". On day 2 it was solved by adding `virtual`,
on day 3 with a factory override, and today by writing twenty lines of
`body()` without touching a single class of the testbench. It is worth having them compare the
three: that is the whole story of the course in one exercise.
The trap they are going to find is the first one of the section: if the sequence does not
send a `rst_op` as the first item, the VTALU starts up with `reset_n` at 0, `done`
never rises and the driver stays in the first `finish_item()`. The `run.sh` has
a `+UVM_TIMEOUT` set so that finishes with a message instead of hanging.

## Exercise · Day 6 · 3 of 3

#### *Three planted bugs, and none of them looks like the others*

`cd code/ejercicios/d6-debug && bash run.sh`

| | File | How it shows up |
|:--:|---|---|
| **1** | `driver.svh` | **it hangs**: it dies on `[PH_TIMEOUT]` |
| **2** | `default_seq_test.svh` | **it ends at `t=0`** and says PASS |
| **3** | `random_sequence.svh` | **it lies in green**: `add_test` passes with the wrong stimulus |

- The checker says **which** of the three is still broken. Which line it is, is
  the exercise

Note:
It is the only exercise of the course where there is nothing to write: there is
something to find. And it is the one that looks most like your first month on the
job, where nobody hands you a file with a hole — they hand you a testbench that
does not work.
The idea that orders the three rows, and worth saying before letting them go:
**the failure modes of a UVM testbench do not look like each other**. The one
that hangs shows up at once and costs nothing. The other two pass **in green**,
and those are the ones that cost weeks.
All three are in the debug appendix table, and reading it is allowed: the list
exists precisely so that the second time it takes them five minutes.
The third one deserves its own comment because it breaks the reflex the course
has been training: `+TOPOLOGY` is the right tool for *"the tree is not the one
you drew"*… and here it **is not enough**, because what got built wrong is a
`uvm_object` and the tree only shows `uvm_component`. The only way to see it is
to look at what went out on the bus.

## Yesterday we left…

#### *Where the testbench stands*

- The testbench was left **reusable for one agent**: agents with `is_active`, the
  analysis in the `env`, and the stimulus outside the tree, in sequences. The last
  piece —coordinating two— is this morning
- No line of the test names a component from inside the `env`: the last one went
  with the `default_sequence` through `uvm_config_db`
- And the other half of the verification plan is missing: the rows **no
  scoreboard can close**, because they are not about the result but about the
  protocol

Note:
The day 7 recap works as a hinge, and it is worth saying the two things it is
made of: this morning UVM gets closed —the virtual sequence is the last piece,
and with it the testbench of the course is whole— and this afternoon opens what
UVM does not solve, which is the other half of the plan.
The third bullet is the arc planted on day 1 with the verification plan and left
open on purpose: the scoreboard checks **what**, the assertion checks **how**.
Today it closes.

---

## Agenda

#### *Day 7 · ≈ 5 h 15 · unit 8 · the other half*

- Warm-up: five seeds and a merge, with `make regresion`
- Virtual sequences: the last piece of the reusable testbench
- Assertions (SVA)
- The capstone: an APB testbench, from scratch
- From the VTALU to a real bus
- The debug toolbox · The 21 silent traps
- Glossary, references and wrap-up
- Self-assessment: fifteen things you should be able to do by now
- *On Monday*: what to do with this once the screen goes off

*And afterwards, **day 8**: optional, and for whoever has already handed in the capstone*

**By the end of the day you can:**

- **Write** a property that sees a protocol violation, and say why `--assert` is
  not optional
- **Coordinate** two interfaces from a single virtual sequence
- **Hand in** a whole testbench for a DUT you have not seen before

Note:
The morning has three pieces and the order matters: the seed warm-up is ten
minutes without SystemVerilog and it hooks into the `make regresion` the capstone
is going to ask for; the virtual sequences close UVM; and SVA opens the other
half of the plan. The afternoon is the capstone.
The third objective is the one the course is worth, and it is honest to put it as
an objective of the day even if the hand-in comes later: in a company format the
capstone is handed in the next day, and in a term it goes to the exam period.
What gets done this afternoon is starting it with the instructor next to you,
which is when it pays off the most.

## Exercise · Day 7 · 1 of 2

#### *The same sequence, another seed*

`cd code/ejercicios/d7-semillas && bash run.sh`

- The only exercise of the course without SystemVerilog: what gets written is the
  **regression**, six lines of shell
- Run the same test with seeds 1 to 5 and **merge** the five coverages
  with `verilator_coverage --write`
- It is graded by checking that the merge covers more than the best of the five on its own

Note:
It is the last row of the *coverage closure* table, done, and it is the warm-up
of day 7: ten minutes, zero SystemVerilog, and it leaves in place the
`make regresion` this afternoon's capstone is going to ask for. It also closes the
arc day 5 opened with the directed case: one fills the bin random cannot reach,
the other accumulates what random does reach, and they do not replace each other.
The detail to underline is why the test sends **25** operations and not
a thousand: with a thousand this does not work. It is measured and it is on the slide *"another seed, and
again"* — `u2/convencional` and `u7/sequences` give 66 out of 76 with any seed, and the merge
too. With 25 the stimulus has not saturated yet and there each seed does cover a
different piece: 41 to 47 bins each, 62 for the five merged.
The rule they take away, in one line: another seed **accumulates** while the
stimulus has not saturated, and **reproduces** an intermittent failure. It does not fill a bin the
stimulus cannot reach.
And the merge command is worth naming for what it is in the industry:
`verilator_coverage --write` is here what the `ucdb` merge is in Questa. A real
regression is a hundred seeds overnight and one single number in the morning.

## Virtual sequences

#### *The problem: two interfaces and a single `start()`*

- A **virtual sequence** is a sequence that does not send items of its own: it only
  starts other sequences, on **several sequencers**
- It shows up when the DUT has more than one interface —a configuration bus and a
  data stream, for example— and the test needs to coordinate them: *configure
  first, then send traffic*
- It is called "virtual" because it is not tied to a type of item nor to a sequencer
- The `u7/agents` already left us the scenario built: **two VTALU**. There the second agent
  was passive; with both active there are **two sequencers**, and something to coordinate
- `full_sequence` is already half a virtual sequence: it sends no items of its own, it only
  starts others. The only thing it lacks is the second sequencer

Note:
First hour of day 7, and that is on purpose. It is the last piece of the reusable
testbench, and it arrives on capstone day because it is the day the student looks
at a new DUT and decides which structure it deserves. The capstone has **two**
APB slaves, each with its own interface —one driven by the testbench, the other
by a module— and that is the shape of the agents section: one active and one
passive, a single sequencer, and no virtual sequence. This hour is what gives the
student the criterion to decide that instead of guessing it, and what leaves them
the answer written down for the day the second slave is theirs too.
It is worth starting from the problem and not from the syntax, because the syntax is
half a screen: what is hard to understand is why a new class is needed
when `full_sequence` already composes sequences.
The answer is the one in the last bullet, and it is geometric: a normal sequence
knows **one** sequencer, the one `start()` handed it. Anything that wants to talk to
two interfaces needs two handles, and those handles have to come from
somewhere.
The example runs and it is in `code/u7/sequences/virtual/`: it is the testbench of this
section with **two lines** changed in the `env`, and everything else by
reference. It is worth saying before showing the code, because it is half of the
argument: a virtual sequence does not change the structure of the testbench.

---

## Virtual sequences

#### *The virtual sequencer: handles, not items*

```sv
class virtual_sequencer extends uvm_sequencer;
   `uvm_component_utils(virtual_sequencer)

sequencer clase_sequencer_h;
   sequencer modulo_sequencer_h;

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

endclass : virtual_sequencer
```

```sv
      // The handles are passed HERE and not looked up by string: in connect_phase
      // both agents already exist, and if somebody renames a component this does
      // not compile instead of returning null at simulation time.
      virtual_sequencer_h.clase_sequencer_h  = clase_agent_h.sequencer_h;
      virtual_sequencer_h.modulo_sequencer_h = modulo_agent_h.sequencer_h;
```

- It has no queue, it does not arbitrate, it does not talk to any driver. It is a `uvm_component`
  that exists in order to **hold the handles** and to live in the tree with a name
- It extends `uvm_sequencer` **without parameterizing it**: the default item is
  `uvm_sequence_item` and none ever gets sent
- The handles get assigned in the `connect_phase`, where the agents already exist

Note:
The question that comes up on its own: and why a component, if it is only two pointers?
For two reasons. One, so the sequence reaches it with `p_sequencer` instead
of looking it up by string. Two, because it has to be in the tree so the test
can start a sequence on top of it: `seq.start(env_h.virtual_sequencer_h)`.
The book resolves the handles with `uvm_top.find("*.env_h.sequencer_h")`. It still
works —`uvm_top` is there for compatibility, the current form is
`uvm_root::get()`— but looking components up by string is fragile: the day
somebody renames the `env_h`, the `find()` returns `null` and the fatal shows up
far from the change. Assigning them in the `connect_phase` **does not compile** if the name
changed, which is exactly what one wants.

---

## Virtual sequences

#### *The virtual sequence: `p_sequencer` and two branches*

```sv
// `uvm_declare_p_sequencer declares `p_sequencer` with the type above and casts
// it on its own inside m_set_p_sequencer. Without it, get_sequencer() returns a
// uvm_sequencer_base and every use would need a cast by hand.
class coordinada_sequence extends uvm_sequence;
   `uvm_object_utils(coordinada_sequence)
   `uvm_declare_p_sequencer(virtual_sequencer)
```

```sv
      // --- 1. Both ALUs get reset at the same time -----------------------------
      // fork/join over TWO sequencers. Each branch blocks on its own driver, and
      // the join waits for both: that cannot be written inside a normal
      // sequence, which only knows the sequencer that started it.
      fork
         reset_a.start(p_sequencer.clase_sequencer_h);
         reset_b.start(p_sequencer.modulo_sequencer_h);
      join

// --- 2. Parallel traffic, different on each interface -------------------
      // A does the directed overflow case while B sends at random.
      fork
         maxmult.start(p_sequencer.clase_sequencer_h);
         random_b.start(p_sequencer.modulo_sequencer_h);
      join
```

- `` `uvm_declare_p_sequencer `` declares `p_sequencer` **with the type of the
  virtual sequencer** and casts it on its own. Without it, `get_sequencer()` returns a
  `uvm_sequencer_base` and you have to cast by hand at every use
- The `fork`/`join` is over **two sequencers**: each branch blocks on its driver and
  the `join` waits for both
- That cannot be written inside a normal sequence, which knows a single
  sequencer

Note:
The `uvm_declare_p_sequencer` is sugar, and it is worth saying so: the only thing it does is
declare the variable and redefine `m_set_p_sequencer()` with the `$cast`. If the
sequencer it gets started on is not of that type, the fatal fires there and not
twenty lines later.
The detail that gets overlooked: the two branches of the `fork` start **different**
sequences on **different** sequencers. If they were two sequences on the
same sequencer, they would compete for the arbitration and the items would come out
interleaved — which is a legitimate scenario, but it is another one.
And a warning from the field: a virtual sequence with a single sequencer is a
normal sequence with more ceremony. The class is justified when there are two.

---

## Virtual sequences

#### *What no sequence on its own can do*

```sv
      // --- 3. What no single sequence can do ----------------------------------
      // The result of VTALU A is the operand of B. It is a dependency BETWEEN
      // interfaces: the second one cannot even start being built until the
      // first one answered.
      primera.A  = 8'h0F;
      primera.B  = 8'h07;
      primera.op = mul_op;
      primera.start(p_sequencer.clase_sequencer_h);

`uvm_info("COORDINADA", $sformatf(
                "A returned %0d: it goes as an operand into B", primera.result), UVM_LOW)

segunda.A  = primera.result[7:0];
      segunda.B  = 8'h01;
      segunda.op = add_op;
      segunda.start(p_sequencer.modulo_sequencer_h);
```

- The result of VTALU **A** goes in as an operand of **B**: a dependency
  **between interfaces**, and in series. The second one cannot even be assembled until the
  first has answered
- The `result` comes back inside the item, which is the way back of this unit
- `0F × 07 = 105`, and B answers `106`. Run it: `code/u7/sequences/virtual/run.sh`

Note:
This is the slide that justifies the class. The two `fork` of the previous slide
could be imitated with two tests running in parallel; this one cannot, because there is a piece of data
that crosses from one interface to the other in the middle of the scenario.
It is exactly the shape of the real case the bus appendix promises:
configure over APB, read the status, and only then send traffic over AXI with
what the configuration returned. The protocol changes, not the structure.
And the criterion for the afternoon: in the capstone the second slave is driven
by a module, so there is **one** sequencer and this is not needed. The virtual
sequence comes in the day both interfaces belong to the testbench and one depends
on the other — and then it is written just like here.
And the honest close: the example runs on two VTALU because it is the DUT we
have. With two different interfaces —two transactions, two drivers— the
virtual sequence is written **the same**: the handles would be of two types of
sequencer, and nothing more.

---

## Virtual sequences

#### *And if branch B has to wait for A?*

```systemverilog
// uvm_event: a notice, from one to many. It comes from the global pool, nobody builds it
uvm_event listo = uvm_event_pool::get_global("dut_configurado");

listo.trigger();          // the branch that configured gives notice
listo.wait_trigger();     // the one waiting blocks here
listo.wait_ptrigger();    // the same, but if it already happened, it walks on

// uvm_barrier: a meeting point between N branches
uvm_barrier arranque = uvm_barrier_pool::get_global("arranque");
arranque.set_threshold(2);
arranque.wait_for();      // neither of the two goes on until both have arrived
```

- The `join` synchronizes **at the end**. When branch B has to wait for A
  **in the middle**, a synchronization object is needed
- `uvm_event` is **one to many**: one gives notice, those waiting move on. And
  `trigger(data)` can carry a `uvm_object` attached
- `uvm_barrier` is **symmetric**: nobody goes on until everybody has arrived. It is the
  "start together" of two agents that have to begin on the same cycle
- A shared `bit` with `wait(flag)` is not enough: it **loses the pulse** if the one
  waiting arrived late, and it carries no data

Note:
This is the question that shows up on its own as soon as the `fork` of the previous
slide is drawn, and it is worth answering right there: *"and if branch B cannot start
until A configured the DUT?"*.
The distinction to make clear is **one to many versus symmetric**. The
`uvm_event` has a side that gives notice and another that waits, and the roles do not
change: it is for "the reset finished", "the DUT is configured", "the interrupt
arrived". The `uvm_barrier` has no sides: the N branches execute the same
line and none goes on until all are there. It is for "start together" and for
"everybody wait until the configuration phase ends".
The `wait_ptrigger()` deserves its own second, because it is the classic race: if
branch A triggers before B reaches the `wait_trigger()`, B waits
forever. The `p` is for *persistent*: it asks whether the event **already** happened at some point.
The practical rule: if you cannot guarantee the order, `wait_ptrigger()`.
And why not a shared `bit`, which is the first thing anybody tries: a `bit` does not
keep history, does not carry attached data, and cannot be reset between phases without
somebody swallowing a pulse. The two UVM objects exist precisely because
that homemade version fails once every hundred runs.
Its own failure mode: a barrier with the threshold set wrong does not give an error —
it hangs. The symptom is a test that ends on `+UVM_TIMEOUT` without a single
`UVM_ERROR`, and `+UVM_OBJECTION_TRACE` shows the objection up and nobody
moving on.

## Assertions (SVA)

#### *The hole the scoreboard left*

- The scoreboard of this course checks **the result**: `A op B` against what
  the DUT gave back. A thousand operations, a thousand comparisons, zero errors
- Nobody checks **the protocol**. A DUT that gives back the right `result` but drops
  `done` one cycle early, or raises it on a `no_op`, **passes every test of the
  course**
- The rule of the protocol is written in three places: in prose in the spec,
  inside the BFM, and in the head of whoever wrote it. In **none** of the
  three is it checked
- An **assertion** is that same sentence, in executable form, running on its own the whole
  simulation

Note:
It is worth opening the section with the question and leaving it hanging for half a minute: *which
part of the testbench would notice if the DUT raised `done` two cycles early?*
The honest answer is none, and it comes as a surprise, because by this point the testbench
already has a scoreboard, coverage, two agents and sequences.
The reason is structural, not an oversight: the scoreboard receives *transactions*, which
is precisely what is left **after** erasing the protocol. The monitor erases it
in the analysis ports and it does well: that is what makes the scoreboard not know
that a `clk` exists. The price is that the layer that sees the wires —the interface— is
the only one that can check them, and until today it only moved them.
This is also the answer to *"why is SVA the other half of
verification?"*: it is not another technique for doing the same thing, it is the half this
testbench does not cover.

---

## Assertions (SVA)

#### *Immediate and concurrent: the one you know and the new one*

```systemverilog
// IMMEDIATE: it is a STATEMENT. It runs when the thread goes past it,
// once, and that is all. The one from the transactions is of this family.
assert (cmd.op inside {add_op, sub_op, and_op, xor_op, mul_op})
   else `uvm_error("SEQ", "invalid operation");

// CONCURRENT -- the new thing. It is a DECLARATION with a clock: it gets
// plugged in when the simulation starts and evaluated on every edge, forever.
a_done : assert property (@(posedge clk) start |=> ##[0:4] done);
```

- The **immediate** one lives inside a `begin/end`, it is procedural, and it only exists
  while the thread is standing there
- The **concurrent** one lives in no thread: it is a declaration, like an
  `always`. It gets written once and checks every edge of the whole simulation
- That is why a concurrent one can describe something that **lasts several cycles**, and an
  immediate one cannot

Note:
The distinction is hard at first and it is worth anchoring it with the RTL analogy:
an immediate one is to an `if` what a concurrent one is to an `always_ff`. The
first executes; the second gets **instantiated**.
The practical consequence is the one that matters: the immediate one can only look at the
present —the value of a variable at that instant—, while the concurrent one
has a time axis of its own and can say *"if this happens, three cycles later
that has to happen"*. No amount of `if` writes that sentence without
inventing state machines by hand.
And the hook back to the transactions: `assert(x.randomize())` is an immediate one, and there
is the silent trap of that section —`assert` is a simulation directive, and
with asserts switched off the argument does not get executed. Here you see why: they are the
same keyword for two different things.

---

## Assertions (SVA)

#### *Anatomy of a property*

```systemverilog
a_done_llega : // <- the label: NOT optional
assert property (
 @(posedge clk) // <- the clock: when it gets sampled
 disable iff (!reset_n) // <- when NOT to check
 start && (op_set != no_op) // <- the antecedent
 |-> // <- the implication
 ##[1:5] done // <- the consequent
) else `uvm_error("SVA", "..."); // <- what to do if it fails
```

- It reads like a sentence: *"on every edge of `clk`, as long as there is no reset, if
  `start` is up with a real operation, then `done` arrives within
  five cycles"*
- The **label** comes out in the error message and in the coverage report. A
  property without a label is an anonymous error at three in the morning
- The seven parts are always the same. The rest of the section is learning what
  can go in each one

Note:
It is worth writing this slide on the blackboard as a template and going back to it every
time a new property comes up: the student who gets lost in SVA almost always
gets lost because they do not tell the antecedent from the consequent.
The label deserves a paragraph of its own. Without it, the simulator invents one
(`__unnamed$_0`), and that name is the one that is going to show up in the log of the nightly
regression and in the assertion coverage report. It is exactly the same
argument as the `begin : name` the course has been using since interfaces and BFM.
The `disable iff` is looked at in detail further on, but it is worth getting ahead of why it is
so high up in the template: it is the part that gets forgotten most and the one that generates the most false
positives.

---

## Assertions (SVA)

#### *`|->` against `|=>`, mistake number one*

```systemverilog
// |->  overlapping: the consequent starts on THE SAME edge
a : assert property (@(posedge clk) start |-> !done);

// |=>  non-overlapping: the consequent starts on the NEXT edge
b : assert property (@(posedge clk) start |=> !done);
```

- `a |=> b` is exactly `a |-> ##1 b`. There is no more mystery than that
- Which one goes in? It depends on whether the response is **combinational** (the same edge) or
  **registered** (the next one). In the VTALU, `done` comes out of an `always_ff`:
  it is always the next one
- Getting it wrong does not have a single symptom: `start |-> done` with a registered
  `done` **fails on every transaction** —it sees the old `done`—, and a property whose
  antecedent never occurs passes vacuously. That is why it always goes with its `cover`

Note:
This is the first question of every SVA interview and it is worth practising it
with the DUT in hand: `done_1c <= start && (op != 3'b000)` is an NBA, so
what gets written on edge *n* is only read on *n+1*. With `|->` the
property would compare `start` against the **old** `done`.
The operational rule, which is more useful than the theory: `|=>` **is** `|-> ##1`, so
the question is not which of the two operators goes in but **how many edges later** the
spec promises it. An `assign` answers on the same edge and a `<=` on the next one, but
that is the easy case: the star property of this very section —`start && op_set !=
no_op |-> ##[1:5] done`— uses `|->` for a `done` that comes out of an `always_ff`,
because the spec promises a window of one to five edges and not a single one.
And the trap to name out loud, without overstating it: getting this wrong sometimes
shouts —`|->` against a registered signal fails on every transaction— and sometimes
stays quiet, when the antecedent you wrote never occurs and the property is vacuously
satisfied. That second case is the one the final report takes as good, and it is the
reason why the `cover property` slide is not an extra: it is the only check of the
check.

---

## Assertions (SVA)

#### *Looking at the past: `$rose`, `$fell`, `$stable`, `$past`*

```systemverilog
$rose(start)      // 0 -> 1 between the previous edge and this one
$fell(done)       // 1 -> 0
$stable(A)        // the value is the same as on the previous edge
$past(result, 3)  // the value it had 3 edges ago
```

- The four of them compare **against the previous sample**, not against the previous
  instant. In SVA time is counted in edges of the property's clock, not in
  nanoseconds
- `$stable` is the one that writes *"it was not touched"*, which is half a library of protocol
  rules
- `$past(x, n)` is a free delay line: it is good for checking a fixed latency
  without writing a state machine

Note:
Careful with `$rose` on a signal that moves **on the same edge** the property
samples: it is not going to see it go up on that edge, it is going to see it go up on the next one.
That is exactly the topic of the slide that follows, and it is worth planting it here.
`$past` with the second argument is the one that gets underestimated the most: checking *"the
result of now corresponds to the operands of four edges ago"* is one
line, and by hand it is a shift register and three bugs.
It is worth saying as well where they can be used, because there is a half-truth going
around: they *can* be called from procedural code —an `always @(posedge clk) if
($rose(req)) …` is legal (1800-2017 §16.9.3) and Verilator 5.052 accepts it—, because
that is where they infer the clock from. What they always need is **a** clock: in an
`initial` with no clock event they mean nothing. And the practical limit of this flow:
`$past` with the explicit clock argument is not supported by Verilator (*Unsupported:
$past expr2 and/or clock arguments*).

---

## Assertions (SVA)

#### *The property that is worth the section*

```sv
   // --- The stimulus ---

// The rule from slide 1 of day 1, executable at last: while start is up, the
   // operands and the operation are not touched.
   property p_operandos_estables;
      @(negedge clk) start |=> $stable(A) && $stable(B) && $stable(op_set);
   endproperty : p_operandos_estables

a_operandos_estables :
   assert property (p_operandos_estables)
   else
      `uvm_error("SVA", $sformatf(
                 "%m: operand changed with start up: A=%0d B=%0d op=%s", A, B, op2enum().name()))
```

- It is **the rule of *The VTALU spec*, day 1**: while `start` is up, the
  operands are not touched. It sat written in prose for six days
- Eleven lines, and they check every transaction of every test, on both agents, without
  anybody connecting them to anything
- The scoreboard **cannot** write this rule: by the time the transaction reaches
  it, the protocol has already been erased

Note:
This is the moment to go back to the spec slide and read it word for word.
The distance between *"start has to stay at 1 and the operands stable until the
operation finishes"* and the line of SVA on screen is almost zero — and that is
the whole argument for why assertions get written early and not at the end: the
specification **is already written**, it only has to be translated.
The `$stable(op_set)` at the end is the one that tends to be missing and it is the one that catches the ugliest
bug: changing the operation halfway through a transaction is legal for the compiler,
illegal for the DUT and transparent for the scoreboard.
It is worth showing the `@(negedge clk)` and **not** explaining it yet: leave it as a
curiosity that gets cleared up on the next slide. Somebody is going to ask first.

---

## Assertions (SVA)

#### *⚠ Two clocks: an assertion is worth what its sampling is worth*

```sv
   // TWO CLOCKS, and it is not an implementation detail: the BFM drives on
   // negedge and the DUT registers on posedge. An assertion samples in the
   // preponed region of the edge it is given, so a signal written ON the negedge
   // is not seen on that negedge: it is seen on the next one. With everything on
   // posedge, two consecutive no_op -- start goes down at t=111 and back up at
   // t=120, between two posedges -- read as ONE transaction with the operands
   // changing: 145 false positives every 1000 operations. With everything on
   // negedge, the false positives move to the done properties.
   //
   //   stimulus (start, A, B, op_set)  -> negedge, where the BFM writes
   //   response (done, result)         -> posedge, where the DUT registers

default disable iff (!reset_n);
```

| With a single clock | Over 1000 operations |
| --- | --- |
| everything on `posedge` | **145 false positives** on the stability of operands |
| everything on `negedge` | false positives on the `done` properties |
| **stimulus on `negedge`, response on `posedge`** | **0 errors** ✅ |

- The BFM drives on `negedge` and the DUT registers on `posedge`. **There is no
  single edge that makes all four properties correct**
- SVA sampling is the *preponed* region: a signal written **on** the edge
  is not seen on that edge, it is seen on the next one

Note:
This is the most valuable lesson of the section and it is not in the tutorials, so
it is worth telling it with the trace in hand: on two consecutive `no_op`, `start` goes down
at `t=111` and comes back up at `t=120` — **between two `posedge`**. The sampling does not
see it go down. The two transactions read as a single one, with the operands
changing in the middle, and the property screams 145 times about something that never happened.
The short way of saying it: *an assertion does not check what happened, it checks what it
saw*. And what it sees depends on a single character in the `@()`.
It is another **silent trap**, and one of the worst: it compiles, it runs, and it throws 145 errors
at you that do not exist. The beginner's reflex is to loosen the property until it
shuts up —and there they are left without a check. The correct reflex is to look at which edge
the one driving the stimulus writes on.
The underlying industrial way out is the **clocking block**, which declares the sampling
once for the whole interface instead of repeating it property by property. It is in
day 1 —`030-interfaces-bfm.md` and `docs/clocking-blocks.md` (in Spanish)— and it
is worth naming again here, because only now is the full problem it solves in view.

---

## Assertions (SVA)

#### *The pulse the sampling does not see*

![Two no_op in a row: start goes down at 111 and up at 120, between two posedge](../res/diagrams/en/assertions_dos_relojes.svg)

- Between two `posedge` a whole `start` pulse fits that the sampling never sees
- All on `posedge`: the two `no_op` read as **one**, and out come 145 screams
- Stimulus on `negedge`: at `t=120` it is already low, the antecedent does not start

Note:
This is the figure to pause on and walk through with a finger, because the whole
argument is in two edges. It is worth asking before showing it: *how many
transactions does an assertion sampled on `posedge` see?* The answer read off the
drawing is one, and there are two.
The amber band is what the section has been saying in words: between `t=111` and
`t=120` the signal changes twice and no `posedge` sampling lands in there. It is
not a bug of the simulator nor of the property — it is that sampling happens in
*preponed*, and at `t=130` what it sees is `start` high, same as at `t=110`.
And the second row is the cure: the same drawing with the other edge. At `t=120`
the `negedge` sampling sees `start` low, the antecedent is false, and the property
does not even start. One character.
The detail almost nobody looks at: the values of `A`, `B` and `op_set` change
exactly at `t=120`, that is, inside the transaction the `posedge` sampling believes
it is watching. That is why the 145 errors talk about operand stability and not
about something else.

---

## Assertions (SVA)

#### *Variable latency, in one line*

```sv
   // The variable latency from the VTALU spec section, in one line: one cycle for the
   // one-cycle ops, four edges for the multiplication.
   property p_done_llega;
      @(posedge clk) start && (op_set != no_op) |-> ##[1:5] done;
   endproperty : p_done_llega

a_done_llega :
   assert property (p_done_llega)
   else `uvm_error("SVA", $sformatf("%m: start con op=%s y done no llego en 5 ciclos", op2enum().name()))

// The fine print: no_op is the only operation that does not answer.
   property p_no_op_sin_done;
      @(posedge clk) start && (op_set == no_op) |=> !done;
   endproperty : p_no_op_sin_done

a_no_op_sin_done :
   assert property (p_no_op_sin_done)
   else `uvm_error("SVA", $sformatf("%m: done subio para una no_op"))
```

- `##[1:5] done` says *"between one and five edges later"*. The VTALU takes **one**
  on `add`/`sub`/`and`/`xor` and **four** on the multiplication: one property covers
  both
- `##n` is an exact delay, `##[a:b]` a window, `##[1:$]` *"at some
  point"* — which is almost never what you want: a property without an upper bound
  can never fail by timeout
- The antecedent **excludes `no_op`** on purpose: it is the only operation that does not
  answer, and putting it inside would turn the property into a generator of false
  positives

Note:
The upper bound is what separates a useful assertion from a decorative one.
`##[1:$] done` is also true for a DUT that answers next Tuesday: it
compiles, it passes, and it checks nothing. The number that goes there comes out of the specification,
not out of what the DUT does today — and if it is not in the specification, that is
the finding of the section.
The 5 in this example has a deliberate margin over the 4 real edges of the
multiplication. It is worth asking the group whether they would prefer `##[1:4]`, and why. The
honest answer is that it depends on whether the specification says *"four"* or says
*"up to five"*: an assertion is a contract, and tightening it more than the contract
turns it into a source of false positives when somebody changes the pipeline.
The `p_no_op_sin_done` below is the complement and it uses `|=>` precisely because of what
the previous slide said: `done` comes out of an `always_ff`.

---

## Assertions (SVA)

#### *`disable iff` and the reset*

```systemverilog
default disable iff (!reset_n);   // once, for the whole interface

property p;
   @(posedge clk) disable iff (!reset_n)   // or property by property
   start |=> done;
endproperty
```

- During a reset **everything is wrong on purpose**: `done` drops, `start` drops,
  the transactions halfway through get abandoned. Without `disable iff`, every reset
  is a batch of false positives
- `disable iff` **aborts** the evaluations in flight, it does not make them fail. The
  property forgets what it was waiting for and starts from zero
- The `default disable iff` at the top of the interface applies it to all of them: it is one
  line against twenty repetitions

Note:
The second classic mistake, after the `|->`/`|=>`. And the symptom misleads: the
regression fills up with errors **at the beginning of every test**, which is precisely when
one looks least, because "it is still initialising".
It is worth naming the inverse mistake, which is more dangerous: a `disable iff` with the
condition the wrong way round —`disable iff (reset_n)`— switches the property off during
normal operation and leaves it active only during the reset. It always passes, it never checks,
and there is no way of realising it from the log. It is the second silent trap
of the section and it is also headed off with `cover property`.
The difference between *aborting* and *failing* matters when the reset arrives halfway through
a long transaction. In this DUT it is one cycle; on a real bus, with
transactions of dozens, it is the difference between a usable property and one that
has to be switched off.

---

## Assertions (SVA)

#### *Where they live: inside the interface*

- They go **with the signals**, in the `interface`, not in the class testbench. There they
  see `clk`, `start`, `A`, `B` and `done` without anybody passing them along
- They do not have to be connected, nor instantiated, nor built in a `build_phase`.
  They exist because the interface exists
- The `top` of the agents instantiates **two** BFM: the same properties check
  both VTALU, including the one driven by the legacy module nobody wrote
- A **passive agent** gets them thrown in for free: watching an interface is now also
  checking it

Note:
This is the slide that connects the section with the whole architecture of the course. The
interface had been the place where the testbench *moves* wires; from
here on it is also where it *watches over* them, and both for the same reason: it is the
only layer that sees them.
The reuse argument is the one that convinces a team: the properties travel with
the interface. Whoever instantiates this BFM in another project gets the protocol check
already fitted, without reading a line of UVM. It is exactly what does not happen with a
scoreboard, which has to be built, connected and configured.
And the twist from the agents is worth saying slowly: the legacy module
—the "boss's tester", without one line of UVM— is also being checked. Nobody
asked its permission. That is the exercise of the day.
---

## Assertions (SVA)

#### *`bind`: when the interface is not yours*

```systemverilog
// The checker lives outside. The RTL is not touched -- often it cannot be.
module apb_checks (input bit PCLK, PSEL, PENABLE, PREADY);
   a_setup : assert property (@(posedge PCLK) PSEL && !PENABLE |=> PENABLE);
   c_setup : cover  property (@(posedge PCLK) PSEL && !PENABLE);
endmodule

// And in the top, one line per module you want to watch over:
bind apb_regs apb_checks chk (.*);
```

- The previous slide holds when the interface **is yours**. Somebody else's RTL, the
  bought IP and the legacy module do not get edited
- `bind` puts an instance **inside** another module from the outside: the checker
  sees the DUT's internal signals as if it had been written there
- The `.*` connects by name. One `bind` covers **every** instance of
  that module — or `bind top.dut ...` for a single one
- You can also bind to an `interface`, and Verilator supports both forms

Note:
This is the interview question that follows the previous slide, and it is worth
putting it like this: *"very nice to put the properties in the interface — and when the
interface is not yours?"*. The answer is `bind`, and it is the way
assertions are used in the industry: one checker file per block, all
bound from the top, and the RTL without a line of verification inside.
The underlying reason is not aesthetic: in a synthesis flow the RTL that is handed over
is the one that gets synthesized, and putting `assert property` inside it forces everybody
to carry the verification along. With `bind`, whoever synthesizes does not compile
the checker file and that is that.
The concrete advantage, and the one that makes it worth it: the bound checker sees the
DUT's **internal signals** — the FSM state, the wait state counter —,
which is exactly what the interface does not see. That is where assertions stop
checking the protocol and start checking the implementation.
And the warning: a badly written `bind` does not fail, connects nothing and the property is
left not running. As always, the antidote is the `cover property` — if the cover
is at zero, the `bind` did not arrive.

---

## Assertions (SVA)

#### *The integration with UVM: the `else` that makes it count*

```systemverilog
// The default: $error, and in Verilator also $stop — it cuts off on the first failure
a : assert property (p);

// What you want in UVM: the failure counts and the simulation goes on
a : assert property (p)
    else `uvm_error("SVA", $sformatf("%m: operand changed"));
```

- Without an `else`, the default action of an assertion that fails is `$error` —and in
  several simulators, `$stop`. The simulation gets cut off and the *Report Summary*
  **does not get printed**
- With an `else` that calls `` `uvm_error ``, the failure comes in through the same channel
  as everything else: it counts in the summary, it respects `+UVM_MAX_QUIT_COUNT`, and the
  `run.sh` detects it without changing a line
- The `%m` of the message prints **which instance** of the interface failed:
  `top.clase_bfm` or `top.modulo_bfm`

Note:
It is the bridge between the two halves of the course and it has to be made explicit: the
assertion is not a world apart with its own report. It is one more `uvm_error`, and
that is why `uvm_summary_ok` of `common.sh` detects it without anything having had to be
touched.
The reason the default is no good is practical: a nightly regression that
gets cut off at the first failure reports **one** failure. The same run with
`uvm_error` reports all 154, and that is the difference between *"something is wrong"* and
*"it is wrong on every multiplication"*.
The `%m` looks like a detail and it is not: with two instances of the same interface,
a message without `%m` does not say which of the two ALUs broke. It is the same problem
`get_full_name()` solved in reporting, with the tool of the language
instead of the one of the library.

---

## Assertions (SVA)

#### *Every assertion goes with its `cover property`*

```sv
   // And the cover that goes with it: without this, a regression where the random
   // never subtracted too much leaves the assertion green having checked nothing.
   c_ovf : cover property (@(posedge clk) done && ovf);
   c_sub_sin_borrow : cover property (@(posedge clk) done && (op_set == sub_op) && !ovf);

c_mult_3ciclos : cover property (@(posedge clk) $rose(start) && (op_set == mul_op) ##3 done);
   c_mult_4ciclos : cover property (@(posedge clk) $rose(start) && (op_set == mul_op) ##4 done);
   c_un_ciclo : cover property (@(posedge clk) $rose(start) && (op_set inside {add_op, sub_op, and_op, xor_op}) ##1 done);
```

```plaintext
  covergroup : 86.8% (66/76)
  user       : 80.0% ( 4/ 5)
```

- A property whose **antecedent never occurs** passes. Without assertion
  coverage, a switched-off check looks exactly like a green check
- `c_mult_3ciclos` stays at **zero forever**: the chain of the multiplier
  is `done3 → done2 → done1 → done_mult`, that is **four** edges, not three. The
  cover at 0 gives away that the mental model of the latency was wrong
- In Verilator the `cover property` land in the **same `coverage.dat`** as the
  covergroups of the conventional testbench: code, functional and assertion coverage, one
  single report

Note:
This slide closes the circle the conventional testbench opened and it is worth saying so: the
question *"how do I know I measured?"* had three answers in the course, and this is the
third one. Functional coverage says what stimulus was generated; assertion
coverage says which **checks actually got evaluated**.
The case of `c_mult_3ciclos` is a pedagogical gift and it came out of writing the
section, not out of inventing it: the intuitive count was three —the module is called
`vtalu_mult`— and the hardware takes four, because the `done` travels through a pipeline
of its own. The property with `##3` would have passed just the same if it had been a badly
written `assert`, and the `cover` at zero is the only thing that gives it away.
The rule to take away: for every `assert property` you write, write the
`cover property` of the antecedent. It is two lines and it is the difference between a
testbench that checks and one that says it checks.

---

## Assertions (SVA)

#### *Assertion or scoreboard: the same rule, two places*

| | Assertion | Scoreboard |
| --- | --- | --- |
| What it checks | the **protocol**: who moves, and when | the **transformation**: `A op B` |
| Where it lives | in the `interface`, with the wires | in the testbench, with the transactions |
| When it screams | on the exact edge on which it breaks | when the result arrives |
| What it needs | nothing: it plugs itself in | monitor, analysis port, `connect_phase` |

- Short rule: **protocol → assertion. Data → scoreboard.** Writing a
  protocol check in the scoreboard is rebuilding the time the monitor
  has just taken care of erasing
- And the other way round: writing the reference model of a multiplier in SVA is
  possible and it is a bad idea

Note:
The question that always comes up: *why not check everything in a single place?* The
answer is that the two layers see different things and neither can see the other's
without undoing the monitor's work.
The advantage of the *"it screams on the exact edge"* is the one that saves the most time in
real life, and it is worth putting in numbers: a scoreboard mismatch gives you a
wrong result and you have to track backwards until you find the cycle
where it started. An assertion gives you the cycle. On a bus with overlapping
transactions, that is the difference between half an hour and two days.
The other half of the rule matters too: SVA does not replace the scoreboard. Nobody
wants to read a reference model written in properties, and whoever tried it tells it
as an anecdote.

---

## Assertions (SVA)

#### *The example of the section: the bug the scoreboard does not see*

```sv
            // +BUG=1: changes B halfway through the multiplication. The
            // multiplier already latched A and B on the first edge, so the
            // RESULT DOES NOT CHANGE: the scoreboard stays green. The only
            // thing that sees it is the assertion. That is the whole section.
            if (bug_operandos && iop == mul_op) begin
               @(negedge clk);
               @(negedge clk);
               B = ~iB;
            end
            do @(negedge clk); while (done == 0);
            oresult   = result;
            start = 1'b0;
```

```plaintext
** Report counts by severity
UVM_INFO :    2
UVM_WARNING :    0
UVM_ERROR :  154
UVM_FATAL :    0
** Report counts by id
[MAXMULT]     1
[RNTST]     1
[SVA]   154
```

- `+BUG=1` changes `B` **halfway through the multiplication**. The multiplier has already
  latched the operands on the first edge: **the result comes out right all the same**
- The scoreboard compares 1000 operations and does not find a single difference: in the
  summary there is **not one `[SELF CHECKER]`**. It is doing its job properly — this bug is
  not a data bug
- The assertion catches it 154 times, on the exact edge. It is the same example as reporting, turned inside out: over there the scoreboard was broken to teach reporting;
  here the protocol gets broken to show who sees it

Note:
Run both runs live if there is time: `bash code/u8/assertions/run.sh` does the
clean one and the buggy one, one after the other, and the comparison of the two *Report
Summary* is the slide.
It is worth pointing out why the bug is invisible, because it is not obvious: the pipeline
does `a_int <= A` on the first edge and `mult1 <= a_int * b_int` on the second.
Everything that happens to `A` and `B` after the first edge gets discarded. A
designer would say the DUT is *robust*; a verification engineer would say the testbench
is lying — the stimulus violated the contract and nobody found out.
And the punchline: this bug is not hypothetical. It is exactly what the legacy
module of the exercise does, and it is exactly the kind of thing that survives for years in a
block that "works".

---

## Assertions (SVA)

#### *The traps of this section*

| The symptom | The cause | How to head it off |
| --- | --- | --- |
| The property **always passes** | the antecedent never occurs | one `cover property` per assertion |
| **False positives** on every transaction | you sample it with the edge it is written on | stimulus and response go on different edges |
| False positives **at the start** of every test | the `disable iff (!reset)` is missing | `default disable iff` once, at the top |
| The log says **PASS** and the properties did not run | `--assert` is missing at compile time | the `cover` at 0 is the one that warns you |

- The four share the shape of the appendix: **they compile, they run, and they lie**
- The fourth is the cheapest to commit and the most expensive: without `--assert`, Verilator
  compiles the properties and does not evaluate them. All green, zero checking

Note:
The fourth row deserves a minute because it is specific to the flow of this course and
comes as a surprise: `--assert` is not a "more warnings" flag, it is the switch that
turns a declaration into a check. Without it, the whole block of the interface
is expensive documentation.
And the antidote is the same for all four, which is the elegant part: the `cover
property`. If the cover is at zero, either the property does not run, or its antecedent does not
occur. In both cases you have to go and look, and in both cases the `assert` on its own
would have said that everything is fine.
These four are added to the appendix of the silent traps, which from this
section on are twenty-one.

---

## Assertions (SVA)

#### *Summary of the unit*

- A **concurrent assertion** is a declaration with a clock: it gets written once
  and checks every edge of the simulation, on its own
- The anatomy never changes: `label : assert property (@(clock) disable iff
  (reset) antecedent |-> consequent) else action;`
- `|->` is the same edge and `|=>` **is** `|-> ##1`. The question is not which of the
  two, it is how many edges later the spec promises it
- The properties live **in the `interface`**, with the signals. They do not get connected, they do not
  get built, and they travel with it
- In UVM the action is `` `uvm_error ``, so the failure **counts** in the
  *Report Summary* instead of killing the simulation
- **Every assertion goes with its `cover property`**: it is the only check of the check
- And the one that takes the section: **an assertion is worth what its sampling is worth**.
  The stimulus gets sampled where the stimulus gets written

Note:
If the group takes away a single sentence, let it be the last one. Everything else in this
section is syntax and can be looked up; the sampling is judgement, and it is what separates a
property that checks from one that makes noise or from one that stays quiet.
The second one to take away is the one about the `cover property`, for a cultural reason: it is
the only defence against the testbench that feels safe. A team with
three hundred assertions and no assertion coverage does not know how many it is
running.
And it is worth closing with the location on the map: this is the half that was missing. The
scoreboard checks what the DUT computes; the assertions, how you talk to it. A
serious verification plan has both columns.

---

## Assertions (SVA)

#### *What this section does differently*

- **The *UVM Primer* has no SVA.** It teaches the class testbench
  end to end and leaves the assertions out: they belong to the other half of
  SystemVerilog
- This section exists because the question comes anyway —in the interview, and in the
  first real block one gets to verify
- The two clocks, the table of the 145 false positives and the `cover property` that
  never gets covered **did not come out of a tutorial**: they came out of writing this
  section on the VTALU of the course and looking at why it did not add up
- Everything here runs on Verilator, without licences, with the same `run.sh` as the
  other thirty-seven examples

Note:
It is worth being explicit with the group about where each thing comes from, because it is part of
what the course teaches: the difference between reading about SVA and writing SVA is
exactly the two-clocks slide. No tutorial has it because the
tutorials use a DUT where stimulus and response share an edge.
It is also the answer to *"why one more UVM course?"*. This one runs. And when
something does not add up, the section tells why it did not add up instead of changing the example.
What is left out and is worth naming so nobody discovers it late:
formal assertions, `expect`, and the prefabricated bus properties that come with
commercial VIP. With what is in this section they can be read without help.

## Exercise · Day 7 · 2 of 2

#### *The legacy module violates the protocol and nobody knew*

`cd code/ejercicios/d7-sva && bash run.sh`

- The "boss's tester" of the agents drives its VTALU **by hand** for the
  multiplication, and it goes about getting the operand of the next one ready while it waits for
  `done`. It has been in production for years
- The scoreboard compares a thousand operations and does not find a single difference:
  the multiplier latched `A` and `B` on the first edge. **The bug is not a data bug**
- Write the property that does see it. The two `done` ones are already there, as a template
- The checker asks for three things: that it fire on `modulo_bfm`, that it **not** fire
  even once on `clase_bfm`, and that the scoreboard stay green

Note:
The exercise gets solved with a three-line property, but the second
condition of the checker is the one that teaches: whoever samples it on `posedge` is going to see
false positives on the interface that **does** respect the protocol, and the message
is going to send them to look at the edge. It is the two-clocks slide, cashed in.
It is worth insisting on the `cover property` hint for whoever gets no firings:
the natural reflex is to loosen the property until it does something, and it is the wrong
reflex. The cover at 0 tells *"the property is badly written"* apart from *"the
antecedent does not occur"*, and they are two different problems.
And the moral that goes beyond the exercise: nobody wrote the property
thinking about the boss's module. It lives in the interface, and that is why it checks
everybody who uses it — including code that was written five years before
this testbench existed.

## Review · Day 7

#### *1 of 5 · Immediate and concurrent*

**What is the underlying difference between `assert(x.randomize())` and `assert property (@(posedge clk) …)`?**

- [x] One is a **statement**; the other, a **declaration with a clock**
- [ ] None: the second is syntactic sugar for the first
- [ ] The first can be switched off from the command line and the second cannot
- [ ] The first is only valid inside a class and the second only inside a module, because of the scheduler

> **Statement against declaration** — the immediate one runs when the thread goes past it; the concurrent one gets evaluated on its own, on every edge of its clock. It is to an `if` what the concurrent one is to an `always_ff`: one executes, the other gets instantiated. That is why only the concurrent one can describe something that lasts several cycles.

---

## Review · Day 7

#### *2 of 5 · `|->` against `|=>`*

**The `done` of the VTALU comes out of an `always_ff`. Which implication goes in `start |?? done`?**

- [ ] `|->`, because the antecedent and the consequent belong to the same transaction
- [x] `|=>`, because what gets written with `<=` is read one edge later
- [ ] Either of the two: the difference is a matter of style
- [ ] Neither: for registered signals you have to use `$past()` on the antecedent

> **`|=>` when the consequent comes out of a `<=`** — because `|=>` *is* `|-> ##1`, and the question to ask is how many edges later the spec promises it. With `|->` against a registered signal the property does not pass vacuously: it **fails on every transaction**, because it compares against the old `done`. The one that passes quietly is the one whose antecedent never occurs — which is why it always goes with its `cover property`.

---

## Review · Day 7

#### *3 of 5 · The sampling edge*

**All the properties of the VTALU sampled on `@(posedge clk)` give 145 errors over 1000 operations, and the DUT is healthy. Why?**

- [ ] The `disable iff (!reset_n)` is missing
- [ ] The `posedge` is too fast: the clock has to be divided
- [ ] Covergroups and assertions cannot share the clock without a `clocking block`
- [x] The stimulus is written on the `negedge` and the sampling does not see it

> **An assertion is worth what its sampling is worth** — the BFM writes the stimulus on the `negedge`, and on two consecutive `no_op` `start` goes down and comes back up between two `posedge`: the sampling does not see it go down. The stimulus gets sampled where the stimulus gets written. Stimulus on `negedge`, response of the DUT on `posedge`: zero errors. With a single clock there is no way.

---

## Review · Day 7

#### *4 of 5 · The assertion that checks nothing*

**An `assert` property reports 0 failures during the whole regression. What do you know?**

- [x] Nothing yet: it may never have been evaluated at all
- [ ] That the rule it describes holds
- [ ] That the DUT is free of protocol bugs
- [ ] That the property has a badly written `disable iff` and stayed off the whole time

> **Zero failures and zero evaluations look the same** — its antecedent may never have occurred, or `--assert` may be missing and it is not even being evaluated. That is why every assertion goes with its `cover property`: it is the only check of the check. In the section, `c_mult_3ciclos` stays at 0 and gives away that the real latency is four edges, not three.

---

## Review · Day 7

#### *5 of 5 · Assertion or scoreboard*

**The DUT gives back the right `result` but drops `done` one cycle earlier than the specification says. Who catches it?**

- [ ] The scoreboard, when it compares the result
- [ ] The functional coverage, because the `done` bin is left empty
- [x] An assertion in the interface: it is a **protocol** bug
- [ ] The `uvm_fatal` of the `command_monitor`, which would stop seeing commands on the bus

> **Protocol → assertion. Data → scoreboard** — and it is not a preference: by the time the transaction reaches the scoreboard, the protocol is no longer there. Writing the check there would be rebuilding by hand the time the monitor has just erased.

## Capstone · Day 7

#### *The whole testbench, from a blank sheet*

`cd code/ejercicios/d7-final && cat spec.en.md`

- The previous exercises gave you a file with a hole in it. This one gives a **DUT,
  a spec and nothing else**
- The DUT is not the VTALU: it is an **APB3 slave** with four registers. It has
  addresses, two phases per transfer, a *wait state* and an error response
- Everything gets written: the interface with the protocol, the transaction, the driver, the
  monitor, the agent, the scoreboard, the covergroup, the sequences and the tests
- The checker goes **in stages**, and each one prints its `STAGE N OK`. It can be
  finished one at a time — and that is the way to do it

Note:
It is the afternoon of day 7 and it is the exercise that justifies the whole course. It is worth
saying it that bluntly: up to here the student has completed somebody else's structure, which is
exactly what they are going to be asked for on the first day of a real project — but
they have never built one. The difference between *"I did the course"* and *"I know how to do it"* is this
afternoon.
If the group is short of time, stage 1 —the monitor— on its own already leaves something: it is the
deliverable the bus appendix recommends as the first one, and it gets done in half
an hour.
The other use, for whoever is studying alone: it is the exercise that can be shown in
an interview. A UVM testbench on an APB, written from scratch, with its
coverage plan, is exactly the example they ask for.

---

## Capstone · Day 7

#### *The DUT: four registers and the small print*

| Addr | Name | Access | Contents |
|---|---|:--:|---|
| `0x00` | `CTRL` | RW | bit 0 = `EN` · bit 1 = `CLR`, **autoclear** |
| `0x04` | `SCRATCH` | RW | 32 bits, and **adds to `ACC` if `EN`** |
| `0x08` | `ACC` | RO | the accumulator |
| `0x0C` | `STATUS` | RO | bit 0 = `EN` · bit 1 = `OVF`, sticky |

```sv
 // The handshake: the write does not wait, the read inserts ONE wait state.
 // rd_wait re-arms as soon as PENABLE drops, that is between one transfer and
 // the next, with no need to count cycles.
 logic rd_wait;
 always_ff @(posedge PCLK or negedge PRESETn) begin
 if (!PRESETn) rd_wait <= 1'b1;
 else if (!PENABLE) rd_wait <= 1'b1;
 else if (access && !PWRITE) rd_wait <= 1'b0;
 end

assign PREADY  = !PSEL ? 1'b1 : (PWRITE ? 1'b1 : !rd_wait);
   assign PSLVERR = access && !mapped;
```

- The read puts in **one wait state**: the driver waits for the handshake, it does not count cycles
- From `0x10` upwards, `PSLVERR`. Writing an RO, on the other hand, is **not** an error

Note:
The four traps of the spec are put there on purpose and all four are about
a spec badly read, not about UVM: the wait state of the read, the `CLR` that never gets read
at 1, the read-only register that gets written without giving an error, and the accumulator
that only runs with `EN=1`. They are the four that hang the first testbench, and
they are together in a section of `spec.en.md` called *The small print* — in
a real spec they are not going to be together nor in a section with that name.
The `assign` of the `PREADY` is the whole slide if one has to be picked: it says that the
write does not wait and the read does, and out of that comes the `do @(posedge PCLK); while
(!PREADY);` of the driver. A driver that takes for granted that ACCESS lasts one cycle reads
`PRDATA` one cycle too early — and it does not fail every time, which is the worst that
can happen.

---

## Capstone · Day 7

#### *The order: monitor, driver, scoreboard, coverage*

- **1 · The monitor.** The `top.sv` brings **two** slaves: one for your testbench and
  another driven by an ordinary module, without UVM. A **passive** agent on that one, and
  let us see the eight transfers. Without a driver
- **2 · The driver.** The protocol inside the interface, and a directed
  sequence that writes and reads the four registers
- **3 · The scoreboard.** The DUT modelled in software. The checker runs it twice:
  against the healthy DUT it has to keep quiet, and with **`+BUG=1`** it has to scream
- **4 · The coverage.** The covergroup with the nine rows of the verification
  plan of the spec: at least 20 points, 90 % covered. And **two rows come empty**
- **5 · The properties.** The APB protocol inside `apb_if.sv`, with
  `--assert`. With **`+BUG=2`** there is a bug the scoreboard cannot see

Note:
The order is not a whim of the checker: it is the field advice of the appendix
*From the VTALU to a real bus*. The first thing that gets written is the monitor, because
whoever starts with the driver writes stimulus nobody is watching and discovers a
week later that their monitor does not reconstruct. That is why the `top.sv` comes with the second
slave: so the monitor has something to watch **before** the driver
exists.
Stage 3 is the one that gets discussed the most and the one that pays off the most: a scoreboard that has never
seen an error is not tested. `+BUG=1` takes the `CTRL.EN` gate off the DUT, so
the accumulator always adds. A model that has not modelled `EN` passes both
runs and the checker catches it — which is exactly what a regression
with a mutation test would do.
And a hint about shape for stage 3, which saves a rewrite: the APB answers
**in order and one at a time**, so a queue is enough and the scoreboard can compare
on the spot. It is worth writing that assumption down in the plan like any
other, because it is the first one that falls over when the DUT stops being a simple
slave: there the pattern is the table indexed by ID of the analysis ports.
And stage 4 closes the circle of day 6: the covergroup does not get invented, it gets copied
from the table of the verification plan. If a bin is left at zero, there is a row of the
plan that was not verified — no matter how green the scoreboard is.

---

## Capstone · Day 7

#### *Stage 5: the bug the scoreboard cannot see*

```systemverilog
// In apb_if.sv, with the signals. The payload does not move until it ends
property p_payload_estable;
   @(posedge PCLK) PSEL && !(PENABLE && PREADY) |=> $stable({PADDR, PWRITE, PWDATA});
endproperty

a_payload_estable : assert property (p_payload_estable)
   else `uvm_error("SVA", $sformatf("%m: the payload moved before PREADY"))
```

- `+BUG=2` does to the usual module what `d7-sva` did to the legacy
  tester: **it moves `PADDR` in the middle of ACCESS**
- The DUT answers at the new address, the monitor reconstructs **eight spotless
  transfers**, and the scoreboard has nothing to compare wrongly
- Measured: **8 `UVM_ERROR [SVA]`** and the same 8 transfers in the monitor's
  log. The only one that notices is the assertion
- And rows **8 and 9** of the plan come empty: *back to back* and unaligned
  address. The bins are called `back_to_back` and `unaligned`

Note:
This is the stage that makes the capstone integrate the whole day and not half of it. The
argument *"the scoreboard checks what, the assertion checks how"* came all the way from
day 1 and got demonstrated on the VTALU; here it gets demonstrated on a bus with
addresses, two phases and a wait state, which is where the student is going to need it.
It is worth doing the arithmetic out loud, because it is what convinces: with `+BUG=2` the
module changes the address after SETUP. The DUT is combinational in its
decoding, so it serves the new address. The monitor samples on the
handshake edge, so it reconstructs the transfer with the new
address. Monitor and DUT agree — **there is nothing the scoreboard can compare
wrongly**. The only one that knows the address moved is the one that was watching the
wire on every edge.
The two empty rows are the other half of the exercise and they are deliberately
uncomfortable: the two things they measure are promised in the spec, each on a
loose line, and none of the seven rows above measures them. Row 9 also
trips up the scoreboard that decodes with the whole address — `PADDR[1:0]` is
ignored, so `0x06` **is** the `SCRATCH`.
And a trap worth telling because the course itself fell for it: the
obvious reading of *"`PSLVERR` is valid together with `PREADY`"* is
`PSLVERR |-> PREADY`, and it is **false** on this DUT. `PSLVERR` is combinational, so
on an unmapped read it is already high during the wait state. Written as an
assertion it fires on the healthy DUT. That rule is a `cover`, not an `assert`.

## Appendix · From the VTALU to a real bus

#### *What does not change*

- The DUT of the course has a three-signal handshake. On Monday you are going to
  run into **AXI, APB or AHB**, and the honest question is how much of this is any use
- The tree, all of it: `test` → `env` → `agent` → sequencer, driver and monitors, with
  the analysis hanging off the analysis ports. **It is the same diagram**
- The agent is still **one per interface**. A DUT with a configuration APB
  and a data AXI is two agents, not one bigger agent
- The configuration still comes down through **one object per level**, and the scope of the
  `config_db` is still a path
- The sequence is still an object that gets created, runs and is thrown away

Note:
This appendix exists because everybody asks the question when they finish, and the
short answer is good news: the **architecture** does not change at all. What
changes is a single class, the driver, and one more single class, the monitor.
It is worth saying it with numbers so it does not sound like consolation: of the nine classes of
`code/u7/sequences`, in an APB agent two get rewritten —driver and monitor—, the
transaction gains fields, and the rest —test, env, agent, config, scoreboard,
coverage, sequences— gets copied and adapted.
And the underlying reason is the one the course has been repeating since the `env`: what
knows about the protocol is shut away in one place. Changing protocol touches that
place and nothing else. If the student had to rewrite the env, it would be a sign that the
agent was badly built.

---

## Appendix · From the VTALU to a real bus

#### *What does change*

- **The driver stops being a linear task.** An operation of the VTALU is raising
  `start` and waiting for `done`. A bus has phases —address, data, response— and in
  AXI the five channels run **independently**: the driver goes from a `send_op()`
  to several threads with `fork`
- **The monitor has to reconstruct.** Watching one edge is no longer enough: the
  address of one channel has to be paired with the data of another, by ID. It is the hardest class
  of the agent, and the one most underestimated
- **The transaction grows**: address, burst type, length, strobes, response. And
  the constraints stop being decorative — in AXI a burst cannot cross a
  4 KB boundary, and that is a `constraint`, not a comment
- **Virtual sequences stop being a luxury**: configure over APB, then
  send traffic over AXI with what the configuration gave back. The shape is the one from
  sequences —`virtual_sequencer`, `p_sequencer`, one `fork` per interface—; the
  only thing that changes is that the two sequencers are of different types
- **RAL shows up.** If the DUT has registers —and it does—, `uvm_reg` gives you the
  model and the register tests already done

Note:
The first bullet is the one to underline, because it is where the
intuition the course built breaks. In the VTALU, "an operation" and "an exchange
on the bus" are the same thing. In AXI they are not: a write transaction is three
channels that can go in any order, and `item_done()` gets called when the
response arrived, not when the address was put out.
A practical consequence worth getting ahead of: the moment the driver has
several transactions in flight, the `get_next_item` / `item_done` pair stops
being enough and a `uvm_tlm_fifo` shows up inside the driver, or the *pipelined* mode. It is not
a new topic: they are the same pieces as threads and as put and get.
And about the second bullet, to bring the anxiety down: the monitor of a known
protocol almost never gets written. It gets bought or downloaded.

---

## Appendix · From the VTALU to a real bus

#### *Vertical reuse: the block env inside the system env*

```systemverilog
class soc_env extends uvm_env;
   apb_env apb_env_h;     // the block env, without touching a line of it
   axi_env axi_env_h;
   soc_scoreboard sb_h;   // the system one watches both ends, not the transfers

function void build_phase(uvm_phase phase);
      // What changes is not the env's code: it is its CONFIGURATION
      apb_cfg.is_active = UVM_PASSIVE;   // here the APB is driven by the SoC's CPU
      uvm_config_db #(apb_env_config)::set(this, "apb_env_h*", "cfg", apb_cfg);
      apb_env_h = apb_env::type_id::create("apb_env_h", this);
   endfunction
endclass
```

- The reuse of the agents section is **horizontal**: two instances of the same
  agent in the same env. This one is **vertical**, and it is the one that pays off in a SoC
- The block env does not get edited. What changes is its config: the agent becomes
  **passive** because at system level the bus is driven by the DUT, not the testbench
- That is why `is_active` and the config object are not ceremony: they are the hinge that
  makes the same code work at both levels
- What does **not** move up is the block scoreboard: the system one compares the SoC's
  input against its output, and the block one goes on measuring its bus

Note:
This is the answer to *"and what are all those classes for, if my DUT has a bus?"*, and the
answer is that the block testbench is not written for the block: it is written
so that in six months it goes whole inside the chip's testbench.
The concrete rule that decides whether an env is reusable, worth handing over as a
three-point checklist: **it does not create its own interface** —it receives it through
`config_db`—, **it does not read from the `config_db` with absolute paths** —no
`uvm_test_top.env_h.*`, because at system level that path does not exist—, and **it does not
raise objections of its own** unless it is the one in charge. An env that breaks
any of the three compiles just the same and cannot be instantiated twice.
The change from active to passive is the typical case and is worth explaining slowly: at
block level the testbench drives the APB because there is nobody else. At
SoC level that bus is driven by the real processor, so the same agent has to
watch without driving — and that is already solved, it is the `is_active` of the agents
section. Not one new line.
And the fact that closes the capstone: the env they wrote in `d7-final` **already** is
reusable, because its config comes from outside and so does its interface. It was not
a coincidence; it was the `apb_env_config`.

---

## Appendix · From the VTALU to a real bus

#### *Where to start*

- **Look for a VIP before writing an agent.** Almost nobody writes an AXI agent
  from scratch: the vendors sell them and there are free ones. Writing your own is a project
  of months and it is not the one you were asked for
- **The protocol before the methodology.** 90 % of the bugs of a new agent
  are about a badly read protocol, not about UVM. The spec of the bus first
- **The first thing that gets written is the monitor**, not the driver. If you cannot *see* the
  bus you cannot verify anything — not even somebody else's stimulus
- And there the **passive agent** is your first real deliverable:
  watch before driving
- **SVA in parallel.** A bus has rules that get checked where they happen, not in the
  scoreboard, and on a bus with overlapping transactions that is the difference between
  half an hour and two days. You already have the tool: **the assertions**, with the advantage
  that the properties travel inside the interface of the VIP

Note:
The order of this slide is field advice and it is worth defending: whoever
starts with the driver writes stimulus nobody is watching, and discovers a
week later that their monitor does not reconstruct. Whoever starts with the monitor can
plug it in passively on somebody else's stimulus —or on a test from the designer— and is
already contributing on the first day.
If somebody asks where the learning path goes on **after this course**, the short
list, in order: **TLM2** —`uvm_tlm_generic_payload` and the sockets, which is how
bus VIPs get connected to each other—, the **RAL backdoor** —`docs/en/verilator.md`
explains why it is not here—, the **`uvm_sequence_library`** for the stress test
you do not write, and reading the `dv/` of a real open project: the agents of
**OpenTitan** and the AXI VIP of **pulp-platform/axi** are production code and
they read for free. And one that is not UVM and is worth the career: **formal**
with SymbiYosys, which proves the same properties they wrote today without any
stimulus.
What is **not** on that list is what they have already seen: RAL is day 8, the
regression with seeds is the day 7 warm-up and `make regresion`, and the
`clocking block` is half a section of unit 2.
And a last one, which is not technical: in a real project the testbench almost always
already exists. What gets asked for on the first day is not building one, it is **adding a test
to it** — which is exactly what they practised in the exercises of days 3 and 6.

## Appendix · The debug toolbox

#### *The tools we saw, all together*

| Tool | What for | Where it came up |
| --- | --- | --- |
| `VLT_TRACE=1` + GTKWave | see the real signals | The VTALU spec |
| `+UVM_VERBOSITY=UVM_HIGH` | see the monitors’ messages | Reporting |
| `+UVM_CONFIG_DB_TRACE` | who put what in the `config_db`, and who read it | Agents |
| `+TOPOLOGY` → `print_topology()` | the tree UVM **actually** built | Agents |
| `+UVM_OBJECTION_TRACE` | who raised and who dropped the objection | Tests |
| `+UVM_TIMEOUT=N,NO` | a ceiling for the hang, instead of waiting | Tests |
| `+UVM_MAX_QUIT_COUNT=N` | kill the run at the Nth error | Reporting |

- The bottom six are **plusargs**: no code gets touched and nothing gets recompiled. On a
  testbench with UVM that is minutes of difference per attempt

Note:
This appendix exists because the tools are spread over four
sections and they are all needed together, at the worst moment: when something does not work and
the clock is running. It is the slide worth printing — and in fact it is already printed:
`docs/en/uvm-cheatsheet.pdf` is this table, the class hierarchy, the nine phases and
the handshake of the driver on a single A4 side. The source is `res/en/machete.html`,
it opens with a double click and it prints with Ctrl+P.
The point to say out loud is the one about the plusargs. A `$display`
added by hand costs a recompilation of UVM —minutes— and on top of that you have to
remember to take it out. Six of these seven are already fitted in the binary you compiled: they get switched
on from the command line and they leave no trace. The seventh, `VLT_TRACE`, also
needs the `$dumpfile`/`$dumpvars` block in the top — today `u2/convencional` and
`ejercicios/d1b` have it.
And one detail of `+UVM_TIMEOUT` that bites, because it does not error out: the value
is an integer in time units, not an expression with a unit. UVM reads it with
`$sscanf(…, "%d,%s")` (`uvm_root.svh:916`), so `+UVM_TIMEOUT=5ms` does not complain:
it takes the `5` and cuts the simulation off at 5 ns. You write
`+UVM_TIMEOUT=5000000,NO`, and the `NO` is so that a `set_timeout()` written in the
testbench does not overwrite what you asked for on the command line.
`+TOPOLOGY` is not from UVM: it is from the `base_test` of the course, which reads the plusarg and
calls `uvm_root::get().print_topology()`. It is worth clarifying so nobody
looks for it in the LRM. The same for `VLT_TRACE=1`, which is from the `run.sh`.
And one that is not in the table because it is not a tool but a habit:
running with `SEED=N`. A bug that shows up once every ten runs does not get debugged
until you can repeat it at will.

---

## Appendix · The debug toolbox

#### *Which one to use, according to the symptom*

| The symptom | The first suspect | What to look at it with |
| --- | --- | --- |
| It ends at **t=0** and says PASS | nobody raised the objection | `+UVM_OBJECTION_TRACE` |
| It **never ends** | an `item_done()` that was not called, or an objection that does not get dropped | `+UVM_TIMEOUT=5000000,NO` and then the trace |
| The scoreboard **screams on every one** | the monitor samples badly — the DUT hardly ever is the problem | `+UVM_VERBOSITY=UVM_HIGH` |
| The `config_db` **does not find** | the scope of the `set()`, not the `get()` | `+UVM_CONFIG_DB_TRACE` |
| The coverage gives **0 %** | the `new()` or the `sample()` of the covergroup is missing | read the `.dat` with `verilator_coverage` |
| The tree **is not the one you drew** | a `create()` without the factory, or a late override | `+TOPOLOGY` |

- The golden rule is in the second column: **suspect number one is never
  the DUT.** It is the testbench watching it

Note:
This slide is the index of the previous one, and the order of the rows is not accidental: they are
the six things that actually happen, ordered by how many times you are going to
see them.
The first and the second are two sides of the same coin: the objection. If nobody raises it,
the sim ends at zero; if nobody drops it, it never ends. That is why the objection
trace is the first tool to switch on when the simulation time
makes no sense.
The third is the one from the day 5 exercise, and the lesson it leaves is a matter of craft, not
of syntax: a monitor that samples on the wrong edge invents failures that
do not exist and makes you lose days. Before opening the RTL, look at what the monitor says
it saw.
The fourth has a trap inside the trap: `get(null, "*", ...)` does not fail
—it gives back the first thing it finds— so the symptom is not "it does not find", it is
"it found somebody else's". The trace shows it; the `get` does not.
And to close: the last column is all there is. If the symptom is not here,
the next step is the waveforms, which is the tool that does
47 % of the work.

## Appendix · The 21 silent traps

#### *It compiles, it runs, and it lies*

| The symptom | The cause | How to head it off | Section |
| --- | --- | --- | :-- |
| The coverage gives **0 %** | the `new()` or the `sample()` of the covergroup is missing | one `sample()` per transaction, in the subscriber | Functional coverage |
| The daughter runs the method of **the mother** | without `virtual`, SV resolves by the **type of the variable**, at compile time | `virtual` on every method somebody is going to extend | Polymorphism |
| The component reads **somebody else's config** | `get(null, "*", …)` gives back the first thing that matches | `get(this, "", …)`, and `+UVM_CONFIG_DB_TRACE` | Tests |
| The test passes with **the wrong stimulus** | the `set_type_override()` arrived **after** the `create()` of the env | the override first, always. `+TOPOLOGY` gives it away | The env |
| The register model goes **green** and the field was never tested | the access starts with `WO`: `bit_bash` skips it and `do_check` drops it from the mask | if the field is readable, `WC` or `W1C`. `WO*` only if it really is not | RAL · d8 |

- None of these five gives a warning. None leaves the regression in red. All of them
  get discovered weeks later, or do not get discovered

Note:
This appendix is the one to print out and stick next to the monitor. They
are spread over seven sections because each one shows up when the
concept shows up, but they are needed together — and they are needed at the worst moment.
The thesis of the appendix is in the subtitle, and it is worth stating it as a general rule
of the craft: **in verification, the expensive mistake is not the one that breaks, it is the one that
lies.** A compilation error costs two minutes. A testbench that passes
measuring the wrong thing costs a tape-out.
The fourth row is the one that hurts the most in a big team, because whoever commits it
is not the one who suffers it: somebody adds an override in their test, somebody else moves
the `create()`, and the stimulus changes without anybody touching the stimulus file.
That is why the `+TOPOLOGY` of the agents is so cheap: it is ten seconds of reading
the tree UVM actually built, against the one you drew in your head.

---

## Appendix · The 21 silent traps

#### *The one publishing and the one listening*

| The symptom | The cause | How to head it off | Section |
| --- | --- | --- | :-- |
| The subscriber counts **0** and the monitor prints 1000 | the `connect()` in the `connect_phase` is missing | cross-check it: against what the one that already worked says | Analysis ports · d4 |
| The monitor **never publishes**, and the scoreboard screams | `bfm.command_monitor_h = this` is missing in the `build_phase` | the `uvm_fatal` shows up in the class that is **not** to blame | Analysis ports |
| The copy **loses the fields of the mother** | a `do_copy()` that does not call `super.do_copy(rhs)` | every `do_copy()` calls the one above first | Hierarchies |
| Two different transactions **compare equal** | `super.do_compare()` called on a loose line and thrown away | chained with `&&`, never loose | Transactions |

- The four have the same shape: **the one that fails is not the one that got it wrong.** That
  is why the first reflex —opening the file that screamed— is the wrong reflex

Note:
The `bfm.command_monitor_h = this` row is the one that teaches the pattern best, and
it is worth telling it as a story: whoever forgets that line sees a `uvm_fatal` from the
scoreboard, opens the scoreboard, and the scoreboard is perfect. The monitor —which is
the one that got it wrong— says absolutely nothing, because its `always` in the
interface never called it.
The rule that comes out of there, and that holds for all four: when something screams, go up a
layer. The one that reports a mismatch is the last of the chain; the bug is almost always
in the one feeding it.
The last two are the ones from the *deep operations* of the class hierarchies and it is worth
pointing out the asymmetry: `do_copy()` without `super` loses data in silence;
`do_compare()` without `&&` compares too few of them, and gives back *equal* for two objects
that are not. The second is worse, because it switches off the whole scoreboard without switching it off.

---

## Appendix · The 21 silent traps

#### *Stimulus, scope and objections*

| The symptom | The cause | How to head it off | Section |
| --- | --- | --- | :-- |
| The edge bins **never get filled** | `dist` with `:=`: the weight goes to **each** value of the range | measure the histogram **once**, with `:/` | Constrained random |
| The `randomize()` **does not run** with the asserts switched off | `assert(x.randomize())` — `assert` is a simulation directive | `if (!x.randomize()) uvm_fatal(…)` | Constrained random |
| Under the override, **some** transactions are of the old type | a `new()` where a `type_id::create()` belonged | what goes through the factory is what gets created with `create()` | Transactions |
| **Both agents** start up the same | two `set()` with scope `"*"`: the second overwrites the first | the scope is the **path** of the one that reads, with `*` at the end | Agents · d6 |
| The agent starts up **active** even though you set `is_active` in the `config_db` | the missing `super.build_phase()`: the one that reads it is `uvm_agent` | either a config object, or `super` — never half of each | Agents |
| The simulation **never ends** | an `item_done()` that was not called | `+UVM_TIMEOUT=5000000,NO` first, the trace after | Agents |
| It ends at **t=0** and says PASS | nobody raised the objection around the sequence | `+UVM_OBJECTION_TRACE` | Sequences |

Note:
The last two are the only ones on the list that do make noise — one hangs and
the other ends oddly — and they are here because the noise they make does not point at the
culprit. A hang does not say what was left waiting; a t=0 says PASS, which is
worse than an error.
The one about `assert(randomize())` deserves being told in full because it is the one most badly
copied from the internet: `assert` is not a function, it is a directive, and a simulator with
asserts disabled **does not execute the argument**. Which means the randomize
simply does not happen, the transaction gets sent with the previous values, and the
testbench carries on as if nothing had happened.
The one about the `new()` that eats the override is the subtlest of day 5, and it is worth
showing the number: in `add_test`, two of the transactions of the testbench were
built with `new()` and therefore were **not** `add_transaction`. Nobody
found out, because the scoreboard compared fine all the same.
And a closing recommendation for whoever is studying alone: read this appendix now and
again on the day something does not work. The first time you understand none of them; the
second you understand exactly the one that is happening to you.

---

## Appendix · The 21 silent traps

#### *The four from the assertions*

| The symptom | The cause | How to head it off | Section |
| --- | --- | --- | :-- |
| The log says **PASS** and the properties did not run | `--assert` is missing at compile time | the `cover property` at 0 is the only one that warns you | Assertions |
| The property **always passes** | the antecedent never occurs, or the implication is the one that is wrong | one `cover property` per `assert property` | Assertions |
| **145 false positives** and the DUT is healthy | you sample it with the edge it is written on | stimulus on `negedge`, response of the DUT on `posedge` | Assertions · d7 |
| False positives **at the start** of every test | the `disable iff (!reset_n)` is missing | `default disable iff`, once, at the very top | Assertions |

- The four are of the same family as the ones above, with one aggravating factor:
  a broken assertion **looks exactly the same** as one that works. There is no output
  to look at

Note:
These four reached the appendix with the assertions and they are the only ones on the list
where the check itself is what fails — the rest are bugs of the
testbench; these are bugs of the one checking the testbench. That is why the antidote is
always the same and that is why it is worth repeating it until you are sick of it: **one `cover
property` per `assert property`**.
The first row is the cheapest to commit in this flow and it is worth showing it
live: taking `--assert` out of the `run.sh` of `code/u8/assertions` leaves the run with `+BUG=1`
at 0 `UVM_ERROR`. The 154 failures disappear without anything warning you.
The third is the lesson of the section and the only one on the list that is not in
any tutorial. The wrong reflex, when the false positives show up, is to
loosen the property until it shuts up: there you are left without a check and with the
feeling of having fixed it. The right reflex is to ask on which edge
the one driving the stimulus writes.

---

## Appendix · The 21 silent traps

#### *And the one the clocking block brings*

| The symptom | The cause | How to head it off | Section |
| --- | --- | --- | :-- |
| The scoreboard fails **once every twenty** and the waveform looks fine | half the signals get read through `cb.sig` and the other half through `sig` | if it went into the clocking block, **the whole** protocol reads it through there | Interfaces and BFM |

- It is the only one on the list that **a tool adds**: without a clocking
  block it does not exist. Badly used it is worse than not using it
- Two names for the same wire, and they differ by one cycle:
  `code/u2/clocking/mezcla.sv` prints `3` and `4` at the same instant
- The variant of the same mistake: waiting for `@(posedge clk)` and then reading `cb.sig`.
  If you adopt the clocking block, you adopt **its event too**

Note:
This trap closes the appendix and it is the one that best sums up its thesis, because the
symptom is the worst of all the ones on the list: **intermittent**. The rest
fail always or never fail; this one fails when the data changes,
which is one run in however many and precisely the one you are not watching.
And it has a twist worth marking out loud: it is the only one on the list that
shows up *because* you used the tool that avoids another problem. The clocking
block takes the sampling race out and puts the possibility of this mixture in. It is not an
argument for not using it — it is the argument for using it **whole**, or not using it.
The rule in one line, which is Dave Rich's: if a signal belongs to the
timing contract of a clocking block, it is always accessed through that contract. The
long material is in `docs/clocking-blocks.md` (in Spanish).

## Glossary · the words of the trade

#### *What it is called on the job, and not in the textbook*

| What a textbook says | What gets said at work |
| --- | --- |
| coverage of the functionality / of the code | *functional* / *code coverage* |
| the test plan | *verification plan*, *coverage plan* |
| reaching full coverage | *coverage closure* |
| edge cases | *corner cases* |
| hand-written / random stimulus | *directed* / *constrained-random stimulus* |
| signal plots | *waveforms* |
| the random number seed | *seed* |
| the nightly test run | *regression* |
| the first chips back · redoing the masks | *first silicon* · *respin* |
| a check written for the simulator | *assertion* — and `assert property` never gets translated |
| reading a signal at a given moment | *sampling* — and the edge it happens on, the *sampling edge* |
| test bed, test harness | **testbench**, always — nobody says anything else |

- The concepts are the ones in the course; these are the exact words that the LRM, the
  *User Guide* and every answer you are going to find use. This table is the bridge

Note:
This slide exists because between knowing a concept and being able to look it up there is a
vocabulary, and it is the one nobody teaches: the student has just learned the
concepts and from tomorrow every search, every question on a forum and every
interview goes through these exact words.
The last row is not a joke. "Test bed" and "test harness" turn up in translated books
and in software, and **nobody says them here**: in an interview or in a mail to the team you
say testbench. The same with *coverage*, *seed* and *tape-out*.
A rule of thumb for work: the technical nouns are fixed and do not get paraphrased.
"Randomize the transaction", "run the regression", "this does not close coverage". It sounds like
jargon and it is how the trade talks.

---

## Glossary · The pieces

#### *One line each, to have them together*

| Word | What it is |
| --- | --- |
| *handle* | the name of an object — it is **not** the object |
| *factory* | the dictionary of types: you ask for the base class and you get the derived one |
| *override* | changing the type the factory hands out, without touching whoever asks for it |
| *transaction* | a piece of data that travels through the testbench: a `uvm_sequence_item` |
| *agent* | everything that knows how to speak one interface, in a box |
| *sequence* / *sequencer* | the stimulus (object) and the arbiter that hands it out (component) |
| *virtual sequence* | the one that sends no items of its own: it coordinates **several** sequencers |
| *driver* | turns a transaction into signals |
| *monitor* | watches the bus and publishes transactions |
| *scoreboard* | compares what came out against what should have come out |
| *subscriber* | anybody listening to an analysis port |
| *objection* | the *"I still have work to do"* that keeps the phase alive |
| *assertion* | a rule of the protocol written so the simulator checks it |
| *property* | the rule itself: clock, antecedent, implication, consequent |
| *antecedent* / *consequent* | the *"if"* and the *"then"* of a property |
| *cover property* | counts **how many times a property actually held**. The check of the check |

Note:
It is the slide to keep open while reading somebody else's code, and also the one that
serves as a quick review before an interview.
The two rows that get confused the most are *sequence* and *sequencer*, and the way not to
get them wrong is the one from day 6: the one ending in **-er** is the **component** —it is in
the tree, it has phases—; the other is the object that gets created, runs and is thrown away. The
same holds for *driver* and *monitor*. The rule is about the pieces of the tree
and not about the suffix: the UVM *policies* —`uvm_printer`, `uvm_comparer`,
`uvm_packer`, `uvm_recorder`— and the `uvm_report_catcher` end the same way and
are objects.
And the first row is the hardest one and the one that costs the most: *handle*. If the
student takes a single word away from this glossary, let it be that a handle is not an
object.
The *virtual sequence* row brings two more words along that are going to
show up in any production testbench: the *virtual sequencer*, which is a
component without a queue whose only contents are the handles to the real
sequencers, and `p_sequencer`, the handle already cast to that type that
`` `uvm_declare_p_sequencer `` declares for you.
A warning about *sequence*, which now shows up twice in the course with two
meanings: the UVM one is an object that generates stimulus; the SVA one
(`sequence ... endsequence`, the assertions) is a temporal expression —*"this, and three
edges later that"*— and has nothing to do with it. The context always tells them
apart, but the first time it confuses.

---

## Glossary · Three words that mislead

- **`virtual`** — in SystemVerilog it is **three unrelated things**: a *virtual
  method* (resolved by the object), a *virtual class* (abstract, it does not get
  instantiated) and a *virtual interface* (a handle to an interface). That they share
  the word is an accident of the language
- **`assert`** — in SystemVerilog it is **two things**: the *immediate* one, a statement
  that runs where the thread goes past, and the *concurrent* one (`assert property`), a
  declaration with a clock that gets evaluated on its own the whole simulation — the assertions. The
  `assert(randomize())` that is seen everywhere is the first one, and it is a poor
  way of checking a return value: that is why the course uses `` `uvm_fatal ``
- ***coverage*** — without a surname it means nothing. If somebody tells you "we are
  at 90 %", the question is always *code or functional?*
- And one of scale: a **test** in UVM is a **class**, not a file nor a
  run. The run is a *run*; the set of runs, a *regression*

Note:
The three are here because each one has already caused a confusion in the course, and
it is worth closing by naming them.
`virtual` was flagged in polymorphism and it comes back in the testbench in objects with the
virtual interface. The
question that sorts it out: virtual what? If it is a method, it looks at the object. If it is
a class, it does not get instantiated. If it is an interface, it is a handle.
The `assert` is the trap of the transactions and it is worth repeating why: it reports
outside UVM, it does not go into the Report Summary, and with the assertions switched off there are
simulators that do not even evaluate the expression — which means `randomize()` does not get called.
And the last row looks obvious until the first project meeting, where
"how many tests do you have" and "how many tests did you run last night" are two different
questions with two very different numbers.

## References

- **IEEE 1800-2017** — SystemVerilog Language Reference Manual. The final arbiter
  of every discussion about syntax.
- **IEEE 1800.2** / **Accellera UVM** — the methodology, and the *UVM User Guide*.
  You have the code of `uvm-core` on disk: `make uvm`.
- **Verification Academy** — Siemens EDA ·
  [verificationacademy.com](https://verificationacademy.com)
- **Salemi, Ray.** *The UVM Primer* — Boston Light Press, 2013. The book I
  learned UVM with, and where several of the examples in `code/` came from.
- **2024 Siemens EDA / Wilson Research Group Functional Verification Study**.
  Source of the **data** of Trends. The charts are our own: they are generated
  with `make figs` from `res/trends/data.json`.
- **On RAL**: the *Using the Register Layer Classes* chapter of the **UVM 1.2
  User’s Guide** from Accellera is the long explanation, and the table of the twenty-five field
  accesses —`RW`, `WOC`, `W1C`…— is in the **IEEE 1800.2**, under `uvm_reg_field`. What
  the unit does not use lives in the same place: `add_hdl_path` for the backdoor,
  and **IP-XACT** (IEEE 1685) or **SystemRDL** (Accellera) to generate the model instead
  of writing it.
- **On clocking blocks**, which is the liveliest discussion of the course: the
  threads by **Dave Rich** on Verification Academy (2014, 2022 and 2024), his paper
  *The Missing Link: The Testbench to DUT Connection*, and the **DV Coding Style
  Guide from lowRISC/OpenTitan**, which prescribes them as a rule. The summary, with the
  links and the quotes, in **`docs/clocking-blocks.md`** (in Spanish).

Note:
The list is ordered by when you are going to need it, and it is worth saying so.
The LRM and the *User Guide* are for consulting: nobody reads them straight through, you go and
look things up when there is a discussion about syntax or semantics. The Verification
Academy is the place where almost everything this course left out lives, and it is
free with registration.
About Salemi's book it is worth repeating what `docs/en-que-se-diferencia.md` (in Spanish) says: this
course does not replace it and does not follow it. If somebody wants a second pass over
the same concepts written by another person, it is the best one there is to start with.
And the point about the charts, because it is the part a student may want to
verify: the percentages of unit 1 are from the Wilson Research
Group study; the charts are our own and get regenerated with `make figs` from a JSON that
is in the repo. Nothing in unit 1 is an image downloaded from the internet.

---

## If you want to keep reading

<div class="creditos creditos-ref">
<a class="libro" href="https://www.amazon.com/UVM-Primer-Step-Step-Introduction/dp/0974164933" target="_blank" rel="noopener">


The book I learned with
The UVM Primer
Ray Salemi · Boston Light Press, 2013 · ISBN 978-0974164939

</a>
This course is not that book: it has another structure, another DUT, another simulator and four units of material the book does not cover. What it does share is credited in <code>NOTICE</code>, and the complete list of differences is in <code>docs/en-que-se-diferencia.md</code> (in Spanish).
</div>

Note:

It is worth saying out loud when you get here: the book is short, it is well
written and it is still the best way to start in English. If the course was of any
use to somebody, let them buy it.

---

## Credits

- Part of the examples in `code/` derives from those of the **UVM Primer**, published
  by its author under **Apache-2.0**. Here they stay under Apache-2.0, with the `NOTICE`
  the licence asks for and the list of changes.
- The course —`slides/` and `docs/`— is **CC BY 4.0**. The tools in `tools/`,
  **MIT**.
- The trend charts are our own, made from the published percentages
  of the Wilson Research Group / Siemens EDA study.
- **reveal.js** and **forkit.js** by Hakim El Hattab (MIT); the typefaces
  Chakra Petch and IBM Plex under SIL OFL 1.1.

Note:
This slide is not legal formalism, and it is worth saying why it is here: the course asks
to be cited, so it has to cite first. What was borrowed is
named, with its licence and with the list of changes in the `NOTICE`.
The practical part for whoever wants to reuse the material: **CC BY 4.0** the slides and the
docs, **Apache-2.0** the code, **MIT** the tools. It can be taught,
adapted, translated and charged for. The only condition is citing the source, and there is no
hidden "non-commercial" clause.
If somebody asks why three licences instead of one: because they are three different
things. The code derives from Apache-2.0 code and has to go on being that; the
slides are original work and CC BY is the one an academic setting understands; the
tools are software and MIT is what anybody copying them expects.

## This is as far as we got

#### *What you take with you*

- You know **why** verification exists as a discipline, and what the
  numbers of the industry say
- You wrote a conventional testbench, you measure it with **functional coverage**, and
  you know how to read the number that comes out
- You can read and write **OOP in SystemVerilog**: classes, inheritance,
  polymorphism, parameterized classes, the factory
- You built a **complete UVM testbench** —test, env, components, monitors,
  driver, scoreboard, transactions, agents and sequences— piece by piece,
  understanding what replaces what
- You wrote **assertions**: the other half of the plan, the one no scoreboard can
  close because it is not about the result but about the protocol
- And you handed it in: the **capstone** is a DUT you had not seen before, its
  spec, and the whole testbench from a blank sheet — which is literally what gets
  asked for at work
- And all of that runs on your machine, with **free tools**, without asking
  anybody for a licence

Note:
It is worth reading the list out loud and slowly, because after seven days nobody
has a sense of how much they saw. It is seven bullets and each one was a whole course
a week ago.
The one to underline is the last, and not out of activism: **all of this runs on
the student's machine**. There is no part of the course left in demo mode
because a licence is missing, and that means that the day they want to repeat an
example, try out an idea or show something to somebody, they can. Most of the
UVM material they are going to find from here on does not have that property.
And the honest clarification before the slide about what was left out, so nobody
leaves with the wrong idea: this is an **introductory** course, and what
follows is a list of what was not covered. Finishing it is not knowing UVM — it is being able to
read somebody else's testbench, write one of your own, and understand the next thing you
learn without it sounding like gibberish.

---

## What was left out

#### *and where to go on*

| Topic | Why you are going to run into it |
| --- | --- |
| `uvm_event`, `uvm_barrier` | The synchronization that is left when the objection is not enough |
| `uvm_heartbeat` | The one that warns you a component stopped showing signs of life in a regression of hours |
| `uvm_sequence_library` | A bag of sequences the sequencer picks from at random: the stress test without writing it |
| `uvm_pool`, `uvm_queue` | The collections of UVM. An associative array is enough until it has to be shared |
| **TLM2, phase jumps** | The limit of the course, and it is explicit |
| UPF, gate-level, PSS | Three worlds apart: low power, the netlist with delays, and generating the tests from a model |

- The three places to go on: the **LRM IEEE 1800-2017**, the *UVM User Guide*
  from **Accellera**, and **Verification Academy**
- And one almost nobody uses: the **code of `uvm-core`**. It is on your disk, in
  `code/.uvm/src/`, and by this point you can read it
- And if you get stuck: **[Discussions](https://github.com/leandrotozzi/verifythis/discussions)**,
  with one category per day. An example that does not run or an explanation that does not get
  understood are **issues of the course**, not problems of yours
- And if you want to go on right here: **day 8** is optional and starts after the
  self-assessment and *On Monday* — RAL, the reference model in C, and a second
  capstone

Note:
**RAL came out of this table and is now unit 9**, optional, with the example that
runs in `code/u9/ral/` and the exercise `d8-ral`. It is on **day 8**, after
this slide and not in the middle, because it is only understood once the student has already
written the scoreboard RAL replaces — and because as far as we know it is the first course that shows it
running on a free simulator. What was left out of RAL, and is said in
the unit: the backdoor and generating the model from IP-XACT.
The **`clocking block`** also came out of this table: it is half a section of
unit 2, with its example that runs in `code/u2/clocking/`.
The **callbacks** came out for the same reason: they are half a section of unit 7, with
the `code/u7/callbacks/` that injects the error in the driver — the third hook
unit 1 promises. And **regression and seeds** as well: the exercise `d7-semillas`
is the whole cycle, and `make regresion` left it as a tool, with a report of
the bins that were left open.
**SVA came out of this table and is now a whole unit**, and it is one of the most original things
the course has: no introductory UVM book brings it. The **virtual sequences**
came out too: they are the first hour of today, with an example that runs in
`code/u7/sequences/virtual/`.
The last three rows are worth reading out loud with this sentence in front: an
introductory course that lists what it does not cover is worth more than one that pretends
to cover everything. `uvm_heartbeat`, the sequence library and the collections get understood
in an afternoon when they are needed; UPF, gate-level and PSS are another career.
The last line is not a joke. After this course the student can open
`uvm_component.svh` and understand what `build_phase` does, because they saw every piece
the library hands them built by hand.
If there is time, open it live and look together for the `m_set_full_name()` that makes
the config_db find things. It is the best way to close the course: the
library stops being magic.

## Self-assessment

#### *Fifteen things you should be able to do by now · 1 of 3*

| Can I…? | Where it is |
| --- | --- |
| **1 ·** Explain why **47 %** of a verification engineer's time goes on debug, and what this course does about it | [Trends](libro/day1.html#trends) |
| **2 ·** Write a five-column **verification plan** for a DUT I have not seen before | [The verification plan](libro/day1.html#the-verification-plan) |
| **3 ·** Say why **100 % code coverage** does not mean the DUT is verified | [Functional coverage](libro/day1.html#functional-coverage) |
| **4 ·** Say what to look at **first** when a `covergroup` reports 0 % | [Functional coverage](libro/day1.html#functional-coverage) |
| **5 ·** Explain which race a `clocking block` avoids — and why they are **optional** anyway | [Interfaces and BFM](libro/day1.html#interfaces-and-bfm) |

Note:
This rubric is for the student, not for the instructor, and it is worth saying so:
nobody grades it. It is good for two different moments —before the exam, as a study
guide; and right now, as a diagnosis— and the instruction is the same in
both: read the statement and ask yourself *"can I explain it to somebody?"*, not
*"does it ring a bell?"*. The difference between the two answers is the whole course.
Every row links to the section of the **book**, which is the version to read straight
through, with the instructor note inside the text. A "no" is not bad
news: it is a link.
If it is being taught in class, project the three slides and ask for hands per row. The three
that get the most hands are the ones to review, and that measurement is worth more than
the complete review.

---

## Self-assessment

#### *Fifteen things you should be able to do by now · 2 of 3*

| Can I…? | Where it is |
| --- | --- |
| **6 ·** Extend a class and change its behaviour **without copying it**, and say what `super` does | [Classes and extensions](libro/day2.html#classes-and-extensions) |
| **7 ·** Change the class a testbench uses **without touching the `env`**, with a `set_type_override` | [The factory pattern](libro/day2.html#the-factory-pattern) |
| **8 ·** Explain why a UVM simulation **ends at t=0** if nobody raises an objection | [Tests](libro/day3.html#tests) |
| **9 ·** Say why `build_phase` runs top down and `connect_phase` the other way round | [Components and phases](libro/day3.html#components-and-phases) |
| **10 ·** Make a scoreboard that fails say **something more** than "it failed" | [Reporting](libro/day3.html#reporting) |

Note:
The 8 and the 9 are the two most often answered with a *"it rings a bell"*: they are mechanics of
the library and they are understood by looking, until the day you have to debug a
testbench that finishes without having sent any stimulus. If the student hesitates on
either of the two, the Tests section is half an hour and closes them.
The 10 is the one that pays off most in the long run and the one most underestimated. The whole course
points at the 47 % of row 1: a `uvm_error` that prints *"FAIL"* leaves whoever is
debugging exactly where they were, and one that prints the transaction, the
prediction and the time saves them half a morning. It is the difference between a
testbench that works and one you can work with.

---

## Self-assessment

#### *Fifteen things you should be able to do by now · 3 of 3*

| Can I…? | Where it is |
| --- | --- |
| **11 ·** Hang a new subscriber off an analysis port **without touching the one publishing** | [A single place that watches the wire](libro/day4.html#a-single-place-that-watches-the-wire) |
| **12 ·** Write a constraint that reaches a corner case, and **measure** whether the `dist` does what it says | [Constrained random](libro/day5.html#constrained-random) |
| **13 ·** Say what an agent with `is_active = UVM_PASSIVE` builds and what it does **not** | [Agents](libro/day6.html#agents) |
| **14 ·** Explain why a `uvm_sequence` **does not show up** in `print_topology()` | [Sequences](libro/day6.html#sequences) |
| **15 ·** Write a property that sees a protocol violation, and say why `--assert` is not optional | [Assertions (SVA)](libro/day7.html#assertions-sva) |

- All fifteen? Then what is left is the **capstone**: an APB slave, its
  spec, and the whole testbench from a blank sheet

Note:
The 14 is the question thrown out on day 1, when the UVM class diagram
shows up, and it gets answered on day 6. If the student can answer it, they understood the
division that explains half the library: `uvm_object` is the **data** and
`uvm_component` is the **structure**. An object gets created and thrown away; a component
gets built once and lasts the whole simulation.
The 12 says *measure*, not *write*, and it is on purpose: the exercise `d5b` exists
because a `dist` with the weights properly set can give a histogram that lies,
and whoever never measured it has no way of knowing.
And the last line is the only honest thing that can be said about the fifteen: they are
a necessary condition, not a sufficient one. What proves somebody knows how to do this is
a testbench of their own working, and that is the capstone. A student who ticks all
fifteen and does not finish it did not finish the course.

## On Monday

#### *What to do with this once the screen goes off*

- **First thing: a testbench of your own, running.** The capstone is the
  minimum. If it is already handed in, the next one is a DUT of yours — the one
  at work, the one from your thesis, whichever. A finished course proves nothing;
  a testbench does
- **Keep two pages and throw away the rest:** the one-page cheat sheet and *The
  21 silent traps*. They are the two you open with the simulator running
- **If you get stuck, ask here:**
  [Discussions](https://github.com/leandrotozzi/verifythis/discussions) has one
  category per day. An example that does not run is a **course issue**
- **And if something confused you, fix it.** It is CC BY 4.0 and the whole repo
  is there: the slides, the examples, the graders and the linters. A PR that
  clears up a slide is worth as much as one that adds a section

*Thanks for getting this far.*

Note:
The last slide of the course, and it is worth it being short and in the
imperative: after seven days nobody takes away one more new idea, but they do
take away one instruction.
The instruction is the first line, and it is worth saying it looking at the
camera or at the group: **the only thing that proves somebody can do this is a
testbench of their own, running**. Not the capstone marked, not the fifteen rows
of the self-assessment in green: one of their own, on a DUT nobody prepared to be
easy.
The second bullet is the most practical advice on the slide and the one most
thanked six months later. Of everything that got printed this week, what gets
opened again is two pages: the cheat sheet —`docs/en/uvm-cheatsheet.pdf`, one
page, A4— and the silent-traps table, which is written to be searched by symptom
and not to be read.
And the invitation in the fourth is not courtesy. The course improves where
somebody trips: half the presenter notes exist because somebody asked the same
thing twice. If it is taught in class, close by explicitly asking for the three
things that were not understood — and writing them down before the group leaves.

## Yesterday we left…

#### *Where the testbench stands*

- The capstone handed in: an APB slave, its spec, and a whole testbench written
  from a blank sheet — monitor, driver, scoreboard, coverage and properties
- The scoreboard of that testbench **predicts by hand** the value of every
  register, and the coverage of the bus was written row by row
- And that is done the same way at work… until the DUT has sixty registers. That
  is when both things get modelled, and that is the whole of day 8

Note:
This day is **optional and it goes after the wrap-up**, and both things are on
purpose. The course ends on day 7: whoever got that far wrote a complete UVM
testbench from a blank sheet and lacks nothing to go to work. What is here is
what gets added once that has happened.
The recap has a concrete job on day 8: the three pieces of today are only
understood as a replacement for something the student has **just written by
hand**. RAL replaces the register-by-register prediction, the golden model in C
replaces the whole prediction, and the second capstone shows where the pattern of
the first stops working. Without the capstone done, all three are abstractions
without a problem.

---

## Agenda

#### *Day 8 · ≈ 4 h · optional · what comes after the capstone*

- RAL, unit 9 — the register model over the same APB
- The reference model in C, through DPI
- The second capstone: a FIFO with backpressure

**By the end of the day you can:**

- **Read and write** a register by name, without writing a single `PADDR`, and
  say what the adapter and the predictor do
- **Plug in** a reference model written in C, and prove it with a mutation
- **Write** a scoreboard for a DUT where a table is not enough

Note:
For whoever teaches it: in a company this is another half day, and it usually
gets taught when the group has real registers in the project. In a term it is the
optional unit, or the final assignment for those who want a high mark.
The three objectives are deliberately concrete and not "understand RAL": day 8
has no row in the `175b` self-assessment, so the rubric the student takes away is
these three verbs and the eight-question review. The third is the one that pays off the most of the three and
the least expected — a FIFO has order and occupancy, and that does not fit in a
four-row table.

## RAL

#### *Unit 9 · optional · the register stops being an address*

- Every chip has configuration registers, and a small SoC has **two hundred**
- Without RAL, the testbench writes them like this: `addr = 8'h04`, `wdata = ...`, and the
  scoreboard keeps a `logic [31:0]` for each one
- The day the architect moves `SCRATCH` from `0x04` to `0x24`, you have to look for
  `8'h04` all over the testbench — and `0x04` was also the value of something else
- **RAL** —*Register Abstraction Layer*— is the layer that puts a name on that:
  `model.SCRATCH.write(status, 'h1000_0000)`
- It is optional and it goes at the end on purpose: **it is only understood once you have
  written the testbench it replaces**

Note:
This unit is short and it is the last one, and both things are deliberate. RAL is the
piece of UVM most often taught without context —there are courses that give it on day
2— and that way it is not understood: it looks like one more API. With the capstone just done,
on the other hand, the student has the comparison inside their head. They wrote the
scoreboard that predicts `CTRL`; now I show them the library that does it on its own,
and also where it does not.
The number of 200 registers is not rhetorical. A PHY block or a memory
controller has that many, and the register spec arrives as a spreadsheet. The
next step, which this course does not take, is **generating the model** from that spreadsheet
with IP-XACT or SystemRDL: nobody writes 200 registers by hand. It is worth saying, because
otherwise the student walks away with the idea that RAL is a lot of typing.
And the argument about moving `0x04` to `0x24` is the one that convinces a
sceptic: it is not elegance, it is that the map gets written **only once**.

---

## RAL

#### *Three pieces, and only one knows what bus is underneath*

| Piece | What it is | How many times it gets written |
| --- | --- | --- |
| `uvm_reg_block` | the map: registers, fields, addresses | one per **DUT** |
| `uvm_reg_adapter` | translates access ↔ bus transaction | one per **protocol** |
| `uvm_reg_predictor` | what the monitor saw, said in registers | none: it comes done |

- The model **does not know** there is an APB underneath. You change the adapter and the same
  model drives AHB
- The adapter is the file that comes with a VIP you bought. It is twenty lines
- And underneath everything, without a single change: the driver, the monitor and the agent of the
  capstone

Note:
The table is the slide. That the third column says *one per DUT*, *one per
protocol* and *none* is the whole economic argument for RAL, and it is the one that
holds the decision up in a project meeting.
It is worth pointing at the last line with a finger: nothing the student wrote yesterday gets
replaced here. `code/u9/ral/` compiles the interface, the transaction,
the driver, the monitor and the agent of `d7-final/solucion/` exactly as they are, through
`+incdir`. RAL is a layer, not a different testbench — and it is the reason why
this unit fits into three files.
If somebody asks about the backdoor: it exists, it gets declared with `add_hdl_path` and it reads
the signal of the RTL without going through the bus. It does not go into the course because it depends on the
hierarchy support of the simulator, which is precisely what changes between
tools. The frontdoor —the one that uses the real bus— is the one you have to know.

---

## RAL

#### *The model: the table of the spec, in code*

```sv
// 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
```

- A field gets declared with `configure()`, and the argument that matters is the
  **access string**: `"RW"`, `"RO"`, `"WC"`…
- That string **is the specification**. It is not documentation: it is what UVM uses
  to predict, and to generate the tests of *The tests you did not write*

Note:
`configure(parent, size, lsb_pos, access, volatile, reset, has_reset, is_rand,
individually_accessible)` — nine positional arguments, and it is the ugliest signature
in UVM. It is worth writing it on the blackboard once; afterwards the student copies it from the
example, which is what everybody does.
`CLR` is the field that justifies the slide. The spec of the capstone says *"writing a
1 puts `ACC` and `OVF` at zero, and the bit always reads 0"*, and that is trap 2
of the small print — the one that makes the hand-written scoreboard fail. The access
that says exactly that is **`WC`**: the write clears the field, the mirror goes down
to zero, and the read returns that zero. `W1C` works just as well here.
And here is RAL's silent trap, which is worth more than the slide. `WOC` —the name
you write first, because it sounds like "write-only, clears"— **also** gives zero
errors, but it gives them for the wrong reason: `uvm_reg_bit_bash_seq.svh:129-133`
skips every field whose access starts with `WO` (Accellera's own comment says
*"Ignore Write-only fields because you are not supposed to read them"*), and
`do_check` takes it out of the comparison mask (`uvm_reg.svh:2782-2788`), so the
`mirror(UVM_CHECK)` does not look at it either. With `WOC` bit 1 of `CTRL` is never
tested and nobody prints anything; the only trace is in the timing, because the
bashing of `CTRL` takes four transfers less. Green is not checked, and a `WO*`
access is the cheapest way there is to switch off a check without noticing.
The complete list of accesses is in the LRM 1800.2, and there are twenty-five. You do not have to
know them by heart: you have to know that **the list exists**, and look there before
inventing a `set_compare` or a callback. Half of the bad register models
you come across are an `RW` field with patches on top.

---

## RAL

#### *The adapter: the only thing that knows there is an APB*

```sv
   // 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
```

- `reg2bus` goes down: the model asks for a generic access, this builds the transaction
  of the bus
- `bus2reg` goes up: the transaction comes back —from the driver, or **from the monitor**— and this
  counts it in terms of an access
- `PSLVERR` turns into `UVM_NOT_OK`, and there the `status` of every `write()`
  stops being decorative

Note:
Twenty-two lines, and that is the whole file. It is worth saying the number out loud,
because RAL has a reputation for being heavy and the project-specific part is
this one.
The `reg2bus` / `bus2reg` symmetry is the one to fix: one function per
direction, and neither of the two has state. The `uvm_reg_bus_op` is the common
currency —`kind`, `addr`, `data`, `status`— and it is deliberately as flat as possible:
any register bus fits in there.
The `const ref` of the `reg2bus` comes from the signature of the base class and has to be copied
exactly. It works on Verilator 5.052, which was not obvious.
And a warning from the field: `bus2reg` is called **by the predictor too**, with the
item the monitor saw. An adapter that reads something from the driver —or that depends on
having built the transaction itself— works with automatic prediction and breaks
the day you switch to explicit. That is why both functions are pure.

---

## RAL

#### *Hooking it up: three lines and a `connect_phase`*

```sv
   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
```

- `set_sequencer` is what makes `model.CTRL.write()` end up in the driver:
  the model sends items through **the sequencer of the agent that already existed**
- `set_auto_predict(0)` switches off the automatic prediction, and the `uvm_reg_predictor`
  replaces it by listening to the **analysis port of the monitor**
- And the `model.build()` of the `build_phase`: a `uvm_reg_block` is a `uvm_object`,
  not a component. **Nobody calls it for you**

Note:
The phase trap that takes everybody's first afternoon is the last
line of the slide. `apb_reg_block::type_id::create("model")` gives back an object
with zero registers, because `build()` here is an ordinary method that gets called by hand
—not the `build_phase` of a component, which UVM walks on its own—. The symptom is a
`uvm_fatal` from `uvm_reg_map` that talks about a null register and does not mention the
word `build`.
The second thing to point out is where the sequencer comes from: it is
`agent_h.sequencer_h`, the same one from the capstone, the same one the normal sequences
run on. RAL does not bring a sequencer of its own. That means a register
sequence and a traffic one compete for the same driver, and there the
priorities show up — which is a topic for another course, but it is worth them knowing it exists.

---

## RAL

#### *Prediction: who tells the model what happened*

| | Who predicts | What happens if the DUT does something else |
| --- | --- | --- |
| **automatic** | the `write()` call itself | the model **does not find out**: it believes what it meant to send |
| **explicit** | the `uvm_reg_predictor`, from the monitor | the model believes **what happened on the wire** |

- The automatic one is one line fewer and it is the one that comes up in the tutorials
- The explicit one is the one to use, and for the same reason the scoreboard
  of the capstone looks at the monitor and not at the driver
- And it is free: the monitor and its analysis port **were already there**

Note:
This is the judgement slide of the unit and it is worth not rushing it. With
`set_auto_predict(1)`, `model.CTRL.write(status, 'h1)` updates the mirror at the
moment it gets called, before the bus has done anything. If the driver sends
the transfer wrong, or the DUT ignores it, the model goes on being convinced that
`EN=1`. It is exactly the design mistake the course has been attacking since day 1: **the
one who checks cannot believe the one who drives**.
With explicit prediction the path is the long and correct one: the driver drives,
the monitor sees the wire, the analysis port publishes it, the predictor calls
`bus2reg` and only then does the mirror change. It is the same drawing as the scoreboard, with
a piece of the library instead of a hand-written class.
The bonus, which can be seen in the example: since the predictor listens to the bus and not to the
calls, the model also finds out about the transfers **somebody else** made —
another sequence, another master, an ordinary module. Automatic prediction cannot
do that even in principle.

---

## RAL

#### *The whole path, from the call to the mirror*

![The RAL data path: from the write to the bus, and from the monitor to the mirror](../res/diagrams/en/ral_camino.svg)

- The way down is written; the way up —monitor, analysis port and `bus2reg`— **was there**
- The `uvm_reg_predictor` is not written: instantiate it and plug in the map
- The dashed one is `set_auto_predict(1)`: the shortcut not to take

Note:
This is the figure worth having on screen while reading the `connect_phase`: every
one of the three lines of that function is an arrow of the drawing.
`set_sequencer` splices the way down, `predictor.map`/`predictor.adapter` give the
predictor the two things it needs, and `agent_h.ap.connect(...)` is the arrow that
goes up from the monitor.
The symmetry is the point: the adapter shows up **twice**, once per direction, and
it is the only piece of the drawing that knows there is an APB underneath. Swapping
it for an AHB one moves those two boxes and no other.
And the right half is not RAL: the monitor, the analysis port and the agent are the
ones from the capstone, without a change. Worth saying it with a finger on the
drawing, because it is what explains that the unit fits in three files.
The dashed shortcut is the trap of the unit. With `set_auto_predict(1)` that arrow
is enough for the mirror to change, so the bottom half of the drawing turns
decorative: the model believes what the test meant to send, not what happened.

---

## RAL

#### *The stimulus, without a single `PADDR`*

```sv
      // --- 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)
```

- There is no address in any call: the address is **in the map**
- Nobody assigned the mirror. `get_mirrored_value()` gives back 1 because the monitor saw
  the transfer and the predictor counted it
- Underneath, the driver of the capstone is doing SETUP, ACCESS and the *wait state* of
  the read, the same as yesterday

`bash run.sh` · `code/u9/ral/`

Note:
It is worth running it live and looking at the log with `grep MONITOR`: for every line of
stimulus there is a complete APB transfer, with its address and its handshake,
done by the driver they wrote. It is the demonstration that RAL does not
replace the testbench, it drives it.
The line most worth discussing is `model.CTRL.read(status, data)` against
`model.CTRL.mirror(status, UVM_CHECK)`. Both read from the DUT. The difference is
that `mirror` compares against what the model believed **before** the read, and if
it does not match it reports a `uvm_error` without anybody writing a check. It is a
register scoreboard in one word.
And the third form, which is not on the slide and is worth naming: `set()` +
`update()`. `set()` changes the desired value in the model, without touching the bus, and
`update()` writes **only the registers whose desired value differs from the mirror**.
It is how a whole block gets configured at the start of a test, and it is where RAL stops
being convenient and starts genuinely saving simulation time.

---

## RAL

#### *The tests you did not write*

```sv
      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);
```

- Both come from `uvm-core`. **They know nothing about this DUT**: they read the model and
  generate the stimulus and the check out of it
- `uvm_reg_hw_reset_seq` reads everything after the reset and compares it with the reset
  value declared
- `uvm_reg_bit_bash_seq` writes and reads **every writable bit of every register**,
  one by one, in both directions

Note:
This pair of sequences is the RAL argument that wins discussions, because it does not
appeal to taste: they are two real tests, free, that on a block of 200 registers
cover 80 % of the bugs of address decoding and of fields wired the wrong way round.
There are more in the library and it is worth naming them: `uvm_reg_access_seq` (writes through
the frontdoor and reads through the backdoor, and the other way round), `uvm_reg_shared_access_seq` for
registers in more than one map, and `uvm_mem_walk_seq` for memories. The ones that
need a backdoor stay out of the course for what was said before.
The implementation detail worth telling, because it explains why the
model has to be right: `bit_bash` **does not skip** the read-only fields — it writes
the bit and demands that they read back as they were —, and it does the same with the
reserved bits, which it treats as `RO` (`uvm_reg_bit_bash_seq.svh:137-139, 149-152`).
What it really skips is the `WO*` family, `NOACCESS` and the fields with
`set_compare(UVM_NO_CHECK)`; `individually_accessible` it does not even look at. And
it uses the access string to know what to expect back. Which means the quality of the
test they give you is exactly the quality of the model you wrote.

---

## RAL

#### *And that is why the model is the spec*

```
    CTRL.CLR as "WC"   0 UVM_ERROR, and bit_bash did write bit 1
    CTRL.CLR as "RW"   2 UVM_ERROR, from uvm_reg_bit_bash_seq
    > Writing a 1 in bit #1 of register "model.CTRL" ...
      yielded 'h0000000000000000 instead of 'h0000000000000002
```

- One word changed in a string, and a sequence nobody wrote catches it
  with the number of the bit
- It is **trap 2** of the small print of the capstone —`CLR` never reads as 1— and
  there a whole scoreboard was needed to see it
- The register model is the only document of a project that is the spec **and**
  the code at the same time

`bash run.sh` runs both versions and compares them

Note:
This is the slide that justifies the unit, and the `run.sh` of the example produces it
on its own: it runs `builtin_test` with the model right and with `+MAL`, which declares `CLR`
as `RW`, and shows the two numbers side by side.
The punchline to say out loud: in the capstone, that same trap cost writing
a scoreboard, modelling the autoclear by hand and discovering the bug with a message
of your own. Here it costs **picking one word well**, and the error message is written by
Accellera, with the number of the bit inside.
The honest downside, which has to be said so it does not sound like a brochure: if you
get it wrong the other way round —you declare `RW` a field the DUT implemented as `RW`
when the spec said something else— the model and the DUT agree on the
mistake and no sequence says anything. The register model verifies the DUT
against **the spec written in the model**, not against the real spec. That is why the
review of the model against the document is still human work, and that is why
stage 1 of the exercise prints the map so it can be compared by hand.

---

## RAL

#### *What RAL does not do, and it has to be said*

```sv
      // 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);
```

- `ACC` and `STATUS` have an address, but **they are not registers**: their value gets
  produced by a write to *another* address
- A model predicts *"what I wrote is what I am going to read"*, and for these two that
  sentence is false. `set_compare(UVM_NO_CHECK)` says so in the model
- The accumulator goes on being checked where it already was: **in the scoreboard**, which is
  the one that knows how to add
- The read updates the mirror all the same — a read *is* a prediction

Note:
If they take a single idea away from this unit, let it be this one: **an address is not a
register**. RAL models addressable storage, and it does it very well. It does not
model behaviour. The accumulator of the capstone —which adds only with `EN=1`, which
overflows, which gets cleared with `CLR`— is behaviour, and that lives in the
scoreboard, as it lived yesterday.
The failure mode of not saying it is the worst of all and it is an everyday one: the team puts
RAL in, switches on `mirror(UVM_CHECK)` over the whole map, and the regression fills up with
errors on the status registers. Since they are false positives, somebody switches the
check off **entirely** — and from then on the model verifies nothing and nobody
finds out. The difference between switching off three named fields and switching off the global
check is the whole difference.
The two `UVM_WARNING` the example prints —`GET_MIRRORED_VAL/VOL`— are the
library saying the same thing on its own account: the mirror of a `volatile` field is not
evidence. They are in the output on purpose.

---

## RAL

#### *Summary of the unit*

- The **model** is the map of the spec in code, and the access string of each
  field is the part that verifies
- The **adapter** is the only thing that knows about the bus: twenty lines, once per
  protocol
- The prediction goes **through the monitor**, not through the call — the same rule as the
  scoreboard
- It gives you `hw_reset_seq` and `bit_bash_seq` for free, and it charges you knowing **what is not a
  register**
- And all of this runs on **Verilator 5.052**, which until today nobody had shown

Note:
The close of the unit and of the technical course. The last line is not marketing: when
writing this unit it was first tested whether `uvm_reg_adapter` and the frontdoor
worked on Verilator, before writing a single slide, and the result is
measured in `docs/en/verilator.md`. Everything the unit uses works: the model, the
adapter, the `uvm_reg_predictor`, `mirror(UVM_CHECK)` and the two sequences of the
library.
For whoever goes on alone, the order of what is missing: `uvm_reg_access_seq` with
a backdoor, generating the model from IP-XACT or SystemRDL —which is how it
is really done—, and `uvm_mem` for memories. All three are extensions of what
they saw here, not new topics.
And the bridge to the exercise: the first thing they are going to be asked for in a project with
registers is exactly this, with the spreadsheet of the spec on the left-hand side of
the screen.

## Exercise · Day 8 · 1 of 2

#### *Modelling the register map*

`cd code/ejercicios/d8-ral && cat README.md`

- It is **literally** the first thing you get asked for in a project with registers: they
  give you the table of the spec and you give back the model
- The DUT and the testbench are the ones from the capstone. The adapter, the predictor and the
  tests come from the unit. **The only thing you write is `apb_reg_block.svh`**
- Four registers, six fields, forty lines
- The checker goes in stages: the **map** —printed and compared with the table, without
  simulating anything—, the **accesses** —the two sequences of the library— and **what the
  model cannot predict**

Note:
It is the shortest exercise of the fifteen and the one most like a real task from
the first weeks of a project. Forty lines, and half of them are copying and
pasting the pattern of `CTRL`.
The stage that teaches is stage 1, and for a reason of method: the model gets **printed**
—`+UVM_TESTNAME=mapa_test`— and gets compared line by line against the register
table of the exercise README, before simulating anything. It is what has to be done with a real register
model, where the typical mistake is not about UVM but an offset copied
wrong from a 200-row spreadsheet.
Stage 2 is where `CLR` falls: whoever declared it `RW` passes stage 1 without
a problem and finds out here, with the number of the bit, thanks to a test they did not
write. It is worth letting them fall there — it is the moment when the RAL argument
stops being an opinion.
And stage 3 is the one that separates: it asks you to **switch off** a check, which is the opposite of
what the course has been asking for the last seven days. The justification has to come
from them: `STATUS.EN` changed because of a write to another address, the model
cannot know it, and a false positive that gets let through ends up with somebody switching
the whole check off.

## The reference model in C

#### *The scoreboard that rewrites the spec*

- The scoreboard of the course predicts **in SystemVerilog**: a `case` with the
  arithmetic of the VTALU. For five eight-bit operations it is perfect
- For a DSP, a codec or a crypto engine, that arithmetic **already exists, and in C**:
  the algorithm team wrote it, and it is against that model that the spec was signed off
- Rewriting it in SystemVerilog is maintaining **two** models and spending the project
  debugging the difference between them. That is not verifying: it is having two specs
- The way out is not to rewrite it. Verilator compiles to C++, so the model gets
  **linked inside the simulation**: no socket, no separate process, no IPC

Note:
This is the technique that separates a course testbench from a production one, and the
argument is not about convenience: it is about **authority**. In a project with serious
arithmetic, the spec is not a PDF — it is a program in C that somebody ran against a thousand
vectors before the RTL existed. A scoreboard that reimplements that
program in SystemVerilog does not verify the DUT against the spec: it verifies the DUT
against the reading the verification engineer made of the spec, which is another thing.
The question worth throwing at the group before showing the code: *"if the
C model and the scoreboard differ, who is right?"*. The uncomfortable answer
is that you do not know, and finding out costs days. With DPI the question does not
exist because there is only one model.
And the reason why this section is so cheap in this course: DPI is part of the LRM
and the commercial simulators ship it as a base feature —what leaves it out are the
free student editions—; what costs you in a commercial flow is the *toolchain*:
`-sv_lib`, compiling the `.c` separately, and remembering the library on every run.
Here the simulator compiles to C++ by design, so the bridge is one more file on the
command line and there is nothing to configure.

---

## The reference model in C

#### *`import "DPI-C"`: one declaration on each side*

```sv
   // 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);
```

```c
/* 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;
}
```

- The name after `"DPI-C"` is **the symbol the linker looks for**: it has to
  match letter by letter with the one in the `.c`
- An `input int` travels as an `int`; an `output int` arrives as an `int *`. A
  `function` cannot consume time; a DPI `task` can, but only declared `context` and
  calling back into an `export "DPI-C" task`
- The `.c` goes on the `verilator` line as one more source. **There is no DPI flag**

Note:
It is worth reading the two declarations side by side, because the symmetry is the whole
mechanism: the one above is the promise and the one below is who keeps it, and the
compiler does not cross-check them — the one who joins them is the linker, at the end. Out of that comes the
number one failure mode of DPI, which is worth naming before it shows up: an
*undefined reference* to a function that is written, right there, in plain sight. Almost
always it is one of two things — the name does not match, or the file got compiled as
C++ and the symbol came out with a mangled name.
That last one is literally what happens here: Verilator hands the user's sources
to the C++ compiler, so the `.c` needs the `extern "C"` that is
in the file. Without that guard, the example does not link and the error does not say why.
The type table of the LRM is longer —there is `svBitVecVal` for wide vectors,
`svOpenArrayHandle` for arrays— and it is not needed here. The rule of thumb: if the
data fits in an `int`, the signature writes itself; if not, you look up annex H of the
1800 and copy it.

---

## The reference model in C

#### *The scoreboard: the prediction gets asked for, not written*

```sv
   // 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
```

- It is **the only** difference from the scoreboard of the sequences. The monitor, the
  analysis port, the FIFO, the `do_compare` and the `uvm_error` do not change
- The golden model replaces the six lines of predicting, and no other piece
  of the testbench finds out there is C on the other side
- And the traffic goes both ways: the result comes back from C, and
  `vtalu_golden_bug(1)` goes from SystemVerilog to **change the state** of the model

Note:
The count is worth doing out loud because it is the design argument of the whole
unit: one six-line function changed and nothing else did. That happens because
the scoreboard was already well divided up —predicting and comparing are two jobs, and
they were in two methods—, and it is the late reward for having separated
`predict_result` from `write` three days ago.
The `int'(...)` line is the one to point at: the UVM types do not cross the
border. On the other side there is no `command_transaction`, there are three integers. When the
data is an object —an image, a packet, a matrix— what gets passed is a
pointer or an open array, and the one who decides the format is the C model, not the
testbench.
And the `vtalu_golden_bug` is not an ornament: **a scoreboard that has never seen an error
is not tested**. `run.sh` runs the same test against a mutated model —the
multiplication truncated to eight bits— and demands that the scoreboard scream. If it does not
scream, the testbench is comparing against itself and nobody was going to find out. It is
the same mutation test the checker of the capstone does with `+BUG=1`, from the
other side of the wire.

---

## The reference model in C

#### *What you gain, what you pay*

| You gain | You pay |
| --- | --- |
| **One single model**, the one that signed off the spec | the opcodes get synchronized **by hand**: one `enum` on each side |
| The model gets tested with the tools of C | an `undefined reference` does not say which of the two declarations is wrong |
| Arithmetic that in SystemVerilog is painful —floating point, matrices, crypto— | the C model runs in **zero time**: it cannot wait for an edge |
| Performance: it is a function call, not an IPC | a `segfault` in the model takes the whole simulation down with it |

- The rule for deciding: if the prediction **already exists in C**, DPI. If you write it
  yourself from scratch and it is five lines, a `case` in SystemVerilog and that is it
- It runs: `make u8/dpi` — two tests against the healthy model, and one against the mutated one

Note:
The table is what has to be left written down, and the row that gives the most discussion is the
first one on the right: the duplicated `enum`. It is real and it has no elegant solution
—the LRM does not share types between the two sides—, and it is the first thing to
look at when **all** the comparisons fail at once. If one in every
six fails, it is the DUT; if all of them fail, it is the mapping.
The third row on the right is the one that surprises and is worth getting ahead of: a DPI
`function` runs in zero time, so the C model cannot synchronize with the clock. That
is what `import "DPI-C" task` is for — with one clarification almost every tutorial
skips: C cannot block by itself. A DPI task consumes time **only** if it is declared
`context` and the C calls back into an `export "DPI-C" task` of SystemVerilog, which
is the one that waits for the edge. And there it is no longer a golden model, it is a
bus model, which is another topic.
The rule of the second-to-last bullet is the one to take away, because the risk of
this section is that somebody comes out wanting to do everything through DPI. The VTALU does **not**
justify DPI: five eight-bit operations get written in a `case` and read
better. The example exists so the technique has been seen when the DUT that does
justify it comes along, and that DUT arrives sooner than you think.

## Review · Day 8

#### *1 of 8 · The access string*

**`CLR` clears itself when you write a 1 to it. You declare it `"WOC"`, and `bit_bash` and `mirror(UVM_CHECK)` give zero errors. What happened?**

- [ ] Nothing: `WOC` is the access that describes a field that clears on a write
- [ ] `WOC` is not in the LRM, so UVM treats it as a plain `RW`
- [x] Both skip `WO*` accesses: that bit never got tested
- [ ] The predictor leaves the mirror at `x`, and a comparison against `x` always passes

> **Green is not checked** — `uvm_reg_bit_bash_seq.svh:129-133` skips every field whose access starts with `WO` (*"you are not supposed to read them"*), and `do_check` takes it out of the comparison mask (`uvm_reg.svh:2782-2788`). The only trace is in the timing: bashing `CTRL` takes four transfers less. The right access is `WC` (or `W1C`), and with it the bit does get bashed. A `WO*` access is the cheapest way there is of switching a check off without noticing.

---

## Review · Day 8

#### *2 of 8 · Automatic or explicit prediction*

**What changes between `set_auto_predict(1)` and hooking a `uvm_reg_predictor` to the monitor?**

- [x] With auto-predict the model believes what it **meant** to send, not what happened
- [ ] Nothing: the predictor is the internal implementation of auto-predict
- [ ] The predictor is faster: it does not build the bus transaction
- [ ] Auto-predict only works frontdoor, and the predictor works backdoor too

> **The one who checks cannot believe the one who drives** — with `set_auto_predict(1)`, `model.CTRL.write()` updates the mirror at the moment of the call, before the bus has done anything: if the driver sends the transfer wrong, the model stays convinced. With the predictor, the mirror only changes once the monitor has seen the wire. It is the same drawing as the capstone scoreboard, with a library piece instead of a hand-written class. And it is free: the monitor and its analysis port **were already there**.

---

## Review · Day 8

#### *3 of 8 · volatile*

**`STATUS` changes on its own, without anybody writing it. What are you saying when you declare it `volatile` in `configure()`?**

- [x] That the mirror is not evidence: the value can change without going through the bus
- [ ] That UVM is going to re-read it from the DUT before every comparison, to be safe
- [ ] That the field drops out of the map and stops having an address
- [ ] That it has to be read backdoor, because the frontdoor does not get there in time

> **The mirror stops being evidence** — a model predicts *"what I wrote is what I am going to read"*, and for a `volatile` field that sentence is false. The two `UVM_WARNING GET_MIRRORED_VAL/VOL` of the example are the library saying exactly that, and they are in the output on purpose. What does have to be checked gets checked where it is known: in the **scoreboard**, and in the model goes `set_compare(UVM_NO_CHECK)` on that field so that RAL does not invent an error.

---

## Review · Day 8

#### *4 of 8 · mirror() against read()*

**`model.CTRL.read(status, data)` and `model.CTRL.mirror(status, UVM_CHECK)`. How do they differ?**

- [ ] `read` goes over the bus and `mirror` stays in the mirror, with no transfer at all
- [ ] `mirror` writes the mirror into the DUT, to leave the two of them equal
- [ ] `read` updates the mirror and `mirror` does not touch it, so as not to hide an error
- [x] Both read from the DUT; `mirror` also compares against what the model believed

> **`mirror` is a register scoreboard in one word** — both read from the DUT; the difference is that `mirror` compares against what the model believed **before** the read, and if it does not match it reports a `uvm_error` without anybody writing a check. And a read *is* a prediction: both update the mirror afterwards.

---

## Review · Day 8

#### *5 of 8 · Who knows about the bus*

**What does the `uvm_reg_block` know about the APB?**

- [ ] The base address and the width of `PADDR`, which reach it through the `uvm_reg_map`
- [x] Nothing: the only one that knows about the bus is the adapter
- [ ] Everything: that is why there is one register model per protocol
- [ ] The SETUP and ACCESS timing, to predict the wait state of the read

> **The model does not know there is an APB underneath** — swap the adapter and the same model drives an AHB. The adapter is twenty lines, once per protocol, and it is the file that comes with a VIP you bought. Watch out for one thing: `bus2reg` is called **by the predictor too**, with the item the monitor saw, so an adapter that depends on something the driver put there works in one direction and fails in the other.

---

## Review · Day 8

#### *6 of 8 · DPI and time*

**Can an `import "DPI-C" function` of the golden model wait for a clock edge?**

- [ ] Yes, by putting a `#1` inside the `.c`
- [x] No: a `function` runs in zero time
- [ ] Yes, as long as the `.c` is compiled with Verilator's timing support
- [ ] Yes: the simulator suspends the C thread for the duration of the call

> **Zero time, like any `function`** — to consume time you need `import "DPI-C" task`, and with a clarification almost every tutorial skips: C cannot block by itself. A DPI task consumes time **only** if it is declared `context` and from the C it calls back into an `export "DPI-C" task` of SystemVerilog, which is the one that waits for the edge. And at that point it is no longer a golden model, it is a bus model.

---

## Review · Day 8

#### *7 of 8 · undefined reference*

**The `.c` is written and it compiles, and the link fails with *undefined reference* to the golden model function. What do you look at first?**

- [ ] Whether the DPI flag is missing from the `verilator` command line
- [ ] Whether the `.c` is in its own `-f` and not mixed in with the `.sv`
- [x] The name, and the `extern "C"`: the symbol may have come out mangled
- [ ] Whether the SystemVerilog `function` is declared `virtual` so the symbol gets exported

> **The compiler does not cross the two declarations: the one that joins them is the linker** — hence an error about something that is written, right there, in plain sight. It is almost always one of two things: the name does not match letter for letter, or the file got compiled as C++ and the symbol came out mangled. That last one is literally the case here: Verilator hands the user's sources to the C++ compiler, so the `.c` needs its `extern "C"`. And there is no DPI flag: the `.c` goes on the `verilator` command line like any other source.

---

## Review · Day 8

#### *8 of 8 · The scoreboard that never shouted*

**The scoreboard with the golden model in C runs a thousand operations and reports not one. Is that enough?**

- [ ] Yes: a thousand comparisons without a single difference is the definition of verified
- [ ] Yes, as long as the functional coverage closed at 100 % on top of that
- [ ] No, because both sides share the opcode `enum` and cancel each other out
- [x] No: a scoreboard that has never seen an error is not tested

> **The model has to be broken on purpose** — `vtalu_golden_bug(1)` mutates the multiplication and `run.sh` demands that the scoreboard shout. If it does not shout, the testbench is comparing against itself and nobody was going to find out: it is the same mutation test the capstone grader does with `+BUG=1`, from the other side of the wire. And the duplicated `enum` is real but it is a different symptom: if **every** comparison fails at once, it is the mapping; if one in six fails, it is the DUT.

## Exercise · Day 8 · 2 of 2

#### *The reference model in C, and the two mutations that prove it*

`cd code/ejercicios/d8-dpi && bash run.sh`

- The only file of the exercise is `vtalu_golden.c`. Not one line of the
  testbench gets touched
- Two operations are missing: the **subtraction with its borrow** —which goes out
  through a pointer— and the product with the mutation hook
- The checker runs three times: healthy DUT against your model, **mutated DUT**
  (`VTALU_BUG=1`), and your mutated model (`+GOLDEN_BUG`)

Note:
Stage 2 is what makes the exercise worth it, and it is worth explaining first:
against the healthy DUT, a model returning some fixed thing could pass by
accident if the stimulus were poor. With the DUT lying on bit 0, there is no way
of passing without having computed — it is the same mutation test as the
capstone, pointed at the model instead of at the scoreboard.
The subtraction is the one that trips people, and not because of the arithmetic:
`a - b` is one line. What gets forgotten is the **second half of the answer**,
the borrow, and it gets forgotten because it crosses the boundary in another way
—through a pointer, which is how a SystemVerilog `output int` travels—. The
scoreboard compares it, so without it every subtraction fails and no other
operation does: that pattern of failures is the one to learn to read.
And the trap you cannot see, which is solved in the skeleton on purpose so they
do not lose the hour there: without `extern "C"`, Verilator hands the file to the
**C++** compiler, the symbol comes out mangled, and the link fails with an
*undefined reference* to a function written two lines above. It is DPI's number
one failure mode with Verilator.

## Capstone 2 · Day 8

#### *The second final: a FIFO with backpressure*

`cd code/ejercicios/d8-fifo && cat spec.en.md`

- For whoever has already handed in the APB. **The protocol is simpler** —there are no
  addresses, no wait states, no error response— and even so it is harder
- The APB one is a slave **with no useful memory**: an address and a value, and the
  scoreboard can be a table of four rows. A FIFO has **order** and
  **occupancy**, and both have to be carried
- The bug of `+BUG=1` is not a data bug: `almost_full` goes up **one place late**.
  The data still comes out right and in order, so a scoreboard that only
  compares `rd_data` passes green
- The small print: the flags describe the state **before** the edge,
  `rd_data` arrives **one cycle late**, writing with the FIFO full is **not an
  error**, and a simultaneous read **makes room** for the write

Note:
This is the exercise that separates whoever understood from whoever copied the pattern, and the
mechanism by which it separates is in the third bullet: the bug is in a **control
output**, not in the data path. A scoreboard that compares what
comes out of `rd_data` closes six of the seven rows of the plan and passes green
with the DUT broken. To see it the flags have to be predicted, and to predict the
flags the occupancy has to be modelled — that is, writing a reference model
with state, which is what the first capstone could not ask for.
It is worth saying why it goes second and not first: the APB is the DUT you run into in the
first year, and the table-address-value pattern is the right one there. This one teaches
when that pattern stops being any use, and that lesson is not understood without having used
the pattern before.
The trap that catches the most people is the order of updating the model: first look
at whether the read takes something out —that frees a place— and only then whether the write goes in.
The other way round, the simultaneous write with the FIFO full shows up as a lost piece of data
that the DUT never lost, and the student spends an hour looking for the bug in the RTL.
And the second one: the `check_phase` that claims data that never came out. Almost
always the test ended one cycle too early, and it is the `drain_time` of day 3
showing up where nobody expected it.