Module services api by desmonddak · Pull Request #673 · intel/rohd

desmonddak · 2026-06-25T19:19:50Z

Description & Motivation

This is a subset of the PR #669 that introduces the new API for Services attached to a module (outputters like wave dumpers, netlisters, translators, tracing services, etc).

Related Issue(s)

None

Testing

This runs a full dart test with the new API in place in the tests.

Backwards-compatibility

Is this a breaking change that will not be backwards-compatible? If yes, how so?

No, we retain the old interfaces but they should eventually be deprecated.
WaveDumper
generateSynth
...

Documentation

Does the change require any updates to documentation? If so, where? Are they included?

Some examples have been modified to match.

…agree on names

…al/instance naming routine names

Introduces a singleton service registry (ModuleServices) that provides a unified query surface for DevTools and inspection tools. Module.build() now registers the root module with ModuleServices.instance. Also adds SvService which wraps SystemVerilog synthesis and registers with ModuleServices for DevTools access to SV metadata. This is a clean separation: no netlist code is included. The netlist branch will later extend ModuleServices with a netlistService field.

mkorbel1 · 2026-07-16T17:12:51Z

+///  - [outputPath] — the default file or directory written by [write].
+///  - [multiFile] — whether [write] emits one file per module definition
+///    (a directory) or a single combined file.
+///  - [write] — performs the write, honouring [multiFile].


i like this API because it's easy to understand, but should we be using some sort of URI object or something from Dart instead that supports referencing files, directories, and other weird stuff instead? im not sure the answer, genuine question

I filed this as Issue #684

if we don't fix before next release, will this not get us stuck with the API?

Backed by _rootModule. Setter eagerly syncs ModuleTree.rootModuleInstance. Safe for module_services_api (no FLC dependencies).

mkorbel1 · 2026-07-17T18:17:00Z

