1# Runtime Debug API 2 3### Requirements 4 51. Runtime should support debugging on the platforms from low-end IoT devices to high-end mobile phones. 6 7### Key Design Decisions 8 91. Runtime doesn't patch apps' bytecode on the fly. Instead, it notifies the listeners when the PC of bytecode is changed. 10 111. Runtime and debugger work in the same process. Debugger functionality is provided via shared library, the runtime loads when working in debugg mode. Debugger works in its own thread and is responsible for thread management rely on it. Runtime doesn't create/destroy threads. 12 13### Rationale 14 151. As some low-end targets can store bytecode in ROM, runtime cannot patch apps' bytecode on the fly. So it uses slower approach with interpreter instrumentation. 16 171. To simplify communication between debugger and runtime (especially on microcontrollers) they are work in the same process. Debugger is loaded as shared library when it's necessary. 18 19### Specification / Implementation 20 21To start runtime in debug mode, thef `Runtime::StartDebugger()` method is used. This method loads the debug library and calls the `StartDebugger` function from it. It takes pointer to [`debug::Debugger`](../runtime/tooling/debugger.h) object that implements [debug interface](../runtime/include/tooling/debug_interface.h) - point of interaction with the runtime. 22Also it takes a TCP port number and a reserved argument. 23 24Runtime provides [`RuntimeNotificationManager`](../runtime/include/runtime_notification.h) class that allows to subscribe to different events: 25* `LoadModule` - occurs when the Panda file is loaded by the runtime 26* `StartProcess` - occurs when the managed process is started or failed to start 27* `BytecodePcChanged` - occurs when the PC of bytecode is changed during interpretation (only if runtime works in debug mode) 28 29[`debug::Debugger`](../runtime/tooling/debugger.h) subscribes to these events and notifies debugger via hooks. 30