diff --git a/api/python/debuggercontroller.py b/api/python/debuggercontroller.py index 11a2092..600ecae 100644 --- a/api/python/debuggercontroller.py +++ b/api/python/debuggercontroller.py @@ -1491,16 +1491,11 @@ def execute_backend_command(self, command: Union[str, bytes]) -> str: """ Execute a backend command and get the output - For LLDB adapter (on Linux and macOS), any LLDB commands can be executed. The returned string is what gets - printed if one executes the command in the LLDB prompt. - - For DbgEnd adapter (on Windows), any Windbg commands can be executed. However, nothing will be returned. - This is because the backend processes the command asynchronously. By the time it returns, the commands are not - executed yet. However, the output are still printed to the Debugger console in the global area. - - Note, the user should never run any command that resumes the target (either running or stepping). It will - cause the UI to desynchronize and even hang. This is a known limitation, and we will try to address it. + For LLDB adapter, any LLDB commands can be executed. The returned string is what gets printed if one executes + the command in the LLDB prompt. + For DbgEnd adapter, any WinDbg commands can be executed. The returned string is what gets printed if one + executes the command in WinDbg. """ return dbgcore.BNDebuggerInvokeBackendCommand(self.handle, command) diff --git a/docs/guide/index.md b/docs/guide/index.md index e8c6a2a..8a69465 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -141,6 +141,11 @@ Double-clicking the addresses in the PC (program counter), SP (stack pointer), a The active thread is marked with `(*)`. Double-clicking another thread will set that as the active thread. As a result, the register widget will show the registers from the new active thread. +The stack trace is symbolized using both information from the analysis and the debug adapter backend. +In the above screenshot, we can see that function names like `MD5Update` and `MD5Init` are from the analysis (named by +the user), and the `start` function in the `dyld` module comes from the LLDB backend, which can read symbols from other +modules other than the current one. + ![](../../img/debugger/threadwidgetcontextmenu.png) The context menu offers to suspend and resume each thread individually. A convenience method is offered to make a thread "solo", which suspends all other threads and resumes the thread. Note, resuming the thread does NOT cause the thread to start executing immediately. It only makes the thread execute the next time the target is resumed, e.g., by pressing the `Go` or `Step Over` button. There are some known issues when suspending/resuming individual threads with LLDB adapter. @@ -186,6 +191,9 @@ Among these actions, target control actions, e.g., `Run`/`Step Into` have the sa ![](../../img/debugger/stackvariable.png) +Note: stack variable annotation is disabled by default because it is sometimes inaccurate. +It can be turned on by setting `debugger.stackVariableAnnotations` to true. + When the target breaks and a stack trace is available, the debugger annotates the stack variables in the linear view as data variables. The above image shows the annotated stack with two stack frames. The start and end of each stack frame are marked, and stack variables are defined according to the stack variables in the functions. @@ -196,8 +204,6 @@ Only the stack frames and variables of the current (active) thread are annotated The annotation is done only when there are at least two frames in the stack trace. This is a known limitation, and we will address it later. -If the stack variable annotation does not work in certain cases or even causes problems, it can be disabled by setting `debugger.stackVariableAnnotations` to false. - ### Other UI Elements @@ -382,6 +388,14 @@ plenty of them by running a backend command directly. To do so, first find the [`Debugger`](#debugger-console) console in the global area widget, type a command into the input box, and then press enter. +To run a backend command with the API, use the +[execute_backend_command](https://api.binary.ninja/binaryninja.debugger.debuggercontroller-module.html#binaryninja.debugger.debuggercontroller.DebuggerController.execute_backend_command) +API. For example, this will return all loaded modules (for LLDB adapter): + +```Python +dbg.execute_backend_command('image list') +``` + ### Hardware Breakpoints Hardware breakpoint is very useful and we plan to add better support for it soon. It is tracked by this diff --git a/docs/img/debugger/contextmenu.png b/docs/img/debugger/contextmenu.png index f5372aa..e5e06d6 100644 Binary files a/docs/img/debugger/contextmenu.png and b/docs/img/debugger/contextmenu.png differ diff --git a/docs/img/debugger/stacktracewidget.png b/docs/img/debugger/stacktracewidget.png index 51fec0d..e14b9eb 100644 Binary files a/docs/img/debugger/stacktracewidget.png and b/docs/img/debugger/stacktracewidget.png differ