Register Callbacks II: Prediction and the Backdoor
Keep related mirrors consistent with post_predict: an alias, a counter that another register clears, a lock. Give a backdoor the transform its storage needs, after measuring why encode and decode do not do it in uvm-core 2020.3.1.
You Will Be Able To
- Write
post_predictcallbacks for an alias pair, a clear on another register's write, and a lock. - Say which predictions run
post_predictand which do not. - Put a storage transform inside a user backdoor.
- Explain why
encodeanddecodecallbacks have no effect in uvm-core 2020.3.1.
- Lesson
- U18.8
- Time
- 30 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
A memory stored each byte XORed with a5. The team added a decode callback to the backdoor, as the standard describes, and peek still returned scrambled bytes. The callback ran on every peek; its result never reached the item.
| Backdoor | Bus wrote 77 at offset 2; peek returns |
|---|---|
| Raw, with a decode callback | d2 |
| Unscrambles in read_func (the fix) | 77 for what the bus wrote |
Measured in the example: the stored byte is 77 ^ a5 = d2.
post_predict Runs When the Mirror Changes
post_predict(fld, previous, value, kind, path, map) is a field callback. The field calls it after every write prediction (kind UVM_PREDICT_WRITE) and read prediction (UVM_PREDICT_READ). Auto prediction, the U13.3 predictor and backdoor accesses all predict. value is an inout: the callback may change what the mirror becomes.
A direct predict (UVM_PREDICT_DIRECT) does not call it. That makes cross-register rules safe: a callback that predicts another register does not start a chain back.
| Rule | post_predict on | Does |
|---|---|---|
| Alias: two addresses, one storage | each register's field | predict the other register with value |
| Clear on another write | the writing register's field | predict 0 for the cleared field |
| Lock: a field ignores writes | the locked field | set value = previous while locked |
Each rule changes the model's mirror only; the bus is untouched.
Keeping an Alias Pair Equal
CFG at 08 and CFG_A at 0C are one byte in the design. Each register's field gets an alias_cb that predicts the other register. A write through either address now leaves both mirrors equal. So does a read after the design changed the byte by itself.
Remove the callback from CFG_A's field and the pair drifts: after cfg_a.write(5a) the CFG mirror stays 3c. A post_predict callback runs only for the field it is added to.
A Clear and a Lock
In the slice, STATUS counts CMD writes, and command 00 clears the count. STATUS's own hooks never run for a CMD write. So count_cb sits on CMD's field: on each write prediction it predicts STATUS, 0 for command 00 and one more otherwise.
Once CTRL's lock is 1, the design ignores CTRL writes. The bus transfer still happens, though, and auto prediction would take the new value. lock_cb, on both CTRL fields, sets value = previous for a write while the mirrored lock is 1. The mirror keeps 13 after ctrl.write(07).
lock_cb on the mode field only
uvm_reg_field_cb::add(regs.ctrl.mode, lk);
The lock field takes the written 0: mirror 03, design 13 (the quiz predict).
lock_cb on both fields
uvm_reg_field_cb::add(regs.ctrl.mode, lk);
uvm_reg_field_cb::add(regs.ctrl.lock, lk);
Mirror 13, design 13 (the example).
The fields of one register are predicted in order, mode before lock. So while mode is predicted, the lock mirror still holds the value from before this write, which is the one that counts.
The Backdoor Hook Points
A user backdoor (U14.1) overrides write and read_func. The base read calls do_pre_read, then read_func, then do_post_read; the base write is a fatal stub, so your write decides whether to call do_pre_write and do_post_write. These run the backdoor's own pre_*/post_* methods and the callbacks of uvm_reg_bd_cb (uvm_callbacks #(uvm_reg_backdoor, uvm_reg_cbs)).
Two of those callbacks are for storage that is not plain: decode on reads and encode on writes. The standard intends them for scrambled or ECC storage.
- Test
- Neutral
- Storage
- Step
- Control
- Data
- Read the storage
read_funcputs the stored byte, d2, into the item.Follow the calls, values and waits
- return d2: tb.dut.mem[2] → raw_backdoor
- Decode a copy
do_post_readcopies the item's value array into a local array and passes that todecode. The callback turns d2 into 77 in the copy.Follow the calls, values and waits
- data 77 in the copy only: a copy of the value array → unscramble_cb
- The copy is dropped
Nothing copies the array back into the item, so
peekreturns d2. The fix is a backdoor that unscrambles inread_func.
Read the diagram as text
- Test: regs.mem.peek(st, 2, v)
- raw_backdoor: read(): do_pre_read, read_func, do_post_read
- tb.dut.mem[2]: stored byte d2
- a copy of the value array: get_value_array copies
- unscramble_cb: decode: data[0] ^= a5
- Test → raw_backdoor: read(rw)
- raw_backdoor → tb.dut.mem[2]: read_func
- raw_backdoor → a copy of the value array: get_value_array
- a copy of the value array → unscramble_cb: decode(copy)
Standard behaviour: decode and encode transform backdoor data. Measured on uvm-core 2020.3.1: their changes are lost.
What Uvm-Core 2020.3.1 Does with Encode and Decode
do_post_read calls rw.get_value_array(value_array), which copies the item's dynamic array into a local one, and passes the local array to decode. Nothing writes the local array back. do_pre_write does the same for encode. The callbacks run; their changes are lost.
A raw backdoor plus callbacks
uvm_reg_bd_cb::add(raw, unscr);
regs.mem.peek(st, 2, v); // d2
decode ran once; peek returned the stored byte.
The transform in the backdoor
rw.set_value(tb.dut.mem[off] ^ 8'ha5, 0);
regs.mem.peek(st, 2, v); // the plain value
peek and the bus agree.
Try It
The two alias callbacks keep the mirrors equal in both directions. count_cb follows STATUS through two commands and the clear; lock_cb keeps CTRL at 13 when the locked design ignores 07.
The raw backdoor shows both backdoor callbacks running and changing nothing. peek returns the stored d2, and a poke of 11 is stored as 11, read by the bus as b4. The plain backdoor agrees with the bus.
Remove count_cb and run again: the STATUS mirror stays 00 while the design counts.
cfg.write(3c): cfg mirror 3c, cfg_a mirror 3c cfg_a.write(5a): cfg mirror 5a, cfg_a mirror 5a cmd.write(07), cmd.write(09): status mirror 02, design 02 cmd.write(00): status mirror 00, design 00 ctrl.write(13) then ctrl.write(07): ctrl mirror 13, design 13 raw backdoor + decode callback: frontdoor wrote 77, peek returns d2, decode ran 1 time(s) raw backdoor + encode callback: poke 11, frontdoor reads b4, encode ran 1 time(s) plain backdoor: peek returns b4 plain backdoor: poke 22, frontdoor reads 22Check Yourself
Common Mistakes
Wrong Copy previous to the other register in post_predict.
previous is the old mirror; the new one is value.
Fix Predict the other register with value.
void'(other.predict(previous));void'(other.predict(value));Wrong Keep the alias with other.set(value).
set changes the desired value only; the other mirror stays stale.
Fix Use predict, which sets the mirror and the desired value.
Wrong Describe scrambled storage with a decode callback on a raw backdoor.
uvm-core 2020.3.1 passes decode a copy and throws it away, so peek returns the scrambled value.
Fix Unscramble in the backdoor's read_func and scramble in its write.
Remember
post_predictruns for write and read predictions and may changevalue; a directpredictruns no callbacks.- An alias pair needs a callback on each register's field that predicts the other with
value. A clear sits on the writing register's field; a lock setsvalue = previous. - Backdoor callbacks run through
do_pre_read,do_post_read,do_pre_writeanddo_post_write; yourwritemust call the write pair. - In uvm-core 2020.3.1
encodeanddecodechange a copy only: put storage transforms in the backdoor itself.