[feat] Support ExternalSV parameter overrides

Adds support for SystemVerilog parameter overrides on ExternalSV descriptors and propagates those overrides through both Verilator compilation and PyCDE wrapper generation.

Author: H2Oxi

docs/design/external/ExternalSV_zh.md

@@ -9,6 +9,7 @@
 - `python/assassyn/ir/module/external.py` 解析注解构造 `_ExternalConfig`，并通过元类直接构造 `ExternalIntrinsic`，兼容属性访问与 `[]` 操作。
 - `Singleton.peek_builder()` 提供的构建器上下文确保在缺失 `with SysBuilder` 的情况下也能生成合法的 `ExternalIntrinsic`/`PureIntrinsic` 节点，并延迟应用构造阶段的输入默认值 (`_apply_pending_connections`)。
 - `ExternalIntrinsic` 与 `PureIntrinsic.EXTERNAL_OUTPUT_READ` 定义在 `python/assassyn/ir/expr/intrinsic.py`，由后端统一调度。
+- `ExternalSV` 支持通过 `__parameters__` 提供 SystemVerilog 参数覆盖（`int/bool/str` 或 `PathLike`），供 Verilator 编译与 PyCDE wrapper 统一使用。
 
 ## Verilog 生成
 - `python/assassyn/codegen/verilog/design.py:_generate_external_module_wrapper` 基于 ExternalSV 声明生成 PyCDE wrapper。

python/assassyn/codegen/simulator/verilator.md

@@ -49,7 +49,7 @@ Dataclass capturing the direction, type information, and host language types for
 
 ### `ExternalFFIModule`
 
-Dataclass that tracks all information for a generated crate: crate name, paths, symbol prefix, IO port descriptors, clock/reset flags, and the produced shared library metadata.
+Dataclass that tracks all information for a generated crate: crate name, paths, symbol prefix, IO port descriptors, clock/reset flags, parameter overrides, and the produced shared library metadata.
 
 These types appear in `__all__`, making them available to other generator components.
 
