# themperek/cocotb-vivado architecture

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

- Interactive diagram: https://gitdiagram.com/themperek/cocotb-vivado
- Repository: https://github.com/themperek/cocotb-vivado

## Overview

cocotb-vivado lets engineers run Python/cocotb testbenches against Vivado XSim designs. The main workflow is to pass plain HDL and optional Vivado-managed sources to the runner, prepare and parse Vivado simulation inputs, build or reuse an XSim snapshot, then run tests through the XSI-backed cocotb interface. Separate branches cover Vivado source formats and the simulator compatibility layer. Some internal calls are omitted where excerpts show imports but not dispatch details.

Main entry points: [`src/cocotb_vivado/vivado/sources.py`](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/sources.py) (Vivado source types), [`src/cocotb_vivado/runner.py`](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/runner.py) (Build and test runner), [`src/cocotb_vivado/stub/simulator.py`](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/simulator.py) (Simulator API shim), [`src/cocotb_vivado/stub/manager.py`](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/manager.py) (Simulation manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build and Vivado inputs"]
  node_runner["Build and test runner<br/>[runner.py]"]
  node_vivado_sources["Vivado source types<br/>[sources.py]"]
  node_simdir["Simulation directory parser<br/>[sim_dir.py]"]
  node_snapshot["XSim snapshot"]
end

subgraph group_compat["Cocotb compatibility"]
  node_simulator_stub["Simulator API shim<br/>[simulator.py]"]
  node_manager["Simulation manager<br/>[manager.py]"]
  node_handles["Port and callback handles<br/>[handles.py]"]
  node_enums["GPI constants<br/>[_gpi_enums.py]"]
  node_xsi["XSI interface<br/>[xsi.py]"]
end

subgraph group_support["Vivado support"]
  node_tcl["Vivado command helpers<br/>[_tcl.py]"]
  node_part["Part discovery<br/>[part.py]"]
  node_vivado_api["Vivado source API<br/>[__init__.py]"]
end

node_engineer(("Test author"))
node_xsim["Vivado XSim tools"]
node_cocotb["cocotb runtime"]

node_engineer -->|"builds and tests"| node_runner
node_runner -->|"prepares sources"| node_vivado_sources
node_vivado_sources -->|"runs Vivado"| node_xsim
node_vivado_sources -->|"parses generated files"| node_simdir
node_runner -->|"builds or reuses"| node_snapshot
node_xsim -->|"produces"| node_snapshot
node_runner -->|"compiles and elaborates"| node_xsim
node_runner -->|"runs tests with"| node_cocotb
node_cocotb -.->|"uses simulator API"| node_simulator_stub
node_simulator_stub -->|"dispatches callbacks"| node_manager
node_simulator_stub -->|"exposes handle types"| node_handles
node_simulator_stub -->|"uses constants"| node_enums
node_manager -->|"drives simulation"| node_xsi
node_manager -->|"uses callbacks and ports"| node_handles
node_handles -->|"uses type constants"| node_enums
node_xsi -->|"loads XSI library"| node_xsim
node_vivado_api -->|"exports source classes"| node_vivado_sources
node_vivado_sources -->|"invokes tool helpers"| node_tcl
node_vivado_sources -->|"resolves part"| node_part
node_part -->|"uses discovery command"| node_tcl

click node_runner "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/runner.py"
click node_vivado_sources "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/sources.py"
click node_simdir "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/sim_dir.py"
click node_simulator_stub "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/simulator.py"
click node_manager "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/manager.py"
click node_handles "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/handles.py"
click node_enums "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/_gpi_enums.py"
click node_xsi "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/xsi.py"
click node_tcl "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/_tcl.py"
click node_part "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/part.py"
click node_vivado_api "https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/__init__.py"

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_runner,node_vivado_sources,node_simdir,node_snapshot toneBlue
class node_simulator_stub,node_manager,node_handles,node_enums,node_xsi toneAmber
class node_tcl,node_part,node_vivado_api toneMint
class node_engineer,node_xsim,node_cocotb toneIndigo
```

## Components

### Build and Vivado inputs

- [Build and test runner](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/runner.py): `src/cocotb_vivado/runner.py`
- [Vivado source types](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/sources.py): `src/cocotb_vivado/vivado/sources.py`
- [Simulation directory parser](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/sim_dir.py): `src/cocotb_vivado/vivado/sim_dir.py`
- **XSim snapshot**

### Cocotb compatibility

- [Simulator API shim](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/simulator.py): `src/cocotb_vivado/stub/simulator.py`
- [Simulation manager](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/manager.py): `src/cocotb_vivado/stub/manager.py`
- [Port and callback handles](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/stub/handles.py): `src/cocotb_vivado/stub/handles.py`
- [GPI constants](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/_gpi_enums.py): `src/cocotb_vivado/_gpi_enums.py`
- [XSI interface](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/xsi.py): `src/cocotb_vivado/xsi.py`

### Vivado support

- [Vivado command helpers](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/_tcl.py): `src/cocotb_vivado/vivado/_tcl.py`
- [Part discovery](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/part.py): `src/cocotb_vivado/vivado/part.py`
- [Vivado source API](https://github.com/themperek/cocotb-vivado/blob/main/src/cocotb_vivado/vivado/__init__.py): `src/cocotb_vivado/vivado/__init__.py`

### Other components

- **Test author**
- **Vivado XSim tools**
- **cocotb runtime**

## Connections

- Test author → Build and test runner: builds and tests (evidence: `README.md`)
- Build and test runner → Vivado source types: prepares sources (evidence: `README.md`)
- Vivado source types → Vivado XSim tools: runs Vivado (evidence: `README.md`)
- Vivado source types → Simulation directory parser: parses generated files (evidence: `README.md`)
- Build and test runner → XSim snapshot: builds or reuses (evidence: `README.md`)
- Vivado XSim tools → XSim snapshot: produces (evidence: `README.md`)
- Build and test runner → Vivado XSim tools: compiles and elaborates (evidence: `README.md`)
- Build and test runner → cocotb runtime: runs tests with (evidence: `README.md`)
- cocotb runtime → Simulator API shim: uses simulator API
- Simulator API shim → Simulation manager: dispatches callbacks (evidence: `src/cocotb_vivado/stub/simulator.py`)
- Simulator API shim → Port and callback handles: exposes handle types (evidence: `src/cocotb_vivado/stub/simulator.py`)
- Simulator API shim → GPI constants: uses constants (evidence: `src/cocotb_vivado/stub/simulator.py`)
- Simulation manager → XSI interface: drives simulation (evidence: `src/cocotb_vivado/stub/manager.py`)
- Simulation manager → Port and callback handles: uses callbacks and ports (evidence: `src/cocotb_vivado/stub/manager.py`)
- Port and callback handles → GPI constants: uses type constants (evidence: `src/cocotb_vivado/stub/handles.py`)
- XSI interface → Vivado XSim tools: loads XSI library (evidence: `src/cocotb_vivado/xsi.py`)
- Vivado source API → Vivado source types: exports source classes (evidence: `src/cocotb_vivado/vivado/__init__.py`)
- Vivado source types → Vivado command helpers: invokes tool helpers (evidence: `src/cocotb_vivado/vivado/sources.py`)
- Vivado source types → Part discovery: resolves part (evidence: `src/cocotb_vivado/vivado/sources.py`)
- Part discovery → Vivado command helpers: uses discovery command (evidence: `src/cocotb_vivado/vivado/part.py`)
