Interface struct

doc/tutorials/chapter_6/answers/exercise_2_n_bit_subtractor.dart

@@ -7,7 +7,6 @@ import '../../chapter_3/answers/helper.dart';
 import '../../chapter_5/answers/full_subtractor.dart';
 
 class FullSubtractorComb extends FullSubtractor {
-  @override
   FullSubtractorComb(super.a, super.b, super.borrowIn) {
     // Declare input and output
     final a = input('a');

lib/src/exceptions/logic/put_exception.dart

@@ -9,10 +9,11 @@
 
 import 'package:rohd/rohd.dart';
 
-/// An exception that thrown when a [Logic] signal fails to `put`.
+/// An exception that thrown when a [Logic] signal fails to [Logic.put].
 class PutException extends RohdException {
-  /// Creates an exception for when a `put` fails on a `Logic` with [context] as
-  /// to where the
+  /// Creates an exception for when a [Logic.put] fails on a [Logic] with
+  /// [context] as to where the failure occurred and [message] describing the
+  /// failure.
   PutException(String context, String message)
       : super('Failed to put value on signal ($context): $message');
 }

lib/src/interfaces/interface.dart

@@ -79,43 +79,81 @@ class Interface<TagType extends Enum> {
       {Iterable<TagType>? inputTags,
       Iterable<TagType>? outputTags,
       Iterable<TagType>? inOutTags,
-      String Function(String original)? uniquify}) {
+      String Function(String original)? uniquify,
+      String? groupName}) {
     uniquify ??= (original) => original;
 
+    // Derive the interface group name from the uniquify function.
+    // We probe with a sentinel to detect what the function adds.
+    // Supports prefix patterns (e.g. 'ace0_pcieRp_X') and suffix
+    // patterns (e.g. 'x_m', 'x_dti_a2f').
+    if (groupName == null) {
+      const sentinel = '\x00';
+      final probed = uniquify(sentinel);
+      if (probed.endsWith(sentinel)) {
+        // Prefix-based: uniquify('X') → 'prefix_X'
+        groupName = probed.substring(0, probed.length - 1);
+      } else if (probed.startsWith(sentinel)) {
+        // Suffix-based: uniquify('X') → 'X_suffix'
+        groupName = probed.substring(1);
+      }
+    }
+
+    // Helper to register the port group if we successfully extracted one.
+    void registerGroup(String portName) {
+      if (groupName != null && groupName.isNotEmpty) {
+        // Strip leading/trailing separators for a cleaner group name.
+        var trimmed = groupName;
+        if (trimmed.startsWith('_')) {
+          trimmed = trimmed.substring(1);
+        }
+        if (trimmed.endsWith('_')) {
+          trimmed = trimmed.substring(0, trimmed.length - 1);
+        }
+        if (trimmed.isNotEmpty) {
+          module.registerPortGroup(portName, trimmed);
+        }
+      }
+    }
+
     if (inputTags != null) {
       for (final port in getPorts(inputTags).values) {
+        final portName = uniquify(port.name);
         port <=
             (port is LogicArray
                 ? module.addInputArray(
-                    uniquify(port.name),
+                    portName,
                     srcInterface.port(port.name),
                     dimensions: port.dimensions,
                     elementWidth: port.elementWidth,
                     numUnpackedDimensions: port.numUnpackedDimensions,
                   )
                 : module.addInput(
-                    uniquify(port.name),
+                    portName,
                     srcInterface.port(port.name),
                     width: port.width,
                   ));
+        registerGroup(portName);
       }
     }
 
     if (outputTags != null) {
       for (final port in getPorts(outputTags).values) {
+        final portName = uniquify(port.name);
         final output = (port is LogicArray
             ? module.addOutputArray(
-                uniquify(port.name),
+                portName,
                 dimensions: port.dimensions,
                 elementWidth: port.elementWidth,
                 numUnpackedDimensions: port.numUnpackedDimensions,
               )
             : module.addOutput(
-                uniquify(port.name),
+                portName,
                 width: port.width,
               ));
         output <= port;
         srcInterface.port(port.name) <= output;
+        registerGroup(portName);
       }
     }
 
@@ -131,20 +169,22 @@ class Interface<TagType extends Enum> {
               port, 'LogicNet must be used for inOut ports.');
         }
 
+        final portName = uniquify(port.name);
         port <=
             (port is LogicArray
                 ? module.addInOutArray(
-                    uniquify(port.name),
+                    portName,
                     srcInterface.port(port.name),
                     dimensions: port.dimensions,
                     elementWidth: port.elementWidth,
                     numUnpackedDimensions: port.numUnpackedDimensions,
                   )
                 : module.addInOut(
-                    uniquify(port.name),
+                    portName,
                     srcInterface.port(port.name),
                     width: port.width,
                   ));
+        registerGroup(portName);
       }
     }
   }

lib/src/interfaces/interface_structure.dart

@@ -0,0 +1,40 @@
+// Copyright (C) 2026 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// interface_structure.dart
+// A LogicStructure that represents a group of interface ports.
+//
+// 2026 May
+// Author: ROHD Contributors
+
+import 'package:meta/meta.dart';
+import 'package:rohd/rohd.dart';
+
+/// A [LogicStructure] created from a group of [Interface] ports.
+///
+/// This enables [Interface] ports grouped by direction to be represented as
+/// a single `typedef struct packed` in SystemVerilog, rather than individual
+/// flat signals.
+///
+/// The [interfaceTypeName] is used to derive the SV typedef name when
+/// generating struct-typed output.
+@internal
+class InterfaceStructure extends LogicStructure {
+  /// The type name to use for the SV struct typedef, derived from the
+  /// interface class name.
+  final String interfaceTypeName;
+
+  /// Creates an [InterfaceStructure] from a list of [Logic] elements.
+  InterfaceStructure(
+    super.elements, {
+    required this.interfaceTypeName,
+    super.name,
+  });
+
+  @override
+  InterfaceStructure clone({String? name}) => InterfaceStructure(
+        elements.map((e) => e.clone(name: e.name)),
+        interfaceTypeName: interfaceTypeName,
+        name: name ?? this.name,
+      );
+}