Repository: intel/rohd (dart)

Issue:
Rename `ExternalSystemVerilogModule`'s argument from `topModuleName` to `definitionName`
## Motivation
It's confusing to call it `topModuleName` since it's not really a "top", and its inconsistent with `definitionName` used on all other `Module`s.

## Desired solution
Rename it from `topModuleName` to `definitionName`.  This does break backwards compatibility, unfortunately.

Pull request:
<!-- Please make sure you check out the contribution guidelines before submitting a pull request! -->

## Description & Motivation

It's inconsistent and confusing to call it `topModuleName`, so rename it to `definitionName`.

## Related Issue(s)

Fix #169

## Testing

Existing tests pass

## Backwards-compatibility

> Is this a breaking change that will not be backwards-compatible?  If yes, how so?

*Yes!*  This is an API change.  Users will need to change the name of the parameter used.

## Documentation

> Does the change require any updates to documentation?  If so, where?  Are they included?

Yes, updated API docs and README.

Patch:
diff --git a/README.md b/README.md
index 3b913f5f2..27b0c92f3 100644
--- a/README.md
+++ b/README.md
@@ -713,7 +713,7 @@ The ROHD simulator is a static class accessible as [`Simulator`](https://intel.g
 
 ## Instantiation of External Modules
 
-ROHD can instantiate external SystemVerilog modules.  The [`ExternalSystemVerilogModule`](https://intel.github.io/rohd/rohd/ExternalSystemVerilogModule-class.html) constructor requires the top level SystemVerilog module name.  When ROHD generates SystemVerilog for a model containing an `ExternalSystemVerilogModule`, it will instantiate instances of the specified `topModuleName`.  This is useful for integration related activities.
+ROHD can instantiate external SystemVerilog modules.  The [`ExternalSystemVerilogModule`](https://intel.github.io/rohd/rohd/ExternalSystemVerilogModule-class.html) constructor requires the top level SystemVerilog module name.  When ROHD generates SystemVerilog for a model containing an `ExternalSystemVerilogModule`, it will instantiate instances of the specified `definitionName`.  This is useful for integration related activities.
 
 There is an upcoming package for SystemVerilog cosimulation with ROHD which adds cosimulation capabilities to an `ExternalSystemVerilogModule` planned for release soon.
 
diff --git a/lib/src/external.dart b/lib/src/external.dart
index e2a408a91..0be7de7b6 100644
--- a/lib/src/external.dart
+++ b/lib/src/external.dart
@@ -18,29 +18,26 @@ import 'package:rohd/rohd.dart';
 /// as extend functionality with behavioral models or cosimulation.
 abstract class ExternalSystemVerilogModule extends Module
     with CustomSystemVerilog {
-  /// The name of the top SystemVerilog module.
-  final String topModuleName;
-
   /// A map of parameter names and values to be passed to the SystemVerilog
   /// module.
   final Map<String, String>? parameters;
 
   /// Constructs an instance of an externally defined SystemVerilog module.
   ///
-  /// The name of the SystemVerilog module should match [topModuleName] exactly.
-  /// The [name] will be the instance name when referred to in generated
-  /// SystemVerilog.
-  ExternalSystemVerilogModule(
-      {required this.topModuleName,
-      this.parameters,
-      super.name = 'external_module'})
-      : super(definitionName: topModuleName, reserveDefinitionName: true);
+  /// The name of the SystemVerilog module should match [definitionName]
+  /// exactly. The [name] will be the instance name when referred to in
+  /// generated SystemVerilog.
+  ExternalSystemVerilogModule({
+    required String definitionName,
+    this.parameters,
+    super.name = 'external_module',
+  }) : super(definitionName: definitionName, reserveDefinitionName: true);
 
   @override
   String instantiationVerilog(String instanceType, String instanceName,
           Map<String, String> inputs, Map<String, String> outputs) =>
       SystemVerilogSynthesizer.instantiationVerilogWithParameters(
-          this, topModuleName, instanceName, inputs, outputs,
+          this, definitionName, instanceName, inputs, outputs,
           parameters: parameters, forceStandardInstantiation: true);
 }
 


Test patch:
diff --git a/test/external_test.dart b/test/external_test.dart
index 8ab0ececf..85f18d49a 100644
--- a/test/external_test.dart
+++ b/test/external_test.dart
@@ -14,7 +14,7 @@ import 'package:test/test.dart';
 class MyExternalModule extends ExternalSystemVerilogModule {
   MyExternalModule(Logic a, {int width = 2})
       : super(
-            topModuleName: 'external_module_name',
+            definitionName: 'external_module_name',
             parameters: {'WIDTH': '$width'}) {
     addInput('a', a, width: width);
     addOutput('b', width: width);