MARTe2 Debug Suite Specifications

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. 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

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 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. 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 (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 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

7.6 KiB Raw Blame History