Module services api

CHANGELOG.md

@@ -1,3 +1,23 @@
+## Next Release
+
+- Added the `ModuleService` API for module-scoped generation, capture, and
+  inspection services. `ModuleServices` registers and looks up services for a
+  built module hierarchy, and `hierarchyJson` exposes its hierarchy as JSON.
+- Added `ArtifactProducingService` and `ModuleServiceArtifact` for
+  transport-neutral output. Artifact-producing services default
+  `outputDirectory` to the current directory and `outputBaseName` to the
+  module definition name, and expose named, media-typed byte streams without
+  requiring filesystem output.
+- Added `SystemVerilogService` for configured SystemVerilog synthesis,
+  in-memory source output, artifact inspection, and explicit directory writes.
+  Added `WaveformService` for in-memory waveform capture with optional file
+  writing through `writeToFile`.
+- Added legacy-compatible `Module.dumpSystemVerilog` and `Module.dumpWaves`
+  convenience methods. `dumpSystemVerilog()` returns simple in-memory output;
+  `dumpWaves()` provides standard VCD capture as the replacement for
+  `WaveDumper`. `WaveDumper` and `generateSynth` are deprecated in favor of
+  these `Module` methods.
+
 ## 0.6.10
 
 - Improved `Logic.replicate(1)` and same-width `signExtend` to return the original signal, eliminating redundant replication modules and generated SystemVerilog (<https://github.com/intel/rohd/pull/689>).

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Anyone interested in participating in ROHD is more than welcome to help!
 
 ## Code of Conduct
 
-ROHD adopts the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1 for the code of conduct. It can be accessed [here](CODE_OF_CONDUCT.md).
+ROHD adopts the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1 for the  [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Getting Help
 
@@ -124,7 +124,7 @@ Please include the SPDX tag near the top of any new files you create:
 Here is an example of a recommended file header template:
 
 ```dart
-// Copyright (C) 2021-2023 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // example.dart

benchmark/many_submodules_benchmark.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2024 Intel Corporation
+// Copyright (C) 2024-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // many_submodules_benchmark.dart
@@ -33,7 +33,7 @@ class ManySubmodulesBenchmark extends AsyncBenchmarkBase {
   Future<void> run() async {
     final dut = ManySubmodulesModule(Logic(), numSubModules: 10000);
     await dut.build();
-    dut.generateSynth();
+    dut.dumpSystemVerilog();
   }
 }
 

benchmark/wave_dump_benchmark.dart

@@ -1,4 +1,4 @@
-// Copyright (C) 2023 Intel Corporation
+// Copyright (C) 2023-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 //
 // wave_dump_benchmark.dart
@@ -56,7 +56,7 @@ class WaveDumpBenchmark extends AsyncBenchmarkBase {
     _mod = _ModuleToDump(Logic(), _clk);
     await _mod.build();
 
-    WaveDumper(_mod, outputPath: _vcdTemporaryPath);
+    _mod.dumpWaves(outputPath: _vcdTemporaryPath);
 
     await Simulator.run();
 

doc/tutorials/chapter_1/01_setup_installation.md

@@ -162,7 +162,7 @@ Future<void> main({bool noPrint = false}) async {
 
   // Let's see what this module looks like as SystemVerilog, so we can pass it
   // to other tools.
-  final systemVerilogCode = counter.generateSynth();
+  final systemVerilogCode = counter.dumpSystemVerilog().output;
   if (!noPrint) {
     print(systemVerilogCode);
   }
@@ -175,7 +175,7 @@ Future<void> main({bool noPrint = false}) async {
 
   // Attach a waveform dumper so we can see what happens.
   if (!noPrint) {
-    WaveDumper(counter);
+    counter.dumpWaves();
   }
 
   // Drop reset at time 25.

doc/tutorials/chapter_2/helper.dart

@@ -13,7 +13,8 @@ import 'package:rohd/rohd.dart';
 
 Future<void> displaySystemVerilog(Module mod) async {
   await mod.build();
-  print('\nYour System Verilog Equivalent Code: \n ${mod.generateSynth()}');
+  print('\nYour System Verilog Equivalent Code: \n '
+      '${mod.dumpSystemVerilog()}');
 }
 
 class LogicInitialization extends Module {

doc/tutorials/chapter_3/answers/exercise_sv.dart

@@ -33,7 +33,7 @@ void main() async {
   await fSub.build();
 
   // ignore: avoid_print - tutorial
-  print(fSub.generateSynth());
+  print(fSub.dumpSystemVerilog());
 
   test('should return 0 when a and b equal 1', () {
     a.put(1);

doc/tutorials/chapter_3/full_adder.dart

@@ -76,5 +76,5 @@ void main() async {
   final mod = FullAdderModule(a, b, cIn, faOps);
   await mod.build();
 
-  print(mod.generateSynth());
+  print(mod.dumpSystemVerilog());
 }

doc/tutorials/chapter_4/answers/exercise_1_sv.dart

@@ -10,7 +10,7 @@ void main() async {
   final mod = NBitAdder(a, b);
   await mod.build();
 
-  print(mod.generateSynth());
+  print(mod.dumpSystemVerilog());
 
   test('should return 255 when both inputs are added', () {
     a.put(127);

doc/tutorials/chapter_4/answers/exercise_2_sv.dart

@@ -9,7 +9,7 @@ void main() async {
 
   final mod = NBitSubtractor(a, b);
   await mod.build();
-  print(mod.generateSynth());
+  print(mod.dumpSystemVerilog());
 
   test('should return 5 when a is 25 and b is 20', () {
     a.put(25);

doc/tutorials/chapter_4/basic_generation_sv.dart

@@ -78,7 +78,7 @@ void main() async {
 
   await nbitAdder.build();
 
-  print(nbitAdder.generateSynth());
+  print(nbitAdder.dumpSystemVerilog());
 
   test('should return 10 when both inputs are 5.', () {
     a.put(5);

doc/tutorials/chapter_5/00_basic_modules.md

@@ -95,7 +95,7 @@ Do note that the `build()` method returns a `Future<void>`, not just `void`. Thi
 
 ## Converting ROHD Module to System Verilog RTL
 
-Next, we can see how extending your `Logic` to `Module` enables the generation of system Verilog code. Building on the previous example, we've made some slight modifications by adding `simModule.build()` and `simModule.generateSynth()`.
+Next, we can see how extending your `Logic` to `Module` enables the generation of system Verilog code. Building on the previous example, we've made some slight modifications by adding `simModule.build()` and `simModule.dumpSystemVerilog().output`.
 
 ```dart
 void main() async {
@@ -106,15 +106,16 @@ void main() async {
     await simModule.build();
 
     // Print out system verilog code
-    print(simModule.generateSynth());
+    print(simModule.dumpSystemVerilog().output);
 
     test('should return input value.',
           () => expect(simModule.out.value.toInt(), equals(1)));
 
     // Add this to test on generate system verilog code
     test(
           'should generate system verilog code.',
-        () => expect(simModule.generateSynth(), contains('module SimpleModule(')));
+        () => expect(simModule.dumpSystemVerilog().output,
+          contains('module SimpleModule(')));
 }
 ```
 

doc/tutorials/chapter_5/answers/full_adder.dart

@@ -49,7 +49,7 @@ void main() async {
   final mod = FullAdder(a: a, b: b, carryIn: cIn);
   await mod.build();
 
-  print(mod.generateSynth());
+  print(mod.dumpSystemVerilog());
 
   test('should return true if result sum similar to truth table.', () {
     for (var i = 0; i <= 1; i++) {

doc/tutorials/chapter_5/answers/full_subtractor.dart

@@ -44,7 +44,7 @@ Future<void> main() async {
 
   await diff.build();
 
-  print(diff.generateSynth());
+  print(diff.dumpSystemVerilog());
 
   test('should return true if results matched truth table', () {
     for (var i = 0; i <= 1; i++) {

doc/tutorials/chapter_5/answers/n_bit_subtractor.dart

@@ -36,7 +36,7 @@ Future<void> main() async {
   final mod = NBitFullSubtractor(a, b);
   await mod.build();
 
-  print(mod.generateSynth());
+  print(mod.dumpSystemVerilog());
 
   test('should return 1 when a is 8 and b is 7.', () {
     a.put(8);

doc/tutorials/chapter_5/n_bit_adder.dart

@@ -79,7 +79,7 @@ void main() async {
 
   await nbitAdder.build();
 
-  // print(nbitAdder.generateSynth());
+  // print(nbitAdder.dumpSystemVerilog());
 
   test('should return 20 when A and B perform add.', () {
     a.put(15);

doc/tutorials/chapter_7/00_sequential_logic.md

@@ -5,7 +5,7 @@
 - [Shift Register](#shift-register)
 - [ROHD Simulator](#rohd-simulator)
 - [Unit Test in Sequential Logic](#unit-test-in-sequential-logic)
-- [Wave Dumper](#wave-dumper)
+- [Waveform Dumping](#waveform-dumping)
 - [Exercise](#exercise)
 
 ## Learning Outcome
@@ -44,7 +44,7 @@ class ShiftRegister extends Module {
 void main() async {
   final shiftReg = ShiftRegister();
   await shiftReg.build();
-  print(shiftReg.generateSynth());
+  print(shiftReg.dumpSystemVerilog().output);
 }
 ```
 
@@ -196,7 +196,7 @@ void main() async {
 
   final shiftReg = ShiftRegister(clk, reset, sin);
   await shiftReg.build();
-  print(shiftReg.generateSynth());
+  print(shiftReg.dumpSystemVerilog().output);
 
   // Inject 1 to reset and 0 to shift in
   reset.inject(1);
@@ -217,9 +217,9 @@ void main() async {
 }
 ```
 
-## Wave Dumper
+## Waveform Dumping
 
-Let also add `WaveDumper` to view the waveform of the Simulation results.
+Let also call `dumpWaves` to view the waveform of the Simulation results.
 
 ```dart
 void main() async {
@@ -242,8 +242,8 @@ void main() async {
   // Run the simulator but don't wait for it
   unawaited(Simulator.run());
 
-  // Output the simulation waveform using WaveDumper
-  WaveDumper(shiftReg,
+  // Output the simulation waveform
+  shiftReg.dumpWaves(
         outputPath: 'doc/tutorials/chapter_7/shift_register.vcd');
 }
 ```
@@ -252,7 +252,7 @@ Now, let print the flop before the first clock Positive edge. We can just call t
 
 ```dart
 ...
-WaveDumper(shiftReg,
+shiftReg.dumpWaves(
         outputPath: 'doc/tutorials/chapter_7/shift_register.vcd');
 printFlop('Before');
 ```

doc/tutorials/chapter_7/answers/exercise_1_d_flip_flop.dart

@@ -44,7 +44,7 @@ Future<void> main() async {
     final dff = DFlipFlop(data, reset, clk);
     await dff.build();
 
-    print(dff.generateSynth());
+    print(dff.dumpSystemVerilog());
 
     data.inject(1);
     reset.inject(1);
@@ -60,7 +60,7 @@ Future<void> main() async {
 
     unawaited(Simulator.run());
 
-    WaveDumper(dff,
+    dff.dumpWaves(
         outputPath: 'doc/tutorials/chapter_7/answers/d_flip_flop.vcd');
 
     printFlop('Before');

doc/tutorials/chapter_7/shift_register.dart

@@ -69,7 +69,7 @@ void main() {
     // kick-off the simulator, but we don't want to wait
     unawaited(Simulator.run());
 
-    WaveDumper(shiftReg,
+    shiftReg.dumpWaves(
         outputPath: 'doc/tutorials/chapter_7/shift_register.vcd');
 
     printFlop('Before');

doc/tutorials/chapter_8/01_interface.md

@@ -168,9 +168,9 @@ Future<void> main() async {
   counterInterface.en.inject(0);
   counterInterface.reset.inject(1);
 
-  print(counter.generateSynth());
+  print(counter.dumpSystemVerilog().output);
 
-  WaveDumper(counter,
+  counter.dumpWaves(
       outputPath: 'doc/tutorials/chapter_8/counter_interface.vcd');
   Simulator.registerAction(25, () {
     counterInterface.en.put(1);

doc/tutorials/chapter_8/02_finite_state_machine.md

@@ -268,11 +268,11 @@ await oven.build();
 reset.inject(1);
 ```
 
-Let also attach a `WaveDumper` to preview what is the waveform and what happened during the Simulation.
+Let also call `dumpWaves` to preview the waveform and what happened during the Simulation.
 
 ```dart
 if (!noPrint) {
-  WaveDumper(oven, outputPath: 'oven.vcd');
+  oven.dumpWaves(outputPath: 'oven.vcd');
 }
 ```
 

doc/tutorials/chapter_8/03_pipeline.md

@@ -282,7 +282,7 @@ void main() async {
   reset.inject(1);
 
   // Attach a waveform dumper so we can see what happens.
-  WaveDumper(csm, outputPath: 'csm.vcd');
+  csm.dumpWaves(outputPath: 'csm.vcd');
 
   Simulator.registerAction(10, () {
     reset.inject(0);

doc/tutorials/chapter_8/answers/exercise_1_spi.dart

@@ -139,7 +139,7 @@ void main() async {
 
   await tb.build();
 
-  print(tb.generateSynth());
+  print(tb.dumpSystemVerilog());
 
   testInterface.cs.inject(0);
   testInterface.sdi.inject(0);
@@ -163,7 +163,7 @@ void main() async {
   Simulator.setMaxSimTime(100);
   unawaited(Simulator.run());
 
-  WaveDumper(peri, outputPath: 'doc/tutorials/chapter_8/spi-new.vcd');
+  peri.dumpWaves(outputPath: 'doc/tutorials/chapter_8/spi-new.vcd');
 
   await drive(LogicValue.ofString('01010101'));
 }

doc/tutorials/chapter_8/answers/exercise_2_toycapsule_fsm.dart

@@ -49,13 +49,13 @@ Future<void> main(List<String> args) async {
   final toyCap = ToyCapsuleFSM(clk, reset, dispenseBtn, coin);
   await toyCap.build();
 
-  print(toyCap.generateSynth());
+  print(toyCap.dumpSystemVerilog());
 
   toyCap.toyCapsuleStateMachine.generateDiagram();
 
   reset.inject(1);
 
-  WaveDumper(toyCap, outputPath: 'toyCapsuleFSM.vcd');
+  toyCap.dumpWaves(outputPath: 'toyCapsuleFSM.vcd');
 
   Simulator.setMaxSimTime(100);
   Simulator.registerAction(25, () {

doc/tutorials/chapter_8/answers/exercise_3_pipeline.dart

@@ -34,14 +34,14 @@ void main(List<String> args) {
     final pipe = Pipeline4Stages(clk, reset, a);
     await pipe.build();
 
-    // print(pipe.generateSynth());
+    // print(pipe.dumpSystemVerilog());
 
     a.inject(5);
     reset.inject(1);
 
     Simulator.registerAction(10, () => reset.put(0));
 
-    WaveDumper(pipe, outputPath: 'answer_1.vcd');
+    pipe.dumpWaves(outputPath: 'answer_1.vcd');
 
     Simulator.registerAction(50, () {
       // stage 4 / result: 30 + (30 * 3) = 120

doc/tutorials/chapter_8/carry_save_multiplier.dart

@@ -108,7 +108,7 @@ void main() async {
   reset.inject(1);
 
   // Attach a waveform dumper so we can see what happens.
-  WaveDumper(csm, outputPath: 'csm.vcd');
+  csm.dumpWaves(outputPath: 'csm.vcd');
 
   Simulator.registerAction(10, () {
     reset.inject(0);

doc/tutorials/chapter_8/counter_interface.dart

@@ -63,9 +63,9 @@ Future<void> main() async {
 
   await counter.build();
 
-  print(counter.generateSynth());
+  print(counter.dumpSystemVerilog());
 
-  WaveDumper(counter,
+  counter.dumpWaves(
       outputPath: 'doc/tutorials/chapter_8/counter_interface.vcd');
   Simulator.registerAction(25, () {
     intf.en.put(1);