UVM RAL · Chapter 5 · Adapters

reg2bus() & bus2reg()

The adapter's two methods, reg2bus and bus2reg, form a codec: an encoder and a decoder over one common format, and getting the codec exactly right is where an adapter is correct or subtly wrong. That format is the generic bus operation, whose fields are worth naming: the kind of read or write, the address, which is a byte address by RAL convention, the data, the access width, and the byte-enable mask. reg2bus encodes this into a concrete bus item, and bus2reg decodes a bus item back into it. The rule is that they must be exact inverses, because bus2reg is also called by the predictor on every transaction it merely observes. If bus2reg does not reconstruct exactly what reg2bus sent, the mirror drifts. This lesson details the fields, the inverse contract, and the byte-versus-word address subtlety, then breaks an adapter that puts a byte address on a word-addressed bus so every access lands on the wrong register.

Foundation12 min readUVM RALreg2busbus2reguvm_reg_bus_opAddress GranularityPredictor

Chapter 5 · Section 5.3 · Adapters

1. Why Should I Learn This?

The codec is the adapter, and codec errors are the hardest adapter bugs to see because they are correct in one direction or for one case and wrong in another. An address conversion that works for offset 0x00 (which is 0 either way) fails for every other register; a data placement that is right for writes is wrong for reads; an encoding that reg2bus does one way and bus2reg decodes another passes a frontdoor round-trip but drifts the mirror through the predictor. Understanding the uvm_reg_bus_op fields and the exact-inverse contract is what lets you write a codec that is correct for every register, both directions, and both the frontdoor and the predictor.

Learning the methods in depth — especially the byte-versus-word address granularity that trips up nearly every first adapter — is what turns 'the adapter mostly works' into 'the adapter is correct.' It is the precise version of 5.2's overview.

2. Industry Story — the adapter that worked only at register zero

An engineer writes an adapter for a word-addressed bus — a bus where each successive address selects the next 32-bit word, so word 0 is register 0x00, word 1 is register 0x04, word 2 is 0x08. In reg2bus, they copy RAL's rw.addr straight into the bus item's address field. It passes their first smoke test, which happens to exercise the register at offset 0x00.

Every other register is wrong. RAL's rw.addr is a byte address, so the register at offset 0x08 arrives as rw.addr = 0x08, and putting that byte value onto a word-addressed bus selects word 8 — byte address 0x20 — an entirely different register. So a write to CTRL at 0x08 lands on the register at 0x20, a read of STATUS at 0x04 selects word 4 (0x10), and only register 0x00 (where byte and word address coincide at 0) is ever correct. Because the smoke test used 0x00, the adapter looked fine; the failures appeared as bizarre, register-specific corruption once real tests exercised the map, and looked like a decode bug in the DUT. The fix is one shift: on a word-addressed bus, item.addr = rw.addr >> 2. The lesson: RAL's addr is a byte address; the adapter must convert it to the bus's addressing granularity, and forgetting to means only register zero works while every other access lands on the wrong register.

3. Concept — the bus_op fields, the inverse contract, and granularity

The uvm_reg_bus_op is the codec's common format:

kind — UVM_READ or UVM_WRITE. Selects the transaction type and which data field is meaningful.
addr — the register's address, a byte address by RAL convention. The adapter converts it to the bus's granularity (byte-addressed: use as-is; word-addressed: shift).
data — the value. On a write, reg2bus reads it as the write data; on a read, bus2reg fills it with the returned read data.
n_bits — the width of this access. Relevant for buses that carry the access size, or for splitting a wide register (3.1).
byte_en — the byte-enable mask for a sub-word write (mapped to pstrb/wstrb), tied to supports_byte_enable (5.2).
status — filled by bus2reg from the bus response (5.2).

The two methods are a codec, and the binding rule is that they are exact inverses: bus2reg(reg2bus(op)) must equal op. This matters because of where bus2reg runs — the predictor calls it on every transaction it passively observes to reconstruct the operation and update the mirror. So reg2bus (the encoder used to produce traffic) and bus2reg (the decoder the predictor uses to understand traffic) must agree perfectly, or the reconstructed operation differs from the one sent and the mirror drifts. Here are both uses of bus2reg, and why the two methods must agree:

