marte-debug/SPECS.md

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 <1/0> [Decimation]: Enable/disable telemetry for a signal.
• FORCE : Persistent signal override.
• UNFORCE : Remove override.
• LOG : Streaming format used on Port 8082.