AXI-Lite Adapter — Working Example

Chapter 5 · Section 5.5 · Adapters

1. Why Should I Learn This?

Most SoC register interfaces are AXI-Lite (or AXI) rather than APB, so the AXI-Lite adapter is the one you will most often write in practice — and its extra structure introduces mistakes APB does not have: mapping to the wrong channel, and, above all, handling the two-code response incompletely. AXI's DECERR is exactly the response a bus returns for an access to an unmapped address — the very error a register test most wants to catch — so an adapter that ignores DECERR passes the accesses that matter most to fail.

Learning the AXI-Lite example gives you the template for the common case, shows how one generic operation maps onto a multi-channel protocol, and — through the DECERR bug — drives home that bus2reg must translate the complete response, including every error code the bus can return. It is the APB example scaled up to the protocol you will actually use.

2. Industry Story — the decode errors that all passed

A team ports a block's register environment from APB to AXI-Lite by writing a new adapter (exactly the one-adapter port RAL promises, 5.1). The reg2bus correctly drives the AW/W channels for writes and AR for reads; the bus2reg reconstructs address, kind, and data. For status, it translates the response: rw.status = (rresp == SLVERR) ? UVM_NOT_OK : UVM_IS_OK.

That looks complete, and register accesses to valid addresses work. But AXI-Lite has two error responses, and the team only handled one. When a refactor introduces an access to an unmapped address, the AXI interconnect answers with DECERR (a decode error), not SLVERR — and the adapter's status logic, checking only for SLVERR, falls through to UVM_IS_OK. So the access to the unmapped address is reported as a success, and the errored (garbage) read data is used as valid. Every decode error in the environment is invisible, which is precisely the class of error — accessing a register that is not there — that a register interface test exists to catch. The bug ships and surfaces as a driver reaching a non-existent register in the field. The post-mortem: AXI encodes multiple error responses (SLVERR and DECERR), and bus2reg must map all of them to UVM_NOT_OK; recognizing only SLVERR lets DECERR — the unmapped-address error — pass as success.

3. Concept — the AXI-Lite environment and its channels

A complete AXI-Lite register environment has these pieces:

• The five channels. A write uses AW (awaddr, awprot), W (wdata, wstrb), and B (bresp); a read uses AR (araddr, arprot) and R (rdata, rresp). Each channel handshakes with its own valid/ready.
• The adapter's reg2bus. For a write, populate the AW address and the W data + wstrb (byte enables). For a read, populate the AR address. The item carries the fields for the kind of access.
• The adapter's bus2reg. Reconstruct address, kind, and data (read data from R's rdata), and status from the response channel for that kind: bresp for a write, rresp for a read. The response is a two-bit code: OKAY (0), EXOKAY (1, exclusive — not used by Lite), SLVERR (2), DECERR (3). Map both SLVERR and DECERR to UVM_NOT_OK.
• supports_byte_enable = 1 (AXI has wstrb); provides_responses matched to the driver (5.4) — the B and R channels are naturally responses.
• The binding and predictor, as always.

A write completes across three handshakes — AW, W, then B — unlike APB's single two-phase transfer. Here is that flow on the wire:

4. Mental Model — one operation, many channels, a two-code response

5. Working Example — a complete AXI-Lite adapter

The AXI-Lite adapter routes the generic op onto the channels and reads status from the correct response, mapping both error codes:

