Debug (executable)

The debug executable is a host-side diagnostics agent. It provides task/memory inspection, screen capture, a bounded LVGL UI tree and synthetic pointer/keyboard input through a character-device transport. The payload schema lives in the reusable Debug protocol library; this executable owns the live service and its integration with the Graphics, Task, Memory and VFS subsystems.

Startup and runtime ownership

DebugExecutable implements ExecutableTrait. The normal invocation creates an informational graphics window; passing --background omits the window but still starts the service. It spawns a Task child called Debug agent transport and opens the VFS endpoint /devices/debug/transport with read/write access.

The foreground loop checks window events every 50 ms. Closing the window signals the transport task to stop and then joins it. The transport itself polls its synchronous file interface; a busy read sleeps 10 ms and retries. In background mode the foreground loop has no window-close event, so its lifetime depends on external task/runtime shutdown.

The executable does not create the transport device; a platform or test environment must mount it before requests can be served. Graphics access requires a functioning Graphics manager, even for headless UI inspection and injection.

Request and response framing

The transport reads at most MAX_REQUEST_BYTES + 1 bytes and rejects requests larger than 16 KiB. It parses the JSON Request enum and applies debug_protocol::validate_request. Responses are JSON objects terminated by a newline:

{
  "ok": true,
  "result": {
    "width": 800,
    "height": 600
  }
}

An error uses {"ok":false,"error":{"code":"…","message":"…"}}. Normal JSON responses are capped at 64 KiB; oversized responses become a response_too_large error rather than being sent partially. A successful screenshot returns metadata in the JSON frame followed immediately by the raw RGBA8888 byte payload, whose length is payload_bytes. Clients must read that extra binary frame before the next response.

Supported operations and limits

• diagnostics: memory total/used/free/page size and up to 64 task records, with a truncation flag.
• resolution and screenshot: active display dimensions, or a bounded RGBA8888 screenshot with validated metadata.
• ui_tree: a bounded, potentially truncated snapshot. Element IDs are local to the snapshot and must not be treated as persistent object identifiers.
• pointer_move, pointer_button, key and text: synthetic input queued through Graphics; coordinates must fit the display and the internal signed-point representation.
• Text input is restricted to printable ASCII. Key names include arrows, Enter, Escape, Backspace, Delete, Home, End, Next and Previous, plus single printable characters.

A screenshot's path request field is validated as non-empty by the protocol; the executable currently captures and streams the image to the client, not a VFS file at that path.

Security and failure boundaries

The agent accepts input requests over its mounted transport; it does not implement a login or authorization check inside dispatch. Restrict access to /devices/debug/transport at the surrounding platform/VFS boundary and do not expose it to untrusted network clients. A service task failure is logged; ordinary input queue contention produces a busy response.

Source and API references

• executables/debug/src/lib.rs — executable, service loop, dispatch and framing.
• libraries/debug_protocol/src/lib.rs — request schema and size limits.
• Graphics subsystem — actual capture and injection.
• Executable contract — task launch and context.