fpga-design-implview 0.1.0__tar.gz

fpga_design_implview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rocco Ardino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fpga_design_implview-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tests *.py
+recursive-include examples *.toml

fpga_design_implview-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: fpga-design-implview
+Version: 0.1.0
+Summary: Pictures and an interactive viewer of Vivado implemented designs: device resources and what the design uses of them
+Author-email: Rocco Ardino <roccoardino@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rardino/fpga-design-implview
+Project-URL: Issues, https://github.com/rardino/fpga-design-implview/issues
+Keywords: fpga,vivado,floorplan,placement,routing,visualization,eda
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# Vivado implemented design renderer and viewer
+
+This project was made with the help of Claude Opus 5.5.
+
+`fpga-design-implview` draws what a Vivado implementation uses of the device: every site
+of the part (slices, BRAM, DSP, URAM, IO, GT, clocking, hard blocks), lit up when the
+design uses it and colored by hierarchy, with the part, WNS/WHS and the legend. The
+part comes from the checkpoint: any design, any device.
+
+## Examples
+
+PYNQ-Z2 (xc7z020), placement and routing usage:
+
+<p>
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/gpt.png" width="49%" alt="PYNQ-Z2 design, placement">
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/gpt_routing.png" width="49%" alt="PYNQ-Z2 design, routing usage">
+</p>
+
+<p>
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/mlp.png" width="49%" alt="PYNQ-Z2 design, placement">
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/mlp_routing.png" width="49%" alt="PYNQ-Z2 design, routing usage">
+</p>
+
+Note: the text on the right is optional, `--no-panel` leaves only the device.
+
+## Install
+
+```sh
+pipx install fpga-design-implview   # or pip; Python 3.11+
+```
+
+The command is `fpga-design-implview`, or `implview` for short. Vivado is needed to read
+the checkpoint (with a license for its device); drawing works without it.
+
+## Usage
+
+```sh
+fpga-design-implview render path/to/impl_1               # <top>.png, <top>.pdf
+fpga-design-implview render top_routed.dcp -o top.html   # interactive viewer
+fpga-design-implview render path/to/impl_1 -H highlight.toml --stats --theme dark
+```
+
+The input is a run directory, a project directory or a routed checkpoint. The output
+format follows the extension: `.png` (placement, plus `_routing.png`), `.pdf`, `.svg`,
+`.html`.
+
+The first run opens the checkpoint in Vivado (batch mode) and caches the export in
+`~/.cache/implview`, so later renders take seconds. Vivado is `$IMPLVIEW_VIVADO` (or
+`--vivado CMD` before the command), else `vivado` on the PATH, else the install under
+`~/opt/xilinx`, `~/Xilinx`, `/opt/Xilinx` or `/tools/Xilinx` matching the checkpoint's
+version.
+
+| Option                     | What                                              |
+|----------------------------|---------------------------------------------------|
+| `-o FILE`, `-O DIR`        | output file (repeatable), output directory        |
+| `-H FILE`                  | highlight file: what to color and how             |
+| `-g PATH`                  | color a hierarchy path (repeatable)               |
+| `--depth N`                | automatic groups cut at depth N                   |
+| `--stats`                  | utilization table and cells per group             |
+| `--theme dark`             | dark theme                                        |
+| `--no-routing`             | skip the routing page (faster first export)       |
+| `--no-panel`, `--no-labels` | device only, no names on it                    |
+| `--save-highlight FILE`    | write the groups used as a highlight file         |
+| `--refresh`                | export again, ignore the cache                    |
+
+Other commands: `export` (only the export), `device PART` (only the device), `info`
+(part, top, cache status), `tcl` (path of `implview.tcl`).
+
+## Colors
+
+By default the hierarchy is split into up to 8 groups. A highlight file (`-H`) chooses:
+
+```toml
+[[highlight]]
+path = "u_core/u_fft"                # * inside one level, ** any depth
+color = "#2a78d6"
+label = "FFT"
+
+[[highlight]]
+path = "u_core/gen_ch[*].u_filter"   # a generate loop: one shade per instance
+color = ["#8fe0bb", "#0f6e4b"]
+label = "filter"
+
+[options]
+others = "grey"                      # or "hide"; also theme, stats, labels, panel
+```
+
+The most specific path holds a cell. More in
+[examples](https://github.com/rardino/fpga-design-implview/tree/main/examples).
+
+## Viewer
+
+Scroll to zoom, drag to pan, `F` to fit. Hover a site for its cells, click to pin them,
+click a cell to highlight its module. Search cell names (`*`, `?`), toggle groups and
+layers (routing, clock regions, pblocks), switch light/dark, save the view as PNG.
+
+## From a build script
+
+Export at the end of the implementation run, in the same Vivado session, to skip
+opening the checkpoint again (`fpga-design-implview tcl` prints the script's path):
+
+```tcl
+source /path/to/implview.tcl
+implview::export_all $out/implview -routing     ;# <top>.ivd.gz and <part>.ivdev.gz
+```
+
+then `fpga-design-implview render $out/implview/<top>.ivd.gz`.
+
+## Status
+
+Tried on Zynq-7000 (xc7z020) and Virtex UltraScale+ HBM (xcvu37p, three SLRs).
+UltraScale, Zynq UltraScale+ and Versal are not tried yet. Nets are not drawn, only how
+much each interconnect tile is used. The picture follows Vivado's tile grid, not the die
+to scale.
+
+Tests, from a clone: `pip install -e .[test] && pytest` (no Vivado needed).

fpga_design_implview-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Vivado implemented design renderer and viewer
+
+This project was made with the help of Claude Opus 5.5.
+
+`fpga-design-implview` draws what a Vivado implementation uses of the device: every site
+of the part (slices, BRAM, DSP, URAM, IO, GT, clocking, hard blocks), lit up when the
+design uses it and colored by hierarchy, with the part, WNS/WHS and the legend. The
+part comes from the checkpoint: any design, any device.
+
+## Examples
+
+PYNQ-Z2 (xc7z020), placement and routing usage:
+
+<p>
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/gpt.png" width="49%" alt="PYNQ-Z2 design, placement">
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/gpt_routing.png" width="49%" alt="PYNQ-Z2 design, routing usage">
+</p>
+
+<p>
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/mlp.png" width="49%" alt="PYNQ-Z2 design, placement">
+<img src="https://github.com/rardino/fpga-design-implview/raw/main/docs/pynq-z2/mlp_routing.png" width="49%" alt="PYNQ-Z2 design, routing usage">
+</p>
+
+Note: the text on the right is optional, `--no-panel` leaves only the device.
+
+## Install
+
+```sh
+pipx install fpga-design-implview   # or pip; Python 3.11+
+```
+
+The command is `fpga-design-implview`, or `implview` for short. Vivado is needed to read
+the checkpoint (with a license for its device); drawing works without it.
+
+## Usage
+
+```sh
+fpga-design-implview render path/to/impl_1               # <top>.png, <top>.pdf
+fpga-design-implview render top_routed.dcp -o top.html   # interactive viewer
+fpga-design-implview render path/to/impl_1 -H highlight.toml --stats --theme dark
+```
+
+The input is a run directory, a project directory or a routed checkpoint. The output
+format follows the extension: `.png` (placement, plus `_routing.png`), `.pdf`, `.svg`,
+`.html`.
+
+The first run opens the checkpoint in Vivado (batch mode) and caches the export in
+`~/.cache/implview`, so later renders take seconds. Vivado is `$IMPLVIEW_VIVADO` (or
+`--vivado CMD` before the command), else `vivado` on the PATH, else the install under
+`~/opt/xilinx`, `~/Xilinx`, `/opt/Xilinx` or `/tools/Xilinx` matching the checkpoint's
+version.
+
+| Option                     | What                                              |
+|----------------------------|---------------------------------------------------|
+| `-o FILE`, `-O DIR`        | output file (repeatable), output directory        |
+| `-H FILE`                  | highlight file: what to color and how             |
+| `-g PATH`                  | color a hierarchy path (repeatable)               |
+| `--depth N`                | automatic groups cut at depth N                   |
+| `--stats`                  | utilization table and cells per group             |
+| `--theme dark`             | dark theme                                        |
+| `--no-routing`             | skip the routing page (faster first export)       |
+| `--no-panel`, `--no-labels` | device only, no names on it                    |
+| `--save-highlight FILE`    | write the groups used as a highlight file         |
+| `--refresh`                | export again, ignore the cache                    |
+
+Other commands: `export` (only the export), `device PART` (only the device), `info`
+(part, top, cache status), `tcl` (path of `implview.tcl`).
+
+## Colors
+
+By default the hierarchy is split into up to 8 groups. A highlight file (`-H`) chooses:
+
+```toml
+[[highlight]]
+path = "u_core/u_fft"                # * inside one level, ** any depth
+color = "#2a78d6"
+label = "FFT"
+
+[[highlight]]
+path = "u_core/gen_ch[*].u_filter"   # a generate loop: one shade per instance
+color = ["#8fe0bb", "#0f6e4b"]
+label = "filter"
+
+[options]
+others = "grey"                      # or "hide"; also theme, stats, labels, panel
+```
+
+The most specific path holds a cell. More in
+[examples](https://github.com/rardino/fpga-design-implview/tree/main/examples).
+
+## Viewer
+
+Scroll to zoom, drag to pan, `F` to fit. Hover a site for its cells, click to pin them,
+click a cell to highlight its module. Search cell names (`*`, `?`), toggle groups and
+layers (routing, clock regions, pblocks), switch light/dark, save the view as PNG.
+
+## From a build script
+
+Export at the end of the implementation run, in the same Vivado session, to skip
+opening the checkpoint again (`fpga-design-implview tcl` prints the script's path):
+
+```tcl
+source /path/to/implview.tcl
+implview::export_all $out/implview -routing     ;# <top>.ivd.gz and <part>.ivdev.gz
+```
+
+then `fpga-design-implview render $out/implview/<top>.ivd.gz`.
+
+## Status
+
+Tried on Zynq-7000 (xc7z020) and Virtex UltraScale+ HBM (xcvu37p, three SLRs).
+UltraScale, Zynq UltraScale+ and Versal are not tried yet. Nets are not drawn, only how
+much each interconnect tile is used. The picture follows Vivado's tile grid, not the die
+to scale.
+
+Tests, from a clone: `pip install -e .[test] && pytest` (no Vivado needed).

fpga_design_implview-0.1.0/examples/highlight.toml

@@ -0,0 +1,41 @@
+# Example highlight file, for a design with this hierarchy:
+#   u_core/u_fft, u_core/gen_ch[0..3].u_filter, u_core/u_ctrl,
+#   u_io/u_adc_a, u_io/u_adc_b, u_io/u_pcie, u_io/u_ddr
+#
+#   fpga-design-implview render path/to/impl_1 -H examples/highlight.toml
+#
+# path: hierarchy path, * inside one level, ** any depth, brackets are literal.
+# A path matching several instances (a generate loop) gets one shade each.
+
+[[highlight]]
+path = "u_core/u_fft"
+color = "#2a78d6"
+label = "FFT"
+
+[[highlight]]
+path = "u_core/gen_ch[*].u_filter"
+color = ["#8fe0bb", "#0f6e4b"]      # channel 0 light, channel 3 dark
+label = "filter"
+
+[[highlight]]
+path = "u_core/u_ctrl"
+color = "#eda100"
+label = "control"
+
+[[highlight]]
+path = "u_io/u_adc_*"                # u_adc_a and u_adc_b
+color = "#e87ba4"
+label = "ADC"
+
+[[highlight]]
+path = "u_io/u_pcie"
+color = "#eb6834"
+label = "PCIe"
+
+[[highlight]]
+path = "u_io/u_ddr"
+color = "#e34948"
+label = "DDR"
+
+[options]
+others = "grey"                      # everything else; "hide" to leave it uncolored

fpga_design_implview-0.1.0/examples/pynq-z2/gpt.toml

@@ -0,0 +1,72 @@
+# PYNQ-Z2 (xc7z020): the infrastructure and a GPT accelerator.
+#
+#   fpga-design-implview render pynqz2-gpt.ivd.gz -H examples/pynq-z2/gpt.toml
+#
+# The accelerator's AXI registers and stream FIFOs, the GP0 split and ID
+# slot and the PS resets are left in "(other)".
+
+# The infrastructure, the same colors in the three examples: warm for the
+# infrastructure, blue and violet for the model.
+
+[[highlight]]
+path = "u_ps/u_system/ps7"
+color = "#eb6834"
+label = "PS7"
+
+[[highlight]]
+path = "u_ps/u_system/sc_hp"
+color = "#eda100"
+label = "SmartConnect HP0"
+
+[[highlight]]
+path = "u_ps/u_system/sc_ctrl"
+color = "#e87ba4"
+label = "SmartConnect GP0"
+
+[[highlight]]
+path = "u_core/u_dma"
+color = "#1baf7a"
+label = "AXI DMA"
+
+[[highlight]]
+path = "u_core/u_ddr_rw"
+color = "#008300"
+label = "ddr_rw"
+
+[[highlight]]
+path = "u_core/u_test"
+color = "#e34948"
+label = "axis_test"
+
+# The GPT. gpt_core holds the parameter memories and the model (u_gpt); the
+# more specific paths below take their cells out of it.
+
+[[highlight]]
+path = "u_core/g_gpt.u_gpt/u_core"
+color = "#a77be0"
+label = "GPT parameters"
+
+[[highlight]]
+path = "u_core/g_gpt.u_gpt/u_core/u_gpt"
+color = "#174a8b"
+color_dark = "#4f8fe0"
+label = "GPT: embedding, head, glue"
+
+[[highlight]]
+path = "u_core/g_gpt.u_gpt/u_core/u_gpt/u_block/u_attention"
+color = "#2a78d6"
+label = "attention"
+
+[[highlight]]
+path = "u_core/g_gpt.u_gpt/u_core/u_gpt/u_block/u_engine"
+color = "#6250d6"
+label = "linear engine"
+
+[[highlight]]
+path = "u_core/g_gpt.u_gpt/u_core/u_gpt/**/u_ln*"   # u_ln1, u_ln2, u_lnf
+color = "#7fb4ee"
+gradient = false
+label = "layer norms"
+
+[options]
+others = "grey"

fpga_design_implview-0.1.0/examples/pynq-z2/mlp.toml

@@ -0,0 +1,60 @@
+# PYNQ-Z2 (xc7z020): the infrastructure and an MLP accelerator.
+#
+#   fpga-design-implview render pynqz2-mlp.ivd.gz -H examples/pynq-z2/mlp.toml
+#
+# The accelerator's AXI registers and stream FIFOs, the GP0 split and ID
+# slot and the PS resets are left in "(other)".
+
+# The infrastructure, the same colors in the three examples: warm for the
+# infrastructure, blue and violet for the model.
+
+[[highlight]]
+path = "u_ps/u_system/ps7"
+color = "#eb6834"
+label = "PS7"
+
+[[highlight]]
+path = "u_ps/u_system/sc_hp"
+color = "#eda100"
+label = "SmartConnect HP0"
+
+[[highlight]]
+path = "u_ps/u_system/sc_ctrl"
+color = "#e87ba4"
+label = "SmartConnect GP0"
+
+[[highlight]]
+path = "u_core/u_dma"
+color = "#1baf7a"
+label = "AXI DMA"
+
+[[highlight]]
+path = "u_core/u_ddr_rw"
+color = "#008300"
+label = "ddr_rw"
+
+[[highlight]]
+path = "u_core/u_test"
+color = "#e34948"
+label = "axis_test"
+
+# The MLP. mlp_core holds the parameter memories and the network (u_mlp).
+
+[[highlight]]
+path = "u_core/g_mlp.u_mlp/u_core"
+color = "#a77be0"
+label = "MLP parameters"
+
+[[highlight]]
+path = "u_core/g_mlp.u_mlp/u_core/u_mlp"
+color = "#174a8b"
+color_dark = "#4f8fe0"
+label = "MLP: argmax, glue"
+
+[[highlight]]
+path = "u_core/g_mlp.u_mlp/u_core/u_mlp/u_l*"   # one shade per layer
+color = ["#2a78d6", "#7fb4ee"]
+label = "layer"
+
+[options]
+others = "grey"

fpga_design_implview-0.1.0/examples/pynq-z2/platform.toml

@@ -0,0 +1,44 @@
+# PYNQ-Z2 (xc7z020), the infrastructure alone: the PS7 with an AXI
+# SmartConnect on GP0 and on HP0, and in the PL the GP0 register slots,
+# ddr_rw, the AXI DMA and axis_test.
+#
+#   fpga-design-implview render pynqz2-platform.ivd.gz -H examples/pynq-z2/platform.toml
+#
+# The GP0 split and ID slot, the PS resets and the LED counters are left in
+# "(other)".
+
+# The infrastructure, the same colors in the three examples: warm for the
+# infrastructure, blue and violet for the model.
+
+[[highlight]]
+path = "u_ps/u_system/ps7"
+color = "#eb6834"
+label = "PS7"
+
+[[highlight]]
+path = "u_ps/u_system/sc_hp"
+color = "#eda100"
+label = "SmartConnect HP0"
+
+[[highlight]]
+path = "u_ps/u_system/sc_ctrl"
+color = "#e87ba4"
+label = "SmartConnect GP0"
+
+[[highlight]]
+path = "u_core/u_dma"
+color = "#1baf7a"
+label = "AXI DMA"
+
+[[highlight]]
+path = "u_core/u_ddr_rw"
+color = "#008300"
+label = "ddr_rw"
+
+[[highlight]]
+path = "u_core/u_test"
+color = "#e34948"
+label = "axis_test"
+
+[options]
+others = "grey"

fpga_design_implview-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fpga-design-implview"
+dynamic = ["version"]
+description = "Pictures and an interactive viewer of Vivado implemented designs: device resources and what the design uses of them"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Rocco Ardino", email = "roccoardino@gmail.com" }]
+keywords = ["fpga", "vivado", "floorplan", "placement", "routing", "visualization", "eda"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = ["numpy>=1.24", "matplotlib>=3.7"]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/rardino/fpga-design-implview"
+Issues = "https://github.com/rardino/fpga-design-implview/issues"
+
+[project.scripts]
+fpga-design-implview = "fpga_design_implview.cli:main"
+implview = "fpga_design_implview.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "fpga_design_implview.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fpga_design_implview = ["tcl/*.tcl"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fpga_design_implview-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fpga_design_implview-0.1.0/src/fpga_design_implview/__init__.py

@@ -0,0 +1,3 @@
+"""Pictures and an interactive viewer of Vivado implemented designs."""
+
+__version__ = "0.1.0"

fpga_design_implview-0.1.0/src/fpga_design_implview/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

fpga_design_implview-0.1.0/src/fpga_design_implview/cache.py

@@ -0,0 +1,26 @@
+"""Exports are cached: devices by part, designs by checkpoint and options."""
+
+import hashlib
+import os
+
+
+def root():
+    base = os.environ.get("IMPLVIEW_CACHE") or os.path.join(
+        os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache"), "implview")
+    return base
+
+
+def device_path(part):
+    d = os.path.join(root(), "devices")
+    os.makedirs(d, exist_ok=True)
+    return os.path.join(d, f"{part}.ivdev.gz")
+
+
+def design_path(dcp, *opts):
+    st = os.stat(dcp)
+    key = f"{os.path.abspath(dcp)}|{st.st_mtime_ns}|{st.st_size}|{'|'.join(map(str, opts))}"
+    h = hashlib.sha1(key.encode()).hexdigest()[:16]
+    d = os.path.join(root(), "designs")
+    os.makedirs(d, exist_ok=True)
+    name = os.path.splitext(os.path.basename(dcp))[0]
+    return os.path.join(d, f"{name}-{h}.ivd.gz")