Add LogicEnum for enumerable types as hardware signals

.github/configs/mlc_config.json

@@ -12,6 +12,9 @@
     {
       "pattern":"^https://github.com"
     },
+    {
+      "pattern":"^https://intel\\.github\\.io(?:/|$)"
+    },
     {
       "pattern":"^https://pymtl3.readthedocs.io/en/latest/$"
     },

doc/user_guide/_docs/A02-logical_signals.md

@@ -2,7 +2,7 @@
 title: "Logical Signals"
 permalink: /docs/logical-signals/
 excerpt: "Logic signals"
-last_modified_at: 2025-7-24 
+last_modified_at: 2026-08-10
 toc: true
 ---
 
@@ -18,7 +18,7 @@ var x = Logic();
 var bus = Logic(name: 'b', width: 8)
 ```
 
-There are other types like [`LogicArray`](https://intel.github.io/rohd/rohd/LogicArray-class.html)s and [`LogicStructure`](https://intel.github.io/rohd/rohd/LogicStructure-class.html)s which extend from `Logic`, as well.
+There are other types which extend `Logic`, including [`LogicArray`](https://intel.github.io/rohd/rohd/LogicArray-class.html), [`LogicStructure`](https://intel.github.io/rohd/rohd/LogicStructure-class.html), and [`LogicEnum`](https://intel.github.io/rohd-website/docs/logic-enums/) for representing Dart enum values as typed hardware signals.
 
 #### The value of a signal
 

doc/user_guide/_docs/A08-modules.md

@@ -2,7 +2,7 @@
 title: "Modules"
 permalink: /docs/modules/
 excerpt: "Modules"
-last_modified_at: 2025-7-24
+last_modified_at: 2026-08-10
 toc: true
 ---
 
@@ -54,7 +54,7 @@ All gates or functionality apart from assign statements in ROHD are implemented
 
 The default width of a port is 1.  You can control the width of ports using the `width` argument of `addInput()` and `addOutput()`.  You may choose to set them to a static number, based on some other variable, or even dynamically based on the width of input parameters.  These functions also return the input/output signal.
 
-There are also similar functions called `addTypedInput` and `addTypedOutput` which will create a port with matching widths and types.  This is especially useful for creating `LogicStructure` ports.
+There are also similar functions called `addTypedInput` and `addTypedOutput` which will create a port with matching widths and types. This is especially useful for creating `LogicStructure` and [`LogicEnum`](https://intel.github.io/rohd-website/docs/logic-enums/) ports.
 
 Available mechanisms for creating ports on a `Module` are listed below:
 
@@ -70,6 +70,8 @@ Available mechanisms for creating ports on a `Module` are listed below:
 | `addInOut`         | Adds an in/out (bidirectional) `Logic` port to the module with explicit width. Requires an external source. |
 | `addInOutArray`    | Adds an in/out (bidirectional) `LogicArray` port to the module with explicit dimensions and element width. Requires an external source. |
 
+`LogicEnum` supports typed input and output ports. Typed enum in/out ports are not currently supported because there is no net-backed `LogicEnum` type.
+
 You can also use [`Interface`s](https://intel.github.io/rohd-website/docs/interfaces/) to create groups of ports.
 
 It can be convenient to use dart getters for signal names so that accessing inputs and outputs of a module doesn't require calling `input()` and `output()` every time.  It also makes it easier to consume your module.

doc/user_guide/_docs/A10-conditionals.md

@@ -2,7 +2,7 @@
 title: "Conditionals"
 permalink: /docs/conditionals/
 excerpt: "Conditionals"
-last_modified_at: 2022-12-06
+last_modified_at: 2026-08-10
 toc: true
 ---
 
@@ -92,6 +92,8 @@ Combinational([
 ]);
 ```
 
