# drichmond/risc-v-on-pynq architecture

> Architecture diagram of the GitHub repository drichmond/risc-v-on-pynq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drichmond/risc-v-on-pynq
- Repository: https://github.com/drichmond/risc-v-on-pynq

## Overview

##### Project Type & Purpose
- This is a hardware-software co-design: a Python package that runs on a PYNQ-Z1 host, provides Jupyter magics and drivers to load and interact with RISC-V processor overlays on FPGA.
- Key use cases:
- Load and run PicoRV32 overlays (AXI or BRAM-only)
- Compile RISC-V C/Assembly code from notebooks
- Drive processor execution and memory I/O

##### High-Level Components
A. Host-Side (PYNQ-Z1 board with Linux + Jupyter)
1. Jupyter Notebook Interface
- Shows user code, magics (`%%compile_riscv`), demos, tutorials
2. Python Package: `riscvonpynq`
- Overlay Driver (subclass of `pynq.Overlay`)
- Notebook Magics (compile & program)
- RISC-V Program Class (manages build files, compiles via makefiles)
- Processor Drivers (BRAM‐only and Mixed BRAM+DDR variants, subclass `pynq.DefaultHierarchy`)
3. External RISC-V Toolchain
- GCC cross‐compiler invoked by magics/Program class

B. FPGA-Side
1. Bitstream (loaded by Overlay driver)
2. IP Core Hierarchy (the “overlay”)
- PicoRV32 Core
- Memory Interfaces:
- BRAM blocks (`picorv32_bram`)
- AXI interconnect + DDR bridge (`picorv32_axi`)
- PicoBram interface & Bridge (`picobridge`, `picobram_if`)
3. On-chip & Off-chip Memory
- FPGA BRAM
- On-board DDR via AXI

##### Relationships & Data Flow
- Notebook → riscvonpynq.Magics → RISC-V Toolchain → Compiled ELF/BIN
- Python Program API → Processor Driver → Memory‐mapped I/O → FPGA Memory → PicoRV32 Execution
- Overlay Driver → Loads Bitstream → Instantiates IP hierarchy in FPGA fabric
- Processor Driver ↔ Host Python via DMA/AXI/BRAM transfers

##### Architectural Patterns & Design Principles
- Layered architecture separating:
- User Interface (Jupyter)
- Middleware (Python package with Magics & Drivers)
- Hardware Abstraction (pynq.Overlay, DefaultHierarchy)
- Hardware Implementation (IP cores in FPGA)
- Reuse of Vivado packaging (component.xml, .tcl scripts under `ip/…`)
- Extensibility points:
- New overlays by dropping IP directories (`ip/*`)
- Notebook examples in `notebooks/`

##### Putting It All Together

