Refactor to combine LogicValue and LogicValues into LogicValue,…

… plus some related adjustments (#115)

CHANGELOG.md

@@ -1,3 +1,14 @@
+## (next release)
+- Breaking: Merged `LogicValue` and `LogicValues` into one type called `LogicValue`.
+- Deprecation: Aligned `LogicValue` to `Logic` by renaming `length` to `width`.
+- Breaking: `Logic.put` no longer accepts `List<LogicValue>`, swizzle it together instead.
+- Deprecated `Logic.valueInt` and `Logic.valueBigInt`; instead use equivalent functions on `Logic.value`.
+- Deprecated `bit` on both `LogicValue` and `Logic`; instead just check `width`.
+- Added ability in `LogicValue.toString` to decide whether or not to include the width annotation through `includeWidth` argument.
+- Fixed a bug related to zero-width construction of `LogicValue`s (https://github.com/intel/rohd/issues/90).
+- Fixed a bug where generated constants in SystemVerilog had no width, which can cause issues in some cases (e.g. swizzles) (https://github.com/intel/rohd/issues/89)
+- Added capability to convert binary strings to ints with underscore separators using `bin` (https://github.com/intel/rohd/issues/56).
+
 ## 0.2.0
 - Updated implementation to avoid `Iterable.forEach` to make debug easier.
 - Added `ofBool` to `LogicValue` and `LogicValues` (https://github.com/intel/rohd/issues/34).

README.md

@@ -162,22 +162,22 @@ var bus = Logic(name: 'b', width: 8)
 #### The value of a signal
 You can access the current value of a signal using `value`.  You cannot access this as part of synthesizable ROHD code.  ROHD supports X and Z values and propogation.  If the signal is valid (no X or Z in it), you can also convert it to an int with `valueInt` (ROHD will throw an exception otherwise).  If the signal has more bits than a dart `int` (64 bits, usually), you need to use `valueBigInt` to get a `BigInt` (again, ROHD will throw an exception otherwise).
 
-Bits of a `Logic` are of type [`LogicValue`](https://intel.github.io/rohd/rohd/LogicValue-class.html), with pre-defined constant enum values `x`, `z`, `one`, and `zero`.  The value of a `Logic` is represented by a [`LogicValues`](https://intel.github.io/rohd/rohd/LogicValues-class.html), which behaves like a collection of `LogicValue`s.  Both `LogicValue` and `LogicValues` have a number of built-in logical operations (like &, |, ^, +, -, etc.).
+The value of a `Logic` is of type [`LogicValue`](https://intel.github.io/rohd/rohd/LogicValue-class.html), with pre-defined constant bit values `x`, `z`, `one`, and `zero`.  `LogicValue` has a number of built-in logical operations (like &, |, ^, +, -, etc.).
 
 ```dart
 var x = Logic(width:2);
 
-// a LogicValues
+// a LogicValue
 x.value
 
 // an int
-x.valueInt
+x.value.toInt()
 
 // a BigInt
-x.valueBigInt
+x.value.toBigInt()
 ```
 
-You can create `LogicValues`s using a variety of constructors including `fromInt`, `fromBigInt`, `filled` (like '0, '1, 'x, etc. in SystemVerilog), and `from` (which takes any `Iterable<LogicValue>`).
+You can create `LogicValue`s using a variety of constructors including `ofInt`, `ofBigInt`, `filled` (like '0, '1, 'x, etc. in SystemVerilog), and `of` (which takes any `Iterable<LogicValue>`).
 
 #### Listening to and waiting for changes
 You can trigger on changes of `Logic`s with some built in events.  ROHD uses dart synchronous [streams](https://dart.dev/tutorials/language/streams) for events.
@@ -423,11 +423,11 @@ ROHD supports [`Case`](https://intel.github.io/rohd/rohd/Case-class.html) and [`
 ```dart
 Combinational([
   Case([b,a].swizzle(), [
-      CaseItem(Const(LogicValues.ofString('01')), [
+      CaseItem(Const(LogicValue.ofString('01')), [
         c < 1,
         d < 0
       ]),
-      CaseItem(Const(LogicValues.ofString('10')), [
+      CaseItem(Const(LogicValue.ofString('10')), [
         c < 1,
         d < 0,
       ]),
@@ -438,7 +438,7 @@ Combinational([
     conditionalType: ConditionalType.Unique
   ),
   CaseZ([b,a].swizzle(),[
-      CaseItem(Const(LogicValues.ofString('z1')), [
+      CaseItem(Const(LogicValue.ofString('z1')), [
         e < 1,
       ])
     ], defaultItem: [
@@ -523,7 +523,7 @@ class Counter extends Module {
 
 ### Non-synthesizable signal deposition
 
-For testbench code or other non-synthesizable code, you can use `put` or `inject` on any `Logic` to deposit a value on the signal.  The two functions have similar behavior, but `inject` is shorthand for calling `put` inside of `Simulator.injectAction`, which allows the deposited change to propogate within the same `Simulator` tick.
+For testbench code or other non-synthesizable code, you can use `put` or `inject` on any `Logic` to deposit a value on the signal.  The two functions have similar behavior, but `inject` is shorthand for calling `put` inside of `Simulator.injectAction`, which allows the deposited change to propogate within the same `Simulator` tick.  Generally, you will want to use `inject` for testbench interaction with a design.
 
 ```dart
 var a = Logic(), b = Logic(width:4);
@@ -533,17 +533,7 @@ a.put(0);
 b.inject(0xf);
 
 // you can also put a `LogicValue` onto a signal
-a.put(LogicValue.x);
-
-// you can also put a `LogicValues` onto a signal
-b.put(LogicValues([
-  LogicValue.one,
-  LogicValue.zero,
-  LogicValue.x,
-  LogicValue.z,
-  ].reversed // reverse since arrays start with 0
-));
-
+a.inject(LogicValue.x);
 ```
 
 Note: changing a value directly with `put()` will propogate the value, but it will not trigger flip-flop edge detection or cosim interaction.
@@ -745,5 +735,5 @@ Read more about cocotb here: https://github.com/cocotb/cocotb or https://docs.co
 Author: Max Korbel <<max.korbel@intel.com>>
 
 
-Copyright (C) 2021 Intel Corporation  
+Copyright (C) 2021-2022 Intel Corporation  
 SPDX-License-Identifier: BSD-3-Clause

doc/Architecture.md

@@ -6,14 +6,11 @@ This document describes the organization and architecture of the ROHD framework.
 ## Major Concepts
 
 ### Logic
-The `Logic` is the fundamental "wire" that connects signals throughout a hardware design.  It behaves very similarly to a `logic` in SystemVerilog.  It has a fixed creation-time-defined width.  At any point in time, it has one value of type `LogicValues`.  A `Logic` can be connected to up to one source, and any number of destinations.  All connections must be the same width.
+The `Logic` is the fundamental "wire" that connects signals throughout a hardware design.  It behaves very similarly to a `logic` in SystemVerilog.  It has a fixed creation-time-defined width.  At any point in time, it has one value of type `LogicValue`.  A `Logic` can be connected to up to one source, and any number of destinations.  All connections must be the same width.
 
 Any time the source of a `Logic` changes, it propogates the change outwards to its destinations.  There are various events that can be subscribed to related to signal value transitions on `Logic`.
 
-### LogicValues and LogicValue
-A `LogicValues` represents a multi-bit 4-value (`1`, `0`, `x`, `z`) static value.  It is immutable.  It can be thought of as an array of `LogicValue`s.
-
-A `LogicValue` is a single bit 4-value bit.
+A `LogicValue` represents a multi-bit (including 0-bit and 1-bit) 4-value (`1`, `0`, `x`, `z`) static value.  It is immutable. 
 
 ### Module
 The `Module` is the fundamental building block of hardware designs in ROHD.  They have clearly defined inputs and outputs, and all logic contained within the module should connect either/both from inputs and to outputs.  The ROHD framework will determine at `build()` time which logic sits within which `Module`.  Any functional operation, whether a simple gate or a large module, is implemented as a `Module`.
@@ -40,4 +37,4 @@ Contains logic for synthesizing `Module`s into some output.  It is structured to
 Various generic objects and classes that may be useful in different areas of ROHD.
 
 ### values
-Definitions for things like `LogicValues` and `LogicValue`.
+Definitions for things related to `LogicValue`.

lib/rohd.dart

@@ -1,4 +1,4 @@
-/// Copyright (C) 2021 Intel Corporation
+/// Copyright (C) 2021-2022 Intel Corporation
 /// SPDX-License-Identifier: BSD-3-Clause
 
 export 'src/simulator.dart';
@@ -8,6 +8,8 @@ export 'src/wave_dumper.dart';
 export 'src/modules/modules.dart';
 export 'src/interface.dart';
 export 'src/external.dart';
-export 'src/values/values.dart';
 export 'src/synthesizers/synthesizers.dart';
 export 'src/swizzle.dart';
+export 'src/values/values.dart';
+// ignore: unused_import
+import 'src/values/values.dart';

lib/src/external.dart

@@ -10,8 +10,6 @@
 
 import 'package:rohd/rohd.dart';
 
-// TODO: offer a way to reference sub-module signals
-
 /// Represents a [Module] whose definition exists outside of this framework in SystemVerilog.
 ///
 /// This is useful for interacting with SystemVerilog modules.