LogicStructure and LogicArray

README.md

@@ -487,7 +487,7 @@ Combinational([
       c < 0,
       d < 1,
     ],
-    conditionalType: ConditionalType.Unique
+    conditionalType: ConditionalType.unique
   ),
   CaseZ([b,a].swizzle(),[
       CaseItem(Const(LogicValue.ofString('z1')), [
@@ -496,7 +496,7 @@ Combinational([
     ], defaultItem: [
       e < 0,
     ],
-    conditionalType: ConditionalType.Priority
+    conditionalType: ConditionalType.priority
   )
 ]);
 ```

benchmark/logic_value_of_benchmark.dart

@@ -33,7 +33,7 @@ class LogicValueOfBenchmark extends BenchmarkBase {
 
   @override
   void run() {
-    LogicValue.of(toOf);
+    LogicValue.ofIterable(toOf);
   }
 }
 

doc/user_guide/_docs/logic-arrays.md

@@ -0,0 +1,44 @@
+---
+title: "Logic Arrays"
+permalink: /docs/logic-arrays/
+last_modified_at: 2022-6-5
+toc: true
+---
+
+A `LogicArray` is a type of `LogicStructure` that mirrors multi-dimensional arrays in hardware languages like SystemVerilog.  In ROHD, the `LogicArray` type inherits a lot of functionality from `LogicStructure`, so it can behave like a `Logic` where it makes sense or be individually referenced in other places.
+
+`LogicArray`s can be constructed easily using the constructor:
+
+```dart
+// A 1D array with ten 8-bit elements.
+LogicArray([10], 8);
+
+// A 4x3 2D array, with four arrays, each with three 2-bit elements.
+LogicArray([4, 3], 2, name: 'array4x3');
+
+// A 5x5x5 3D array, with 125 total elements, each 128 bits.
+LogicArray([5, 5, 5], 128);
+```
+
+As long as the total width of a `LogicArray` and another type of `Logic` (including `Logic`, `LogicStructure`, and another `LogicArray`) are the same, assignments and bitwise operations will work in per-element order.  This means you can assign two `LogicArray`s of different dimensions to each other as long as the total width matches.
+
+## Unpacked arrays
+
+In SystemVerilog, there is a concept of "packed" vs. "unpacked" arrays which have different use cases and capabilities. In ROHD, all arrays act the same and you get the best of both worlds.  You can indicate when constructing a `LogicArray` that some number of the dimensions should be "unpacked" as a hint to `Synthesizer`s. Marking an array with a non-zero `numUnpackedDimensions`, for example, will make that many of the dimensions "unpacked" in generated SystemVerilog signal declarations.
+
+```dart
+// A 4x3 2D array, with four arrays, each with three 2-bit elements.
+// The first dimension (4) will be unpacked.
+LogicArray(
+  [4, 3],
+  2,
+  name: 'array4x3w1unpacked',
+  numUnpackedDimensions: 1,
+);
+```
+
+## Array ports
+
+You can declare ports of `Module`s as being arrays (including with some dimensions "unpacked") using `addInputArray` and `addOutputArray`. Note that these do _not_ automatically do validation that the dimensions, element width, number of unpacked dimensions, etc. are equal between the port and the original signal. As long as the overall width matches, the assignment will be clean.
+
+Array ports in generated SystemVerilog will match dimensions (including unpacked) as specified when the port is created.

doc/user_guide/_docs/logic-structures.md

@@ -0,0 +1,68 @@
+---
+title: "Logic Structures"
+permalink: /docs/logic-structures/
+last_modified_at: 2022-6-5
+toc: true
+---
+
+A `LogicStructure` is a useful way to group or bundle related `Logic` signals together. They operate in a similar way to "`packed` `structs`" in SystemVerilog, or a `class` containing multiple `Logic`s in ROHD, but with some important differences.
+
+**`LogicStructure`s will _not_ convert to `struct`s in generated SystemVerilog.** They are purely a way to deal with signals during generation time in ROHD.
+
+**`LogicStructure`s can be used anywhere a `Logic` can be**. This means you can assign one structure to another structure, or inter-assign between normal signals and structures.  As long as the overall width matches, the assignment will work. The order of assignment of bits is based on the order of the `elements` in the structure.
+
+**Elements within a `LogicStructure` can be individually assigned.** This is a notable difference from individual bits of a plain `Logic` where you'd have to use something like `withSet` to effectively modify bits within a signal.
+
+`LogicArray`s are a type of `LogicStructure` and thus inherit these behavioral traits.
+
+## Using `LogicStructure` to group signals
+
+The simplest way to use a `LogicStructure` is to just use its constructor, which requires a collection of `Logic`s.
+
+For example, if you wanted to bundle together a `ready` and a `valid` signal together into one structure, you could do this:
+
+```dart
+final rvStruct = LogicStructure([Logic(name: 'ready'), Logic(name: 'valid')]);
+```
+
+You could now assign this like any other `Logic` all together:
+
+```dart
+Logic ready, valid;
+rvStruct <= [ready, valid].rswizzle();
+```
+
+Or you can assign individual `elements`:
+
+```dart
+rvStruct.elements[0] <= ready;
+rvStruct.elements[1] <= valid;
+```
+
+## Making your own structure
+
+Referencing elements by index is often not ideal for named signals. We can do better by building our own structure that inherits from `LogicStructure`.
+
+```dart
+class ReadyValidStruct extends LogicStructure {
+  final Logic ready;
+  final Logic valid;
+
+  factory ReadyValidStruct() => MyStruct._(
+        Logic(name: 'ready'),
+        Logic(name: 'valid'),
+      );
+
+  ReadyValidStruct._(this.ready, this.valid)
+      : super([ready, valid], name: 'readyValid');
+
+  @override
+  LogicStructure clone({String? name}) => ReadyValidStruct();
+}
+```
+
+Here we've built a class that has `ready` and `valid` as fields, so we can reference those instead of by element index.  We use some tricks with `factory`s to make this easier to work with.
+
+We override the `clone` function so that we can make a duplicate structure of the same type.
+
+There's a lot more that can be done with a custom class like this, but this is a good start. There are places where it may even make sense to prefer a custom `LogicStructure` to an `Interface`.

example/fir_filter.dart

@@ -71,7 +71,7 @@ class FirFilter extends Module {
           ],
           orElse: [out < 0] +
               // Set all 'z' to zero.
-              List<ConditionalAssign>.generate(depth, (index) => z[index] < 0))
+              List<Conditional>.generate(depth, (index) => z[index] < 0))
     ]);
   }
 }

example/oven_fsm.dart

@@ -200,7 +200,9 @@ Future<void> main({bool noPrint = false}) async {
   //
   // Check on https://mermaid.js.org/intro/ to view the diagram generated.
   // If you are using vscode, you can download the mermaid extension.
-  oven.ovenStateMachine.generateDiagram(outputPath: 'oven_fsm.md');
+  if (!noPrint) {
+    oven.ovenStateMachine.generateDiagram(outputPath: 'oven_fsm.md');
+  }
 
   // Before we can simulate or generate code with the counter, we need
   // to build it.

lib/rohd.dart

@@ -3,9 +3,9 @@
 
 export 'src/external.dart';
 export 'src/interface.dart';
-export 'src/logic.dart';
 export 'src/module.dart';
 export 'src/modules/modules.dart';
+export 'src/signals/signals.dart';
 export 'src/simulator.dart';
 export 'src/state_machine.dart';
 export 'src/swizzle.dart';

lib/src/collections/iterable_removable_queue.dart

@@ -24,7 +24,7 @@ class IterableRemovableQueue<T> {
   /// Adds a new item to the end of the queue.
   void add(T item) {
     final newElement = _IterableRemovableElement<T>(item);
-    if (_first == null) {
+    if (isEmpty) {
       _first = newElement;
       _last = _first;
     } else {

lib/src/exceptions/conditionals/signal_redriven_exception.dart

@@ -18,7 +18,7 @@ class SignalRedrivenException extends RohdException {
   /// with default error [message].
   ///
   /// Creates a [SignalRedrivenException] with an optional error [message].
-  SignalRedrivenException(String signals,
+  SignalRedrivenException(Iterable<Logic> signals,
       [String message = 'Sequential drove the same signal(s) multiple times: '])
-      : super(message + signals);
+      : super(message + signals.toString());
 }

lib/src/exceptions/logic/logic_construction_exception.dart

@@ -0,0 +1,21 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// logic_construction_exception.dart
+// An exception thrown when a logical signal fails to construct.
+//
+// 2023 June 1
+// Author: Max Korbel <max.korbel@intel.com>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd/src/exceptions/rohd_exception.dart';
+
+/// An exception that thrown when a [Logic] is connecting to itself.
+class LogicConstructionException extends RohdException {
+  /// A message describing why the construction failed.
+  final String reason;
+
+  /// Creates an exception when a [Logic] is trying to connect itself.
+  LogicConstructionException(this.reason)
+      : super('Failed to construct signal: $reason');
+}

lib/src/exceptions/logic/logic_exceptions.dart

@@ -2,5 +2,7 @@
 /// SPDX-License-Identifier: BSD-3-Clause
 
 export 'invalid_multiplier_exception.dart';
+export 'logic_construction_exception.dart';
 export 'put_exception.dart';
 export 'self_connecting_logic_exception.dart';
+export 'signal_width_mismatch_exception.dart';

lib/src/exceptions/logic/signal_width_mismatch_exception.dart

@@ -0,0 +1,21 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// port_width_mismatch_exception.dart
+// Definition for exception when a signal has the wrong width.
+//
+// 2023 June 2
+// Author: Max Korbel <max.korbel@intel.com>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd/src/exceptions/rohd_exception.dart';
+
+/// An [Exception] thrown when a signal has the wrong width.
+class SignalWidthMismatchException extends RohdException {
+  /// Constructs a new [Exception] for when a signal has the wrong width.
+  SignalWidthMismatchException(Logic signal, int expectedWidth,
+      {String additionalMessage = ''})
+      : super('Signal ${signal.name} has the wrong width.'
+            ' Expected $expectedWidth but found ${signal.width}.'
+            ' $additionalMessage');
+}

lib/src/exceptions/logic_value/logic_value_construction_exception.dart

@@ -0,0 +1,18 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// logic_value_construction_exception.dart
+// An exception that thrown when a signal failes to `put`.
+//
+// 2023 May 1
+// Author: Max Korbel <max.korbel@intel.com>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd/src/exceptions/rohd_exception.dart';
+
+/// An exception that thrown when a [LogicValue] cannot be properly constructed.
+class LogicValueConstructionException extends RohdException {
+  /// Creates an exception for when a construction of a `LogicValue` fails.
+  LogicValueConstructionException(String message)
+      : super('Failed to construct `LogicValue`: $message');
+}

lib/src/exceptions/logic_value/logic_value_exceptions.dart

@@ -1,4 +1,5 @@
-/// Copyright (C) 2023 Intel Corporation
-/// SPDX-License-Identifier: BSD-3-Clause
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
 
 export 'invalid_truncation_exception.dart';
+export 'logic_value_construction_exception.dart';

lib/src/exceptions/module/port_width_mismatch_exception.dart

@@ -13,9 +13,11 @@ import 'package:rohd/src/exceptions/rohd_exception.dart';
 /// An [Exception] thrown when a port has the wrong width.
 class PortWidthMismatchException extends RohdException {
   /// Constructs a new [Exception] for when a port has the wrong width.
-  PortWidthMismatchException(Logic port, int expectedWidth)
+  PortWidthMismatchException(Logic port, int expectedWidth,
+      {String additionalMessage = ''})
       : super('Port ${port.name} has the wrong width.'
-            ' Expected $expectedWidth but found ${port.width}.');
+            ' Expected $expectedWidth but found ${port.width}.'
+            ' $additionalMessage');
 
   /// Constructs a new [Exception] for when two ports should have been the
   /// same width, but were not.

lib/src/interface.dart

@@ -12,18 +12,6 @@ import 'package:collection/collection.dart';
 import 'package:meta/meta.dart';
 
 import 'package:rohd/rohd.dart';
-import 'package:rohd/src/exceptions/name/name_exceptions.dart';
-import 'package:rohd/src/utilities/sanitizer.dart';
-
-/// An extension of [Logic] useful for [Interface] definitions.
-class Port extends Logic {
-  /// Constructs a [Logic] intended to be used for ports in an [Interface].
-  Port(String name, [int width = 1]) : super(name: name, width: width) {
-    if (!Sanitizer.isSanitary(name)) {
-      throw InvalidPortNameException(name);
-    }
-  }
-}
 
 /// Represents a logical interface to a [Module].
 ///