@@ -72,7 +72,8 @@ Creates an `ExternalFFIModule` spec from an `ExternalSV` **class** (rather than
 3. Allocates unique crate and dynamic library names
 4. Copies the SystemVerilog source to the crate's `rtl/` directory
 5. Calls `_collect_ports_from_class` to partition ports into inputs and outputs
-6. Returns a fully populated `ExternalFFIModule` with the class name as `original_module_name`
+6. Copies `metadata["parameters"]` (if any) into the spec so Verilator can apply `-G` overrides
+7. Returns a fully populated `ExternalFFIModule` with the class name as `original_module_name`
 
 ### `_collect_ports` / `_collect_ports_from_class` / `_dtype_to_port`
 
@@ -97,14 +98,14 @@ Writes `Cargo.toml`, `src/lib.rs`, and `src/wrapper.cpp` for a given spec before
 
 Runs the full native toolchain:
   1. Ensures the `.sv` file is present (`_ensure_sv_source`).
-  2. Calls Verilator (`_run_verilator_compile`) into `build/verilated`.
+  2. Calls Verilator (`_run_verilator_compile`) into `build/verilated`, passing any `ExternalSV` parameter overrides via `-G`.
   3. Collects all generated C++ sources (`_gather_source_files`).
   4. Builds the shared library via `_build_compile_command` and `_run_subprocess`.
   5. Writes `.verilator-lib-path` so the Rust wrapper knows where to load the artifact.
 
 ### `_write_manifest_file`
 
-Takes a manifest path plus a list of specs and rewrites the JSON summary in a single helper. This avoids duplicating the `json.dumps(..., indent=2)` call across the different generation entry points.
+Takes a manifest path plus a list of specs and rewrites the JSON summary (including `parameters`) in a single helper. This avoids duplicating the `json.dumps(..., indent=2)` call across the different generation entry points.
 
 ### `_record_used_name_hints`
 

python/assassyn/codegen/simulator/verilator.py

@@ -51,6 +51,7 @@ class ExternalFFIModule:  # pylint: disable=too-many-instance-attributes
     sv_rel_path: str
     inputs: List[FFIPort] = field(default_factory=list)
     outputs: List[FFIPort] = field(default_factory=list)
+    parameters: Dict[str, object] = field(default_factory=dict)
     has_clock: bool = False
     has_reset: bool = False
     original_module_name: str = ""
@@ -190,9 +191,29 @@ def _run_verilator_compile(crate: ExternalFFIModule, sv_source: Path, obj_dir: P
         "--Mdir",
         str(obj_dir),
     ]
+    if crate.parameters:
+        for name in sorted(crate.parameters):
+            verilator_cmd.append(_format_verilator_parameter(name, crate.parameters[name]))
     _run_subprocess(verilator_cmd)
 
 
+def _format_verilator_parameter(name: str, value: object) -> str:
+    """Format a SystemVerilog parameter override for Verilator's -G flag."""
+    if isinstance(value, bool):
+        literal = "1" if value else "0"
+    elif isinstance(value, int):
+        literal = str(value)
+    elif hasattr(value, "__fspath__"):
+        literal = json.dumps(os.fspath(value))
+    elif isinstance(value, str):
+        literal = json.dumps(value)
+    else:
+        raise TypeError(
+            f"Unsupported ExternalSV parameter type for {name}: {type(value)}"
+        )
+    return f"-G{name}={literal}"
+
+
 def _resolve_verilator_paths() -> tuple[Path, Path]:
     """Locate the Verilator include directories."""
     verilator_root = os.environ.get("VERILATOR_ROOT")
@@ -348,6 +369,7 @@ def _create_external_spec(
         sv_rel_path=os.path.join("rtl", src_sv_path.name),
         inputs=ports_in,
         outputs=ports_out,
+        parameters={},
         has_clock=getattr(module, "has_clock", False),
         has_reset=getattr(module, "has_reset", False),
         original_module_name=module.name,
@@ -364,19 +386,17 @@ def _create_external_spec_from_class(
     metadata = external_class.metadata()
     top_module = metadata.get("module_name")
     if not top_module:
-        msg = (
+        raise ValueError(
             f"ExternalSV class {external_class.__name__} "
             "must specify '__module_name__'"
         )
-        raise ValueError(msg)
 
     file_path = metadata.get("source")
     if not file_path:
-        msg = (
+        raise ValueError(
             f"ExternalSV class {external_class.__name__} "
             "must specify '__source__'"
         )
-        raise ValueError(msg)
 
     crate_name = _unique_name(
         f"verilated_{_sanitize_base_name(top_module, external_class.__name__)}",
@@ -398,6 +418,7 @@ def _create_external_spec_from_class(
     shutil.copy(src_sv_path, crate_path / "rtl" / src_sv_path.name)
 
     ports_in, ports_out = _collect_ports_from_class(external_class)
+    parameters = metadata.get("parameters", {}) or {}
 
     return ExternalFFIModule(
         crate_name=crate_name,
@@ -409,6 +430,7 @@ def _create_external_spec_from_class(
         sv_rel_path=os.path.join("rtl", src_sv_path.name),
         inputs=ports_in,
         outputs=ports_out,
+        parameters=dict(parameters),
         has_clock=metadata.get("has_clock", False),
         has_reset=metadata.get("has_reset", False),
         original_module_name=external_class.__name__,
@@ -428,6 +450,7 @@ def _spec_manifest_entry(spec: ExternalFFIModule, simulator_root: Path) -> Dict[
         "has_reset": spec.has_reset,
         "lib_filename": spec.lib_filename,
         "lib_path": str(spec.lib_path) if spec.lib_path else "",
+        "parameters": dict(spec.parameters),
         "inputs": [
             {
                 "name": port.name,

python/assassyn/codegen/verilog/_expr/intrinsics.md

@@ -107,7 +107,8 @@ This function generates Verilog code for block intrinsic operations, which are c
    - The cleanup phase incorporates these stored predicates into post-wait assignments and triggers via `get_pred`
 
 4. **EXTERNAL_INSTANTIATE / ExternalIntrinsic**: Creates and wires external modules in-line
-   - `ExternalIntrinsic` instances are handled before the opcode switch, generating calls to `<wrapper>::new()` and wiring all inputs
+   - `ExternalIntrinsic` instances are handled before the opcode switch, generating calls to `@modparams` wrappers and wiring all inputs
+   - Parameter overrides from `ExternalSV.metadata()["parameters"]` are formatted and passed into the wrapper factory before port connections
    - Updates the dumper's bookkeeping (`external_instance_names`, `external_wrapper_names`, `external_output_exposures`) while consulting the shared `ExternalRegistry` for instance owners and cross-module consumers
 
 The function integrates with the credit-based pipeline architecture by managing execution conditions and finish signals.

python/assassyn/codegen/verilog/_expr/intrinsics.py

@@ -5,6 +5,7 @@
 including PureIntrinsic, Intrinsic, and Log.
 """
 
+import os
 from typing import Optional, TYPE_CHECKING
 from string import Formatter
 
@@ -202,6 +203,19 @@ def _handle_external_output(dumper, expr, intrinsic, rval):
     return result
 
 
+def _format_external_param_value(name: str, value: object) -> str:
+    """Format ExternalSV parameter values for PyCDE wrapper instantiation."""
+    if isinstance(value, bool):
+        return "1" if value else "0"
+    if isinstance(value, int):
+        return str(value)
+    if hasattr(value, "__fspath__"):
+        return repr(os.fspath(value))
+    if isinstance(value, str):
+        return repr(value)
+    raise TypeError(f"Unsupported ExternalSV parameter type for {name}: {type(value)}")
+
+
 def codegen_pure_intrinsic(dumper, expr: PureIntrinsic) -> Optional[str]:
     """Generate code for pure intrinsic operations."""
     intrinsic = expr.opcode
@@ -233,6 +247,14 @@ def codegen_external_intrinsic(dumper, expr: ExternalIntrinsic) -> Optional[str]
         wrapper_name = f"{ext_class.__name__}_ffi"
         dumper.external_wrapper_names[ext_class] = wrapper_name
 
+    parameters = metadata.get("parameters", {}) or {}
+    param_args = []
+    if parameters:
+        for name in sorted(parameters):
+            param_args.append(
+                f"{name}={_format_external_param_value(name, parameters[name])}"
+            )
+
     connections = []
     if metadata.get('has_clock'):
         connections.append('clk=self.clk')
@@ -242,7 +264,14 @@ def codegen_external_intrinsic(dumper, expr: ExternalIntrinsic) -> Optional[str]
         value_code = dumper.dump_rval(value, False)
         connections.append(f"{port_name}={value_code}")
 
-    call = f"{wrapper_name}({', '.join(connections)})" if connections else f"{wrapper_name}()"
+    wrapper_factory = (
+        f"{wrapper_name}({', '.join(param_args)})" if param_args else f"{wrapper_name}()"
+    )
+    call = (
+        f"{wrapper_factory}({', '.join(connections)})"
+        if connections
+        else f"{wrapper_factory}()"
+    )
     dumper.external_instance_names[expr] = rval
 
     entries = dumper.external_metadata.reads_for_instance(expr)

python/assassyn/codegen/verilog/design.md

@@ -112,7 +112,7 @@ The CIRCTDumper class is the main visitor that converts Assassyn IR into Verilog
 1. **Execution Control**: `wait_until` and per-expression `meta_cond` metadata decide when statements run, while FINISH gating now reads the precomputed `finish_sites` stored in module metadata instead of collecting tuples during emission.
 2. **Module State**: `current_module` tracks traversal context, while port declarations are derived from immutable metadata instead of mutating dumper dictionaries.
 3. **Array Management**: `array_metadata`, `memory_defs`, and ownership metadata ensure multi-port register arrays are emitted while memory payloads (`array.is_payload(memory)` returning `True`) are routed through dedicated generators.
-4. **External Integration**: `external_metadata` (an `ExternalRegistry`) captures external classes, instance ownership, and cross-module reads. Runtime maps (`external_wrapper_names`, `external_instance_names`, `external_wire_assignments`, `external_wire_outputs`, and `external_output_exposures`) reuse that registry to materialise expose/valid ports and wire consumers to producers without recomputing analysis.
+4. **External Integration**: `external_metadata` (an `ExternalRegistry`) captures external classes, instance ownership, and cross-module reads. Runtime maps (`external_wrapper_names`, `external_instance_names`, `external_wire_assignments`, `external_wire_outputs`, and `external_output_exposures`) reuse that registry to materialise expose/valid ports and wire consumers to producers without recomputing analysis. `_generate_external_module_wrapper` now emits `@modparams` wrappers and threads `ExternalSV.metadata()["parameters"]` into instantiations so SystemVerilog parameter overrides propagate into PyCDE.
 5. **Expression Naming**: `expr_to_name` and `name_counters` guarantee deterministic signal names whenever expression results must be reused across statements.
 6. **Code Generation**: `code`, `logs`, and `indent` store emitted lines and diagnostic information used later by the testbench.
 7. **Module Metadata**: `module_metadata` maps each `Module` to its `ModuleMetadata`. The structure tracks FINISH intrinsics, async calls, FIFO interactions (annotated with `expr.meta_cond`), and every array/value exposure required for cleanup. These entries are populated before the dumper is constructed via [`collect_fifo_metadata`](./analysis.md), so `CIRCTDumper` receives a frozen snapshot and never mutates it during emission. See [metadata module](/python/assassyn/codegen/verilog/metadata.md) for details. The dumper exposes this information via convenience helpers such as `async_callers(module)`, which forwards to the frozen `AsyncLedger` stored on the interaction matrix.

python/assassyn/codegen/verilog/design.py

@@ -294,10 +294,19 @@ def _generate_external_module_wrapper(self, ext_class):
         class_name = f"{ext_class.__name__}_ffi"
         metadata = ext_class.metadata()
         module_name = metadata.get('module_name', ext_class.__name__)
+        parameters = metadata.get("parameters", {}) or {}
+        param_names = sorted(parameters)
 
         self.external_wrapper_names[ext_class] = class_name
 
-        self.append_code(f'class {class_name}(Module):')
+        self.append_code('@modparams')
+        if param_names:
+            self.append_code(f'def {class_name}({", ".join(param_names)}):')
+        else:
+            self.append_code(f'def {class_name}():')
+        self.indent += 4
+        impl_name = f"{class_name}Impl"
+        self.append_code(f'class {impl_name}(Module):')
         self.indent += 4
 
         # Set the module name for PyCDE
@@ -315,6 +324,8 @@ def _generate_external_module_wrapper(self, ext_class):
             else:
                 self.append_code(f'{wire_name} = Output({wire_type})')
 
+        self.indent -= 4
+        self.append_code(f'return {impl_name}')
         self.indent -= 4
         self.append_code('')
 

python/assassyn/ir/module/external.md

@@ -20,6 +20,7 @@ class MyIP(ExternalSV):
     y: WireOut[UInt(32)]
     __source__ = "rtl/my_ip.sv"
     __module_name__ = "my_ip"
+    __parameters__ = {"ADDR_WIDTH": 8, "INIT_FILE": "rtl/init.hex"}
 
 inst = MyIP(a=value_a, b=value_b)  # returns ExternalIntrinsic
 result = inst.y          # wire output → PureIntrinsic(EXTERNAL_OUTPUT_READ)
@@ -38,6 +39,7 @@ result = inst.y          # wire output → PureIntrinsic(EXTERNAL_OUTPUT_READ)
 
   * The decorator validates that the class extends `ExternalSV`, walks `__annotations__`, and gathers all `WireIn`/`WireOut`/`RegOut` definitions into the `_wires` metadata table.
   * Configuration fields such as `__source__`, `__module_name__`, `__has_clock__`, and `__has_reset__` are captured so code generation stages can decide how to wrap and clock the external block.
+  * `__parameters__` (optional dict) captures SystemVerilog parameter overrides; values may be `int`/`bool`/`str` (or `PathLike`, converted to `str`, with `bool` coerced to `int`) and are surfaced to both Verilator (`-G`) and PyCDE wrapper generation.
   * The decorated class remains callable; invoking it runs through the metaclass and returns an `ExternalIntrinsic` instead of a Python object. There is no longer a mutable Python instance that exposes setters/getters.
 
 -----
@@ -46,6 +48,8 @@ result = inst.y          # wire output → PureIntrinsic(EXTERNAL_OUTPUT_READ)
 
   * **Construction**: The metaclass intercepts calls to the class and routes them to `_create_external_intrinsic`, which wraps the request in an `ExternalIntrinsic`.
   * **Metadata**: `_wires` stores port declarations (direction + kind + dtype) while `_metadata` records auxiliary fields such as `module_name`, `source`, clock/reset booleans, etc. Downstream code generation stages read these tables directly.
+  * **Parameters**: `__parameters__` is folded into `_metadata["parameters"]` so simulator + Verilog backends can apply SV parameter overrides consistently.
+  * **Parameter Access**: `ExternalSV.parameters()` returns a copy of the normalized parameter map.
   * **No Mutable Instance**: The descriptor no longer inherits from `Downstream` or exposes mutation APIs like `in_assign`. All connectivity is described by the returned intrinsic and its operands.
   * **Debugging Support**: `__repr__` is implemented on the Python side for better logging, but day-to-day interaction happens through the intrinsic nodes.
 

python/assassyn/ir/module/external.py

@@ -5,12 +5,48 @@
 # pylint: disable=duplicate-code,too-few-public-methods
 
 from dataclasses import dataclass
+from os import fspath
 from typing import Any, Dict, Generic, TypeVar, Literal
 
 
 T = TypeVar('T')
 
 
+def _normalize_external_parameters(parameters: Any) -> Dict[str, Any]:
+    """Normalize ExternalSV parameter overrides into a plain dict.
+
+    Accepted parameter values:
+      - int/bool (bool coerced to int)
+      - str
+      - PathLike (converted via os.fspath)
+    """
+    if parameters is None:
+        return {}
+    if not isinstance(parameters, dict):
+        raise TypeError("ExternalSV __parameters__ must be a dict of name -> value")
+
+    normalized: Dict[str, Any] = {}
+    for name, value in parameters.items():
+        if not isinstance(name, str):
+            raise TypeError("ExternalSV parameter names must be strings")
+        if isinstance(value, bool):
+            normalized[name] = int(value)
+            continue
+        if isinstance(value, int):
+            normalized[name] = value
+            continue
+        if hasattr(value, "__fspath__"):
+            normalized[name] = fspath(value)
+            continue
+        if isinstance(value, str):
+            normalized[name] = value
+            continue
+        raise TypeError(
+            "ExternalSV parameter values must be int/bool/str or PathLike"
+        )
+    return normalized
+
+
 def _create_external_intrinsic(cls, **input_connections):
     """Factory function to create ExternalIntrinsic with proper IR builder tracking."""
     # pylint: disable=import-outside-toplevel
@@ -160,6 +196,7 @@ class MyExternal(ExternalSV):
         'module_name': getattr(cls, '__module_name__', cls.__name__),
         'has_clock': getattr(cls, '__has_clock__', False),
         'has_reset': getattr(cls, '__has_reset__', False),
+        'parameters': _normalize_external_parameters(getattr(cls, '__parameters__', None)),
     })
 
     return cls
@@ -206,3 +243,9 @@ def port_specs(cls) -> Dict[str, WireSpec]:
     def metadata(cls) -> Dict[str, Any]:
         """Return metadata dictionary for the external module."""
         return cls._metadata
+
+    @classmethod
+    def parameters(cls) -> Dict[str, Any]:
+        """Return a copy of the normalized external parameter overrides."""
+        params = cls._metadata.get("parameters", {})
+        return dict(params)