fpga-design-implview 0.1.0__py3-none-any.whl

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/__main__.py

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

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")

fpga_design_implview/cli.py

@@ -0,0 +1,256 @@
+"""implview command line."""
+
+import argparse
+import os
+import sys
+import time
+
+from . import __version__, cache, vivado
+from .dcp import dcp_info, find_dcp
+from .design import load_design
+from .device import load_device
+
+
+def _log(msg):
+    sys.stderr.write(f"implview: {msg}\n")
+
+
+def _atomic_run(outputs, args, a, version):
+    """Run Vivado writing to temporary names, then move into place."""
+    tmp = {p: p + f".tmp{os.getpid()}" for p in outputs}
+    args = [tmp.get(x, x) for x in args]
+    try:
+        vivado.run(args, a.vivado, version)
+        for p, t in tmp.items():
+            os.replace(t, p)
+    finally:
+        for t in tmp.values():
+            if os.path.exists(t):
+                os.remove(t)
+
+
+def export(a, src):
+    """Design (and device on a cache miss) for a checkpoint, run directory or
+    exported .ivd.gz. Returns (device, design, path of the design export)."""
+    if src.endswith(".ivd.gz"):
+        des = load_design(src)
+        devp = os.path.join(os.path.dirname(src), f"{des.part}.ivdev.gz")
+        if not os.path.exists(devp):
+            devp = cache.device_path(des.part)
+        if not os.path.exists(devp):
+            raise SystemExit(f"implview: no device file for {des.part}; run `fpga-design-implview device {des.part}`")
+        des.source = src
+        _check_placed(des)
+        return load_device(devp), des, src
+
+    dcp = find_dcp(src)
+    info = dcp_info(dcp)
+    part = info.get("part", "")
+    routing = not getattr(a, "no_routing", False)
+    devp = cache.device_path(part)
+    out = getattr(a, "output_design", None)
+    desp = out or cache.design_path(dcp, routing)
+    if not out and not routing and not os.path.exists(desp) and os.path.exists(cache.design_path(dcp, True)):
+        desp = cache.design_path(dcp, True)     # an export with routing has it all
+    refresh = getattr(a, "refresh", False)
+    if refresh or not os.path.exists(desp) or not os.path.exists(devp):
+        args = ["design", os.path.abspath(dcp), desp]
+        outputs = [desp]
+        if refresh or not os.path.exists(devp):
+            args += ["-device", devp]
+            outputs.append(devp)
+        if routing:
+            args.append("-routing")
+        _log(f"{dcp}: {part}, top {info.get('top', '?')}, Vivado {info.get('vivado', '?')}: exporting")
+        t0 = time.time()
+        _atomic_run(outputs, args, a, info.get("vivado", ""))
+        _log(f"export done in {time.time() - t0:.0f} s")
+    des = load_design(desp)
+    des.source = dcp
+    if not routing:
+        des.pips = {}
+    _check_placed(des)
+    return load_device(devp), des, desp
+
+
+def _check_placed(des):
+    """Warn when most cells have no site: a synthesized checkpoint (like the
+    unsuffixed <top>.dcp Vivado copies into impl_1) draws almost nothing."""
+    unplaced = des.unplaced()
+    total = len(des.cells) + (unplaced or 0)
+    if not unplaced or unplaced <= 0.01 * total:
+        return
+    if len(des.cells) >= total / 2:
+        _log(f"warning: {unplaced:,} of {total:,} cells are not placed")
+        return
+    _log(f"warning: only {len(des.cells):,} of {total:,} cells have a site: "
+         f"the checkpoint is not placed")
+    if des.source.endswith(".dcp"):
+        try:
+            best = find_dcp(os.path.dirname(os.path.abspath(des.source)))
+        except FileNotFoundError:
+            return
+        if os.path.abspath(best) != os.path.abspath(des.source):
+            _log(f"the implemented checkpoint of this run is {best}")
+
+
+def _render_options(a):
+    """Highlight entries and render options: the command line wins over the
+    [options] of the highlight file."""
+    from .highlight import Entry, load_config
+    entries, opts = [], {}
+    if a.highlight:
+        try:
+            cfg = load_config(a.highlight)
+        except (OSError, ValueError) as e:
+            raise SystemExit(f"implview: {e}")
+        entries, opts = cfg.entries, cfg.options
+    entries += [Entry(g) for g in a.group or []]
+    pick = lambda k, d: getattr(a, k) if getattr(a, k) is not None else opts.get(k, d)
+    return entries, {"theme": pick("theme", "light"), "stats": pick("stats", False),
+                     "labels": pick("labels", True), "panel": pick("panel", True),
+                     "label_size": pick("label_size", 10.0),
+                     "label_style": pick("label_style", "pill"),
+                     "hide_other": opts.get("others") == "hide"}
+
+
+def cmd_render(a):
+    from .layout import build_layout
+    from .placement import build_placement, group_cells
+    entries, opt = _render_options(a)
+    dev, des, _ = export(a, a.input)
+    lay = build_layout(dev)
+    groups, cg, unmatched = group_cells(des, min(a.max_groups, 8), entries, a.depth)
+    for p in unmatched:
+        _log(f"warning: highlight path {p!r} matches nothing")
+    place = build_placement(dev, des, groups, cg, opt["hide_other"])
+    if place.missing:
+        _log(f"warning: {place.missing} cells are on sites the device file does not have")
+    if a.save_highlight:
+        from .highlight import write_config
+        from .render import group_colors
+        write_config(a.save_highlight, groups, group_colors("light", groups), des.top)
+        _log(f"highlight file written to {a.save_highlight}")
+    outs = a.output or [f"{des.top or 'design'}.png", f"{des.top or 'design'}.pdf"]
+    if a.outdir:
+        os.makedirs(a.outdir, exist_ok=True)
+        outs = [o if os.path.isabs(o) else os.path.join(a.outdir, o) for o in outs]
+    html = [o for o in outs if o.lower().endswith(".html")]
+    pics = [o for o in outs if o not in html]
+    written = []
+    if pics:
+        from .render import write_outputs
+        written += write_outputs(pics, dev, lay, des, place,
+                                 **{k: v for k, v in opt.items() if k != "hide_other"})
+    if html:
+        from .html import write_html
+        for o in html:
+            write_html(o, dev, lay, des, place)
+            written.append(o)
+    for w in written:
+        print(w)
+
+
+def cmd_export(a):
+    a.output_design = a.output
+    dev, des, path = export(a, a.input)
+    print(path)
+
+
+def cmd_device(a):
+    path = a.output or cache.device_path(a.part)
+    if a.refresh or not os.path.exists(path):
+        _atomic_run([path], ["device", a.part, path], a, "")
+    print(path)
+
+
+def cmd_info(a):
+    dcp = find_dcp(a.input)
+    info = dcp_info(dcp)
+    print(f"checkpoint  {dcp}")
+    for k in ("part", "top", "product"):
+        print(f"{k:<11} {info.get(k, '')}")
+    devp = cache.device_path(info.get("part", ""))
+    print(f"device      {devp} ({'cached' if os.path.exists(devp) else 'not cached'})")
+    try:
+        exe = vivado.command(a.vivado, info.get("vivado", ""))
+        print(f"vivado      {' '.join(exe)}")
+    except vivado.VivadoError as e:
+        print(f"vivado      {e}")
+
+
+def cmd_tcl(a):
+    print(os.path.join(vivado.TCL_DIR, "implview.tcl"))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="fpga-design-implview",
+        description="Pictures of Vivado implemented designs: the device resources and "
+                    "what the design uses of them.")
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    ap.add_argument("--vivado", help="command that runs Vivado (default: $IMPLVIEW_VIVADO, "
+                                     "vivado on the PATH, or an install matching the checkpoint)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def source(p):
+        p.add_argument("input", help="routed checkpoint, run directory (impl_1), project "
+                                     "directory, or an exported .ivd.gz")
+        p.add_argument("--no-routing", action="store_true", help="skip the routing usage export")
+        p.add_argument("--refresh", action="store_true", help="export again, ignore the cache")
+
+    p = sub.add_parser("render", help="write PNG/PDF/SVG/HTML pictures of a design")
+    source(p)
+    p.add_argument("-o", "--output", action="append",
+                   help="output file, by extension: .png .pdf .svg .html (repeatable; "
+                        "default <top>.png and <top>.pdf)")
+    p.add_argument("-O", "--outdir", help="directory for the outputs")
+    p.add_argument("--theme", choices=("light", "dark"), help="default light")
+    p.add_argument("-H", "--highlight", metavar="FILE",
+                   help="highlight file (TOML): which hierarchy to color and how")
+    p.add_argument("-g", "--group", action="append", metavar="PATH",
+                   help="hierarchy path to color, palette colors, repeatable (* inside a "
+                        "level, ** any depth)")
+    p.add_argument("--depth", type=int, help="group by hierarchy cut at this depth")
+    p.add_argument("--max-groups", type=int, default=8, help="automatic groups (max 8)")
+    p.add_argument("--stats", action=argparse.BooleanOptionalAction,
+                   help="utilization table and cells per group in the panel (default off)")
+    p.add_argument("--labels", action=argparse.BooleanOptionalAction,
+                   help="group and clock region names on the device (default on)")
+    p.add_argument("--label-size", type=float, metavar="PT",
+                   help="font size of the group names on the device (default 10)")
+    p.add_argument("--label-style", choices=("pill", "text"),
+                   help="group names as colored badges (default) or plain text")
+    p.add_argument("--panel", action=argparse.BooleanOptionalAction,
+                   help="design, part and legend on the right (default on)")
+    p.add_argument("--save-highlight", metavar="FILE",
+                   help="write the groups used as a highlight file, to edit")
+    p.set_defaults(func=cmd_render)
+
+    p = sub.add_parser("export", help="only export a design (and its device) from Vivado")
+    source(p)
+    p.add_argument("-o", "--output", help="design file (default: in the cache)")
+    p.set_defaults(func=cmd_export)
+
+    p = sub.add_parser("device", help="export the resource map of a part into the cache")
+    p.add_argument("part", help="e.g. xcvu37p-fsvh2892-2L-e")
+    p.add_argument("-o", "--output", help="device file (default: in the cache)")
+    p.add_argument("--refresh", action="store_true")
+    p.set_defaults(func=cmd_device)
+
+    p = sub.add_parser("info", help="part, top and cache status of a checkpoint")
+    p.add_argument("input")
+    p.set_defaults(func=cmd_info)
+
+    p = sub.add_parser("tcl", help="path of implview.tcl, to export from a Vivado session")
+    p.set_defaults(func=cmd_tcl)
+
+    a = ap.parse_args(argv)
+    try:
+        a.func(a)
+    except (vivado.VivadoError, FileNotFoundError) as e:
+        raise SystemExit(f"implview: {e}")
+
+
+if __name__ == "__main__":
+    main()

fpga_design_implview/dcp.py

@@ -0,0 +1,41 @@
+"""What a checkpoint is, without Vivado: dcp.xml inside the zip names the part."""
+
+import glob
+import os
+import re
+import xml.etree.ElementTree as ET
+import zipfile
+
+# Checkpoints of an implementation run, most complete first.
+STAGES = ("_routed.dcp", "_postroute_physopt.dcp", "_physopt.dcp", "_placed.dcp", "_opt.dcp")
+
+
+def dcp_info(path):
+    with zipfile.ZipFile(path) as z:
+        root = ET.fromstring(z.read("dcp.xml"))
+    info = {}
+    for tag, key in (("Part", "part"), ("Top", "top"), ("PRODUCT", "product")):
+        e = root.find(tag)
+        if e is not None:
+            info[key] = e.get("Name", "")
+    m = re.search(r"v(\d{4}\.\d+)", info.get("product", ""))
+    info["vivado"] = m.group(1) if m else ""
+    return info
+
+
+def find_dcp(path):
+    """The checkpoint to show for a path: a .dcp, a run directory (impl_1)
+    or a project directory (its impl_1 run)."""
+    if os.path.isfile(path):
+        return path
+    if not os.path.isdir(path):
+        raise FileNotFoundError(path)
+    runs = [path]
+    runs += sorted(glob.glob(os.path.join(path, "*.runs", "impl_*")))
+    runs += sorted(glob.glob(os.path.join(path, "impl_*")))
+    for run in runs:
+        for stage in STAGES:
+            hits = sorted(glob.glob(os.path.join(run, "*" + stage)), key=os.path.getmtime)
+            if hits:
+                return hits[-1]
+    raise FileNotFoundError(f"no implemented checkpoint (*_routed.dcp, ...) under {path}")

fpga_design_implview/design.py

@@ -0,0 +1,73 @@
+"""Implemented design: placed primitive cells, pblocks, routing usage.
+
+Read back from the gzip'ed TSV written by `implview::export_design`
+(tcl/implview.tcl).
+"""
+
+import gzip
+from collections import Counter
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Cell:
+    name: str
+    site: str
+    bel: str
+    ref: str                # REF_NAME (LUT6, FDRE, RAMB36E2, ...)
+    group: str              # PRIMITIVE_GROUP (LUT, FLOP_LATCH, BLOCKRAM, ...)
+
+
+@dataclass
+class Design:
+    part: str = ""
+    top: str = ""
+    info: dict = field(default_factory=dict)
+    cells: list = field(default_factory=list)
+    pblocks: list = field(default_factory=list)     # (name, grid ranges)
+    pads: list = field(default_factory=list)        # (site, port, a cell on its net)
+    pips: dict = field(default_factory=dict)        # tile name -> used pips
+    source: str = ""                                # checkpoint the export came from
+
+    def slack(self, key):
+        v = self.info.get(key, "")
+        try:
+            return float(v)
+        except ValueError:
+            return None
+
+    def group_counts(self):
+        return Counter(c.group for c in self.cells)
+
+    def unplaced(self):
+        """Primitive cells without a site, None for exports that do not say."""
+        try:
+            return max(int(self.info["primitives"]) - len(self.cells), 0)
+        except (KeyError, ValueError):
+            return None
+
+
+def load_design(path):
+    d = Design()
+    with gzip.open(path, "rt") as f:
+        header = f.readline().rstrip("\n").split("\t")
+        if header[0] != "#implview-design":
+            raise ValueError(f"{path}: not an implview design file")
+        for line in f:
+            r = line.rstrip("\n").split("\t")
+            k = r[0]
+            if k == "U":
+                d.cells.append(Cell(r[5], r[1], r[2], r[3], r[4]))
+            elif k == "P":
+                d.pips[r[1]] = int(r[2])
+            elif k == "X":
+                d.pblocks.append((r[1], r[2] if len(r) > 2 else ""))
+            elif k == "O":
+                d.pads.append((r[1], r[2], r[3]))
+            elif k == "part":
+                d.part = r[1]
+            elif k == "top":
+                d.top = r[1]
+            else:
+                d.info[k] = r[1] if len(r) > 1 else ""
+    return d

fpga_design_implview/device.py

@@ -0,0 +1,126 @@
+"""Device resource map: tiles on the Vivado tile grid, their sites and BELs.
+
+Read back from the gzip'ed TSV written by `implview::export_device`
+(tcl/implview.tcl). One file per part, cached by `implview.cache`.
+"""
+
+import gzip
+import re
+from dataclasses import dataclass, field
+
+import numpy as np
+
+SITE_NAME_RE = re.compile(r"^(.*)_X(\d+)Y(\d+)$")
+
+
+@dataclass
+class Site:
+    name: str
+    type: str
+    tile: int               # index into Device.tile_*
+    clock_region: str
+    bonded: bool
+    prefix: str             # name without the _X#Y# suffix (SLICE, RAMB18, ...)
+    x: int                  # site X/Y from the name, -1 if the name has none
+    y: int
+
+
+@dataclass
+class ClockRegion:
+    name: str
+    row: int
+    col: int
+    gx0: int                # grid bounds, inclusive (top left .. bottom right)
+    gy0: int
+    gx1: int
+    gy1: int
+    slr: str
+
+
+@dataclass
+class Device:
+    part: str = ""
+    info: dict = field(default_factory=dict)
+    tile_name: list = field(default_factory=list)
+    tile_type: list = field(default_factory=list)
+    gx: np.ndarray = None
+    gy: np.ndarray = None
+    tile_nsites: np.ndarray = None
+    tile_slr: np.ndarray = None
+    sites: list = field(default_factory=list)
+    bels: dict = field(default_factory=dict)        # site type -> [(bel, bel type)]
+    clock_regions: list = field(default_factory=list)
+    slrs: list = field(default_factory=list)        # (name, index, is_master, config order)
+    pins: dict = field(default_factory=dict)        # site name -> package pin
+
+    @property
+    def name(self):
+        return self.info.get("device", self.part)
+
+    @property
+    def width(self):
+        return int(self.gx.max()) + 1
+
+    @property
+    def height(self):
+        return int(self.gy.max()) + 1
+
+    def site_index(self):
+        return {s.name: i for i, s in enumerate(self.sites)}
+
+    def tile_index(self):
+        return {n: i for i, n in enumerate(self.tile_name)}
+
+    def tile_sites(self):
+        """Site indices of each tile (list of lists)."""
+        out = [[] for _ in self.tile_name]
+        for i, s in enumerate(self.sites):
+            out[s.tile].append(i)
+        return out
+
+
+def parse_site_name(name):
+    m = SITE_NAME_RE.match(name)
+    if not m:
+        return name, -1, -1
+    return m.group(1), int(m.group(2)), int(m.group(3))
+
+
+def load_device(path):
+    dev = Device()
+    gx, gy, ns, slr = [], [], [], []
+    with gzip.open(path, "rt") as f:
+        header = f.readline().rstrip("\n").split("\t")
+        if header[0] != "#implview-device":
+            raise ValueError(f"{path}: not an implview device file")
+        for line in f:
+            r = line.rstrip("\n").split("\t")
+            k = r[0]
+            if k == "T":
+                dev.tile_name.append(r[1])
+                dev.tile_type.append(r[2])
+                gx.append(int(r[3]))
+                gy.append(int(r[4]))
+                ns.append(int(r[5]))
+                slr.append(int(r[6]) if r[6] else 0)
+            elif k == "S":
+                prefix, x, y = parse_site_name(r[2])
+                dev.sites.append(Site(r[2], r[3], int(r[1]), r[4], r[5] == "1", prefix, x, y))
+            elif k == "B":
+                dev.bels[r[1]] = [tuple(b.split(":", 1)) for b in r[2:] if b]
+            elif k == "R":
+                dev.clock_regions.append(ClockRegion(
+                    r[1], int(r[2]), int(r[3]), int(r[4]), int(r[5]), int(r[6]), int(r[7]), r[8]))
+            elif k == "L":
+                dev.slrs.append((r[1], int(r[2]), r[3] == "1", int(r[4]) if r[4] else 0))
+            elif k == "K":
+                dev.pins[r[2]] = r[1]
+            elif k == "part":
+                dev.part = r[1]
+            else:
+                dev.info[k] = r[1] if len(r) > 1 else ""
+    dev.gx = np.array(gx, dtype=np.int32)
+    dev.gy = np.array(gy, dtype=np.int32)
+    dev.tile_nsites = np.array(ns, dtype=np.int32)
+    dev.tile_slr = np.array(slr, dtype=np.int32)
+    return dev