Add LogicEnum for enumerable types as hardware signals

[mkorbel1]

Description & Motivation

Adds LogicEnum<T extends Enum>, a strongly typed hardware signal that maps Dart enum values to hardware encodings.

LogicEnum preserves enum information through simulation, conditional logic, FSMs, module hierarchy, and SystemVerilog synthesis. Generated SystemVerilog uses enum typedefs and symbolic values by default, while generateEnums: false retains packed-logic output for tool compatibility.

The implementation validates mappings and assignments, supports explicit sparse encodings, and preserves enum types across typed inputs and outputs. Struct support and typed enum inout ports remain out of scope.

Related Issue(s)

Addresses #139 and the enum portion of #594. Related to #592.

Testing

Added comprehensive LogicEnum unit and integration coverage, including simulation, conditionals, FSMs, hierarchy, arrays and structures, typed ports, and SystemVerilog generation in enabled and disabled modes.

Generated SystemVerilog is compiled and behaviorally compared with Icarus Verilog. The full non-benchmark suite passes with 1,357 tests and one expected skip, and all 49 enum tests pass on Node.

Backwards-compatibility

This is mostly additive, and designs that do not use LogicEnum are unaffected.

FiniteStateMachine<StateIdentifier> now requires an enum state identifier, and its state signals are LogicEnum instances. Existing enum-based FSMs remain compatible because LogicEnum extends Logic.

SystemVerilog enum generation is enabled by default for LogicEnum signals and can be disabled with SystemVerilogSynthesizerConfiguration(generateEnums: false).

Documentation

The new public APIs and configuration options include Dartdoc. The FSM tests also demonstrate typed enum signals and direct enum assignments. A separate user-guide page is not included.

[desmonddak]

Please establish the Const / enum-literal contract explicitly
LogicEnum should remain a driveable Logic subtype, not become a Const subtype.

The intended distinction should be documented and tested:

LogicEnum is a signal with a domain mapping and a driveable clone.
A Dart enum member is a domain literal, not an ordinal or universally meaningful packed value.
getsEnum(T.member), put(T.member), inject(T.member), and conditional assignment should lower the member through the receiver’s mapping.
A packed Const may drive a LogicEnum only when its exact encoded value belongs to that mapping.
Unmapped packed constants and unmapped raw values must be rejected or constrained to x according to the current API contract.
Cloning an enum signal must retain its enum type, mapping, width, definitionName, and definition-name reservation policy while producing a driveable signal.

One important release consideration: it changes FiniteStateMachine to require StateIdentifier extends Enum. That is a real breaking change and needs a migration note.

We will need some appropriate extension for netlist to represent enums like it represents constants (they do not evaporate) along with tests. This is likely a major change for netlist, including a version update to show it has enum declarations.