RAL Integration in the Environment

Overview

A register model is useful only when the environment wiring is complete and deterministic . Most mirror failures, hanging register sequences, and random frontdoor bugs come from missing integration steps rather than from sequence logic.

This topic is the implementation playbook for integrating RAL into an APB/AXI style UVM environment: build order, map and adapter binding, predictor connections, model sharing across hierarchy, and failure triage.

Lessons in this topic

1. env-build-checklist - numbered integration steps from model creation to first mirror check.

2. sequencer-map-adapter - deep dive on set_sequencer(map, adapter) behavior and common map mistakes.

3. predictor-connection - connect_phase wiring for monitor to predictor to mirror flow.

4. config-db-sharing - one reg_model handle shared across multi-level env hierarchy.

5. integration-reference-env - complete reg_env source with annotations and callouts.

6. integration-debug-playbook - hung sequence, mirror mismatch, and missing predictor investigation.

Integration architecture map

Legend: [UVM] [RAL]

[TEST] reg sequences, mirror checks, reset checks
   │
   │ (configures env, then starts reg traffic)
   ▼
[UVM] reg_env
   ├─ build_phase:
   │    - create agent, adapter, predictor
   │    - create or fetch reg_model
   │    - reg_model.build()
   │    - reg_model.lock_model()
   │
   ├─ connect_phase:
   │    - reg_model.default_map.set_sequencer(bus.sqr, adapter)
   │    - reg_model.default_map.set_auto_predict(0)
   │    - predictor.map     = reg_model.default_map
   │    - predictor.adapter = adapter
   │    - bus.mon.ap.connect(predictor.bus_in)
   │
   └─ config_db:
        - publish same reg_model handle to sub-envs and tests

[RAL] frontdoor path:
  reg.write/read/mirror -> map + adapter -> bus sequencer -> driver -> DUT

[RAL] observe path:
  monitor -> predictor -> adapter.bus2reg -> map.predict -> mirror sync

Expected outcome after correct wiring

• Frontdoor register writes route through the intended bus sequencer and adapter.

• Monitor-observed traffic updates the mirror through one explicit predictor path.

• reg.mirror(UVM_CHECK) reflects real bus traffic, including non-RAL masters when monitored.

• Every env layer references the same reg_model handle instead of cloning divergent copies.

Key takeaways

• RAL integration is an env responsibility; tests should only consume reg API.

• set_sequencer and predictor connection are complementary and both required.

• Model sharing and explicit prediction remove most large-env mirror drift issues.

Common pitfalls

• Treating integration as sequence code instead of env infrastructure.

• Calling set_sequencer but forgetting monitor to predictor wiring.

• Creating multiple independent reg_model objects at different env levels.