65 lines
4.7 KiB
Markdown
65 lines
4.7 KiB
Markdown
# MARTe2 Debug Suite Specifications
|
|
|
|
**Version:** 1.2
|
|
**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.
|
|
|
|
## 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`.
|
|
|
|
## 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-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.
|
|
|
|
### 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.
|
|
|
|
## 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.
|