Diagram plugins and Konata integration #18

2024-11-29T14:39:43Z

MartinKavik commented

2024-11-29 14:39:43 +00:00

(Migrated from github.com)

Diagram Connectors (Plugins)

Diagram Connectors are FastWave plugins providing interactivity to diagrams. They can both listen to diagram changes made by users and modify the diagram directly. Their main purpose is to connect signals / variables from VCD/FST files with the related diagrams. They are based on the same architecture like decoders - The WebAssembly Component Model. The Plugin and Host API is defined in WIT language and the plugins / diagram connectors can be written in any supported language - currently C/C++, C#, Go, Javascript, Python, Rust. However, we recommend to write plugins in Rust because the support and tooling, speed and size are the best.

In the demo below, the wave.fst file is loaded to get SV39 Memory Management Unit simulation data. Then a diagram cache_diagram.excalidraw is loaded (the file contains a JSON-encoded diagram definition). This diagram is basically a dialog with text fields that can be modified by the user or the plugin in real-time. Then, the plugin rust_diagram_connector.wasm is loaded through the Javascript commands panel. The plugin automatically updates Address and Status fields according to the value defined in the Time (ps) field in the diagram after the plugin initialization and then on each Time (ps) value change.

The Diagram Connector API can be easily extended according to the FastWave users feedback because bindings between plugins and FastWave is automatically generated from WIT files and the Rust compiler guarantees we cannot forget to implement additional host functions.

The demo:

A snippet from the rust_diagram_connector.wasm source code:

Konata Integration

Konata is an instruction pipeline visualizer for Onikiri2-Kanata/Gem5-O3PipeView formats. It's a cross-platform app based on Electron. It didn't have an external API but the new API was implemented in the forked version. It's a REST API powered by Express: "Fast, unopinionated, minimalist web framework for Node.js". FastWave either connects to already running Konata process or starts the app by itself. Then it'll send a request to open the chosen file in a new Konata tab as demonstrated below. Konata is maintained since 2016, it's stable and thanks to Electron there is no problem to run it on any platform so we don't expect any merge conflicts in the future. Also the new API is easily extendable and we can prepare pre-built binaries to be downloaded automatically by FastWave later. And thanks to the FastWave Plugin architecture, users may write plugins to communicate with Konata through FastWave.

Konata integration demo - starting the app and then opening the second file in a new tab:

Note: In case you want to test the Konata bridge now (as demonstrated above), you can just clone the forked Konata version next to the FastWave repo and follow the steps in its README section Development.

## Diagram Connectors (Plugins) _Diagram Connectors_ are FastWave plugins providing interactivity to diagrams. They can both listen to diagram changes made by users and modify the diagram directly. Their main purpose is to connect signals / variables from VCD/FST files with the related diagrams. They are based on the same architecture like _decoders_ - [The WebAssembly Component Model](https://component-model.bytecodealliance.org/). The Plugin and Host API is defined in [WIT language](https://component-model.bytecodealliance.org/design/wit.html) and the plugins / diagram connectors can be written in any supported language - currently C/C++, C#, Go, Javascript, Python, Rust. However, we recommend to write plugins in Rust because the support and tooling, speed and size are the best. In the demo below, the `wave.fst` file is loaded to get SV39 Memory Management Unit simulation data. Then a diagram `cache_diagram.excalidraw` is loaded (the file contains a JSON-encoded diagram definition). This diagram is basically a dialog with text fields that can be modified by the user or the plugin in real-time. Then, the plugin `rust_diagram_connector.wasm` is loaded through the `Javascript commands` panel. The plugin automatically updates `Address` and `Status` fields according to the value defined in the `Time (ps)` field in the diagram after the plugin initialization and then on each `Time (ps)` value change. The Diagram Connector API can be easily extended according to the FastWave users feedback because bindings between plugins and FastWave is automatically generated from WIT files and the Rust compiler guarantees we cannot forget to implement additional host functions. The demo: ![video_diagram_connector](https://github.com/user-attachments/assets/e22b1152-342e-49d5-a13a-21b62376efd4) A snippet from the `rust_diagram_connector.wasm` source code: ![screenshot_diagram_connector_rs](https://github.com/user-attachments/assets/e54d0909-0cc3-4287-8cc5-6419ae795be2) ## Konata Integration [Konata](https://github.com/shioyadan/Konata) is an instruction pipeline visualizer for Onikiri2-Kanata/Gem5-O3PipeView formats. It's a cross-platform app based on [Electron](https://www.electronjs.org/). It didn't have an external API but the new API was implemented in the [forked version](https://github.com/MartinKavik/Konata/tree/api). It's a REST API powered by [Express](https://expressjs.com/): _"Fast, unopinionated, minimalist web framework for [Node.js](https://nodejs.org/en/)"_. FastWave either connects to already running Konata process or starts the app by itself. Then it'll send a request to open the chosen file in a new Konata tab as demonstrated below. Konata is maintained since 2016, it's stable and thanks to Electron there is no problem to run it on any platform so we don't expect any merge conflicts in the future. Also the new API is easily extendable and we can prepare pre-built binaries to be downloaded automatically by FastWave later. And thanks to the FastWave Plugin architecture, users may write plugins to communicate with Konata through FastWave. Konata integration demo - starting the app and then opening the second file in a new tab: ![video_konata](https://github.com/user-attachments/assets/44ce2964-2ab3-403f-97b4-d4b05b93319f) _Note:_ In case you want to test the Konata bridge now (as demonstrated above), you can just clone the forked Konata version next to the FastWave repo and follow the steps in its README section Development.