Figure 1 — reg2bus encodes on the way out; bus2reg decodes on the way in, and it runs in TWO places: returning a frontdoor result, and — shown here — in the predictor, which observes bus traffic and reconstructs the operation to update the mirror. Because the predictor decodes traffic that reg2bus encoded, the two methods must be exact inverses: if bus2reg reconstructs a different op (rw') than reg2bus sent (rw), the mirror is updated from a misreading and drifts. reg2bus encodes, bus2reg decodes, and the codec must be lossless.

4. Mental Model — a lossless, symmetric codec over one format

Mental Model — the adapter is a codec; the predictor is why it must be lossless both ways

An adapter is not two loosely-related helper functions; it is one codec, and a codec is only correct if encode and decode are exact inverses over the whole format.

Think of reg2bus as encode() and bus2reg as decode() over the uvm_reg_bus_op format. For a frontdoor access alone, you might imagine you only need encode to be right and decode to return the read data — but the predictor changes that. The predictor sits on the bus watching traffic it did not initiate, and it decodes every transaction with bus2reg to figure out what operation occurred and update the mirror. That traffic includes the transactions your own reg2bus encoded. So decode(encode(op)) must give back op exactly — same address (after granularity conversion), same data in the same place, same kind — or the predictor reconstructs a phantom operation and updates the mirror from it, and the mirror silently diverges from the hardware. The codec must be lossless (no field dropped, like status in 5.2) and symmetric (encode and decode agree on every field, like the byte/word address conversion). A one-directional or one-case-only codec is the signature of an adapter that works in a smoke test and drifts in a real one.

Two habits:

Round-trip test the codec. bus2reg(reg2bus(op)) must equal op for reads, writes, every address, and both success and error status.
Convert addr to the bus's granularity, symmetrically. Byte address in RAL; shift for a word-addressed bus in reg2bus, and shift back in bus2reg.

5. Working Example — the fields, read/write data, and granularity, both ways

An adapter for a word-addressed bus, with the codec symmetric on address and data:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

// OUTBOUND: encode. RAL addr is a BYTE address; this bus is word-addressed -> shift.
virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
  word_item item = word_item::type_id::create("item");
  item.awrite = (rw.kind == UVM_WRITE);
  item.aaddr  = rw.addr >> 2;          // byte address -> word address (4 bytes/word)
  item.awdata = rw.data;               // write data (meaningful on a write)
  item.awstrb = rw.byte_en;            // byte enables
  return item;
endfunction
 
// INBOUND: decode. Must be the exact inverse — shift back, and read data on a read.
virtual function void bus2reg(uvm_sequence_item bus_item, ref uvm_reg_bus_op rw);
  word_item item;
  if (!$cast(item, bus_item)) begin `uvm_fatal("ADPT", "bad item") return; end
  rw.kind   = item.awrite ? UVM_WRITE : UVM_READ;
  rw.addr   = item.aaddr << 2;                       // word address -> byte address (inverse)
  rw.data   = item.awrite ? item.awdata : item.ardata;  // write data out, READ data in
  rw.status = item.aerr ? UVM_NOT_OK : UVM_IS_OK;
endfunction

A round-trip test proves the two are inverses — the check every adapter should carry:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

// Round-trip: decode(encode(op)) must equal op, for reads AND writes, every address.
uvm_reg_bus_op op, back;
op.kind = UVM_WRITE;  op.addr = 'h08;  op.data = 32'hDEAD;  op.byte_en = 'hF;
uvm_sequence_item item = adapter.reg2bus(op);
adapter.bus2reg(item, back);
assert(back.kind == op.kind && back.addr == op.addr && back.data == op.data)
  else `uvm_error("ADPT", $sformatf("codec not inverse: addr %0h -> %0h", op.addr, back.addr))
// back.addr == 0x08 only if reg2bus shifted >>2 and bus2reg shifted <<2 symmetrically.

The address is shifted out in reg2bus and back in bus2reg, so the byte address survives the round trip; the data is placed by kind, so reads and writes both reconstruct correctly. Drop either symmetry and the round-trip test fails — which is exactly the next section, unshifted.

6. Debugging Session — the byte address on a word-addressed bus

Putting RAL's byte address straight onto a word-addressed bus makes every register except offset zero land on the wrong register

ADDRESS GRANULARITY

Buggy Code

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

// The bus is WORD-addressed (address N selects the Nth 32-bit word), but reg2bus copies
// RAL's BYTE address directly with no conversion:
virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
  word_item item = word_item::type_id::create("item");
  item.aaddr  = rw.addr;               // BUG: byte address 0x08 -> selects WORD 8 (byte 0x20)
  item.awrite = (rw.kind == UVM_WRITE);
  item.awdata = rw.data;
  return item;
endfunction
// A write to CTRL at byte offset 0x08 lands on the register at byte 0x20.

Symptom

Register 0x00 works perfectly (byte and word address are both 0 there), so a smoke test passes and the adapter looks correct — but every other register is wrong in a register-specific way: CTRL at 0x08 reads/writes the register at 0x20, STATUS at 0x04 hits word 4 (0x10), and so on, each off by the byte-to-word factor. It looks like a bizarre address-decode bug in the DUT, and because register zero is fine, the pattern (only offset-zero correct) is easy to miss. A round-trip codec test, had one existed, would have failed immediately for any non-zero address.

Root Cause

RAL's rw.addr is a byte address, but the bus is word-addressed — each address increments select the next 32-bit word — so the byte address must be converted (>> 2 for 4-byte words) before it is placed on the bus. The adapter copied the byte address directly, so a byte offset of 0x08 was interpreted by the bus as word 0x08, i.e. byte address 0x20, selecting a completely different register. Only offset 0x00 survives, because zero is zero in either granularity. The register model, the map (whose byte offsets are correct), and the DUT decode are all right; the adapter failed to convert between RAL's byte-address convention and the bus's word-address granularity.

Fix

Convert the address to the bus's granularity in reg2bus, and invert it in bus2reg: item.aaddr = rw.addr >> 2; outbound and rw.addr = item.aaddr << 2; inbound (as in Section 5). Then add a round-trip codec test that exercises a non-zero address, so the asymmetry cannot pass a smoke test again. The rule the bug teaches: RAL's addr is a byte address, so the adapter must convert it to the bus's addressing granularity — symmetrically in both methods — and a codec that is only correct at offset zero is an unconverted-address bug that a round-trip test on any non-zero register catches instantly. When only register zero works, look at the address conversion.

7. Common Mistakes

Not converting addr to the bus's granularity. A byte address on a word-addressed bus lands on the wrong register for every non-zero offset.
reg2bus and bus2reg not symmetric. The predictor decodes differently than reg2bus encoded, drifting the mirror.
Reconstructing data without regard to kind. Write data on a write, read data on a read; getting it backward corrupts reads.
Only smoke-testing at offset zero. Zero hides the address-granularity bug; test a non-zero register.
Dropping status or n_bits. An incomplete decode misreports errors (5.2) or mishandles wide accesses.

8. Industry Best Practices

Round-trip test the codec. bus2reg(reg2bus(op)) == op for reads, writes, a non-zero address, and success and error status.
Handle address granularity symmetrically. Convert byte to bus granularity in reg2bus, invert in bus2reg.
Reconstruct data by kind. Keep write-data and read-data paths distinct in bus2reg.
Reconstruct the complete uvm_reg_bus_op. Address, kind, data, status, and n_bits where the bus uses it.
Test non-zero registers first. They expose the granularity and symmetry bugs that offset zero conceals.

9. Interview / Review Questions

10. Key Takeaways

The adapter is a codec over the uvm_reg_bus_op (kind, addr, data, n_bits, byte_en, status): reg2bus encodes, bus2reg decodes.
They must be exact inverses because the predictor runs bus2reg on observed traffic that reg2bus encoded; a mismatch reconstructs a phantom operation and drifts the mirror. Round-trip test: bus2reg(reg2bus(op)) == op.
RAL's addr is a byte address — convert it to the bus's granularity (shift for a word-addressed bus) in reg2bus, and invert in bus2reg.
Reconstruct data by kind (write data on a write, read data on a read) and reconstruct the complete operation, including status (5.2).
The signature bug is a byte address on a word-addressed bus with no conversion: only offset zero works while every other access lands on the wrong register — test a non-zero register to catch it.