Mirrors_Framework/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra.git synced 2026-05-24 01:16:22 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

GP-983: Updated Debugger Help

Browse Source
This commit is contained in:
d-millar
2021-06-04 16:09:35 -04:00
committed by Dan
parent 5808049c83
commit de437c2ad5
33 changed files with 486 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Ghidra/Debug/Debugger/certification.manifest
+1
View File
@@ -38,6 +38,7 @@ src/main/help/help/topics/DebuggerBreakpointsPlugin/images/breakpoint-mixed-ed.p
src/main/help/help/topics/DebuggerBreakpointsPlugin/images/breakpoints-clear-all.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerBreakpointsPlugin/images/breakpoints-disable-all.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerBreakpointsPlugin/images/breakpoints-enable-all.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerBreakpointsPlugin/images/breakpoints-make-effective.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html||GHIDRA||||END|
src/main/help/help/topics/DebuggerConsolePlugin/images/DebuggerConsolePlugin.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerInterpreterPlugin/DebuggerInterpreterPlugin.html||GHIDRA||||END|
Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/Debugger.html
+1 -1
View File
@@ -26,7 +26,7 @@
user. The user can rewind this recording at any point and the UI will recall those
observations, displaying the recorded machine state instead of the present machine state. These
traces can also be saved, loaded, and analyzed after a target has terminated or been
disconnected. Furthermore, they can be commited to a Ghidra Server for sharing and revision
disconnected. Furthermore, they can be committed to a Ghidra Server for sharing and revision
control; however, conflicting changes <EM>cannot</EM> be merged.</P>
<P>A system of mappings, which is usually populated automatically, tracks the relationship of
Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/GettingStarted.html
+73 -70
View File
@@ -13,36 +13,28 @@
<BODY lang="EN-US">
<H1>Debugger: Getting Started</H1>
<P>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.</P>
<P>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.</P>
<H2>Pay Attention to Errors</H2>
<P>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.</P>
<P>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.</P>
<H2><A name="launching">Launching a Target</A></H2>
<P>Starting up the Ghidra Debugger for the simplest use case, user-mode debugging of a local
process, entails four steps:</P>
process, entails two steps:</P>
<OL>
<LI>Load the default Debugger tool</LI>
<LI>Open (or import) your program into the Debugger tool</LI>
<LI>Launch the tool and populate it with the executable you want to debug</LI>
<LI>Start the agent</LI>
<LI>Start the target process</LI>
<LI>Click the "Debug" button ("bug" icon) in the main toolbar</LI>
</OL>
<P>To load the default Debugger tool, from the main Ghidra application window select <SPAN
@@ -51,10 +43,10 @@
Chest.</P>
<P>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 <SPAN
class="menu">Open With &rarr; Debugger</SPAN>. 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 <SPAN class=
"menu">Open With &rarr; Debugger</SPAN>. If you open an empty Debugger tool, you can add
programs to it later in the usual ways, e.g. via <SPAN class="menu">File &rarr; Import
File...</SPAN> or by dragging-and-dropping programs onto the running tool.</P>
@@ -65,35 +57,41 @@
should already be selected. Choosing "Configure All Plugins" (the plug icon near the top
right), should show the full list of pre-selected plugins. Debugger-related plugins all begin
with "Debugger". At a bare minimum, you will need the "DebuggerTargetsPlugin" and the
"DebuggerObjectsPlugin", and the plugins on which they depend (DebuggerInterpreterPlugin,
DebuggerModelServiceProxyPlugin, DebuggerTraceMangerServicePlugin).</P>
"DebuggerObjectsPlugin", and the plugins on which they depend.</P>
<P>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 <SPAN class="menu">Help &rarr; About my_program</SPAN> menu item in the main tool
bar. For example, on a Linux system, if you've imported "xclock", <SPAN class="menu">Help
&rarr; About xclock...</SPAN> should have an entry at the bottom of the page for "Executable
Location: /usr/bin/xclock".</P>
<P>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 <SPAN
class="menu">Help &rarr; About my_program</SPAN> menu item in the main tool bar. For example,
on a Linux system, if you've imported "xclock", <SPAN class="menu">Help &rarr; About
xclock...</SPAN> should have an entry at the bottom of the page for "Executable Location:
/usr/bin/xclock".</P>
<P>Alternative launch options may be available using the dropdown next to the "Debug" button.
Furthermore, to access additional configuration options, use the <SPAN class="menu">Debugger
&rarr; Debug program &rarr; ...</SPAN> menu options. The options selected here are saved and
applied for later launches, whether from the button or the menu.</P>
<P>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 <A href=
"help/topics/DebuggerTargetsPlugin/DebuggerTargetsPlugin.html">Targets</A> window. A new
tree-structure will be populated within the <A href=
A blank "Agent" window may appear, indicating the agent status and connection port (if GADP was
selected). An interpreter console will appear, potentially including various information about
the launch. A connection will be added to the <A href=
"help/topics/DebuggerTargetsPlugin/DebuggerTargetsPlugin.html">Targets</A> window. A new tree
structure will be populated within the <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html">Objects</A> window. The
remaining windows will be populated with current trace information.</P>
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.</P>
<H2>Debugger Components</H2>
<P>Each of these pieces require some explanation.</P>
<P>Some of the more commonly-access components are explained below. Many also have their own
help pages.</P>
<H3>Debugging Agent</H3>
<P>The "agent" is a process running on the local system, which acts as the mediator between the
<P>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.</P>
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.</P>
<H3>Interpreter</H3>
<P>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.</P>
<H3>Targets / Connections</H3>
<P>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
<P>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.</P>
to a target. Using this method of starting a connection requires the additional step of
launching or attaching to a specific target.</P>
<H3>Objects</H3>
<P>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.</P>
<P>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.</P>
<H3>Traces and Threads</H3>
@@ -146,20 +144,25 @@
empty. If the current position (indicated by the draggable caret at the top of the right
display) lies outside the bounds of the current trace, all of the remaining windows will be
empty. Selecting a thread and a position causes the trace-based windows to display information
for that thread and time tick.</P>
for that thread and time. From this window, the "step" buttons can be used to simulate target
execution to some extent.</P>
<H3>Commands / Miscellany</H3>
<P>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.</P>
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.</P>
<H3>Console</H3>
<P>This console is a central place for reporting activity, errors, and suggesting actions. This
is the first place to look when troubleshooting.</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/Troubleshooting.html
+84 -19
View File
@@ -13,13 +13,17 @@
<BODY lang="EN-US">
<H1>Debugger: Troubleshooting</H1>
<P>Often, it's a good idea to troubleshoot starting with your platform's native debugger. If it
doesn't work there, it's not likely to work in Ghidra, since it relies on that debugger. For
Linux, this is GDB; for Windows, this is WinDbg.</P>
<H2>Error Console</H2>
<P>The first place to look when you're having trouble is the Debug Console. Second, if you're
in Eclipse, you can check its "Console" window. Often, Ghidra's Debug Console will offer
actions to help you resolve a well-known issue or configuration problem. It also duplicates the
error log, when those messages are emitted from a debugger-related class. These typically offer
clues to exactly what has gone wrong.</P>
running from Eclipse, you can check its "Console" window. Often, Ghidra's Debug Console will
offer actions to help you resolve a well-known issue or configuration problem. It also
duplicates the error log when those messages are emitted from a debugger-related component.
These typically offer clues to exactly what has gone wrong.</P>
<H2>Settings and Toggles</H2>
@@ -50,7 +54,7 @@
trigger the trace. If auto-record is toggled off, you'll need to hit "Record (R)" with the
process selected to start a trace.</LI>
<LI>"Subscribe to..." causes a particular obejct to be tracked by the trace. Processes,
<LI>"Subscribe to..." causes a particular object to be tracked by the trace. Processes,
threads, registers, memory, stack, and so forth are tracked automatically, but you may wish
to add other objects ad hoc.</LI>
</UL>
@@ -58,24 +62,74 @@
<P>In the Threads provider:</P>
<UL>
<LI>The "Track...to latest snap" toggle determines whether the caret (and all resulting
information) should track the current thread position as it updates.</LI>
<LI>The "Track the tool to the latest snap" toggle determines whether the caret (and all
resulting information) should track the current thread position as it updates.</LI>
<LI>The "Set to automatically save..." toggle causes traces to be saved into the Ghidra
program database at the end of a session. (Open sessions will be re-opened with the tool in
the Threads window, reflected in the thin tabs at its top.)</LI>
<LI>The "Synchronize..." toggle attempts to maintain synchronization between the Object
provider (i.e. the active target information) and the trace.</LI>
<LI>The "Synchronize trace activation..." toggle attempts to maintain synchronization between
the Object provider (i.e. the active target information) and the trace.</LI>
</UL>
<P>In the Debugger menu:</P>
<UL>
<LI>The "Save Traces By Default" toggle causes traces to be saved into the Ghidra project
database at the end of a session. (Open sessions will be re-opened with the tool in the
Threads window, reflected in the thin tabs at its top.)</LI>
</UL>
<H1><A name="faq">Frequently Asked Questions / Common Problems</A></H1>
<H2><A name="no_executable">I Can't Launch the Current Program</A></H2>
<P>This happens when the local launchers cannot locate the original executable from which the
current program was imported. Furthermore, if the user account under which Ghidra is running
does not have permission to execute the original executable, the local launchers will not make
offers to execute it. First, use <SPAN class="menu">Help &rarr; About [program]</SPAN> to check
the path of the executable. If it was imported from an older version of Ghidra, it may not be
correctly recorded. Verify that the file exists on the local system and can be executed. You
may need to close and re-open the program database or just switch program tabs back and forth
to get the launchers to re-assess their offers.</P>
<H2><A name="gdb_mising">I Can't Launch With GDB</A></H2>
<P>Ghidra does not come packaged with any 3rd-party debuggers. It relies on what is already
available on the local system. If you're trying to debug on Linux, and you only see the "GDB
over SSH" launcher, it's likely because the local launchers could not find your copy of GDB.
Either you don't have one installed, or it's not in its usual place. First verify GDB is
installed and that you can run it from your shell's command line. We recommend version 8 or
better. Second, click the "Connect" button in the "Targets" window, select the desired GDB
connector and configure GDB's path appropriately. Then, click "Connect" and verify the
connection is created successfully. You should now be able to use the "Quick Launch" button in
the "Objects" window to launch the current program. Furthermore, the now-configured connector
should make offers in the "Debug Program" menu and the "Debug" drop-down button.</P>
<P>If you're trying to debug using GDB on Windows, please consider using WinDbg (dbgeng.dll)
instead. If you insist on GDB, then there is a workaround, but it may take some work. We have
not yet implemented a pseudo-terminal wrapper for Windows, which is needed to communicate with
GDB/MI and support interrupts. The work-around is to use the "GDB over SSH" connector, but
you'll need to install an SSH server for Windows. There are a variety of options, including
WSL, Cygwin, and MSYS.</P>
<H2><A name="ssh_key_exchange">I Can't Connect to GDB Over SSH</A></H2>
<P>First, verify that you can SSH into the target system and execute GDB via your shell's
command line. If that works, but Ghidra still can't connect, then it's likely an issue with
allowed / supported key exchange algorithms. Ghidra currently uses Ganymed SSH v262, which
(unfortunately) supports very few (likely outdated) algorithms, and those algorithms are
removed from the default SSH configuration of more recent Linux distributions. One solution is
to replace the Ganymed JAR file with a patched one. There is a "v263," which supports more
algorithms, but it is not available in Maven Central, and is not created by Ganymed's original
maintainers. A second solution is to change the target system's SSH configuration to allow the
older algorithms. At some point, we may convert our connector to use JSch instead, since it's
actively maintained.</P>
<H2><A name="breakpoints_ineffective">My Breakpoints Aren't Working</A></H2>
<P>If your target is not breaking as expected, chances are the breakpoint has not actually been
sent to the debugger. Breakpoints in the static listing are not necessarily effective for a
target. Many things depend on tracing and module mapping to work correctly. Occasionally,
either because of configuration options, or some other hiccup, these dependencies are not met.
Futhermore, Ghidra can only send breakpoints to a target while it is suspended. If you are
Furthermore, Ghidra can only send breakpoints to a target while it is suspended. If you are
trying, for example, to break before "main", you must ensure Ghidra has a chance to place the
breakpoint before the target would reach it. This may require using the command interpreter or
changing your native debugger's options. Otherwise, verify that you are actually tracing the
@@ -88,8 +142,20 @@
the case, right-click your target in the <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html">Objects</A> window and select
"Record". Please note that this action is enabled on any object, but is ignored if nothing
knows how to record it. Currently, only user-mode processes running on a 64-bit x86 system are
known to work well. Be sure you have selected the process, not a thread.</P>
knows how to record it. Recorders typically examine the object and its environment (i.e.,
debugger name, target operating system, architecture) to determine if and how to record it. Be
sure you have selected the process, not a thread.</P>
<H2>I Click Record, but I Get an Empty Dialog</H2>
<P>That dialog is meant to display a list of offers for recording the selected target. If it's
empty, it's because nothing knows how to record it. Most likely, this means the target
environment (arch, os, etc.) is not recognized. Rarely, this is an error in the connector,
which may incorrectly report the target environment. Less rarely, the native debugger requires
the user to manually specify the target platform. Most likely, the target environment is simply
not supported by Ghidra, yet. If Ghidra supports the target processor, this can usually be
resolved by coding up a new opinion, selecting the correct Ghidra language and compiler spec
(ABI) for the environment as reported by the debugger connection.</P>
<H2>My Modules are not Mapped in</H2>
@@ -102,8 +168,7 @@
<A href="help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html">Modules</A> window.
Right-click the module where you expected to sync and select "Map Modules." If you do not see
the program you expected, it may be because it is not named in a way that Ghidra would
recognize it as the given module. Currently, the program's name must contain (case insensitive)
the module's filename (ignoring the full path). A user action to remedy this is a known feature
gap.</P>
recognize it as the given module. To force Ghidra to map a module to the current program,
select "Map Module to ...."</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBots/DebuggerBots.html
+1 -1
View File
@@ -13,7 +13,7 @@
<BODY lang="EN-US">
<H1>Debugger Bots: Workflow Automation</H1>
<P>Bots a are pluggable part of the Debugger's Workflow plugin and provide useful automation,
<P>Bots are a pluggable part of the Debugger's Workflow plugin and provide useful automation,
taking actions on the user's behalf that would otherwise be tedious, or that should occur
"under the hood." Each can be toggled from the <SPAN class="menu">Edit &rarr; Tool
Options</SPAN> menu in Ghidra's <EM>Project</EM> window.</P>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html
+8 -7
View File
@@ -48,9 +48,9 @@
cursor, this will prompt to set one, giving a reasonable set of default parameters based on the
context at the cursor. At an instruction, it will prefer to set a Software Execution
breakpoint. At defined data, it will prefer to set a Read/Write breakpoint of the size of data.
At undefined data, or if the target does not support the suggested default, an error dialog is
presented. Please use one of the Set Breakpoint actions to force specific commands. Please
beware: the default parameters are not always acceptable to the connected debugger.</P>
At undefined data, or if the target does not support the suggested default, the default kind is
left unselected. Please use one of the Set Breakpoint actions to force specific commands.
Please beware: the default parameters are not always acceptable to the connected debugger.</P>
<H3><A name="set_breakpoint"></A><IMG alt="" src="images/breakpoint-enable.png"> Set
Breakpoint</H3>
@@ -78,7 +78,7 @@
the instruction or data at the cursor.</LI>
<LI>Length - the length in bytes of the breakpoint. Some debuggers for some kinds of
breakpoints, may not allow a value other than 1. For execution breakpoints, this defaults to
breakpoints may not allow a value other than 1. For execution breakpoints, this defaults to
1; for access breakpoints, this defaults to the size of the data at the cursor.</LI>
<LI>Kinds - the kind(s) of breakpoint. Only the reasonable combinations are presented, but
@@ -106,8 +106,9 @@
<H2><A name="colors"></A>Tool Options: Colors</H2>
<P>The background coloring of enabled and disabled breakpoints can be configured in the tool's
options. By default, enabled breakpoints are colored a de-saturated red, while disabled
breakpoints have no background color at all.</P>
<P>The background coloring of enabled and disabled, effective and ineffective breakpoints can
be configured in the tool's options. By default, enabled breakpoints are colored a desaturated
red, ineffective breakpoints are colored grey, and disabled breakpoints have no background at
all.</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html
+23 -16
View File
@@ -69,23 +69,21 @@
<LI>Enabled - displays an icon indicating the state of the breakpoint. Clicking the icon
toggles the breakpoint.</LI>
<LI style="list-style: none">
<UL>
<LI><IMG alt="" src="images/breakpoint-enable.png"> Enabled</LI>
<UL style="list-style-type: none">
<LI><IMG alt="" src="images/breakpoint-enable.png"> Enabled</LI>
<LI><IMG alt="" src="images/breakpoint-disable.png"> Disabled</LI>
<LI><IMG alt="" src="images/breakpoint-disable.png"> Disabled</LI>
<LI><IMG alt="" src="images/breakpoint-mixed-ed.png"> Inconsistent: Enabled with disabled
locations</LI>
<LI><IMG alt="" src="images/breakpoint-mixed-ed.png"> Inconsistent: Enabled with disabled
locations</LI>
<LI><IMG alt="" src="images/breakpoint-mixed-de.png"> Inconsistent: Disabled with enabled
locations</LI>
<LI><IMG alt="" src="images/breakpoint-mixed-de.png"> Inconsistent: Disabled with enabled
locations</LI>
<LI><IMG alt="" src="images/breakpoint-ineffective-e.png"> Enabled but ineffective</LI>
<LI><IMG alt="" src="images/breakpoint-ineffective-e.png"> Enabled but ineffective</LI>
<LI><IMG alt="" src="images/breakpoint-ineffective-d.png"> Disabled and ineffective</LI>
</UL>
</LI>
<LI><IMG alt="" src="images/breakpoint-ineffective-d.png"> Disabled and ineffective</LI>
</UL>
<LI>Image - gives the name of the Ghidra program, if the breakpoint is mapped to one.</LI>
@@ -96,8 +94,8 @@
<LI>Length - usually 1. For access breakpoints, this notes the length in bytes of the address
range.</LI>
<LI>Kinds - indicates the kind(s) of breakpoint: Software (execution), Execution (hardware),
Read (hardware), and/or Write (hardware).</LI>
<LI>Kinds - indicates the kind(s) of breakpoint: SW_EXECUTE, HW_EXECUTE, READ, and/or
WRITE.</LI>
<LI>Locations - counts the number of trace locations mapped to this logical breakpoint,
applying the trace filter if active. Note that a logical breakpoint with 0 locations is
@@ -155,7 +153,15 @@
<P>This action is always available. It disables every breakpoint. For any breakpoint that is
already disabled, no action is taken.</P>
<H3><A name="clear_breakpoints"></A><IMG alt="" src="images/breakpoint-enable.png"> Clear
<H3><A name="make_breakpoints_effective"></A><IMG alt="" src=
"images/breakpoints-make-effective.png"> Make Breakpoints Effective</H3>
<P>This action is available whenever there are mapped breakpoints with 0 locations, i.e., it
corresponds to a target location where the breakpoint is still missing. It places such
breakpoints where possible. This action is also offered as a resolution in the console. It
appears in the log any time this action is available.</P>
<H3><A name="clear_breakpoints"></A><IMG alt="" src="images/breakpoint-clear.png"> Clear
Selected Breakpoints</H3>
<P>This action is available when one or more breakpoints or locations are selected. It clears
@@ -164,7 +170,8 @@
<H3><A name="clear_all_breakpoints"></A><IMG alt="" src="images/breakpoints-clear-all.png">
Clear All Breakpoints</H3>
<P>This action is always available. Use with caution! It deletes every breakpoint.</P>
<P>This action is always available. <FONT color="red">Use with caution!</FONT> It deletes every
breakpoint.</P>
<H2>Filter Actions</H2>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointsPlugin/images/DebuggerBreakpointsPlugin.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 28 KiB

Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointsPlugin/images/breakpoints-make-effective.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 381 B

Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html
+5 -1
View File
@@ -26,7 +26,7 @@
configuration, this can comprise a wide range of components, including all GUI views, active
connectors, and running agents. Currently, it implements an appender to gather all Log4J
messages emitted by Ghidra and filters for debugger-related packages and a level in the range
INFO through and including FATAL. That feature will likely be removed as more components are
INFO through FATAL, inclusive. That feature will likely be removed as more components are
programmed to work directly with the console. Soon, it may also provide a command-line
interface to control Ghidra's debugging sessions and interact with traces.</P>
@@ -64,5 +64,9 @@
<H3><A name="clear"></A>Clear</H3>
<P>Removes all messages, including actionable messages, from the log.</P>
<H3><A name="select_none"></A>Select None</H3>
<P>Resets the selection, usually so table scrolling can be restored to "normal."</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerInterpreterPlugin/DebuggerInterpreterPlugin.html
+2 -2
View File
@@ -28,11 +28,11 @@
<H3><A name="Clear_Interpreter"></A>Clear Interpreter</H3>
<P>This action is always available. It clears the console's ouput buffer.</P>
<P>This action is always available. It clears the console's output buffer.</P>
<H3><A name="Remove_Interpreter"></A>Remove Interpreter</H3>
<P>This action appears when the target's interpreter is not longer valid, i.e., the connection
<P>This action appears when the target's interpreter is no longer valid, i.e., the connection
was closed. It permanently closes the console. Note this action can only appear if this console
was pinned.</P>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html
+21 -14
View File
@@ -25,10 +25,10 @@
<P><A name="Toggle_Header"></A>The dynamic listing is analogous to Ghidra's listing for static
analysis, but in the dynamic context. That is, it displays memory contents from a target. More
precisely, it displays recorded memory contents in a trace. In most use cases, that trace is
"at the present", meaning it is the most recent memory from a live target. Multiple listings
"at the present," meaning it is the most recent memory from a live target. Multiple listings
can be displayed simultaneously, using the same pattern as many other Ghidra windows. The
"primary" listing is always displayed and generally tracks with the rest of the tool. Any
listing can be "snapshotted", i.e., duplicated. This is where dynamic listings differ from
listing can be "snapshotted," i.e., duplicated. This is where dynamic listings differ from
static listings. Static snapshots remain in place; they do not automatically navigate. Dynamic
snapshots can still be configured to navigate, following the rest of the tool. A common use is
to configure a "snapshot" to follow the stack pointer. Still, you can disable a listing's
@@ -43,20 +43,20 @@
mark-up is added to the listing, it exists "from this time on". That is, its time interval is
from the current time to infinity, i.e., it has been created but never destroyed. When mark-up
is removed from the listing, its "destruction time" is set to just before the current time. If
this would cause the mark-up to "never exist", i.e., its destruction time is equal to its
creation time, then the record is deleted altogether. This yields a mostly-intuitive mechanism
for marking things up "in time," but the fact that mark-up is bound in time can still be
this would cause the mark-up to "never exist," i.e., its destruction time precedes its creation
time, then the record is deleted altogether. This yields a mostly-intuitive mechanism for
marking things up "in time," but the fact that mark-up is bound in time can still be
surprising. For example, disassembling some instructions and then stepping back in time will
cause that disassembly to disappear.</P>
<P>Because not all memory is captured, some background coloring is used to indicate the state
of attempted memory reads. Regardless of state, the most-recent contents, as recorded in the
trace, or 0s are displayed in the listing. "Stale" memory, that is ranges of memory which have
not been read at the current time, are displayed with a darker background. Where that memory is
marked "read-only" and has been successfully read previously, that coloring is subdued, since
the contents are unlikely to have changed. Where a read was attempted but failed, the range is
displayed with a pink background. Otherwise, up-to-date contents are displayed with the default
background color.</P>
trace, are displayed in the listing, defaulting to 00. "Stale" memory, that is ranges of memory
which have not been read at the current time, are displayed with a darker background. Where
that memory is marked "read-only" and has been successfully read previously, that coloring is
subdued, since the contents are not likely to have changed. Where a read was attempted but
failed, the first address in the failed range is displayed with a pink background. Otherwise,
up-to-date contents are displayed with the default background color.</P>
<H2>Actions</H2>
@@ -110,9 +110,9 @@
<P>This action is available whenever a trace is active in the listing. It prompts the user for
an address, which can be expressed in Sleigh, then attempts to navigate to it. The expression
is evaluated in the context of the current thread and point in time. If the current trace is
live and at the present, the target may be queried to retrieve any machine state required to
evaluate the expression.</P>
is evaluated in the context of the current thread, frame, and point in time. If the current
trace is live and at the present, the target may be queried to retrieve any machine state
required to evaluate the expression.</P>
<TABLE width="100%">
<TBODY>
@@ -135,6 +135,13 @@
static location, the listing logs a "missing module" to the console, offering either to import
the module or map it to an existing program.</P>
<H3><A name="open_program"></A>Open Program</H3>
<P>This action is offered as a resolution whenever a module cannot be automatically opened.
This typically happens when the module's program database has crash data that can be recovered
and/or needs a version upgrade. It will attempt to open the program, allowing Ghidra to prompt
you about the situation.</P>
<H3><A name="capture_memory"></A>Capture Memory</H3>
<P>This action is available when the current trace is "at the present" with a live target, and
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerMemviewPlugin/DebuggerMemviewPlugin.html
+10 -10
View File
@@ -17,13 +17,13 @@
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerMemviewPlugin.png" style="width:100%"></TD>
"images/DebuggerMemviewPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<P>As in the Threads view, you may wish to follow the evolution of various objects over time.
The Debugger Memview Plugin provides a generic time vs. memory (or memory vs. time) plot of
The memory viewer window provides a generic time vs. address (or address vs. time) plot of
objects marked as of interest. The plot may be populated from either a script, typically
processing an entire trace, or updated on-the-fly from a live target trace. The objects are
listed in the viewer's table on the left for the purpose of quick identification and sorting,
@@ -37,7 +37,7 @@
corner to get an accurate tool tip. Points past the maximum time or address will not display
values for that coordinate.</P>
<H2>Memview Table</H2>
<H2>Table</H2>
<P>The table on the right provides the standard Ghidra table-style interface listing each
object, its starting and ending times and starting and ending addresses, if available. Clicking
@@ -46,14 +46,14 @@
corner of the corresponding object in the panel. Applying the filter will redisplay only the
selected objects in the panel, if that option is enabled.</P>
<H2>Memview Panel</H2>
<H2>Plot Panel</H2>
<P>The panel displays all of the object in the table or the table's selection, depending on the
options enabled. Clicking on the panel will set the red arrow at that position and display the
current position in the title. Doubling-clicking on object will cause it to be centered in the
display. The size of the panel can be expanded or contracted on either axis with the Zoom
buttons. The top left corner of the panel (which may or may not be visible depending on
scrolling) always corresponds to the first address and the first tick. Scroll bars are enabled
scrolling) always corresponds to the first address and the first snap. Scroll bars are enabled
if any object lies outside the viewable portion of the panel. Drag&amp;drop can also be used to
position the panel view. Ctrl-drag&amp;drop draws a box around a region of the display, and the
enclosed objects are selected in the table.</P>
@@ -66,19 +66,19 @@
<H3><A name="toggle_layout"></A><IMG alt="" src="images/view-refresh.png">Toggle Layout</H3>
<P>The default panel view is time vs address. The toggle button serves as both the way to
<P>The default panel view is time vs. address. The toggle button serves as both the way to
switch views and to refresh the display.</P>
<H3><A name="toggle_process_trace"></A><IMG alt="" src="images/sync_enabled.png">Toggle Process
Trace</H3>
<P>By default, as new objects are added to a debugger trace, they appear in the Memview table
and panel. The behavior can be toggled on or off at the user's discretion.</P>
<P>By default, as new objects are added to a debugger trace, they appear in the table and
panel. The behavior can be toggled on or off at the user's discretion.</P>
<H3><A name="apply_to_panel"></A><IMG alt="" src="images/filter_off.png">Toggle Apply
Filter</H3>
<P>This button determines whether the table filter affects the display panel. When toggled on,
only selected objects are displayed in the panel.</P>
<P>This button determines whether the table filter affects the plot panel. When toggled on,
only objects listed in the table are displayed in the plot.</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModelServicePlugin/DebuggerModelServicePlugin.html
+14 -11
View File
@@ -27,17 +27,17 @@
<P>This group of actions is available whenever there exists a debug launcher that knows how to
run the current program. Various launchers may all make offers to run the current program, each
of which is presented as a item in this group. Not all offers are guaranteed to work. For
example, an offer to launch the program remotely via SSH depends on the host's availability and
the user's credentials. The offers are ordered by most recent activation. The most recent offer
used is the default one-click launcher for the current program. Each launcher may check various
conditions before making an offer. Most commonly, it will check that there is a suitable
debugger for the current program's architecture (language) on the local system, that the
program's original executable image still exists on disk, and that the user has permission to
execute it. A launcher may take any arbitrary action to run the program. Most commonly, it
starts a new connection suitable for the target, and then launches the program on that
connection. If <A href=
example, an offer to launch the program remotely via SSH depends on the host's availability,
the user's credentials, and the presence of the target binary on the host. The offers are
ordered by most recent activation. The most recent offer used is the default launcher for the
current program. Each launcher may check various conditions before making an offer. Most
commonly, it will check that there is a suitable debugger for the current program's
architecture (language) on the local system, that the program's original executable image still
exists on disk, and that the user has permission to execute it. A launcher may take any
arbitrary action to run the program. Most commonly, it starts a new connection suitable for the
target, and then launches the program on that connection. If <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html#record_automatically">Record
Automatically</A> is enabled, this will provide a one-click action to debug the current
Automatically</A> is enabled, this will provide a single-click action to debug the current
program. This is similar to the <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html#quick_launch">Quick Launch</A>
action in the Commands and Objects window, except this one does not require an existing
@@ -53,6 +53,9 @@
<H3><A name="disconnect_all"></A> Disconnect All</H3>
<P>This action is always available from the main application window. It closes all debugger
connections, no matter what tool created them. This is a sort of panic and reset action.</P>
connections, no matter what tool created them. This is a sort of panic and reset action. NOTE:
A complete and total reset is not always possible. Some connectors may load native libraries
into Ghidra's JVM. Unless that connector is careful to reset that library's state, subsequent
connections could be affected.</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html
+11 -9
View File
@@ -23,13 +23,13 @@
</TABLE>
<P>The concept of a module may vary from platform to platform, but in most cases, it refers to
a binary image which is loaded or mapped into memory. Likely, these are the same files that
Ghidra can import for static analysis. Similarly, the concept of a section may vary, but in
most cases, it refers to a portion of a module, possibly backed by its binary image. This
window displays information about modules, and sometimes their sections, known to the connected
debugger. Information in this window reflects what has been recorded into the current trace,
which in turn comes from a target. The top table displays module information, and the bottom
table displays section information.</P>
a binary image which is loaded or mapped into memory comprising some portion of the target's
executable code. Likely, these are the same files that Ghidra can import for static analysis.
Similarly, the concept of a section may vary, but in most cases, it refers to a portion of a
module, possibly backed by its binary image. This window displays information about modules,
and sometimes their sections, known to the connected debugger. Information in this window
reflects what has been recorded into the current trace, which in turn comes from a target. The
top table displays module information, while the bottom table displays section information.</P>
<H2>Table Columns</H2>
@@ -42,6 +42,8 @@
<LI>Max Address - if available, the maximum address where the module is mapped in the
target's memory. Double-clicking this field navigates to the address.</LI>
<LI>Name - a short name for the module, typically its file name.</LI>
<LI>Module Name - the name of the module, ideally its full path on the target's
filesystem.</LI>
@@ -147,12 +149,12 @@
<H3><A name="import_missing_module"></A>Import Missing Module</H3>
<P>This action is offered to resolve a "Missing Module" console message. It is equivalent to <A
<P>This action is offered to resolve a "missing module" console message. It is equivalent to <A
href="#import_from_fs">Import From File System</A> on the missing module.</P>
<H3><A name="map_missing_module"></A>Map Missing Module</H3>
<P>This action is offered to resolve a "Missing Module" console message. It is equivalent to <A
<P>This action is offered to resolve a "missing module" console message. It is equivalent to <A
href="#map_module_to">Map Module To</A> on the missing module.</P>
<H3><A name="filter_by_module"></A>Filter Sections by Module</H3>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModulesPlugin/images/DebuggerModulesPlugin.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 28 KiB

Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html
+81 -84
View File
@@ -21,8 +21,8 @@
</TBODY>
</TABLE>
<P>The Debugger's Objects window permits the user to interact directly with a connected
debugger and its targets. Along with the command-line, it is the primary mechanism for issuing
<P>The Objects window permits the user to interact directly with a connected debugger and its
targets. Along with the command-line interpreter, it is the primary mechanism for issuing
commands, e.g., <B>step</B>, to a target. Commands are accessible from the tool bar, the
pull-down, and pop-up menus. Commands are enabled in two ways: (1) the object selected has a
property that marks it as a logical target for that command, or (2) the object has an ancestor
@@ -38,44 +38,34 @@
<P>The application of these special properties to each object to determine its behavior and
relevant actions allows all objects to be treated generically. This feature has several
powerful implications. All objects may be represented in many ways, and one representation may
easily be converted into another. The default representation is a tree, and the Debugger's
Objects plugin starts with a tree to represent a debugger session's state. Any portion of the
tree may be reproduced as its own subtree or as a table or as a graph using the <A href=
"DebuggerObjectsPlugin.html#display_as">Display as...</A> actions. Any portion of display may
equally be exported or imported from the plugin. The generic aspect of all objects also allows
easily be converted into another. The default representation is a tree, and the Objects plugin
starts with a tree to represent a debugger session's state. Any portion of the tree may be
reproduced as its own subtree or as a table or as a graph using the <A href=
"DebuggerObjectsPlugin.html#display_as">Display as...</A> actions. Any portion of the display
may be exported from or imported into the plugin. The generic aspect of all objects also allows
the user to process them in scripts or plugins in common ways. For example, you could write a
script to walk the entire tree and find objects with "File" in the name or with the value
0xDEADBEEF.</P>
<P>The hierarchy reflected in the initial display has either been derived from the target, as
in the case of WinDbg v.2's dbgmodel engine, or imposed by the designers of the current
"model". The model is the schema chosen by the authors for a particular debugger target. It
usually mirrors to some extent the underlying relationships in the native debugger, but need
not, and is usually fixed for that target. (In the future, we intend to expose this schema and
allow it to be transformed by the user.) Commands executed within this plugin are passed from
the GUI through the model to the target manager and on to the agent which makes the required
native calls. In general, this plugin does not operate on any object in a trace or controlled
by a recorder, except for actions which initiate a recording or add objects to a recording.</P>
is the case with WinDbg Preview's dbgmodel.dll engine, or imposed by the designers of the
current connector's "model." The model has a type schema chosen by the authors for a particular
debugger target. It usually mirrors to some extent the underlying relationships in the native
debugger, but need not, and is usually fixed for that target. Commands executed within this
plugin are passed from the GUI through the model, typically manifesting in native API calls, or
commands sent to a special interpreter of the debugger. This plugin does not operate on traces,
except for actions which initiate a recording.</P>
<H3><A name="console"></A><IMG alt="" src="images/console.png"> Console</H3>
<P>Shows the console for the selected context, usually the debugger's command-line interpreter.
Some models may also present a target's standard I/O via a console.</P>
<H2>Target Management</H2>
<P>The following actions manage targets, e.g., processes, within a connected debugger.</P>
<H2>Actions for Target Management</H2>
<H3><A name="quick_launch"></A><IMG alt="" src="images/debugger.png"> Quick Launch</H3>
<P>Launch a new target using the current program.</P>
<P>This action is the fastest and probably most common way of starting a debugger target. The
action attempts to launch the program in the currently selected tab of the static listing
window. The success of the action depends on the program being associated with an existing
executable file on the local system. The value associated with the program may, of course, be
checked using the <A href="help/topics/About/About_Program_File.htm">About Program File</A>
function.</P>
<P>Launches a new target using the current program. This action is the fastest and probably
most common way of starting a debugger target on an existing connection. The action attempts to
launch the program in the currently selected tab of the static listing window. The success of
the action depends on the program being associated with an existing executable file on the
local system. The value associated with the program may, of course, be checked using the <A
href="help/topics/About/About_Program_File.htm">About Program File</A> function.</P>
<H3><A name="launch"></A><IMG alt="" src="images/launch.png"> Launch</H3>
@@ -87,7 +77,7 @@
for the platform.</P>
<P>For example, the CommandLineLaunch version of the dialog for JDI targets displays a check
box for whether the target shuld be suspended on launch, the default quote character used by
box for whether the target should be suspended on launch, the default quote character used by
the command line, the program used to start the virtual machine (java), the path to where it's
installed, and fields for the name of the class and any user options you might supply:</P>
@@ -101,25 +91,23 @@
</TABLE>
<P>The options displayed by the Launch command are, for some targets, connected to the
currently selected item under Connectors. For example, the Windows tree offers four possible
connectors: one for command-line launch, one for attach, open for kernel-mode debugging, and
one for opening previously-generated dump or trace files.</P>
currently selected item under Connectors. For example, the dbgmodel.dll connector offers
several launchers: one for command-line launch, one for attach, open for kernel-mode debugging,
and one for opening previously-generated dump or TTD trace files.</P>
<H3><A name="attach"></A><IMG alt="" src="images/attach.png"> Attach</H3>
<P>Attach to a running target</P>
<P>If the debugger has available a list of running targets for the local system, the attach
action provides a convenient way to select and attach to an existing process. If the
highlighted object in the provider is considered "attachable", the attach action attempts to
connect that element. The list of "attachable" targets is typically displayed in the tree under
<B>Session/Available</B>. Bare in mind it often takes time to populate the <B>Available</B>
list, which may need to be manually refreshed.</P>
<P>Attach to a running target. If the debugger has available a list of running targets for the
local system, the attach action provides a convenient way to select and attach to an existing
process. If the highlighted object in the provider is considered "attachable", the attach
action attempts to connect that element. The list of "attachable" targets is typically
displayed in the tree under <B>Session/Available</B>. Bear in mind it often takes time to
populate the <B>Available</B> list, which may need to be manually refreshed.</P>
<H3><A name="detach"></A><IMG alt="" src="images/detach.png"> Detach</H3>
<P>Detach from the selected target, usually allowing it to resume execution. (This action
terminates the current trace for the target, if applicable, but does not close it.)</P>
<P>Detach from the selected target, usually allowing it to resume execution. As a consequence,
this action terminates the trace for the current target, if applicable.</P>
<H3><A name="re-attach"></A><IMG alt="" src="images/attach.png"> Re-attach</H3>
@@ -128,12 +116,10 @@
<H3><A name="kill"></A><IMG alt="" src="images/kill.png"> Kill</H3>
<P>Kill this current target. (As with <B>detach</B>, this terminates a current trace, if
applicable, but does not close it.)</P>
<P>Kill the current target. As a consequence, this action terminates the trace for the current
target, if applicable.</P>
<H2>Execution Management</H2>
<P>The following actions manage execution state of a target.</P>
<H2>Actions for Execution Management</H2>
<H3><A name="interrupt"></A><IMG alt="" src="images/stop.png"> Interrupt (Pause, Suspend,
Break)</H3>
@@ -156,6 +142,10 @@
<P>Allow the current target to finish the current subroutine, pausing after.</P>
<H3><A name="step_last"></A><IMG alt="" src="images/stepout.png"> Step Last / Extended</H3>
<P>Perform a target-defined step, often the last (possibly custom or extended) step.</P>
<H3><A name="set_breakpoint"></A><IMG alt="" src="images/breakpoint-set.png"> Set
Breakpoint</H3>
@@ -170,15 +160,17 @@
</TABLE>
<P>The given expression can follow any form accepted by the connected debugger, although most
often this will be an address. The listing can only set breakpoints on specific addresses, not
symbols or expressions. The listing is also not available until the target is being recorded.
For a recorded target, breakpoints can also be managed in the <A href=
often this will be an address. Compare this to the listing, which can only set breakpoints on
specific addresses, not symbols or expressions. Furthermore, some targets allow breakpoints to
be specified before a target is launched. Conversely, the listing is not available until the
target is launched and being recorded. For a recorded target, breakpoints (including locations
set via this action) can be managed in the <A href=
"help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html">Breakpoints</A> window
or using the <A href=
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Breakpoint
Marker</A> actions from the disassembly listings.</P>
<H2>Trace Management</H2>
<H2>Actions for Trace Management</H2>
<P>The following actions manage target tracing. Note that many other windows are not usable
until a target is recorded into a trace.</P>
@@ -195,7 +187,7 @@
<P>Automatically record and open recognized targets. If Ghidra cannot uniquely identify the
platform, it will select one by priority without prompting the user.</P>
<H2><A name="display_as"></A>Display Management</H2>
<H2><A name="display_as"></A>Actions for Display Management</H2>
<P>The following actions can create additional displays of portions of the debugger model.</P>
@@ -216,15 +208,15 @@
<H3><A name="display_as_graph"></A><IMG alt="" src="images/display_as_graph.png"> Display As
Graph</H3>
<P>Constructs and displays a graph from the selection and its visible descendants. (The graph
does not currently maintain synchronization.)</P>
<P>Constructs and displays a graph from the selection and its visible descendants. NOTE: The
graph does not currently maintain synchronization.</P>
<H3><A name="display_as_xml"></A><IMG alt="" src="images/display_as_xml.png"> Display As
XML</H3>
<P>Encodes the selected object and its visible descendants in XML and prints the result to the
console. (Note: various characters not allowed in XML may be converted, typically to
underscores, in the result.)</P>
console. NOTE: Various characters not allowed in XML may be converted, typically to
underscores, in the result.</P>
<H3><A name="display_filtered_tree"></A><IMG alt="" src="images/display_filtered_tree.png">
Display Filtered Tree</H3>
@@ -255,45 +247,52 @@
<P>Displays a list of the methods available for the selection, which may be applied and
combined in a filter.</P>
<H2>Data Management</H2>
<P>The following actions can export and import model information.</P>
<H2>Actions for Data Management</H2>
<H3><A name="export_as_xml"></A><IMG alt="" src="images/export_as_xml.png"> Export as XML</H3>
<P>Convert the selection and its visible descendants to XML and export the result to a file of
the user's choosing.</P>
<P>Converts the selection and its visible descendants to XML and exports the result to a file
of the user's choosing.</P>
<H3><A name="import_from_xml"></A><IMG alt="" src="images/import_from_xml.png"> Import from
XML</H3>
<P>Import "facts" from a file of the user's choosing and render it as a tree.</P>
<P>Imports "facts" from a file of the user's choosing and renders it as a tree.</P>
<H3><A name="export_as_facts"></A><IMG alt="" src="images/export_as_facts.png"> Export as
Facts</H3>
<P>Convert the selection and its visible descendants to "fact" files and export the result to a
directory of the user's choosing. (Currently, "fact" files itemize the path, name, value, type,
and children for each object.)</P>
<P>Converts the selection and its visible descendants to "fact" files and exports the result to
a directory of the user's choosing. Currently, "fact" files itemize the path, name, value,
type, and children for each object.</P>
<H3><A name="import_from_facts"></A><IMG alt="" src="images/import_from_facts.png"> Import from
Facts</H3>
<P>Import XML from a directory of the user's choosing and render them as a tree.</P>
<P>Imports XML from a directory of the user's choosing and renders them as a tree.</P>
<H3><A name="open_trace"></A><IMG alt="" src="images/text-xml.png"> Import from trace</H3>
<P>Import from trace is roughly equivalent to using the open dump/trace connector.</P>
<H2>Miscellaneous</H2>
<H2>Miscellaneous Actions</H2>
<P>The following actions are for maintenance or experiments</P>
<H3><A name="console"></A><IMG alt="" src="images/console.png"> Console</H3>
<P>Shows the console for the selected context, usually the debugger's command-line interpreter.
Some models may also present a target's standard I/O via a console.</P>
<H3><A name="refresh"></A><IMG alt="" src="images/reload.png"> Refresh Node</H3>
<P>Queries the model for the current object's children and rebuilds that portion of the
display.</P>
<H3><A name="toggle_base">Toggle Base</A></H3>
<P>Asks the connector to display numeric values in decimal or hexadecimal. This may also cause
updates to the trace database, renaming objects whose names are derived from those numeric
values.</P>
<H3><A name="toggle_subscription">Subscribe / Unsubscribe to Selection</A></H3>
<P>Asks the recorder to include or exclude the current object from the trace.</P>
@@ -305,19 +304,18 @@
<B>step</B> action will only be enabled for objects marked <B>steppable</B>. If "selection
only" is off, the debugger will walk the path up from the current object looking for an
ancestor for which the action is enabled. For example, if threads are <B>steppable</B> and
contain registers as children, <B>step</B> will still be enabled for that thread if the current
selection is one of its registers.</P>
contain registers as descendants, <B>step</B> will still be enabled for that thread if the
current selection is one of its registers.</P>
<H3><A name="hide_intrinsic_attributes"></A>Hide Intrinsic Attributes</H3>
<P>Toggle which objects are visible (mostly for diagnostic purposes). Attributes for each
object may be split into those that convey information intended for the user and those that
convey information for the debugger. The latter are not normally visible, because they just
clutter the display. However, under certain circumstances, the user may want to see them. For
example, the <B>_update_mode</B> attribute determines when node is refreshed, and the
<B>_state</B> attribute indicates whether a thread is running or stopped. In the latter case,
this information is reflected for the user in the display, but the invisible attribute actually
determines the behavior.</P>
<P>Toggle whether hidden objects are visible &mdash; mostly for diagnostic purposes. Some
attributes convey information intended for the user and some convey information for the
machine. The latter are not normally visible, because they just clutter the display. However,
under certain circumstances, the user may want to see them. For example, the <B>_state</B>
attribute indicates whether a thread is running or stopped. In the latter case, this
information is reflected for the user by visual cues in the display, but the invisible
attribute actually determines the behavior.</P>
<H3><A name="toggle_ignore_state">Ignore State</A></H3>
@@ -327,7 +325,7 @@
<H2><A name="color"></A>Color Options</H2>
<P>The debugger represents different types of objects with different colors. Bare in mind these
<P>The debugger represents different types of objects with different colors. Bear in mind these
colors are not blended, i.e. one color may override another. Examples include:</P>
<UL>
@@ -345,7 +343,6 @@
populated)</LI>
<LI>Targets: native objects with special properties</LI>
</UL><BR>
<BR>
</UL>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerPcodeStepperPlugin/DebuggerPcodeStepperPlugin.html
+11 -14
View File
@@ -34,7 +34,7 @@
<P>P-code stepping is built into the emulation framework, and so the other UI elements
(listing, registers, etc.) will display machine state from emulated p-code operations, i.e.,
partially executed machine instructions. The p-code stepper provides a means of navigating time
at p-code-level and displaying p-code-level details of the machine state.</P>
at the p-code-level and displaying p-code-level details of the machine state.</P>
<H2>Table Columns</H2>
@@ -42,8 +42,8 @@
values and user-assigned types. It has the following columns:</P>
<UL>
<LI>Ref - describes how the select p-code operation uses the variable. Blank indicates no
reference. A &larr; indicates read. A &rarr; indicates write.</LI>
<LI>Ref - describes how the selected p-code operation uses the variable. Blank indicates no
reference. A left arrow &larr; indicates read. A right arrow &rarr; indicates write.</LI>
<LI>Unique - the name (address and size) of the variable.</LI>
@@ -58,24 +58,21 @@
<H2>Actions</H2>
<P>The p-code stepper provides the following actions:</P>
<P>The p-code stepper provides the following actions. Regarding other windows' ability to
interact with the target, stepping at the p-code level implies you are no longer "at the
present."</P>
<H3><A name="step_trace_pcode_backward"></A>Step Trace p-code Backward</H3>
<P>This action is available when the current coordinates have some positive number of p-code
ticks. It steps the trace backward to the previous p-code tick, possibly using emulation. Note
that stepping backward does not affect the target, and many windows that would ordinarily
interact with a live target, may no longer do so, until the user steps back to the present.
Note also that any component or script that does interact with the target and record things
"into the present" may not cause updates in windows that are not displaying the present.</P>
ticks. It steps the trace backward to the previous p-code tick.</P>
<H3><A name="step_trace_pcode_forward"></A>Step Trace p-code Forward</H3>
<P>This action is available when a thread is selected. It steps the current thread forward to
the next p-code tick, using emulation. Note that emulation does not affect the target, and many
windows that would ordinarily interact with a live target, may not longer do so, until the user
steps back to the present. Note also that any component or script that does interact with the
target and record things "into the present" may not cause updates in windows that are not
displaying the present.</P>
the next p-code tick, using emulation. Note that emulation does not affect the target.
Furthermore, emulation of p-code user-ops, including those indicating a system call, is
generally not possible. Pluggable mechanisms for emulating user-ops and/or simulating a more
complete system is a work in progress.</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html
+2 -2
View File
@@ -80,10 +80,10 @@
<P>The dialog provides more information about each register, potentially displays a larger set
of registers, and permits the precise selection of registers to include in the window. This
varies from using the table filter in that the register window will not query the target for a
register unless it is selected. Note that de-selecting a register does not prohibit other
register unless it is selected. Note that deselecting a register does not prohibit other
components from reading that register. For example, the program counter and stack pointer are
read by the recorder whether or not they're displayed in the table. The actions allow for the
addition and subtraction of selections from the register set. Most columns are self-explanator
addition and subtraction of selections from the register set. Most columns are self-explanatory
or duplicate the same column in the main window. The "Known" column indicates whether Ghidra
was able to find the same register on the target. Unknown registers are never populated by the
recorder, but they can still be populated by the user. Modifying the values of unknown
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html
+9 -9
View File
@@ -23,15 +23,15 @@
</TABLE>
<P>The stack window displays the current trace's execution stack, as unwound and reported by
the target. Not all debuggers will unwind the stack, in which case, this window displays a
synthetic innermost frame. When emulation was used to generate the current machine state, only
a synthetic frame is shown. Level 0 always refers to the innermost frame, and each incremental
level refers to the next caller in the chain &mdash; most of the time. The current frame
comprises one element of the tool's current "coordinates." Selecting a frame changes those
coordinates, potentially causing other windows to display different information. Namely, the <A
href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A> window
will show registers for the current frame, assuming they can be retrieved. The Listings may
also navigate to the current frame's program counter.</P>
the target. Not all debuggers will unwind the stack, in which case, this window displays only
the innermost frame. When emulation is used to generate the current machine state, only a
single synthetic frame is shown. Level 0 always refers to the innermost frame, and each
incremental level refers to the next caller in the chain &mdash; most of the time. The current
frame comprises one element of the tool's current "coordinates." Selecting a frame changes
those coordinates, potentially causing other windows to display different information. Namely,
the <A href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A>
window will show registers for the current frame, assuming they can be retrieved. The Listings
may also navigate to the current frame's program counter.</P>
<H2>Table Columns</H2>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStaticMappingPlugin/DebuggerStaticMappingPlugin.html
+6 -5
View File
@@ -28,7 +28,7 @@
automation, e.g., the <A href="help/topics/DebuggerBots/DebuggerBots.html#map_modules">Map
Modules</A> bot, or by higher-level user actions, e.g., the <A href=
"help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html#map_modules">Map Modules</A>
action. This under-the-hood static mapping window dislays the mappings table, allowing users or
action. This under-the-hood static mapping window displays the mappings table, allowing users or
developers to diagnose image mapping issues and manually add mappings, regardless of reported
modules and/or sections. For most users, there is no reason to access this window.</P>
@@ -63,10 +63,11 @@
<H3><A name="add"></A>Add Mapping</H3>
<P>This action is available when one primary listing (dynamic or static) has a selection, and
the other's cursor is at a valid location. It will add a mapping, using the selection's size
and minimum address, and the cursor as the corresponding minimum address. The lifespan given is
"from now on out", i.e., the current time to infinity.</P>
<P>This action is always available. It presents a dialog to manually add a mapping. When one
primary listing (dynamic or static) has a selection, and the other's cursor is at a valid
location, it will populate the dialog, using the selection's size and minimum address, and the
cursor as the corresponding minimum address. The default lifespan is "from now on out", i.e.,
the current snap to infinity.</P>
<H3><A name="remove"></A>Remove Mapping</H3>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStaticMappingPlugin/images/DebuggerStaticMappingPlugin.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTargetsPlugin/DebuggerTargetsPlugin.html
+19 -18
View File
@@ -22,13 +22,12 @@
</TBODY>
</TABLE>
<P>The targets window manages connections to live debuggers. In most cases, a "connection" is a
connection to a local "agent" process which manages a native debugger, communicating
<P>The targets window manages connections to live debuggers. In most cases, each item is a
GADP/TCP connection to a local "agent" process which manages a native debugger, communicating
information about its targets. It is possible, however, to create a connection without starting
an agent, e.g., to re-connect to an existing agent, or a remote agent. Additionally, different
connectors may implement alternative protocols, permitting direct communication with a native
target. This window allows the user to establish new connections and disconnect from existing
sessions.</P>
connectors may implement alternative protocols, or use a debugging API directly. This window
allows the user to establish and terminate connections.</P>
<H2>Actions</H2>
@@ -36,7 +35,7 @@
<H3><A name="connect"></A><IMG alt="" src="images/connect.png"> Connect</H3>
<P>Prompts the user to select a launcher and configure its parameters.</P>
<P>Prompts the user to select a connector and configure its parameters.</P>
<TABLE width="100%">
<TBODY>
@@ -46,27 +45,29 @@
</TBODY>
</TABLE>
<P>The top drop-down displays a list of pluggable connectors or launchers. A description and
the options for the currently-selected launcher are displayed below. Some launchers will start
new sessions; whereas, others may simply connect to existing sessions. Each connector defines
its own options, but common ones include port numbers, host names, the system paths of
debugging components, etc. The launchers should provide help in the form of tool-tips, accessed
by hovering over each option name. Selecting "connect" will launch the connector and dismiss
the dialog.</P>
<P>The top drop-down displays a list of pluggable connectors. A description and the options for
the currently-selected connector are displayed below. Some will start a new session, while
others may simply connect to an existing session. Each connector defines its own options, but
common ones include port numbers, host names, the system paths of debugging components, etc.
Each connector should provide help in the form of tool tips, accessed by hovering over an
option's name. Clicking "Connect" will start the connector and dismiss the dialog.</P>
<H3><A name="disconnect"></A><IMG alt="" src="images/disconnect.png"> Disconnect</H3>
<P>This action is available when a connection is selected. It destroys the connection. Note,
this does not necessarily destroy all processes created by the connector.</P>
<P>This action is available when a connection is selected. It closes the connection. Note,
depending on the robustness of the connector's termination logic, this may not clean up all
processes created by the connector.</P>
<H3><A name="disconnect_all"></A> Disconnect All</H3>
<P>This action is always available. It closes all debugger connections, no matter what tool
created them. This is a sort of panic and reset action.</P>
created them. This is a sort of panic and reset action. As with Disconnect, clean-up depends on
each connector's implementation.</P>
<H3><A name="flush_caches"></A>Flush Caches</H3>
<P>This maintenance command instructs the connector to flush its local caches. It should
rarely, if ever, be needed by the user.</P>
<P>This maintenance command instructs the selected connector to flush its local caches. It
should rarely, if ever, be needed by the user. It may be useful if, e.g., stale memory is not
getting updated.</P>
</BODY>
</HTML>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTargetsPlugin/images/DebuggerTargetsPlugin.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.4 KiB

