Driving and receiving of hierarchical PairInterfaces (#628)

Author: mkorbel1

.github/configs/mlc_config.json

@@ -14,6 +14,9 @@
     },
     {
       "pattern":"^https://www.nandland.com"
+    },
+    {
+      "pattern":"^https://.*\\.fandom\\.com"
     }
   ]
 }

lib/src/interfaces/pair_interface.dart

@@ -289,6 +289,128 @@ class PairInterface extends Interface<PairDirection> {
     return subInterface;
   }
 
+  /// Makes `this` drive interface signals tagged with [tags] on [other].
+  ///
+  /// In addition to the base [Interface.driveOther] functionality, this also
+  /// handles driving signals on all [subInterfaces] hierarchically when [other]
+  /// is a [PairInterface], considering `reverse`.
+  @override
+  void driveOther(
+      Interface<PairDirection> other, Iterable<PairDirection> tags) {
+    super.driveOther(other, tags);
+
+    if (other is PairInterface) {
+      subInterfaces.forEach((subIntfName, subInterface) {
+        if (!other.subInterfaces.containsKey(subIntfName)) {
+          throw InterfaceTypeException(
+              other, 'missing a sub-interface named $subIntfName');
+        }
+
+        if (_subInterfaces[subIntfName]!.reverse) {
+          subInterface.receiveOther(other.subInterfaces[subIntfName]!, tags);
+        } else {
+          subInterface.driveOther(other.subInterfaces[subIntfName]!, tags);
+        }
+      });
+    }
+  }
+
+  /// Makes `this` signals tagged with [tags] be driven by [other].
+  ///
+  /// In addition to the base [Interface.receiveOther] functionality, this also
+  /// handles receiving signals from all [subInterfaces] hierarchically when
+  /// [other] is a [PairInterface], considering `reverse`.
+  @override
+  void receiveOther(
+      Interface<PairDirection> other, Iterable<PairDirection> tags) {
+    super.receiveOther(other, tags);
+
+    if (other is PairInterface) {
+      subInterfaces.forEach((subIntfName, subInterface) {
+        if (!other.subInterfaces.containsKey(subIntfName)) {
+          throw InterfaceTypeException(
+              other, 'missing a sub-interface named $subIntfName');
+        }
+
+        if (_subInterfaces[subIntfName]!.reverse) {
+          subInterface.driveOther(other.subInterfaces[subIntfName]!, tags);
+        } else {
+          subInterface.receiveOther(other.subInterfaces[subIntfName]!, tags);
+        }
+      });
+    }
+  }
+
+  /// Makes `this` conditionally drive interface signals tagged with [tags] on
+  /// [other].
+  ///
+  /// In addition to the base [Interface.conditionalDriveOther] functionality,
+  /// this also handles conditional driving of signals on all [subInterfaces]
+  /// hierarchically when [other] is a [PairInterface]. Returns a
+  /// [ConditionalGroup] that combines all conditionals from the main interface
+  /// and sub-interfaces, considering `reverse`.
+  @override
+  Conditional conditionalDriveOther(
+      Interface<PairDirection> other, Iterable<PairDirection> tags) {
+    final conditionals = <Conditional>[
+      super.conditionalDriveOther(other, tags)
+    ];
+
+    if (other is PairInterface) {
+      subInterfaces.forEach((subIntfName, subInterface) {
+        if (!other.subInterfaces.containsKey(subIntfName)) {
+          throw InterfaceTypeException(
+              other, 'missing a sub-interface named $subIntfName');
+        }
+
+        if (_subInterfaces[subIntfName]!.reverse) {
+          conditionals.add(subInterface.conditionalReceiveOther(
+              other.subInterfaces[subIntfName]!, tags));
+        } else {
+          conditionals.add(subInterface.conditionalDriveOther(
+              other.subInterfaces[subIntfName]!, tags));
+        }
+      });
+    }
+
+    return ConditionalGroup(conditionals);
+  }
+
+  /// Makes `this` signals tagged with [tags] be driven conditionally by
+  /// [other].
+  ///
+  /// In addition to the base [Interface.conditionalReceiveOther] functionality,
+  /// this also handles conditional receiving of signals from all
+  /// [subInterfaces] hierarchically when [other] is a [PairInterface]. Returns
+  /// a [ConditionalGroup] that combines all conditionals from the main
+  /// interface and sub-interfaces, considering `reverse`.
+  @override
+  Conditional conditionalReceiveOther(
+      Interface<PairDirection> other, Iterable<PairDirection> tags) {
+    final conditionals = <Conditional>[
+      super.conditionalReceiveOther(other, tags)
+    ];
+
+    if (other is PairInterface) {
+      subInterfaces.forEach((subIntfName, subInterface) {
+        if (!other.subInterfaces.containsKey(subIntfName)) {
+          throw InterfaceTypeException(
+              other, 'missing a sub-interface named $subIntfName');
+        }
+
+        if (_subInterfaces[subIntfName]!.reverse) {
+          conditionals.add(subInterface.conditionalDriveOther(
+              other.subInterfaces[subIntfName]!, tags));
+        } else {
+          conditionals.add(subInterface.conditionalReceiveOther(
+              other.subInterfaces[subIntfName]!, tags));
+        }
+      });
+    }
+
+    return ConditionalGroup(conditionals);
+  }
+
   @override
   @mustBeOverridden
   // ignore: deprecated_member_use_from_same_package