class reg2axil_adapter extends uvm_reg_adapter;
  `uvm_object_utils(reg2axil_adapter)
  function new(string name = "reg2axil_adapter");
    super.new(name);
    supports_byte_enable = 1;   // AXI WSTRB
    provides_responses   = 1;   // B / R channels are responses
  endfunction
 
  virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
    axil_item item = axil_item::type_id::create("item");
    item.kind = rw.kind;
    if (rw.kind == UVM_WRITE) begin
      item.awaddr = rw.addr;    // write-address channel
      item.wdata  = rw.data;    // write-data channel
      item.wstrb  = rw.byte_en; // byte enables
    end else begin
      item.araddr = rw.addr;    // read-address channel
    end
    return item;
  endfunction
 
  virtual function void bus2reg(uvm_sequence_item bus_item, ref uvm_reg_bus_op rw);
    axil_item item;  axil_resp_e resp;
    if (!$cast(item, bus_item)) begin `uvm_fatal("ADPT","bad item") return; end
    rw.kind = item.kind;
    if (item.kind == UVM_WRITE) begin
      rw.addr = item.awaddr;  rw.data = item.wdata;  resp = item.bresp;   // write -> BRESP
    end else begin
      rw.addr = item.araddr;  rw.data = item.rdata;  resp = item.rresp;   // read  -> RRESP
    end
    // Map EVERY error code: SLVERR and DECERR both fail; only OKAY/EXOKAY are OK.
    rw.status = (resp == AXI_OKAY || resp == AXI_EXOKAY) ? UVM_IS_OK : UVM_NOT_OK;
  endfunction
endclass

Bound like any adapter, it drives real AXI-Lite — and reports decode errors honestly:

reg_model.default_map.set_sequencer(axil_agent.sequencer, axil_adapter);
uvm_status_e s;  logic [31:0] got;
cfg.write(s, 32'h0000_0013);   // AW + W + B handshakes; status from BRESP
cfg.read (s, got);             // AR + R handshakes; read data + status from R (RRESP)
// An access to an UNMAPPED address returns DECERR on the response -> s == UVM_NOT_OK.
if (s != UVM_IS_OK) `uvm_error("REG", "AXI-Lite access errored (SLVERR or DECERR)")

Status comes from the response channel matching the access kind, and every non-OKAY code — including DECERR — becomes UVM_NOT_OK. The next section forgets the second code.

6. Debugging Session — the DECERR that was never mapped

// bus2reg translates the response, but only checks for SLVERR:
rw.status = (item.rresp == AXI_SLVERR) ? UVM_NOT_OK : UVM_IS_OK;   // BUG: DECERR falls through to OK
// An access to an UNMAPPED address returns DECERR (decode error), not SLVERR:
cfg.read(s, got);   // rresp == DECERR -> (DECERR != SLVERR) -> status = UVM_IS_OK (wrong)
// The unmapped-address access is reported as SUCCESS; garbage data used as valid.

7. Common Mistakes

• Mapping only SLVERR and forgetting DECERR. Accesses to unmapped addresses pass — the error register tests most want to catch.
• Reading status from the wrong response channel. Write status is bresp, read status is rresp; mixing them misreports.
• Populating the wrong channels in reg2bus. A write needs AW + W; a read needs AR — filling the wrong channel for the kind fails the access.
• Reading write data on a read. Read data comes back on R's rdata; reconstruct data by kind.
• Wrong provides_responses or supports_byte_enable. As in APB (5.4, 3.3), match the driver and the wstrb capability.

8. Industry Best Practices

• Map the complete response in bus2reg. Treat anything not OKAY/EXOKAY as UVM_NOT_OK — SLVERR and DECERR both fail.
• Read status from the response channel matching the kind. bresp for writes, rresp for reads.
• Route by kind in reg2bus. Write → AW + W (+ wstrb); read → AR.
• Test an unmapped-address access. Confirm it returns UVM_NOT_OK (DECERR) — the decode-error path.
• Reuse one proven AXI-Lite adapter. The common SoC register bus; write it once, integration-test it, reuse it.

9. Interview / Review Questions

10. Key Takeaways

• AXI-Lite is a five-channel bus: a write uses AW (address), W (data + wstrb), and B (response); a read uses AR (address) and R (data + response).
• reg2bus routes by kind — write → AW + W, read → AR; bus2reg reads status from the response channel matching the kind (bresp for writes, rresp for reads) and read data from R's rdata.
• AXI's response is a two-bit code — map every non-OKAY value (SLVERR and DECERR) to UVM_NOT_OK; recognizing only one lets the other pass.
• DECERR is the unmapped-address error — the one register tests most want to catch — so omitting it silently reports accesses to non-existent registers as success.
• A write is three handshakes (AW, W, B) versus APB's single two-phase transfer; otherwise the adapter rules are the same — inverse codec, complete status, supports_byte_enable/provides_responses matched to the bus and driver.