+/// // Or get the concatenated output (like generateSynth):
+/// print(sv.allContents);
+/// ```
+class SystemVerilogService extends CodeGenService {


Something doesn't feel quite right to me in this API. Some thoughts:

If I want to generate some SV (pretty common), why am I constructing a "service"? Though the abstraction levels as a service make sense to me.

Why does the act of constructing said service immediately produce the output?

In what cases do I want to run the SynthBuilder with a selected synthesizer instead of this service?

When there are multiple synthesizers (e.g. SystemC), will I have multiple services or one service that takes multiple synthesizers?

The two APIs currently are basically:

Turn this module into SV quickly (generateSynth function on module)

Make a thing that builds an output based on this Synthesizer and give me outputs I can do more work with (SynthBuilder with Synthesizer arg)

This is deprecating the first, but keeping the second, and there's still some API overlap.

I think this is close to right, but something is a little off. Thoughts?

Let me ponder this.

I have NetlistService, SystemVerilogService, SystemCService, TraceService, and WaveformService. So some of this is trying to go for least surprise even though they are not fully symmetric. For example, the outputing services need to be setup after the build. WaveformService tracks with the simulator running, so it is truly a live 'service', but the output services execute (though we could use an api that says 'generate' for those.

I never thought of SynthBuilder as a user API.

Here is a live usage on HCL:

final adder = FloatingPointAdderSinglePath(clk: clk, fp1, fp2); await adder.build(); NetlistService(adder, outputPath: '$buildDir/${adder.definitionName}.json'); final sv = SystemVerilogService(adder, outputPath: '$buildDir/${adder.definitionName}.sv' // embedSourceTraceComments: false, ); final sc = SystemCService(adder, outputPath: '$buildDir/${adder.definitionName}.sc', multiFile: false); TraceService(adder, svService: sv, scService: sc).write('x.flc.json'); WaveformService(adder, format: WaveOutputFormat.fst, outputPath: '$buildDir/${adder.definitionName}.fst');

One additional thing: the synthesizers must run to store FLC info. Then the TraceService can access to generate FLC.

I think of these services as constructing an in-memory view that can be further manipulated (written to file, written to string, perhaps searched, etc). The only challenge I face is that if we change any line numbers then trace gets broken.

A added simpler Module.dumpSystemVerilog and Module.dumpWaveforms which don't require forming a Service.
I discovered some usefuless to the Service model: it can stay alive and provide an API, so for example, the NetlistService can provide connectivity queries beyond just netlisting as it has created a model of the design. We could do that with Module after build, but there are other examples like the WaveformService enabling incremental waveform queries. We can also make these more highly optioned so we don't keep extending all new capabilities as part of Module.

i dont see these in the current PR? also, does dumpWaves work better?

mkorbel1 · 2026-08-17T20:47:10Z


-# run tests in JS (increase heap size also)
+# Run tests in sub-packages
+for pkg in packages/*/; do


what about hierarchical packages (like rohd_devtools_widgets)?

See comment below. pub workspace is the Dart/Flutter answer.

mkorbel1 · 2026-08-17T20:48:31Z

+/// // Or get the concatenated output (like generateSynth):
+/// print(sv.allContents);
+/// ```
+class SystemVerilogService extends CodeGenService {


i dont see these in the current PR? also, does dumpWaves work better?

mkorbel1 · 2026-08-17T20:54:16Z

+///
+/// For more control over filtering, timescale, and recording windows, see
+/// [WaveformService] constructor parameters.
+@Deprecated('Use WaveformService instead')


or the dumpWaves on Module?

Yes, the deprecation mentions first using Module.dumpWaves() and then the WaveformService.

mkorbel1 · 2026-08-17T20:55:04Z

+///
+/// For more control over filtering, timescale, and recording windows, see
+/// [WaveformService] constructor parameters.
+@Deprecated('Use WaveformService instead')


Update documentation (doc/ directory) as well.

mkorbel1 · 2026-08-17T20:55:59Z

    final dut = ManySubmodulesModule(Logic(), numSubModules: 10000);
    await dut.build();
-    dut.generateSynth();
+    SystemVerilogService(dut).output;


should use dumpSystemVerilog instead in most cases, including tutorials, benchmarks, simple tests, etc?

mkorbel1 · 2026-08-17T20:56:22Z

    await _mod.build();

-    WaveDumper(_mod, outputPath: _vcdTemporaryPath);
+    WaveformService(_mod, outputPath: _vcdTemporaryPath);


should use dumpWaves in most scenarios including simple tests, benchmarks, tutorials, etc?

Done. Renamed to dumpWaves. Using the two dump routines everywhere except the new services tests.

mkorbel1 · 2026-08-17T21:30:18Z

+  /// DevTools evaluates this via `EvalOnDartLibrary` to display the module
+  /// hierarchy.  Richer design views (e.g. a slim netlist) are composed by the
+  /// DevTools client from the relevant registered service.
+  String get hierarchyJSON => ModuleTree.instance.hierarchyJSON;


nit: use Json instead (https://dart.dev/effective-dart/style#do-capitalize-acronyms-and-abbreviations-longer-than-two-letters-like-words)

Done for JSON.

mkorbel1 · 2026-08-17T21:32:07Z

+  /// filtering, timescale, start/stop times, flush size, and overwrite policy.
+  WaveformService(
+    this.module, {
+    this.outputPath = 'waves.vcd',


should this default to null and automatically pick the name based on format instead? e.g. if someone picks format: .fst but doesnt specify the path, it would be weird for it to be waves.vcd

maybe if format is default to null also then you can infer the type from the file name too? e.g. if someone says waves.fst it defaults format to fst?

then just need to document behavior if there is none specified for either?

I reworked these substantially to consider the idea of having byte stream as well as file output, and defaults like module name and use the format as the extension, etc. So it would be good to reanalyze the changes to the API. Conceptually similar, but more scalable.

mkorbel1 · 2026-08-17T21:34:15Z

+  ///
+  /// Requires an FST writer to be available; see the DevTools subclass for
+  /// a fully FST-backed implementation.
+  fst,


is FST supported in this PR?

No, but we check here and throw. We should add fst soon.

mkorbel1 · 2026-08-17T21:43:01Z

 dart pub get
+
+# Install dependencies for sub-packages
+for pkg in packages/*/; do


what about sub-sub-packages?

The suggestion is to use a pub workspace. Since there is a mix of flutter and dart packages, this means flutter controls. But that gives us full repo analysis and testing without scripting, but with a dart program to manage.

https://dart.dev/tools/pub/workspaces

…ices_api # Conflicts: # doc/tutorials/chapter_3/answers/exercise_sv.dart

…rkspace

desmonddak added 30 commits April 17, 2026 08:30

move synthesis naming to a common naming utility so all synthesizers …

82e900e

…agree on names

dart 3.11 parameter_assignments pickiness

85f88ce

Merge branch 'main' into central_naming

b1de1e5

conflict resolved and dart format . works

b7087c4

properly assign naming spaces for instances vs signals

4a55214

format issue

ed7be36

Controllable enforcement of signal vs instance name uniqueness.

ab09aed

Refactored to Namer class. No external API changes for ROHD

520d280

signal registry

61d0319

module context name uniquification instead of signal/instance split

becdb36

Merge branch 'main' into central_naming

a86f80c

cleanup of port vs signal name assumptions, constant merging and sign…

d5904a6

…al/instance naming routine names

simplified forModule, improved code doc

6dfe0f9

more coverage for Namer

3c90e5d

first passing version of SystemC translated tests

f918ec7

SystemC and SV tests are comingled.

91604b1

we need sudo in installation scripts

810eec7

avoid a race and using a lock for SystemC

6c39020

cascade introduced

340af62

use BigInt.one shifted instead of a platform-dependent constant

0b4732b

JS platform skip SystemC

6aeb6aa

cleanup tmp_test after systemc tests

832ef9f

create test dir

4b92fc6

cascade issue

824a191

yet another JS issue

de589e5

trying to match devcontainer to normal ci

d0e985b

dart tests using ffi to drive systemc

60974d7

fixed recent analyzer failure (version change)

1951d17

skip FFI tests in CI as dart:ffi is not available

e4d931d

mkorbel1 reviewed Jul 16, 2026

View reviewed changes

desmonddak added 6 commits July 16, 2026 13:27

Remove dart_test.yaml - only needed in branches with FFI tests

df8a606

fully deprecate WaveDumper, multiple review fixes

ee6c7a3

deprecate generateSynth

4db1142

refactor: Convert rootModule field to property with ModuleTree sync

b8f5f63

Backed by _rootModule. Setter eagerly syncs ModuleTree.rootModuleInstance. Safe for module_services_api (no FLC dependencies).

Merge remote-tracking branch 'upstream/main' into module_services_api

a6120e9

missed generateSynth calls

73e06a5

mkorbel1 reviewed Jul 17, 2026

View reviewed changes

desmonddak added 8 commits July 17, 2026 18:10

cleanup module_services lookup and rootModule APIs

e8bc6d3

Support headers in multi-file SV output

d8dc42a

single and multi-file header control for SV

e98a0c0

cleaner ModuleTree update

8d9be73

Merge branch 'main' into module_services_api

bb66629

remove deprecated calls

39f0054

fixes for mismatching verilog

63c7410

simpler 'dump' Module output methods for common use cases

fab34e5

desmonddak requested a review from mkorbel1 August 8, 2026 22:48

mkorbel1 reviewed Aug 17, 2026

View reviewed changes

desmonddak added 11 commits August 19, 2026 16:09

Merge branch 'main' of https://github.com/intel/rohd into module_serv…

e23bb5a

…ices_api # Conflicts: # doc/tutorials/chapter_3/answers/exercise_sv.dart

major overhaul of module_services api as well as converting to pub wo…

f33f2f4

…rkspace

full repo analysis fixes

93b8197

date fixes. new clean command to match dart clean

75de5cb

upgrade Flutter

a7f6bf9

fix two failures in CI

b0be50a

isolate IO test from rest

e7ddb26

flutter for CodeSpaces

0ffec9a

devcontainer needs flutter

7c6dc8f

migrate pub workspace capability to pub-workspace branch

03680d2

remove the workspace file

3d193c2

desmonddak requested a review from mkorbel1 August 20, 2026 06:40

Uh oh!

Conversation

desmonddak commented Jun 25, 2026

Description & Motivation

Related Issue(s)

Testing

Backwards-compatibility

Documentation

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

desmonddak Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

desmonddak Jul 19, 2026 •

edited

Loading