After

Width:  |  Height:  |  Size: 9.0 KiB

Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html
+33 -44
View File
@@ -38,37 +38,37 @@
open trace in a button, where the "current" or "focused" trace is selected. Clicking a tab will
select its trace and focus the tool onto it. A trace associated with a live target has a red
"recording" icon at its left. If that icon is not present, or has disappeared, the trace is
dead or terminated. A "dead" trace can still be manipulated and marked up, but it will
(obviously) not record any new information from the (dead) target.</P>
dead or terminated. A "dead" trace can still be manipulated and marked up, but it will not
record any new target information.</P>
<P>In most cases, a trace is ephemeral, but occasionally, interesting behavior is observed that
is difficult to store as program mark-up. When a trace is no longer needed, it can be closed by
is difficult to store as static mark-up. When a trace is no longer needed, it can be closed by
right-clicking the tab and selecting "Close Trace." <FONT color="red">Warning:</FONT> closing a
trace that has not been saved <EM>cannot</EM> be undone. If you have gathered a collection of
unwanted traces, use the "Close Others," "Close Dead," or "Close All" action from the pop-up
trace that has not been saved <EM>cannot</EM> be undone. If you accumulate many unwanted
traces, use one of the "Close Others," "Close Dead," or "Close All" actions from the pop-up
menu.</P>
<H2>Navigating Threads</H2>
<P>Selecting a thread in the timeline or the table will navigate to (or "activate" or "focus")
that thread. Many windows which are sensitive to the current thread will update. Notably, the
<A href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A> window
will display the new thread's register values. <A href=
that thread. Windows which are sensitive to the current thread will update. Notably, the <A
href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A> window
will display the activated thread's register values. <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Listing</A> windows with
configured location tracking will re-compute that location with the new thread's context and
navigate to it. The thread timeline displays all recorded threads in a timeline. Threads which
are alive will appear to extend "to the end of time." The threads table displays more detailed
information, in the following columns:</P>
configured location tracking will re-compute that location with the thread's context and
navigate to it. The thread timeline displays all recorded threads. Threads which are alive will
appear to extend "to the end of time." The threads table displays more detailed information in
the following columns:</P>
<UL>
<LI>Name - the name of the thread given by the debugger. Often, this is just an index or
unique id assigned to the thread. This field can be modified, and it has no effect on the
unique id assigned to the thread. This field can be modified, but it has no effect on the
target.</LI>
<LI>Created - the point in time when this thread was first observed. If the thread's creation
was observed, then it is its creation time.</LI>
<LI>Created - the snapshot when this thread was first observed. If the thread's creation was
observed, then it is its creation time.</LI>
<LI>Destroyed - if destroyed, the point in time when this thread was last observed. If the
<LI>Destroyed - if destroyed, the snapshot when this thread was last observed. If the
thread's destruction was observed, then it is its destruction time.</LI>
<LI>State - the thread's current state. For a dead trace, this is either ALIVE or TERMINATED,
@@ -84,48 +84,39 @@
<P>The user can navigate through time within the current trace by using the caret above the
threads timeline. There are also actions for "stepping the trace" forward and backward. See the
<A href="help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html">Time</A> window for a way to
display and navigate to specific events in the trace's timeline.</P>
display and navigate to specific events in the trace's timeline. Note that stepping away from
the present will prevent most windows from interacting with the live target. While some
components and scripts may interact with the target and record things "into the present," such
updates may not appear on screen until the user steps back to the present. Stepping the trace
does not affect the target, except that viewing the present requires querying the live target,
which can perturb its state.</P>
<H3><A name="step_trace_snap_backward"></A><IMG alt="" src="images/arrow_up.png">Step Track
<H3><A name="step_trace_snap_backward"></A><IMG alt="" src="images/arrow_up.png">Step Trace
Snap Backward</H3>
<P>This action is available when there exists a snapshot previous to the current. It steps the
trace backward to the previous snapshot, causing most windows to display the recorded data from
the new point in time. Note that stepping backward does not affect the target, and many windows
that would ordinarily interact with a live target, may no longer do so, until the user steps
back to the present. Note also that any component or script that does interact with the target
and record things "into the present" will not cause updates in windows that are not displaying
the present.</P>
the new point in time.</P>
<H3><A name="step_trace_snap_forward"></A><IMG alt="" src="images/arrow_down.png">Step Trace
Snap Forward</H3>
<P>This action is available when there exists a snapshot ahead of the current. It steps the
trace forward to the next snapshot, causing most windows to display the recorded data from the
new point in time. If the new point in time represents "the present" for a live trace, then
many windows will resume interacting with the target. Note that stepping the trace does not
affect the target; however, stepping back to the present may cause some windows to query the
target.</P>
new point in time.</P>
<H3><A name="step_trace_tick_backward"></A><IMG alt="" src="images/stepback.png">Step Track
<H3><A name="step_trace_tick_backward"></A><IMG alt="" src="images/stepback.png">Step Trace
Tick Backward</H3>
<P>This action is available when there exists a point in time previous to the current. It steps
the trace backward to the previous tick, possibly using emulation. Note that stepping backward
does not affect the target, and many windows that would ordinarily interact with a live target,
may no longer do so, until the user steps back to the present. Note also that any component or
script that does interact with the target and record things "into the present" may not cause
updates in windows that are not displaying the present.</P>
<P>This action is available when the current point in time includes emulated steps. It steps
the trace backward to the previous tick.</P>
<H3><A name="step_trace_tick_forward"></A><IMG alt="" src="images/stepinto.png">Step Trace Tick
Forward</H3>
<P>This action is available when a thread is selected. It steps the current thread forward to
the next tick, using emulation. Note that emulation does not affect the target, and many
windows that would ordinarily interact with a live target, may no longer do so, until the user
steps back to the present. Note also that any component or script that does interact with the
target and record things "into the present" may not cause updates in windows that are not
displaying the present.</P>
the next tick, using emulation. Note that emulation does not affect the target. Furthermore,
emulation may halt early if it encounters certain instructions or causes an exception.</P>
<H3><A name="seek_trace_present"></A><IMG alt="" src="images/continue.png">Seek Trace to
Present</H3>
@@ -134,12 +125,10 @@
current trace is live, it immediately steps the trace to the present. Furthermore, as long as
it is enabled and the current trace is live, whenever the recorder steps forward, the tool
steps with it. In most cases, this option should remain on, otherwise stepping the target will
not cause any windows to update to the new machine state. Toggling it off then on is a quick
way to return to the present after browsing the past.</P>
not cause any windows to update. Toggling it off then on is a quick way to return to the
present after browsing the past.</P>
<H2>Actions</H2>
<P>There are additional actions for managing focus and traces.</P>
<H2>Other Actions</H2>
<H3><A name="sync_focus"></A>Synchronize Trace and Target Focus</H3>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerThreadsPlugin/images/DebuggerThreadsPlugin.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 22 KiB

Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html
+13 -10
View File
@@ -22,13 +22,13 @@
</TBODY>
</TABLE>
<P>This window displays all recorded "snapshots" in the current trace. Typically, there is one
snapshot per event recorded. Other tables often display the times of various events or use time
ranges to describe lifespans of various records. Those times refer to the "snap," which is a
0-up counter of snapshot records. Thus, a snapshot is a collection of observations of a
target's state, usually while suspended, along with any user mark up. Selecting a snapshot
navigates to the selected point in time. Note that browsing the past may prevent other windows
from interacting with a live target.</P>
<P>This window displays all recorded snapshots in the current trace. Typically, there is one
snapshot per event recorded. Other windows often display the times of various events or use
time ranges to describe lifespans of various records. Those times refer to the "snap," which is
a 0-up counter of snapshot records. Thus, a snapshot is a collection of observations of a
target's state, usually while suspended, along with any mark up. Selecting a snapshot navigates
to the selected point in time. Note that browsing the past may prevent other windows from
interacting with a live target.</P>
<H2>Table Columns</H2>
@@ -44,8 +44,11 @@
<LI>Event Thread - the thread that caused the event, if applicable. In the case of thread
creation, this should probably be the spawned thread, not the parent.</LI>
<LI>Ticks - the number of ticks until the next snapshot, if known. If not known, or if
nothing cared to record or compute this, it is 0.</LI>
<LI>Schedule - if applicable, a source snap and the stepping schedule which produces this
snapshot. This always applies to "scratch" snapshots produced by emulation, but may also
apply if the stepping schedule between recorded events is somehow known. Typically, it is
just the number of steps of the source snapshot's event thread; however, the notation does
allow other threads to be stepped, too.</LI>
<LI>Description - a user-modifiable description of the snapshot or event. This defaults to
the debugger's description of the event.</LI>
@@ -58,7 +61,7 @@
<H3><A name="hide_scratch"></A>Hide Scratch</H3>
<P>This toggle action is always available. It is enabled by default. The emulation service,
which enabled trace extrapolation and interpolation, writes emulated state into the trace's
which enables trace extrapolation and interpolation, writes emulated state into the trace's
"scratch space," which comprises all negative snaps. When this toggle is enabled, those
snapshots are hidden. They can be displayed by disabling this toggle. Note that navigating into
scratch space may cause temporary undefined behavior in some windows, and may prevent
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTraceManagerServicePlugin/DebuggerTraceManagerServicePlugin.html
+8 -9
View File
@@ -13,11 +13,11 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Trace Management</H1>
<P>This service plugin manages the collection of open traces, and it controlled primarily via
the <A href="help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html">Threads</A> window.
It maintains a list of open traces, the active trace coordinates (trace, time, thread, frame),
and permits saving, opening, and closing traces. To some extent, it also tracks which traces
are being actively recorded.</P>
<P>This service plugin manages the collection of open traces, and it is controlled primarily
via the <A href="help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html">Threads</A>
window. It maintains a list of open traces, the active trace coordinates (trace, time, thread,
frame), and permits saving, opening, and closing traces. To some extent, it also tracks which
traces are being actively recorded.</P>
<H2>Actions</H2>
@@ -48,10 +48,9 @@
<H3><A name="close_other_traces"></A>Close Other Traces</H3>
<P>This action is available whenever there is an open trace other than the active one --
usually two or more open traces. It closes all traces in this tool, except the active trace.
<FONT color="red">WARNING:</FONT> Any closed trace that has not been saved will be lost, even
when Save by Default is active.</P>
<P>This action is available whenever there is an open trace other than the active one. It
closes all traces in this tool, except the active trace. <FONT color="red">WARNING:</FONT> Any
closed trace that has not been saved will be lost, even when Save by Default is active.</P>
<H3><A name="close_dead_traces"></A>Close Dead Traces</H3>
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerWatchesPlugin/DebuggerWatchesPlugin.html
+19 -18
View File
@@ -24,15 +24,15 @@
<P>Watches refer to expressions which are evaluated each pause in order to monitor the value of
variables in the target machine state. The watch variables are expressed in Sleigh and
evaluated in the current thread's and trace's context at the current point in time. If the
current trace is live and at the present, then the target state is read and recorded as
necessary. The watch can be assigned a data type so that the raw data is rendered in a
meaningful way. When applicable, that data type can optionally be applied to the trace
database. Some metadata about the watch is also given, e.g., the address of the value.</P>
evaluated in the current thread's context at the current point in time. If the current trace is
live and at the present, then the necessary target state is queried and recorded. The watch can
be assigned a data type so that the raw data is rendered in a meaningful way. When applicable,
that data type can optionally be applied to the trace database. Some metadata about the watch
is also given, e.g., the address of the value.</P>
<H2>Examples</H2>
<P>For those less familar with Sleigh, here are some example expressions:</P>
<P>For those less familiar with Sleigh, here are some example expressions:</P>
<UL>
<LI><CODE>*:4 (RSP+8)</CODE>: Display 4 bytes of [ram] starting 8 bytes after the offset
@@ -68,15 +68,15 @@
trace. Clicking the Apply Data Type action will apply it to the current trace, if
possible.</LI>
<LI>Representation - the value of the watch as interpreted the selected data type.</LI>
<LI>Representation - the value of the watch as interpreted by the selected data type.</LI>
<LI>Error - if an error occurs during compilation or evaluation of the expression, that error
is rendered here. Double-clicking the row will display the stack trace. Note that errors
during evaluation can be a very common occurrence, especially as contexts change, and should
not cause alarm. An expression devised for one context may not have meaning under another,
even if it evaluates without error. E.g., <CODE>RIP</CODE> will disappear when switching to a
32-bit trace, or <CODE>*:8 (*:8 (RSP+8))</CODE> may cause an invalid dereference if an x86
<CODE>PUSH</CODE> causes <CODE>*:8 (RSP+8)</CODE> to become 0.</LI>
not necessarily cause alarm. An expression devised for one context may not have meaning under
another, even if it evaluates without error. E.g., <CODE>RIP</CODE> will disappear when
switching to a 32-bit trace, or <CODE>*:8 (*:8 (RSP+8))</CODE> may cause an invalid
dereference if an x86 <CODE>PUSH</CODE> causes <CODE>*:8 (RSP+8)</CODE> to become 0.</LI>
</UL>
<H2>Actions</H2>
@@ -85,14 +85,14 @@
<H3><A name="apply_data_type"></A>Apply Data to Listing</H3>
<P>This action is available when there's an active trace and at least one watch with an address
and data type is selected. If so, it applies that data type to the value in the listing. That
is, it attempts to apply the selected data type to the evaluated address, sizing it to the
value's size.</P>
<P>This action is available when there's an active trace, and at least one watch with an
address and data type is selected. If so, it applies that data type to the value in the
listing. That is, it attempts to apply the selected data type to the evaluated address, sizing
it to the value's size.</P>
<H3><A name="select_addresses"></A>Select Range</H3>
<P>This action is available when there's an active trace and at least one watch with memory
<P>This action is available when there's an active trace, and at least one watch with memory
addresses is selected. It selects the memory range comprising the resulting value. This only
works when the outermost operator of the expression is a memory dereference. It selects the
range at the address of that dereference having the size of the dereference. For example, the
@@ -101,7 +101,7 @@
<H3><A name="select_reads"></A>Select Reads</H3>
<P>This action is available when there's an active trace and at least one watch with memory
<P>This action is available when there's an active trace, and at least one watch with memory
reads is selected. It selects all memory ranges dereferenced in the course of expression
evaluation. This can be useful when examining a watch whose value seems unusual. For example,
the expression <CODE>*:8 RSP</CODE> would cause 8 bytes of memory, starting at the offset given
@@ -111,7 +111,8 @@
<H3><A name="add"></A>Add</H3>
<P>This action is always available. It adds a blank watch to the table.</P>
<P>This action is always available. It adds a blank watch to the table. Modify the expression
to make the entry useful.</P>
<H3><A name="remove"></A>Remove</H3>
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/DebuggerResources.java
+19 -1
View File
@@ -573,6 +573,22 @@ public interface DebuggerResources {
}
}
abstract class AbstractStepLastAction extends DockingAction {
public static final String NAME = "Step Last";
public static final Icon ICON = ICON_STEP_FINISH; // TODO: Draw one
public static final String HELP_ANCHOR = "step_last";
public static HelpLocation help(Plugin owner) {
return new HelpLocation(owner.getName(), HELP_ANCHOR);
}
public AbstractStepLastAction(Plugin owner) {
super(NAME, owner.getName());
setDescription("Repeat the last stepping action");
setHelpLocation(help(owner));
}
}
abstract class AbstractInterruptAction extends DockingAction {
public static final String NAME = "Interrupt";
public static final Icon ICON = ICON_TERMINATE;
@@ -956,12 +972,14 @@ public interface DebuggerResources {
interface SelectNoneAction {
String NAME = "Select None";
String GROUP = "Select";
String HELP_ANCHOR = "select_none";
static ActionBuilder builder(Plugin owner) {
String ownerName = owner.getName();
return new ActionBuilder(NAME, ownerName)
.popupMenuGroup(GROUP)
.popupMenuPath(NAME);
.popupMenuPath(NAME)
.helpLocation(new HelpLocation(ownerName, HELP_ANCHOR));
}
}
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/objects/DebuggerObjectsProvider.java
+3 -3
View File
@@ -1169,11 +1169,11 @@ public class DebuggerObjectsProvider extends ComponentProviderAdapter
new ActionBuilder("Step Last", plugin.getName())
.keyBinding("ALT F8")
.toolBarGroup(DebuggerResources.GROUP_CONTROL, "C" + groupTargetIndex)
.toolBarIcon(AbstractStepFinishAction.ICON)
.toolBarIcon(AbstractStepLastAction.ICON)
.popupMenuPath("&Step Last")
.popupMenuGroup(DebuggerResources.GROUP_CONTROL, "C" + groupTargetIndex)
.popupMenuIcon(AbstractStepFinishAction.ICON)
.helpLocation(AbstractStepFinishAction.help(plugin))
.popupMenuIcon(AbstractStepLastAction.ICON)
.helpLocation(AbstractStepLastAction.help(plugin))
//.withContext(ObjectActionContext.class)
.enabledWhen(ctx ->
isInstance(ctx, TargetSteppable.class) && isStopped(ctx))
Ghidra/Debug/Debugger/src/screen/java/ghidra/app/plugin/core/debug/gui/target/DebuggerTargetsPluginScreenShots.java
+2 -2
View File
@@ -96,9 +96,9 @@ public class DebuggerTargetsPluginScreenShots extends GhidraScreenShotGenerator
@Test
public void testCaptureDebuggerTargetsPlugin() throws Throwable {
modelService.addModel(
new ScreenShotDebuggerObjectModel("Demo connection to 'localhost:12345'"));
new ScreenShotDebuggerObjectModel("DEMO@1234abcd localhost:12345"));
modelService.addModel(
new ScreenShotDebuggerObjectModel("Demo connection to 'debug-demo:12345'"));
new ScreenShotDebuggerObjectModel("DEMO@4321fedc debug-demo:12345"));
captureIsolatedProvider(targetsProvider, 400, 300);
}
Ghidra/Debug/Debugger/src/screen/java/ghidra/app/plugin/core/debug/gui/thread/DebuggerThreadsPluginScreenShots.java
+7 -2
View File
@@ -26,6 +26,7 @@ import ghidra.app.services.DebuggerTraceManagerService;
import ghidra.app.services.TraceRecorder;
import ghidra.dbg.model.*;
import ghidra.trace.model.Trace;
import ghidra.trace.model.thread.TraceThread;
import ghidra.util.database.UndoableTransaction;
import help.screenshot.GhidraScreenShotGenerator;
@@ -44,6 +45,10 @@ public class DebuggerThreadsPluginScreenShots extends GhidraScreenShotGenerator
threadsPlugin = addPlugin(tool, DebuggerThreadsPlugin.class);
}
protected boolean nullOrDead(TraceThread thread) {
return thread == null || !thread.isAlive();
}
@Test
public void testCaptureDebuggerThreadsPlugin() throws Throwable {
mb.createTestModel();
@@ -77,12 +82,12 @@ public class DebuggerThreadsPluginScreenShots extends GhidraScreenShotGenerator
recorder.forceSnapshot();
process.removeThreads(handler1Thread);
waitFor(() -> recorder.getTraceThread(handler1Thread) == null);
waitFor(() -> nullOrDead(recorder.getTraceThread(handler1Thread)));
recorder.forceSnapshot();
recorder.forceSnapshot();
recorder.forceSnapshot();
process.removeThreads(handler2Thread);
waitFor(() -> recorder.getTraceThread(handler2Thread) == null);
waitFor(() -> nullOrDead(recorder.getTraceThread(handler2Thread)));
long lastSnap = recorder.forceSnapshot().getKey();
traceManager.openTrace(trace);