# xiaoweish/uvm-source architecture

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

- Interactive diagram: https://gitdiagram.com/xiaoweish/uvm-source
- Repository: https://github.com/xiaoweish/uvm-source

## Overview

1. This repository is the Accellera UVM reference kit for IEEE 1800.2-2020. It is not an application; it is a SystemVerilog verification framework plus examples, documentation, and a small amount of DPI/C/C++ support code.

2. The canonical implementation lives under `src/`. That tree is the library source that users compile into their simulator flow. The `docs/html/src/` tree is a generated mirror of the same library sources, and `docs/html/files/` is the generated reference manual.

3. The library is organized into major subsystems by responsibility:
- `src/base`: core object model, components, phases, factory, config/resource DB, reporting, objections, transactions, recording, and root services
- `src/seq`: sequence, sequencer, and sequence-item infrastructure
- `src/comps`: reusable verification components such as agent, driver, monitor, env, test, scoreboard, subscriber
- `src/tlm1` and `src/tlm2`: transaction-level modeling interfaces, ports, exports, sockets, FIFOs, and request/response plumbing
- `src/reg`: register and memory abstraction, adapters, predictors, maps, fields, and built-in register sequences
- `src/dap`: data access policy helpers used by config-style state transfer
- `src/macros`: compile-time helper macros that generate common UVM boilerplate

4. The central runtime boundary is the UVM object/component hierarchy. `uvm_object` is the non-hierarchical base for data and transactions; `uvm_component` is the hierarchical base for testbench structure and participates in phasing, configuration, reporting, and factory-based construction. Everything higher-level is built on this split.

5. The execution model is phase-driven. `uvm_root` anchors the hierarchy and starts phase execution. Phase classes in `base` separate build/connect/elaboration from runtime behavior, and objections control when run-time phases drain. This is the main control-flow backbone of any UVM environment built on this repo.

6. The configuration and discovery path is split across factory, config DB, and resource DB:
- the factory handles type/name-based object and component creation and overrides
- `uvm_config_db` is the primary hierarchical configuration channel used by environments and tests
- the resource pool/database layer underpins broader keyed lookup and sharing
This is the main “setup-time” data flow from test top into components.

7. The stimulus path is sequencer/driver-based. Sequences generate sequence items, sequencers arbitrate and hand items to drivers, and drivers convert those items into pin-level or bus-level activity. Monitors observe DUT behavior and publish analysis traffic. This is the primary dataflow used in the examples and in user testbenches built with the library.

8. TLM is the decoupling boundary between producers and consumers. TLM1 provides analysis ports, blocking/nonblocking FIFOs, and req/rsp-style connectivity. TLM2 adds generic payloads, sockets, time annotations, and initiator/target abstractions. These subsystems are what let agents, scoreboards, predictors, and transactors communicate without tight coupling.

9. The register layer is a major subsystem on its own. `src/reg` models registers, fields, memories, files, blocks, maps, adapters, and predictors, and includes built-in sequences for access, reset, bit-bashing, and memory walking. It forms a bridge between abstract register models and bus-level protocols via adapters and predictors.

10. Reporting, tracing, and recording are first-class infrastructure, not add-ons. The base layer includes report objects, handlers, catchers, servers, printers, recorders, and transaction databases/streams. These are used throughout the library to control diagnostics and capture simulation activity.

11. The `src/dpi` directory contains the non-SV boundary into external code. It includes C/C++ and simulator-specific implementations for HDL access, regex support, and service commands. This is the main portability boundary because behavior can vary by simulator vendor and compiled DPI support.

12. `compat/` and `src/deprecated/` capture backward-compatibility and legacy behavior. They exist to ease migration from older UVM versions and to support older macros/APIs, but they are intentionally separate from the main clean implementation. This boundary is important when diagramming “supported core” versus “compatibility surface.”

13. `examples/` is the usage/validation side of the repo. The `simple` examples isolate individual features like callbacks, phases, factory, TLM1/TLM2, sequences, objections, and registers. The `integrated` examples show complete environments with DUTs, agents, scoreboards, register models, and tests, which is the clearest illustration of the expected dataflow through the library.

14. Tooling and packaging are lightweight but important: `bin/` contains helper scripts for migration and platform naming; the `Makefile.*` files in examples show vendor-specific build entry points; `README` plus `DEVIATIONS.md` define standard coverage and known deviations. The repo is therefore best understood as a standards-based verification library with vendor-tool integration points, not as a standalone executable system.

