A system of mappings, which is usually populated automatically, tracks the relationship of diff --git a/Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/GettingStarted.html b/Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/GettingStarted.html index 01910a582a..9509347486 100644 --- a/Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/GettingStarted.html +++ b/Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/GettingStarted.html @@ -13,36 +13,28 @@
During this testing phase, you will likely encounter many bugs, which is why these features - are not yet included in our binary release. As is, the debugger is poised to support debugging - native user-mode applications for Windows and Linux on 64-bit x86. This is accomplished by - "connecting" to the respective debugger for each platform: MS dbgeng.dll on Windows, and GDB/MI - on Linux. A variety of configurations are possible, and we are already developing more - connectors, but native desktop applications are the target for this initial roll-out. See the - Developer's Guide if you would like to contribute.
+The debugger is poised to support debugging native user-mode applications for Windows and + Linux on 64-bit x86. This is accomplished by "connecting" to the respective debugger for each + platform: MS dbgeng.dll on Windows, and GDB/MI on Linux. A variety of configurations are + possible, and we are already developing more connectors, but native desktop applications are + the target for this release.
There's still quite a bit of polish to get right, which is why this release is currently - source only. One of those areas deals with error handling and error reporting. Many actions are - taken automatically on behalf of the user, e.g., reading registers when a target is paused. In - most cases, errors on automatic actions are dropped to the console, as displaying them could - become a pest. That said, if things don't seem right, please check the Eclipse console for log - messages.
+Many actions are taken automatically on behalf of the user, e.g., reading registers when a + target is paused. In most cases, errors on automatic actions are dropped to the Debug Console, + as displaying them in a dialog could become a pest. That said, if things still don't seem + right, please check the application log messages.
Starting up the Ghidra Debugger for the simplest use case, user-mode debugging of a local - process, entails four steps:
+ process, entails two steps:To load the default Debugger tool, from the main Ghidra application window select
To launch the tool, you have several options, identical to those you might use to launch the
- CodeBrowser tool. You can double-click the Debugger icon to launch an empty Debugger tool. You
- can drag a program that you have already imported from the Active Project window onto the tool
- icon in the Tool Chest, or you can right-click on one of the project programs and pick . If you open an empty Debugger tool, you can add
+ CodeBrowser tool. You can click the Debugger icon to launch an empty Debugger tool. You can
+ drag a program that you have already imported from the Active Project window onto the tool icon
+ in the Tool Chest, or you can right-click on one of the project programs and pick Open With → Debugger. If you open an empty Debugger tool, you can add
programs to it later in the usual ways, e.g. via or by dragging-and-dropping programs onto the running tool.
Steps 3 and 4 can be initiated together by hitting the bug icon in the main tool bar - entitled "Debug /path/to/my_program". For this to work, you must (a) have the program you wish - to run visible and selected in the static Listing window, and (b) have imported the program - from the place it lives on the local system. In other words, the file path associated with the - program should be the path to the executable for the current file system. You can verify this - using the menu item in the main tool - bar. For example, on a Linux system, if you've imported "xclock", should have an entry at the bottom of the page for "Executable - Location: /usr/bin/xclock".
+For the "Debug" button to work, you must (a) have the program you wish to run visible and + selected in the static Listing window, and (b) have imported the program from the place it + lives on the local system. In other words, the file path associated with the program should be + the path to the executable for the current file system. You can verify this using the menu item in the main tool bar. For example, + on a Linux system, if you've imported "xclock", should have an entry at the bottom of the page for "Executable Location: + /usr/bin/xclock".
+ +Alternative launch options may be available using the dropdown next to the "Debug" button. + Furthermore, to access additional configuration options, use the menu options. The options selected here are saved and + applied for later launches, whether from the button or the menu.
When you launch the target by this method, a number of changes should be evident in the GUI. - A blank "Agent" window should appear, indicating the agent status and connection port. An - interpreter console will appear, potentially including various information about the launch. A - connection will be added to the Targets window. A new - tree-structure will be populated within the Targets window. A new tree + structure will be populated within the Objects window. The - remaining windows will be populated with current trace information.
+ remaining windows will be populated with current trace information. Please be patient, on some + platforms it may still take some time for things to populate and settle. The Debug Console + should provide some hints as to ongoing activity.Each of these pieces require some explanation.
+Some of the more commonly-access components are explained below. Many also have their own + help pages.
The "agent" is a process running on the local system, which acts as the mediator between the +
An "agent" is a process running on the local system, which acts as a mediator between the Ghidra GUI and the native debugger. For systems such as Linux that support GDB, the agent wraps the native GDB functionality via a Java container that implements the GDB machine interface (GDB/MI). For Windows, the agent wraps the native dbgeng.dll functionality in a similar @@ -101,38 +99,38 @@ agent dies or is killed, the debugging session will be terminated. Of particular note, the protocol used to communicate between the GUI and the agent is the Ghidra Asynchronous Debug Protocol (GADP). It is not the native protocol associated with the debugger. Direct - communications with a native target are not currently supported, although that functionality - may be added in the future.
+ communication with a native target is not currently supported, although that functionality may + be added in the future. If you choose an IN-VM connector, Ghidra will access the native + debugger directly, so no agent window will appear. This may be faster, but it also introduces + the risk of crashing Ghidra and losing data.The interpreter window allows a user command-line access to the native debugger. For Linux, this means the standard GDB command line interface; for Windows, the WinDbg/kd command set. While basic tasks may not require using the command line interface, more complicated debugging - scenarios invariably require commands specific to the target which cannot or have not been + scenarios invariably require commands specific to the target which have not or cannot be implemented generically in the GUI.
The "Debugger Targets" window adds an entry for every new GUI-to-agent connection. These may - be added directly from this window using the "Connect" button. This allows the user to select +
The "Debugger Targets" window adds an entry for every new debugger connection. These may be + added directly from this window using the "Connect" button. This allows the user to select non-default connection options and/or to initiate a connection without launching or attaching - to a target. For Linux, the default connection is equivalent to the menu choice, "GNU gdb local - agent via GADP/TCP". For Windows, the default is "MS dbgeng.dll (WinDbg) local agent via - GADP/TCP". Using this method of starting a connection requires the additional step of launching - or attaching to a specific target.
+ to a target. Using this method of starting a connection requires the additional step of + launching or attaching to a specific target.To launch or attach to a target without using the tool-bar "Debug" option, you will need to - use the "Objects" window. The "Objects" window provides a default tree-structured list of - everything the debugger knows about the target. On its tool bar are buttons for "Quick Launch', - "Launch", and "Attach". "Quick Launch", like the "Debug" button on the main tool bar, runs the - executable associated with the active program in the Listing view. "Launch" allows you to - specify a target and its parameters, typically, in the form of a command line. This target can - be any executable on the system and need not be associated with an imported program. The - "Attach" button populates a list with potential targets from the running process list for the - system, which the user may select and attach to.
+To launch or attach to a target without using the "Debug" button, you will need to use the + "Objects" window. The "Objects" window provides a default tree-structured list of everything + the debugger knows about the target. On its tool bar are buttons for "Quick Launch', "Launch", + and "Attach". "Quick Launch", like the "Debug" button on the main tool bar, runs the executable + associated with the active program in the Listing view. "Launch" allows you to specify a target + and its parameters, typically, in the form of a command line. This target can be any executable + on the system and need not be associated with an imported program. The "Attach" button + populates a list with potential targets from the running process list for the system, which the + user may select and attach to.
The control buttons in the Objects window or commands issued in the Interpreter cause the target to advance in the usual ways. (The control buttons in the Thread window, by contrast, cause the trace to move forward or backward without affecting the target.) Breakpoints can be - set from either the "Breakpoints" window or the listing. Breakpoints are typically aggregated - by target. The "Registers" and "Stack" display, on the other hand, reflect the selected thread - from the "Threads" window. Typically, the thread selected for the trace in the Threads display - is kept in sync with the active thread for the debugger selected in the Objects view, but this - need not be the case. Similarly, the "Dynamic Listing", marked RIP or RSP in most case, shows - the bytes from the target's actual memory and may or may not match the bytes from the imported - executable in the primary "Listing". When it can, the Ghidra debugger attempts to keep the - Static and Dynamic Listings synchronized.
+ set from either the "Breakpoints" window or the listing. The "Registers" and "Stack" display + reflect the state of the selected thread from the "Threads" window. Typically, the thread + selected for the trace in the Threads display is kept in sync with the active thread for the + debugger selected in the Objects view, but this need not be the case. Similarly, the "Dynamic + Listing" shows the bytes from the target's actual memory, which may or may not match the bytes + from the imported executable in the primary "Listing". When it can, the Ghidra debugger keeps + the Static and Dynamic Listings synchronized. + +This console is a central place for reporting activity, errors, and suggesting actions. This + is the first place to look when troubleshooting.