ROHD Module Hierarchy and Signals Visualization (Flutter UI) (#435)

.github/workflows/general.yml

@@ -92,3 +92,24 @@ jobs:
         with:
           folder: doc/api
           branch: docs
+
+  build-devtool:
+    name: Build Devtools
+    timeout-minutes: 30
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Flutter SDK
+        uses: flutter-actions/setup-flutter@v2
+        with:
+          channel: beta
+          version: 3.18.0-0.2.pre
+
+      - name: Run Flutter Test
+        run: tool/gh_actions/devtool/run_devtool_test.sh
+
+      - name: Build Static Web
+        run: tool/gh_actions/devtool/build_web.sh
+
+

analysis_options.yaml

@@ -8,6 +8,7 @@ analyzer:
     strict-raw-types: true
   exclude:
     - doc/tutorials/chapter_9/rohd_vf_example
+    - rohd_devtools_extension
 
 # keep up to date, matching https://dart-lang.github.io/linter/lints/options/options.html
 # some lints are not yet available, so disabled and marked with [not currently recognized]

extension/devtools/config.yaml

@@ -0,0 +1,4 @@
+name: rohd
+issueTracker: https://github.com/intel/rohd/issues
+version: 0.0.1
+materialIconCodePoint: '0xe1c5'

lib/src/diagnostics/inspector_service.dart

@@ -0,0 +1,102 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// inspector_service.dart
+// The service that handle interaction between ROHD and Devtools Extension.
+//
+// 2024 January 23
+// Author: Yao Jing Quek <yao.jing.quek@intel.com>
+
+import 'dart:convert';
+import 'package:rohd/rohd.dart';
+
+extension _LogicDevToolUtils on Logic {
+  /// Converts the current object instance into a JSON string.
+  ///
+  /// This function uses Dart's built-in `json.encode()` method to convert
+  /// the object's properties into a JSON string. The output string will
+  /// contain keys such as `name`, `width`, and `value`.
+  Map<String, dynamic> toMap() => {
+        'name': name,
+        'width': width,
+        'value': value.toString(),
+      };
+}
+
+extension _ModuleDevToolUtils on Module {
+  /// Convert the [Module] object and its sub-modules into a JSON
+  /// representation.
+  ///
+  /// Returns a JSON map representing the [Module] and its properties.
+  ///
+  /// If [skipCustomModules] is set to `true` (default), sub-modules that are
+  /// instances of [CustomSystemVerilog] will be excluded from the JSON schema.
+  Map<String, dynamic> toJson({bool skipCustomModules = true}) {
+    final json = {
+      'name': name,
+      // ignore: invalid_use_of_protected_member
+      'inputs': inputs.map((key, value) => MapEntry(key, value.toMap())),
+      'outputs': outputs.map((key, value) => MapEntry(key, value.toMap())),
+    };
+
+    final isCustomModule = this is CustomSystemVerilog;
+
+    if (!isCustomModule || !skipCustomModules) {
+      json['subModules'] = subModules
+          .where(
+              (module) => !(module is CustomSystemVerilog && skipCustomModules))
+          .map((module) => module.toJson(skipCustomModules: skipCustomModules))
+          .toList();
+    }
+
+    return json;
+  }
+
+  /// Generates a JSON schema representing a tree structure of the [Module]
+  /// object and its sub-modules.
+  ///
+  /// The [module] parameter is the root [Module] object for which the JSON
+  /// schema is generated.
+  ///
+  /// By default, sub-modules that are instances of [CustomSystemVerilog] will
+  /// be excluded from the schema.
+  /// Pass [skipCustomModules] as `false` to include them in the schema.
+  ///
+  /// Returns a JSON string representing the schema of the [Module] object
+  /// and its sub-modules.
+  String buildModuleTreeJsonSchema(Module module,
+          {bool skipCustomModules = true}) =>
+      jsonEncode(toJson(skipCustomModules: skipCustomModules));
+}
+
+/// `ModuleTree` implements the Singleton design pattern
+/// to ensure there is only one instance of it during runtime.
+///
+/// This class is used to maintain a tree-like structure
+/// for managing modules in an application.
+class ModuleTree {
+  /// Private constructor used to initialize the Singleton instance.
+  ModuleTree._();
+
+  /// Singleton instance of `ModuleTree`.
+  ///
+  /// Always returns the same instance of `ModuleTree`.
+  static ModuleTree get instance => _instance;
+  static final _instance = ModuleTree._();
+
+  /// Stores the root Module instance.
+  static Module? rootModuleInstance;
+
+  /// Returns the `hierarchyString` as JSON.
+  ///
+  /// This getter allows access to the `_hierarchyString` string.
+  ///
+  /// Returns: string representing hierarchical structure of modules in JSON
+  /// format.
+  String get hierarchyJSON =>
+      rootModuleInstance?.buildModuleTreeJsonSchema(rootModuleInstance!) ??
+      json.encode({
+        'status': 'fail',
+        'reason': 'module not yet build',
+      });
+}

lib/src/module.dart

@@ -14,6 +14,7 @@ import 'package:collection/collection.dart';
 import 'package:meta/meta.dart';
 
 import 'package:rohd/rohd.dart';
+import 'package:rohd/src/diagnostics/inspector_service.dart';
 import 'package:rohd/src/utilities/config.dart';
 import 'package:rohd/src/utilities/sanitizer.dart';
 import 'package:rohd/src/utilities/timestamper.dart';
@@ -254,6 +255,8 @@ abstract class Module {
     }
 
     _hasBuilt = true;
+
+    ModuleTree.rootModuleInstance = this;
   }
 
   /// Adds a [Module] to this as a subModule.