Main entry points: [`src`](https://github.com/xiaoweish/uvm-source/tree/main/src) (Library sources), [`src/base/uvm_component.svh`](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_component.svh) (Component base), [`src/base/uvm_object.svh`](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_object.svh) (Object base), [`src/comps/uvm_comps.svh`](https://github.com/xiaoweish/uvm-source/blob/main/src/comps/uvm_comps.svh) (Comps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_uvm_pkg["UVM package<br/>package entry<br/>[uvm_pkg.sv]"]
  node_uvm_src["Library sources<br/>SV library"]
  node_uvm_object(("Object base<br/>non-hier object<br/>[uvm_object.svh]"))
  node_uvm_component(("Component base<br/>hier component<br/>[uvm_component.svh]"))
  node_uvm_root(("Root runtime<br/>simulation root<br/>[uvm_root.svh]"))
  node_phasing["Phases<br/>phase system<br/>[uvm_phase.svh]"]
  node_config_res["Config & resource<br/>setup dataflow<br/>[uvm_config_db.svh]"]
  node_reporting["Reporting<br/>diagnostics"]
  node_recording["Recording<br/>transaction trace<br/>[uvm_recorder.svh]"]
end

subgraph group_stimulus["Stimulus flow"]
  node_sequences["Sequences<br/>stimulus API<br/>[uvm_sequence.svh]"]
  node_sequencers["Sequencers<br/>arbitration<br/>[uvm_sequencer.svh]"]
  node_comps["Comps<br/>reusable agents<br/>[uvm_comps.svh]"]
end

subgraph group_interop["Interop layers"]
  node_tlm1["TLM1<br/>analysis/connectivity<br/>[uvm_tlm.svh]"]
  node_tlm2["TLM2<br/>generic payload<br/>[uvm_tlm2.svh]"]
  node_reg["Registers<br/>reg model<br/>[uvm_reg_model.svh]"]
  node_dpi["DPI layer<br/>C/C++ bridge<br/>[uvm_dpi.cc]"]
  node_macros["Macros<br/>compile-time helpers"]
  node_compat["Compatibility<br/>legacy surface<br/>[readme.important]"]
end

subgraph group_usage["Usage material"]
  node_examples_simple["Simple examples<br/>feature demos"]
  node_examples_integrated["Integrated examples<br/>full env demos"]
  node_docs["Docs mirror<br/>generated docs"]
  node_tooling["Tooling<br/>scripts/build"]
end

node_uvm_pkg -->|"assembles"| node_uvm_src
node_uvm_src -->|"defines"| node_uvm_object
node_uvm_src -->|"defines"| node_uvm_component
node_uvm_component -->|"participates in"| node_phasing
node_uvm_root -->|"starts"| node_phasing
node_uvm_component -->|"uses"| node_config_res
node_uvm_component -->|"reports through"| node_reporting
node_uvm_object -->|"records with"| node_recording
node_uvm_object -->|"stimulates via"| node_sequences
node_sequences -->|"arbitrate on"| node_sequencers
node_sequencers -->|"drives"| node_comps
node_comps -->|"publishes"| node_tlm1
node_comps -->|"transacts via"| node_tlm2
node_reg -->|"bridges via"| node_tlm1
node_reg -->|"is exercised by"| node_sequencers
node_dpi -->|"extends"| node_uvm_src
node_macros -->|"supports"| node_uvm_src
node_compat -->|"wraps"| node_macros
node_examples_simple -->|"demonstrates"| node_uvm_src
node_examples_integrated -->|"demonstrates"| node_uvm_src
node_docs -->|"mirrors"| node_uvm_src
node_tooling -->|"builds"| node_examples_simple

click node_uvm_pkg "https://github.com/xiaoweish/uvm-source/blob/main/src/uvm_pkg.sv"
click node_uvm_src "https://github.com/xiaoweish/uvm-source/tree/main/src"
click node_uvm_object "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_object.svh"
click node_uvm_component "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_component.svh"
click node_uvm_root "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_root.svh"
click node_phasing "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_phase.svh"
click node_config_res "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_config_db.svh"
click node_reporting "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_report_handler.svh"
click node_recording "https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_recorder.svh"
click node_sequences "https://github.com/xiaoweish/uvm-source/blob/main/src/seq/uvm_sequence.svh"
click node_sequencers "https://github.com/xiaoweish/uvm-source/blob/main/src/seq/uvm_sequencer.svh"
click node_comps "https://github.com/xiaoweish/uvm-source/blob/main/src/comps/uvm_comps.svh"
click node_tlm1 "https://github.com/xiaoweish/uvm-source/blob/main/src/tlm1/uvm_tlm.svh"
click node_tlm2 "https://github.com/xiaoweish/uvm-source/blob/main/src/tlm2/uvm_tlm2.svh"
click node_reg "https://github.com/xiaoweish/uvm-source/blob/main/src/reg/uvm_reg_model.svh"
click node_dpi "https://github.com/xiaoweish/uvm-source/blob/main/src/dpi/uvm_dpi.cc"
click node_macros "https://github.com/xiaoweish/uvm-source/blob/main/src/macros/uvm_object_defines.svh"
click node_compat "https://github.com/xiaoweish/uvm-source/blob/main/src/deprecated/readme.important"
click node_examples_simple "https://github.com/xiaoweish/uvm-source/tree/main/examples/simple"
click node_examples_integrated "https://github.com/xiaoweish/uvm-source/tree/main/examples/integrated"
click node_docs "https://github.com/xiaoweish/uvm-source/tree/main/docs/html"
click node_tooling "https://github.com/xiaoweish/uvm-source/tree/main/bin"

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_uvm_pkg,node_uvm_src,node_uvm_object,node_uvm_component,node_uvm_root,node_phasing,node_config_res,node_reporting,node_recording toneBlue
class node_sequences,node_sequencers,node_comps toneAmber
class node_tlm1,node_tlm2,node_reg,node_dpi,node_macros,node_compat toneMint
class node_examples_simple,node_examples_integrated,node_docs,node_tooling toneRose
```

## Components

### Core runtime

Object model, hierarchy, phases, configuration, reporting, and transaction infrastructure.

- [UVM package](https://github.com/xiaoweish/uvm-source/blob/main/src/uvm_pkg.sv): package entry · Primary package entrypoint that assembles the reference kit library. · `src/uvm_pkg.sv`
- [Library sources](https://github.com/xiaoweish/uvm-source/tree/main/src): SV library · Canonical SystemVerilog implementation consumed by simulator flows. · `src`
- [Object base](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_object.svh): non-hier object · Base class for data and transactions. · `src/base/uvm_object.svh`
- [Component base](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_component.svh): hier component · Hierarchical base for testbench structure, phasing, config, and reporting. · `src/base/uvm_component.svh`
- [Root runtime](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_root.svh): simulation root · Anchors the hierarchy and starts phase execution. · `src/base/uvm_root.svh`
- [Phases](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_phase.svh): phase system · Build/connect/elaboration/runtime phase classes and drain control. · `src/base/uvm_phase.svh`
- [Config & resource](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_config_db.svh): setup dataflow · Factory overrides, config DB, resource DB, and keyed lookup services. · `src/base/uvm_config_db.svh`
- [Reporting](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_report_handler.svh): diagnostics · Report objects, handlers, servers, catchers, and messages. · `src/base/uvm_report_handler.svh`
- [Recording](https://github.com/xiaoweish/uvm-source/blob/main/src/base/uvm_recorder.svh): transaction trace · Printers, recorders, transaction streams, and databases. · `src/base/uvm_recorder.svh`

### Stimulus flow

Sequences, sequencers, drivers, monitors, and reusable verification components.

- [Sequences](https://github.com/xiaoweish/uvm-source/blob/main/src/seq/uvm_sequence.svh): stimulus API · Sequence, sequence-item, and sequencer infrastructure. · `src/seq/uvm_sequence.svh`
- [Sequencers](https://github.com/xiaoweish/uvm-source/blob/main/src/seq/uvm_sequencer.svh): arbitration · Sequencer bases, push sequencers, and analysis FIFO integration. · `src/seq/uvm_sequencer.svh`
- [Comps](https://github.com/xiaoweish/uvm-source/blob/main/src/comps/uvm_comps.svh): reusable agents · Agent, driver, monitor, env, test, scoreboard, subscriber, and comparators. · `src/comps/uvm_comps.svh`

### Interop layers

TLM, register modeling, DPI, macros, and compatibility surface.

- [TLM1](https://github.com/xiaoweish/uvm-source/blob/main/src/tlm1/uvm_tlm.svh): analysis/connectivity · Ports, exports, imps, FIFOs, req/rsp plumbing, and analysis connections. · `src/tlm1/uvm_tlm.svh`
- [TLM2](https://github.com/xiaoweish/uvm-source/blob/main/src/tlm2/uvm_tlm2.svh): generic payload · Sockets, generic payload, time annotation, and initiator/target abstractions. · `src/tlm2/uvm_tlm2.svh`
- [Registers](https://github.com/xiaoweish/uvm-source/blob/main/src/reg/uvm_reg_model.svh): reg model · Register/memory abstraction, maps, adapters, predictors, and built-in sequences. · `src/reg/uvm_reg_model.svh`
- [DPI layer](https://github.com/xiaoweish/uvm-source/blob/main/src/dpi/uvm_dpi.cc): C/C++ bridge · Simulator-facing C/C++ support for HDL access, regex, and service commands. · `src/dpi/uvm_dpi.cc`
- [Macros](https://github.com/xiaoweish/uvm-source/blob/main/src/macros/uvm_object_defines.svh): compile-time helpers · Boilerplate-generation macros for objects, sequences, TLM, regs, reporting, and versioning. · `src/macros/uvm_object_defines.svh`
- [Compatibility](https://github.com/xiaoweish/uvm-source/blob/main/src/deprecated/readme.important): legacy surface · Back-compat macros and legacy support kept separate from the main implementation. · `src/deprecated/readme.important`

### Usage material

Examples, generated docs, and tooling around the library.

- [Simple examples](https://github.com/xiaoweish/uvm-source/tree/main/examples/simple): feature demos · Focused examples for factory, phases, config, sequences, TLM, objections, and registers. · `examples/simple`
- [Integrated examples](https://github.com/xiaoweish/uvm-source/tree/main/examples/integrated): full env demos · Complete environments showing agents, DUTs, scoreboards, register models, and tests. · `examples/integrated`
- [Docs mirror](https://github.com/xiaoweish/uvm-source/tree/main/docs/html): generated docs · Generated HTML reference and mirrored source tree for the library. · `docs/html`
- [Tooling](https://github.com/xiaoweish/uvm-source/tree/main/bin): scripts/build · Migration scripts, vendor makefiles, and packaging/README guidance. · `bin`

## Connections

- UVM package → Library sources: assembles · Package entry includes the canonical library subsystems.
- Library sources → Object base: defines · Core object base underpins non-hierarchical data and transactions.
- Library sources → Component base: defines · Component base underpins hierarchy and testbench structure.
- Component base → Phases: participates in · Components are scheduled and coordinated by the phase system.
- Root runtime → Phases: starts · Root anchors the hierarchy and launches phase execution.
- Component base → Config & resource: uses · Components consume factory, config DB, and resource DB setup flow.
- Component base → Reporting: reports through · Component diagnostics flow through report infrastructure.
- Object base → Recording: records with · Objects and transactions can be printed, recorded, and traced.
- Object base → Sequences: stimulates via · Sequence items are generated from the object side of the split.
- Sequences → Sequencers: arbitrate on · Sequencers accept, arbitrate, and hand off items from sequences.
- Sequencers → Comps: drives · Sequencers connect to drivers inside reusable verification components.
- Comps → TLM1: publishes · Monitors and subscribers use analysis and FIFO connectivity.
- Comps → TLM2: transacts via · Agents and transactors can use TLM2 sockets and generic payloads.
- Registers → TLM1: bridges via · Register prediction and callbacks often communicate over analysis paths.
- Registers → Sequencers: is exercised by · Built-in register sequences run through sequencer-style stimulus.
- DPI layer → Library sources: extends · DPI support backs library services and simulator-specific integration.
- Macros → Library sources: supports · Macros generate common boilerplate used across the library.
- Compatibility → Macros: wraps · Compatibility surface preserves older macro/API behavior.
- Simple examples → Library sources: demonstrates · Simple examples isolate individual library features.
- Integrated examples → Library sources: demonstrates · Integrated examples show full environment dataflow built on the library.
- Docs mirror → Library sources: mirrors · Generated documentation mirrors the canonical source tree.
- Tooling → Simple examples: builds · Vendor makefiles and helper scripts drive example compilation.