How drichmond/risc-v-on-pynq works
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 |
+--------------------------------------------------+