# ichen522/axi_dma architecture

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

- Interactive diagram: https://gitdiagram.com/ichen522/axi_dma
- Repository: https://github.com/ichen522/axi_dma
- Video tour (about a minute): https://gitdiagram.com/ichen522/axi_dma/video

## Overview

This repository implements a four-channel AXI DMA: software programs transfers through AXI4-Lite, the DMA arbitrates and moves data over AXI4, and software observes completion or error interrupts. The RTL also includes byte realignment, burst management, error handling, and parameterized outstanding reads. Separate branches capture the documented verification, arbiter fairness proof, implementation sign-off, and bandwidth/area analysis capabilities. RTL relationships follow the README’s architecture and transfer descriptions; unsampled verification and implementation internals are represented only at their supported directory paths.

Main entry points: [`rtl/dma_top.sv`](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_top.sv) (DMA Top), [`rtl/dma_engine.sv`](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_engine.sv) (Shared Engine), [`rtl/dma_csr.sv`](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_csr.sv) (CSR and IRQ), [`rtl/dma_channel.sv`](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_channel.sv) (Channel Control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rtl_control["Control RTL"]
  node_top["DMA Top<br/>[dma_top.sv]"]
  node_csr["CSR and IRQ<br/>[dma_csr.sv]"]
  node_channel["Channel Control<br/>[dma_channel.sv]"]
end

subgraph group_rtl_datapath["AXI Datapath"]
  node_engine["Shared Engine<br/>[dma_engine.sv]"]
  node_arbiter["Round-Robin Arbiter<br/>[dma_rr_arb.sv]"]
  node_fifo["Descriptor and W FIFOs<br/>[dma_fifo.sv]"]
end

subgraph group_verification["Verification"]
  node_testbench["Simulation Testbench"]
  node_reference["C Reference Model<br/>[dma_ref.c]"]
  node_formal["Fairness Proof<br/>[arb_fairness.sv]"]
  node_mutation["Mutation Checks<br/>[mutants.py]"]
end

subgraph group_implementation["Implementation"]
  node_synthesis["Synthesis and STA"]
end

subgraph group_analysis["Performance Analysis"]
  node_area_sweep["Area Sweep<br/>[area_sweep.sh]"]
  node_util_sweep["Utilisation Sweep<br/>[sweep.py]"]
  node_tradeoff["Area Trade-off<br/>[area_tradeoff.py]"]
end

node_software(("Software"))
node_memory[("AXI Memory")]

node_software -->|"programs via AXI-Lite"| node_csr
node_csr -->|"signals IRQ"| node_software
node_top -->|"instantiates"| node_csr
node_top -->|"instantiates"| node_channel
node_top -->|"instantiates"| node_engine
node_csr -->|"sends start and config"| node_channel
node_channel -->|"reports done or error"| node_csr
node_channel -->|"requests chunks"| node_engine
node_engine -->|"arbitrates requests"| node_arbiter
node_engine -->|"uses queues"| node_fifo
node_engine -->|"issues AXI bursts"| node_memory
node_memory -->|"returns read and write responses"| node_engine
node_testbench -->|"simulates RTL"| node_top
node_testbench -->|"checks against"| node_reference
node_formal -->|"proves fairness"| node_arbiter
node_mutation -->|"checks bug detection"| node_testbench
node_top -->|"implemented and timed"| node_synthesis
node_area_sweep -.->|"measures configurations"| node_synthesis
node_util_sweep -->|"simulates configurations"| node_top
node_tradeoff -->|"joins utilisation data"| node_util_sweep
node_tradeoff -->|"joins area data"| node_area_sweep

click node_top "https://github.com/ichen522/axi_dma/blob/main/rtl/dma_top.sv"
click node_csr "https://github.com/ichen522/axi_dma/blob/main/rtl/dma_csr.sv"
click node_channel "https://github.com/ichen522/axi_dma/blob/main/rtl/dma_channel.sv"
click node_engine "https://github.com/ichen522/axi_dma/blob/main/rtl/dma_engine.sv"
click node_arbiter "https://github.com/ichen522/axi_dma/blob/main/rtl/dma_rr_arb.sv"
click node_fifo "https://github.com/ichen522/axi_dma/blob/main/rtl/dma_fifo.sv"
click node_testbench "https://github.com/ichen522/axi_dma/tree/main/tb"
click node_reference "https://github.com/ichen522/axi_dma/blob/main/tb/ref/dma_ref.c"
click node_formal "https://github.com/ichen522/axi_dma/blob/main/formal/arb_fairness.sv"
click node_mutation "https://github.com/ichen522/axi_dma/blob/main/scripts/mutants.py"
click node_synthesis "https://github.com/ichen522/axi_dma/tree/main/syn"
click node_area_sweep "https://github.com/ichen522/axi_dma/blob/main/analysis/area_sweep.sh"
click node_util_sweep "https://github.com/ichen522/axi_dma/blob/main/analysis/sweep.py"
click node_tradeoff "https://github.com/ichen522/axi_dma/blob/main/analysis/area_tradeoff.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_top,node_csr,node_channel toneBlue
class node_engine,node_arbiter,node_fifo,node_memory toneAmber
class node_testbench,node_reference,node_formal,node_mutation toneMint
class node_synthesis toneRose
class node_area_sweep,node_util_sweep,node_tradeoff,node_software toneIndigo
```

## Components

### Control RTL

- [DMA Top](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_top.sv): `rtl/dma_top.sv`
- [CSR and IRQ](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_csr.sv): `rtl/dma_csr.sv`
- [Channel Control](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_channel.sv): `rtl/dma_channel.sv`

### AXI Datapath

- [Shared Engine](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_engine.sv): `rtl/dma_engine.sv`
- [Round-Robin Arbiter](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_rr_arb.sv): `rtl/dma_rr_arb.sv`
- [Descriptor and W FIFOs](https://github.com/ichen522/axi_dma/blob/main/rtl/dma_fifo.sv): `rtl/dma_fifo.sv`

### Verification

- [Simulation Testbench](https://github.com/ichen522/axi_dma/tree/main/tb): `tb`
- [C Reference Model](https://github.com/ichen522/axi_dma/blob/main/tb/ref/dma_ref.c): `tb/ref/dma_ref.c`
- [Fairness Proof](https://github.com/ichen522/axi_dma/blob/main/formal/arb_fairness.sv): `formal/arb_fairness.sv`
- [Mutation Checks](https://github.com/ichen522/axi_dma/blob/main/scripts/mutants.py): `scripts/mutants.py`

### Implementation

- [Synthesis and STA](https://github.com/ichen522/axi_dma/tree/main/syn): `syn`

### Performance Analysis

- [Area Sweep](https://github.com/ichen522/axi_dma/blob/main/analysis/area_sweep.sh): `analysis/area_sweep.sh`
- [Utilisation Sweep](https://github.com/ichen522/axi_dma/blob/main/analysis/sweep.py): `analysis/sweep.py`
- [Area Trade-off](https://github.com/ichen522/axi_dma/blob/main/analysis/area_tradeoff.py): `analysis/area_tradeoff.py`

### Other components

- **Software**
- **AXI Memory**

## Connections

- Software → CSR and IRQ: programs via AXI-Lite (evidence: `README.md`)
- CSR and IRQ → Software: signals IRQ (evidence: `README.md`)
- DMA Top → CSR and IRQ: instantiates (evidence: `README.md`)
- DMA Top → Channel Control: instantiates (evidence: `README.md`)
- DMA Top → Shared Engine: instantiates (evidence: `README.md`)
- CSR and IRQ → Channel Control: sends start and config (evidence: `README.md`)
- Channel Control → CSR and IRQ: reports done or error (evidence: `README.md`)
- Channel Control → Shared Engine: requests chunks (evidence: `README.md`)
- Shared Engine → Round-Robin Arbiter: arbitrates requests (evidence: `README.md`)
- Shared Engine → Descriptor and W FIFOs: uses queues (evidence: `README.md`)
- Shared Engine → AXI Memory: issues AXI bursts (evidence: `README.md`)
- AXI Memory → Shared Engine: returns read and write responses (evidence: `README.md`)
- Simulation Testbench → DMA Top: simulates RTL (evidence: `README.md`)
- Simulation Testbench → C Reference Model: checks against (evidence: `README.md`)
- Fairness Proof → Round-Robin Arbiter: proves fairness (evidence: `README.md`)
- Mutation Checks → Simulation Testbench: checks bug detection (evidence: `README.md`)
- DMA Top → Synthesis and STA: implemented and timed (evidence: `README.md`)
- Area Sweep → Synthesis and STA: measures configurations
- Utilisation Sweep → DMA Top: simulates configurations (evidence: `analysis/sweep.py`)
- Area Trade-off → Utilisation Sweep: joins utilisation data (evidence: `analysis/area_tradeoff.py`)
- Area Trade-off → Area Sweep: joins area data (evidence: `analysis/area_tradeoff.py`)