test/pair_interface_test.dart

@@ -37,6 +37,42 @@ class SimpleInterface extends PairInterface {
   SimpleInterface clone() => SimpleInterface();
 }
 
+class SubInterface extends PairInterface {
+  Logic get subReq => port('sub_req');
+  Logic get subRsp => port('sub_rsp');
+
+  SubInterface()
+      : super(
+          portsFromConsumer: [Logic.port('sub_rsp', 8)],
+          portsFromProvider: [Logic.port('sub_req', 8)],
+        );
+
+  @override
+  SubInterface clone() => SubInterface();
+}
+
+class HierarchicalInterface extends PairInterface {
+  Logic get mainReq => port('main_req');
+  Logic get mainRsp => port('main_rsp');
+  SubInterface get sub1 => subInterfaces['sub1']! as SubInterface;
+  SubInterface get sub2 => subInterfaces['sub2']! as SubInterface;
+
+  HierarchicalInterface({bool excludeSubInterfaces = false})
+      : super(
+          portsFromProvider: [Logic.port('main_req', 8)],
+          portsFromConsumer: [Logic.port('main_rsp', 8)],
+        ) {
+    if (!excludeSubInterfaces) {
+      addSubInterface('sub1', SubInterface(), uniquify: (orig) => 'sub1_$orig');
+      addSubInterface('sub2', SubInterface(),
+          uniquify: (orig) => 'sub2_$orig', reverse: true);
+    }
+  }
+
+  @override
+  HierarchicalInterface clone() => HierarchicalInterface();
+}
+
 class SimpleProvider extends Module {
   late final SimpleInterface _intf;
   SimpleProvider(SimpleInterface intf) {
@@ -118,6 +154,34 @@ class PassthroughPairIntfModule extends Module {
   }
 }
 
+class SubInterfaceTestModule extends Module {
+  SubInterfaceTestModule(
+      HierarchicalInterface intf1, HierarchicalInterface intf2,
+      {required bool useConditional}) {
+    intf1 = addPairInterfacePorts(
+      intf1,
+      PairRole.consumer,
+      uniquify: (original) => 'intf1_$original',
+    );
+    intf2 = addPairInterfacePorts(
+      intf2,
+      PairRole.provider,
+      uniquify: (original) => 'intf2_$original',
+    );
+
+    if (useConditional) {
+      Combinational([
+        intf1.conditionalDriveOther(intf2, {PairDirection.fromProvider}),
+        intf1.conditionalReceiveOther(intf2, {PairDirection.fromConsumer}),
+      ]);
+    } else {
+      intf1
+        ..driveOther(intf2, {PairDirection.fromProvider})
+        ..receiveOther(intf2, {PairDirection.fromConsumer});
+    }
+  }
+}
+
 void main() {
   tearDown(() async {
     await Simulator.reset();
@@ -187,4 +251,62 @@ void main() {
       }
     }
   });
+
+  group('sub-interface drive and receive other', () {
+    for (final useConditional in [false, true]) {
+      test('with useConditional: $useConditional', () async {
+        final mod = SubInterfaceTestModule(
+          HierarchicalInterface(),
+          HierarchicalInterface(),
+          useConditional: useConditional,
+        );
+        await mod.build();
+
+        final vectors = [
+          Vector({
+            'intf1_main_req': 0x01,
+            'intf2_main_rsp': 0x12,
+            'intf1_sub1_sub_req': 0x23,
+            'intf2_sub1_sub_rsp': 0x34,
+            'intf1_sub2_sub_rsp': 0x45,
+            'intf2_sub2_sub_req': 0x56
+          }, {
+            'intf2_main_req': 0x01,
+            'intf1_main_rsp': 0x12,
+            'intf2_sub1_sub_req': 0x23,
+            'intf1_sub1_sub_rsp': 0x34,
+            'intf2_sub2_sub_rsp': 0x45,
+            'intf1_sub2_sub_req': 0x56
+          }),
+        ];
+
+        await SimCompare.checkFunctionalVector(mod, vectors);
+        SimCompare.checkIverilogVector(mod, vectors);
+      });
+    }
+  });
+
+  test('hierarchical interface creation and access', () {
+    final intf = HierarchicalInterface();
+
+    // Test that sub-interfaces were created properly
+    expect(intf.subInterfaces.containsKey('sub1'), isTrue);
+    expect(intf.subInterfaces.containsKey('sub2'), isTrue);
+    expect(intf.subInterfaces.length, equals(2));
+
+    // Test access to sub-interface ports
+    expect(intf.sub1.subReq.width, equals(8));
+    expect(intf.sub1.subRsp.width, equals(8));
+    expect(intf.sub2.subReq.width, equals(8));
+    expect(intf.sub2.subRsp.width, equals(8));
+  });
+
+  test('sub-interface missing error handling', () {
+    expect(
+      () => HierarchicalInterface().driveOther(
+          HierarchicalInterface(excludeSubInterfaces: true),
+          {PairDirection.fromProvider}),
+      throwsA(isA<InterfaceTypeException>()),
+    );
+  });
 }