# vyas789/i3c_avip architecture

> Architecture diagram of the GitHub repository vyas789/i3c_avip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vyas789/i3c_avip
- Repository: https://github.com/vyas789/i3c_avip

## Overview

1. This repository is a SystemVerilog/UVM verification collateral package for an accelerated MIPI I3C VIP. The architecture is split into a synthesizable HDL top and a non-synthesizable HVL top so the same bench can run in simulation or emulation.

2. The DUT is the I3C controller RTL in `rtl_dev/src`. The core is built from `I3C_TOP`, `i3c_bit_engine`, `i3c_cmd_ctrl`, `i3c_sdr_fsm`, `i3c_daa_fsm`, `i3c_scl_gen`, FIFO blocks, a register interface, and a device table. This is the hardware block under verification.

3. The HDL top in `src/hdl_top` is the accelerated, synthesizable side of the testbench. It contains the bus and protocol interfaces (`apb_if`, `i3c_if`), a wrapper around the DUT, and BFM-style components for APB, I3C controller, and I3C target driving/monitoring.

4. The HVL top in `src/hvl_top` is the UVM side. It contains the APB master agent, I3C controller agent, I3C target agent, environment configuration, virtual sequencer, scoreboard, RAL model, and coverage components. This is where constrained-random stimulus, checking, and test orchestration live.

5. APB is the control/configuration path into the DUT. The APB master agent programs DUT registers through the HDL-top APB interface and RAL layer, which then influences protocol behavior such as address setup, FIFO access, and mode control.

6. The main protocol data path is I3C traffic between the controller-side BFM and target-side BFM, coordinated by the HVL sequences. The controller and target agents model the two bus participants and support write, read, repeated-start, multi-transfer, and dynamic address assignment scenarios.

7. The verification environment is organized around layered sequences. Base sequences and virtual sequences are defined separately for APB, controller, target, and top-level test behavior, with many scenario-specific tests for 8/16/32/64-bit transfers, random transfer widths, start/stop combinations, FIFO-full behavior, invalid address handling, and DAA flows.

8. Scoreboarding and checking are centralized in `src/hvl_top/env/i3c_scoreboard*`. The scoreboard compares expected versus observed protocol outcomes, including address/NACK behavior and transaction ordering, while coverage components track exercised protocol and feature space.

9. The test catalog is explicit and regression-oriented. Individual tests live under `src/hvl_top/test`, and regression lists are under `src/hvl_top/testlists` such as `i3c_standard_mode_regression.list`. This makes it straightforward to map a test suite to coverage goals and to a diagram of stimulus selection.

10. Simulation infrastructure is split by tool in `sim/`. There are make-based flows for Questasim, Synopsys VCS, and Cadence Xcelium, plus generated waveform and coverage artifacts per test and merged regression coverage. The checked-in `sim/questa_sim` results show the repository is used as a complete verification delivery, not just source code.

11. Unit-test collateral under `unit_test/` validates individual HDL and HVL components in isolation, such as BFMs, agent config, driver proxies, and transaction objects. This is an important boundary: component correctness is verified separately from full system protocol behavior.

12. The repository also includes architecture and planning documents under `doc/` and `rtl_dev/doc/`. These define the intended design, verification plan, naming conventions, and coverage model, which are useful reference layers for understanding the intended subsystem boundaries in a diagram.

