interface added and web ui created
This commit is contained in:
Martino Ferrari
@@ -1,64 +1,145 @@
|
||||
# MARTe2 Debug Suite Specifications
|
||||
|
||||
**Version:** 1.2
|
||||
**Version:** 2.0
|
||||
**Status:** Active / Implemented
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
This project implements a "Zero-Code-Change" observability and debugging layer for the MARTe2 real-time framework. The system allows developers to Trace, Force, and Monitor any signal in a running MARTe2 application without modifying existing source code.
|
||||
|
||||
This project implements a "Zero-Code-Change" observability and debugging layer for the
|
||||
MARTe2 real-time framework. Developers can trace, force, and monitor any signal in a
|
||||
running MARTe2 application without modifying existing source code.
|
||||
|
||||
The suite ships two interchangeable transport backends sharing a common abstract interface:
|
||||
|
||||
- **`DebugService`** — TCP command channel + binary UDP telemetry + `TcpLogger` sidecar.
|
||||
Paired with a native Rust/egui GUI.
|
||||
- **`WebDebugService`** — HTTP command endpoint + Server-Sent Events telemetry, with an
|
||||
embedded single-page browser UI. No additional client software required.
|
||||
|
||||
---
|
||||
|
||||
## 2. System Architecture
|
||||
- **The Universal Debug Service (C++ Core):** A singleton MARTe2 Object that patches the registry and manages communication.
|
||||
- **The Broker Injection Layer (C++ Templates):** Templated wrappers that intercept `Execute()` and `Init()` calls for tracing, forcing, and execution control.
|
||||
- **The Remote Analyser (Rust/egui):** A high-performance, multi-threaded GUI for visualization and control.
|
||||
- **Network Stack:**
|
||||
- **Port 8080 (TCP):** Commands and Metadata.
|
||||
- **Port 8081 (UDP):** High-Speed Telemetry for Oscilloscope.
|
||||
- **Port 8082 (TCP):** Independent Real-Time Log Stream via `TcpLogger`.
|
||||
|
||||
- **`DebugServiceI` (Abstract Interface):** Singleton that decouples the broker injection
|
||||
layer from the transport. Defined in `DebugServiceI.h`.
|
||||
- **`DebugService` (TCP/UDP Transport):** TCP text command channel (port 8080), binary UDP
|
||||
telemetry (port 8081), `TcpLogger` log sidecar (port 8082).
|
||||
- **`WebDebugService` (HTTP/SSE Transport):** Single HTTP port (default 8090) serving the
|
||||
embedded web UI, command API, and SSE telemetry stream.
|
||||
- **`DebugBrokerWrapper` (Injection Layer):** C++ template wrappers injected via registry
|
||||
patching. Depend only on `DebugServiceI`; transport-agnostic.
|
||||
- **`TcpLogger` (Log Sidecar):** Optional standalone component forwarding `REPORT_ERROR`
|
||||
events to TCP clients on a dedicated port (used with `DebugService` only).
|
||||
|
||||
---
|
||||
|
||||
## 3. Requirements
|
||||
|
||||
### 3.1 Functional Requirements (FR)
|
||||
- **FR-01 (Discovery):** Discover the full MARTe2 object hierarchy at runtime. The GUI client SHALL request the full application tree upon connection and display it in a hierarchical tree view.
|
||||
- **FR-02 (Telemetry):** Stream high-frequency signal data (verified up to 100Hz+) to a remote client via UDP.
|
||||
|
||||
- **FR-01 (Discovery):** Discover the full MARTe2 object hierarchy at runtime. The client
|
||||
SHALL request the full application tree and display it hierarchically.
|
||||
- **FR-02 (Telemetry):** Stream high-frequency signal data (verified > 100 Hz) to a remote
|
||||
client. `DebugService` uses binary UDP; `WebDebugService` uses SSE.
|
||||
- **FR-03 (Forcing):** Allow manual override of signal values in memory during execution.
|
||||
- **FR-04 (Logs):** Stream global framework logs to a dedicated terminal/client via a standalone `TcpLogger` service.
|
||||
- **FR-05 (Log Filtering):** The client must support filtering logs by type (Debug, Information, Warning, FatalError) and by content using regular expressions.
|
||||
- **FR-06 (Execution Control):** Provide a mechanism to pause and resume the execution of all patched real-time threads (via Brokers), allowing for static inspection of the system state.
|
||||
- **FR-07 (Session Management):** Support runtime re-configuration and "Apply & Reconnect" logic. The GUI provides a "Disconnect" button to close active network streams.
|
||||
- **FR-08 (Decoupled Tracing):** Tracing activates telemetry; data is buffered and shown as a "Last Value" in the sidebar, but not plotted until manually assigned.
|
||||
- **FR-09 (Advanced Plotting):**
|
||||
- Support multiple plot panels with perfectly synchronized time (X) axes.
|
||||
- Drag-and-drop signals from the traced list into specific plots.
|
||||
- Plot modes: Standard (Time Series) and Logic Analyzer (Stacked rows).
|
||||
- Signal transformations: Gain, offset, units, and custom labels.
|
||||
- **FR-10 (Navigation & Scope):**
|
||||
- Context menus for resetting zoom (X, Y, or both).
|
||||
- "Fit to View" functionality that automatically scales both axes.
|
||||
- High-performance oscilloscope mode with configurable time windows (10ms to 10s).
|
||||
- Triggered acquisition (Single/Continuous, rising/falling edges).
|
||||
- **FR-11 (Data Recording):** Record any traced signal to disk in Parquet format with a visual recording indicator in the GUI.
|
||||
- **FR-12 (Configuration Awareness):** The DebugService SHALL store a complete copy of the application's configuration provided at initialization.
|
||||
- **FR-13 (Metadata Enrichment):** Metadata returned by `INFO` and `DISCOVER` SHALL be enriched with additional fields from the stored configuration (e.g., Frequency, PVNames, Units).
|
||||
- **FR-14 (Configuration Serving):** Provide a `CONFIG` command to serve the full stored configuration in JSON format to the client.
|
||||
The override SHALL persist across RT cycles until explicitly released.
|
||||
- **FR-04 (Logs):** Forward all `REPORT_ERROR` events to a connected client in real time.
|
||||
`DebugService` uses `TcpLogger` on a dedicated TCP port. `WebDebugService` embeds logs
|
||||
in the SSE stream.
|
||||
- **FR-05 (Log Filtering):** The client SHOULD support filtering log output by level and
|
||||
by content.
|
||||
- **FR-06 (Execution Control):** Provide pause and resume for all patched RT threads,
|
||||
allowing static inspection of the system state.
|
||||
- **FR-07 (Breakpoints):** Halt execution when a signal crosses a threshold. Supported
|
||||
operators: `>`, `<`, `==`, `>=`, `<=`, `!=`.
|
||||
- **FR-08 (Execution Stepping):** After a pause or breakpoint, allow resuming for exactly
|
||||
N output-broker cycles then pausing again. Optional per-thread filter.
|
||||
- **FR-09 (Decoupled Tracing):** Activating a trace SHALL only stream data; displaying
|
||||
the data (plot, sidebar) is the client's responsibility.
|
||||
- **FR-10 (Signal Monitoring):** Poll any `DataSourceI` signal at a configurable period
|
||||
without requiring that signal to be traced at full RT rate.
|
||||
- **FR-11 (Config Awareness):** The service SHALL accept and store a full copy of the
|
||||
application's CDB (`SetFullConfig`). `INFO` and `DISCOVER` responses SHALL be enriched
|
||||
with additional metadata fields from this CDB.
|
||||
- **FR-12 (Config Serving):** Provide a `CONFIG` command returning the full stored
|
||||
configuration as JSON.
|
||||
- **FR-13 (MARTe2 Messaging):** Allow sending `Message` objects to any ORD object via an
|
||||
`MSG` command.
|
||||
- **FR-14 (Dual Transport):** Both `DebugService` and `WebDebugService` SHALL implement
|
||||
the identical `DebugServiceI` interface and be mutually exclusive singletons. Switching
|
||||
transport SHALL require only a config change (different class name, different port).
|
||||
- **FR-15 (Embedded Web UI):** `WebDebugService` SHALL serve a self-contained single-page
|
||||
application with real-time plotting (Chart.js), signal tree, force/break/monitor dialogs,
|
||||
and an integrated log viewer — without any external server or build tooling.
|
||||
|
||||
### 3.2 Technical Constraints (TC)
|
||||
|
||||
- **TC-01:** No modifications allowed to the MARTe2 core library or component source code.
|
||||
- **TC-02:** Instrumentation must use Runtime Class Registry Patching.
|
||||
- **TC-03:** Real-time threads must remain lock-free; use `FastPollingMutexSem` or atomic operations for synchronization.
|
||||
- **TC-04:** Telemetry must be delivered via UDP to minimize impact on real-time jitter.
|
||||
- **TC-02:** Instrumentation MUST use runtime class registry patching (`ClassRegistryDatabase`).
|
||||
- **TC-03:** RT-path methods (`ProcessSignal`, `IsPaused`) MUST be lock-free or use only
|
||||
`FastPollingMutexSem`; no heap allocation on the RT path.
|
||||
- **TC-04:** `DebugService` telemetry MUST use UDP to minimise jitter impact.
|
||||
- **TC-05:** No STL — use `Vec<T>` and `StreamString` throughout.
|
||||
- **TC-06:** C++98 compatibility for all source files (no `auto`, no range-for, no raw
|
||||
string literals).
|
||||
- **TC-07:** The `DebugServiceI` abstract interface MUST be the only dependency of
|
||||
`DebugBrokerWrapper`. Concrete transport headers MUST NOT be included by broker code.
|
||||
|
||||
## 4. Performance Metrics
|
||||
- **Latency:** Telemetry dispatch overhead < 5 microseconds per signal.
|
||||
- **Throughput:** Support for 100Hz+ sampling rates with zero packet loss on local networks.
|
||||
- **Scalability:** Handle up to 4096 unique signals and 16 simultaneous client connections.
|
||||
- **Code Quality:** Maintain a minimum of **85% code coverage** across all core service and broker logic.
|
||||
---
|
||||
|
||||
## 5. Communication Protocol (Port 8080)
|
||||
- **LS [Path]:** List nodes at the specified path.
|
||||
- **TREE:** Returns a full recursive JSON structure representing the entire application tree.
|
||||
- **INFO [Path]:** Returns detailed metadata for a specific node or signal.
|
||||
- **PAUSE / RESUME:** Global execution control.
|
||||
- **TRACE <Signal> <1/0> [Decimation]:** Enable/disable telemetry for a signal.
|
||||
- **FORCE <Signal> <Value>:** Persistent signal override.
|
||||
- **UNFORCE <Signal>:** Remove override.
|
||||
- **LOG <Level> <Msg>:** Streaming format used on Port 8082.
|
||||
## 4. Performance Requirements
|
||||
|
||||
- **Latency:** `ProcessSignal` overhead < 5 µs per signal when tracing is inactive.
|
||||
- **Throughput:** Support > 100 Hz signal tracing with zero sample loss on local networks
|
||||
(UDP transport).
|
||||
- **Scalability:** Handle up to 4096 unique signals.
|
||||
- **Ring buffer size:** `TraceRingBuffer` initialised to 4 MB in both transports.
|
||||
- **SSE clients:** `WebDebugService` supports up to 8 simultaneous SSE clients.
|
||||
- **TCP rate limit:** Server disconnects clients sending > 100 commands/s.
|
||||
- **VALUE output cap:** `GetSignalValue` returns at most 256 elements per call.
|
||||
|
||||
---
|
||||
|
||||
## 5. Performance Hardening Log
|
||||
|
||||
| Fix | Category | Description |
|
||||
|---|---|---|
|
||||
| **#1** | Naming | `STREAMER_MTU = 1400`, `STREAMER_BUFFER_SIZE = 4096` replace magic numbers |
|
||||
| **#2** | Concurrency | `tracePushMutex` serialises multi-producer `TraceRingBuffer::Push()` |
|
||||
| **#3** | Concurrency | Break indices copied under `activeMutex`; condition evaluated outside lock |
|
||||
| **#4** | Concurrency | `Atomic::Add` for lock-free per-signal decimation counter |
|
||||
| **#5** | Robustness | `TraceRingBuffer::Pop` skips corrupt entry; full discard only when unrecoverable |
|
||||
| **#6** | Security | TCP command rate-limit: > 100 cmd/s → client disconnect |
|
||||
| **#7** | Latency | `Vec::Swap` inside spinlock; deallocation outside — shorter lock hold time |
|
||||
| **#8** | Robustness | 30-second idle timeout on active TCP client |
|
||||
| **#9** | Safety | `VALUE` output capped at 256 elements; `"truncated":true` flag included |
|
||||
| **#10** | Correctness | `inputBuffer` reassembles split TCP commands; bounded at 8 KiB |
|
||||
| **#11** | Correctness | `Initialise()` never calls `MoveToRoot()` on the framework-supplied CDB |
|
||||
|
||||
---
|
||||
|
||||
## 6. Command Protocol Summary
|
||||
|
||||
| Command | Transport | Description |
|
||||
|---|---|---|
|
||||
| `DISCOVER` | Both | Full signal list with metadata |
|
||||
| `TREE` | Both | Live ORD hierarchy as JSON |
|
||||
| `INFO <path>` | Both | Node metadata enriched from CDB |
|
||||
| `LS [path]` | Both | Immediate children of ORD node |
|
||||
| `TRACE <name> <0\|1> [dec]` | Both | Enable/disable signal tracing |
|
||||
| `FORCE <name> <value>` | Both | Persistent signal value injection |
|
||||
| `UNFORCE <name>` | Both | Remove forced value |
|
||||
| `BREAK <name> <op> <thr>` | Both | Set conditional breakpoint |
|
||||
| `BREAK <name> OFF` | Both | Clear breakpoint |
|
||||
| `PAUSE` | Both | Halt all RT threads |
|
||||
| `RESUME` | Both | Release paused RT threads |
|
||||
| `STEP <n> [thread]` | Both | Run N cycles then pause |
|
||||
| `STEP_STATUS` | Both | Query pause/step state |
|
||||
| `VALUE <name>` | Both | Read current signal value |
|
||||
| `MONITOR SIGNAL <name> <ms>` | Both | Register slow-rate polling |
|
||||
| `UNMONITOR SIGNAL <name>` | Both | Stop slow-rate polling |
|
||||
| `CONFIG` | Both | Full CDB as JSON |
|
||||
| `MSG <obj> <fn> [k=v …]` | Both | Send MARTe2 Message |
|
||||
| `SERVICE_INFO` | Both | Transport metadata |
|
||||
|
||||
Reference in New Issue
Block a user