LogicStructure and LogicArray

[mkorbel1]

Description & Motivation

Adds both LogicStructure and LogicArray implementations to ROHD. See new documentation for details on API and usage.

It also adds a variety of bug fixes, both previously found and newly discovered.

• Implements Create something like a LogicStructure to group Logics in a way that can be used like Logic #36, the main issue for this PR.
• Fixes SystemVerilog synthesizer assumes undriven signals with valid values are constants during generation #254, where non-synthesizable signal deposition could impact constant values on undriven signals.
• Fixes Reinstate connection width mismatch exception #311, where signal width mismatch exceptions were poor.
• Fixes a bug where indexing of constant values generated invalid SystemVerilog.
• Fixes a bug where constants and LogicValues with negative 64-bit values would generate invalid SystemVerilog notation (with a - sign).
• Adds ConditionalGroup, a single Conditional that accepts a collection of other Conditionals for grouping them together.
• Adds LogicValue.of which accepts a dynamic input and tries its best to build what you're looking for. Adds LogicValue.ofIterable to replace the old LogicValue.of.
• Adds a variety of new tests for various features that were previously under-tested.
• Updates some typos in the README
• Fixed the oven FSM example to not generate the oven_fsm.md file during tests.
• Reorganized Logic and related content into a new signals directory.
• Minor fix in the IterableRemovableQueue to make code more readable.
• Modified SignalRedrivenException constructor to accept a list of signals instead of just a string.
• Added a new LogicConstructionException type for failures in construction of a signal.
• Added a new SignalWidthMismtachException type for failures in connecting two signals together, and updated PortWidthMismatchException.
• Added a new LogicValueConstructionException type for failures when creating a LogicValue
• Upgrades for getRange, swizzle, slice, etc. that remove unnecessary module creation when there are 0-width or only 1 element.
• Added information in Logic related to LogicStructures and LogicArrays: isArrayMember, structureName, arrayIndex, parentStructure
• Migraded index wrapping modification code into a separate reusable utility
• Made some Lists non-growable for minor perf enhancement
• Modified some Exceptions to Errors (and updated Replace generic Exceptions with more specific or ROHD-related exceptions #105)

Also opened some new issues:

• Complete testing for unpacked arrays in generated SystemVerilog #376 tracking completion of testing of SystemVerilog generated for unpacked arrays until bugs are fixed in SystemVerilog simulators.
• Write part-assign automation for LogicArrays #377 tracking part-assign automation for LogicArrays
• Support LogicArray ports rohd-cosim#32 adding LogicArray support to ROHD Cosim

Related Issue(s)

Fix #36
Fix #254
Fix #311

Testing

Extensive new tests written and existing tests upgraded.

Backwards-compatibility

Is this a breaking change that will not be backwards-compatible? If yes, how so?

Yes, a variety of small changes.

• Shorthand notation for mulAssign and divAssign APIs have changed slightly.
• Some things that used to return ConditionalAssign now return Conditional (e.g. < operator for Logic).
• Some error and exception throwing has changed to be more informative

Documentation

Does the change require any updates to documentation? If so, where? Are they included?

Yes, added new docs in the user guide.