Central synthesizer naming

doc/tutorials/chapter_6/answers/exercise_2_n_bit_subtractor.dart

@@ -7,7 +7,6 @@ import '../../chapter_3/answers/helper.dart';
 import '../../chapter_5/answers/full_subtractor.dart';
 
 class FullSubtractorComb extends FullSubtractor {
-  @override
   FullSubtractorComb(super.a, super.b, super.borrowIn) {
     // Declare input and output
     final a = input('a');

lib/src/exceptions/logic/put_exception.dart

@@ -9,10 +9,11 @@
 
 import 'package:rohd/rohd.dart';
 
-/// An exception that thrown when a [Logic] signal fails to `put`.
+/// An exception that thrown when a [Logic] signal fails to [Logic.put].
 class PutException extends RohdException {
-  /// Creates an exception for when a `put` fails on a `Logic` with [context] as
-  /// to where the
+  /// Creates an exception for when a [Logic.put] fails on a [Logic] with
+  /// [context] as to where the failure occurred and [message] describing the
+  /// failure.
   PutException(String context, String message)
       : super('Failed to put value on signal ($context): $message');
 }

lib/src/module.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2021-2025 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // module.dart
@@ -11,11 +11,11 @@ import 'dart:async';
 import 'dart:collection';
 
 import 'package:meta/meta.dart';
-
 import 'package:rohd/rohd.dart';
 import 'package:rohd/src/collections/traverseable_collection.dart';
 import 'package:rohd/src/diagnostics/inspector_service.dart';
 import 'package:rohd/src/utilities/config.dart';
+import 'package:rohd/src/utilities/namer.dart';
 import 'package:rohd/src/utilities/sanitizer.dart';
 import 'package:rohd/src/utilities/timestamper.dart';
 import 'package:rohd/src/utilities/uniquifier.dart';
@@ -52,6 +52,18 @@ abstract class Module {
   /// An internal mapping of input names to their sources to this [Module].
   late final Map<String, Logic> _inputSources = {};
 
+  // ─── Central naming (Namer) ─────────────────────────────────────
+
+  /// Central namer that owns both the signal and instance namespaces.
+  /// Initialized lazily on first access (after build).
+  @internal
+  late final Namer namer = _createNamer();
+
+  Namer _createNamer() {
+    assert(hasBuilt, 'Module must be built before canonical names are bound.');
+    return Namer.forModule(this);
+  }
+
   /// An internal mapping of inOut names to their sources to this [Module].
   late final Map<String, Logic> _inOutSources = {};
 
@@ -202,6 +214,18 @@ abstract class Module {
           this, 'Module must be built to access uniquified name.');
   String _uniqueInstanceName;
 
+  /// A stable identity used to memoize this module's canonical instance name
+  /// across repeated synthesis passes (e.g. netlist then SystemVerilog).
+  ///
+  /// Defaults to the [Module] itself, which is correct for modules that are
+  /// part of the built hierarchy and therefore persist across passes.
+  /// Synthesis-time throwaway modules that are *recreated* on every pass (and
+  /// thus have a fresh [Module] identity each time) must override this to
+  /// return a stable identity — typically the [Logic] they drive — so their
+  /// instance name does not drift run-to-run.
+  @internal
+  Object get instanceNameKey => this;
+
   /// If true, guarantees [uniqueInstanceName] matches [name] or else the
   /// [build] will fail.
   final bool reserveName;

lib/src/synthesizers/synth_builder.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2021-2025 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // synth_builder.dart

lib/src/synthesizers/synthesizer.dart

@@ -1,12 +1,11 @@
-// Copyright (C) 2021-2023 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // synthesizer.dart
 // Generic definition for something that synthesizes output files
 //
 // 2021 August 26
 // Author: Max Korbel <max.korbel@intel.com>
-//
 
 import 'package:rohd/rohd.dart';
 

lib/src/synthesizers/systemverilog/systemverilog_synth_module_definition.dart

@@ -18,8 +18,8 @@ class SystemVerilogSynthModuleDefinition extends SynthModuleDefinition {
 
   @override
   void process() {
-    _replaceNetConnections();
-    _collapseChainableModules();
+    _buildNetConnectsForNaming();
+    _collapseMarkedChainableModules();
     _replaceInOutConnectionInlineableModules();
   }
 
@@ -30,34 +30,41 @@ class SystemVerilogSynthModuleDefinition extends SynthModuleDefinition {
   /// Creates a new [_NetConnect] module to synthesize assignment between two
   /// [LogicNet]s.
   SystemVerilogSynthSubModuleInstantiation _addNetConnect(
-      SynthLogic dst, SynthLogic src) {
+    SynthLogic dst,
+    SynthLogic src,
+  ) {
     // make an (unconnected) module representing the assignment
-    final netConnect =
-        _NetConnect(LogicNet(width: dst.width), LogicNet(width: src.width));
+    final netConnect = _NetConnect(
+      LogicNet(width: dst.width),
+      LogicNet(width: src.width),
+    );
 
     // instantiate the module within the definition
     final netConnectSynthSubModInst =
         (getSynthSubModuleInstantiation(netConnect)
             as SystemVerilogSynthSubModuleInstantiation)
-
           // map inouts to the appropriate `_SynthLogic`s
           ..setInOutMapping(_NetConnect.n0Name, dst)
           ..setInOutMapping(_NetConnect.n1Name, src);
 
     // notify the `SynthBuilder` that it needs declaration
     supportingModules.add(netConnect);
 
+    netConnectSynthSubModInst.pickName(module);
+
     return netConnectSynthSubModInst;
   }
 
-  /// Replace all [assignments] between two [LogicNet]s with a [_NetConnect].
-  void _replaceNetConnections() {
+  /// Builds [_NetConnect] instances for [LogicNet] assignments.
+  void _buildNetConnectsForNaming() {
     final reducedAssignments = <SynthAssignment>[];
 
     for (final assignment in assignments) {
       if (assignment.src.isNet && assignment.dst.isNet) {
-        assert(assignment is! PartialSynthAssignment,
-            'Net connections should not be partial assignments.');
+        assert(
+          assignment is! PartialSynthAssignment,
+          'Net connections should not be partial assignments.',
+        );
 
         _addNetConnect(assignment.dst, assignment.src);
       } else {
@@ -73,106 +80,19 @@ class SystemVerilogSynthModuleDefinition extends SynthModuleDefinition {
     }
   }
 
-  /// Collapses chainable, inlineable modules.
-  void _collapseChainableModules() {
+  /// Collapses chainable, inlineable modules after naming.
+  void _collapseMarkedChainableModules() {
     // collapse multiple lines of in-line assignments into one where they are
     // unnamed one-liners
     //  for example, be capable of creating lines like:
     //      assign x = a & b & c & _d_and_e
     //      assign _d_and_e = d & e
     //      assign y = _d_and_e
 
-    // Also feed collapsed chained modules into other modules
-    // Need to consider order of operations in systemverilog or else add ()
-    // everywhere! (for now add the parentheses)
-
-    // Algorithm:
-    //  - find submodule instantiations that are inlineable
-    //  - filter to those who only output as input to one other module
-    //  - pass an override to the submodule instantiation that the corresponding
-    //    input should map to the output of another submodule instantiation
-    // do not collapse if signal feeds to multiple inputs of other modules
-
-    final inlineableSubmoduleInstantiations = module.subModules
-        .whereType<InlineSystemVerilog>()
-        .map((m) => getSynthSubModuleInstantiation(m)
-            as SystemVerilogSynthSubModuleInstantiation);
-
-    // number of times each signal name is used by any module
-    final signalUsage = <SynthLogic, int>{};
-
-    for (final subModuleInstantiation in subModuleInstantiations) {
-      for (final inSynthLogic in [
-        ...subModuleInstantiation.inputMapping.values,
-        ...subModuleInstantiation.inOutMapping.values
-      ]) {
-        if (inputs.contains(inSynthLogic) || inOuts.contains(inSynthLogic)) {
-          // dont worry about inputs to THIS module
-          continue;
-        }
-
-        subModuleInstantiation as SystemVerilogSynthSubModuleInstantiation;
-
-        if (subModuleInstantiation.inlineResultLogic == inSynthLogic) {
-          // don't worry about the result signal
-          continue;
-        }
-
-        signalUsage.update(
-          inSynthLogic,
-          (value) => value + 1,
-          ifAbsent: () => 1,
-        );
-      }
-    }
-
-    final singleUseSignals = <SynthLogic>{};
-    signalUsage.forEach((signal, signalUsageCount) {
-      // don't collapse if:
-      //  - used more than once
-      //  - inline modules for preferred names
-      if (signalUsageCount == 1 && signal.mergeable) {
-        singleUseSignals.add(signal);
-      }
-    });
-
-    // partial assignments are a special case, count as a usage
-    for (final partialAssignment
-        in assignments.whereType<PartialSynthAssignment>()) {
-      singleUseSignals.remove(partialAssignment.src);
-    }
-
-    final singleUsageInlineableSubmoduleInstantiations =
-        inlineableSubmoduleInstantiations.where((subModuleInstantiation) {
-      // inlineable modules have only 1 result signal
-      final resultSynthLogic = subModuleInstantiation.inlineResultLogic!;
-
-      return singleUseSignals.contains(resultSynthLogic) &&
-
-          // don't inline modules if they were cleared from instantiation
-          subModuleInstantiation.needsInstantiation;
-    });
-
-    // remove any inlineability for those that want no expressions
-    for (final instantiation in subModuleInstantiations) {
-      final subModule = instantiation.module;
-      if (subModule is SystemVerilog) {
-        singleUseSignals.removeAll(subModule.expressionlessInputs.map((e) =>
-            instantiation.inputMapping[e] ?? instantiation.inOutMapping[e]));
-      }
-      // ignore: deprecated_member_use_from_same_package
-      else if (subModule is CustomSystemVerilog) {
-        singleUseSignals.removeAll(subModule.expressionlessInputs.map((e) =>
-            instantiation.inputMapping[e] ?? instantiation.inOutMapping[e]));
-      }
-    }
-
     final synthLogicToInlineableSynthSubmoduleMap =
         <SynthLogic, SystemVerilogSynthSubModuleInstantiation>{};
-    for (final subModuleInstantiation
-        in singleUsageInlineableSubmoduleInstantiations) {
-      (subModuleInstantiation.module as InlineSystemVerilog).resultSignalName;
-
+    for (final subModuleInstantiation in chainableModulesToCollapse
+        .cast<SystemVerilogSynthSubModuleInstantiation>()) {
       // inlineable modules have only 1 result signal
       final resultSynthLogic = subModuleInstantiation.inlineResultLogic!;
 
@@ -189,8 +109,10 @@ class SystemVerilogSynthModuleDefinition extends SynthModuleDefinition {
     for (final subModuleInstantiation in subModuleInstantiations) {
       subModuleInstantiation as SystemVerilogSynthSubModuleInstantiation;
 
-      subModuleInstantiation.synthLogicToInlineableSynthSubmoduleMap =
-          synthLogicToInlineableSynthSubmoduleMap;
+      subModuleInstantiation.synthLogicToInlineableSynthSubmoduleMap = {
+        ...?subModuleInstantiation.synthLogicToInlineableSynthSubmoduleMap,
+        ...synthLogicToInlineableSynthSubmoduleMap,
+      };
     }
   }
 
@@ -199,11 +121,12 @@ class SystemVerilogSynthModuleDefinition extends SynthModuleDefinition {
   /// [_NetConnect] assignment instead of a normal assignment.
   void _replaceInOutConnectionInlineableModules() {
     for (final subModuleInstantiation in subModuleInstantiations.toList().where(
-        (e) =>
-            e.module is InlineSystemVerilog &&
-            e.needsInstantiation &&
-            e.outputMapping.isEmpty &&
-            e.inOutMapping.isNotEmpty)) {
+          (e) =>
+              e.module is InlineSystemVerilog &&
+              e.needsInstantiation &&
+              e.outputMapping.isEmpty &&
+              e.inOutMapping.isNotEmpty,
+        )) {
       // algorithm:
       // - mark module as not needing declaration
       // - add a net_connect
@@ -225,8 +148,10 @@ class SystemVerilogSynthModuleDefinition extends SynthModuleDefinition {
         parentSynthModuleDefinition: this,
       );
 
-      final netConnectSynthSubmod = _addNetConnect(subModResult, dummy)
-        ..synthLogicToInlineableSynthSubmoduleMap ??= {};
+      final netConnectSynthSubmod = _addNetConnect(
+        subModResult,
+        dummy,
+      )..synthLogicToInlineableSynthSubmoduleMap ??= {};
 
       netConnectSynthSubmod.synthLogicToInlineableSynthSubmoduleMap![dummy] =
           subModuleInstantiation;
@@ -260,19 +185,21 @@ class _NetConnect extends Module with SystemVerilog {
   _NetConnect(LogicNet n0, LogicNet n1)
       : assert(n0.width == n1.width, 'Widths must be equal.'),
         width = n0.width,
-        super(
-          definitionName: _definitionName,
-          name: _definitionName,
-        ) {
+        super(definitionName: _definitionName, name: _definitionName) {
     n0 = addInOut(n0Name, n0, width: width);
     n1 = addInOut(n1Name, n1, width: width);
   }
 
   @override
   String instantiationVerilog(
-      String instanceType, String instanceName, Map<String, String> ports) {
-    assert(instanceType == _definitionName,
-        'Instance type selected should match the definition name.');
+    String instanceType,
+    String instanceName,
+    Map<String, String> ports,
+  ) {
+    assert(
+      instanceType == _definitionName,
+      'Instance type selected should match the definition name.',
+    );
     return '$instanceType'
         ' #(.WIDTH($width))'
         ' $instanceName'

lib/src/synthesizers/systemverilog/systemverilog_synthesizer.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2021-2025 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // systemverilog_synthesizer.dart