Main entry points: [`src/hvl_top/env/i3c_env.sv`](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_env.sv) (I3C Env), [`rtl_dev/src/I3C_TOP.v`](https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/I3C_TOP.v) (I3C Top), [`src/hvl_top/controller/i3c_controller_agent.sv`](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/controller/i3c_controller_agent.sv) (Ctrl Agent), [`src/hvl_top/target/i3c_target_agent.sv`](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/target/i3c_target_agent.sv) (Tgt Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_rtl["DUT RTL"]
  node_node_dut_top["I3C Top<br/>rtl block<br/>[I3C_TOP.v]"]
  node_node_dut_engines["Core Engines<br/>rtl engines<br/>[i3c_bit_engine.v]"]
  node_node_dut_regs["Register Plane<br/>rtl control"]
end

subgraph group_group_hdl["HDL Top"]
  node_node_hdl_top["HDL Top<br/>bench shell<br/>[hdl_top.sv]"]
  node_node_hdl_if["Bus IFs<br/>interfaces<br/>[apb_if.sv]"]
  node_node_hdl_wrapper["DUT Wrapper<br/>[i3c_wrapper.sv]"]
  node_node_hdl_apb_bfm["APB BFM<br/>hdl bfm"]
  node_node_hdl_ctrl_bfm["Ctrl BFM<br/>hdl bfm"]
  node_node_hdl_tgt_bfm["Tgt BFM<br/>hdl bfm"]
end

subgraph group_group_hvl["HVL Top"]
  node_node_hvl_top["HVL Top<br/>uvm top<br/>[hvl_top.sv]"]
  node_node_apb_agent["APB Agent<br/>uvm agent"]
  node_node_ctrl_agent["Ctrl Agent<br/>uvm agent"]
  node_node_tgt_agent["Tgt Agent<br/>uvm agent"]
  node_node_env["I3C Env<br/>uvm env<br/>[i3c_env.sv]"]
  node_node_vseq["Virtual Seq<br/>uvm sequencer"]
  node_node_scoreboard["Scoreboard<br/>checker<br/>[i3c_scoreboard.sv]"]
  node_node_ral["RAL Model<br/>register model"]
  node_node_tests["Tests<br/>test catalog<br/>[test.sv]"]
  node_node_regression["Regression Lists<br/>testlists"]
end

subgraph group_group_sim["Simulation"]
  node_node_sim["Sim Flows<br/>tool flows"]
  node_node_cov_artifacts["Coverage Artifacts<br/>reports<br/>[index.html]"]
end

subgraph group_group_unit["Unit Tests"]
  node_node_unit_hdl["HDL Unit<br/>unit tests"]
  node_node_unit_hvl["HVL Unit<br/>unit tests"]
end

subgraph group_group_doc["Docs"]
  node_node_docs["Plans & Docs"]
end

node_node_hdl_top -->|"uses"| node_node_hdl_if
node_node_hdl_top -->|"wraps"| node_node_hdl_wrapper
node_node_hdl_wrapper -->|"instantiates"| node_node_dut_top
node_node_dut_top -->|"builds from"| node_node_dut_engines
node_node_dut_top -->|"controls via"| node_node_dut_regs
node_node_hvl_top -->|"creates"| node_node_env
node_node_env -->|"connects"| node_node_apb_agent
node_node_env -->|"connects"| node_node_ctrl_agent
node_node_env -->|"connects"| node_node_tgt_agent
node_node_env -->|"coordinates"| node_node_vseq
node_node_env -->|"checks"| node_node_scoreboard
node_node_env -->|"programs"| node_node_ral
node_node_apb_agent -->|"drives"| node_node_hdl_apb_bfm
node_node_ctrl_agent -->|"drives"| node_node_hdl_ctrl_bfm
node_node_tgt_agent -->|"drives"| node_node_hdl_tgt_bfm
node_node_ral -->|"programs"| node_node_dut_regs
node_node_tests -->|"launches"| node_node_vseq
node_node_regression -->|"selects"| node_node_tests
node_node_sim -->|"produces"| node_node_cov_artifacts
node_node_sim -->|"runs"| node_node_tests
node_node_unit_hdl -->|"validates"| node_node_hdl_ctrl_bfm
node_node_unit_hvl -->|"validates"| node_node_ctrl_agent
node_node_unit_hvl -->|"validates"| node_node_tgt_agent
node_node_docs -->|"defines"| node_node_env
node_node_docs -->|"specifies"| node_node_dut_top

click node_node_dut_top "https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/I3C_TOP.v"
click node_node_dut_engines "https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/i3c_bit_engine.v"
click node_node_dut_regs "https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/i3c_reg_interface.v"
click node_node_hdl_top "https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/hdl_top.sv"
click node_node_hdl_if "https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/apb_if/apb_if.sv"
click node_node_hdl_wrapper "https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/i3c_wrapper.sv"
click node_node_hdl_apb_bfm "https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/apb_master_agent_bfm/apb_master_agent_bfm.sv"
click node_node_hdl_ctrl_bfm "https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/controller_agent_bfm/i3c_controller_agent_bfm.sv"
click node_node_hdl_tgt_bfm "https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/target_agent_bfm/i3c_target_agent_bfm.sv"
click node_node_hvl_top "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/hvl_top.sv"
click node_node_apb_agent "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/apb_master/apb_master_agent.sv"
click node_node_ctrl_agent "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/controller/i3c_controller_agent.sv"
click node_node_tgt_agent "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/target/i3c_target_agent.sv"
click node_node_env "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_env.sv"
click node_node_vseq "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/virtual_sequencer/i3c_virtual_sequencer.sv"
click node_node_scoreboard "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_scoreboard.sv"
click node_node_ral "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_ral_reg_block.sv"
click node_node_tests "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/test/test.sv"
click node_node_regression "https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/testlists/i3c_standard_mode_regression.list"
click node_node_sim "https://github.com/vyas789/i3c_avip/tree/production/sim/questa_sim/makefile"
click node_node_cov_artifacts "https://github.com/vyas789/i3c_avip/blob/production/sim/questa_sim/merged_cov_html_report/index.html"
click node_node_unit_hdl "https://github.com/vyas789/i3c_avip/blob/production/unit_test/hdl_unit_test/controller_agent_bfm_unit_test/i3c_controller_driver_bfm_unit_test/i3c_controller_driver_bfm_unit_test.sv"
click node_node_unit_hvl "https://github.com/vyas789/i3c_avip/blob/production/unit_test/hvl_unit_test/controller_unit_test/controller_tx_unit_test/i3c_controller_tx_unit_test.sv"
click node_node_docs "https://github.com/vyas789/i3c_avip/blob/production/doc/i3c_avip_main_architectural_document.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_dut_top,node_node_dut_engines,node_node_dut_regs toneBlue
class node_node_hdl_top,node_node_hdl_if,node_node_hdl_wrapper,node_node_hdl_apb_bfm,node_node_hdl_ctrl_bfm,node_node_hdl_tgt_bfm toneAmber
class node_node_hvl_top,node_node_apb_agent,node_node_ctrl_agent,node_node_tgt_agent,node_node_env,node_node_vseq,node_node_scoreboard,node_node_ral,node_node_tests,node_node_regression toneMint
class node_node_sim,node_node_cov_artifacts toneRose
class node_node_unit_hdl,node_node_unit_hvl toneIndigo
class node_node_docs toneTeal
```

## Components

### DUT RTL

Synthesizable I3C controller under verification.

- [I3C Top](https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/I3C_TOP.v): rtl block · Main RTL controller integration block under test. · `rtl_dev/src/I3C_TOP.v`
- [Core Engines](https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/i3c_bit_engine.v): rtl engines · Bit engine, command control, SDR, DAA, SCL generation, FIFOs, register interface, and device table. · `rtl_dev/src/i3c_bit_engine.v`
- [Register Plane](https://github.com/vyas789/i3c_avip/blob/production/rtl_dev/src/i3c_reg_interface.v): rtl control · Register interface and device table programming plane. · `rtl_dev/src/i3c_reg_interface.v`

### HDL Top

Accelerated synthesizable testbench side.

- [HDL Top](https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/hdl_top.sv): bench shell · Synthesizable top-level verification wrapper for emulation/simulation. · `src/hdl_top/hdl_top.sv`
- [Bus IFs](https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/apb_if/apb_if.sv): interfaces · APB and I3C interface definitions shared across bench components. · `src/hdl_top/apb_if/apb_if.sv`
- [DUT Wrapper](https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/i3c_wrapper.sv): wrapper · Wraps the DUT and binds it to the accelerated testbench fabric. · `src/hdl_top/i3c_wrapper.sv`
- [APB BFM](https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/apb_master_agent_bfm/apb_master_agent_bfm.sv): hdl bfm · Synthesizable APB master driver and monitor for register programming. · `src/hdl_top/apb_master_agent_bfm/apb_master_agent_bfm.sv`
- [Ctrl BFM](https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/controller_agent_bfm/i3c_controller_agent_bfm.sv): hdl bfm · Controller-side protocol driver and monitor for I3C traffic. · `src/hdl_top/controller_agent_bfm/i3c_controller_agent_bfm.sv`
- [Tgt BFM](https://github.com/vyas789/i3c_avip/blob/production/src/hdl_top/target_agent_bfm/i3c_target_agent_bfm.sv): hdl bfm · Target-side protocol driver and monitor for I3C traffic. · `src/hdl_top/target_agent_bfm/i3c_target_agent_bfm.sv`

### HVL Top

UVM stimulus, checking, and orchestration.

- [HVL Top](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/hvl_top.sv): uvm top · Non-synthesizable UVM testbench entry and orchestration layer. · `src/hvl_top/hvl_top.sv`
- [APB Agent](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/apb_master/apb_master_agent.sv): uvm agent · APB master agent, proxies, sequencer, driver, monitor, and coverage. · `src/hvl_top/apb_master/apb_master_agent.sv`
- [Ctrl Agent](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/controller/i3c_controller_agent.sv): uvm agent · I3C controller-side agent for protocol stimulus and observation. · `src/hvl_top/controller/i3c_controller_agent.sv`
- [Tgt Agent](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/target/i3c_target_agent.sv): uvm agent · I3C target-side agent for protocol stimulus and observation. · `src/hvl_top/target/i3c_target_agent.sv`
- [I3C Env](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_env.sv): uvm env · Connects agents, configuration, scoreboard, RAL, and virtual sequencing. · `src/hvl_top/env/i3c_env.sv`
- [Virtual Seq](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/virtual_sequencer/i3c_virtual_sequencer.sv): uvm sequencer · Virtual sequencer coordinating APB, controller, and target flows. · `src/hvl_top/env/virtual_sequencer/i3c_virtual_sequencer.sv`
- [Scoreboard](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_scoreboard.sv): checker · Central protocol and transaction-order checking, including NACK/address behavior. · `src/hvl_top/env/i3c_scoreboard.sv`
- [RAL Model](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/env/i3c_ral_reg_block.sv): register model · Register abstraction used to program DUT control and status fields. · `src/hvl_top/env/i3c_ral_reg_block.sv`
- [Tests](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/test/test.sv): test catalog · Top-level tests and scenario-specific virtual sequences. · `src/hvl_top/test/test.sv`
- [Regression Lists](https://github.com/vyas789/i3c_avip/blob/production/src/hvl_top/testlists/i3c_standard_mode_regression.list): testlists · Explicit regression selections and suite definitions. · `src/hvl_top/testlists/i3c_standard_mode_regression.list`

### Simulation

Tool flows, regressions, and generated artifacts.

- [Sim Flows](https://github.com/vyas789/i3c_avip/tree/production/sim/questa_sim/makefile): tool flows · Questa, VCS, and Xcelium make-based simulation flows. · `sim/questa_sim/makefile`
- [Coverage Artifacts](https://github.com/vyas789/i3c_avip/blob/production/sim/questa_sim/merged_cov_html_report/index.html): reports · Per-test and merged waveform/coverage outputs from regression runs. · `sim/questa_sim/merged_cov_html_report/index.html`

### Unit Tests

Isolated component-level verification collateral.

- [HDL Unit](https://github.com/vyas789/i3c_avip/blob/production/unit_test/hdl_unit_test/controller_agent_bfm_unit_test/i3c_controller_driver_bfm_unit_test/i3c_controller_driver_bfm_unit_test.sv): unit tests · Isolated HDL component tests, including controller BFM behavior. · `unit_test/hdl_unit_test/controller_agent_bfm_unit_test/i3c_controller_driver_bfm_unit_test/i3c_controller_driver_bfm_unit_test.sv`
- [HVL Unit](https://github.com/vyas789/i3c_avip/blob/production/unit_test/hvl_unit_test/controller_unit_test/controller_tx_unit_test/i3c_controller_tx_unit_test.sv): unit tests · Isolated HVL component tests for configs, proxies, transactions, and target sequences. · `unit_test/hvl_unit_test/controller_unit_test/controller_tx_unit_test/i3c_controller_tx_unit_test.sv`

### Docs

Architecture and verification planning references.

- [Plans & Docs](https://github.com/vyas789/i3c_avip/blob/production/doc/i3c_avip_main_architectural_document.md): docs · Architectural, verification, coverage, and coding guidance documents. · `doc/i3c_avip_main_architectural_document.md`

## Connections

- HDL Top → Bus IFs: uses · Top instantiates shared APB/I3C interfaces.
- HDL Top → DUT Wrapper: wraps · Synthesizable top wraps the DUT integration.
- DUT Wrapper → I3C Top: instantiates · Wrapper contains the RTL controller block.
- I3C Top → Core Engines: builds from · Top-level RTL is composed from protocol engines and FIFOs.
- I3C Top → Register Plane: controls via · Register plane configures protocol and data-path behavior.
- HVL Top → I3C Env: creates · UVM top constructs the environment.
- I3C Env → APB Agent: connects · Environment includes APB configuration agent.
- I3C Env → Ctrl Agent: connects · Environment includes controller-side agent.
- I3C Env → Tgt Agent: connects · Environment includes target-side agent.
- I3C Env → Virtual Seq: coordinates · Virtual sequencer orchestrates cross-agent scenarios.
- I3C Env → Scoreboard: checks · Environment centralizes scoreboarding and protocol checking.
- I3C Env → RAL Model: programs · Environment uses RAL for register access abstraction.
- APB Agent → APB BFM: drives · UVM APB agent talks through synthesizable APB BFM.
- Ctrl Agent → Ctrl BFM: drives · Controller agent maps to accelerated controller BFM.
- Tgt Agent → Tgt BFM: drives · Target agent maps to accelerated target BFM.
- RAL Model → Register Plane: programs · RAL writes reach DUT register interface.
- Tests → Virtual Seq: launches · Tests select and start layered virtual sequences.
- Regression Lists → Tests: selects · Regression lists enumerate the test catalog.
- Sim Flows → Coverage Artifacts: produces · Simulation flows generate waveforms and coverage reports.
- Sim Flows → Tests: runs · Tool flows execute the regression test catalog.
- HDL Unit → Ctrl BFM: validates · HDL unit tests cover BFM behavior in isolation.
- HVL Unit → Ctrl Agent: validates · HVL unit tests cover agent/config/proxy behavior.
- HVL Unit → Tgt Agent: validates · HVL unit tests cover target-side transaction logic.
- Plans & Docs → I3C Env: defines · Docs describe environment boundaries and intent.
- Plans & Docs → I3C Top: specifies · Docs capture DUT architecture and design intent.