ThePerfectComputer (Migrated from github.com) reviewed 2024-11-29 14:39:43 +00:00

src-tauri/wit/diagram_connector/world.wit

					
				@ -0,0 +4,4 @@

				    log: func(message: string);

				    listen-for-component-text-changes: func(diagram-connect-name: string, component-id: string);

				    set-component-text: func(component-id: string, text: string);

				    address-and-way: func(time-text: string) -> result<tuple<string, option<u32>>>;

ThePerfectComputer (Migrated from github.com) commented

2024-12-05 16:02:32 +00:00

Is the address-and-way function defined in excalidraw? If so, where?

ThePerfectComputer (Migrated from github.com) commented

2024-12-05 16:13:51 +00:00

I would assume that there is some javascript code somewhere that exports address-and-way for example?

I would assume that there is some javascript code somewhere that exports `address-and-way` for example?

MartinKavik commented

2024-12-04 19:29:02 +00:00

(Migrated from github.com)

Local testing step by step:

rustup update stable
cargo install cargo-make
Clone this repo and pull the latest changes from the working branch or from the branch main if the PR has been already merged.
Extract test_files/sv39_mmu_cache_sim.zip to sv39_mmu_cache_sim.
makers install
makers start
Click the Load file.. button and choose test_files/sv39_mmu_cache_sim/fst/wave.fst
Click the hamburger menu in the Diagram Panel, then click Open and choose test_files/cache_diagram.excalidraw
Run command FW.add_diagram_connectors(["../test_files/components/rust_diagram_connector/rust_diagram_connector.wasm"]) in the Javascript commands panel. (The command is also written directly in the loaded diagram.)
Edit text in the Time (ps) field in the diagram and notice automatic changes in other fields.
Clone MartinKavik/Konata to Konata folder, put it next to the cloned FastWave2.0 folder.
Select the api branch in the Konata repo folder and pull latest changes.
sudo npm -g install electron
sudo npm -g install electron-packager
make init
In the FastWave app window, click the Open Konata file.. and select test_files/sv39_mmu_cache_sim/fst/konata.log.
FastWave will start Konata app and automatically open the konata.log file.
Repeat the step 16. to open konata.log again.
Notice a new tab in the Konata app window.

Note A: When FastWave web-only version is implemented, then FastWave web app could open Konata app directly through custom protocol handlers (see Deep Links | Electron; e.g. Discord invitation links work the same way). Or we can initiate WebSocket connection from Konata app as a fallback solution. We can try to port / rewrite Konata later to integrate it directly into FastWave but I wouldn't recommended it until it's requested by multiple FastWave users and make it really sense.

Note B: Many steps will not be needed once both FastWave and updated Konata are released with their binaries and if we make possible to distribute wave data together with related diagrams and diagram connectors (in case users will need such feature).

Local testing step by step: 1. `rustup update stable` 2. `cargo install cargo-make` 3. Clone this repo and pull the latest changes from the working branch or from the branch `main` if the PR has been already merged. 4. Extract `test_files/sv39_mmu_cache_sim.zip` to `sv39_mmu_cache_sim`. 5. `makers install` 6. `makers start` 7. Click the `Load file..` button and choose `test_files/sv39_mmu_cache_sim/fst/wave.fst` 8. Click the hamburger menu in the Diagram Panel, then click `Open` and choose `test_files/cache_diagram.excalidraw` 9. Run command `FW.add_diagram_connectors(["../test_files/components/rust_diagram_connector/rust_diagram_connector.wasm"])` in the `Javascript commands` panel. (The command is also written directly in the loaded diagram.) 10. Edit text in the `Time (ps)` field in the diagram and notice automatic changes in other fields. 11. Clone [MartinKavik/Konata](https://github.com/MartinKavik/Konata/tree/api) to `Konata` folder, put it next to the cloned `FastWave2.0` folder. 12. Select the `api` branch in the `Konata` repo folder and pull latest changes. 13. `sudo npm -g install electron` 14. `sudo npm -g install electron-packager` 15. `make init` 16. In the FastWave app window, click the `Open Konata file..` and select `test_files/sv39_mmu_cache_sim/fst/konata.log`. 17. FastWave will start Konata app and automatically open the `konata.log` file. 18. Repeat the step 16. to open `konata.log` again. 19. Notice a new tab in the Konata app window. _Note A_: When FastWave web-only version is implemented, then FastWave web app could open Konata app directly through custom protocol handlers (see [Deep Links | Electron](https://www.electronjs.org/docs/latest/tutorial/launch-app-from-url-in-another-app); e.g. Discord invitation links work the same way). Or we can initiate WebSocket connection from Konata app as a fallback solution. We can try to port / rewrite Konata later to integrate it directly into FastWave but I wouldn't recommended it until it's requested by multiple FastWave users and make it really sense. _Note B_: Many steps will not be needed once both FastWave and updated Konata are released with their binaries and if we make possible to distribute wave data together with related diagrams and diagram connectors (in case users will need such feature).

Sign in to join this conversation.

No reviewers