Register Callbacks I: Access Hooks
Hook register and memory accesses with uvm_reg_cbs. Know the order of field and register hooks, and where uvm-core departs from the standard. Refuse an access before the bus, list a register's callbacks, and use the library's read-only and write-only callbacks.
You Will Be Able To
- Predict the order of field and register hooks around one register write, in the standard and in uvm-core 2020.3.1.
- Refuse an access in
pre_writeso no bus transfer happens, reading the old value from the mirror. - Hook reads (
pre_read,post_read) and memories (uvm_mem_cb), and list callbacks withuvm_reg_cb_iter. - Say when the map adds
uvm_reg_read_only_cbsanduvm_reg_write_only_cbsby itself.
- Lesson
- U18.7
- Time
- 30 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
In this register slice the CTRL mode only rises: the design ignores a write that lowers it. The test lowered the mode, the bus transfer went out, and auto prediction set the mirror to the new value. The design still held the old one, and a later mirror check failed far from the cause.
| CTRL at mode 9, write 03 | Bus transfers | Status | Mirror | Design |
|---|---|---|---|---|
With the ratchet in the mode field's pre_write (the example) | 0 | UVM_NOT_OK | 09 | 09 |
Measured in the example: the callback refuses the write before the bus, so the model and the design still agree.
Where the Hooks Run
uvm_reg_cbs is the hook class of the register layer. Its tasks pre_write, post_write, pre_read and post_read receive the uvm_reg_item of the access. The pools are typedefs: uvm_reg_field_cb for fields, uvm_reg_cb for registers, uvm_mem_cb for memories and uvm_reg_bd_cb for backdoors.
Each field, in order
The field's own
pre_writemethod, then its callbacks in add order. A callback may change the field value:mode_legalturned c into 9.mode c -> 9lock 0The register
The register's
pre_writemethod, then its callbacks. They see the merged value.value 09Status check
If any hook set a status other than
UVM_IS_OK, the access ends here: no transfer, no prediction.lowered mode ends hereThe bus
The adapter turns the item into a bus transfer; auto prediction updates the mirror.
APB write 00 data=09Post hooks
Register callbacks, then the register method; then for each field its callbacks, then its method.
order callbacks before methods
These steps are what uvm-core 2020.3.1 does; the example prints every hook, so you can read the order from the log. Reads follow the same plan with pre_read and post_read.
| Pre hook | Standard (§18.11.2.2 b) | uvm-core 2020.3.1 (measured) |
|---|---|---|
| First | register method, register callbacks | each field: method, callbacks |
| Then | each field: method, callbacks | register method, register callbacks |
| A register callback sees | the value as written | the value after field callbacks changed it |
Write portable callbacks so that neither level depends on the other having run first.
The judgement this leaves you: a register-level check sees field edits (like 9 for c) only on uvm-core. Put a rule that needs the edited value on the field that edits it, or repeat the edit in the check.
- Model
- Step
- Control
- Data
- Fields first (uvm-core)
Each field runs its own
pre_writemethod, then its callbacks.mode_legalchanges the reserved mode c to 9. - Then the register (uvm-core)
The register's method and callbacks see the merged value 09. Standard behaviour (IEEE 1800.2-2020 §18.11.2.2 b): the register runs before its fields.
- One check
After all pre hooks comes one status check. OK goes to the bus; anything else returns at once, with no transfer. On the second write
mode_ratchetsetUVM_NOT_OK. - Post hooks
After the transfer, callbacks run before methods: register, then each field. Here uvm-core and the standard agree.
Read the diagram as text
- mode field: method, then mode_legal (c -> 9), mode_ratchet, mode_log
- lock field: method, then lock_log
- ctrl register: method, then ctrl_log; value 09
- status check: UVM_NOT_OK: stop here
- APB write 00: then auto prediction: mirror 09
- post hooks: register callbacks, method; per field callbacks, method
- mode field → lock field: next field
- lock field → ctrl register: merged value
- ctrl register → status check: all pre hooks done
- status check → APB write 00: UVM_IS_OK
- APB write 00 → post hooks: transfer done
Measured on uvm-core 2020.3.1 with Verilator 5.052. Only the pre hooks depart from the standard: fields before the register.
Refusing an Access Before the Bus
ratchet_cb is a field callback on CTRL's mode. In pre_write it compares the new mode with the mirrored one; if the new mode is lower, it sets the item's status to UVM_NOT_OK. The other pre-write hooks still run, then do_write returns before the bus. The mirror stays at 09, and write returns UVM_NOT_OK.
Ratchet in post_write
task post_write(uvm_reg_item rw);
if (rw.get_value(0) < mode.get_mirrored_value())
rw.set_status(UVM_NOT_OK);
endtask
Too late: the transfer went out and the mirror already holds 3, so the check never fires.
Ratchet in pre_write
task pre_write(uvm_reg_item rw);
if (rw.get_value(0) < mode.get_mirrored_value())
rw.set_status(UVM_NOT_OK);
endtask
No transfer, mirror unchanged (the example).
A register callback that sets UVM_NOT_OK stops the access too. The status check comes after the field and register pre hooks, whichever ran first. Put the check where its rule lives: this rule is about one field, so it sits on the field.
One value is already changed when your hook runs: write sets the desired value first. The refused write leaves desired 03 and mirror 09, so a later update would try to send 03.
Memories have the same hooks. uvm_mem_cb::add(regs.mem, cb) attaches a callback to a memory; rw.get_offset() says which word. A memory's pre_write or pre_read can refuse the access the same way. In the example mem_log prints offset 2 around a write and a read.
Read-Only and Write-Only Registers at One Address
STATUS (read-only) and CMD (write-only) share address 04. The library has two singleton callbacks for this. uvm_reg_read_only_cbs refuses writes with UVM/REG/READONLY; uvm_reg_write_only_cbs refuses reads with UVM/REG/WRTEONLY. Each sets UVM_NOT_OK before the bus.
You do not add them for such a pair. When add_reg finds a read-only and a write-only register at one address, the map adds both callbacks itself. In the example status.write and cmd.read are refused although the test added nothing; adding them again only prints CBPREG.
To see what is attached, walk the register's pool with uvm_reg_cb_iter: first(), then next() until null. Fields have uvm_reg_field_cb_iter, memories uvm_mem_cb_iter. In the example STATUS lists the map's uvm_reg_read_only_cbs before the test's status_log.
Add the read-only callback yourself when a register must refuse writes on its own. An example is a register that a lock turns read-only. remove takes it off again.
What to Hook, and What to Subclass
| Use | Hook | Why there |
|---|---|---|
| Protection: lock, mode, privilege | register or field pre_write, pre_read | Runs before the bus; can refuse |
| Legal values, reserved bits | field pre_write | Can change the field value |
| Access log or audit | post_write, post_read | Sees the final value and status |
| Coverage of accesses | post_write, post_read | Counts only accesses that happened |
| Cross-register rules | post_predict | Runs after each read or write prediction (U18.8) |
Register callbacks add behaviour to a generated model without editing it.
A generated register model is regenerated when the specification changes, so edits inside its classes are lost. Callbacks live in your bench and survive regeneration. Subclass a register only when its own methods must change for every user.
Try It
The first write prints every hook in uvm-core's order, fields before the register, with the field callback changing mode c to 9. The second write is refused by mode_ratchet: the other pre hooks still print, but no APB line follows, and the mirror stays 09. The two UVM_ERROR lines come from the library's read-only and write-only callbacks.
The iterator shows what is attached: the map's singletons and the test's status_log. The read and the memory accesses print their pre_read, post_read and memory hooks; the memory stores 5a scrambled as ff.
Move the ratchet's check into post_write and run again: an APB write appears, the mirror becomes 03, and the design still holds 09.
ctrl.write(0c): mode c, lock 0 mode.pre_write method value=c mode_legal.pre_write callback value=c -> 9 mode_log.pre_write callback value=9 lock.pre_write method value=0 lock_log.pre_write callback value=0 ctrl.pre_write method value=9 ctrl_log.pre_write callback value=9 25 ns APB write 00 data=09 ctrl_log.post_write callback value=9 status=UVM_IS_OK ctrl.post_write method value=9 mode_log.post_write callback value=9 status=UVM_IS_OK mode.post_write method value=9 lock_log.post_write callback value=0 status=UVM_IS_OK lock.post_write method value=0 status=UVM_IS_OK mirror=09 dut=09 ctrl.write(03): lowers the mode mode.pre_write method value=3 mode_ratchet.pre_write callback refuses: 3 is below 9 mode_log.pre_write callback value=3 ctrl_log.pre_write callback value=3 status=UVM_NOT_OK transfers=0 mirror=09 desired=03 dut=09 status.write(01): STATUS is read-only status=UVM_NOT_OK transfers=0 commands taken=0 cmd.read: CMD is write-only status=UVM_NOT_OK transfers=0 callbacks on STATUS: uvm_reg_read_only_cbs status_log callbacks on CMD: uvm_reg_write_only_cbs cmd.write(07) then status.read status_log.pre_read callback 85 ns APB read 04 data=01 status_log.post_read callback value=1 status=UVM_IS_OK 1 command(s) taken mem.write(2, 5a) then mem.read(2) mem_log.pre_write callback offset=2 value=5a 115 ns APB write 48 data=5a mem_log.post_write callback offset=2 value=5a status=UVM_IS_OK mem_log.pre_read callback offset=2 145 ns APB read 48 data=5a mem_log.post_read callback offset=2 value=5a status=UVM_IS_OK read 5a, stored ffCheck Yourself
Common Mistakes
Wrong Refuse a write that breaks a rule in post_write.
The transfer has already happened and auto prediction has already moved the mirror.
Fix Set UVM_NOT_OK in pre_write (or pre_read), before the bus.
Wrong Compare the new mode with mode.get() inside the callback.
write sets the desired value to the new value before any hook runs, so get returns the request itself.
Fix Use get_mirrored_value(), the model's view of the design.
if (rw.get_value(0) < mode.get())if (rw.get_value(0) < mode.get_mirrored_value())Wrong Add uvm_reg_read_only_cbs to a read-only register that shares its address with a write-only one.
The map already added it when it mapped the pair, so each add only prints CBPREG.
Fix Add it yourself only for a register that must refuse writes on its own.
Remember
- Pre-hook order: the standard runs the register before its fields; uvm-core 2020.3.1 runs the fields first. Post hooks run callbacks before methods, register then fields, in both. Do not depend on the pre order.
- A status other than
UVM_IS_OKafter the pre hooks ends the access with no transfer and no prediction. - Read rules from the mirror:
writehas already set the desired value. - Memories take callbacks through
uvm_mem_cb;uvm_reg_cb_iterand its field and memory twins list what is attached. - The map adds read-only and write-only callbacks itself for a pair at one address; add them yourself only for a register alone.