[PyCDE] Auto-name signals from Python variable names (#9856)

Automatically derive signal names from the
Python variable they are assigned to. For example, `x = comb.AddOp(a, b)`
will auto-name the resulting signal "x" without requiring a manual
`.name = "x"` call.

A new `debug` parameter on `System()` switches auto-naming from
`sv.namehint` attributes to `hw.wire` ops with inner symbols, creating
optimization barriers that guarantee named wires appear in the output
SystemVerilog.

AI-assisted-by: GitHub Copilot (Claude)

Author: teqdruid

.github/workflows/testPycdeESI.yml

@@ -52,6 +52,17 @@ jobs:
           fetch-depth: 1
           submodules: true
 
+      - name: Setup venv and install dependencies
+        run: |
+          set -o errexit
+          whoami
+          apt update
+          apt install -y python3-venv
+          python3 -m venv venv
+          . venv/bin/activate
+          pip install --upgrade pip
+          pip install -r frontends/PyCDE/python/requirements.txt
+
       - name: ccache
         uses: hendrikmuhs/ccache-action@v1.2
         with:
@@ -70,6 +81,7 @@ jobs:
           BUILD_SHARED: ${{ matrix.build-shared }}
           BUILD_TYPE: ${{ matrix.build-type }}
         run: |
+          . venv/bin/activate
           export PATH="/usr/lib/ccache:/usr/local/opt/ccache/libexec:$PATH"
           mkdir build && cd build
           # In order for ccache to be effective, these flags should be kept in sync with nighly.
@@ -95,17 +107,21 @@ jobs:
 
       - name: Test CIRCT
         run: |
+          . venv/bin/activate
           ninja -C build check-circt -j$(nproc)
       - name: Test PyCDE
         run: |
+          . venv/bin/activate
           ninja -C build check-pycde -j$(nproc)
       # The PyCDE integration tests exercise the ESI runtime.
       - name: Test PyCDE and ESI runtime integration
         run: |
+          . venv/bin/activate
           ninja -C build check-pycde-integration -j$(nproc)
 
       - name: Test ESI runtime (pytest)
         run: |
+          . venv/bin/activate
           # Install the ESI C++ runtime into the esiaccel Python package tree
           # so that cmake-based tests can find headers, libraries, and the
           # esiaccelConfig.cmake.

frontends/PyCDE/pyproject.toml

@@ -5,6 +5,7 @@ requires = [
   "wheel",
   "cmake>=3.23,<4",
   "ninja>=1.10",
+  "executing",
 
   # MLIR build depends.
   "numpy",
@@ -42,7 +43,7 @@ name = "pycde"
 dynamic = ["version"]
 description = "Python CIRCT Design Entry"
 authors = [{ name = "John Demme", email = "John.Demme@microsoft.com" }]
-dependencies = ['numpy']
+dependencies = ['numpy', 'executing']
 requires-python = ">=3.10"
 
 [project.urls]

frontends/PyCDE/python/requirements.txt

@@ -1,6 +1,8 @@
 numpy
-pybind11>=2.9
+nanobind>=2.2.0
 PyYAML
 cocotb>=1.6.2
 cocotb-test>=0.2.2
 jinja2
+executing>=2.2.0
+psutil

frontends/PyCDE/src/CMakeLists.txt

@@ -34,6 +34,7 @@ declare_mlir_python_sources(PyCDESources
   pycde/instance.py
   pycde/seq.py
   pycde/signals.py
+  pycde/tracer.py
   pycde/ndarray.py
   pycde/esi.py
   pycde/fsm.py

frontends/PyCDE/src/pycde/constructs.py

@@ -15,6 +15,7 @@
 from .circt import ir
 from .circt.support import BackedgeBuilder
 from .circt.dialects import msft as raw_msft
+from .tracer import get_var_name
 
 import typing
 from typing import List, Optional, Union
@@ -77,6 +78,9 @@ def Wire(type: Type, name: str = None):
   """Declare a wire. Used to create backedges. Must assign exactly once. If
   'name' is specified, use 'NamedWire' instead."""
 
+  if name is None:
+    name = get_var_name(depth=1, skip_pycde=True)
+
   class WireValue(type._get_value_class(), AssignableSignal):
 
     def __init__(self):
@@ -139,6 +143,9 @@ def Reg(type: Type,
         name: str = None) -> Signal:
   """Declare a register. Must assign exactly once."""
 
+  if name is None:
+    name = get_var_name(depth=1, skip_pycde=True)
+
   class RegisterValue(type._get_value_class()):
 
     def assign(self, new_value: Signal):

frontends/PyCDE/src/pycde/signals.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 from .support import get_user_loc, _obj_to_value_infer_type
+from .tracer import get_var_name
 from .types import (Array, Bit, Bits, Bundle, BundledChannel, Channel,
                     ChannelDirection, ChannelSignaling, Type)
 
@@ -27,6 +28,29 @@ def _FromCirctValue(value: ir.Value, type: Type | None = None) -> Signal:
   return type._get_value_class()(value, type)
 
 
+def _apply_auto_name(signal: Signal, name: str) -> Signal:
+  """Apply an auto-derived name to a signal. In normal mode, sets sv.namehint.
+  In debug mode, wraps the signal with hw.wire with a symbol to create an
+  optimization barrier that preserves the name in the output Verilog."""
+  from .system import System
+  try:
+    system = System.current()
+    is_debug = system.debug
+  except RuntimeError:
+    is_debug = False
+
+  if is_debug:
+    from .module import _BlockContext
+    from .circt.dialects import hw as raw_hw
+    sym_name = _BlockContext.current().uniquify_symbol(name)
+    inner_sym = raw_hw.InnerSymAttr.get(ir.StringAttr.get(sym_name))
+    wire_op = raw_hw.WireOp(signal.value, name=name, inner_sym=inner_sym)
+    signal.value = wire_op.result
+  else:
+    signal.name = name
+  return signal
+
+
 class Signal:
   """Root of the PyCDE value (signal, in RTL terms) hierarchy."""
 
@@ -589,6 +613,9 @@ def __getitem__(self, idx: Union[int, BitVectorSignal]) -> Signal:
       v = hw.ArrayGetOp(self.value, idx)
       if self.name and isinstance(idx, int):
         v.name = self.name + f"__{idx}"
+      var_name = get_var_name(depth=2)
+      if var_name is not None:
+        _apply_auto_name(v, var_name)
       return v
 
   @__getitem__.register(slice)
@@ -606,6 +633,9 @@ def __get_item__slice(self, s: slice):
       ret = hw.ArraySliceOp(self.value, idxs[0], ret_type)
       if self.name is not None:
         ret.name = f"{self.name}_{idxs[0]}upto{idxs[1]}"
+      var_name = get_var_name(depth=2)
+      if var_name is not None:
+        _apply_auto_name(ret, var_name)
       return ret
 
   def slice(self, low_idx: Union[int, BitVectorSignal],
@@ -701,6 +731,9 @@ def __getattr__(self, attr):
         v = hw.StructExtractOp(self.value, attr)
         if self.name:
           v.name = f"{self.name}__{attr}"
+        var_name = get_var_name(depth=1)
+        if var_name is not None:
+          _apply_auto_name(v, var_name)
         return v
     raise AttributeError(f"{type(self)} object has no attribute '{attr}'")
 
@@ -1222,8 +1255,14 @@ def to_circt(arg):
           # Return the wrapped values, if any.
           converted_results = tuple(
               _FromCirctValue(res) for res in created.results)
-          return converted_results[0] if len(
-              converted_results) == 1 else converted_results
+          if len(converted_results) == 1:
+            signal = converted_results[0]
+            if signal.name is None:
+              var_name = get_var_name(depth=1, skip_pycde=True)
+              if var_name is not None:
+                _apply_auto_name(signal, var_name)
+            return signal
+          return converted_results
 
         return create
 

frontends/PyCDE/src/pycde/system.py

@@ -42,17 +42,19 @@ class System:
       "mod", "top_modules", "name", "passed", "_old_system_token", "_op_cache",
       "_generate_queue", "output_directory", "files", "mod_files",
       "packaging_funcs", "sw_api_langs", "_instance_roots", "_placedb",
-      "_appid_index", "platform", "core_freq", "plugin_added_passes"
+      "_appid_index", "platform", "core_freq", "plugin_added_passes", "_debug"
   ]
 
   def __init__(self,
                top_modules: Union[List[Type[Module]], Type[Module]],
                name: str = None,
                output_directory: str = None,
                sw_api_langs: List[str] = None,
-               core_clock_frequency_hz: Optional[int] = None):
+               core_clock_frequency_hz: Optional[int] = None,
+               debug: bool = False):
     from .module import Module
     self.passed = False
+    self._debug = debug
     self.mod = ir.Module.create()
     if isinstance(top_modules, Iterable):
       self.top_modules = list(top_modules)
@@ -119,6 +121,13 @@ def _get_ip(self):
   def set_debug():
     ir._GlobalDebug.flag = True
 
+  @property
+  def debug(self) -> bool:
+    """True when debug mode is enabled — auto-naming uses hw.wire instead of
+    sv.namehint for better Verilog readability at the cost of some
+    optimizations."""
+    return self._debug
+
   # TODO: Ideally, we'd be able to run the cf-to-handshake lowering passes in
   # pycde.  As of now, however, the cf/memref/arith dialects are not registered
   # so the assembly can't be loaded. The right way to do this is to have pycde

frontends/PyCDE/src/pycde/testing.py

@@ -24,6 +24,7 @@ def unittestmodule(generate=True,
                    print_after_passes=False,
                    emit_outputs=False,
                    debug=False,
+                   system_debug=False,
                    **kwargs):
   """
   Like @module, but additionally performs system instantiation, generation,
@@ -46,7 +47,9 @@ def testmodule_inner(func_or_class):
     # module generator functions
     setattr(builtins, mod.__name__, mod)
 
-    sys = System([mod], output_directory=f"out_{func_or_class.__name__}")
+    sys = System([mod],
+                 output_directory=f"out_{func_or_class.__name__}",
+                 debug=system_debug)
     if generate:
       sys.generate()
       if print:

frontends/PyCDE/src/pycde/tracer.py

@@ -0,0 +1,83 @@
+#  Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+#  See https://llvm.org/LICENSE.txt for license information.
+#  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+import ast
+import sys
+
+import executing
+
+# PyCDE-internal modules where auto-naming from variable names IS desired.
+# Code in any other pycde.* module is considered "internal plumbing" and will
+# be skipped when skip_pycde is True.
+_PYCDE_AUTONAME_MODULES = frozenset((
+    "pycde.constructs",
+    "pycde.bsp",
+    "pycde.bsp.common",
+    "pycde.bsp.cosim",
+    "pycde.bsp.dma",
+    "pycde.bsp.xrt",
+))
+
+
+def _is_pycde_internal(module_name: str) -> bool:
+  """Return True if module_name belongs to pycde but is NOT on the allowlist."""
+  if module_name == 'pycde' or module_name.startswith('pycde.'):
+    return module_name not in _PYCDE_AUTONAME_MODULES
+  return False
+
+
+def _name_from_target(target: ast.AST):
+  """Extract a name string from an AST assignment target node.
+
+  Returns a name for simple variable assignments and subscript assignments
+  with constant or simple-name keys.  Returns None for attribute stores,
+  starred targets, tuple unpacking, or anything else we can't map to a
+  simple name."""
+  if isinstance(target, ast.Name):
+    return target.id if target.id != "_" else None
+
+  if isinstance(target, ast.Subscript) and isinstance(target.value, ast.Name):
+    container = target.value.id
+    s = target.slice
+    if isinstance(s, ast.Constant) and isinstance(s.value, (int, str)):
+      return f"{container}_{s.value}"
+    if isinstance(s, ast.Name):
+      return f"{container}_{s.id}"
+
+  return None
+
+
+def get_var_name(depth=1, skip_pycde=False):
+  """Determine whether the result of the current call is being assigned to a
+  simple variable.  Returns the variable name as a string, or None.
+
+  Uses the ``executing`` library to identify the currently executing AST
+  node and inspects the enclosing statement for an assignment target.
+
+  If skip_pycde is True, returns None when the target frame belongs to pycde
+  internal code (but NOT for modules on the allowlist like pycde.constructs
+  and pycde.bsp.*).
+
+  Silently returns None on any failure."""
+  try:
+    frame = sys._getframe(depth + 1)
+
+    if skip_pycde:
+      module_name = frame.f_globals.get('__name__', '')
+      if _is_pycde_internal(module_name):
+        return None
+
+    ex = executing.Source.executing(frame)
+    node = ex.node
+    if node is None:
+      return None
+    for stmt in ex.statements:
+      if isinstance(stmt, ast.Assign) and len(stmt.targets) == 1:
+        # Only return a name if the executing node is the direct RHS of the
+        # assignment — not a sub-expression within a larger expression.
+        if stmt.value is node:
+          return _name_from_target(stmt.targets[0])
+    return None
+  except Exception:
+    return None

frontends/PyCDE/test/test_constructs.py

@@ -17,11 +17,11 @@
 # CHECK:         %in = sv.wire sym @in : !hw.inout<i8>
 # CHECK:         {{%.+}} = sv.read_inout %in {sv.namehint = "in"} : !hw.inout<i8>
 # CHECK:         sv.assign %in, %In : i8
-# CHECK:         [[r1:%.+]] = seq.compreg %In, %clk : i8
+# CHECK:         %r1__reg1 = seq.compreg sym @r1__reg1 %In, %clk : i8
 # CHECK:         %c0_i8{{.*}} = hw.constant 0 : i8
-# CHECK:         [[r5:%.+]] = seq.compreg %In, %clk reset %rst, %c0_i8{{.*}}  : i8
-# CHECK:         [[r6:%.+]] = seq.compreg.ce %In, %clk, %InCE : i8
-# CHECK:         hw.output [[r2]], [[r1]], [[r5]], [[r6]] : i8, i8, i8, i8
+# CHECK:         %r_rst__reg1 = seq.compreg sym @r_rst__reg1 %In, %clk reset %rst, %c0_i8{{.*}}  : i8
+# CHECK:         %r_ce__reg1 = seq.compreg.ce sym @r_ce__reg1 %In, %clk, %InCE : i8
+# CHECK:         hw.output [[r2]], %r1__reg1, %r_rst__reg1, %r_ce__reg1 : i8, i8, i8, i8
 
 
 @unittestmodule()
@@ -91,12 +91,12 @@ def pe(r, c):
 
 
 # CHECK-LABEL:  hw.module @ControlReg_num_asserts2_num_resets1
-# CHECK:          [[r0:%.+]] = hw.array_get %asserts[%false]
-# CHECK:          [[r1:%.+]] = hw.array_get %asserts[%true]
+# CHECK:          [[r0:%.+]] = hw.array_get %asserts[%false] {sv.namehint = "asserts__0"}
+# CHECK:          [[r1:%.+]] = hw.array_get %asserts[%true] {sv.namehint = "asserts__1"}
 # CHECK:          [[r2:%.+]] = comb.or bin [[r0]], [[r1]]
-# CHECK:          [[r3:%.+]] = hw.array_get %resets[%c0_i0]
+# CHECK:          [[r3:%.+]] = hw.array_get %resets[%c0_i0] {sv.namehint = "resets__0"}
 # CHECK:          [[r4:%.+]] = comb.or bin [[r3]]
-# CHECK:          %state = seq.compreg [[r6]], %clk reset %rst, %false{{.*}}
+# CHECK:          %state = seq.compreg sym @reg__reg1 {{%.+}}, %clk reset %rst, %false{{.*}}
 # CHECK:          [[r5:%.+]] = comb.mux bin [[r4]], %false{{.*}}, %state
 # CHECK:          [[r6:%.+]] = comb.mux bin [[r2]], %true{{.*}}, [[r5]]
 # CHECK:          hw.output %state