# enjoy-digital/litex architecture

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

- Interactive diagram: https://gitdiagram.com/enjoy-digital/litex
- Repository: https://github.com/enjoy-digital/litex

## Overview

LiteX is a Python framework for composing FPGA logic and complete SoCs. A designer combines hardware cores, CPUs, interconnects, and board/target configuration; SoC integration brings these into a design that can be emitted as Verilog and used with FPGA toolchains. The repository also provides simulation, embedded BIOS/software, and host-side SoC access. The README documents the overall design flow; some subsystem details below rely on the file tree and SOURCE INDEX, so unsampled links are omitted.

Main entry points: [`litex/soc/integration/soc.py`](https://github.com/enjoy-digital/litex/blob/master/litex/soc/integration/soc.py) (SoC Integration), [`litex/gen/fhdl/verilog.py`](https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/verilog.py) (Verilog Backend), [`litex/soc/interconnect`](https://github.com/enjoy-digital/litex/tree/master/litex/soc/interconnect) (Bus Fabrics), [`litex/soc/interconnect/csr.py`](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr.py) (CSR Registers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hdl["Logic Generation"]
  node_fhdl_expression["HDL Expressions<br/>[expression.py]"]
  node_hierarchy["HDL Hierarchy<br/>[hierarchy.py]"]
  node_namer["Signal Naming<br/>[namer.py]"]
  node_verilog["Verilog Backend<br/>[verilog.py]"]
end

subgraph group_soc["SoC Composition"]
  node_soc_integration["SoC Integration<br/>[soc.py]"]
end

subgraph group_fabric["Interconnect Fabrics"]
  node_bus_fabrics["Bus Fabrics"]
  node_axi_full["AXI Full<br/>[axi_full.py]"]
  node_streams["Streams<br/>[stream.py]"]
  node_csr["CSR Registers<br/>[csr.py]"]
  node_csr_bus["CSR Bus<br/>[csr_bus.py]"]
  node_event_manager["Event Manager"]
end

subgraph group_hardware["Hardware Subsystems"]
  node_cpu_cores["CPU Cores"]
  node_peripheral_cores["Peripheral Cores"]
  node_hyperbus["HyperBus Core<br/>[hyperbus.py]"]
  node_video["Video Cores<br/>[video.py]"]
end

subgraph group_runtime["Simulation and Access"]
  node_simulation["Simulation<br/>[core.py]"]
  node_bios["BIOS<br/>[main.c]"]
  node_client["Host Client<br/>[litex_client.py]"]
  node_etherbone["Etherbone Transport<br/>[etherbone.py]"]
end

node_designer(("SoC Designer"))
node_fpga_tools["FPGA Toolchains"]

node_designer -->|"configures"| node_soc_integration
node_cpu_cores -->|"integrated by"| node_soc_integration
node_peripheral_cores -->|"integrated by"| node_soc_integration
node_hyperbus -->|"integrated by"| node_soc_integration
node_soc_integration -->|"uses"| node_bus_fabrics
node_soc_integration -->|"uses"| node_csr
node_soc_integration -->|"uses"| node_event_manager
node_soc_integration -->|"instantiates"| node_hyperbus
node_video -->|"uses"| node_streams
node_video -->|"uses"| node_csr
node_axi_full -->|"uses"| node_streams
node_event_manager -->|"builds registers"| node_csr
node_bus_fabrics -.->|"includes"| node_axi_full
node_bus_fabrics -.->|"includes"| node_csr_bus
node_fhdl_expression -->|"translated by"| node_verilog
node_hierarchy -->|"lowered by"| node_verilog
node_namer -->|"names signals for"| node_verilog
node_soc_integration -.->|"emits design through"| node_verilog
node_soc_integration -.->|"can simulate through"| node_simulation
node_soc_integration -.->|"provides embedded runtime"| node_bios
node_client -->|"uses transport"| node_etherbone
node_client -.->|"accesses SoC"| node_soc_integration
node_verilog -->|"feeds"| node_fpga_tools

click node_soc_integration "https://github.com/enjoy-digital/litex/blob/master/litex/soc/integration/soc.py"
click node_cpu_cores "https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu"
click node_peripheral_cores "https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores"
click node_hyperbus "https://github.com/enjoy-digital/litex/blob/master/litex/soc/cores/hyperbus.py"
click node_video "https://github.com/enjoy-digital/litex/blob/master/litex/soc/cores/video.py"
click node_bus_fabrics "https://github.com/enjoy-digital/litex/tree/master/litex/soc/interconnect"
click node_axi_full "https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/axi/axi_full.py"
click node_streams "https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/stream.py"
click node_csr "https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr.py"
click node_csr_bus "https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr_bus.py"
click node_event_manager "https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr_eventmanager.py"
click node_fhdl_expression "https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/expression.py"
click node_hierarchy "https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/hierarchy.py"
click node_namer "https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/namer.py"
click node_verilog "https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/verilog.py"
click node_simulation "https://github.com/enjoy-digital/litex/blob/master/litex/gen/sim/core.py"
click node_bios "https://github.com/enjoy-digital/litex/blob/master/litex/soc/software/bios/main.c"
click node_client "https://github.com/enjoy-digital/litex/blob/master/litex/tools/litex_client.py"
click node_etherbone "https://github.com/enjoy-digital/litex/blob/master/litex/tools/remote/etherbone.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_fhdl_expression,node_hierarchy,node_namer,node_verilog toneBlue
class node_soc_integration toneAmber
class node_bus_fabrics,node_axi_full,node_streams,node_csr,node_csr_bus,node_event_manager toneMint
class node_cpu_cores,node_peripheral_cores,node_hyperbus,node_video toneRose
class node_simulation,node_bios,node_client,node_etherbone,node_designer,node_fpga_tools toneIndigo
```

## Components

### Logic Generation

- [HDL Expressions](https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/expression.py): `litex/gen/fhdl/expression.py`
- [HDL Hierarchy](https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/hierarchy.py): `litex/gen/fhdl/hierarchy.py`
- [Signal Naming](https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/namer.py): `litex/gen/fhdl/namer.py`
- [Verilog Backend](https://github.com/enjoy-digital/litex/blob/master/litex/gen/fhdl/verilog.py): `litex/gen/fhdl/verilog.py`

### SoC Composition

- [SoC Integration](https://github.com/enjoy-digital/litex/blob/master/litex/soc/integration/soc.py): `litex/soc/integration/soc.py`

### Interconnect Fabrics

- [Bus Fabrics](https://github.com/enjoy-digital/litex/tree/master/litex/soc/interconnect): `litex/soc/interconnect`
- [AXI Full](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/axi/axi_full.py): `litex/soc/interconnect/axi/axi_full.py`
- [Streams](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/stream.py): `litex/soc/interconnect/stream.py`
- [CSR Registers](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr.py): `litex/soc/interconnect/csr.py`
- [CSR Bus](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr_bus.py): `litex/soc/interconnect/csr_bus.py`
- [Event Manager](https://github.com/enjoy-digital/litex/blob/master/litex/soc/interconnect/csr_eventmanager.py): `litex/soc/interconnect/csr_eventmanager.py`

### Hardware Subsystems

- [CPU Cores](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores/cpu): `litex/soc/cores/cpu`
- [Peripheral Cores](https://github.com/enjoy-digital/litex/tree/master/litex/soc/cores): `litex/soc/cores`
- [HyperBus Core](https://github.com/enjoy-digital/litex/blob/master/litex/soc/cores/hyperbus.py): `litex/soc/cores/hyperbus.py`
- [Video Cores](https://github.com/enjoy-digital/litex/blob/master/litex/soc/cores/video.py): `litex/soc/cores/video.py`

### Simulation and Access

- [Simulation](https://github.com/enjoy-digital/litex/blob/master/litex/gen/sim/core.py): `litex/gen/sim/core.py`
- [BIOS](https://github.com/enjoy-digital/litex/blob/master/litex/soc/software/bios/main.c): `litex/soc/software/bios/main.c`
- [Host Client](https://github.com/enjoy-digital/litex/blob/master/litex/tools/litex_client.py): `litex/tools/litex_client.py`
- [Etherbone Transport](https://github.com/enjoy-digital/litex/blob/master/litex/tools/remote/etherbone.py): `litex/tools/remote/etherbone.py`

### Other components

- **SoC Designer**
- **FPGA Toolchains**

## Connections

- SoC Designer → SoC Integration: configures
- CPU Cores → SoC Integration: integrated by (evidence: `litex/soc/integration/soc.py`)
- Peripheral Cores → SoC Integration: integrated by (evidence: `litex/soc/integration/soc.py`)
- HyperBus Core → SoC Integration: integrated by (evidence: `litex/soc/integration/soc.py`)
- SoC Integration → Bus Fabrics: uses (evidence: `litex/soc/integration/soc.py`)
- SoC Integration → CSR Registers: uses (evidence: `litex/soc/integration/soc.py`)
- SoC Integration → Event Manager: uses (evidence: `litex/soc/integration/soc.py`)
- SoC Integration → HyperBus Core: instantiates (evidence: `litex/soc/integration/soc.py`)
- Video Cores → Streams: uses (evidence: `litex/soc/cores/video.py`)
- Video Cores → CSR Registers: uses (evidence: `litex/soc/cores/video.py`)
- AXI Full → Streams: uses (evidence: `litex/soc/interconnect/axi/axi_full.py`)
- Event Manager → CSR Registers: builds registers (evidence: `litex/soc/interconnect/csr_eventmanager.py`)
- Bus Fabrics → AXI Full: includes (evidence: `litex/soc/interconnect/axi/__init__.py`)
- Bus Fabrics → CSR Bus: includes (evidence: `litex/soc/interconnect/wishbone.py`)
- HDL Expressions → Verilog Backend: translated by (evidence: `litex/gen/fhdl/verilog.py`)
- HDL Hierarchy → Verilog Backend: lowered by (evidence: `litex/gen/fhdl/verilog.py`)
- Signal Naming → Verilog Backend: names signals for (evidence: `litex/gen/fhdl/verilog.py`)
- SoC Integration → Verilog Backend: emits design through
- SoC Integration → Simulation: can simulate through
- SoC Integration → BIOS: provides embedded runtime
- Host Client → Etherbone Transport: uses transport (evidence: `litex/tools/litex_client.py`)
- Host Client → SoC Integration: accesses SoC
- Verilog Backend → FPGA Toolchains: feeds
