Fst Writer

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. It can be accessed in the [ROHD Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Getting Help
 

benchmark/wave_dump_benchmark.dart

@@ -56,7 +56,7 @@ class WaveDumpBenchmark extends AsyncBenchmarkBase {
     _mod = _ModuleToDump(Logic(), _clk);
     await _mod.build();
 
-    WaveDumper(_mod, outputPath: _vcdTemporaryPath);
+    WaveformService(_mod, outputPath: _vcdTemporaryPath);
 
     await Simulator.run();
 

doc/tutorials/chapter_7/answers/exercise_1_d_flip_flop.dart

@@ -60,7 +60,7 @@ Future<void> main() async {
 
     unawaited(Simulator.run());
 
-    WaveDumper(dff,
+    WaveformService(dff,
         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() async {
     // kick-off the simulator, but we don't want to wait
     unawaited(Simulator.run());
 
-    WaveDumper(shiftReg,
+    WaveformService(shiftReg,
         outputPath: 'doc/tutorials/chapter_7/shift_register.vcd');
 
     printFlop('Before');

doc/tutorials/chapter_8/answers/exercise_1_spi.dart

@@ -163,7 +163,7 @@ void main() async {
   Simulator.setMaxSimTime(100);
   unawaited(Simulator.run());
 
-  WaveDumper(peri, outputPath: 'doc/tutorials/chapter_8/spi-new.vcd');
+  WaveformService(peri, outputPath: 'doc/tutorials/chapter_8/spi-new.vcd');
 
   await drive(LogicValue.ofString('01010101'));
 }

doc/tutorials/chapter_8/answers/exercise_2_toycapsule_fsm.dart

@@ -55,7 +55,7 @@ Future<void> main(List<String> args) async {
 
   reset.inject(1);
 
-  WaveDumper(toyCap, outputPath: 'toyCapsuleFSM.vcd');
+  WaveformService(toyCap, outputPath: 'toyCapsuleFSM.vcd');
 
   Simulator.setMaxSimTime(100);
   Simulator.registerAction(25, () {

doc/tutorials/chapter_8/answers/exercise_3_pipeline.dart

@@ -41,7 +41,7 @@ void main(List<String> args) async {
 
     Simulator.registerAction(10, () => reset.put(0));
 
-    WaveDumper(pipe, outputPath: 'answer_1.vcd');
+    WaveformService(pipe, outputPath: 'answer_1.vcd');
 
     Simulator.registerAction(50, () async {
       // stage 4 / result: 30 + (30 * 3) = 120

doc/tutorials/chapter_8/carry_save_multiplier.dart

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

doc/tutorials/chapter_8/counter_interface.dart

@@ -65,7 +65,7 @@ Future<void> main() async {
 
   print(counter.generateSynth());
 
-  WaveDumper(counter,
+  WaveformService(counter,
       outputPath: 'doc/tutorials/chapter_8/counter_interface.vcd');
   Simulator.registerAction(25, () {
     intf.en.put(1);

doc/tutorials/chapter_8/oven_fsm.dart

@@ -190,9 +190,9 @@ Future<void> main({bool noPrint = false}) async {
   // Let's start off with asserting reset to Oven.
   reset.inject(1);
 
-  // Attach a waveform dumper so we can see what happens.
+  // Attach a waveform service so we can see what happens.
   if (!noPrint) {
-    WaveDumper(oven, outputPath: 'doc/tutorials/chapter_8/oven.vcd');
+    WaveformService(oven, outputPath: 'doc/tutorials/chapter_8/oven.vcd');
   }
 
   if (!noPrint) {

doc/tutorials/chapter_9/rohd_vf_example/lib/rohd_vf_example.dart

@@ -315,7 +315,7 @@ Future<void> main({Level loggerLevel = Level.FINER}) async {
   await tb.counter.build();
 
   // dump wave here
-  WaveDumper(tb.counter);
+  WaveformService(tb.counter);
 
   // Set a maximum simulation time so it doesn't run forever
   Simulator.setMaxSimTime(300);

doc/user_guide/_get-started/03-development-recommendations.md

@@ -10,9 +10,9 @@ toc: true
 - The [ROHD Cosimulation](https://github.com/intel/rohd-cosim) package allows you to cosimulate the ROHD simulator with a variety of SystemVerilog simulators.
 - The [ROHD Hardware Component Library](https://github.com/intel/rohd-vf) provides a set of reusable and configurable components for design and verification.
 - Visual Studio Code (vscode) is a great, free IDE with excellent support for Dart.  It works well on all platforms, including native Windows or Windows Subsystem for Linux (WSL) which allows you to run a native Linux kernel (e.g. Ubuntu) within Windows.  You can also use vscode to develop on a remote machine with the Remote SSH extension.
-  - vscode: <https://code.visualstudio.com/>
+  - vscode: <https://code.visualstudio.com/download>
   - WSL: <https://docs.microsoft.com/en-us/windows/wsl/install-win10>
-  - Remote SSH: <https://code.visualstudio.com/blogs/2019/07/25/remote-ssh>
+  - Remote SSH: <https://code.visualstudio.com/docs/remote/ssh>
   - Dart extension for vscode: <https://marketplace.visualstudio.com/items?itemName=Dart-Code.dart-code>
 
 Head over to the [user guide]({{ site.baseurl }}{% link _docs/A01-sample-example.md %}) to learn more about how to use ROHD.

example/example.dart

@@ -68,9 +68,9 @@ Future<void> main({bool noPrint = false}) async {
 
   // Now let's try simulating!
 
-  // Attach a waveform dumper so we can see what happens.
+  // Attach a waveform service so we can see what happens.
   if (!noPrint) {
-    WaveDumper(counter);
+    WaveformService(counter);
   }
 
   // Let's also print a message every time the value on the counter changes,

example/fir_filter.dart

@@ -106,9 +106,9 @@ Future<void> main({bool noPrint = false}) async {
 
   // Now let's try simulating!
 
-  // Attach a waveform dumper.
+  // Attach a waveform service.
   if (!noPrint) {
-    WaveDumper(firFilter);
+    WaveformService(firFilter);
   }
 
   // Let's set the initial setting.

example/logic_array.dart

@@ -65,7 +65,7 @@ Future<void> main({bool noPrint = false}) async {
 
   // Simulate the module
   if (!noPrint) {
-    WaveDumper(logicArrayExample);
+    WaveformService(logicArrayExample);
   }
 
   // Set the input values

example/oven_fsm.dart

@@ -223,9 +223,9 @@ Future<void> main({bool noPrint = false}) async {
   // Set a maximum time for the simulation so it doesn't keep running forever.
   Simulator.setMaxSimTime(300);
 
-  // Attach a waveform dumper so we can see what happens.
+  // Attach a waveform service so we can see what happens.
   if (!noPrint) {
-    WaveDumper(oven, outputPath: 'oven.vcd');
+    WaveformService(oven, outputPath: 'oven.vcd');
   }
 
   // Kick off the simulation.

lib/rohd.dart

@@ -1,9 +1,12 @@
-// Copyright (C) 2021-2023 Intel Corporation
+// Copyright (C) 2021-2026 Intel Corporation
 // SPDX-License-Identifier: BSD-3-Clause
 
+export 'src/diagnostics/diagnostics.dart';
 export 'src/exceptions/exceptions.dart';
 export 'src/external.dart';
 export 'src/finite_state_machine.dart';
+export 'src/fst/fst_types.dart';
+export 'src/fst/fst_writer.dart';
 export 'src/interfaces/interfaces.dart';
 export 'src/module.dart';
 export 'src/modules/modules.dart';

lib/src/diagnostics/diagnostics.dart

@@ -0,0 +1,13 @@
+// Copyright (C) 2026 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// diagnostics.dart
+// Barrel export for the diagnostics library.
+//
+// 2026 July 16
+// Author: Desmond Kirkpatrick <desmond.a.kirkpatrick@intel.com>
+
+export 'module_service.dart';
+export 'module_services.dart';
+export 'waveform_service.dart';
+export 'waveform_writer.dart';

lib/src/diagnostics/module_service.dart

@@ -0,0 +1,50 @@
+// Copyright (C) 2026 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// module_service.dart
+// Common base types shared by all module-scoped services.
+//
+// 2026 June 23
+// Author: Desmond Kirkpatrick <desmond.a.kirkpatrick@intel.com>
+
+import 'package:rohd/rohd.dart';
+
+/// The common contract implemented by every module-scoped service that
+/// registers with [ModuleServices].
+abstract interface class ModuleService {
+  /// The top-level [Module] this service operates on.
+  Module get module;
+
+  /// A JSON-serialisable summary of this service.
+  Map<String, Object?> toJson();
+}
+
+/// A [ModuleService] that emits output to one or more files.
+abstract class OutputService implements ModuleService {
+  /// The default location written by [write].
+  String? get outputPath;
+
+  /// Whether [write] emits one file per module definition (`true`) or a single
+  /// combined file (`false`).
+  bool get multiFile;
+
+  /// Writes this service's output to [path], or to [outputPath] when [path] is
+  /// omitted.
+  void write([String? path]);
+}
+
+/// An [OutputService] that generates source-code text, keyed per module
+/// definition.
+abstract class CodeGenService extends OutputService {
+  /// The combined single-file generated output (including any header).
+  String get output;
+
+  /// The generated output keyed by module definition name
+  /// ([Module.definitionName]).
+  Map<String, String> get contentsByDefinitionName;
+
+  /// The generated output for a single module [definitionName], or `null` when
+  /// that definition was not generated.
+  String? moduleOutput(String definitionName) =>
+      contentsByDefinitionName[definitionName];
+}

lib/src/diagnostics/module_services.dart

@@ -0,0 +1,54 @@
+// Copyright (C) 2026 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// module_services.dart
+// Slim, type-keyed registry of module-scoped services for DevTools and other
+// inspection tools.
+//
+// 2026 April 25
+// Author: Desmond Kirkpatrick <desmond.a.kirkpatrick@intel.com>
+
+import 'package:rohd/rohd.dart';
+import 'package:rohd/src/diagnostics/inspector_service.dart';
+
+/// A slim, type-keyed registry of [ModuleService]s.
+class ModuleServices {
+  ModuleServices._();
+
+  /// The singleton instance.
+  static final ModuleServices instance = ModuleServices._();
+
+  Module? _rootModule;
+
+  /// The most recently built top-level [Module].
+  Module? get rootModule => _rootModule;
+
+  set rootModule(Module? value) {
+    _rootModule = value;
+    ModuleTree.rootModuleInstance = value;
+  }
+
+  /// Returns the module hierarchy as a JSON string.
+  String get hierarchyJSON => ModuleTree.instance.hierarchyJSON;
+
+  final Map<Type, ModuleService> _services = <Type, ModuleService>{};
+
+  /// Registers [service] under the type argument [T].
+  void register<T extends ModuleService>(T service) {
+    _services[T] = service;
+  }
+
+  /// Returns the registered service of type [T], or `null` if none.
+  T? lookup<T extends ModuleService>() => _services[T] as T?;
+
+  /// Removes the registered service of type [T], if any.
+  void unregister<T extends ModuleService>() {
+    _services.remove(T);
+  }
+
+  /// Resets all services. Intended for test teardown.
+  void reset() {
+    rootModule = null;
+    _services.clear();
+  }
+}