Add support for in/out ports (#46)

Author: mkorbel1

README.md

@@ -31,6 +31,8 @@ pip install cocotb
 
 You will also need your favorite SystemVerilog simulator to do cosimulation between ROHD and SystemVerilog modules.  ROHD Cosim does *not* do any SystemVerilog parsing or SystemVerilog simulation itself.
 
+See the section on [support and limitations](#support--limitations) for more details on simulators, versions, limitations, etc.
+
 ## Using ROHD Cosim
 
 There are two steps to using ROHD Cosim:
@@ -153,6 +155,16 @@ The diagram below shows how the port configuration connects to your simulation.
 
 ![Port Config Diagram](https://github.com/intel/rohd-cosim/raw/main/doc/diagrams/port.png)
 
+## Support & Limitations
+
+ROHD Cosim depends on cross-compatibility with SystemVerilog simulators and the libraries from cocotb that enable VPI-based communication between them. Because of this, there are some limitations which may be version and simulator specific, as well as some fundamental limitations that have to do with the communication mechanisms.
+
+- The simulation must occur over time.  That is, it is not possible to have a "purely combinational" block of logic, change an input, and view an instantaneous output change, as you normally can with ROHD modules.  This is because coordination between the ROHD simulation and the SystemVerilog simulator is coordinated by `Simulator` phasing.  Therefore, changes on the output of a SystemVerilog cosimulated module will not update until some time has passed.
+- ROHD Cosim can support simulators supported by cocotb, but has only been tested with those officially listed in the [`SystemVerilogSimulator` enum](https://intel.github.io/rohd-cosim/rohd_cosim/SystemVerilogSimulator.html).
+- Cross-version compatibility between ROHD Cosim, cocotb, and SystemVerilog simulators can, unfortunatley, be delicate.  Check the [simulator support documentation from cocotb](https://docs.cocotb.org/en/stable/simulator_support.html) for more details about which versions of which simulators will work well with which versions of cocotb (and thus ROHD Cosim).
+- Different SystemVerilog simulators have different limitations and capabilities, and thus those features would be limited in cosimulation as well. For example, Verilator does not support X/Z values.
+- In/Out ports and bidirectional wires are supported in ROHD Cosim, as they are in ROHD, however contention may not be calculated at these port boundaries in a realistic way. This has to do with how ROHD Cosim sends and receives updates with the SystemVerilog simulator. If the SystemVerilog simulator resolves a value or contention on an inout port, it may not be possible for ROHD to determine whether the contention can/should break, for example.
+
 ----------------
 2022 September 9  
 Author: Max Korbel <<[email protected]>>

lib/src/configs/cosim_port_config.dart

@@ -34,14 +34,13 @@ class CosimPortConfig extends CosimConfig {
   Future<CosimConnection> connect() async {
     // ignore: close_sinks
     final socket = await Socket.connect(InternetAddress.loopbackIPv4, port)
-        // ignore: avoid_types_on_closure_parameters
         .catchError((Object error, StackTrace stackTrace) {
       print('Caught exception during socket connection: $error');
       print('> Stack trace:\n$stackTrace');
       // ignore: only_throw_errors
       throw error;
     });
-    // ignore: avoid_types_on_closure_parameters
+
     socket.handleError((Object error, StackTrace stackTrace) {
       print('Caught exception from socket via port configuration: $error');
       print('> Stack trace:\n$stackTrace');

lib/src/configs/cosim_wrap_config.dart

@@ -24,6 +24,7 @@ enum SystemVerilogSimulator {
   /// Known limitations to be aware of:
   /// - Verilator does not support invalid (`x`, `z`) values in the simulation.
   /// - Support for unpacked array ports is limited.
+  /// - Support for inout connections is limited.
   verilator,
 }
 
@@ -145,6 +146,7 @@ class CosimWrapConfig extends CosimProcessConfig {
                 {
                   ...registreeEntry.value.inputs,
                   ...registreeEntry.value.outputs,
+                  ...registreeEntry.value.inOuts,
                 }.map((key, value) => MapEntry(key, '')),
               )),
       if (dumpWavesString != null) dumpWavesString,

lib/src/cosim.dart

@@ -192,7 +192,6 @@ mixin Cosim on ExternalSystemVerilogModule {
     _socket = connection.socket;
 
     // catch errors if the socket shuts down
-    // ignore: avoid_types_on_closure_parameters
     unawaited(_socket!.done.catchError((Object error) {
       logger?.info('Encountered error upon socket completion, '
           'shutting down cosim: $error');
@@ -208,7 +207,6 @@ mixin Cosim on ExternalSystemVerilogModule {
         endCosim();
       },
       cancelOnError: true,
-      // ignore: avoid_types_on_closure_parameters
       onError: (Object err, StackTrace stackTrace) {
         logger?.info(
             'Encountered error while listening to socket, ending cosim: $err');
@@ -302,6 +300,28 @@ mixin Cosim on ExternalSystemVerilogModule {
   /// Keeps track of whether we need to do an update post-tick.
   bool _pendingPostUpdate = false;
 
+  /// A mapping from [inOut]s to a "received" driver of them, so that it can
+  /// calculate if contention has occurred.
+  final Map<Logic, Logic> _inoutToReceivedInOutDriverMap = {};
+
+  /// Returns the driver of an [inOut] to be driven by "received" updates.
+  Logic _inoutReceivedDriver(String inoutName) {
+    final io = inOut(inoutName);
+    if (!_inoutToReceivedInOutDriverMap.containsKey(io)) {
+      final driverName = 'ioDriverOf_$inoutName';
+      final driver = io is LogicArray
+          ? LogicArray(
+              name: driverName,
+              io.dimensions,
+              io.elementWidth,
+              numUnpackedDimensions: io.numUnpackedDimensions)
+          : Logic(name: driverName, width: io.width);
+      _inoutToReceivedInOutDriverMap[io] = driver;
+      io <= driver;
+    }
+    return _inoutToReceivedInOutDriverMap[io]!;
+  }
+
   /// Sets up listeners on ports in both directions with cosimulation for
   /// all [_registrees].
   static Future<void> _setupPortHandshakes({
@@ -323,19 +343,24 @@ mixin Cosim on ExternalSystemVerilogModule {
             ' drive this signal: "${event.signalName}"');
       }
 
-      // handle case where there was an unpacked array (should end with ']')
+      /// Gets a output or else an inout.
+      Logic getPort(String name) =>
+          _registrees[registreeName]!.tryOutput(name) ??
+          _registrees[registreeName]!._inoutReceivedDriver(name);
+
       if (portName.endsWith(']')) {
+        // handle case where there was an unpacked array (should end with ']')
         final splitPortName = portName.split(RegExp(r'[\[\]]'));
         final arrayName = splitPortName[0];
         final arrayIndex = int.parse(splitPortName[1]);
-        (_registrees[registreeName]!.output(arrayName) as LogicArray)
+        (getPort(arrayName) as LogicArray)
             .flattenedUnpacked
             .toList()[arrayIndex]
             // ignore: unnecessary_null_checks
             .put(event.signalValue!);
       } else {
         // ignore: unnecessary_null_checks
-        _registrees[registreeName]!.output(portName).put(event.signalValue!);
+        getPort(portName).put(event.signalValue!);
       }
     });
 
@@ -357,7 +382,10 @@ mixin Cosim on ExternalSystemVerilogModule {
 
     for (final registree in _registrees.values) {
       // listen to every input of this module
-      for (final modInput in registree.inputs.values) {
+      for (final modInput in [
+        ...registree.inputs.values,
+        ...registree.inOuts.values
+      ]) {
         if (modInput.width == 0) {
           // no need to listen to 0-bit signals, they won't be changing
           // (and won't exist in SV)
@@ -568,7 +596,10 @@ async def setup_connections(dut, connector : rohd_connector.RohdConnector):
         cocoTbHier += '.${registree.cosimHierarchy}';
       }
 
-      for (final outputEntry in registree.outputs.entries) {
+      for (final outputEntry in [
+        ...registree.outputs.entries,
+        ...registree.inOuts.entries
+      ]) {
         final outputName = outputEntry.key;
         final outputLogic = outputEntry.value;
         if (outputLogic.width == 0) {
@@ -592,7 +623,10 @@ async def setup_connections(dut, connector : rohd_connector.RohdConnector):
               '))\n');
         }
       }
-      for (final inputEntry in registree.inputs.entries) {
+      for (final inputEntry in [
+        ...registree.inputs.entries,
+        ...registree.inOuts.entries
+      ]) {
         final inputName = inputEntry.key;
         final inputLogic = inputEntry.value;
         if (inputLogic.width == 0) {

pubspec.yaml

@@ -19,3 +19,4 @@ dependencies:
 dev_dependencies:
   args: ^2.3.1
   test: ^1.17.3
+

test/cosim_mod_inout.sv

@@ -0,0 +1,22 @@
+// Copyright (C) 2025 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// cosim_mod_inout.sv
+// A simple SystemVerilog module for testing combinational cosimulation with inout ports.
+//
+// 2025 January
+// Author: Max Korbel <[email protected]>
+
+// A special module for connecting two nets bidirectionally
+module net_connect #(parameter WIDTH=1) (w, w); 
+    inout wire[WIDTH-1:0] w;
+endmodule
+
+module my_cosim_test_module_nets(
+    inout wire a,
+    inout wire b
+);
+
+net_connect net_connect(a, b);
+
+endmodule

test/cosim_test.dart

@@ -69,6 +69,28 @@ class DoubleCosimModuleTop extends Module {
   }
 }
 
+class ExampleTopModuleWithInouts extends Module {
+  late final ExampleCosimModuleInOut ecm;
+
+  ExampleTopModuleWithInouts(LogicNet a, LogicNet b) {
+    a = addInOut('a', a);
+    b = addInOut('b', b);
+
+    ecm = ExampleCosimModuleInOut(a, b);
+  }
+}
+
+class ExampleCosimModuleInOut extends ExternalSystemVerilogModule with Cosim {
+  @override
+  List<String> get verilogSources => ['../../test/cosim_mod_inout.sv'];
+
+  ExampleCosimModuleInOut(LogicNet a, LogicNet b)
+      : super(definitionName: 'my_cosim_test_module_nets') {
+    addInOut('a', a);
+    addInOut('b', b);
+  }
+}
+
 Future<void> main() async {
   tearDown(() async {
     await Simulator.reset();
@@ -99,6 +121,92 @@ Future<void> main() async {
       await Simulator.run();
     });
 
+    if (sim != SystemVerilogSimulator.verilator) {
+      // verilator does not support inout connections: https://github.com/verilator/verilator/issues/2844
+
+      group('inout', () {
+        test('simple push and check with inout', () async {
+          final a = LogicNet();
+          final b = LogicNet();
+          final mod = ExampleTopModuleWithInouts(a, b);
+          await mod.build();
+
+          await CosimTestingInfrastructure.connectCosim(
+              'simple_push_n_check_with_inout',
+              systemVerilogSimulator: sim);
+
+          // in the a -> b direction
+          Simulator.registerAction(2, () {
+            a.put(1);
+          });
+          Simulator.registerAction(3, () {
+            expect(b.value, equals(LogicValue.one));
+          });
+          Simulator.registerAction(4, () {
+            a.put(0);
+          });
+          Simulator.registerAction(5, () {
+            expect(b.value, equals(LogicValue.zero));
+          });
+
+          // break contention
+          Simulator.registerAction(6, () {
+            a.put(LogicValue.z);
+          });
+
+          // in the b -> a direction
+          Simulator.registerAction(7, () {
+            b.put(1);
+          });
+          Simulator.registerAction(9, () {
+            expect(a.value, equals(LogicValue.one));
+          });
+          Simulator.registerAction(10, () {
+            b.put(0);
+          });
+          Simulator.registerAction(11, () {
+            expect(a.value, equals(LogicValue.zero));
+          });
+
+          await Simulator.run();
+        });
+
+        test('simple push and check with inout contention', () async {
+          final a = Logic();
+          final b = Logic();
+          final mod = ExampleTopModuleWithInouts(
+              LogicNet()..gets(a), LogicNet()..gets(b));
+          await mod.build();
+
+          await CosimTestingInfrastructure.connectCosim(
+              'simple_push_n_check_with_inout_contention',
+              systemVerilogSimulator: sim);
+
+          // in the a -> b direction
+          Simulator.registerAction(2, () {
+            a.put(1);
+          });
+          Simulator.registerAction(3, () {
+            expect(mod.inOut('a').value, equals(LogicValue.one));
+            expect(mod.inOut('b').value, equals(LogicValue.one));
+          });
+
+          // contention
+          Simulator.registerAction(6, () {
+            b.put(0);
+          });
+          Simulator.registerAction(7, () {
+            expect(mod.inOut('a').value, equals(LogicValue.x));
+            expect(mod.inOut('b').value, equals(LogicValue.x));
+          });
+
+          // breaking contention doesn't work, so we're done...
+
+          await Simulator.run();
+        });
+      });
+    }
+
     test('comb latency', () async {
       final a = Logic();
       final mod = ExampleTopModule(a);

test/port_stuff/port_launch.dart

@@ -65,7 +65,6 @@ Future<void> runCosim(int port,
   final mod = BottomMod(a);
   await mod.build();
 
-  // ignore: dead_code
   if (enableLogging) {
     Logger.root.level = Level.ALL;
     Logger.root.onRecord.listen(print);

test/port_test.dart

@@ -80,7 +80,7 @@ void main() async {
     final stdoutBuffer = StringBuffer();
     unawaited(proc.stdout.transform(utf8.decoder).forEach((msg) {
       stdoutBuffer.write(msg);
-      // ignore: dead_code
+
       if (enableLogging) {
         print(msg);
       }