Skip to content
kevindadiPublic

About

Text-first native workbench for embedded real-time scheduling analysis: RTSL / TDG / PTPN to WCET/WCRT, schedulability and deadlock reports via the PTPN analyzer, plus ELF to readable CFG extraction via elf2tdg. Built with Tauri 2, React and Rust.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

RT-PN

Native desktop workbench for the Priority Timed Petri Net (PTPN) analyzer.

RT-PN is the Rust desktop front-end of PrioritizedTPN. The analyzer, lowering and scheduling analysis stay in the original C++17 CLI; RT-PN owns the desktop workflow, text-first presentation and explicit graph previews.

Built with Tauri 2 + React + TypeScript:

  • native window and file dialogs, Rust command boundary
  • CodeMirror 6 for dense text stages, line numbers, search and selection
  • React Flow for on-demand PTPN / state-class / CFG / thread previews
  • no graph is shown by default; text remains the primary representation

Workflows

On launch the workbench shows a two-card workflow chooser; the two analysis modes get dedicated workspaces and their stages/panels are never mixed. The sidebar's workflow section can switch modes at any time (NEW WORKSPACE).

  • Scheduling analysis — specification-first, timed/prioritized PTPN.
  • Binary analysis — ELF layout and CFG inspection via elf2tdg.

Sample models for both modes ship in examples/ (see Layout); the in-app EXAMPLES / SAMPLE buttons resolve them at runtime.

Scheduling analysis (specification-first)

RTSL / TDG JSON / PTPN → analyzer → DAG, PTPN, STATE SPACE, TIMELINE, REPORT text stages. Assumptions, core/priority coverage, exactness and truncation stay visible in the inspector; PREVIEW opens a PTPN or state-class graph.

Binary analysis (code-first)

ELF → readable ELF layout → program CFG (schema 2.4) → static timing analysis → report.

The binary workflow is isolated from scheduling analysis: it has its own stages, inspector and sample (examples/elf2tdg), and never feeds an ELF into the PTPN analyzer. TDG output is gone; the program CFG is elf2tdg's primary analysis IR.

Importing an .elf, .out or .axf binary now runs the bundled elf2tdg extractor:

  1. elf2tdg <elf> --view elf writes a readable ELF loader view (<stem>.elf.mmd, Mermaid layout source).
  2. elf2tdg <elf> --view cfg --format json writes the lossless program CFG (functions, blocks, instructions, typed edges, roots, calls, concurrency annotations, diagnostics); --format dot feeds the Graphviz SVG preview.
  3. Optional analysis profiles drive the M3 timing features: --board-profile examples/elf2tdg/profiles/*.toml (clocks, memory-region wait states, instruction/data cache, branch prediction, WCET longest-path analysis), --cpu, and --freq.
  4. Raw elf2tdg outputs are kept next to the analysis artifacts (%LOCALAPPDATA%\RT-PN\artifacts\elf-* on Windows; override with PTPN_ARTIFACT_DIR).

Static cycle counts are estimates, not certified WCET bounds; the timing model caveats must stay visible in the UI. The proposed CFG-first interface (overview, function index, graph explorer, analysis cards, inspector) is documented in docs/elf2tdg-ui-design.md.

Development

Prerequisites:

  • Rust (MSVC toolchain on Windows)
  • Node.js 20+ and npm
  • WebView2 (included with Windows 11)
  • CMake 3.27+, Ninja, a vcpkg checkout, and the Visual Studio C++ build tools (the release ptpn is a static MSVC build)
  • just (winget install --id Casey.Just)

The two analysis engines are git submodules under engines/; the top-level just recipes build them and stage them as Tauri sidecars:

git submodule update --init
npm install
just doctor        # report the detected CMake/Ninja/C++/vcpkg/rustc
just dev           # build + stage the engines, then start the desktop app

Machine-local tool paths can live in .env.local (start from .env.local.example). Detection prefers the environment overrides, then PATH, then the Visual Studio toolchain (CMake, cl.exe via vcvars64.bat) and the CMake/Ninja bundled with CLion, then D:/vcpkg for vcpkg.

The desktop window is created in Rust, so WebView2 state is kept in .webview2/ during development and under the portable package's webview2/ directory when RT_PN_WEBVIEW_DATA_DIR is set.

The plain npm run tauri dev still works once the sidecars are staged with just stage.

Engine discovery depends on the build mode. just stage builds both engines and stages them as Tauri sidecars, so neither mode needs extra configuration by default:

  • Debug builds (just dev): PTPN_BIN / ELF2TDG_BIN override → sidecar next to the app executable → repository build trees (cmake-build-*/, build/ptpn, build/cargo/release) → PATH. This keeps isolated engine development possible; the sidebar shows which source was used.
  • Release builds (installers / portable package): PTPN_BIN / ELF2TDG_BIN override is honored but flagged as ENV·EXTERNAL in the sidebar → ptpn.exe / elf2tdg.exe (or bin/…) next to the app executable → error. The working directory and PATH are never scanned, so a stray CLI cannot shadow the bundled sidecars.