+The `cases` helper accepts enum members as keys when its selector is a compatible [`LogicEnum`](https://intel.github.io/rohd-website/docs/logic-enums/). It returns an ordinary `Logic`, so enum results must be supplied as explicitly mapped signals rather than bare Dart enum members.
+
 Note that ROHD supports the 'z' syntax, not the '?' syntax (these are equivalent in SystemVerilog).
 
 There is no support for an equivalent of `casex` from SystemVerilog, since it can easily cause unsynthesizeable code to be generated (see: <https://www.verilogpro.com/verilog-case-casez-casex/>).

doc/user_guide/_docs/A15-fsm.md

@@ -2,7 +2,7 @@
 title: "Finite State Machines"
 permalink: /docs/fsm/
 excerpt: "Finite State Machines"
-last_modified_at: 2023-09-19
+last_modified_at: 2026-08-10
 toc: true
 ---
 
@@ -47,14 +47,17 @@ Now, let's define the encoding of outputs (the color of the light).
 
 ```dart
 enum LightColor {
-  green(0),
-  yellow(1),
-  red(2);
-
-  final int value;
-
-  const LightColor(this.value);
+  green,
+  yellow,
+  red,
 }
+
+final lightType = LogicEnum(
+  LightColor.values,
+  definitionName: 'LightColor',
+);
+final northLight = addTypedOutput('northLight', lightType.clone);
+final eastLight = addTypedOutput('eastLight', lightType.clone);
 ```
 
 Now we can go ahead and describe the set of states for our state machine. Note that for each state, we describe a few things:
@@ -68,16 +71,16 @@ final states = <State<LightStates>>[
   State(LightStates.northFlowing, events: {
     TrafficPresence.isEastActive(traffic): LightStates.northSlowing,
   }, actions: [
-    northLight < LightColor.green.value,
-    eastLight < LightColor.red.value,
+    northLight < LightColor.green,
+    eastLight < LightColor.red,
   ]),
   State(
     LightStates.northSlowing,
     events: {},
     defaultNextState: LightStates.eastFlowing,
     actions: [
-      northLight < LightColor.yellow.value,
-      eastLight < LightColor.red.value,
+      northLight < LightColor.yellow,
+      eastLight < LightColor.red,
     ],
   ),
   State(
@@ -86,17 +89,17 @@ final states = <State<LightStates>>[
       TrafficPresence.isNorthActive(traffic): LightStates.eastSlowing,
     },
     actions: [
-      northLight < LightColor.red.value,
-      eastLight < LightColor.green.value,
+      northLight < LightColor.red,
+      eastLight < LightColor.green,
     ],
   ),
   State(
     LightStates.eastSlowing,
     events: {},
     defaultNextState: LightStates.northFlowing,
     actions: [
-      northLight < LightColor.red.value,
-      eastLight < LightColor.yellow.value,
+      northLight < LightColor.red,
+      eastLight < LightColor.yellow,
     ],
   ),
 ];
@@ -120,14 +123,14 @@ final states = <State<LightStates>>[
   State(LightStates.northFlowing, events: {
     TrafficPresence.isEastActive(traffic): LightStates.northSlowing,
   }, actions: [
-    northLight < LightColor.green.value,
+    northLight < LightColor.green,
   ]),
   State(
     LightStates.northSlowing,
     events: {},
     defaultNextState: LightStates.eastFlowing,
     actions: [
-      northLight < LightColor.yellow.value,
+      northLight < LightColor.yellow,
     ],
   ),
   State(
@@ -136,15 +139,15 @@ final states = <State<LightStates>>[
       TrafficPresence.isNorthActive(traffic): LightStates.eastSlowing,
     },
     actions: [
-      eastLight < LightColor.green.value,
+      eastLight < LightColor.green,
     ],
   ),
   State(
     LightStates.eastSlowing,
     events: {},
     defaultNextState: LightStates.northFlowing,
     actions: [
-      eastLight < LightColor.yellow.value,
+      eastLight < LightColor.yellow,
     ],
   ),
 ];
@@ -156,13 +159,13 @@ FiniteStateMachine<LightStates>(
   states,
   setupActions: [
     // by default, lights should be red
-    northLight < LightColor.red.value,
-    eastLight < LightColor.red.value,
+    northLight < LightColor.red,
+    eastLight < LightColor.red,
   ],
 );
 ```
 
-This state machine is now functional and synthesizable into SystemVerilog!
+This state machine is now functional and synthesizable into SystemVerilog. Its `currentState` and `nextState` signals are `LogicEnum<LightStates>`, and generated SystemVerilog uses the `LightColor` enum for internal output backing signals and symbolic assignments. See [Logic Enums](https://intel.github.io/rohd-website/docs/logic-enums/) for details about enum mappings and generation.
 
 You can even generate a mermaid diagram for the state machine using the [`generateDiagram`](https://intel.github.io/rohd/rohd/FiniteStateMachine/generateDiagram.html) API.
 

doc/user_guide/_docs/A21-generation.md

@@ -1,7 +1,7 @@
 ---
 title: "Generating Outputs"
 permalink: /docs/generation/
-last_modified_at: 2023-11-13
+last_modified_at: 2026-08-10
 toc: true
 ---
 
@@ -53,6 +53,20 @@ final generatedSv = myModule.generateSynth(
 
 The same configuration can be passed directly to `SystemVerilogSynthesizer` when using `SynthBuilder`.
 
+## Controlling enum generation
+
+[`LogicEnum`](https://intel.github.io/rohd-website/docs/logic-enums/) signals generate SystemVerilog enum typedefs and symbolic values by default. Enum generation can be disabled for compatibility with tools or flows that require packed logic:
+
+```dart
+final generatedSv = myModule.generateSynth(
+  configuration: const SystemVerilogSynthesizerConfiguration(
+    generateEnums: false,
+  ),
+);
+```
+
+With enum generation disabled, the same design is emitted using ordinary packed logic and numeric values.
+
 ## Controlling naming
 
 ### Modules

doc/user_guide/_docs/A23-logic-enums.md

@@ -0,0 +1,108 @@
+---
+title: "Logic Enums"
+permalink: /docs/logic-enums/
+excerpt: "Representing enumerable values as hardware signals"
+last_modified_at: 2026-08-10
+toc: true
+---
+
+## Logic Enums
+
+[`LogicEnum<T>`](https://intel.github.io/rohd/rohd/LogicEnum-class.html) is a `Logic` signal constrained to values from a Dart enum. It associates each enum member with a bit-vector encoding and preserves that type information through simulation and SystemVerilog generation.
+
+```dart
+enum Operation { idle, read, write }
+
+final operation = LogicEnum(
+  Operation.values,
+  name: 'operation',
+  definitionName: 'Operation',
+);
+```
+
+The default constructor assigns sequential encodings in the order provided. The width is inferred from the number of values, or it can be set explicitly with `width`.
+
+For sparse or protocol-defined encodings, use `LogicEnum.withMapping`:
+
+```dart
+final operation = LogicEnum<Operation>.withMapping(
+  {
+    Operation.idle: 0,
+    Operation.read: 1,
+    Operation.write: 3,
+  },
+  width: 2,
+  definitionName: 'Operation',
+);
+```
+
+Mappings must be non-empty and contain unique, valid, non-negative encodings that fit within the signal width. Reading a valid but unmapped bit pattern in simulation produces `x`.
+
+## Using Enum Values
+
+Enum members can be used directly in conditional assignments to a compatible `LogicEnum`:
+
+```dart
+Combinational([
+  If(enable, then: [
+    operation < Operation.read,
+  ], orElse: [
+    operation < Operation.idle,
+  ]),
+]);
+```
+
+Use `getsEnum` for a continuous connection to a constant enum value. In testbench code, `put` and `inject` also accept enum members. The current enum member is available through `valueEnum` when the signal contains a mapped value.
+
+```dart
+final constantOperation = operation.clone()
+  ..getsEnum(Operation.write);
+
+operation.inject(Operation.read);
+expect(operation.valueEnum, Operation.read);
+```
+
+Assignments between `LogicEnum`s require the same Dart enum type, width, and compatible encodings. A destination may have additional mapped values, but every value mapped by the source must have the same encoding in the destination.
+
+## Cases
+
+Enum members can be used as keys when a `LogicEnum` is the selector:
+
+```dart
+final selected = cases(operation, {
+  Operation.idle: idleData,
+  Operation.read: readData,
+  Operation.write: writeData,
+});
+```
+
+The `cases` helper returns an ordinary `Logic`, so bare enum members are not accepted as result or default values. When an enum result is required, provide explicitly mapped `LogicEnum` branch signals and connect the result to a compatible `LogicEnum` destination.
+
+## Module Ports
+
+Use `addTypedInput` and `addTypedOutput` to preserve an enum's mapping across module boundaries:
+
+```dart
+final operationIn = addTypedInput('operationIn', operationSource);
+final operationOut = addTypedOutput('operationOut', operationIn.clone);
+
+operationOut <= operationIn;
+```
+
+Generated SystemVerilog keeps input and output ports packed and uses internal enum-typed backing signals. Typed `LogicEnum` in/out ports are not supported because `LogicEnum` does not currently have a net-backed variant.
+
+## Generated SystemVerilog
+
+By default, SystemVerilog generation emits enum typedefs and symbolic values for `LogicEnum` signals. The `definitionName` supplies the preferred typedef name, and generated names are uniquified when necessary.
+
+Enum generation can be disabled for tools or flows that require ordinary packed logic:
+
+```dart
+final generatedSv = module.generateSynth(
+  configuration: const SystemVerilogSynthesizerConfiguration(
+    generateEnums: false,
+  ),
+);
+```
+
+Disabling enum generation changes only the generated representation; simulation behavior and the ROHD model remain typed.

lib/rohd.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2021-2023 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 
 export 'src/exceptions/exceptions.dart';
@@ -8,7 +8,7 @@ export 'src/interfaces/interfaces.dart';
 export 'src/module.dart';
 export 'src/modules/modules.dart';
 export 'src/selection.dart';
-export 'src/signals/signals.dart';
+export 'src/signals/signals.dart' hide LogicDef;
 export 'src/simulator.dart';
 export 'src/swizzle.dart';
 export 'src/synthesizers/synthesizers.dart';