rohd_devtools_extension/.gitignore

@@ -0,0 +1,43 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

rohd_devtools_extension/.metadata

@@ -0,0 +1,30 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "f65dd3bac0c44c036fe4b158c5d550c4ec529a60"
+  channel: "master"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: f65dd3bac0c44c036fe4b158c5d550c4ec529a60
+      base_revision: f65dd3bac0c44c036fe4b158c5d550c4ec529a60
+    - platform: web
+      create_revision: f65dd3bac0c44c036fe4b158c5d550c4ec529a60
+      base_revision: f65dd3bac0c44c036fe4b158c5d550c4ec529a60
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

rohd_devtools_extension/.vscode/launch.json

@@ -0,0 +1,34 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "rohd_devtools_extension",
+            "request": "launch",
+            "type": "dart"
+        },
+        {
+            "name": "rohd_devtools_extension (profile mode)",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "profile"
+        },
+        {
+            "name": "rohd_devtools_extension (release mode)",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "release"
+        },
+        {
+            "name": "rohd_devtools_extension + simulated environment",
+            "program": "lib/main.dart",
+            "request": "launch",
+            "type": "dart",
+            "args": [
+                "--dart-define=use_simulated_environment=true"
+            ],
+        },
+    ]
+}

rohd_devtools_extension/README.md

@@ -0,0 +1,25 @@
+# ROHD Devtool
+
+The ROHD Devtool provides debugging functionality for hardware designers. Initial proposals and discussions for the devtool can be found at <https://github.com/intel/rohd/discussions/418>.
+
+How to Use the ROHD Devtool:
+
+1. Set a breakpoint on your ROHD design.
+2. When the breakpoint is hit, an URL will be outputted.
+3. Run the dart devtools command on your terminal.
+4. A webpage will open, and you can paste the URL into the webpage.
+5. Look for the tab labeled 'ROHD'.
+
+## Contributions
+
+We welcome contributions to the development of the ROHD Devtool. Please refer to our Contributing doc for guidance on how to get started.
+
+## Running Tests on the Devtool
+
+The ROHD Devtool runs in an iframe, which means that the --platform chrome flag is required to ensure tests are run in the browser.
+
+```cmd
+flutter test --platform chrome Optional[test\modules\tree_structure\model_tree_card_test.dart] > test_output.txt
+```
+
+This command will output the test results to a text file named `test_output.txt`.

rohd_devtools_extension/analysis_options.yaml

@@ -0,0 +1,28 @@
+# This file configures the analyzer, which statically analyzes Dart code to
+# check for errors, warnings, and lints.
+#
+# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
+# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
+# invoked from the command line by running `flutter analyze`.
+
+# The following line activates a set of recommended lints for Flutter apps,
+# packages, and plugins designed to encourage good coding practices.
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  # The lint rules applied to this project can be customized in the
+  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
+  # included above or to enable additional rules. A list of all available lints
+  # and their documentation is published at https://dart.dev/lints.
+  #
+  # Instead of disabling a lint rule for the entire project in the
+  # section below, it can also be suppressed for a single line of code
+  # or a specific dart file by using the `// ignore: name_of_lint` and
+  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
+  # producing the lint.
+  rules:
+    # avoid_print: false  # Uncomment to disable the `avoid_print` rule
+    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options

rohd_devtools_extension/devtools_options.yaml

@@ -0,0 +1,2 @@
+extensions:
+  - rohd: true

rohd_devtools_extension/lib/main.dart

@@ -0,0 +1,18 @@
+// Copyright (C) 2024 Intel Corporation
+// SPDX-License-Identifier: BSD-3-Clause
+//
+// main.dart
+// Entry point for main application.
+//
+// 2024 January 5
+// Author: Yao Jing Quek <yao.jing.quek@intel.com>
+
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'src/modules/rohd_devtools_module.dart';
+
+void main() {
+  runApp(const ProviderScope(
+    child: RohdDevToolsModule(),
+  ));
+}