The desktop app never reimplements analysis. It launches the CLI with tdg|rtsl|ptpn -f … --export-ptpn --export-scg --export-metrics --export-wcet and parses the exports.

Resource budgets and long runs

Petri-net state-class reachability is exponential in the model, so every analysis is bounded. The inspector's RESOURCE BUDGET block passes --max-states (default 20000), --timeout (default 120 s) and --max-memory (default 2048 MB) to ptpn; setting timeout or memory to 0 disables that bound. When a limit fires the engine exits 5 and the workbench marks the run PARTIAL — the state class graph is then an incomplete prefix and the metrics are conservative bounds. Runs can be cancelled while the engine explores (the process is terminated), analyzer output streams into the run log, and RUN HISTORY keeps structured snapshots so the latest two runs can be compared (WCRT, state counts, exactness and truncation regressions). EXPORT MD / EXPORT JSON write a report containing the budgets, partial flag, metrics and stage text.

Deadlock counterexamples and pending timings

When the explored state space contains reachable deadlocks, the inspector's COUNTEREXAMPLE section shows the shortest transition path from the initial state class to a deadlock (markings included) and opens it as a graph preview; the same trace is included in exported reports.

RTSL models with measured by llm timing are not analyzable until the pending intervals are filled. PENDING TIMING runs ptpn check --diagnostics json, lists the pending tasks with their expected interval count, and FILL & ANALYZE feeds the entered [min, max] pairs to ptpn fill. The patched source is written to the artifact directory and analyzed immediately, leaving the original model untouched.

Scheduling policies and formal semantics

The sidebar SCHEDULING POLICY selector overrides the model's policy for the next analysis (--policy) and picks the equal-priority tie mode (--tie fifo | arbitrary). The supported policies are fixed, fixed_prior_with_resume, fixed_prior_with_restart, rm, dm, pip, pcp, srp, edf, fifo and llf; the selected id is carried through the run details, status bar, exported reports and .rtpn runs.

The new SEMANTICS stage documents the selected policy formally with three layers:

  • Mermaid diagrams: a state-class diagram (S = (M, Z, E_struct, E_pri, Susp) plus the policy-specific clock set / extra state components — release clocks for EDF/FIFO, laxity clocks for LLF, lock ownership or system ceiling for PIP/PCP/SRP) and a firing-semantics flow (time elapse → structural enabling → E_pri filter → fire → canonicalize) with the policy's selection rule highlighted. Mermaid is bundled locally (lazy-loaded chunk) and rendered with a clean sans-serif dark theme, so the stage works offline;
  • policy notes below the diagrams: the time-elapse, priority-filter and firing rules, preemption/lock/clock behaviour and the engine's documented restrictions;
  • a live animated firing-rule diagram (elapse → enabling → filter → fire → canonicalize) rendered with the policy's selection rule;
  • RUN SWEEP: analyzes the loaded model once per policy with the current tie mode (bounded to the smaller of the current budget and 8 000 states, 30 s per policy) and lists verdict, max WCRT, state count, deadlocks and elapsed time side by side; the table is included in exported MD/JSON reports;
  • ptpn describe output for the loaded model (DESCRIBE MODEL), i.e. the analyser's own restatement of effective priorities, cores and lock nesting.

State-class replay

The REPLAY stage steps through a real transition path of the explored state-class graph: the deadlock counterexample path when one exists, otherwise the shortest path to a state class chosen from the dropdown. Play/pause, step-forward/back, reset, speed and a clickable state timeline are available. Each step shows the marking (place tokens), the selected active set E_pri, suspended transitions, the fired transition and the elapsed time. A WCRT envelope strip under the replay controls draws one bar per task (with deadline ticks and deadline-miss colouring) and moves a playhead to the current step's elapsed time, linking the state-class trace to the analyzed response windows.

EXPORT HTML writes a self-contained offline player (same panels/controls, autoplaying, no external assets) and EXPORT JSON writes the raw step data; both carry the model name and the scheduling policy/tie used, so a replay can be attached to a paper, review bundle or presentation.

COMPARE POLICIES opens the policy-aware side-by-side view: pick any subset of the scheduling policies, run them on the same model (bounded to 5 000 states / 20 s per policy) and replay the lanes with one synchronized playhead. Each lane shows its own deadlock counterexample or shortest path with marking tokens, the fired transition, elapsed time and the selected active set E_pri, which makes the difference between schedulers (e.g. lock inheritance under PCP/PIP) directly visible. EXPORT HTML / EXPORT JSON in comparison mode write the same self-contained multi-lane player or the raw lane data (model name, tie mode and the per-policy budget included), ready for papers or review bundles.

The EDF/FIFO/LLF notes reflect the engine's documented constraints (statically partitioned multi-core, no locks, deterministic segments for event-driven LLF).

Charts, core allocation and project files

  • WCRT / SLACK draws a compact per-task bar chart (deadline marker, red on a deadline miss) from the metrics JSON.
  • CORE ALLOCATION runs ptpn allocate with bounded candidates and shows the search summary, the best assignment and the Pareto front with WCRT, core load, deadlock count and state count per candidate.
  • SAVE PROJECT / OPEN PROJECT store {version, workflow, modelPath, stage, budgets, savedAt} in a .rtpn file; opening a project restores the budget, re-runs the model and returns to the saved stage.

