Split defs.bzl: extract gallery macros to gallery.bzl

Move demo_gallery_image, demo_stage_images, and _STAGE_SCRIPTS to
gallery.bzl. defs.bzl keeps flow macros (demo_flow, demo_sram,
demo_hierarchical). No behavior change.

Update load statements in 14 BUILD.bazel files and 2 docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: oharboe

.claude/commands/demo-add.md

@@ -334,7 +334,7 @@ After synthesis passes, run through placement and generate a gallery screenshot.
 
 ```starlark
 # Add to <project>/BUILD.bazel:
-load("//:defs.bzl", "demo_gallery_image")
+load("//:gallery.bzl", "demo_gallery_image")
 
 demo_gallery_image(
     name = "<top_module>_gallery",

coralnpu/BUILD.bazel

@@ -1,8 +1,9 @@
+load("//:defs.bzl", "demo_flow", "demo_sram")
+load("//:gallery.bzl", "demo_gallery_image", "demo_stage_images", "orfs_run")
 load("@bazel-orfs-verilog//:generate.bzl", "fir_library")
-load("@bazel-orfs//:openroad.bzl", "orfs_synth")
 load("@bazel-orfs-verilog//:verilog.bzl", "verilog_directory")
+load("@bazel-orfs//:openroad.bzl", "orfs_synth")
 load("@rules_chisel//chisel:defs.bzl", "chisel_binary")
-load("//:defs.bzl", "demo_flow", "demo_gallery_image", "demo_sram", "demo_stage_images", "orfs_run")
 
 # Step 1: Compile the Chisel generator binary
 chisel_binary(
@@ -43,7 +44,6 @@ filegroup(
         "@cvfpu//:all_srcs",
         "@fpu_div_sqrt_mvp//:all_srcs",
     ],
-
 )
 
 # Step 5: Parallel per-module synthesis (megaboom pattern)
@@ -54,30 +54,37 @@ filegroup(
 # from ~6 min to ~30s.
 
 KEPT_MODULES = [
-    "Regfile",           # 26,775 cells — register file (24% of design)
+    "Regfile",  # 26,775 cells — register file (24% of design)
     "RetirementBuffer",  #  7,508 cells — reorder buffer
-    "fpnew_fma",         #  7,072 cells — FPU multiply-add
+    "fpnew_fma",  #  7,072 cells — FPU multiply-add
     "CircularBufferMulti",  # 6,911 cells — instruction buffer
-    "Csr",               #  5,225 cells — CSR unit
-    "Mlu",               #  4,819 cells — multiply unit
-    "DispatchV2",        #  4,743 cells — dispatch
+    "Csr",  #  5,225 cells — CSR unit
+    "Mlu",  #  4,819 cells — multiply unit
+    "DispatchV2",  #  4,743 cells — dispatch
     "fpnew_cast_multi",  #  2,605 cells — FPU cast
-    "ram_3x145",         #  2,437 cells — small RAM
-    "DebugModule",       #  2,366 cells — debug
-    "Aligner",           #  2,334 cells — memory alignment
-    "ram_3x137",         #  2,304 cells — small RAM
-    "Alu",               #  2,285 cells — ALU
-    "FetchControl",      #  2,122 cells — fetch control
+    "ram_3x145",  #  2,437 cells — small RAM
+    "DebugModule",  #  2,366 cells — debug
+    "Aligner",  #  2,334 cells — memory alignment
+    "ram_3x137",  #  2,304 cells — small RAM
+    "Alu",  #  2,285 cells — ALU
+    "FetchControl",  #  2,122 cells — fetch control
     "pa_fdsu_srt_single",  # 2,052 cells — FPU divsqrt
 ]
 
 # Mocked SRAMs — always blackboxed
-MOCKED_SRAMS = ["Sram_2048x128", "Sram_512x128"]
+MOCKED_SRAMS = [
+    "Sram_2048x128",
+    "Sram_512x128",
+]
 
 # Modules with SystemVerilog type parameters — slang can't blackbox these.
 # They are still individually synthesized but must NOT appear in SYNTH_BLACKBOXES
 # for the CoreMiniAxi top-level target.
-TYPE_PARAM_MODULES = ["fpnew_fma", "fpnew_cast_multi", "Aligner"]
+TYPE_PARAM_MODULES = [
+    "fpnew_fma",
+    "fpnew_cast_multi",
+    "Aligner",
+]
 
 # Modules safe to blackbox (no type parameters)
 BLACKBOXABLE_MODULES = [m for m in KEPT_MODULES if m not in TYPE_PARAM_MODULES]
@@ -102,14 +109,12 @@ ALL_SYNTH_MODULES = KEPT_MODULES + ["CoreMiniAxi"]
         # CoreMiniAxi can only blackbox modules without type parameters;
         # submodule targets blackbox all other kept modules.
         "SYNTH_BLACKBOXES": " ".join(
-            ([b for b in BLACKBOXABLE_MODULES if b != name] if name == "CoreMiniAxi"
-             else [b for b in KEPT_MODULES if b != name]) + MOCKED_SRAMS,
+            ([b for b in BLACKBOXABLE_MODULES if b != name] if name == "CoreMiniAxi" else [b for b in KEPT_MODULES if b != name]) + MOCKED_SRAMS,
         ),
     },
     module_top = name,
     save_odb = False,
     sources = {"SDC_FILE": [":constraints.sdc"]},
-
     variant = "netlist",
     verilog_files = [":coralnpu_all_sv"],
 ) for name in ALL_SYNTH_MODULES]
@@ -118,21 +123,18 @@ ALL_SYNTH_MODULES = KEPT_MODULES + ["CoreMiniAxi"]
     name = "{}_netlist".format(name),
     srcs = ["{}_netlist_synth".format(name)],
     output_group = "1_2_yosys.v",
-
 ) for name in ALL_SYNTH_MODULES]
 
 filegroup(
     name = "netlists",
     srcs = [":{}_netlist".format(name) for name in ALL_SYNTH_MODULES],
-
 )
 
 genrule(
     name = "CoreMiniAxi_combined_netlist",
     srcs = [":netlists"],
     outs = ["CoreMiniAxi_combined_netlist.v"],
     cmd = "cat $(SRCS) > $@",
-
 )
 
 # Step 6: SRAM macro targets (provide LEF/LIB for mocked memories)
@@ -143,41 +145,35 @@ genrule(
 
 demo_sram(
     name = "Sram_2048x128",
-    verilog_files = [":coralnpu_all_sv"],
-    mock_area = 1.0,
     abstract_stage = "cts",
     arguments = {
         "CORE_UTILIZATION": "40",
         "PLACE_DENSITY": "0.65",
         "PDN_TCL": "$(PLATFORM_DIR)/openRoad/pdn/BLOCK_grid_strategy.tcl",
         "SYNTH_SLANG_ARGS": "--disable-instance-caching=false -DUSE_GENERIC -Iexternal/+_repo_rules+common_cells/include",
     },
+    mock_area = 1.0,
     sources = {"SDC_FILE": [":constraints-sram.sdc"]},
+    verilog_files = [":coralnpu_all_sv"],
 )
 
 demo_sram(
     name = "Sram_512x128",
-    verilog_files = [":coralnpu_all_sv"],
-    mock_area = 1.0,
     abstract_stage = "cts",
     arguments = {
         "CORE_UTILIZATION": "40",
         "PLACE_DENSITY": "0.65",
         "PDN_TCL": "$(PLATFORM_DIR)/openRoad/pdn/BLOCK_grid_strategy.tcl",
         "SYNTH_SLANG_ARGS": "--disable-instance-caching=false -DUSE_GENERIC -Iexternal/+_repo_rules+common_cells/include",
     },
+    mock_area = 1.0,
     sources = {"SDC_FILE": [":constraints-sram.sdc"]},
+    verilog_files = [":coralnpu_all_sv"],
 )
 
 # Step 7: ORFS physical design flow (uses pre-synthesized netlists + SRAM macros)
 demo_flow(
     name = "CoreMiniAxi",
-    substeps = True,
-    verilog_files = [":coralnpu_all_sv"],
-    macros = [
-        ":Sram_2048x128_generate_abstract",
-        ":Sram_512x128_generate_abstract",
-    ],
     arguments = {
         # Synthesis is skipped (SYNTH_NETLIST_FILES provides pre-synthesized netlists).
         # SYNTH_HIERARCHICAL=0 because KEEP_VARS is not generated when synthesis
@@ -211,11 +207,17 @@ demo_flow(
         "FILL_CELLS": "",
         "TAPCELL_TCL": "",
     },
+    macros = [
+        ":Sram_2048x128_generate_abstract",
+        ":Sram_512x128_generate_abstract",
+    ],
     sources = {
         "SDC_FILE": [":constraints.sdc"],
         "SYNTH_NETLIST_FILES": [":CoreMiniAxi_combined_netlist"],
         "PRE_GLOBAL_PLACE_TCL": [":CoreMiniAxi_probe_placement"],
     },
+    substeps = True,
+    verilog_files = [":coralnpu_all_sv"],
 )
 
 # Probe placement: run fast routability-driven placement on floorplan,
@@ -230,7 +232,6 @@ orfs_run(
         "PLACEMENT_TIPS_OUT": "$(location :placement-tips.tcl)",
     },
     script = "//scripts:probe_placement.tcl",
-
 )
 
 demo_gallery_image(
@@ -241,5 +242,9 @@ demo_gallery_image(
 demo_stage_images(
     name = "CoreMiniAxi_images",
     module = "CoreMiniAxi",
-    stages = ["floorplan", "place", "cts"],
+    stages = [
+        "floorplan",
+        "place",
+        "cts",
+    ],
 )

cva6/BUILD.bazel

@@ -1,4 +1,5 @@
-load("//:defs.bzl", "demo_flow", "demo_gallery_image")
+load("//:defs.bzl", "demo_flow")
+load("//:gallery.bzl", "demo_gallery_image")
 
 # CVA6 cv32a60x — 32-bit RISC-V CPU with HPDcache
 #
@@ -17,13 +18,6 @@ load("//:defs.bzl", "demo_flow", "demo_gallery_image")
 
 demo_flow(
     name = "cva6",
-    substeps = True,
-    verilog_files = [
-        "@cva6//:rtl",
-        "@cv_hpdcache//:rtl",
-        "@cvfpu//:all_srcs",
-        "@fpu_div_sqrt_mvp//:all_srcs",
-    ],
     arguments = {
         # Synthesis — survey mode: keep all modules for size analysis
         "SYNTH_HIERARCHICAL": "1",
@@ -55,6 +49,13 @@ demo_flow(
         "TNS_END_PERCENT": "0",
     },
     sources = {"SDC_FILE": [":constraints.sdc"]},
+    substeps = True,
+    verilog_files = [
+        "@cva6//:rtl",
+        "@cv_hpdcache//:rtl",
+        "@cvfpu//:all_srcs",
+        "@fpu_div_sqrt_mvp//:all_srcs",
+    ],
 )
 
 demo_gallery_image(

docs/adding-projects.md

@@ -337,7 +337,7 @@ All three apply GLOBAL_SETTINGS + FAST_SETTINGS by default.
 Use `demo_gallery_image()` to generate `.webp` screenshots:
 
 ```starlark