[ External Toolchain ]
|
v
[Host-Side Tier]
+--------------------------------------------------+
| Jupyter Notebook                                |
|    ⇓                                           |
| riscvonpynq Package                             |
|   • OverlayDriver ← PYNQ API                    |
|   • NotebookMagics → RISC-V Toolchain          |
|   • ProgramClass → Makefiles (ip/*/build)      |
|   • ProcessorDrivers (BRAM / AXI variants)     |
+--------------------------------------------------+
|
v (Load .bit via JTAG/API)
[FPGA-Side Tier]
+--------------------------------------------------+
| FPGA Bitstream (Overlay)                         |
|   → IP Hierarchy:                                |
|     - picorv32_core                              |
|     - picorv32_axi + AXI Interconnect + DDR      |
|     - picorv32_bram                              |
|     - picobridge & picobram_if                   |
|   → On-chip BRAM, Off-chip DDR                   |
|   → Processor Execution & Memory-Mapped I/O      |
+--------------------------------------------------+

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Toolchain
    ET["External RISC-V Toolchain"]:::toolchain
    click ET "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/build.mk"

    %% Host-Side Tier
    subgraph "Host-Side (PYNQ-Z1 + Linux + Jupyter)"
        direction TB
        Notebook["Jupyter Notebook Interface"]:::host
        click Notebook "https://github.com/drichmond/risc-v-on-pynq/tree/master/notebooks/"
        Magics["Notebook Magics"]:::host
        click Magics "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/magic/Magic.py"
        ProgramCls["RISC-V Program Class\n(riscvonpynq/Program.py)"]:::host
        click ProgramCls "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/Program.py"
        ProcDrv["Processor Drivers\n(riscvonpynq/Processor.py)"]:::host
        click ProcDrv "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/Processor.py"
        OverlayDrv["Overlay Driver\n(riscvonpynq/Overlay.py)"]:::host
        click OverlayDrv "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/Overlay.py"
        Constraint["PYNQ-Z1 Constraints\n(riscvonpynq/PYNQ-Z1.xdc)"]:::host
        click Constraint "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/PYNQ-Z1.xdc"
    end

    %% FPGA-Side Tier
    subgraph "FPGA-Side (Overlay in FPGA Fabric)"
        direction TB
        Bit_AXI["AXI Bitstream"]:::fpga
        click Bit_AXI "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/picorv32/axi/picorv32.bit"
        HWH_AXI["AXI Metadata"]:::fpga
        click HWH_AXI "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/picorv32/axi/picorv32.hwh"
        Bit_BRAM["BRAM Bitstream"]:::fpga
        click Bit_BRAM "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/picorv32/bram/picorv32.bit"
        HWH_BRAM["BRAM Metadata"]:::fpga
        click HWH_BRAM "https://github.com/drichmond/risc-v-on-pynq/blob/master/riscvonpynq/picorv32/bram/picorv32.hwh"

        IP_AXI["PicoRV32 AXI Variant"]:::fpga
        click IP_AXI "https://github.com/drichmond/risc-v-on-pynq/tree/master/ip/picorv32_axi/"
        IP_BRAM_IP["PicoRV32 BRAM Variant"]:::fpga
        click IP_BRAM_IP "https://github.com/drichmond/risc-v-on-pynq/tree/master/ip/picorv32_bram/"
        IP_PICOBRAM_IF["PicoBram Interface"]:::fpga
        click IP_PICOBRAM_IF "https://github.com/drichmond/risc-v-on-pynq/tree/master/ip/picobram_if/"
        IP_PICOBRIDGE["PicoBridge (AXI↔BRAM)"]:::fpga
        click IP_PICOBRIDGE "https://github.com/drichmond/risc-v-on-pynq/tree/master/ip/picobridge/"
        IP_PCPI["PCPI Interface"]:::fpga
        click IP_PCPI "https://github.com/drichmond/risc-v-on-pynq/tree/master/ip/pcpi_v1_0/"

        Mem_BRAM["On-chip BRAM"]:::memory
        Mem_DDR["Off-chip DDR"]:::memory
    end

    %% Flows between tiers
    Notebook -->|"invokes"| Magics
    Magics -->|"calls GCC"| ET
    ET -->|"outputs ELF/BIN"| ProgramCls
    ProgramCls -->|"loads ELF/BIN"| ProcDrv
    ProgramCls -->|"uses makefiles"| OverlayDrv

    OverlayDrv -->|"load .bit/.hwh"| Bit_AXI
    OverlayDrv -->|"load .bit/.hwh"| Bit_BRAM

    Bit_AXI --> IP_AXI
    Bit_BRAM --> IP_BRAM_IP
    Bit_AXI --> IP_PICOBRIDGE
    IP_PICOBRIDGE --> IP_BRAM_IP
    IP_PICOBRAM_IF --> Mem_BRAM
    IP_AXI --> Mem_DDR
    IP_BRAM_IP --> Mem_BRAM
    ProcDrv -->|"AXI/BRAM DMA"| Mem_BRAM
    ProcDrv -->|"AXI/DDR DMA"| Mem_DDR

    %% Styles
    classDef host fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef fpga fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef toolchain fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef memory fill:#e2e3e5,stroke:#333,stroke-width:1px;
```
