Optimize constant operations and enforce Const immutability

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Next release
 
+- Improved simulation performance and generated outputs by avoiding module creation for four-state-safe operations involving `Const`s, zero shifts, and muxes with constant controls (<https://github.com/intel/rohd/issues/429>).
+- Enforced that `Const` values cannot be changed through `put` or `inject`, including through another `Logic` driven by a `Const` (<https://github.com/intel/rohd/issues/486>).
 - Added per-`Const` preferred radix control for generated literals, normalized `Const` names to reflect their displayed radix, and enhanced `LogicValue.toRadixString` to omit its width and radix decorator or digit separators (<https://github.com/intel/rohd/issues/601>).
 - Improved generated SystemVerilog to collapse contiguous partial array and range assignments into packed slice assignments when safe (<https://github.com/intel/rohd/pull/676>).
 - Added configurable explicit or implicit object and data types for generated SystemVerilog ports, defaulting to `input wire logic`, `output var logic`, and `inout wire logic` (<https://github.com/intel/rohd/pull/678>).

lib/src/modules/gates.dart

@@ -815,7 +815,22 @@ class LShift extends _ShiftGate {
 /// ```SystemVerilog
 /// control ? d1 : d0
 /// ```
-Logic mux(Logic control, Logic d1, Logic d0) => Mux(control, d1, d0).out;
+///
+/// If [control] is a valid [Const], returns the selected input directly.
+Logic mux(Logic control, Logic d1, Logic d0) {
+  if (control.width != 1) {
+    throw PortWidthMismatchException(control, 1);
+  }
+  if (d0.width != d1.width) {
+    throw PortWidthMismatchException.equalWidth(d0, d1);
+  }
+
+  if (control is Const && control.value.isValid) {
+    return control.value == LogicValue.one ? d1 : d0;
+  }
+
+  return Mux(control, d1, d0).out;
+}
 
 /// A mux (multiplexer) module.
 ///

lib/src/signals/const.dart

@@ -45,7 +45,16 @@ String _constName(LogicValue value, int? preferredRadix) {
 }
 
 /// Represents a [Logic] that never changes value.
+///
+/// Attempts to assign, [put], or [inject] a new value throw an
+/// [UnassignableException], including through another [Logic] driven by the
+/// [Const].
 class Const extends Logic {
+  /// The explanation included when an attempt is made to modify a [Const].
+  static const _unassignableMessage =
+      'A `Const` value cannot be modified, including through another `Logic` '
+      'driven by it.';
+
   /// The preferred radix for displaying this constant in generated outputs.
   ///
   /// Supported radices are binary (2), octal (8), decimal (10), and
@@ -88,12 +97,136 @@ class Const extends Logic {
           // we don't care about maintaining this node unless necessary
           naming: Naming.unnamed,
         ) {
-    _wire.put(value, signalName: name);
+    _wire
+      ..put(value, signalName: name)
+      ..makeImmutable(this, reason: _unassignableMessage);
 
-    makeUnassignable(reason: '`Const` signals are unassignable.');
+    makeUnassignable(reason: _unassignableMessage);
   }
 
   @override
   Const clone({String? name}) =>
       Const(value, width: width, preferredRadix: preferredRadix);
+
+  @override
+  void put(dynamic val, {bool fill = false}) =>
+      throw UnassignableException(this, reason: _unassignableMessage);
+
+  @override
+  void inject(dynamic val, {bool fill = false}) =>
+      throw UnassignableException(this, reason: _unassignableMessage);
+
+  /// Verifies that [other] has the same width as this [Const].
+  void _checkMatchingWidth(Logic other) {
+    if (width != other.width) {
+      throw PortWidthMismatchException.equalWidth(this, other);
+    }
+  }
+
+  @override
+  Logic operator ~() => Const(~value);
+
+  @override
+  Logic operator &(Logic other) {
+    _checkMatchingWidth(other);
+
+    if (other is Const) {
+      return Const(value & other.value);
+    } else if (value.isValid && value.isZero) {
+      return this;
+    }
+
+    return And2Gate(this, other).out;
+  }
+
+  @override
+  Logic operator |(Logic other) {
+    _checkMatchingWidth(other);
+
+    if (other is Const) {
+      return Const(value | other.value);
+    } else if (value.isValid &&
+        value == LogicValue.filled(width, LogicValue.one)) {
+      return this;
+    }
+
+    return Or2Gate(this, other).out;
+  }
+
+  @override
+  Logic operator ^(Logic other) {
+    _checkMatchingWidth(other);
+
+    if (other is Const) {
+      return Const(value ^ other.value);
+    }
+
+    return Xor2Gate(this, other).out;
+  }
+
+  @override
+  Logic operator >>(dynamic other) {
+    if (Logic._isZeroShiftAmount(other)) {
+      return this;
+    } else if (other is Logic && other is! Const) {
+      return ARShift(this, other).out;
+    }
+
+    return Const(value >> (other is Const ? other.value : other));
+  }
+
+  @override
+  Logic operator <<(dynamic other) {
+    if (Logic._isZeroShiftAmount(other)) {
+      return this;
+    } else if (other is Logic && other is! Const) {
+      return LShift(this, other).out;
+    }
+
+    return Const(value << (other is Const ? other.value : other));
+  }
+
+  @override
+  Logic operator >>>(dynamic other) {
+    if (Logic._isZeroShiftAmount(other)) {
+      return this;
+    } else if (other is Logic && other is! Const) {
+      return RShift(this, other).out;
+    }
+
+    return Const(value >>> (other is Const ? other.value : other));
+  }
+
+  @override
+  Logic and() => Const(value.and());
+
+  @override
+  Logic or() => Const(value.or());
+
+  @override
+  Logic xor() => Const(value.xor());
+
+  @override
+  Logic eq(dynamic other) {
+    if (other is Logic) {
+      _checkMatchingWidth(other);
+      return other is Const
+          ? Const(value.eq(other.value))
+          : Equals(this, other).out;
+    }
+
+    return Const(value.eq(LogicValue.of(other, width: width)));
+  }
+
+  @override
+  Logic neq(dynamic other) {
+    if (other is Logic) {
+      _checkMatchingWidth(other);
+      return other is Const
+          ? Const(value.neq(other.value))
+          : NotEquals(this, other).out;
+    }
+
+    return Const(value.neq(LogicValue.of(other, width: width)));
+  }
 }

lib/src/signals/logic.dart

@@ -445,10 +445,22 @@ class Logic {
   Logic operator ~() => NotGate(this).out;
 
   /// Logical bitwise AND.
-  Logic operator &(Logic other) => And2Gate(this, other).out;
+  Logic operator &(Logic other) {
+    if (other is Const) {
+      return other & this;
+    }
+
+    return And2Gate(this, other).out;
+  }
 
   /// Logical bitwise OR.
-  Logic operator |(Logic other) => Or2Gate(this, other).out;
+  Logic operator |(Logic other) {
+    if (other is Const) {
+      return other | this;
+    }
+
+    return Or2Gate(this, other).out;
+  }
 
   /// Logical bitwise XOR.
   Logic operator ^(Logic other) => Xor2Gate(this, other).out;
@@ -478,6 +490,10 @@ class Logic {
   ///
   /// If [isNet] and [other] is constant, then the result will also be a net.
   Logic operator >>(dynamic other) {
+    if (_isZeroShiftAmount(other)) {
+      return this;
+    }
+
     if (isNet) {
       // many SV simulators don't support shifting of nets, so default this
       final shamt = _constShiftAmount(other);
@@ -498,6 +514,10 @@ class Logic {
   ///
   /// If [isNet] and [other] is constant, then the result will also be a net.
   Logic operator <<(dynamic other) {
+    if (_isZeroShiftAmount(other)) {
+      return this;
+    }
+
     if (isNet) {
       // many SV simulators don't support shifting of nets, so default this
       final shamt = _constShiftAmount(other);
@@ -518,6 +538,10 @@ class Logic {
   ///
   /// If [isNet] and [other] is constant, then the result will also be a net.
   Logic operator >>>(dynamic other) {
+    if (_isZeroShiftAmount(other)) {
+      return this;
+    }
+
     if (isNet) {
       // many SV simulators don't support shifting of nets, so default this
       final shamt = _constShiftAmount(other);
@@ -543,6 +567,17 @@ class Logic {
     }
   }
 
+  /// Indicates whether [other] represents a known constant shift of zero.
+  static bool _isZeroShiftAmount(dynamic other) {
+    if (other is Const) {
+      return other.value.isValid && other.value.isZero;
+    } else if (other is Logic) {
+      return false;
+    } else {
+      return LogicValue.ofInferWidth(other).isZero;
+    }
+  }
+
   /// Unary AND.
   Logic and() => AndUnary(this).out;
 

lib/src/signals/wire.dart

@@ -26,6 +26,39 @@ class _Wire {
   /// The current active value of this signal.
   LogicValue _currentValue;
 
+  /// The [Logic] whose immutability makes this wire immutable.
+  Logic? _immutableOwner;
+
+  /// Additional context explaining why this wire is immutable.
+  String? _immutableReason;
+
+  /// Makes this wire immutable on behalf of [owner].
+  ///
+  /// If this wire is already immutable, the original owner and reason are
+  /// preserved.
+  void makeImmutable(Logic owner, {String? reason}) {
+    _immutableOwner ??= owner;
+    _immutableReason ??= reason;
+  }
+
+  /// Throws an [UnassignableException] if this wire is immutable, identifying
+  /// [signalName] as the signal through which the update was attempted.
+  void _assertMutable({required String signalName}) {
+    final immutableOwner = _immutableOwner;
+    if (immutableOwner != null) {
+      final attemptedUpdateReason =
+          'Signal "$signalName" cannot be updated because it is driven by '
+          'immutable signal "$immutableOwner".';
+      throw UnassignableException(
+        immutableOwner,
+        reason: [
+          attemptedUpdateReason,
+          if (_immutableReason != null) _immutableReason,
+        ].join(' '),
+      );
+    }
+  }
+
   /// The last value of this signal before the [Simulator] tick.
   ///
   /// This is useful for detecting when to trigger an edge.
@@ -143,6 +176,11 @@ class _Wire {
   /// Tells this [_Wire] to adopt all the behavior of [other] so that
   /// it can replace [other]. Returns the [_Wire] that has adopted everything.
   _Wire _adopt(_Wire other) {
+    if (_immutableOwner == null && other._immutableOwner != null) {
+      _immutableOwner = other._immutableOwner;
+      _immutableReason = other._immutableReason;
+    }
+
     _glitchController.emitter.adopt(other._glitchController.emitter);
     other._migrateChangedTriggers(this);
 
@@ -218,6 +256,7 @@ class _Wire {
   ///
   /// This function calls [put()] in [Simulator.injectAction()].
   void inject(dynamic val, {required String signalName, bool fill = false}) {
+    _assertMutable(signalName: signalName);
     Simulator.injectAction(() => put(val, signalName: signalName, fill: fill));
   }
 
@@ -233,6 +272,8 @@ class _Wire {
   /// This function is used for propagating glitches through connected signals.
   /// Use this function for custom definitions of [Module] behavior.
   void put(dynamic val, {required String signalName, bool fill = false}) {
+    _assertMutable(signalName: signalName);
+
     var newValue = LogicValue.of(val, fill: fill, width: width);
 
     if (newValue.width != width) {