-load("//:defs.bzl", "demo_gallery_image")
+load("//:gallery.bzl", "demo_gallery_image")
 
 # Start with placement (fast)
 demo_gallery_image(

gallery.bzl

@@ -0,0 +1,84 @@
+"""Gallery image macros for the OpenROAD Demo Gallery.
+
+Generate screenshots and thumbnails from ORFS stage outputs.
+"""
+
+load("@bazel-orfs//:openroad.bzl", _orfs_run = "orfs_run")
+
+orfs_run = _orfs_run
+
+# Per-stage gallery scripts — each stage has different interesting features.
+_STAGE_SCRIPTS = {
+    "floorplan": "//scripts:floorplan_image.tcl",
+    "place": "//scripts:place_image.tcl",
+    "cts": "//scripts:cts_image.tcl",
+    "grt": "//scripts:grt_image.tcl",
+    "route": "//scripts:route_image.tcl",
+    "final": "//scripts:route_image.tcl",
+}
+
+def demo_gallery_image(
+        name,
+        src,
+        stage = None,
+        thumbnail_size = 400):
+    """Generate a gallery screenshot and thumbnail from an ORFS stage.
+
+    Uses a per-stage Tcl script for optimal display settings (e.g. CTS
+    hides power/ground, route shows signal nets). Falls back to the
+    generic gallery_image.tcl for unknown stages.
+
+    Creates two targets:
+        :<name>      — full-resolution screenshot (.webp)
+        :<name>_thumb — resized thumbnail (.webp)
+
+    Args:
+        name: Target name (e.g., "multiplier_gallery")
+        src: The orfs stage target to screenshot (e.g., ":multiplier_route")
+        stage: Stage name for script selection (e.g., "cts"). Auto-detected from src if None.
+        thumbnail_size: Max dimension in pixels for thumbnail (default: 400)
+    """
+    script = _STAGE_SCRIPTS.get(stage, "//scripts:gallery_image.tcl")
+    orfs_run(
+        name = name,
+        src = src,
+        outs = [name + ".webp"],
+        arguments = {
+            "GALLERY_IMAGE": "$(location :" + name + ".webp)",
+            "OR_ARGS": "-gui",
+        },
+        extra_args = "OPENROAD_CMD='xvfb-run -a $(OPENROAD_EXE) -exit $(OPENROAD_ARGS)'",
+        script = script,
+    )
+
+    native.genrule(
+        name = name + "_thumb",
+        srcs = [":" + name],
+        outs = [name + "_thumb.webp"],
+        cmd = "$(execpath //scripts:resize_image) $(SRCS) $@ --size " + str(thumbnail_size),
+        tools = ["//scripts:resize_image"],
+    )
+
+def demo_stage_images(
+        name,
+        module,
+        stages = None):
+    """Generate gallery images at multiple ORFS stages.
+
+    Creates `<name>_<stage>` and `<name>_<stage>_thumb` targets for each
+    specified stage. Images show how the design evolves through the flow —
+    from empty die at floorplan to final routed design.
+
+    Args:
+        name: Target name prefix (e.g. "MeshWithDelays_images")
+        module: The orfs_flow target name (e.g. "MeshWithDelays")
+        stages: List of stages to image (default: ["floorplan", "place", "cts", "route"])
+    """
+    if stages == None:
+        stages = ["floorplan", "place", "cts", "grt", "route"]
+    for stage in stages:
+        demo_gallery_image(
+            name = name + "_" + stage,
+            src = ":" + module + "_" + stage,
+            stage = stage,
+        )

gemmini/BUILD.bazel

@@ -1,7 +1,8 @@
-load("@rules_chisel//chisel:defs.bzl", "chisel_binary")
+load("//:defs.bzl", "demo_flow")
+load("//:gallery.bzl", "demo_gallery_image", "demo_stage_images")
 load("@bazel-orfs-verilog//:generate.bzl", "fir_library")
-load("@bazel-orfs-verilog//:verilog.bzl", "verilog_single_file_library", "verilog_directory")
-load("//:defs.bzl", "demo_flow", "demo_gallery_image", "demo_stage_images")
+load("@bazel-orfs-verilog//:verilog.bzl", "verilog_directory", "verilog_single_file_library")
+load("@rules_chisel//chisel:defs.bzl", "chisel_binary")
 
 # Step 1: Compile the Chisel generator binary
 chisel_binary(
@@ -39,13 +40,11 @@ genrule(
     srcs = [":gemmini_concat_sv"],
     outs = ["MeshWithDelays.sv"],
     cmd = "cp $< $@",
-
 )
 
 # Step 5: ORFS physical design flow
 demo_flow(
     name = "MeshWithDelays",
-    verilog_files = [":gemmini_sv"],
     arguments = {
         # --- Synthesis ---
         # Keep all modules for hierarchy analysis (run //scripts:module_sizes after synth)
@@ -70,6 +69,7 @@ demo_flow(
     sources = {
         "SDC_FILE": [":constraints.sdc"],
     },
+    verilog_files = [":gemmini_sv"],
 )
 
 demo_gallery_image(
@@ -80,5 +80,11 @@ demo_gallery_image(
 demo_stage_images(
     name = "MeshWithDelays_images",
     module = "MeshWithDelays",
-    stages = ["floorplan", "place", "cts", "grt", "route"],
+    stages = [
+        "floorplan",
+        "place",
+        "cts",
+        "grt",
+        "route",
+    ],
 )