Exports default to %LOCALAPPDATA%\RT-PN\artifacts on Windows. If that directory is not writable (for example under a restricted runner), RT-PN probes and falls back to .rt-pn-artifacts in the current workspace. Override with:

PTPN_ARTIFACT_DIR
PTPN_MINGW_BIN        # MinGW runtime `bin` directory, if needed

A model can also be opened by launching the app with a path argument:

rt-pn.exe examples/ptpn/motivating-examples/hw.json
rt-pn.exe firmware.elf

Build

just build     # stage the engines, then `tauri build`
just dist      # installers + portable zip + versions.json

Artifacts:

  • src-tauri/target/release/bundle/ — NSIS installer and MSI
  • dist/rt-pn-portable/ and dist/RT-PN-<version>-portable-<arch>.zip — portable package with both engine CLIs in bin/
  • dist/rt-pn-portable/versions.json — exact engine commits and tool versions

Plain npm run tauri build works too, but requires the sidecars to be staged first (just stage): Tauri validates bundle.externalBin at build time.

The application icon is generated from scripts/make-icon.ps1 (npm run tauri -- icon src-tauri/icons/source.png); the generated src-tauri/icons/ set is committed because the Windows bundlers need it.

Other recipes: just test (engine tests + desktop backend tests + typecheck + e2e), just engines (engine builds only), just update-engines (bump the submodule pins), and just clean.

VS Code / CMake Tools (engine-only debugging)

just remains the unified build entry, but the analyzer engine can also be configured directly from VS Code's CMake Tools. Run once:

node scripts/vscode-cmake-setup.mjs   # or: just vscode-setup

This writes a local engines/prioritized-tpn/CMakeUserPresets.json (MinGW + Ninja + vcpkg x64-mingw-dynamic, build tree cmake-build-vscode) and points .vscode/settings.json at the vscode-windows-debug preset. Both files are machine-local; the release pipeline (just engines/just build) keeps using the MSVC x64-windows-static tree under build/ptpn and is unaffected.

To reconfigure, delete engines/prioritized-tpn/cmake-build-vscode and run the task again; the toolchain paths come from .env.local/auto-detection, the same as just doctor.

Keyboard

  • Ctrl+F / Cmd+F — search within the active text stage
  • Esc — close a graph preview
  • drag an .rtsl, .json, .ptpn, .elf, .out or .axf file onto the window

Layout

engines/prioritized-tpn/  C++ analyzer submodule (PTPN / WCRT / deadlock CLI)
engines/elf2tdg/          Rust ELF -> CFG extractor submodule (still developing)
examples/ptpn/            analyzer examples copied from the C++ CLI repository
examples/elf2tdg/         elf2tdg examples/artifacts copied for the binary workflow
docs/ptpn/                Analyzer documentation moved from the CLI repository
docs/elf2tdg/             elf2tdg documentation snapshot (upstream copy)
scripts/                  build / stage / package / version scripts
Justfile                  unified build entry
build/                    generated engine build outputs (ignored)
src-tauri/binaries/       generated Tauri sidecars (ignored)
src/                 React workbench
  App.tsx            workflow chooser, stages, inspector, run history
  CodeStage.tsx      CodeMirror text surface
  GraphPreview.tsx   React Flow preview
  Semantics.tsx      scheduling-policy formal semantics (Mermaid)
  Mermaid.tsx        lazy Mermaid renderer
  Replay.tsx         state-class replay
  ReplayCompare.tsx  policy-aware side-by-side replay
  api.ts             Tauri commands and native dialogs
src-tauri/src/       Rust backend
  lib.rs             Tauri commands
  cli.rs             ptpn discovery + export orchestration
  model.rs           analysis result model
  dot.rs             PTPN / state-class DOT parser
  workbench.rs       text stage renderers
  binary.rs          ELF / CFG workflow orchestration
  graph.rs           serializable preview graph

The engine submodules remain the source of truth and are pinned by gitlink; examples/ and docs/elf2tdg/ are checked-in copies so the workbench, sample buttons and portable package are self-contained while elf2tdg keeps evolving.

RT-PN workbench

Status

  • Specification-first: functional.
  • Binary-first: elf2tdg drives the ELF loader view, readable CFG and Graphviz preview image; threads/net and the analysis backend are pending.
  • Unified build: just + engine submodules; both CLIs ship as Tauri sidecars.
  • Qt desktop: replaced by RT-PN; the C++ CLI remains unchanged.

License

MIT — see LICENSE. The bundled analyzer engine (PrioritizedTPN) is MIT and the ELF extractor (elf2tdg) is MIT OR Apache-2.0.

About

Text-first native workbench for embedded real-time scheduling analysis: RTSL / TDG / PTPN to WCET/WCRT, schedulability and deadlock reports via the PTPN analyzer, plus ELF to readable CFG extraction via elf2tdg. Built with Tauri 2, React and Rust.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages