# weng20011103/zcu102_pynq architecture

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

- Interactive diagram: https://gitdiagram.com/weng20011103/zcu102_pynq
- Repository: https://github.com/weng20011103/zcu102_pynq

## Overview

This repository is not one application; it is a ZCU102 PYNQ course kit. The architecture is a set of independent lesson projects that all use the same board/platform stack: ZCU102, Vivado 2020.2, and PYNQ v2.7.

The core system boundary is the classic Zynq split:
- Processing System (PS): ARM side running PYNQ/Python notebooks and scripts.
- Programmable Logic (PL): FPGA fabric containing RTL, AXI IP, clocking, DMA, and custom logic.

Most lessons demonstrate how the PS controls the PL through PYNQ abstractions such as GPIO, MMIO, and overlay loading. The notebooks are the user-facing control layer; the bitstreams, .hwh/.overlay metadata, and Vivado projects define the hardware layer.

The repo is organized by lesson, and each lesson is effectively a self-contained mini-architecture:
- Lesson 1–3: simplest GPIO-to-LED path, moving from direct GPIO use to XDC pin binding and then PYNQ bitstream loading.
- Lesson 4: PS-controlled GPIO driving an external DAC, showing board-level peripheral control.
- Lesson 5: clock generation and PS/bitstream constraints, including a frequency-divider RTL block and Clocking Wizard usage.
- Lesson 6: DMA-based data movement, focusing on streaming data between PS memory and PL logic.
- Lesson 7: HLS-generated IP integrated into a PYNQ workflow.
- Lesson 8: a custom AXI4-Lite IP block, showing register-mapped control logic.
- Lesson 9: Vivado TCL automation for reproducible hardware builds.
- Lesson 10: direct PYNQ MMIO access to registers, emphasizing low-level software control of PL hardware.

The dataflow patterns repeat across lessons and are important for a diagram:
- Notebook/script → PYNQ runtime on PS → AXI-Lite/MMIO/GPIO → PL registers or simple logic.
- Notebook/script → DMA buffers in memory → AXI DMA / AXI-Stream path → PL accelerator or FIFO.
- Vivado-generated hardware → bitstream + hardware handoff metadata → loaded by PYNQ as an overlay.

Hardware integration is expressed through constraints and pin mapping files:
- .xdc files bind FPGA signals to ZCU102 LEDs, DAC pins, PMOD headers, clocks, etc.
- RTL files (.v) define small blocks like LED logic, clock dividers, or AXI peripherals.
- HLS/IP artifacts and overlay descriptors connect higher-level generated IP to the same AXI infrastructure.

The supporting material is mostly instructional evidence rather than runtime code:
- Jupyter notebooks demonstrate PS-side control and testing.
- CSVs and plotting scripts capture scope measurements and validation data.
- Pictures and PDFs document expected waveforms, hardware behavior, and design notes.
- TCL scripts show automation for Vivado project creation or IP integration.

The main architectural diagram for this repo should therefore center on one ZCU102 board split into PS and PL, with multiple lesson-specific hardware blocks attached to the PL and multiple Python/Jupyter control paths on the PS. There is no single backend service or monolithic app; the repo is a catalog of hardware/software interaction patterns for FPGA development with PYNQ.

Main entry points: [`PYNQ/hwh`](https://github.com/weng20011103/zcu102_pynq/tree/main/PYNQ/hwh) (Overlay Load), [`lesson5_clocking_wizard_and_ps`](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson5_clocking_wizard_and_ps) (Clocking), [`PYNQ`](https://github.com/weng20011103/zcu102_pynq/tree/main/PYNQ) (PYNQ v2.7), [`lesson1_LED_kirakira_gpio`](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson1_LED_kirakira_gpio) (GPIO LED)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["ZCU102 Platform"]
  node_zcu102_board["ZCU102<br/>zynq board"]
  node_vivado_2020_2["Vivado 2020.2<br/>toolchain"]
end

subgraph group_ps["PS Side"]
  node_pynq_v2_7["PYNQ v2.7<br/>runtime"]
  node_notebooks["Notebooks"]
  node_mmio_gpio(("MMIO/GPIO<br/>PS control APIs"))
  node_overlay_loader["Overlay Load<br/>pynq overlay flow"]
end

subgraph group_pl["PL Side"]
  node_gpio_led_lessons["GPIO LED<br/>lesson cluster"]
  node_dac_control["DAC Control<br/>lesson cluster"]
  node_clocking_path["Clocking<br/>lesson cluster"]
  node_dma_path[("DMA Stream<br/>lesson cluster")]
  node_hls_ip["HLS IP<br/>generated accelerator"]
  node_axi_lite_ip["AXI4-Lite IP<br/>custom peripheral"]
  node_tcl_automation["TCL Automation<br/>build scripts"]
  node_mmio_registers(("PL Registers<br/>memory-mapped regs"))
  node_rtl_blocks{{"RTL Blocks<br/>verilog logic<br/>[led.v]"}}
  node_constraints["XDC Constraints<br/>pin mapping"]
end

subgraph group_support["Support Material"]
  node_measurement_data["Scope Data<br/>validation data"]
  node_lesson_docs["Lesson Docs<br/>readme and notes<br/>[README.md]"]
end

node_zcu102_board -->|"runs"| node_pynq_v2_7
node_zcu102_board -->|"targeted by"| node_vivado_2020_2
node_notebooks -->|"uses"| node_pynq_v2_7
node_pynq_v2_7 -->|"loads"| node_overlay_loader
node_overlay_loader -->|"configures"| node_gpio_led_lessons
node_overlay_loader -->|"configures"| node_dac_control
node_overlay_loader -->|"configures"| node_clocking_path
node_overlay_loader -->|"configures"| node_dma_path
node_overlay_loader -->|"configures"| node_hls_ip
node_overlay_loader -->|"configures"| node_axi_lite_ip
node_overlay_loader -->|"exposes"| node_mmio_registers
node_notebooks -->|"controls"| node_mmio_gpio
node_mmio_gpio -->|"drives"| node_gpio_led_lessons
node_mmio_gpio -->|"drives"| node_dac_control
node_mmio_gpio -->|"reads/writes"| node_mmio_registers
node_gpio_led_lessons -->|"binds via"| node_constraints
node_dac_control -->|"binds via"| node_constraints
node_clocking_path -->|"implements"| node_rtl_blocks
node_clocking_path -->|"binds via"| node_constraints
node_dma_path -->|"streams to"| node_hls_ip
node_hls_ip -->|"integrates with"| node_axi_lite_ip
node_axi_lite_ip -->|"exposes"| node_mmio_registers
node_tcl_automation -->|"automates"| node_vivado_2020_2
node_measurement_data -.->|"supports"| node_lesson_docs

click node_pynq_v2_7 "https://github.com/weng20011103/zcu102_pynq/tree/main/PYNQ"
click node_overlay_loader "https://github.com/weng20011103/zcu102_pynq/tree/main/PYNQ/hwh"
click node_gpio_led_lessons "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson1_LED_kirakira_gpio"
click node_dac_control "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson4_dac_control_by_pynq"
click node_clocking_path "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson5_clocking_wizard_and_ps"
click node_dma_path "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson6_dma_demo"
click node_hls_ip "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson7_hls_demo"
click node_axi_lite_ip "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson8_axi_lite_custom_ip"
click node_tcl_automation "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson9_vivado_tcl"
click node_mmio_registers "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson10_pynq_mmio"
click node_rtl_blocks "https://github.com/weng20011103/zcu102_pynq/blob/main/lesson2_LED_kirakira_xdc/led.v"
click node_constraints "https://github.com/weng20011103/zcu102_pynq/tree/main/XDC/ZCU102_GPIO_LED"
click node_measurement_data "https://github.com/weng20011103/zcu102_pynq/tree/main/lesson4_dac_control_by_pynq/data"
click node_lesson_docs "https://github.com/weng20011103/zcu102_pynq/blob/main/README.md"

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_zcu102_board,node_vivado_2020_2 toneBlue
class node_pynq_v2_7,node_notebooks,node_mmio_gpio,node_overlay_loader toneAmber
class node_gpio_led_lessons,node_dac_control,node_clocking_path,node_dma_path,node_hls_ip,node_axi_lite_ip,node_tcl_automation,node_mmio_registers,node_rtl_blocks,node_constraints toneMint
class node_measurement_data,node_lesson_docs toneRose
```

## Components

### ZCU102 Platform

Board and toolchain baseline shared by all lessons

- **ZCU102**: zynq board · Shared hardware target for every lesson
- **Vivado 2020.2**: toolchain · Hardware design and implementation environment

### PS Side

Python and notebook control running on the ARM processing system

- [PYNQ v2.7](https://github.com/weng20011103/zcu102_pynq/tree/main/PYNQ): runtime · PS runtime used to load overlays and access PL resources · `PYNQ`
- **Notebooks**: control notebooks · User-facing Python/Jupyter control layer across lessons
- **MMIO/GPIO**: PS control APIs · Low-level register and pin access from Python
- [Overlay Load](https://github.com/weng20011103/zcu102_pynq/tree/main/PYNQ/hwh): pynq overlay flow · Loads bitstreams and hardware metadata onto the board · `PYNQ/hwh`

### PL Side

FPGA fabric, RTL, IP, clocks, and interfaces

- [GPIO LED](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson1_LED_kirakira_gpio): lesson cluster · Lessons 1-3: basic LED control and pin binding · `lesson1_LED_kirakira_gpio`
- [DAC Control](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson4_dac_control_by_pynq): lesson cluster · Lesson 4: PS-driven external DAC control · `lesson4_dac_control_by_pynq`
- [Clocking](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson5_clocking_wizard_and_ps): lesson cluster · Lesson 5: clock generation and frequency division · `lesson5_clocking_wizard_and_ps`
- [DMA Stream](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson6_dma_demo): lesson cluster · Lesson 6: memory-to-stream data movement · `lesson6_dma_demo`
- [HLS IP](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson7_hls_demo): generated accelerator · Lesson 7: HLS-generated IP integrated through PYNQ · `lesson7_hls_demo`
- [AXI4-Lite IP](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson8_axi_lite_custom_ip): custom peripheral · Lesson 8: register-mapped custom logic block · `lesson8_axi_lite_custom_ip`
- [TCL Automation](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson9_vivado_tcl): build scripts · Lesson 9: scripted Vivado project and IP setup · `lesson9_vivado_tcl`
- [PL Registers](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson10_pynq_mmio): memory-mapped regs · Lesson 10: direct register access from PYNQ · `lesson10_pynq_mmio`
- [RTL Blocks](https://github.com/weng20011103/zcu102_pynq/blob/main/lesson2_LED_kirakira_xdc/led.v): verilog logic · Small modules such as LED logic and frequency dividers · `lesson2_LED_kirakira_xdc/led.v`
- [XDC Constraints](https://github.com/weng20011103/zcu102_pynq/tree/main/XDC/ZCU102_GPIO_LED): pin mapping · Board pin and interface binding for LEDs, DAC, PMOD, and clocks · `XDC/ZCU102_GPIO_LED`

### Support Material

Measurements, notes, and build documentation

- [Scope Data](https://github.com/weng20011103/zcu102_pynq/tree/main/lesson4_dac_control_by_pynq/data): validation data · CSV traces and plotting scripts used to verify hardware behavior · `lesson4_dac_control_by_pynq/data`
- [Lesson Docs](https://github.com/weng20011103/zcu102_pynq/blob/main/README.md): readme and notes · Readmes, PDFs, and notes documenting each lesson workflow · `README.md`

## Connections

- ZCU102 → PYNQ v2.7: runs · Board hosts the PYNQ image and runtime
- ZCU102 → Vivado 2020.2: targeted by · Vivado produces hardware for the board
- Notebooks → PYNQ v2.7: uses · Python notebooks execute through the PYNQ runtime
- PYNQ v2.7 → Overlay Load: loads · Overlay flow brings hardware metadata and bitstreams onto the PS
- Overlay Load → GPIO LED: configures · Loads the lesson-specific hardware for GPIO and LEDs
- Overlay Load → DAC Control: configures · Loads DAC control hardware and metadata
- Overlay Load → Clocking: configures · Loads clocking-related hardware
- Overlay Load → DMA Stream: configures · Loads DMA-based design overlays
- Overlay Load → HLS IP: configures · Loads HLS-generated accelerator designs
- Overlay Load → AXI4-Lite IP: configures · Loads custom AXI4-Lite peripherals
- Overlay Load → PL Registers: exposes · Makes register maps available for direct access
- Notebooks → MMIO/GPIO: controls · Notebook code drives pins and registers on the PS side
- MMIO/GPIO → GPIO LED: drives · Direct GPIO path to LEDs and simple peripherals
- MMIO/GPIO → DAC Control: drives · PS-side control of external DAC signals
- MMIO/GPIO → PL Registers: reads/writes · Direct memory-mapped access to PL registers
- GPIO LED → XDC Constraints: binds via · LED and header pins are fixed through XDC files
- DAC Control → XDC Constraints: binds via · DAC interface is mapped through board constraints
- Clocking → RTL Blocks: implements · Frequency divider and related RTL logic
- Clocking → XDC Constraints: binds via · Clock pins and generated outputs are constrained
- DMA Stream → HLS IP: streams to · DMA moves data between memory and accelerator logic
- HLS IP → AXI4-Lite IP: integrates with · Generated IP and custom peripherals share the AXI infrastructure
- AXI4-Lite IP → PL Registers: exposes · Registers are accessed through MMIO semantics
- TCL Automation → Vivado 2020.2: automates · Scripts create and configure Vivado projects
- Scope Data → Lesson Docs: supports · Plots, traces, and notes validate the lessons