development/ghidra
development/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra synced 2024-09-13 21:56:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/GP-3837_Dan_traceRmiHelp--SQUASHED'

Browse source
This commit is contained in:
Ryan Kurtz 2024-04-15 07:10:51 -04:00
parent 4e6e847eaa c634283544
commit 636dc6fdc6
134 changed files with 3214 additions and 1550 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-ttd.bat
View file

@ -9,7 +9,7 @@
::@desc </body></html>
::@menu-group local
::@icon icon.debugger
::@help TraceRmiLauncherServicePlugin#dbgeng
::@help TraceRmiLauncherServicePlugin#dbgeng_ttd
::@env OPT_PYTHON_EXE:str="python" "Path to python" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH."
:: Use env instead of args, because "all args except first" is terrible to implement in batch
::@env OPT_TARGET_IMG:str="" "Trace (.run)" "A trace associated with the target binary executable"

2
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh
View file

@ -28,7 +28,7 @@
#@arg :str "Image" "The target binary executable image"
#@args "Arguments" "Command-line arguments to pass to the target"
#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb. Omit the full path to resolve using the system PATH."
#@env OPT_START_CMD:StartCmd="start" "Run command" "The gdb command to actually run the target."
#@env OPT_START_CMD:StartCmd="starti" "Run command" "The gdb command to actually run the target."
#@env OPT_EXTRA_TTY:bool=false "Inferior TTY" "Provide a separate terminal emulator for the target."
#@tty TTY_TARGET if env:OPT_EXTRA_TTY

7
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh
View file

@ -25,8 +25,7 @@
#@desc </body></html>
#@menu-group cross
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#gdb
#@enum StartCmd:str run start starti
#@help TraceRmiLauncherServicePlugin#gdb_qemu
#@arg :str "Image" "The target binary executable image"
#@args "Arguments" "Command-line arguments to pass to the target"
#@env GHIDRA_LANG_EXTTOOL_qemu:str="" "Path to qemu" "The path to qemu for the target architecture."
@ -53,9 +52,9 @@ target_image="$1"
if [ -z "$TTY_TARGET" ]
then
"$GHIDRA_LANG_EXTTOOL_qemu" $@ &
"$GHIDRA_LANG_EXTTOOL_qemu" $OPT_EXTRA_QEMU_ARGS $@ &
else
"$GHIDRA_LANG_EXTTOOL_qemu" $@ <$TTY_TARGET >$TTY_TARGET 2>&1 &
"$GHIDRA_LANG_EXTTOOL_qemu" $OPT_EXTRA_QEMU_ARGS $@ <$TTY_TARGET >$TTY_TARGET 2>&1 &
fi
# Give QEMU a moment to open the socket

2
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/raw-gdb.sh
View file

@ -26,7 +26,7 @@
#@desc </body></html>
#@menu-group raw
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#gdb
#@help TraceRmiLauncherServicePlugin#gdb_raw
#@env OPT_GDB_PATH:str="gdb" "Path to gdb" "The path to gdb. Omit the full path to resolve using the system PATH."
#@env OPT_ARCH:str="i386:x86-64" "Architecture" "Target architecture"

1
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh
View file

@ -15,6 +15,7 @@
# limitations under the License.
##
#@title remote gdb
#@no-image
#@desc <html><body width="300px">
#@desc <h3>Launch with local <tt>gdb</tt> and connect to a stub (e.g., <tt>gdbserver</tt>)</h3>
#@desc <p>This will start <tt>gdb</tt> on the local system and then use it to connect to the remote system.

2
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh
View file

@ -34,7 +34,7 @@
#@desc </body></html>
#@menu-group remote
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#gdb
#@help TraceRmiLauncherServicePlugin#gdb_ssh
#@enum StartCmd:str run start starti
#@arg :str "Image" "The target binary executable image on the remote system"
#@args "Arguments" "Command-line arguments to pass to the target"

2
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh
View file

@ -31,7 +31,7 @@
#@desc </body></html>
#@menu-group remote
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#gdb
#@help TraceRmiLauncherServicePlugin#gdb_gdbserver_ssh
#@arg :str "Image" "The target binary executable image on the remote system"
#@args "Arguments" "Command-line arguments to pass to the target"
#@env OPT_HOST:str="localhost" "[User@]Host" "The hostname or user@host"

4
Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh
View file

@ -26,14 +26,14 @@
#@desc file, and most copies of GDB for UNIX will support only ELF. Nevertheless, Ghidra should
#@desc recognize the target and map it, giving you symbols and debug info in the front end, even
#@desc if not in the GDB CLI.</p>
#@desc <p>You will need to locate the <tt>wine</tt> executable on your system, not the script. To
#@desc <p>You will need to locate the <tt>wine</tt> executable, not the script, on your system. To
#@desc find it, either dissect the <tt>wine</tt> script or consult online documentation for your
#@desc distribution of Wine. There are often two executables, one for 32-bit targets and one for
#@desc 64-bit targets. You must select the correct one.</p>
#@desc </body></html>
#@menu-group cross
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#gdb
#@help TraceRmiLauncherServicePlugin#gdb_wine
#@arg :str "Image" "The target binary executable image"
#@args "Arguments" "Command-line arguments to pass to the target"
#@env OPT_WINE_PATH:str="/usr/lib/wine/wine64" "Path to wine binary" "The path to the wine executable for your target architecture."

3
Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh
View file

@ -15,6 +15,7 @@
# limitations under the License.
##
#@title remote lldb
#@no-image
#@desc <html><body width="300px">
#@desc <h3>Launch with local <tt>lldb</tt> and connect to a stub (e.g., <tt>gdbserver</tt>)</h3>
#@desc <p>This will start <tt>lldb</tt> on the local system and then use it to connect to the remote system.
@ -29,7 +30,7 @@
#@desc </body></html>
#@menu-group remote
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#lldb
#@help TraceRmiLauncherServicePlugin#lldb_remote
#@env OPT_HOST:str="localhost" "Host" "The hostname of the target"
#@env OPT_PORT:str="9999" "Port" "The host's listening port"
#@env OPT_ARCH:str="" "Architecture" "Target architecture override"

1
Ghidra/Debug/Debugger-rmi-trace/build.gradle
View file

@ -15,6 +15,7 @@
*/
apply from: "${rootProject.projectDir}/gradle/javaProject.gradle"
apply from: "${rootProject.projectDir}/gradle/helpProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"

7
Ghidra/Debug/Debugger-rmi-trace/certification.manifest
View file

@ -2,6 +2,13 @@
DEVNOTES.txt||GHIDRA||||END|
Module.manifest||GHIDRA||||END|
data/ExtensionPoint.manifest||GHIDRA||||END|
src/main/help/help/TOC_Source.xml||GHIDRA||||END|
src/main/help/help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionManagerPlugin.html||GHIDRA||||END|
src/main/help/help/topics/TraceRmiConnectionManagerPlugin/images/ConnectDialog.png||GHIDRA||||END|
src/main/help/help/topics/TraceRmiConnectionManagerPlugin/images/TraceRmiConnectionManagerPlugin.png||GHIDRA||||END|
src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html||GHIDRA||||END|
src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbLauncher.png||GHIDRA||||END|
src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbTerminal.png||GHIDRA||||END|
src/main/py/LICENSE||GHIDRA||||END|
src/main/py/README.md||GHIDRA||||END|
src/main/py/pyproject.toml||GHIDRA||||END|

2
Ghidra/Debug/Debugger-rmi-trace/data/debugger-launchers/raw-python3.sh
View file

@ -25,7 +25,7 @@
#@desc </body></html>
#@menu-group raw
#@icon icon.debugger
#@help TraceRmiLauncherServicePlugin#gdb
#@help TraceRmiLauncherServicePlugin#python_raw
#@env OPT_PYTHON_EXE:str="python" "Path to python" "The path to the Python 3 interpreter. Omit the full path to resolve using the system PATH."
#@env OPT_LANG:str="DATA:LE:64:default" "Ghidra Language" "The Ghidra LanguageID for the trace"
#@env OPT_COMP:str="pointer64" "Ghidra Compiler" "The Ghidra CompilerSpecID for the trace"

61
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml Normal file
View file

@ -0,0 +1,61 @@
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!--
This is an XML file intended to be parsed by the Ghidra help system. It is loosely based
upon the JavaHelp table of contents document format. The Ghidra help system uses a
TOC_Source.xml file to allow a module with help to define how its contents appear in the
Ghidra help viewer's table of contents. The main document (in the Base module)
defines a basic structure for the
Ghidra table of contents system. Other TOC_Source.xml files may use this structure to insert
their files directly into this structure (and optionally define a substructure).
In this document, a tag can be either a <tocdef> or a <tocref>. The former is a definition
of an XML item that may have a link and may contain other <tocdef> and <tocref> children.
<tocdef> items may be referred to in other documents by using a <tocref> tag with the
appropriate id attribute value. Using these two tags allows any module to define a place
in the table of contents system (<tocdef>), which also provides a place for
other TOC_Source.xml files to insert content (<tocref>).
During the help build time, all TOC_Source.xml files will be parsed and validated to ensure
that all <tocref> tags point to valid <tocdef> tags. From these files will be generated
<module name>_TOC.xml files, which are table of contents files written in the format
desired by the JavaHelp system. Additionally, the generated files will be merged together
as they are loaded by the JavaHelp system. In the end, when displaying help in the Ghidra
help GUI, there will be one table of contents that has been created from the definitions in
all of the modules' TOC_Source.xml files.
Tags and Attributes
<tocdef>
-id - the name of the definition (this must be unique across all TOC_Source.xml files)
-text - the display text of the node, as seen in the help GUI
-target** - the file to display when the node is clicked in the GUI
-sortgroup - this is a string that defines where a given node should appear under a given
parent. The string values will be sorted by the JavaHelp system using
a javax.text.RulesBasedCollator. If this attribute is not specified, then
the text of attribute will be used.
<tocref>
-id - The id of the <tocdef> that this reference points to
**The URL for the target is relative and should start with 'help/topics'. This text is
used by the Ghidra help system to provide a universal starting point for all links so that
they can be resolved at runtime, across modules.
-->
<tocroot>
<tocref id="Debugger" >
<tocdef id="TraceRmiConnectionManagerPlugin" text="Connection Manager"
sortgroup="m"
target="help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionManagerPlugin.html" />
<tocdef id="TraceRmiLauncherServicePlugin" text="Launchers"
sortgroup="m"
target="help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html" />
</tocref>
</tocroot>

107
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionManagerPlugin.html Normal file
View file

@ -0,0 +1,107 @@
<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
<HTML>
<HEAD>
<META name="generator" content=
"HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">
<TITLE>Debugger: Connections</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
</HEAD>
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Connections</H1>
<DIV class="image">
<IMG alt="" src="images/TraceRmiConnectionManagerPlugin.png">
</DIV>
<P>The Connections window manages connections to live debuggers and, at a high level, their
targets. Each item is a Trace RMI connection (or a step toward one) to a back-end debugger.
Usually, the back end is a native debugger with a plugin that communicates with Ghidra via
Trace RMI. These connections are typically established using a launcher script, invoked from
the <A href=
"help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html">Launcher
Menu</A>, though there are actions here for establishing connections manually or to remote back
ends. There are different kinds of items displayed in the connection list.</P>
<UL>
<LI><IMG alt="" src="icon.debugger.thread"> <B>Server:</B> This node displays the current
state of the Trace RMI server. Ordinarily, the server is not used, since Ghidra can accept
connections on a one-off basis without starting a persistent server. Nevertheless, often for
development purposes, it may be convenient to keep a socket open. There is only one server,
and it is either listening on a port, or not.</LI>
<LI><IMG alt="" src="icon.debugger.connect.accept"> <B>Acceptor:</B> Each acceptor is ready
to receive a single connection from a Trace RMI client. The node displays the host/interface
and port on which it is listening. Once it has received a connection, the acceptor is
destroyed.</LI>
<LI><IMG alt="" src="icon.debugger.connect"> <B>Connection:</B> A connection is a complete
connection to a Trace RMI client. It may have one or more (but usually only one) target trace
associated with it. The node displays a description given by the client along with the remote
host and port. Double-clicking the node will expand its targets, if any.</LI>
<LI><IMG alt="" src="icon.debugger.record"> <B>Target:</B> These are children of their
creating connection. A client can create any number of traces to describe each target it
wishes to trace, but by convention each client ought to create only one. The target node
displays the name of the trace and the last snapshot activated by the client. Double-clicking
the node will activate the target at the last snapshot, and change to <B>Control Target</B>
<A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html#control_mode">mode</A>.</LI>
</UL>
<H2>Actions</H2>
<H3><A name="connect_outbound"></A><IMG alt="" src="icon.debugger.connect.outbound"> Connect
Outbound</H3>
<P>Connect to a back end. The back end plays the role of TCP server while Ghidra plays the TCP
client. The dialog prompts for the (possibly remote) back end's host and port. Once the
connection is established, the back end takes the role of Trace RMI client, despite being the
TCP server. Check the command documentation for your back end's plugin to figure out how to
have it listen first.</P>
<DIV class="image">
<IMG alt="" src="images/ConnectDialog.png">
</DIV>
<H3><A name="connect_accept"></A><IMG alt="" src="icon.debugger.connect.accept"> Connect by
Accept</H3>
<P>Accept a single connection from a back end. Ghidra plays the role of TCP server, and the
back end is the TCP client. The dialog prompts for the host/interface and port on which to
listen. Check the command documentation for your back end's plugin to figure out how to have it
connect to a listening Ghidra. Once the connection is established, the listening port is
closed. The back end plays the role of Trace RMI client.</P>
<H3><A name="close"></A>Close</H3>
<P>Right-click a connection or acceptor to access this action. For an acceptor, this will
cancel it. For an established connection, this will tear it down, rendering its target traces
dead. Note that the back end may retain its live targets, despite losing its connection to
Ghidra.</P>
<H3><A name="close_all"></A>Close All</H3>
<P>Burn it all to the ground and start over. This closes the server, cancels all acceptors, and
tears down all connections. Any live trace in the Debugger will be rendered dead, which often
causes the trace manager to close them. Note that the back ends may retain their live targets,
despite losting their connections to Ghidra.</P>
<H3><A name="start_server"></A>Start Server</H3>
<P>Start a persistent server, able to accept many back-end connections. Ghidra plays the role
of TCP server, and each back end is a TCP client. The dialog prompts for the host/interface and
port on which to listen. Check the command documentation for your back end's plugin to figure
out how to have it connect to a listening Ghidra. The listening port remains open no matter how
many connections it has accepted. It is still possible to connect by other means while the
server is active.</P>
<H3><A name="stop_server"></A>Stop Server</H3>
<P>Stop the server. This closes the persistent server. This does not affect pending acceptors
or established connections.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiConnectionManagerPlugin/images/ConnectDialog.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiConnectionManagerPlugin/images/TraceRmiConnectionManagerPlugin.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 10 KiB

598
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/TraceRmiLauncherServicePlugin.html Normal file
View file

@ -0,0 +1,598 @@
<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">
<HTML>
<HEAD>
<META name="generator" content=
"HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">
<TITLE>Debugger: Launchers</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
</HEAD>
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Launchers</H1>
<P>The Debugger has an updated and simplified launcher system. A nice collection of basic
launchers for our supported platforms are provided out of the box. For Linux, we provide a
suite of GDB-based launchers. For macOS, we provide a suite of LLDB-based launchers (though,
these work on Linux, too). For Windows, we provide a launcher based on the Windows Debugger
(<TT>dbgeng.dll</TT> and <TT>dbgmodel.dll</TT>).</P>
<P>Each launcher automates the creation of a Trace RMI <A href=
"help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionManagerPlugin.html#connect_accept">acceptor</A>,
executes the back-end shell script in a Terminal, then waits for the resulting target trace. In
contrast to the previous system, the Terminal is the first and most basic interface presented.
Even if just about everything else goes wrong, the terminal should still be faithfully
operational:</P>
<DIV class="image">
<IMG alt="" src="images/GdbTerminal.png">
</DIV>
<P>The Terminal is fully integrated into Ghidra's UI and so can be docked or undocked just like
the rest of Ghidra's windows. It provides fairly robust VT-100 emulation. Thus, the user
experience from the Terminal is nearly identical to using the same debugger outside of Ghidra.
This terminal-first approach also ensures that you interact with the target application's
standard I/O. This was not possible in the previous system, as we re-implemented the CLI using
the back end's <TT>execute</TT> method. The debugger's (and so also the target's) actual I/O
streams were hidden away within a GDB/MI wrapper.</P>
<P>Each launcher script sets up a &mdash; usually Python &mdash; environment, launches the
actual debugger, and provides a sequence of commands for it to load the Trace RMI plugin,
connect back to Ghidra, launch the actual target process, and start the target trace. At this
point, the plugin generally takes over, reacting to user and target events, accepting front-end
requests, and generally keeping Ghidra and the back end synchronized.</P>
<P><A name="launch_tracermi"></A>The list of launchers can be accessed in either of two places:
1) In the <B>Debugger &rarr; Configure and Launch ...</B> menu or more conveniently from the
<B>Launch</B> button in the main toolbar. This is the blue bug <IMG alt="" src="icon.debugger">
button near the top center. The <B>Configure and Launch ...</B> menu lists all available
launchers. Selecting one will prompt for its options then launch. To re-launch quickly, use the
<B>Launch</B> button. Clicking it will re-launch using the most recent launcher and
configuration for the current program. If this is the first launch of the given program, the
button will instead activate its drop-down menu. The drop-down is also accessible by clicking
the down arrow next to the <B>Launch</B> button. The drop-down lists all launchers that have
been previously configured for the current program. Clicking one will immediately launch the
program without prompting. The <B>Configure and Launch ...</B> sub-menu of the drop-down
functions exactly like in the <B>Debugger</B> menu.</P>
<P>The Terminal provides some fairly standard actions. Other keyboard control sequences,
notably <B>CTRL-C</B>, are interpreted by the terminal, rather than Ghidra's action system, to
achieve their expected behavior, e.g., interrupt.</P>
<H3><A name="copy"></A>Copy</H3>
<P>This is accessed using the toolbar button or the key sequence <B>CTRL-SHIFT-C</B>. As
expected, it copies the current selection to the system clipboard.</P>
<H3><A name="paste"></A>Paste</H3>
<P>This is accessed using the toolbar button or the key sequence <B>CTRL-SHIFT-V</B>. As
expected, it pastes the text contents of the system clipboard into the terminal, as if
typed.</P>
<H3><A name="find"></A>Find</H3>
<P>This is accessed using the local drop-down menu or the key sequence <B>CTRL-SHIFT-F</B>. It
displays a dialog for searching the terminal's scrollback buffer.</P>
<H3><A name="find_next"></A><A name="find_previous"></A>Find Next/Previous</H3>
<P>These actions are accessed using the local drop-down menu or the key sequence
<B>CTRL-SHIFT-H</B> or <B>CTRL-SHIFT-G</B>, respectively. They repeat the last search in the
forward or backward direction.</P>
<H3><A name="terminate"></A>Terminate</H3>
<P>This action is accessed using the local drop-down menu. It will terminate the Terminal's
current session. Exactly what that means is determined by the Terminal's creator. In general,
it means to destroy the full debugging session associated with the Terminal. That may cause
related terminals, e.g., a secondary terminal for target I/O and associated target traces, to
be terminated as well. <B>NOTE:</B> This action is <EM>not</EM> implied by closing the Terminal
window. Closing the window with an active session merely hides it. It can be recalled using the
<B>Window &rarr; Terminals</B> menu. If the session has already been terminated (indicated by
an orange border) then closing the window will, in fact, destroy the Terminal.</P>
<H2>Stock GDB Launchers</H2>
<P>The following launchers based on GDB (GNU Debugger) are included out of the box:</P>
<H3><A name="gdb"></A>GDB</H3>
<P>This launcher is a Python plugin for GDB, and so is best suited for debugging Linux
user-space targets as well as many embedded systems. Please note you may need to obtain a
properly-configured build of GDB for your target. If you are working with an embedded system,
it is probably safest to install the "multiarch" build of GDB from your package manager.</P>
<P>Once running, you are presented with GDB's command-line interface in Ghidra's Terminal. This
is the <EM>bona fide</EM> GDB command-line interface, so it has all the functionality you would
expect. If you command GDB from this shell, the plugin will keep Ghidra in sync. The terminal
can also be used to interact with the target application when it is running. The plugin
provides an additional set of commands for managing the connection to Ghidra, as well as
controlling trace synchronization. These are all in the "<TT>ghidra</TT>" command prefix. You
can use tab completion to enumerate the available commands and GDB's "<TT>help</TT>" command to
examine their documentation.</P>
<DIV class="image">
<IMG alt="" src="images/GdbLauncher.png">
</DIV>
<H4>Options</H4>
<UL>
<LI><B>Image</B>: This is the path to the target binary image (ELF). Ghidra will try to fill
this in based on information gathered when the current program was imported. If the file
exists and is executable on the local machine, it will be filled in automatically. Otherwise,
it is up to you to locate it. <B>NOTE:</B> If you have patched the current program database,
these changes are <EM>not</EM> applied to the target. You can either 1) apply the same
patches to the target once it is running, or 2) export a patched copy of your image and
direct this launcher to run it.</LI>
<LI><B>Arguments</B>: These are the command-line arguments to pass into the target process.
These are passed as is to GDB's "<TT>set args ...</TT>" command.</LI>
<LI><B>Path to <TT>gdb</TT></B>: This is the command or path to GDB. We recommend version 13
or later. We require version 8 or later.</LI>
<LI><B>Run command</B>: This is the GDB command to actually launch the target. In most cases
this should be "<TT>starti,</TT>" since this will assure you an initial break and a chance to
enable your breakpoints.</LI>
<LI><B>Inferior TTY</B>: Depending on your target and/or personal preference, you may opt to
separate the debugger's and the target's I/O. If you check this box, the launcher will use
GDB's "<TT>set inferior-tty ...</TT>" command to direct the target's I/O to a second Terminal
window.</LI>
</UL>
<H3><A name="gdb_ssh"></A>GDB via SSH</H3>
<P>This works the same as the GDB launcher, but runs <TT>gdb</TT> on a remote system via
<TT>ssh</TT>. In contrast to the previous system, which used an SSH library for Java, this
launcher uses the <TT>ssh</TT> command on the local system. Thus, it should have broader
compatibility with remote systems, and it should use the same configuration files as you are
accustomed to. That said, we developed it using OpenSSH, so your experience will be best if
your copy understands the same command-line arguments. It will need to be capable of port
forwarding. The remote server must permit remote port forwarding (-R option) and terminal
allocation (<TT>-t</TT> option). You will also need to manually install the required Python
packages on the target host, comprising our plugin for GDB and its dependencies.</P>
<H4>Options</H4>
<UL>
<LI><B>Image</B>: This is the path to the target binary image (ELF) <EM>on the remote
system</EM>. Ghidra will try to fill this in based on information gathered when the current
program was imported; however, it cannot examine the <EM>remote</EM> system. If the file
exists and is executable on the <EM>local</EM> machine, it will be filled in automatically.
Whether or not it is filled automatically, please ensure the location is correct with respect
to the remote system. <B>NOTE:</B> If you have patched the current program database, these
changes are <EM>not</EM> applied to the target. You can either 1) apply the same patches to
the target once it is running, or 2) export a patched copy of your image, copy it to the
target system, and direct this launcher to run it.</LI>
<LI><B>Arguments</B>: This works the same as in GDB.</LI>
<LI><B>[User@]Host</B>: This is the host name of the target system, optionally including a
user name. This is passed as is to <TT>ssh</TT>, which may interpret it according to local
configuration.</LI>
<LI><B>Remote Trace RMI Port</B>: An available TCP port on the target system, which will
listen for GDB's Trace RMI connection and forward it back to Ghidra.</LI>
<LI><B>Extra <TT>ssh</TT> arguments</B>: These are extra arguments to pass to <TT>ssh</TT>.
They are inserted immediately after the <TT>ssh</TT> command but before the host name. Beware
that syntax errors may cause strange behavior, and that not all features may be compatible
with this launcher.</LI>
<LI><B>Path to <TT>gdb</TT></B>: This works the same as in GDB, but with respect to the
<EM>remote</EM> file system.</LI>
<LI><B>Run command</B>: This works the same as in GDB.</LI>
<LI>Note there is no option to create a second Terminal (TTY) for the target.</LI>
</UL>
<H3><A name="gdb_gdbserver_ssh"></A>GDB + <TT>gdbserver</TT> via SSH</H3>
<P>This works similarly to the GDB via SSH launcher, but instead of tunneling the Trace RMI
connection, tunnels the RSP (gdbserver) connection. There is actually a fairly elegant method
of doing this straight from within <TT>gdb</TT>, which is exactly what this launcher does:</P>
<UL style="list-style-type: none">
<LI>
<PRE>
target remote | ssh user@host gdbserver - /path/to/image
</PRE>
</LI>
</UL>
<P>This has some advantages compared to running <TT>gdb</TT> on the remote target:</P>
<OL>
<LI>GDB may not be available on the remote target.</LI>
<LI>There is no need to install our plugin for GDB on the target.</LI>
</OL>
<P>But, it also has some drawbacks:</P>
<OL>
<LI><TT>gdbserver</TT> must be installed on the remote system, and the local <TT>gdb</TT>
must be compatible with it.</LI>
<LI>It may be slightly more annoying to map modules from the remote system, because of the
way GDB reports these modules.</LI>
<LI>The memory map may be absent. Though this is overcome by creating an entry for the entire
address space, if the map is of interest to your analysis, it may not be available.</LI>
</OL>
<H4>Options</H4>
<UL>
<LI><B>Image</B>: This works the same as in GDB via SSH.</LI>
<LI><B>Arguments</B>: This works the same as in GDB.</LI>
<LI><B>[User@]Host</B>: This works the same as in GDB via SSH.</LI>
<LI><B>Remote Trace RMI Port</B>: An available TCP port on the target system, which will
listen for GDB's Trace RMI connection and forward it back to Ghidra.</LI>
<LI><B>Extra <TT>ssh</TT> arguments</B>: This works the same as in GDB via SSH.</LI>
<LI><B>Path to <TT>gdbserver</TT></B>: This is the command or path to <TT>gdbserver</TT> with
respect to the <EM>remote</EM> file system.</LI>
<LI><B>Extra <TT>gdbserver</TT> arguments</B>: These are extra arguments to pass to
<TT>gdbserver</TT>. They are inserted immediately after <TT>gdbserver</TT> but before the
dash. Beware that syntax errors may cause strange behavior, and that not all features may be
compatible with this launcher.</LI>
<LI><B>Path to <TT>gdb</TT></B>: This works the same as in GDB, with respect to the
<EM>local</EM> file system.</LI>
<LI>Note there is no option to create a second Terminal (TTY) for the target.</LI>
</UL>
<H3><A name="gdb_qemu"></A>QEMU + GDB</H3>
<P>This launcher orchestrates a QEMU user-mode target and connects to it using our Python
plugin for GDB. You will almost certainly need the "multiarch" build of GDB, and by default,
the launcher will try to use <TT>gdb-multiarch</TT>. You must also install the appropriate
build of QEMU for your target architecture. Ghidra will inspect the current program and attempt
to map its language to the appropriate QEMU command, but this may fail, or be subtly
incorrect.</P>
<H4>Options</H4>
<UL>
<LI><B>Image</B>: This is the path to the target binary image (ELF). This works the same as
in GDB, but is passed to QEMU. This will also provide the name to GDB using its "<TT>file
...</TT>" command.</LI>
<LI><B>Arguments</B>: These are the command-line arguments to pass into the target process.
These are passed as is on QEMU's command line.</LI>
<LI><B>Path to <TT>qemu</TT></B>: The command or path to QEMU.</LI>
<LI><B>QEMU Port</B>: An available TCP port for QEMU to listen on for GDB.</LI>
<LI><B>Extra <TT>qemu</TT> arguments</B>: Extra arguments to pass to <TT>qemu</TT>. These are
inserted immediately after the <TT>qemu</TT> command but before the target program and
arguments. Beware that syntax errors may cause strange behavior, and that not all features
may be compatible with this launcher.</LI>
<LI><B>Path to <TT>gdb</TT></B>: This works the same as in GDB, but defaults to
"gdb-multiarch."</LI>
<LI><B>QEMU TTY</B>: This works similarly as in GDB, but just runs QEMU in the second
Terminal window.</LI>
</UL>
<H3><A name="gdb_wine"></A>Wine + GDB</H3>
<P>This launchers runs <TT>wine</TT> in a <TT>gdb</TT> session on Linux and directs it to a
target Windows executable. There are other ways to rig a Windows target in GDB on Linux, but
this is the method we have chosen: You will need to install Wine on your system and locate the
actual <TT>wine</TT> executable. These are often in some library directory and named
"<TT>wine32</TT>" or "<TT>wine64</TT>." To find them, either examine the file list of the
installed package, or dissect the wrapper <TT>wine</TT> script, usually on your path:</P>
<UL style="list-style-type: none">
<LI>
<PRE>
less $(which wine)
</PRE>
</LI>
</UL>
<P>The locations are usually given in variables at the top of the script, e.g.,
"<TT>/usr/lib/wine/wine64</TT>". One is for 64-bit Windows targets and another is for 32-bit
Windows targets. Unlike native Windows, Wine does not (yet) implement WoW64 (Windows on Windows
64). Instead, the 32-bit target is loaded using a 32-bit copy of Wine, and so is serviced by
Linux's 32-bit system calls. <FONT color="red"><B>NOTE:</B> Careful attention must be given to
select the correct <TT>wine</TT> executable for the target program's architecture!</FONT> Even
though the <TT>wine</TT> executable is smart enough to correct this mistake, it results in
calls to <TT>exec</TT>, which confuse this launcher. If GDB complains that it cannot place
breakpoints because of memory access, it is probably because of this mistake.</P>
<P>The launcher loads some additional support packages in our plugin for GDB, e.g., to scan the
memory map for PE files and amend the module list. Thus, Ghidra can display both Windows and
Linux modules, and map them to its program databases accordingly, despite GDB's inability to
process PE files. There are perhaps other configurations of GDB for Linux that can process ELFs
as well as PEs loaded by Wine, but they do not seem to be readily available in any popular
package repositories.</P>
<H4>Options</H4>
<UL>
<LI><B>Image</B>: This is the path to the target binary image (EXE). This works the same as
in GDB, but is passed to Wine via GDB's "<TT>set args ...</TT>". This will also provide the
name to GDB using its "<TT>file ...</TT>" command.</LI>
<LI><B>Arguments</B>: These are the command-line arguments to pass into the target process.
These are included in "<TT>set args ...</TT>".</LI>
<LI><B>Path to <TT>wine</TT> binary</B>: The path to wine for your target architecture. <FONT
color="red">See note above!</FONT></LI>
<LI><B>Path to <TT>gdb</TT></B>: This works the same as in GDB.</LI>
<LI><B>Inferior TTY</B>: This works the same as in GDB.</LI>
</UL>
<H3><A name="gdb_remote"></A>Remote GDB</H3>
<P>This launcher can target any TCP-based GDB stub that is compatible with a local copy of
<TT>gdb</TT>. Essentially, it just starts <TT>gdb</TT> and then enters</P>
<UL style="list-style-type: none">
<LI>
<PRE>
target remote [host]:[port]
</PRE>
</LI>
</UL>
<P>into it. It is best to test this command outside of Ghidra to be sure everything is
compatible before using this launcher. This launcher does not require an image, nor does it
create your target. Thus, it can be used without a current program.</P>
<H4>Options</H4>
<UL>
<LI><B>Target</B>: The type of target. Either <TT>remote</TT> or <TT>remote-extended</TT>,
depending on the capabilities of the stub.</LI>
<LI><B>Host</B>: The host name of the target stub.</LI>
<LI><B>Port</B>: The TCP port of the target stub.</LI>
<LI><B>Architecture</B> (optional): If the stub does not describe its architecture to GDB,
you must set it before connecting. This is passed as is to "<TT>set arch ...</TT>"
immediately before the "<TT>target ...</TT>" command. Enter "<TT>set arch</TT>" into a GDB
session outside of Ghidra to see the list of available options in your configuration. You may
want to use <TT>gdb-multiarch</TT>.</LI>
<LI><B>Path to <TT>gdb</TT></B>: This works the same as in GDB, though you may want to use
<TT>gdb-multiarch</TT>.</LI>
</UL>
<H3><A name="gdb_raw"></A>Raw GDB</H3>
<P>This is hardly a launcher at all. It simply starts <TT>gdb</TT>, gets it connected to
Ghidra, and starts a trace. This allows you to create or connect to whatever target your copy
of GDB supports. While perhaps the most flexible, it is also the least convenient. It requires
no image, so it can be used without a current program. That also means it will make no effort
to ensure your target maps to the current program, if you happen to have one. You may have to
do it manually.</P>
<H4>Options</H4>
<UL>
<LI><B>Path to <TT>gdb</TT></B>: This works the same as in GDB.</LI>
<LI><B>Architecture</B>: Because the trace is created before the target, you must specify the
target's architecture.</LI>
<LI style="list-style: none">This is passed as is to "<TT>set arch ...</TT>" immediately
before the "<TT>target ...</TT>" command. Enter "<TT>set arch</TT>" into a GDB session
outside of Ghidra to see the list of available options in your configuration.</LI>
</UL>
<H2>Stock LLDB Launchers</H2>
<P>The following launchers based on the LLDB Debugger are included out of the box:</P>
<H3><A name="lldb"></A>LLDB</H3>
<P>This launcher is a Python plugin for LLDB, and so is well suited for debugging user-space
targets on a variety of platforms. It is the <EM>de facto</EM> debugger for macOS. It can be
obtained by installing XCode from the App Store. Though it may require a bit more careful
configuration, it can also be obtained from other repositories like <TT>brew</TT>.</P>
<P>Once running, you are presented with LLDB's command-line interface in Ghidra's Terminal.
This is the <EM>bona fide</EM> LLDB command-line interface, so it has all the functionality you
would expect. If you command LLDB from this shell, the plugin will keep Ghidra in sync. The
terminal can be used to interact with the target application when it is running. The plugin
provides an additional set of commands for managing the connection to Ghidra, as well as
controlling trace synchronization. These are all in the "<TT>ghidra</TT>" category. You can use
tab completion to enumerate the available commands and LLDB's "<TT>help</TT>" command to
examine their documentation.</P>
<H4>Options</H4>
<UL>
<LI><B>Image</B>: This is the path to the target binary image (executable). Ghidra will try
to fill this in based on information gathered when the current program was imported. If the
file exists and is executable on the local machine, it will be filled in automatically.
Otherwise, it is up to you to locate it. <B>NOTE:</B> If you have patched the current program
database, these changes are <EM>not</EM> applied to the target. You can either 1) apply the
same patches to the target once it is running, or 2) export a patched copy of your image and
direct this launcher to run it.</LI>
<LI><B>Arguments</B>: These are the command-line arguments to pass into the target. These are
passed as is to LLDB's "<TT>settings set target.run-args ...</TT>" command.</LI>
<LI><B>Path to <TT>lldb</TT></B>: This is the command or path to LLDB. We recommend version
15 or later.</LI>
<LI><B>Run command</B>: This is the LLDB command to actually launch the target. In most cases
this should include "<TT>--stop-at-entry</TT>", since this will assure you an initial break
and a chance to enable your breakpoints.</LI>
<LI><B>Target TTY</B>: Depending on your target and/or personal preference, you may opt to
separate the debugger's and the target's I/O. If you check this box, the launcher will use
LLDB's "<TT>setting set target.output-path ...</TT>" command (and similar for the input) to
direct the target's I/O to a second Terminal window.</LI>
</UL>
<H3><A name="lldb_remote"></A>Remote LLDB</H3>
<P>This launcher can target any TCP-based GDB stub that is compatible with a local copy of
<TT>lldb</TT>. Essentially, it just starts <TT>lldb</TT> and then enters</P>
<UL style="list-style-type: none">
<LI>
<PRE>
gdb-remote [host]:[port]
</PRE>
</LI>
</UL>
<P>into it. It is best to test this command outside of Ghidra to be sure everything is
compatible before using this launcher. This launcher does not require an image, nor does it
create your target. Thus, it can be used without a current program.</P>
<H4>Options</H4>
<UL>
<LI><B>Host</B>: The host name of the target stub.</LI>
<LI><B>Port</B>: The TCP port of the target stub.</LI>
<LI><B>Architecture</B> (optional): If the stub does not describe its architecture to GDB,
you must set it before connecting. This is passed as is to "<TT>setting set
target.default-arch ...</TT>" immediately before the "<TT>gdb-remote ...</TT>" command.</LI>
<LI><B>Path to <TT>llddb</TT></B>: This works the same as in LLDB.</LI>
</UL>
<H2>Stock Windows Debugger (WinDbg) Launchers</H2>
<P>The following launchers based on Microsoft's <TT>dbgeng.dll</TT> are included out of the
box:</P>
<H3><A name="dbgeng"></A>dbgeng</H3>
<P>This launcher is actually a Python implementation of a console debugger based on
<TT>dbgeng.dll</TT>. This DLL represents the Microsoft Windows Debugger engine, and so is best
suited for debugging Windows user-space targets. Windows kernel targets are not yet supported.
This DLL also backs WinDbg and several other debuggers on Windows. By default, the launcher
will search for this DLL in an installation of the Windows Debugging Kits version 10. If it
does not find it there, it will fall back to the one provided with Windows, which is
substantially less capable. Installing WinDbg is highly recommended. Please note on some system
configurations, one of the debugger's dependencies <TT>dbghelp.dll</TT> may get loaded from the
system directory instead of from the WinDbg installation, usually because a security product
has pre-loaded it into the Python process. You might work around this by copying the affected
DLLs from your WinDbg installation into your Python installation.</P>
<P>Once running, you are presented with a command-line interface in Ghidra's Terminal. This CLI
accepts your usual WinDbg (kd) commands. You can escape from this CLI and enter a Python 3 REPL
by entering "<TT>.exit</TT>". This is not an actual kd command, but our implementation
understands this to mean exit the kd REPL. From the Python 3 REPL, you can access the
underlying Python-based API <TT>pybag</TT>. This is an uncommon need, but may be useful for
diagnostics and/or workarounds. To re-enter the kd REPL, enter "<TT>repl()</TT>".
Alternatively, if you are trying to quit, but typed "<TT>.exit</TT>", just type
"<TT>quit()</TT>" to terminate the session.</P>
<H4>Options</H4>
<UL>
<LI><B>Path to <TT>python</TT></B>: This is the command or path to the Python interpreter. It
must be version 3. Python 2 is not supported.</LI>
<LI><B>Image</B>: This is the path to the target binary image (EXE file). Ghidra will try to
fill this in based on information gathered when the current program was imported. If the file
exists and is executable on the local machine, it will be filled in automatically. Otherwise,
it is up to you to locate it. <B>NOTE:</B> If you have patched the current program database,
these changes are <EM>not</EM> applied to the target. You can either 1) apply the same
patches to the target once it is running, or 2) export a patched copy of your image and
direct this launcher to run it.</LI>
<LI><B>Arguments</B>: These are the command-line arguments to pass into the target process.
These are passed as is into WinDbg's "<TT>CreateProcess</TT>" function.</LI>
<LI><B>Use <TT>dbgmodel</TT></B>: If <TT>dbgmodel.dll</TT> is available on the system, this
launcher will use it to populate the trace's object model. Without that DLL, the launcher
will invent its own model, roughly approximating the same, using just the information
available from <TT>dbgeng.dll</TT>. Disabling this option will prevent the launcher from
using <TT>dbgmodel.dll</TT>, even when it is available.</LI>
<LI><B>Path to <TT>dbgeng</TT></B>: By default, the launcher allows the underlying
<TT>pybag</TT> package to locate the Windows Debugger DLLs. This is typically found by
examining the registry for a Windows Kits 10 installation. Otherwise, it may check its
typical installation directory before falling back to those in the Windows system directory.
This option allows you to override this search. For example, if you have installed WinDbg
Preview or later from the Microsoft Store and wish to use its DLLs, you will need to fill in
this option.</LI>
</UL>
<H3><A name="dbgeng_ttd"></A>TTD (Time-Travel Debugging)</H3>
<P>This is a nascent extension to our launcher for the Windows Debugger. The launcher itself
functions well, but lacks full integration. It is not yet properly packaged for the Ghidra
distribution, but is available in development environments. It also needs some additional
protocol support, namely to integrate its notion of time travel with Ghidra's notion. For the
time being, we map our time specifications as follows. MS TTD uses a tuple for its time specs,
both displayed in hexadecimal, e.g., "B5:1A". The first is the "major," which we believe counts
the events that warrant a snapshot. The second is the "minor," which we believe counts
instructions executed since the major event. Thus, we would like to map the major to a Ghidra
trace snapshot and the minor to steps of p-code emulation. For example, the "B5:1A" notation
would map to "181:26". It should be no surprise the notations are similar, since both MS TTD
and Ghidra (as well as several other "timeless" debuggers) use a snapshot-replay strategy to
recover past machine states. However, we have not yet worked out how to have Ghidra cooperate
with a back end in the replay part of this strategy. Currently, Ghidra will always apply p-code
emulation, despite having a perfectly good and performant back end available. So, for the time
being, we multiply the major number by 1000, thus reserving that many Ghidra snapshots between
major events for MS TTD minor steps. Thus, the notation "B5:1A" will actually map to "181026",
that is snapshot 181026 with no steps of p-code emulation. This hack will fall short if you
visit a time where the minor number exceeds 999.</P>
<P>Furthermore, if you use the Ghidra Debugger UI to visit a past snapshot, the back end is not
yet informed of your intent. You will probably only see stale records of the machine state.
Instead, please use the kd commands from the Terminal to navigate through time. The back end
(MS TTD) will perform the replay, record the snapshot, and command Ghidra to navigate
there.</P>
<H4>Options</H4>
<P>This launcher has the same options as the WinDbg launcher, except that the DLL path must
contain <TT>dbgmodel.dll</TT> and the scripts that implement TTD. These are most easily
obtained by installing WinDbg Preview or later.</P>
<H2>Development and Diagnostic Launchers</H2>
<P>We currently provide one launcher for Trace RMI API exploration and development:</P>
<H3><A name="python_raw"></A>Raw Python</H3>
<P>This launcher runs Python in a Terminal window, connects a Trace RMI client back to Ghidra,
then starts a blank trace. Once running, it presents the Python interpreter, with the
<TT>ghidratrace</TT> and <TT>ghidratrace.client</TT> packages imported into the local
namespace. Thus, a developer can explore the API, invoke methods, and observer how Ghidra
reacts.</P>
<H4>Options</H4>
<UL>
<LI><B>Path to <TT>python</TT></B>: This is the command or path to <TT>python</TT> version 3.
Python 2 is not supported.</LI>
<LI><B>Ghidra Language</B>: The LanguageID for the blank trace.</LI>
<LI><B>Ghidra Compiler</B>: The CompilerSpecID for the blank trace.</LI>
</UL>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbLauncher.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/topics/TraceRmiLauncherServicePlugin/images/GdbTerminal.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 43 KiB

8
Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/app/plugin/core/debug/gui/tracermi/launcher/AbstractTraceRmiLaunchOffer.java
View file

@ -441,9 +441,11 @@ public abstract class AbstractTraceRmiLaunchOffer implements TraceRmiLaunchOffer
PtyParent parent = pty.getParent();
PtyChild child = pty.getChild();
Terminal terminal = terminalService.createWithStreams(Charset.forName("UTF-8"),
Terminal terminal = terminalService.createWithStreams(plugin, Charset.forName("UTF-8"),
parent.getInputStream(), parent.getOutputStream());
terminal.setSubTitle(ShellUtils.generateLine(commandLine));
List<String> withoutPath = ShellUtils.removePath(commandLine);
terminal.setSubTitle(ShellUtils.generateLine(withoutPath));
TerminalListener resizeListener = new TerminalListener() {
@Override
public void resized(short cols, short rows) {
@ -491,7 +493,7 @@ public abstract class AbstractTraceRmiLaunchOffer implements TraceRmiLaunchOffer
PtyParent parent = pty.getParent();
PtyChild child = pty.getChild();
Terminal terminal = terminalService.createWithStreams(Charset.forName("UTF-8"),
Terminal terminal = terminalService.createWithStreams(plugin, Charset.forName("UTF-8"),
parent.getInputStream(), parent.getOutputStream());
TerminalListener resizeListener = new TerminalListener() {
@Override

10
Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/app/plugin/core/debug/service/tracermi/TraceRmiHandler.java
View file

@ -481,6 +481,14 @@ public class TraceRmiHandler implements TraceRmiConnection {
private interface Dispatcher {
RootMessage.Builder dispatch(RootMessage req, RootMessage.Builder rep) throws Exception;
default String exceptionMessage(Throwable exc) {
String msg = exc.getMessage();
if (msg == null) {
return exc.getClass().getCanonicalName();
}
return exc.getClass().getCanonicalName() + ": " + msg;
}
default RootMessage handle(RootMessage req) {
String desc = toString(req);
if (desc != null) {
@ -494,7 +502,7 @@ public class TraceRmiHandler implements TraceRmiConnection {
catch (Throwable e) {
Msg.error(this, "Exception caused by back end", e);
return rep.setError(ReplyError.newBuilder()
.setMessage(e.getMessage()))
.setMessage(exceptionMessage(e)))
.build();
}
}

75
Ghidra/Debug/Debugger-rmi-trace/src/screen/java/ghidra/app/plugin/core/debug/gui/tracermi/connection/TraceRmiConnectionManagerPluginScreenShots.java Normal file
View file

@ -0,0 +1,75 @@
/* ###
* IP: GHIDRA
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package ghidra.app.plugin.core.debug.gui.tracermi.connection;
import java.net.InetSocketAddress;
import org.junit.Test;
import ghidra.app.plugin.core.debug.gui.objects.components.DebuggerMethodInvocationDialog;
import ghidra.app.plugin.core.debug.gui.tracermi.connection.TraceRmiConnectionManagerProviderTest.Cx;
import ghidra.app.plugin.core.debug.gui.tracermi.connection.tree.TraceRmiConnectionNode;
import ghidra.app.plugin.core.debug.gui.tracermi.connection.tree.TraceRmiConnectionTreeHelper;
import ghidra.app.plugin.core.debug.service.tracermi.DefaultTraceRmiAcceptor;
import ghidra.app.plugin.core.debug.service.tracermi.TraceRmiPlugin;
import help.screenshot.GhidraScreenShotGenerator;
public class TraceRmiConnectionManagerPluginScreenShots extends GhidraScreenShotGenerator {
private TraceRmiPlugin servicePlugin;
private TraceRmiConnectionManagerPlugin managerPlugin;
@Test
public void testCaptureTraceRmiConnectionManagerPlugin() throws Throwable {
servicePlugin = addPlugin(tool, TraceRmiPlugin.class);
managerPlugin = addPlugin(tool, TraceRmiConnectionManagerPlugin.class);
TraceRmiConnectionManagerProvider provider =
waitForComponentProvider(TraceRmiConnectionManagerProvider.class);
servicePlugin.startServer();
DefaultTraceRmiAcceptor acceptor =
servicePlugin.acceptOne(new InetSocketAddress("localhost", 0));
DefaultTraceRmiAcceptor forCx =
servicePlugin.acceptOne(new InetSocketAddress("localhost", 0));
try (Cx cx = Cx.complete(forCx, "demo-dbg")) {
cx.client().createTrace(0, "bash");
TraceRmiConnectionNode node =
TraceRmiConnectionTreeHelper.getConnectionNodeMap(provider.rootNode)
.get(cx.connection());
provider.tree.expandTree(node);
waitForTasks();
captureIsolatedProvider(provider, 400, 300);
}
finally {
acceptor.cancel();
}
}
@Test
public void testCaptureConnectDialog() throws Throwable {
servicePlugin = addPlugin(tool, TraceRmiPlugin.class);
managerPlugin = addPlugin(tool, TraceRmiConnectionManagerPlugin.class);
TraceRmiConnectionManagerProvider provider =
waitForComponentProvider(TraceRmiConnectionManagerProvider.class);
performAction(provider.actionConnectOutbound, provider, false);
captureDialog(DebuggerMethodInvocationDialog.class);
}
}

2
Ghidra/Debug/Debugger-rmi-trace/src/test/java/ghidra/app/plugin/core/debug/gui/tracermi/connection/TraceRmiConnectionManagerProviderTest.java
View file

@ -208,7 +208,7 @@ public class TraceRmiConnectionManagerProviderTest extends AbstractGhidraHeadedD
TraceRmiConnectionTreeHelper.getAcceptorNodeMap(provider.rootNode).get(acceptor));
}
record Cx(SocketChannel channel, TestTraceRmiClient client,
public record Cx(SocketChannel channel, TestTraceRmiClient client,
TraceRmiConnection connection)
implements AutoCloseable {
public static Cx complete(TraceRmiAcceptor acceptor, String description)

16
Ghidra/Debug/Debugger/certification.manifest
View file

@ -33,6 +33,8 @@ src/main/help/help/topics/DebuggerMemoryBytesPlugin/DebuggerMemoryBytesPlugin.ht
src/main/help/help/topics/DebuggerMemoryBytesPlugin/images/DebuggerMemoryBytesPlugin.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerMemviewPlugin/DebuggerMemviewPlugin.html||GHIDRA||||END|
src/main/help/help/topics/DebuggerMemviewPlugin/images/DebuggerMemviewPlugin.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html||GHIDRA||||END|
src/main/help/help/topics/DebuggerModelPlugin/images/DebuggerModelPlugin.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerModelServicePlugin/DebuggerModelServicePlugin.html||GHIDRA||||END|
src/main/help/help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html||GHIDRA||||END|
src/main/help/help/topics/DebuggerModulesPlugin/images/DebuggerModuleMapProposalDialog.png||GHIDRA||||END|
@ -42,20 +44,6 @@ src/main/help/help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html||GHID
src/main/help/help/topics/DebuggerObjectsPlugin/images/DebuggerBreakpointDialog.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/DebuggerMethodInvocationDialog_ForLaunch.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/DebuggerObjectsPlugin.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/breakpoint-set.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_graph.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_table.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_tree.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_xml.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_graph.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_table.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_tree.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_xml.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/export_as_facts.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/export_as_xml.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/import_from_facts.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/import_from_xml.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerObjectsPlugin/images/stop.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerPcodeStepperPlugin/DebuggerPcodeStepperPlugin.html||GHIDRA||||END|
src/main/help/help/topics/DebuggerPcodeStepperPlugin/images/DebuggerPcodeStepperPlugin.png||GHIDRA||||END|
src/main/help/help/topics/DebuggerPlatformPlugin/DebuggerPlatformPlugin.html||GHIDRA||||END|

3
Ghidra/Debug/Debugger/data/debugger.theme.properties
View file

@ -134,6 +134,7 @@ icon.debugger.provider.registers = registers.png
icon.debugger.provider.stack = stack.png
icon.debugger.provider.breakpoints = breakpoint-mixed.png
icon.debugger.provider.modules = modules.png
icon.debugger.provider.mappings = icon.content.handler.program
icon.debugger.provider.pcode = stepinto.png
icon.debugger.provider.regions = memory16.gif
icon.debugger.provider.time = time.png
@ -157,6 +158,8 @@ icon.debugger.map.identically = doubleArrow.png
icon.debugger.map.modules = modules.png
icon.debugger.map.sections = icon.debugger.map.modules
icon.debugger.map.regions = icon.debugger.map.modules
icon.debugger.map.auto = icon.debugger.config
icon.debugger.map.manual = icon.debugger.provider.mappings
icon.debugger.block = icon.debugger.map.sections
icon.debugger.select.addresses = text_align_justify.png
icon.debugger.data.types = dataTypes.png

60
Ghidra/Debug/Debugger/src/main/help/help/TOC_Source.xml
View file

@ -54,7 +54,7 @@
target="help/topics/Debugger/Debugger.html" >
<tocdef id="DebuggerGettingStarted" text="Getting Started"
sortgroup="a"
sortgroup="g"
target="help/topics/Debugger/GettingStarted.html" >
<tocdef id="Launching" text="Launching a Target"
@ -63,11 +63,11 @@
</tocdef>
<tocdef id="DebuggerTroubleshooting" text="Troubleshooting"
sortgroup="b"
sortgroup="m"
target="help/topics/Debugger/Troubleshooting.html" />
<tocdef id="DebuggerTargetsPlugin" text="Targets"
sortgroup="c"
sortgroup="m"
target="help/topics/DebuggerTargetsPlugin/DebuggerTargetsPlugin.html" >
<tocdef id="DebuggerModelServicePlugin" text="Tool Actions"
@ -76,55 +76,59 @@
</tocdef>
<tocdef id="DebuggerConsolePlugin" text="Debug Console"
sortgroup="c1"
sortgroup="m"
target="help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html" />
<tocdef id="DebuggerCopyActionsPlugin" text="Copy Actions"
sortgroup="c2"
sortgroup="m"
target="help/topics/DebuggerCopyActionsPlugin/DebuggerCopyActionsPlugin.html" />
<tocdef id="DebuggerObjectsPlugin" text="Commands and Objects"
sortgroup="d"
sortgroup="m"
target="help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html" />
<tocdef id="DebuggerModelPlugin" text="Model"
sortgroup="m"
target="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html" />
<tocdef id="DebuggerInterpreterPlugin" text="Interpreters"
sortgroup="e"
sortgroup="m"
target="help/topics/DebuggerInterpreterPlugin/DebuggerInterpreterPlugin.html" />
<tocdef id="DebuggerThreadsPlugin" text="Threads and Traces"
sortgroup="f"
<tocdef id="DebuggerThreadsPlugin" text="Threads"
sortgroup="m"
target="help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html" />
<tocdef id="DebuggerTraceManagerServicePlugin" text="Trace Management"
sortgroup="g"
sortgroup="m"
target="help/topics/DebuggerTraceManagerServicePlugin/DebuggerTraceManagerServicePlugin.html" />
<tocdef id="DebuggerEmulationServicePlugin" text="Emulation"
sortgroup="g1"
sortgroup="m"
target="help/topics/DebuggerEmulationServicePlugin/DebuggerEmulationServicePlugin.html" />
<tocdef id="DebuggerMemoryBytesPlugin" text="Memory"
sortgroup="h1"
sortgroup="m"
target="help/topics/DebuggerMemoryBytesPlugin/DebuggerMemoryBytesPlugin.html" />
<tocdef id="DebuggerRegistersPlugin" text="Registers"
sortgroup="h"
sortgroup="m"
target="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html" />
<tocdef id="DebuggerListingPlugin" text="Dynamic Listing"
sortgroup="i"
sortgroup="m"
target="help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html" />
<tocdef id="DebuggerDisassemblerPlugin" text="Disassembly and Assembly"
sortgroup="i1"
sortgroup="m"
target="help/topics/DebuggerDisassemblerPlugin/DebuggerDisassemblerPlugin.html" />
<tocdef id="DebuggerStackPlugin" text="Stack"
sortgroup="j"
sortgroup="m"
target="help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html" />
<tocdef id="DebuggerBreakpointsPlugin" text="Breakpoints"
sortgroup="k"
sortgroup="m"
target="help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html" >
<tocdef id="DebuggerBreakpointMarkerPlugin" text="In the Listings"
@ -133,48 +137,48 @@
</tocdef>
<tocdef id="DebuggerRegionsPlugin" text="Memory Regions"
sortgroup="l"
sortgroup="m"
target="help/topics/DebuggerRegionsPlugin/DebuggerRegionsPlugin.html" />
<tocdef id="DebuggerTimePlugin" text="Time"
sortgroup="m"
sortgroup="m"
target="help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html" />
<tocdef id="DebuggerModulesPlugin" text="Modules and Sections"
sortgroup="n"
sortgroup="m"
target="help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html" >
<tocdef id="DebuggerStaticMappingPlugin" text="Static Mappings"
sortgroup="a"
sortgroup="a"
target="help/topics/DebuggerStaticMappingPlugin/DebuggerStaticMappingPlugin.html" />
</tocdef>
<tocdef id="DebuggerWatchesPlugin" text="Watches"
sortgroup="n"
sortgroup="m"
target="help/topics/DebuggerWatchesPlugin/DebuggerWatchesPlugin.html" />
<tocdef id="VariableValueHoverPlugin" text="Variable Hovers"
sortgroup="n1"
sortgroup="m"
target="help/topics/VariableValueHoverPlugin/VariableValueHoverPlugin.html" />
<tocdef id="DebuggerControlPlugin" text="Control and Machine State"
sortgroup="n2"
sortgroup="m"
target="help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html" />
<tocdef id="DebuggerMemviewPlugin" text="Memview Plot"
sortgroup="o"
sortgroup="m"
target="help/topics/DebuggerMemviewPlugin/DebuggerMemviewPlugin.html" />
<tocdef id="DebuggerPcodeStepperPlugin" text="P-code Stepper"
sortgroup="p"
sortgroup="m"
target="help/topics/DebuggerPcodeStepperPlugin/DebuggerPcodeStepperPlugin.html" />
<tocdef id="DebuggerTraceDiffPlugin" text="Comparing Times"
sortgroup="p1"
sortgroup="m"
target="help/topics/DebuggerTraceViewDiffPlugin/DebuggerTraceViewDiffPlugin.html" />
<tocdef id="DebuggerPlatformPlugin" text="Platform Selection"
sortgroup="p2"
sortgroup="m"
target="help/topics/DebuggerPlatformPlugin/DebuggerPlatformPlugin.html" />
</tocdef>
</tocref>

43
Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/Debugger.html
View file

@ -15,38 +15,37 @@
<P>The Debugger is a collection of plugins comprising Ghidra's Dynamic Analysis Framework. This
includes a platform for connecting to and controlling debuggers. Ghidra is not a debugger in
itself, but rather, it relies on existing 3rd-party debuggers, their APIs, wire protocols,
and/or command-line interfaces. Such connectors are pluggable, allowing Ghidra to be extended
and integrated with additional debuggers.</P>
itself, but rather, it relies on existing 3rd-party ("back end") debuggers, their APIs, wire
protocols, and/or command-line interfaces. Such back ends are pluggable, allowing Ghidra to be
extended and integrated with additional debuggers.</P>
<P>When Ghidra recognizes the platform of a target in a connected debugger, it can record that
target into a local database and display the target state. Without recording, the UI will at
least allow interaction through a generic model and/or the debugger's command-line interface.
The recording, called a Trace in Ghidra, logs all the observations made by the framework or the
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 committed to a Ghidra Server for sharing and revision
control; however, conflicting changes <EM>cannot</EM> be merged.</P>
<P>Once a target is launched in the back end, the debugger can record that target into a Ghidra
Trace database, and the UI will display the target state. The user can command the debugger
using it's command-line interface (CLI) or the actions provided in Ghidra's Debugger UI. The
trace logs all the observations made by the framework or the user. The user can rewind this
recording during or after a session, 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 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
imported Ghidra programs to modules recorded in a trace. By default, Ghidra will synchronize
the cursor in the dynamic listing with that in the static listing, and encourage the user to
import missing modules. In this way, existing static analysis is readily at hand during a
dynamic analysis session, and the user can further populate program databases during a
imported Ghidra Program databases to modules recorded in a trace. By default, Ghidra will
synchronize the cursor in the dynamic listing with that in the static listing, and encourage
the user to import missing modules. In this way, existing static analysis is readily at hand
during a dynamic analysis session, and the user can further populate program databases during a
debugging session. However, target memories contain more spaces than program images, e.g.,
stack and heap space, and some of those spaces are modified at runtime, e.g., .bss or .data.
This information, if observed, is dutifully recorded into the trace for immediate or offline
analysis.</P>
<P>A variety of plugins allow the user to interact with the target directly, view and
manipulate machine state, set breakpoints, view recordings, etc. See the table of contents for
a comprehensive list of current plugins. Plugins generally fall into one of these
categories:</P>
<P>A variety of plugins allow the user to interact with the target, view and manipulate machine
state, set breakpoints, view recordings, etc. See the table of contents for a comprehensive
list of current plugins. Plugins generally fall into one of these categories:</P>
<OL>
<LI>Target manipulation - those used for managing connections and interacting with targets,
regardless of tracing</LI>
<LI>Target manipulation - those used for managing connections and interacting with
targets.</LI>
<LI>Trace manipulation - those used for viewing and manipulating the trace database,
including machine state inspection. Most of these behave differently when the view is "at the

199
Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/GettingStarted.html
View file

@ -13,156 +13,133 @@
<BODY lang="EN-US">
<H1>Debugger: Getting Started</H1>
<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>
<P>The debugger supports debugging native user-mode applications for Linux, macOS, and Windows
on 64-bit x86 and often arm64, e.g., when on "Apple Silicon." While not official, it also
supports a variety of other platforms, so long as Ghidra can connect to a debugger that
supports it. Launching is accomplished by connecting to the respective debugger for the target
platform: GDB on Linux, LLDB on macOS, and the Windows Debugger (<TT>dbgeng.dll</TT>) on
Windows. Several launch configurations are already included, and new launchers are fairly
easily added by writing shell scripts.</P>
<H2>Pay Attention to Errors</H2>
<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>
target is paused. In most cases, errors on automatic actions are dropped to the <A href=
"help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A>, as displaying
them in a dialog could become a pest. That said, if things still don't seem right, please check
the terminal or Ghidra's application log.</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 two steps:</P>
<P>Starting up the Ghidra Debugger for user-mode debugging of a local process usually entails
just two steps:</P>
<OL>
<LI>Open (or import) your program into the Debugger tool</LI>
<LI>Click the "Debug" button ("bug" icon) in the main toolbar</LI>
<LI>Click the <B>Launch</B> <IMG alt="(bug icon)" src="icon.debugger"> button in the main
toolbar</LI>
</OL>
<P>To load the default Debugger tool, from the main Ghidra application window select <SPAN
class="menu">Tools &rarr; Import Default Tools...</SPAN> from the menus. Select
"defaultTools/Debugger.tool", and hit "OK". The Debugger tool will be added to the Tool
<P>The first time you launch a given program, you may be asked to select and configure a
specific launcher. To load the default Debugger tool, from the main Ghidra application window
select <B>Tools &rarr; Import Default Tools...</B> from the menus. Select
"defaultTools/Debugger.tool", and hit <B>OK</B>. The Debugger tool will be added to the Tool
Chest.</P>
<P>To launch the tool, you have several options, identical to those you might use to launch the
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>
in the Tool Chest, or you can right-click on one of the programs in the project and pick
<B>Open With &rarr; Debugger</B>. If you open an empty Debugger tool, you can add programs to
it later in the usual ways, e.g. via <B>File &rarr; Import File...</B> or by
dragging-and-dropping programs onto the running tool.</P>
<P>The default tool is pre-configured with a collection of plugins relevant for the Listing and
for Debugger-related operations. As always, there is some chance that the tool will launch with
some portion of the plugins not displayed or with a less-than-optimal layout. To verify which
plugins you have, you can select <SPAN class="menu">File &rarr; Configure</SPAN>. "Debugger"
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.</P>
<P>The default tool is pre-configured with a collection of plugins relevant to both dynamic and
static analysis. As always, there is some chance that the tool will launch with some portion of
the plugins not displayed or with a less-than-optimal layout. To verify which plugins you have,
you can select <B>File &rarr; Configure</B>. "Debugger" should already be selected. Choosing
<B>Configure All Plugins</B> <IMG alt="(the plug icon)" src="icon.extension.configure"> near
the top right should show the full list of pre-selected plugins. Debugger-related plugins all
begin with "Debugger" or "TraceRmi."</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
<P>For the <B>Launch</B> 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>
the path to the executable for the current file system. You can verify this using the <B>Help
&rarr; About my_program</B> menu item in the main tool bar. For example, on a Linux system, if
you've imported "xclock", <B>Help &rarr; About xclock...</B> should have an entry at the bottom
of the page for "<TT>Executable Location: /usr/bin/xclock</TT>".</P>
<P>When you launch the target by this method, a number of changes should be evident in the GUI.
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
A Terminal should appear, containing the actual back end debugger, likely including some
initialization messages and diagnostics. A new trace will appears in the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Listing</A>. 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. 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>
"help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window. The 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 <A href=
"help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A> should provide
some hints as to ongoing activity.</P>
<H2>Debugger Components</H2>
<P>Some of the more commonly-access components are explained below. Many also have their own
<P>Some of the more commonly accessed components are explained below. They also have their own
help pages.</P>
<H3>Debugging Agent</H3>
<H3>Terminal</H3>
<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
fashion. The blank "Agent" window allows you to see the current status of the agent. If the
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
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>
<P>The terminal window allows a user command-line access to the native debugger. For Linux,
this means the standard GDB command line interface; for macOS, the LLDB command line interface;
and 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 have not or cannot be implemented generically in the GUI. Additionally, if for
some reason the connection to Ghidra fails, the terminal will still provide command-line access
for diagnostics and/or manual recovery.</P>
<H3>Interpreter</H3>
<H3>Model</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 have not or cannot be
implemented generically in the GUI.</P>
<P>The <A href="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window
displays a directory of objects in a 3d-party debugging session using a structure determined by
its back-end plugin. In some cases, e.g., when the back end does not recognize the target's
architecture, other displays may struggle to display meaningful information. Even then, this
window should provide a good overview of the debugger's and its target's current state. It may
also provide some useful commands for diagnostics, but the terminal may be a better choice.</P>
<H3>Targets / Connections</H3>
<H3>Listing</H3>
<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. Using this method of starting a connection requires the additional step of
launching or attaching to a specific target.</P>
<P>The back end uses its connection to Ghidra to create a trace and record target information
into it. The Debugger's various windows all derive their contents from the current trace.
Perhaps the most important of these is the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Listing</A> window. Analogous to
the static listing, it displays the raw bytes in the target's memory and allows the user to
mark them up, e.g., disassemble, place data types, comment. Unlike the static listing, this
window shows live bytes in all valid memory, including stacks and heaps. When it can, the
Ghidra debugger keeps the cursor locations in the Static and Dynamic Listings synchronized.</P>
<H3>Objects</H3>
<H3>Controls and Miscellany</H3>
<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>
<P>The main toolbar provides your standard debugging controls, e.g., resume, step, interrupt.
They apply to the current thread or frame as defined by the back end's command set. For
details, see the <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control</A> plugin. During or
after a session, the user can examine trace history or emulate by changing control mode.</P>
<H3>Traces and Threads</H3>
<P>The Targets, Objects, and Interpreter windows are the only windows populated directly using
information gleaned directly from the target. All other windows derive information from the
current trace. Once triggered, Ghidra captures information from the current debugging session
and uses this information to fill the other windows. The most important of these is the
"Threads" provider. The Threads window has two parts: one on the left listing the set of traced
target threads and one on the right indicating the current position in the trace by thread. If
no process is being traced or no thread is selected, all of the remaining windows will be
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. 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. 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>
<P>Breakpoints can be set from either the <A href=
"help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html">Breakpoints</A> window
or the <A href=
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Listing</A>.
The <A href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A>
and <A href="help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html">Stack</A> windows
reflect the state of the current thread, which can be selected in the <A href=
"help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html">Threads</A> window. Typically,
the thread selected for the trace in the Threads window is kept in sync with the
active/selected/focused thread in the back-end debugger, but not always.</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>
<P>The <A href="help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A>
is a central place for reporting activity, errors, and suggesting actions. This and the
Terminal are the first places to look when troubleshooting.</P>
</BODY>
</HTML>

103
Ghidra/Debug/Debugger/src/main/help/help/topics/Debugger/Troubleshooting.html
View file

@ -15,68 +15,79 @@
<P>Often, it's a good idea to troubleshoot by using the target platform's recommended debugger
without connecting it to Ghidra. If it doesn't work there, it's not likely to work in Ghidra,
since it relies on that debugger. For Linux, use gdb; for Windows, use WinDbg; for macOS, use
LLDB.</P>
since it relies on that debugger. For Linux, use gdb; for macOS, use LLDB; for Windows, use
WinDbg.</P>
<H2>Terminal</H2>
<P>The first place to look when you're having trouble is the debugger's terminal. If you do not
see one, check the <B>Window &rarr; Terminals</B> menu. If there is not one there, then there
is no back-end debugger running &mdash; unless, perhaps, you are trying to use a Recorder-based
target. See <A href="#plugin_conf">Plugin Configuration</A> if you suspect this is the
case.</P>
<P>If you already have the correct set of TraceRmi-based plugins enabled, but there is still no
terminal after attempting to launch, then the launcher is sorely mis-configured, or your system
or installation is broken. Use <B>Debugger &rarr; Configure and Launch ...</B> in the menus to
examine and modify your configuration and try again. This menu is also avaible in the drop-down
next to the <B>Launch</B> <IMG alt="" src="icon.debugger"> button.</P>
<P>If you do have a terminal, then examine it, starting at the very top, for errors and
warnings.</P>
<H2>Error Console</H2>
<P>The first place to look when you're having trouble is the Debug Console. Second, if you're
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>
<P>The next place to look is the <A href=
"help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html">Debug Console</A>. Launchers and
plugins for the Debugger often direct their diagnostic messages to this console, and sometimes
offer remedies.</P>
<H2>Settings and Toggles</H2>
<H2>Application Log</H2>
<P>This list is not exhaustive, but here are some options to examine if you're having trouble.
In the FrontEnd tool, under <SPAN class="menu">Edit &rarr; Tool Options</SPAN>, select
"Debugger.Workflow."</P>
<P>The next place to look is Ghidra's application log. From the main project window (not the
Debugger tool window), select <B>Help &rarr; Show Log</B> in the menus. This is Ghidra's full
application log, so you may need to sift through it for debugger-related entries. Usually
searching for "debugger", "launch", "tracermi", or the name of your platform's debugger, etc.,
will help. If you're running from Eclipse, you can check its "Console" window.</P>
<H2><A name="plugin_conf"></A>Plugin Configuration</H2>
<P>It is possible you have an old Debugger tool still configured for Recorder-based targets.
Recorder-based targets are being replaced by TraceRmi-based targets. Try re-importing the
default Debugger tool.</P>
<P>Alternatively, use <B>File &rarr; Configure</B> then click the plug <IMG alt="" src=
"icon.extension.configure"> icon near the top right to check your tool configuration. The
following should be enabled:</P>
<UL>
<LI>"Map modules..." and "Map sections..." control how the debugger attempts to map static
and dynamic memory.</LI>
<LI>TraceRmiPlugin</LI>
<LI>"Disassemble..." triggers automatic disassembly in the dynamic view.</LI>
<LI>TraceRmiLauncherServicePlugin</LI>
<LI>"Show debugger interpreter..." automatically provides access to the command line.</LI>
<LI>TraceRmiConnectionManagerPlugin</LI>
<LI>DebuggerModelPlugin</LI>
</UL>
<P>In the Dynamic Listing:</P>
<P>The following should be disabled:</P>
<UL>
<LI>"Sync to Static Listing" controls the tracking of the Static listing.</LI>
<LI>DebuggerModelServicePlugin</LI>
<LI>DebuggerModelServiceProxyPlugin</LI>
<LI>DebuggerInterpretersPlugin</LI>
<LI>DebuggerObjectsPlugin</LI>
<LI>DebuggerTargetsPlugin</LI>
</UL>
<P>In the Objects provider:</P>
<P>It is possible to leave both sets of plugins enabled, but this is by all means <EM>NOT</EM>
recommended.</P>
<UL>
<LI>"Record Automatically" causes a trace to be started when a Process object comes into
view. If the process object is not exposed automatically, you may have to expand the tree to
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 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>
<P>In the Threads provider:</P>
<UL>
<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 "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>
<H2>Tutorial</H2>
<P>Additional troubleshooting recommendations are given in the Debugger course materials.</P>
</BODY>

63
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html
View file

@ -13,14 +13,9 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Breakpoints in the Listings</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerBreakpointMarkerPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerBreakpointMarkerPlugin.png">
</DIV>
<P>For a description of how breakpoints are managed logically in Ghidra, please read about the
<A href="help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html">Breakpoints</A>
@ -37,14 +32,9 @@
<H2>In the Function Graph</H2>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerFunctionGraphBreakpointMargin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerFunctionGraphBreakpointMargin.png">
</DIV>
<P>When active in the Debugger, the <A href=
"help/topics/FunctionGraphPlugin/Function_Graph.html">Function Graph</A> will display
@ -55,14 +45,9 @@
<H2>In the Decompiler</H2>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerDecompilerBreakpointMargin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerDecompilerBreakpointMargin.png">
</DIV>
<P>When active in the Debugger, the <A href=
"help/topics/DecompilePlugin/DecompilerIntro.html">Decompiler</A> will display breakpoints in
@ -86,8 +71,8 @@
other address-based contexts, but not all of those contexts include visual breakpoint
indicators.</P>
<H3><A name="toggle_breakpoint"></A><IMG alt="" src="images/breakpoint-mixed.png"> Toggle
Breakpoint (K)</H3>
<H3><A name="toggle_breakpoint"></A><IMG alt="" src="icon.debugger.breakpoint.marker.mixed">
Toggle Breakpoint (K)</H3>
<P>This action is always available, and it is suitable for almost all cases. If there is a
breakpoint at the cursor, this simply toggles its state. If there is no breakpoint at the
@ -99,7 +84,7 @@
actions to force specific commands. <B>NOTE:</B> The default parameters are not guaranteed to
be accepted by the connected debugger.</P>
<H3><A name="set_breakpoint"></A><IMG alt="" src="images/breakpoint-enable.png"> Set
<H3><A name="set_breakpoint"></A><IMG alt="" src="icon.debugger.breakpoint.set"> Set
Breakpoint</H3>
<P>This menu is available on the dynamic listing when the target supports at least one
@ -107,18 +92,12 @@
breakpoint actions for each reasonable combination of kinds supported by the target. In the
static listing, all reasonable combinations are available, regardless of target support;
however, only those kinds supported by the target will be included in the resulting command.
<B>NOTE:</B> Breakpoints in the static listing can only be mapped to targets which are recorded
into a trace. Selecting one of the actions will display a prompt allowing adjustments to the
parameters before issuing the command.</P>
Selecting one of the actions will display a prompt allowing adjustments to the parameters
before issuing the command.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerPlaceBreakpointDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerPlaceBreakpointDialog.png">
</DIV>
<UL>
<LI>Address - the address of the breakpoint. It defaults to the address of the instruction or
@ -136,19 +115,19 @@
static location, if applicable.</LI>
</UL>
<H3><A name="enable_breakpoint"></A><IMG alt="" src="images/breakpoint-enable.png"> Enable
<H3><A name="enable_breakpoint"></A><IMG alt="" src="icon.debugger.breakpoint.enable"> Enable
Breakpoint</H3>
<P>This action is available when there is at least one disabled breakpoint at the cursor. It
enables those logical breakpoints.</P>
<H3><A name="disable_breakpoint"></A><IMG alt="" src="images/breakpoint-disable.png"> Disable
Breakpoint</H3>
<H3><A name="disable_breakpoint"></A><IMG alt="" src="icon.debugger.breakpoint.disable">
Disable Breakpoint</H3>
<P>This action is available when there is at least one enabled breakpoint at the cursor. It
disables those logical breakpoints.</P>
<H3><A name="clear_breakpoint"></A><IMG alt="" src="images/breakpoint-clear.png"> Clear
<H3><A name="clear_breakpoint"></A><IMG alt="" src="icon.debugger.breakpoint.clear"> Clear
(Delete) Breakpoint</H3>
<P>This action is available when there is at least one breakpoint (in any state) at the cursor.

204
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointsPlugin/DebuggerBreakpointsPlugin.html
View file

@ -13,154 +13,147 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Breakpoints</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerBreakpointsPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerBreakpointsPlugin.png">
</DIV>
<P>The breakpoints window tabulates and manipulates breakpoints among all traces, including
live targets. Only address-based breakpoints are tabulated. For other traps, e.g., "break on
exception," see the <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html">Objects Window</A>. Breakpoints
can also be manipulated from address-based views, especially the disassembly listings. See <A
href=
"help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window. Breakpoints can
also be manipulated from address-based views, especially the disassembly listings. See <A href=
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Breakpoints in
the Listings</A>.</P>
<P>Individual breakpoint locations from among the traces are consolidated into logical
breakpoints, based on their addresses in the static listing. The static locations are typically
stored as bookmarks in their respective Ghidra programs, comprising the current breakpoint set.
See the <A href=
"help/topics/DebuggerStaticMappingPlugin/DebuggerStaticMappingPlugin.html">Static Mappings</A>
window for the finer details of address mapping. A breakpoint which cannot be mapped to a
static address becomes its own logical breakpoint at its dynamic address. The top table of the
provider displays logical breakpoints; the bottom table displays individual trace breakpoint
locations. <B>NOTE:</B> The breakpoints window cannot display or manipulate breakpoints from a
live target until that target is recorded into a trace. Only those breakpoints visible at the
current snapshot of each trace are included. For live targets, this is typically the latest
snapshot, i.e., the present.</P>
breakpoints, based on their addresses in the static listing. The current breakpoint set
comprises the static locations, stored as bookmarks in their respective program databases. See
the <A href="help/topics/DebuggerStaticMappingPlugin/DebuggerStaticMappingPlugin.html">Static
Mappings</A> window for the finer details of address mapping. A breakpoint which cannot be
mapped to a static address becomes its own logical breakpoint at its dynamic address. The top
table of the provider displays logical breakpoints; the bottom table displays individual
breakpoint locations. <B>NOTE:</B> Only those breakpoints visible at the current snapshot of
each trace are included. For live targets, this is typically the latest snapshot, i.e., the
present.</P>
<P>Depending on what is supported by the connected debugger, breakpoints can trap a target when
an address or range is executed, read, or written; using software or hardware mechanisms. In
the case of "read" or "write" breakpoints, debuggers may differ in terminology. For example,
GDB might call them "watchpoints," but Ghidra still calls these "breakpoints." Some debuggers
allow the user to specify a breakpoint location other than by address, but ultimately each
specification is realized by 0 or more addressable locations. To accommodate this, the <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html">Objects</A> window will
typically display a list of specifications, each listing its locations as children. However,
the grouping of breakpoint locations into logical breakpoints by Ghidra's breakpoint manager is
done <EM>without respect to</EM> the debugger's specifications. A specification may be at a
higher stratum than Ghidra natively understands, e.g., the source filename and line number, and
so such specifications are not relevant. Also note that the debugger might not permit locations
to be manipulated independently of their specifications. This may limit how Ghidra can operate,
since in that case, it must configure the specification, which may affect more locations than
the case of <EM>read</EM> or <EM>write</EM> breakpoints, debuggers may differ in terminology.
For example, GDB might call them <EM>watchpoints</EM>, but Ghidra still calls these
<EM>breakpoints</EM>. Some debuggers allow the user to specify a breakpoint location other than
by address, but ultimately each specification is realized by 0 or more addressable locations.
To accommodate this, the <A href=
"help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window will typically
display a list of specifications, each listing its locations as children. However, the grouping
of breakpoint locations into logical breakpoints by Ghidra's breakpoint manager is done
<EM>without respect to</EM> the debugger's specifications. A specification may be at a higher
stratum than Ghidra natively understands, e.g., the source filename and line number, and so
such specifications are not relevant. Also note that the debugger might not permit locations to
be toggled independently of their specifications. This may limit how Ghidra can operate, since
in that case, it must toggle the specification, which may affect more locations than
intended.</P>
<P>When the <A href="help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">control
mode</A> is set to "trace" or "emulator," it is possible to rewind the trace to past snapshots
and examine old breakpoints. You may also emulate from those snapshots, even if the target is
no longer alive. By default, those historical breakpoints are disabled in the integrated
emulator, but they can be toggled in the usual ways. In addition, the locations can be
manipulated independently, since the emulator has its own breakpoint set. Emulated breakpoints
can be configured with conditions expressed in Sleigh using the <A href="#set_condition">Set
Condition</A> action, or configured to replace the instruction's semantics altogether using the
<A href="#set_injection">Set Injection</A> action.</P>
mode</A> is set to <B>Trace</B> or <B>Emulator</B>, it is possible to rewind the trace to past
snapshots and examine old breakpoints. You may also emulate from those snapshots, even if the
target is no longer alive. By default, those historical breakpoints are disabled in the
integrated emulator, but they can be toggled in the usual ways. In addition, the locations can
be manipulated independently, since the emulator has its own breakpoint set. Emulated
breakpoints can be configured with conditions expressed in Sleigh using the <A href=
"#set_condition">Set Condition</A> action, or configured to replace the instruction's semantics
altogether using the <A href="#set_injection">Set Injection</A> action.</P>
<P>Because of the logical grouping of breakpoints, it is possible for a breakpoint to be in a
mixed or inconsistent state. This happens quite commonly, e.g., when a breakpoint is placed in
a Ghidra program before that program is mapped to any trace. Once mapped, the location of that
breakpoint in the trace is computed and noted as missing. A logical breakpoint without any
location in a trace is called <EM>ineffective</EM> and is drawn in grey, e.g.: <IMG alt="" src=
"images/breakpoint-enable-ineff.png">. An enabled logical breakpoint having a disabled location
is called <EM>inconsistent</EM> and its icon will include an exclamation mark: <IMG alt="" src=
"images/breakpoint-overlay-inconsistent.png">. A disabled logical breakpoint having an enabled
location is similarly inconsistent. Toggling an ineffective or inconsistent logical breakpoint
enables and/or places all its mapped locations, aiming for a consistent enabled state. Toggling
it again disables all locations.</P>
the Static Listing before that program is mapped to any trace. Once mapped, the dynamic
location of that breakpoint is computed and noted as missing. A logical breakpoint without any
location in a target is called <EM>ineffective</EM> and is drawn in grey, e.g.: <IMG alt=""
src="icon.debugger.breakpoint.marker.ineffective.enabled">. An enabled logical breakpoint
having a disabled location is called <EM>inconsistent</EM> and its icon will include an
exclamation mark: <IMG alt="" src="icon.debugger.breakpoint.overlay.inconsistent">. A disabled
logical breakpoint having an enabled location is similarly inconsistent. Toggling an
ineffective or inconsistent logical breakpoint enables and/or places all its mapped locations,
aiming for a consistent enabled state. Toggling it again disables all locations.</P>
<H2>Tables and Columns</H2>
<P>The top table, which lists logical breakpoints, has the following columns:</P>
<UL>
<LI><B>State:</B> displays an icon indicating the state of the breakpoint. If rendered in
grey, the breakpoint has no locations, i.e., it is ineffective. If rendered with an
exclamation mark overlay, the breakpoint is inconsistent. Clicking the icon toggles the
breakpoint.</LI>
<LI>State - displays an icon indicating the state of the breakpoint. If rendered in grey, the
breakpoint has no locations, i.e., it is ineffective. If rendered with an exclamation mark
overlay, the breakpoint is inconsistent. Clicking the icon toggles the breakpoint.</LI>
<UL style="list-style-type: none">
<LI><IMG alt="" src="images/breakpoint-enable.png"> <B>Enabled:</B> The logical
breakpoint, including all its locations, is enabled.</LI>
<LI><IMG alt="" src="icon.debugger.breakpoint.marker.enabled"> <B>Enabled:</B> The
logical breakpoint, including all its locations, is enabled.</LI>
<LI><IMG alt="" src="images/breakpoint-disable.png"> <B>Disabled:</B> The logical
breakpoint, including all its locations, is disabled.</LI>
<LI><IMG alt="" src="icon.debugger.breakpoint.marker.disabled"> <B>Disabled:</B> The
logical breakpoint, including all its locations, is disabled.</LI>
<LI><IMG alt="" src="images/breakpoint-mixed.png"> <B>Mixed:</B> (Listing only) Two
logical breakpoints at the same address have different states.</LI>
<LI><IMG alt="" src="icon.debugger.breakpoint.marker.mixed"> <B>Mixed:</B> (<A href=
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Listing</A>
only) Two logical breakpoints at the same address have different states.</LI>
</UL>
<LI><B>Name:</B> gives the user-defined name of the breakpoint. This cell is only populated
and modifiable when the breakpoint is bookmarked in a program, since the name is associated
with the static location.</LI>
<LI>Name - gives the user-defined name of the breakpoint. This cell is only populated and
modifiable when the breakpoint is bookmarked in a program, since the name is associated with
the static location.</LI>
<LI><B>Address:</B> gives the address of the breakpoint. This is typically the static
address. If the breakpoint cannot be mapped to a static address, this is its dynamic
address.</LI>
<LI>Address - gives the address of the breakpoint. This is typically the static address. If
the breakpoint cannot be mapped to a static address, this is its dynamic address.</LI>
<LI><B>Image:</B> gives the name of the static image, i.e., Ghidra program. If the breakpoint
<LI>Image - gives the name of the static image, i.e., Ghidra program. If the breakpoint
cannot be mapped to a static location, this is blank.</LI>
<LI><B>Length:</B> usually 1. For access breakpoints, this is the length in bytes of the
address range.</LI>
<LI>Length - usually 1. For access breakpoints, this is the length in bytes of the address
range.</LI>
<LI><B>Kinds:</B> indicates the kind(s) of breakpoint: SW_EXECUTE, HW_EXECUTE, READ, and/or
<LI>Kinds - indicates the kind(s) of breakpoint: SW_EXECUTE, HW_EXECUTE, READ, and/or
WRITE.</LI>
<LI><B>Locations:</B> counts the number of locations included in this logical breakpoint,
applying the trace filter if active. Note that a logical breakpoint with 0 locations is
<LI>Locations - counts the number of locations included in this logical breakpoint, applying
the trace filter if active. Note that a logical breakpoint with 0 locations is
ineffective.</LI>
<LI><B>Sleigh:</B> indicates whether or not the breakpoint has a customized Sleigh
configuration. This is only relevant for emulation.</LI>
<LI>Sleigh - indicates whether or not the breakpoint has a customized Sleigh configuration.
This is only relevant for emulation.</LI>
</UL>
<P>The bottom table, which lists breakpoint locations, has the following columns:</P>
<UL>
<LI><B>State:</B> displays an icon indicating the state of the location. If rendered with an
<LI>State - displays an icon indicating the state of the location. If rendered with an
exclamation mark overlay, the location does not agree with its logical breakpoint, or it
cannot be bookmarked. Clicking the icon toggles the location.</LI>
<UL style="list-style-type: none">
<LI><IMG alt="" src="images/breakpoint-enable.png"> <B>Enabled:</B> The location is
enabled.</LI>
<LI><IMG alt="" src="icon.debugger.breakpoint.marker.enabled"> <B>Enabled:</B> The
location is enabled.</LI>
<LI><IMG alt="" src="images/breakpoint-disable.png"> <B>Disabled:</B> The location is
disabled.</LI>
<LI><IMG alt="" src="icon.debugger.breakpoint.marker.disabled"> <B>Disabled:</B> The
location is disabled.</LI>
<LI><IMG alt="" src="images/breakpoint-mixed.png"> <B>Mixed:</B> (Listing only) Two
locations at the same address have different states.</LI>
<LI><IMG alt="" src="icon.debugger.breakpoint.marker.mixed"> <B>Mixed:</B> (<A href=
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Listing</A>
only) Two locations at the same address have different states.</LI>
</UL>
<LI><B>Name:</B> displays the name given to the location by the connected debugger. This
<LI>Name - displays the name given to the location by the connected debugger. This field is
user modifiable.</LI>
<LI>Address - gives the dynamic address of this location.</LI>
<LI>Trace - gives the name of the location's trace.</LI>
<LI>Threads - (hidden by default) if the breakpoint applies to a limited set of threads,
gives the list of threads.</LI>
<LI>Comment - gives a user comment &mdash; the specification's expression by default. This
field is user modifiable.</LI>
<LI><B>Address:</B> gives the dynamic address of this location.</LI>
<LI><B>Trace:</B> gives the name of the location's trace.</LI>
<LI><B>Threads:</B> (hidden by default) if the breakpoint applies to a limited set of
threads, gives the list of threads.</LI>
<LI><B>Comment:</B> gives a user comment &mdash; the specification's expression by default.
This field is user modifiable.</LI>
<LI><B>Sleigh:</B> (hidden by default) indicates whether or not the location has a customized
Sleigh configuration. This is only relevant for emulation.</LI>
<LI>Sleigh - indicates whether or not the location has a customized Sleigh configuration.
This is only relevant for emulation.</LI>
</UL>
<H2>Breakpoint Actions</H2>
@ -170,44 +163,45 @@
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Breakpoint
Marker Actions</A> in the listings.</P>
<H3><A name="enable_breakpoints"></A><IMG alt="" src="images/breakpoint-enable.png">
<H3><A name="enable_breakpoints"></A><IMG alt="" src="icon.debugger.breakpoint.enable">
Enable</H3>
<P>This action is available when one or more breakpoints or locations are selected. It enables
each selected breakpoint. For any breakpoint that is already enabled, no action is taken.</P>
<H3><A name="enable_all_breakpoints"></A><IMG alt="" src="images/breakpoints-enable-all.png">
<H3><A name="enable_all_breakpoints"></A><IMG alt="" src="icon.debugger.breakpoint.enable.all">
Enable All Breakpoints</H3>
<P>This action is always available. It enables every breakpoint. For any breakpoint that is
already enabled, no action is taken.</P>
<H3><A name="disable_breakpoints"></A><IMG alt="" src="images/breakpoint-disable.png">
<H3><A name="disable_breakpoints"></A><IMG alt="" src="icon.debugger.breakpoint.disable">
Disable</H3>
<P>This action is available when one or more breakpoints or locations are selected. It disables
each selected breakpoint. For any breakpoint that is already disabled, no action is taken.</P>
<H3><A name="disable_all_breakpoints"></A><IMG alt="" src="images/breakpoints-disable-all.png">
Disable All Breakpoints</H3>
<H3><A name="disable_all_breakpoints"></A><IMG alt="" src=
"icon.debugger.breakpoint.disable.all"> Disable All Breakpoints</H3>
<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="make_breakpoints_effective"></A><IMG alt="" src=
"images/breakpoints-make-effective.png"> Make Breakpoints Effective</H3>
"icon.debugger.breakpoint.make.effective"> 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</H3>
<H3><A name="clear_breakpoints"></A><IMG alt="" src="icon.debugger.breakpoint.clear">
Clear</H3>
<P>This action is available when one or more breakpoints or locations are selected. It clears
(deletes) each selected breakpoint.</P>
<H3><A name="clear_all_breakpoints"></A><IMG alt="" src="images/breakpoints-clear-all.png">
<H3><A name="clear_all_breakpoints"></A><IMG alt="" src="icon.debugger.breakpoint.clear.all">
Clear All Breakpoints</H3>
<P>This action is always available. <FONT color="red">Use with caution!</FONT> It deletes every
@ -335,14 +329,14 @@ emu_skip_decoded();
<P>For organizing breakpoints the manager provides the following actions:</P>
<H3><A name="filter_by_trace"></A><IMG alt="" src="images/video-x-generic16.png"> Filter to
<H3><A name="filter_by_trace"></A><IMG alt="" src="icon.content.handler.trace"> Filter to
Current Trace</H3>
<P>This toggle is always available. It filters the bottom table to those locations in the
current trace only. Additionally, the "Locations" column of the top table will only count those
in the current trace.</P>
<H3><A name="filter_by_logical"></A><IMG alt="" src="images/filter_off.png"> Filter to
<H3><A name="filter_by_logical"></A><IMG alt="" src="icon.debugger.filter"> Filter to
Breakpoint Selection</H3>
<P>This action is always available. It filters the bottom table to those locations belonging to

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerBreakpointsPlugin/images/DebuggerBreakpointsPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 28 KiB

42
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerConsolePlugin/DebuggerConsolePlugin.html
View file

@ -13,31 +13,26 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Console</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerConsolePlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerConsolePlugin.png">
</DIV>
<P>The console logs messages from Ghidra related to the debugger. Depending on the exact
configuration, this can comprise a wide range of components, including all GUI views, active
connectors, and running agents. Soon, it may also provide a command-line interface to control
Ghidra's debugging sessions and interact with traces.</P>
<P>Some log messages include an action context, allowing plug-ins to offer actions on that
message. These are said to be "actionable" messages. A noteworthy example is when navigating to
a module that could not be automatically mapped from the current project. Instead of displaying
a prompt, it will log a message and suggest actions to resolve the issue. A successful
resolution typically removes the message from the log. Note that additional actions may be
available from the context menu.</P>
<P>The console logs messages from Ghidra related to the debugger. This no longer includes
messages sent to the application log, but only messages that plug-ins deliberately deliver to
this console. Some log messages include an action context, allowing plug-ins to offer actions
on that message. These are said to be "actionable" messages. A noteworthy example is when
navigating to a module that could not be automatically mapped from the current project. Instead
of displaying a prompt, it will log a message and suggest actions to resolve the issue. A
successful resolution typically removes the message from the log. Note that additional actions
may be available from the context menu. Some messages communicate progress of a background
task. These may have a progress bar, and the associated message may change over time. These
entries may offer a cancel action.</P>
<P>By default, the log is sorted so that actionable messages appear at the top. Then, it is
sorted by descending date, so that the most recent messages appear at the top. Like any other
Ghidra table, it can customized and filtered. Note that the filter box is at the top, because
we anticipate a command-line input in the future, which we'd like to place at the bottom.</P>
we anticipate a command-line input in the future, which we would like to place at the
bottom.</P>
<H2>Table Columns</H2>
@ -55,8 +50,7 @@
<H2>Actions</H2>
<P>Not considering extension actions from other plugins, the console provides the
following:</P>
<P>Not considering actions for "actionable" messages, the console provides the following:</P>
<H3><A name="clear"></A>Clear</H3>
@ -68,7 +62,7 @@
<H3><A name="cancel"></A>Cancel</H3>
<P>Some experimental features may display progress entries in the log for background tasks they
run. This action is displayed in the Actions column and will cancel the task.</P>
<P>For a tasks displaying a progress message in the console, this action will cancel the
task.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerConsolePlugin/images/DebuggerConsolePlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 18 KiB

92
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html
View file

@ -31,32 +31,32 @@
are:</P>
<UL>
<LI><IMG alt="" src="images/record.png"> <B>Control Target w/Edits Disabled:</B> The default,
this presents actions for controlling the live target but rejects all machine-state edits.
Breakpoint commands are directed to the live target. When active, the UI automatically
follows the latest snapshot recorded. If the target is terminated, the mode is automatically
<LI><IMG alt="" src="icon.debugger.control.mode.ro.target"> <B>Control Target w/Edits
Disabled:</B> The default, this presents actions for controlling the live target but rejects
all machine-state edits. Breakpoint commands are directed to the live target. When active,
the UI automatically follows the latest snapshot recorded, and navigating back in time is not
permitted. If the target is terminated and the trace remains open, the mode is automatically
switched to <B>Control Trace</B>.</LI>
<LI><IMG alt="" src="images/write-target.png"> <B>Control Target:</B> This presents actions
for controlling the live target and directs edits to the live target. Breakpoint commands are
directed to the live target. To accept edits, the UI must be "live and at the present." If
the trace has no associated target, i.e., it is dead; or if the current view is in the past
or includes any steps of emulation, i.e., it is not at the present; then edits are rejected.
When active, the UI automatically follows the latest snapshot recorded. If the target is
terminated, the mode is automatically switched to <B>Control Emulator</B>.</LI>
<LI><IMG alt="" src="icon.debugger.control.mode.rw.target"> <B>Control Target:</B> This
presents actions for controlling the live target and directs edits to the live target.
Breakpoint commands are directed to the live target. When active, the UI automatically
follows the latest snapshot recorded, an navigating back in time is not permitted. If the
target is terminated and the trace remains open, the mode is automatically switched to
<B>Control Emulator</B>.</LI>
<LI><IMG alt="" src="images/video-x-generic16.png"> <B>Control Trace w/Edits Disabled:</B>
This presents actions for navigating trace snapshots but rejects all machine-state edits.
Breakpoint commands are directed to the emulator.</LI>
<LI><IMG alt="" src="icon.debugger.control.mode.ro.trace"> <B>Control Trace w/Edits
Disabled:</B> This presents actions for navigating trace snapshots but rejects all
machine-state edits. Breakpoint commands are directed to the emulator.</LI>
<LI><IMG alt="" src="images/write-trace.png"> <B>Control Trace:</B> This presents actions for
navigating trace snapshots. It directs all edits to the trace database. Edits are generally
always accepted, and they are applied directly to the trace. Breakpoint commands are directed
to the emulator.</LI>
<LI><IMG alt="" src="icon.debugger.control.mode.rw.trace"> <B>Control Trace:</B> This
presents actions for navigating trace snapshots. It directs all edits to the trace database.
Edits are generally always accepted, and they are applied directly to the trace. Breakpoint
commands are directed to the emulator.</LI>
<LI><IMG alt="" src="images/write-emulator.png"> <B>Control Emulator:</B> This presents
actions for controlling the integrated emulator. Breakpoint commands are directed to the
emulator. This can be used for interpolating and extrapolating execution from the current
<LI><IMG alt="" src="icon.debugger.control.mode.rw.emulator"> <B>Control Emulator:</B> This
presents actions for controlling the integrated emulator. Breakpoint commands are directed to
the emulator. This can be used for interpolating and extrapolating execution from the current
snapshot, without affecting the live target. It directs edits to the integrated emulator by
generating patch steps and appending them to the emulation schedule. See the <A href=
"help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html#goto_time">Go To Time</A> action.
@ -71,67 +71,67 @@
only when the current trace has an associated live target. Commands are directed to the focused
object or a suitable substitute.</P>
<H3><A name="target_resume"></A><IMG alt="" src="images/resume.png"> Resume</H3>
<H3><A name="target_resume"></A><IMG alt="" src="icon.debugger.resume"> Resume</H3>
<P>Allow the current target to resume execution. Other debuggers may call this "continue" or
"go." If successful, the target enters the "running" state until/if it is interrupted or
"go." If successful, the target enters the "running" state until it is interrupted or
terminated. This is available when the target is currently stopped.</P>
<H3><A name="target_interrupt"></A><IMG alt="" src="images/interrupt.png"> Interrupt</H3>
<H3><A name="target_interrupt"></A><IMG alt="" src="icon.debugger.interrupt"> Interrupt</H3>
<P>Interrupt the current target's execution. Other debuggers may call this "break," "suspend,"
or "stop." If successful, the target enters the "stopped" state. This is available when the
target is currently running.</P>
<H3><A name="target_kill"></A><IMG alt="" src="images/kill.png"> Kill</H3>
<H3><A name="target_kill"></A><IMG alt="" src="icon.debugger.kill"> Kill</H3>
<P>Kill the current target. Other debuggers may call this "terminate" or "stop." By default,
this will consequently close the current trace. If successful, the target enters the
"terminated" state. This is always available for a live target.</P>
<P>Kill the current target. Other debuggers may call this "terminate" or "stop." This may
consequently close the current trace. If successful, the target enters the "terminated" state.
This is always available for a live target.</P>
<H3><A name="target_disconnect"></A><IMG alt="" src="images/disconnect.png"> Disconnect</H3>
<H3><A name="target_disconnect"></A><IMG alt="" src="icon.debugger.disconnect"> Disconnect</H3>
<P>Disconnect from the current target's debugger. This usually causes the connected debugger to
terminate and likely kill its targets. By default, this will consequently close the trace for
all affected targets. This is always available for a live target.</P>
terminate and likely kill its targets. This may consequently close the current trace (and
perhaps others). This is always available for a live target.</P>
<H3><A name="target_step_into"></A><IMG alt="" src="images/stepinto.png"> Step Into</H3>
<H3><A name="target_step_into"></A><IMG alt="" src="icon.debugger.step.into"> Step Into</H3>
<P>Step the current target to the next instruction. This is available when the target is
currently stopped. If successful the target may briefly enter the "running" state.</P>
<H3><A name="target_step_over"></A><IMG alt="" src="images/stepover.png"> Step Over</H3>
<H3><A name="target_step_over"></A><IMG alt="" src="icon.debugger.step.over"> Step Over</H3>
<P>Step the current target to the next instruction in the current subroutine. This is available
when the target is currently stopped. If successful the target may briefly enter the "running"
state.</P>
<H3><A name="target_step_out"></A><IMG alt="" src="images/stepout.png"> Step Out</H3>
<H3><A name="target_step_out"></A><IMG alt="" src="icon.debugger.step.finish"> Step Out</H3>
<P>Allow the current target to finish the current subroutine, pausing after. This is available
when the target is currently stopped. If successful the target may briefly enter the "running"
state.</P>
<H3><A name="target_step_last"></A><IMG alt="" src="images/steplast.png"> Step Repeat Last /
Extended</H3>
<H3><A name="target_step_last"></A><A name="target_step_ext"></A><IMG alt="" src=
"icon.debugger.step.last"> Step Extended (Repeat Last)</H3>
<P>Perform a target-defined step, often the last (possibly custom or extended) step. This is
available when the target is currently stopped. If successful the target may briefly enter the
"running" state.</P>
<P>Perform a target-defined step, perhaps the last (possibly custom) step. This is available
when the target is currently stopped. If successful the target may briefly enter the "running"
state.</P>
<H2>Trace Navigation Actions</H2>
<P>These actions are visible when a <B>Control Trace</B> mode is selected. They are available
when there is an active trace.</P>
<H3><A name="trace_snap_backward"></A><IMG alt="" src="images/2leftarrow.png" width="16">
<H3><A name="trace_snap_backward"></A><IMG alt="" src="icon.debugger.snap.backward" width="16">
Snapshot Backward</H3>
<P>This activates the previous snapshot. All windows displaying machine state will show that
recorded in the activated snapshot. This is available only when there exists a snapshot
previous to the current.</P>
<H3><A name="trace_snap_forward"></A><IMG alt="" src="images/2rightarrow.png" width="16">
<H3><A name="trace_snap_forward"></A><IMG alt="" src="icon.debugger.snap.forward" width="16">
Snapshot Forward</H3>
<P>This activates the next snapshot. All windows displaying machine state will show that
@ -144,7 +144,7 @@
available when there is an active trace. Commands are directed to the integrated emulator for
the current trace.</P>
<H3><A name="emu_resume"></A><IMG alt="" src="images/resume.png"> Resume</H3>
<H3><A name="emu_resume"></A><IMG alt="" src="icon.debugger.resume"> Resume</H3>
<P>Allow the emulator to resume execution. This is available when no other integrated emulator
is running. A monitor dialog is presented during execution, but the GUI remains responsive.
@ -154,14 +154,14 @@
system calls are not yet supported. It could also start executing from unmapped memory or enter
an infinite loop. If it seems to carry on too long, interrupt it and examine.</P>
<H3><A name="emu_interrupt"></A><IMG alt="" src="images/interrupt.png"> Interrupt</H3>
<H3><A name="emu_interrupt"></A><IMG alt="" src="icon.debugger.interrupt"> Interrupt</H3>
<P>Interrupt the currently-running emulator. This is available when any integrated emulator is
running. In most cases, this is the emulator for the current trace, but it may not be.
Canceling the dialog for an emulation task will also interrupt the emulator. Upon interruption,
the emulation schedule is noted and the snapshot displayed in the GUI.</P>
<H3><A name="emu_step_back"></A><IMG alt="" src="images/stepback.png"> Step Back</H3>
<H3><A name="emu_step_back"></A><IMG alt="" src="icon.debugger.step.back"> Step Back</H3>
<P>Steps the emulator to the previous instruction, by flow. This is available when the current
snapshot includes emulated steps. This operates by repeating the current emulation schedule
@ -169,7 +169,7 @@
not common, if emulation to the current snapshot took a good bit of time, then stepping
backward will likely take about the same amount of time.</P>
<H3><A name="emu_step_into"></A><IMG alt="" src="images/stepinto.png"> Step Into</H3>
<H3><A name="emu_step_into"></A><IMG alt="" src="icon.debugger.step.into"> Step Into</H3>
<P>Steps the emulator to the next instruction, by flow. This is available when there is an
active thread. At worst, this operates by repeating the current emulation schedule with one
@ -177,7 +177,7 @@
current snapshot and advance it a single step. Note that "Step Over" is not currently supported
by the emulator.</P>
<H3><A name="emu_skip_over"></A><IMG alt="" src="images/skipover.png"> Skip Over</H3>
<H3><A name="emu_skip_over"></A><IMG alt="" src="icon.debugger.skip.over"> Skip Over</H3>
<P>Skips the emulator over the current instruction, ignoring flow. This is available when there
is an active thread. At worst, this operates by repeating the current emulation schedule with

15
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerCopyActionsPlugin/DebuggerCopyActionsPlugin.html
View file

@ -16,8 +16,8 @@
<P>In the course of debugging, the user may want to capture certain state and annotations from
the dynamic context into the static. This might include the contents of the stack, the heap, or
example data stored in uninitialized memory. The copy actions allow for the easy movement of
data and annotations from traces into programs. The actions are all accessed via the <SPAN
class="menu">Debugger</SPAN> menu.</P>
data and annotations from traces into programs. The actions are all accessed via the
<B>Debugger</B> menu.</P>
<H2>Actions</H2>
@ -46,14 +46,9 @@
<P>The <B>Copy Into...</B> actions both present the same dialog: (The <B>Export Trace View</B>
action uses a different dialog.)</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerCopyIntoProgramDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerCopyIntoProgramDialog.png">
</DIV>
<P>The dialog consists of several options, followed by a table that displays the proposed
ranges to copy. For selected ranges not contained in the destination program's memory, new

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerCopyActionsPlugin/images/DebuggerCopyIntoProgramDialog.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 33 KiB

8
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerInterpreterPlugin/DebuggerInterpreterPlugin.html
View file

@ -13,10 +13,14 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A><A name="interpreter"></A>Debugger: Interpreters</H1>
<P><IMG alt="" src="help/shared/note.png">This window only supports the older "Recorder-based"
targets. For newer "TraceRmi-based" targets, the actual debugger runs in an integrated VT-100
terminal emulator.</P>
<P>For debuggers which have built-in interpreters (many do), and whose connectors expose that
interpreter in the model, the interpreters plugin can provide user access to it via a graphical
console emulator. The plugin leverages the existing interpreter console framework in Ghidra, so
the interface should be relatively familiar. Typically, the console is accessed via the Objects
console. The plugin leverages the existing interpreter console framework in Ghidra, so the
interface should be relatively familiar. Typically, the console is accessed via the Objects
window's <A href=
"help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html#console">Console</A> action.
Output is displayed in a large text field, and user input is taken via a small text field at

93
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html
View file

@ -13,14 +13,9 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Dynamic Listing</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerListingPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerListingPlugin.png">
</DIV>
<P><A name="Toggle_Header"></A>The dynamic listing is analogous to Ghidra's listing for static
analysis, but in the dynamic context. It displays annotated memory contents from a target. More
@ -55,8 +50,8 @@
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>
failed, the entire failed range is displayed with a pink background. Otherwise, up-to-date
contents are displayed with the default background color.</P>
<P>The dynamic listing supports editing memory. See <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control and Machine State</A>.
@ -64,6 +59,26 @@
"help/topics/AssemblerPlugin/Assembler.htm">Patch</A> actions, or by pasting byte strings.
These edits may be directed toward a live target, the trace, or the emulator.</P>
<H2>Trace Tabs</H2>
<P>The trace tab bar is displayed when at least one trace is open. It displays the name of each
open trace in a tab, 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 <IMG alt="" src="icon.debugger.record"> 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 not record any new target information.</P>
<H3><A name="close_trace"></A><A name="close_all_traces"></A><A name=
"close_other_traces"></A><A name="close_dead_traces"></A>Close Trace / All / Other / Dead
Traces</H3>
<P>In most cases, a trace is ephemeral, but occasionally, interesting behavior is observed that
is difficult to store as static mark-up. When traces are no longer needed, they can be closed.
Several can be closed at once by right-clicking a tab and selecting one of the actions. See <A
href=
"help/topics/DebuggerTraceManagerServicePlugin/DebuggerTraceManagerServicePlugin.html#close_trace">Trace
Management</A> for details of each action.</P>
<H2>Actions</H2>
<P>The listing provides a variety of actions, some for managing and configuring listings, and
@ -71,16 +86,16 @@
<H3><A name="new_listing"></A>New Dynamic Listing</H3>
<P>This action is always available in the <SPAN class="menu">Window &rarr; Debugger</SPAN>
menu. It creates a new listing window with the same configuration as the primary dynamic
listing. It is equivalent to cloning the primary dynamic listing.</P>
<P>This action is always available in the <B>Window &rarr; Debugger</B> menu. It creates a new
listing window with the same configuration as the primary dynamic listing. It is equivalent to
cloning the primary dynamic listing.</P>
<H3><A name="export_view"></A>Export Trace View</H3>
<P>This action is available whenever there is a trace open in the listing. It is analogous to
"Export Program," but for the current trace at the current time. This provides a mechanism for
capturing a particular point in time from a trace as a static image. The exported image can be
analyzed in Ghidra or another tool.</P>
<P>This action is available in the <B>Debugger</B> menu whenever there is a trace open in the
listing. It is analogous to "Export Program," but for the current trace at the current time.
This provides a mechanism for capturing a particular point in time from a trace as a static
image. The exported image can be analyzed in Ghidra or another tool.</P>
<H3><A name="follows_thread"></A>Follows Selected Thread</H3>
@ -141,13 +156,9 @@
of labels, registers, and constants. Labels may come from the current trace or a program mapped
into the trace. Ambiguities are resolved arbitrarily.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src="images/DebuggerGoToDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerGoToDialog.png">
</DIV>
<P>Some examples:</P>
@ -231,30 +242,36 @@
<H3><A name="read_memory"></A>Read Memory</H3>
<P>This action is available when the current trace is "at the present" with a live target, and
there is a selection of addresses in the dynamic listing. It will instruct the recorder to read
and record the contents of memory for the selected range(s). Typically, the viewable addresses
are automatically read, anyway &mdash; see the Auto-Read action.</P>
<P>This action is available when the current trace is "at the present" with a live target. It
will instruct the target to read the contents of memory for the selected or visible addresses.
Typically, the visible addresses are automatically read &mdash; see the Auto-Read action
&mdash; so this action is for refreshing or for reading large selections.</P>
<H3><A name="auto_memory"></A>Auto-Read Memory</H3>
<P>This action is always available on all dynamic listings. It configures whether or not the
memory range(s) displayed in the listing are automatically read and recorded. Like the Read
Memory action, it is only permitted when the current trace is "at the present" with a live
target. It occurs when the user scrolls the listing, or when the listing is otherwise navigated
to a new location. Note that other components may read memory, regardless of this listing's
configuration. For example, the recorder typically reads the page of memory pointed to by the
memory range(s) displayed in the listing are automatically read. Like the Read Memory action,
it is only permitted when the current trace is "at the present" with a live target. It occurs
when the user scrolls the listing, or when the listing is otherwise navigated to a new
location. Note that other components may read memory, regardless of this listing's
configuration. For example, the target typically reads the page of memory pointed to by the
program counter. In other words, this action <EM>cannot</EM> "disable all memory reads." The
options are pluggable, but currently consist of:</P>
<UL>
<LI>Do Not Read Memory - disables automatic memory reads <EM>for this listing only</EM>.</LI>
<LI><IMG alt="" src="icon.debugger.delete"> Do Not Read Memory - disables automatic memory
reads <EM>for this listing only</EM>.</LI>
<LI>Read Visible Memory - automatically reads stale ranges that enter this listing's
view.</LI>
<LI><IMG alt="" src="icon.debugger.autoread" width="16"> Read Visible Memory - automatically
reads stale ranges that enter this listing's view.</LI>
<LI>Read Visible Memory, RO Once - (default) behaves like Read Visible Memory, except it will
neglect read-only ranges that have been read previously.</LI>
<LI><IMG alt="" src="icon.debugger.autoread" width="16"> Read Visible Memory, RO Once -
(default) behaves like Read Visible Memory, except it will neglect read-only ranges that have
been read previously.</LI>
<LI><IMG alt="" src="icon.debugger.emulate"> Load Emulator from Programs - populates the
trace database using mapped program databases. This is often preferred during "pure
emulation," so that the dynamic listing's contents match those of the static listing.</LI>
</UL>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerListingPlugin/images/DebuggerGoToDialog.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7 KiB

After

Width:  |  Height:  |  Size: 5.8 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerListingPlugin/images/DebuggerListingPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 47 KiB

82
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerMemoryBytesPlugin/DebuggerMemoryBytesPlugin.html
View file

@ -13,14 +13,9 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Memory (Dynamic Bytes)</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerMemoryBytesPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerMemoryBytesPlugin.png">
</DIV>
<P><A name="Toggle_Header"></A>The memory, or dynamic bytes, window is analogous to Ghidra's
bytes window for static analysis, but in the dynamic context. It displays memory contents from
@ -36,13 +31,13 @@
use clones to display different points in time for the same trace.</P>
<P>Because not all memory is recorded, 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, are displayed in the window, 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
of attempted memory reads. Regardless of state, the most-recent contents recorded in the trace
are displayed in the window, 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>
failed, the entire range is displayed with a pink background. Otherwise, up-to-date contents
are displayed with the default background color.</P>
<P>The dynamic bytes viewer supports editing memory. See <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control and Machine State</A>.
@ -72,52 +67,32 @@
<H3><A name="track_location"></A>Track Location</H3>
<P>This action is equivalent to the same action in the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#track_location">Dynamic
Listing</A> window. <B>NOTE:</B> This feature is disabled when the edit toggle is on.</P>
<P>This action is equivalent to the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#track_location">same action</A>
in the Dynamic Listing window. <B>NOTE:</B> This feature is disabled when the edit toggle is
on.</P>
<H3><A name="go_to"></A>Go To (G)</H3>
<P>This action is equivalent to the same action in the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#go_to">Dynamic Listing</A>
window.</P>
<P>This action is equivalent to the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#go_to">same action</A> in the
Dynamic Listing window.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"help/topics/DebuggerListingPlugin/images/DebuggerGoToDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="help/topics/DebuggerListingPlugin/images/DebuggerGoToDialog.png">
</DIV>
<H3><A name="read_memory"></A>Read Memory</H3>
<P>This action is available when the current trace is "at the present" with a live target, and
there is a selection of addresses in the memory window. It will instruct the recorder to read
and record the contents of memory for the selected range(s). Typically, the viewable addresses
are automatically read &mdash; see the Auto-Read action.</P>
<P>This action is equivalent to the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#read_memory">same action</A> in
the Dynamic Listing window.</P>
<H3><A name="auto_memory"></A>Auto-Read Memory</H3>
<P>This action is always available on all memory windows. It configures whether or not the
memory range(s) displayed in the window are automatically read and recorded. Like the Read
Memory action, it is only permitted when the current trace is "at the present" with a live
target. It occurs when the user scrolls the window, or when the window is otherwise navigated
to a new location. Note that other components may read memory, regardless of this windows's
configuration. For example, the recorder typically reads the page of memory pointed to by the
program counter. In other words, this action <EM>cannot</EM> "disable all memory reads." The
options are pluggable, but currently consist of:</P>
<UL>
<LI>Do Not Read Memory - disables automatic memory reads <EM>for this window only</EM>.</LI>
<LI>Read Visible Memory - automatically reads stale ranges that enter this window's
view.</LI>
<LI>Read Visible Memory, RO Once - (default) behaves like Read Visible Memory, except it will
neglect read-only ranges that have been read previously.</LI>
</UL>
<P>This action is equivalent to the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#auto_memory">same action</A> in
the Dynamic Listing window.</P>
<H3><A name="Byte_Viewer_Options"></A>Byte Viewer Options</H3>
@ -126,8 +101,9 @@
<H3><A name="Enable_Disable_Byteviewer_Editing"></A>Toggle Editing</H3>
<P>This action does the same as it does for the static context. Edits may be rejected if the
trace's editing mode is set to Read-Only in the tool. <B>NOTE:</B> This toggle also disables
automatic navigation in order to prevent the cursor from being moved unexpectedly while typing
edits.</P>
trace <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html#control_mode">control mode</A> is
set to Read-Only in the tool. <B>NOTE:</B> This toggle also disables automatic navigation in
order to prevent the cursor from being moved unexpectedly while typing edits.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerMemoryBytesPlugin/images/DebuggerMemoryBytesPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

19
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerMemviewPlugin/DebuggerMemviewPlugin.html
View file

@ -13,14 +13,9 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Memory View</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerMemviewPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerMemviewPlugin.png">
</DIV>
<P>As in the Threads view, you may wish to follow the evolution of various objects over time.
The memory viewer window provides a generic time vs. address (or address vs. time) plot of
@ -60,22 +55,22 @@
<H2>Navigation</H2>
<H3><A name="zoom"></A><IMG alt="" src="images/zoom_in.png">Zoom</H3>
<H3><A name="zoom"></A><IMG alt="" src="icon.widget.imagepanel.zoom.in">Zoom</H3>
<P>The four zoom buttons either contract or expand the view along the time or address axes.</P>
<H3><A name="toggle_layout"></A><IMG alt="" src="images/view-refresh.png">Toggle Layout</H3>
<H3><A name="toggle_layout"></A><IMG alt="" src="icon.debugger.refresh">Toggle Layout</H3>
<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
<H3><A name="toggle_process_trace"></A><IMG alt="" src="icon.debugger.sync">Toggle Process
Trace</H3>
<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
<H3><A name="apply_to_panel"></A><IMG alt="" src="icon.debugger.filter">Toggle Apply
Filter</H3>
<P>This button determines whether the table filter affects the plot panel. When toggled on,

308
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html Normal file
View file

@ -0,0 +1,308 @@
<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">
<HTML>
<HEAD>
<META name="generator" content=
"HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">
<TITLE>Debugger: Model Objects</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
</HEAD>
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Model Objects</H1>
<DIV class="image">
<IMG alt="" src="images/DebuggerModelPlugin.png">
</DIV>
<P>The Model window permits the user to inspect the trace's object database. It also provides
access to some target-defined actions that might not otherwise be accessible from the rest of
the Debugger UI. The object database is a generic description of everything present on the
target and their states. Many of the other windows, e.g., Modules, Regions, Threads, are just
specialized versions of this window.</P>
<P>The target describes the structure of its object directory using a model <EM>schema</EM>.
The Debugger UI uses the schema to navigate this directory and find relevant objects. For most
mundane targets, the Model window is not necessary, but may still be preferred by some users.
For targets implementing features not natively built into the Debugger, the Model and/or
Terminal windows are essential.</P>
<P>The model window consists of three <A href="#pane_toggles">togglable</A> panes: Objects
Tree, Elements Table, and Attributes Table. At the top is a path entry field, which identifies
the current object. Each pane can be hidden, and the whole window can be cloned, allowing users
to customize multiple views. When docked to the side of the Debugger UI, it is common to hide
both tables, so that the Object tree is not obscured. Users who like to see register values in
the tree should enable <A href="#show_primitives">Show Primitives in Tree</A>.</P>
<H2>Objects Tree Pane</H2>
<P>The Tree pane on the left displays the complete object directory. The back-end debugger may
name its Root node to better describe itself. All nodes below that are defined by the target,
but some common nodes are: Available, Processes, Breakpoints, Memory, Modules, Threads, Stack,
and Registers.</P>
<UL>
<LI><B>Available:</B> This node typically lists running processes on the debugger's host to
which it may attach.</LI>
<LI><B>Processes:</B> This node lists all current target processes to which the debugger is
currently attached. Most often, there is only one.</LI>
<LI><B>Breakpoints:</B> This node may appear as a child of the root or of each target
process. It lists the breakpoints for the entire session (in the former case) or for the
target process (in the latter case) or some combination of both. Some targets distinguish
between a breakpoint specification and its locations. If that is the case, the locations
should be children of their specification. If breakpoints are specified for the entire
session, then each target process should also have a Breakpoints node whose children are
links to the locations within that target.</LI>
<LI><B>Memory:</B> This should always appear as a child of a target. It lists the memory
regions, if known, in that target. For processes, this is the memory map. Only those
addresses in a listed region are valid. For targets where the memory map is not known or
cannot be retrieved, there may be a single region covering the entire address space, simply
to ensure the Dynamic Listing and Byte viewers are populated.</LI>
<LI><B>Modules:</B> This should always appear as a child of a target process. It lists
modules known to be loaded into its memory. Some back ends may also present a <B>Sections</B>
node for each module, which lists the sections of that module. Reporting sections for all
modules is often expensive, so each Sections node may be empty until explicitly loaded or
refreshed.</LI>
<LI><B>Threads:</B> This should always appear as a child of the target. It lists all the
threads executing in the target. Even if the target's platform does not support
multi-threading, this node is typically still present, but will list only the one
thread.</LI>
<LI><B>Stack:</B> This node is not always present, depending on whether the back-end debugger
supports unwinding the stack. Most do. It should always appear as a child of a thread. It
lists the stack frames for that thread, where the topmost, i.e., current or innermost, frame
is numbered 0. Each successive unwound frame is numbered 1 and counting up.</LI>
<LI><B>Registers:</B> This node may appear as a child of a thread or frame. It lists the
registers and their values. In contrast to the Registers window, the values displayed here
have <EM>not</EM> been mapped into the trace's Sleigh language. The names and values are
determined entirely by the back end. As the child of a thread, the values are the current
register values for that thread. The PC value may be adjusted by the debugger to reflect its
logical value instead of its actual value. As the child of a frame, then frame 0's values are
the current register values for the containing thread. The values for each successive frame
are those recovered by the debugger unwinding the stack. Please see the back-end debugger's
documentation for any caveats that may apply. Unwinding is often an imperfect science.
<B>NOTE:</B> Because targets often record register values as primitive attributes, they may
not appear in the tree pane by default. Use the Attributes pane, or toggle <A href=
"#show_primitives">Show Primitives in Tree</A> in the local drop-down menu.</LI>
</UL>
<H3>Node Display and Selection</H3>
<P>Most often, each node is displayed by its name. A target may specify the display text,
usually to make it match what appears in its terminal or to present a useful summary of that
object. When a child is a link, the tree displays its key followed by its value in italics.
When a child is a primitive, it is not displayed in the tree by default. This can be toggled
using <A href="#show_primitives">Show Primitives in Tree</A>, in which case, it displays the
key followed by the primitive value. Clicking an object will select it and cause the other two
panes to display the detailed contents of that node, including its primitive values, if any.
Double-clicking an object may have one of 3 effects, in order of precedence:</P>
<OL>
<LI>If the object is <B>activatable</B>, i.e., focusable or selectable, the object will be
activated. This is typically the case for sessions, targets, processes, threads, and frames.
The back-end may further refine the selection. E.g., when activating a process, it may choose
a thread and select its top frame. This becomes the current context throughout the Debugger
UI, often including the back end's command-line interface.</LI>
<LI>If the object is <B>togglable</B>, the object will be toggled. This is typically the case
for breakpoints and maybe their locations. <B>NOTE:</B> The Breakpoint manager, which is
otherwise responsible for all breakpoint interactions in the Debugger UI, prefers to toggle
breakpoint locations rather than specifications. Beware that toggling a specification via the
Model window may put the UI in an unexpected state. The Breakpoint manager will attempt to
toggle the location, despite its specification being disabled, which may prevent it from
having any effect. If you seem to be having trouble toggling a breakpoint elsewhere in the
UI, check and enable the breakpoint specification here or in the command-line interface.</LI>
<LI>If the object represents an <B>address</B> or <B>range</B>, this will go to that address
in the Dynamic Listing. If it's a range, it will go to the minimum address and select the
range. This is typically the case for memory regions, modules, sections, and breakpoint
locations; however, breakpoint locations are often togglable, which supersedes go-to.</LI>
</OL>
<P>Right-clicking an object may present a context menu of target-defined actions. Expanding an
object will display its children. If the target provides a <EM>refresh</EM> method for the
object, expanding it will invoke that method. To suppress the refresh, hold <B>SHIFT</B> when
expanding.</P>
<H2>Elements Table Pane</H2>
<P>The Elements pane on the top right displays the elements of the current object. Typically,
this is the object selected in the Tree pane. Each element is displayed in a row. In most
cases, these are <EM>canonical</EM> values. That is the parent's path plus the value's key
gives the child object's path. If not, then the value is a link. Links are fairly rare, but may
happen, e.g., to list a target's breakpoint locations when the specifications are kept in a
per-session container. (GDB's model exhibits this schema.) In rarer cases, elements may be
primitive values. There are 4 standard columns plus any number of target-defined columns:</P>
<UL>
<LI>Key - This is the index used to access the element from its parent.</LI>
<LI>Value - This is the value of the element.</LI>
<LI>Life - This is the "life" of the object. Trace databases record changes to the object
model over a timeline of snapshots. Many objects, especially containers, have a life from 0
to infinity. Others, e.g., threads will have lives indicating their first and last
observations. Rarely, an object may have multiple disjoint lifespans.</LI>
<LI>Plot - This is a visual plot of the "life" of the object. It is hidden by default. The
header for this column contains a caret that shows the Debugger UI's current snapshot within
this plot. Clicking or dragging in that header while in <B>Control Trace</B> or <B>Control
Emulator</B> <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html#control_mode">mode</A> will
activate the clicked snapshot, allowing quick navigation through time. To suppress this
behavior, i.e., so that you can reposition or sort the column, hold <B>SHIFT</B> while
clicking or dragging.</LI>
<LI><I>[Attribute]</I> - Each relevant attribute described in the schema generates a column.
The target determines which are visible and hidden by default. Right-click the table header
to view all available columns. The available columns will vary depending on the current
object.</LI>
</UL>
<H3>Row, Cells, and Selection</H3>
<P>Clicking a row selects it and causes the Attributes pane to display the selected object's
attributes. Double-clicking a row behaves similarly to the Tree pane. A key difference is when
double-clicking a specific cell. If it is an address or range, the UI will go to that address
or range. If it is an object (or a link), then the UI will activate, toggle, or go to that
object. If no such per-cell action is applicable, then the UI will activate, toggle, or go to
the object represented by the row. Right-clicking may present a context menu of target-defined
actions.</P>
<H2>Attributes Table Pane</H2>
<P>The attributes pane on the bottom right displays the attributes of the current object, or
the selected element. If the Object tree's selection changed last, this displays the attributes
of the object selected in the tree. Likewise, if the Elements table's selection changed last,
this displays the attributes of the selected element. Each attribute, whether or not described
in the schema, is displayed in a row, unless marked as hidden by the target. For canonical
values, the parent's path plus the value's key gives the child object's path. Linked objects
are also possible, but primitive values are most common. The columns are:</P>
<UL>
<LI>Key - This is the name used to access the attribute from its parent.</LI>
<LI>Path - This is the full path to the attribute. It is hidden by default.</LI>
<LI>Value - This is the value of the attribute.</LI>
<LI>Life - This is the "life" of the attribute entry. This differs slightly from the Life
column of the Elements table. Disjoint entries having the same key are not merged. Thus, the
column displays a single span for each row.</LI>
<LI>Plot - This is a visual plot of the "life" of the attribute. It is hidden by default. The
header for this column behaves the same as it does in the Elements table.</LI>
</UL>
<H3>Row Selection</H3>
<P>Clicking a row selects it, but otherwise has no effect. Double-clicking a row behaves
similarly to the Object tree pane. Right-clicking may present a context menu of target-defined
actions.</P>
<H2>Typography</H2>
<P>This window and most of the Debugger UI adheres to the following typography:</P>
<UL>
<LI><B>Bold</B> face is used when the displayed item is (or is an ancestor of) the Debugger's
current object. Note that the Model window's current object, i.e., that selected in the tree,
is not necessarily the same as the Debugger's.</LI>
<LI><FONT color="red">Red</FONT> color is used when the displayed value has changed. Since
when? The value is compared between the current and previous trace-snapshot pairs. "Previous"
meaning the pair that were current immediately before the current pair were activated. The
overall result is: 1) When controlling a live target, the values changed since the last
event, e.g., step completed, are displayed in red. 2) When controlling a trace, the values
between the last two visited snapshots are displayed in red. 3) When controlling an emulator,
it depends whether the last action was navigation or stepping.</LI>
<LI>Primitive values are displayed as strings. In particular, numbers are displayed in
decimal.</LI>
<LI>Addresses and ranges are displayed in hex, possibly prefixed with a space name.</LI>
<LI>Primitive arrays are displayed as colon-separated hex, except boolean arrays, which are
displayed as colon-separated <TT>T</TT>s and <TT>F</TT>s.</LI>
<LI>Objects are displayed as their canonical paths, in some cases using <I>italics</I> for
links.</LI>
</UL>
<H2>Actions</H2>
<P>See the specific launcher and/or back end's documentation for target-defined actions. Those
actions are only available when the current trace has a live target. Several other actions are
available for navigating and configuring the Model window.</P>
<H3><A name="follow_link"></A>Follow Link</H3>
<P>When right-clicking a node or row that represents a link to another object, this action will
make that object this window's current object. That is, it will select it in the tree and cause
the tables to display its contents.</P>
<H3><A name="show_objects_tree"></A><A name="pane_toggles"></A><IMG alt="" src=
"icon.debugger.model.tree.objects"> Show Objects Tree</H3>
<P>This button toggles the display of the Objects tree pane.</P>
<H3><A name="show_elements_table"></A><IMG alt="" src="icon.debugger.model.table.elements">
Show Elements Table</H3>
<P>This button toggles the display of the Elements table.</P>
<H3><A name="show_attributes_table"></A><IMG alt="" src="icon.debugger.model.table.attributes">
Show Attributes Table</H3>
<P>This button toggles the display of the Attributes table.</P>
<H3><A name="limit_to_current_snap"></A>Limit to Current Snap</H3>
<P>By default, all panes will only display values that are effective for the Debugger's current
snapshot. For diagnostics, or to scrutinize a target's history, enabling this toggle will cause
the panes to display all values recorded in the trace regardless of the current snapshot. Be
careful using this when selecting or expanding objects whose contents are volatile, since this
will try to render <EM>all values ever</EM> contained by that object.</P>
<H3><A name="show_methods"></A>Show Methods in Tree</H3>
<P>Some targets have their own notion of an object model, e.g., <TT>dbgmodel.dll</TT>. These
models may present methods, that by their nature, are not suitable for registration at
connection time. Instead, they are reflected and invoked using generic methods. This is an
uncommon case, and even then, users may not be interested in seeing such methods enumerated in
the tree. This toggle allows users to have them displayed in the tree.</P>
<H3><A name="show_primitives"></A>Show Primitives in Tree</H3>
<P>This button toggles the display of primitive values in the tree. When the tables are active,
the tree typically serves only to navigate among objects, and so it need not display primitive
values. If you prefer to have only the tree, then consider displaying primitives in the
tree.</P>
<H3><A name="show_hidden"></A>Show Hidden</H3>
<P>Targets specify a schema for the object model. The schema describes the expected objects,
types, attributes and locations for various components of the session. When describing an
attribute, the target can specify whether or not it is hidden. Hidden attributes are not
displayed in any pane by default. This toggle forces hidden attributes to be visible. For all
panes, new nodes and rows are added for any hidden items. For the elements table, this may also
add a multitude of new columns.</P>
<H3><A name="clone_window"></A><IMG alt="" src="icon.provider.clone"> Clone Window</H3>
<P>This copies the Model window in its current configuration to a new Model window. The cloned
Model window is <EM>disconnected</EM> from the rest of the Debugger UI. The main windows is the
only <EM>connected</EM> window. When an object or snapshot is activated in the Debugger, the
connected window tracks along, setting its current object and/or snapshot to match the
Debugger's. Any disconnected windows remain unaffected, but changes to the model itself are
still displayed.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModelPlugin/images/DebuggerModelPlugin.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 38 KiB

5
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModelServicePlugin/DebuggerModelServicePlugin.html
View file

@ -13,6 +13,11 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Model Service</H1>
<P><IMG alt="" src="help/shared/note.png">This service is the source of older "Recorder-based"
targets. Recorders are being replaced with a system we call <EM>Trace RMI</EM>. The other
topics in Help have been updated accordingly. See <A href=
"help/topics/Debugger/GettingStarted.html">Getting Started</A>.</P>
<P>This service plugin backs the <A href=
"help/topics/DebuggerTargetsPlugin/DebuggerTargetsPlugin.html">Targets</A> window. It maintains
all debugger connections across the entire Ghidra session, that is, they're shared across all

95
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html
View file

@ -13,21 +13,16 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Modules and Sections</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerModulesPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerModulesPlugin.png">
</DIV>
<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 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
and sometimes their sections, known to the back-end 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>
@ -36,39 +31,45 @@
<P>The top table, which lists modules, has the following columns:</P>
<UL>
<LI>Base Address - if available, the minimum address where the module is mapped in the
target's memory. Double-clicking this field navigates to the address.</LI>
<LI>Base - if available, the minimum address where the module is mapped in the target's
memory. Double-clicking this field navigates to the address.</LI>
<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>Max - 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>
<LI>Lifespan - denotes the recorded load and unload times of the module, i.e., the span of
time for which the module record is applicable.</LI>
<LI>Mapping - if mapped to a Ghidra program database, the name of that program. An asterisk
is appended if the mapping only covers the module partially. If multiple mappings cover the
module, they are all listed.</LI>
<LI>Length - the length from base address to max address, inclusive. Note that not every page
in the range is necessarily mapped.</LI>
<LI>Path - the path of the module object in the target's model. This is hidden by default.
See the <A href="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A>
window.</LI>
</UL>
<P>The bottom table, which lists sections, has the following columns:</P>
<UL>
<LI>Start Address - the minimum virtual memory address of the section. Double-clicking this
field navigates to the address.</LI>
<LI>Start - the minimum memory address of the section. Double-clicking this field navigates
to the address.</LI>
<LI>End Address - the maximum virtual memory address of the section. Double-clicking this
field navigates to the address.</LI>
<LI>End - the maximum memory address of the section. Double-clicking this field navigates to
the address.</LI>
<LI>Section Name - the name of the section given by the debugger, usually the same as the
name given in the module's header.</LI>
<LI>Name - the name of the section given by the debugger, usually the name given in the
module binary's header.</LI>
<LI>Module Name - the name of the module containing this section.</LI>
<LI>Length - the number of bytes in the section.</LI>
<LI>Path - the path of the section object in the target's model. This is hidden by default.
See the <A href="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A>
window.</LI>
</UL>
<H2>Actions</H2>
@ -81,7 +82,7 @@
<P>This action is available from a module's or section's pop-up menu. It prompts the user to
import the module from the local file system into Ghidra as a static image.</P>
<H3><A name="auto_map"></A>Auto-Map</H3>
<H3><A name="auto_map"></A><IMG alt="" src="icon.debugger.map.auto"> Auto-Map</H3>
<P>This action is always available. It automatically maps trace memory to static images, using
Module, Section, or Region information. See the <A href="#map_modules">Map Modules</A>, <A
@ -91,14 +92,15 @@
corresponding action whenever the relevant table is updated. By default, it automatically maps
using Modules.</P>
<H3><A name="map_identically"></A>Map Identically</H3>
<H3><A name="map_identically"></A><IMG alt="" src="icon.debugger.map.identically"> Map
Identically</H3>
<P>This action is available when both a trace and a program are opened. It maps the current
trace to the current program using identical addresses. This action ignores the module list. It
is a suitable mapping when the current program is loaded in the trace <EM>without
relocation</EM>. It is also a fallback worth trying in the absence of a module list.</P>
<H3><A name="map_manually"></A>Map Manually</H3>
<H3><A name="map_manually"></A><IMG alt="" src="icon.debugger.map.manual"> Map Manually</H3>
<P>This action is always available. It simply displays the <A href=
"help/topics/DebuggerStaticMappingPlugin/DebuggerStaticMappingPlugin.html">Static Mappings</A>
@ -114,14 +116,9 @@
the user can cause the mapper to re-use the memorized mapping in future sessions. The memorized
module name is saved to the program database.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerModuleMapProposalDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerModuleMapProposalDialog.png">
</DIV>
<H3><A name="map_module_to"></A>Map Module to Current Program</H3>
@ -136,14 +133,9 @@
blocks matching the selected sections and proposes new mappings. Users who prefer this to Map
Modules should also consider setting <A href="#auto_map">Auto-Map</A> to use Sections.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerSectionMapProposalDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerSectionMapProposalDialog.png">
</DIV>
<H3><A name="map_sections_to"></A>Map Sections to Current Program</H3>
@ -157,34 +149,39 @@
It behaves like Map Sections, except that it will propose the selected section be mapped to the
block containing the cursor in the static listing.</P>
<H3><A name="import_missing_module"></A>Import Missing Module</H3>
<H3><A name="import_missing_module"></A><IMG alt="" src="icon.debugger.import"> Import Missing
Module</H3>
<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>
<H3><A name="map_missing_module"></A><IMG alt="" src="icon.debugger.map.modules"> Map Missing
Module</H3>
<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="show_sections_table"></A>Show Sections Table</H3>
<H3><A name="show_sections_table"></A><IMG alt="" src="icon.debugger.modules.table.sections">
Show Sections Table</H3>
<P>This actions is always available. By default the sections table (bottom) is showing. Some
debuggers do not offer section information, and even for those that do, it can be expensive to
retrieve it. The visibility of the section table is controlled by toggling this action.</P>
<H3><A name="filter_by_module"></A>Filter Sections by Module</H3>
<H3><A name="filter_by_module"></A><IMG alt="" src="icon.debugger.filter"> Filter Sections by
Module</H3>
<P>This action is always available. By default the bottom table displays all sections in the
current trace. When this toggle is enabled, and at least one module is selected, the bottom
table will only include sections contained by a selected module.</P>
<H3><A name="select_addresses"></A>Select Addresses</H3>
<H3><A name="select_addresses"></A><IMG alt="" src="icon.debugger.select.addresses"> Select
Addresses</H3>
<P>This action is available when at least one module or section is selected. It selects all
addresses in the dynamic listing contained by the selected modules or sections.</P>
<H3><A name="select_rows"></A>Select Rows</H3>
<H3><A name="select_rows"></A><IMG alt="" src="icon.debugger.select.rows"> Select Rows</H3>
<P>This action is available when the dynamic listing's cursor is at a valid location. It
selects the module and section, if applicable, containing that cursor. If the dynamic listing

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerModulesPlugin/images/DebuggerModulesPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 26 KiB

115
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/DebuggerObjectsPlugin.html
View file

@ -13,13 +13,13 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Commands and Objects</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center"><IMG alt="" border="1" src="images/DebuggerObjectsPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerObjectsPlugin.png">
</DIV>
<P><IMG alt="" src="help/shared/note.png">This window only supports the older "Recorder-based"
targets. For newer "TraceRmi-based" targets, see the <A href=
"help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window.</P>
<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
@ -70,7 +70,7 @@
<H2>Actions for Target Management</H2>
<H3><A name="quick_launch"></A><IMG alt="" src="images/debugger.png"> Quick Launch</H3>
<H3><A name="quick_launch"></A><IMG alt="" src="icon.debugger"> Quick Launch</H3>
<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
@ -79,7 +79,7 @@
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>
<H3><A name="launch"></A><IMG alt="" src="icon.debugger.launch"> Launch</H3>
<P>Launch a new target. Sometimes you may wish to launch a program which has not been imported,
to launch a program with various configuration options, or to pass arguments to the program.
@ -93,21 +93,16 @@
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>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center"><IMG alt="" border="1" src=
"images/DebuggerMethodInvocationDialog_ForLaunch.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerMethodInvocationDialog_ForLaunch.png">
</DIV>
<P>The options displayed by the Launch command are, for some targets, connected to the
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>
<H3><A name="attach"></A><IMG alt="" src="icon.debugger.attach"> Attach</H3>
<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
@ -116,60 +111,57 @@
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>
<H3><A name="detach"></A><IMG alt="" src="icon.debugger.detach"> Detach</H3>
<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>
<H3><A name="re-attach"></A><IMG alt="" src="icon.debugger.attach"> Re-attach</H3>
<P>Re-attaches to the selected target. (Some targets require a separate action for re-attaching
vs. attaching for the first time. If so, this action provides that capability.)</P>
<H3><A name="kill"></A><IMG alt="" src="images/kill.png"> Kill</H3>
<H3><A name="kill"></A><IMG alt="" src="icon.debugger.kill"> Kill</H3>
<P>Kill the current target. As a consequence, this action terminates the trace for the current
target, if applicable.</P>
<H2>Actions for Execution Management</H2>
<H3><A name="interrupt"></A><IMG alt="" src="images/stop.png"> Interrupt (Pause, Suspend,
Break)</H3>
<H3><A name="interrupt"></A><IMG alt="" src="icon.debugger.interrupt"> Interrupt (Pause,
Suspend, Break)</H3>
<P>Interrupt the current target's execution.</P>
<H3><A name="resume"></A><IMG alt="" src="images/resume.png"> Resume (Continue, Go)</H3>
<H3><A name="resume"></A><IMG alt="" src="icon.debugger.resume"> Resume (Continue, Go)</H3>
<P>Allow the current target to resume execution.</P>
<H3><A name="step_into"></A><IMG alt="" src="images/stepinto.png"> Step Into</H3>
<H3><A name="step_into"></A><IMG alt="" src="icon.debugger.step.into"> Step Into</H3>
<P>Step the current target to the next instruction.</P>
<H3><A name="step_over"></A><IMG alt="" src="images/stepover.png"> Step Over</H3>
<H3><A name="step_over"></A><IMG alt="" src="icon.debugger.step.over"> Step Over</H3>
<P>Step the current target to the next instruction in the current subroutine.</P>
<H3><A name="step_finish"></A><IMG alt="" src="images/stepout.png"> Finish</H3>
<H3><A name="step_finish"></A><IMG alt="" src="icon.debugger.step.finish"> Finish</H3>
<P>Allow the current target to finish the current subroutine, pausing after.</P>
<H3><A name="step_last"></A><IMG alt="" src="images/steplast.png"> Step Last / Extended</H3>
<H3><A name="step_last"></A><IMG alt="" src="icon.debugger.step.last"> 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
<H3><A name="set_breakpoint"></A><IMG alt="" src="icon.debugger.breakpoint.set"> Set
Breakpoint</H3>
<P>Set a breakpoint, which will trap target execution under certain conditions.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center"><IMG alt="" border="1" src="images/DebuggerBreakpointDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerBreakpointDialog.png">
</DIV>
<P>The given expression can follow any form accepted by the connected debugger, although most
often this will be an address. Compare this to the listing, which can only set breakpoints on
@ -182,8 +174,7 @@
"help/topics/DebuggerBreakpointMarkerPlugin/DebuggerBreakpointMarkerPlugin.html">Breakpoint
Marker</A> actions from the disassembly listings.</P>
<H3><A name="toggle_option"></A><IMG alt="" src="images/system-switch-user.png"> Toggle
Option</H3>
<H3><A name="toggle_option"></A><IMG alt="" src="icon.debugger.toggle"> Toggle Option</H3>
<P>Toggle an object. This may apply to a breakpoint or to configuration options provided in the
model tree.</P>
@ -193,13 +184,13 @@
<P>The following actions manage target tracing. Note that many other windows are not usable
until a target is recorded into a trace.</P>
<H3><A name="record"></A><IMG alt="" src="images/record.png"> Record</H3>
<H3><A name="record"></A><IMG alt="" src="icon.debugger.record"> Record</H3>
<P>Record the current target, if its platform is recognized, and open its trace. If Ghidra
cannot uniquely identify the platform, it may prompt the user to select from a list of
possibilities.</P>
<H3><A name="record_automatically"></A><IMG alt="" src="images/record.png"> Record
<H3><A name="record_automatically"></A><IMG alt="" src="icon.debugger.record"> Record
Automatically</H3>
<P>Automatically record and open recognized targets. If Ghidra cannot uniquely identify the
@ -209,13 +200,13 @@
<P>The following actions can create additional displays of portions of the debugger model.</P>
<H3><A name="display_as_tree"></A><IMG alt="" src="images/display_as_tree.png"> Display As
<H3><A name="display_as_tree"></A><IMG alt="" src="icon.debugger.tree.object"> Display As
Tree</H3>
<P>Constructs a new tree using the selection as the new root, synchronized with the current
provider.</P>
<H3><A name="display_as_table"></A><IMG alt="" src="images/display_as_table.png"> Display As
<H3><A name="display_as_table"></A><IMG alt="" src="icon.debugger.table.object"> Display As
Table</H3>
<P>Constructs a table from the current object, synchronized with the current provider. If the
@ -223,84 +214,86 @@
columns. If not, the attributes will be rows and their name, kind, value, and type will be
columns.</P>
<H3><A name="display_as_graph"></A><IMG alt="" src="images/display_as_graph.png"> Display As
<H3><A name="display_as_graph"></A><IMG alt="" src="icon.debugger.display.graph"> Display As
Graph</H3>
<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
<H3><A name="display_as_xml"></A><IMG alt="" src="icon.debugger.display.xml"> 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>
<H3><A name="display_filtered_tree"></A><IMG alt="" src="images/display_filtered_tree.png">
Display Filtered Tree</H3>
<H3><A name="display_filtered_tree"></A><IMG alt="" src="icon.debugger.tree.object"> Display
Filtered Tree</H3>
<P>Constructs a static snapshot of the selection and its visible descendants as a tree,
applying a filter to the selection.</P>
<H3><A name="display_filtered_table"></A><IMG alt="" src="images/display_filtered_table.png">
Display Filtered Table</H3>
<H3><A name="display_filtered_table"></A><IMG alt="" src="icon.debugger.table.object"> Display
Filtered Table</H3>
<P>Constructs a static snapshot of the selection and its visible descendants as a table,
applying a filter to the selection.</P>
<H3><A name="display_filtered_graph"></A><IMG alt="" src="images/display_filtered_graph.png">
<H3><A name="display_filtered_graph"></A><IMG alt="" src="icon.debugger.display.xml.filtered">
Display Filtered Graph</H3>
<P>Constructs a static snapshot of the selection and its visible descendants as a graph,
applying a filter to the selection.</P>
<H3><A name="display_filtered_xml"></A><IMG alt="" src="images/display_filtered_xml.png">
<H3><A name="display_filtered_xml"></A><IMG alt="" src="icon.debugger.display.xml.filtered">
Display Filtered XML</H3>
<P>Constructs a static snapshot of the selection and its visible descendants as XML, applying a
filter to the selection.</P>
<H3><A name="display_methods"></A><IMG alt="" src="images/blank.png"> Display Methods</H3>
<H3><A name="display_methods"></A>Display Methods</H3>
<P>Displays a list of the methods available for the selection, which may be applied and
combined in a filter.</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>
<H3><A name="export_as_xml"></A><IMG alt="" src="icon.debugger.display.export.xml"> Export as
XML</H3>
<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>
<H3><A name="import_from_xml"></A><IMG alt="" src="icon.debugger.display.import.xml"> Import
from XML</H3>
<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>
<H3><A name="export_as_facts"></A><IMG alt="" src="icon.debugger.display.export.facts"> Export
as Facts</H3>
<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>
<H3><A name="import_from_facts"></A><IMG alt="" src="icon.debugger.display.import.facts">
Import from Facts</H3>
<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>
<H3><A name="open_trace"></A><IMG alt="" src="icon.debugger.open.windbg.trace"> Import from
trace</H3>
<P>Import from trace is roughly equivalent to using the open dump/trace connector.</P>
<H2>Miscellaneous Actions</H2>
<H3><A name="console"></A><IMG alt="" src="images/console.png"> Console</H3>
<H3><A name="console"></A><IMG alt="" src="icon.debugger.provider.console"> 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>
<H3><A name="refresh"></A><IMG alt="" src="icon.debugger.refresh"> Refresh Node</H3>
<P>Queries the model for the current object's children and rebuilds that portion of the
display.</P>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/breakpoint-set.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 383 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_graph.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 368 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_table.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 566 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_tree.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 295 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_as_xml.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 857 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_graph.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 368 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_table.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 566 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_tree.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 295 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/display_filtered_xml.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 857 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/export_as_facts.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 545 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/export_as_xml.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 857 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/import_from_facts.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 545 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/import_from_xml.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 857 B

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerObjectsPlugin/images/stop.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 172 B

34
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerPcodeStepperPlugin/DebuggerPcodeStepperPlugin.html
View file

@ -13,23 +13,19 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: P-code Stepper</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerPcodeStepperPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerPcodeStepperPlugin.png">
</DIV>
<P>P-code is the "microcode" of Ghidra's processor specifications, compiled from its Sleigh
specification. Originally designed to facilitate static analysis, it is easily applied to
emulation as well. Stepping each p-code operation is an effective means of debugging the
Sleigh. The plugin provides two panes: 1) The p-code listing, and 2) Temporary ("Unique")
variables. The listing works similarly to the dynamic listing. It displays each p-code
operation, highlighting the current "counter", which is the next operation to be executed.
There is also a cursor, allowing selection of an operation. The variables view operates
similarly to the registers view, displaying the current value of each unique variable.</P>
<P>P-code is the "microcode" or "intermediate representation" of Ghidra's processor models,
compiled from their Sleigh specifications. Originally designed to facilitate static analysis,
it is easily applied to emulation as well. Stepping each p-code operation is an effective means
of debugging the Sleigh. The plugin provides two panes: 1) The p-code listing, and 2) Unique or
temporary variables. The listing works similarly to the dynamic listing. It displays each
p-code operation, highlighting the current "counter", which is the next operation to be
executed. There is also a cursor, allowing selection of an operation. The variables view
operates similarly to the registers view, displaying the current value of each unique
variable.</P>
<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.,
@ -62,12 +58,14 @@
interact with the target, stepping at the p-code level implies you are no longer "at the
present."</P>
<H3><A name="emu_trace_pcode_backward"></A>Emulate Trace p-code Backward</H3>
<H3><A name="emu_trace_pcode_backward"></A><IMG alt="" src="icon.debugger.step.back"> Emulate
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.</P>
<H3><A name="emu_trace_pcode_forward"></A>Emulate Trace p-code Forward</H3>
<H3><A name="emu_trace_pcode_forward"></A><IMG alt="" src="icon.debugger.step.into"> Emulate
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.

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerPcodeStepperPlugin/images/DebuggerPcodeStepperPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 28 KiB

73
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerPlatformPlugin/DebuggerPlatformPlugin.html
View file

@ -14,56 +14,57 @@
<H1><A name="plugin"></A>Debugger: Platform Selection</H1>
<P>The Debugger allows the user to work with multiple platforms, i.e., architectures,
compilers, etc., within the context of a single debug target. This plugin allows the user to
switch among platforms and/or introduce new platforms via overrides.</P>
compilers, etc., within the context of a single debug target. This plugin facilitates switching
among platforms and introducing new platforms.</P>
<P>Note we are in a transitional period between two trace database conventions. This plugin is
a necessary component when working with the new convention. In the legacy convention, the
system must ascertain the target's language and compiler at the time it begins recording. If it
fails or makes an incorrect decision, the UI remains mostly empty, or worse, the system
interrogates and instructs the target using the wrong architecture. This mode still works in
most circumstances and is the default and recommended convention. Additional platforms can
still be introduced, but there is perhaps little use for doing so. One case might be to, e.g.,
disassemble JVM bytecodes when debugging a Java process at the native level.</P>
<P>Note we are currently supporting two trace database conventions. In the first, the system
ascertains the target's platform and maps it to a Ghidra language and compiler spec at the time
the trace is created. These are called the <EM>base</EM> language and base compiler spec.
Together, they comprise the trace's <EM>host platform</EM>. This is used by "Recorder-mode"
traces and most "TraceRmi-mode" traces.</P>
<P>In the new convention, the system always records the target, using the "DATA" language,
i.e., no language. The object tree is recorded, and objects with memory are assigned overlay
spaces where their contents are recorded. The only way to disassemble instructions is to add a
guest platform. This plugin will do that automatically, in more or less the same fashion as the
language and compiler are ascertained in legacy mode. If this fails, the recording still
proceeds, and most of the UI is still useful. The user can add (perhaps by trial and error) the
correct platform later. In the meantime, memory, registers, threads, etc., are all still
displayed.</P>
<P>However, there are some cases where it is impractical to know the platform before creating
the trace, e.g., when setting up "raw" connections. For these cases we have a second
convention: The system creates a trace with the host platform
<CODE>DATA:BE:64:default:pointer64</CODE>, for example. Thus, disassembly requires the system
(or user) to ascertain the platform at a later time. This can then be mapped into the existing
trace as a <EM>guest platform</EM>. Either convention permits guest platforms, but they are a
necessary aspect of the second. If the system has failed to ascertain the platform, the user
may attempt to do so by adding <EM>override</EM> platforms in trial-and-error fashion.
Furthermore, even if the system has succeeded, there may be cause to try disassembly in
alternative languages, e.g., Java bytecode when debugging its x86 JVM at the native level.</P>
<H2>Actions</H2>
<P>This plugin adds actions into the Debugger menu under "Choose Platform."</P>
<P>This plugin adds actions under the <B>Debugger &rarr; Choose Platform</B> menu.</P>
<H3><A name="choose_platform"></A>Choose Platform</H3>
<H3><A name="choose_host"></A>Host/base</H3>
<P>This action adds or changes to a specific platform in the current trace. One of these
actions is presented for each recommended or previously chosen platform, if any. The
recommendations are given by an opinion service, so new options may be added by extension
modules. It is possible there are no recommendations for the current trace. The current
platform is designated by a check mark or other selection indicator.</P>
<P>This action corresponds to the current trace's host platform. Technically, this is just one
platform option among possible recommendations, but it is always among them. If the host
language is <B>DATA:...</B>, then this platform will not support disassembly. A guest platform
is necessary.</P>
<H3><A name="choose_platform"></A><I>[Platform Name]</I></H3>
<P>This action is replicated for each recommended platform and for each platform already
present in the trace. The recommendations are given by an opinion service, so new options may
be added by Ghidra extension modules. It is possible there are no recommendations for the
current trace. The current platform is indicated by a check mark.</P>
<H3><A name="choose_more_platforms"></A><A name="prev_diff"></A>More...</H3>
<P>This action is enabled whenever there is a current trace. It presents a dialog with the
recommended platforms for the trace.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerSelectPlatformOfferDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerSelectPlatformOfferDialog.png">
</DIV>
<P>The "Show Only Recommended Offers" check can be disabled to display override offers as well.
<P>The "Show Only Recommended Offers" check can be disabled to display <EM>override</EM>
platforms as well. Every language-compiler-spec pair is offered as an override platform.
Selecting an offer and confirming the dialog will add or change to the selected platform in the
trace. Furthermore, the choice will be added to the "Choose Platform" menu until the trace is
closed.</P>
trace. Furthermore, the choice will be added to the <B>Choose Platform</B> menu for the current
trace.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerPlatformPlugin/images/DebuggerSelectPlatformOfferDialog.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 20 KiB

62
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegionsPlugin/DebuggerRegionsPlugin.html
View file

@ -13,21 +13,16 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Memory Regions</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerRegionsPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerRegionsPlugin.png">
</DIV>
<P>Regions refer to ranges of allocated or reserved memory reported by the target. The precise
meaning of these regions may vary depending on the nature of the target. For user-mode
applications, this is generally pages of memory allocated for image sections, the stack, the
heap, etc. The regions manager allows the user to rename pages and modify the recorded
permissions. Note that such modifications <EM>do not</EM> affect the target; but only the
recording.</P>
<P>Regions refer to ranges of allocated or reserved memory reported by the target, i.e., the
target's memory map. The precise meaning of these regions may vary depending on the nature of
the target. For user-mode applications, this is generally pages of memory allocated for image
sections, the stack, the heap, etc. The regions manager allows the user to rename pages and
modify the recorded permissions. Note that such modifications <EM>do not</EM> affect the
target; but only the recorded trace.</P>
<H2>Table Columns</H2>
@ -36,8 +31,6 @@
<UL>
<LI>Name - the name given to the region by the target. This field is user modifiable.</LI>
<LI>Lifespan - the creation and destruction time of the region.</LI>
<LI>Start - the minimum address of the region. Double-clicking this field navigates to the
address.</LI>
@ -46,14 +39,17 @@
<LI>Length - the length of the region in bytes.</LI>
<LI>Read,Write,Execute,Volatile - various flags of the region. These flags only affect local
<LI>Read, Write, Execute - various flags of the region. These flags only affect Ghidra's
analysis. Toggling these <EM>do not</EM> affect the target.</LI>
<LI>Key, Path - descriptions the region object in the target's model. These are hidden by
default. See the <A href="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A>
window.</LI>
</UL>
<H2>Actions</H2>
<P>Other than modifications enabled by the table, the Regions window provides the following
actions:</P>
<P>The Regions window provides the following actions:</P>
<H3><A name="map_regions"></A>Map Regions</H3>
@ -68,14 +64,9 @@
include the module's file name, otherwise the matcher has no means to identify a corresponding
program.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerRegionMapProposalDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerRegionMapProposalDialog.png">
</DIV>
<H3><A name="map_regions_to"></A>Map Regions to Current Program</H3>
@ -91,12 +82,13 @@
It behaves like Map Regions, except that it will propose the selected region be mapped to the
block containing the cursor in the static listing.</P>
<H3><A name="select_addresses"></A>Select Addresses</H3>
<H3><A name="select_addresses"></A><IMG alt="" src="icon.debugger.select.addresses"> Select
Addresses</H3>
<P>This action is available when at least one region is selected. It selects all addresses in
the dynamic listing contained by the selected regions.</P>
<H3><A name="select_rows"></A>Select Rows</H3>
<H3><A name="select_rows"></A><IMG alt="" src="icon.debugger.select.rows"> Select Rows</H3>
<P>This action is available when the dynamic listing's cursor is at a valid location. It
selects the region containing that cursor. If the dynamic listing has a selection, it selects
@ -105,7 +97,7 @@
<H3><A name="add_region"></A>Add Region</H3>
<P>This action is available when a trace is active. It adds a new region to the memory map. It
should only be used for emulation or to correct or diagnose trace recording issues.</P>
should only be used for emulation or to correct a recorded trace.</P>
<H3><A name="delete_regions"></A>Delete Regions</H3>
@ -116,10 +108,10 @@
<H3><A name="force_full_view"></A>Force Full View</H3>
<P>This action is available when a trace is active. It forces all physical address spaces into
the view. Ordinarily, only those addresses contained in a region at the active snap are
presented in the listing and memory windows. When this toggle is on, regions are ignored.
Instead, all physical addresses are presented. (Here "physical" includes all memory spaces
except <CODE>OTHER</CODE>.) This toggle applies only to the current trace for the duration it
is open.</P>
the view. By default, only those addresses in the memory map &mdash; as recorded in the trace
at the current snapshot &mdash; are displayed in the listing and memory windows. When this
toggle is on, regions are ignored. Instead, all physical addresses are displayed. ("Physical"
includes all Sleigh memory spaces except <CODE>OTHER</CODE>.) This toggle applies only to the
current trace.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegionsPlugin/images/DebuggerRegionMapProposalDialog.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 21 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegionsPlugin/images/DebuggerRegionsPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 19 KiB

83
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html
View file

@ -13,14 +13,9 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Registers</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerRegistersPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerRegistersPlugin.png">
</DIV>
<P>Registers refer to the target processor's register banks. In multi-threaded environments, it
is assumed that each thread has its own register context. The register window presents a subset
@ -30,15 +25,15 @@
<P>The register window uses colors to hint about the state of registers and their values. By
default, changed registers are displayed in red, and stale registers are displayed in dark
grey. A "stale" register is one whose current value is not known. The value displayed is the
last recorded value or the default value 0. Simply, a "changed" register is one whose value has
just changed. For example, if a register is modified as result of stepping, then that register
is changed. However, given the possibility of rewinding, changing thread focus, etc., "changed"
is actually subtly more flexible. The registers window remembers the user's last coordinates
(time, thread, frame, etc.) as well as the current coordinates. So, "changed" more precisely
refers to a register whose value differs between those two coordinates. This permits the user
to switch focus between different coordinates and quickly identify what is different, so long
as those coordinates pertain to the same processor language.</P>
grey. A <EM>stale</EM> register is one whose current value is not known. The value displayed is
the last recorded value or the default value 0. A <EM>changed</EM> register is one whose value
has just changed. For example, if a register is modified as result of stepping, then that
register is changed. However, given the possibility of rewinding, changing thread focus, etc.,
"changed" is actually subtly more flexible. The registers window remembers the user's last
coordinates (time, thread, frame, etc.) as well as the current coordinates. So, "changed" more
precisely refers to a register whose value differs between those two coordinates. This permits
the user to switch focus between different coordinates and quickly identify what is different,
so long as those coordinates pertain to the same processor language.</P>
<H2>Table Columns</H2>
@ -48,24 +43,24 @@
<UL>
<LI>Favorite - a toggle to mark the register as a favorite. By default this includes the
program counter and stack pointer. Favorites are sorted to the top, by default. The list of
favorite registers is memorized per compiler specification.</LI>
favorite registers is memorized per platform.</LI>
<LI>Number - the index of the register in Ghidra's language model. By default, this is the
second sort column.</LI>
<LI>Name - the name of the register in Ghidra's language model.</LI>
<LI>Value - the value of the register as recorded in the trace. When the value refers to a
valid memory offset, right-clicking the row allows the user to navigate to that offset in a
<LI>Value - the value of the register recorded in the trace. When the value refers to a valid
memory offset, right-clicking the row allows the user to navigate to that offset in a
selected memory space. This field is user modifiable when the <B>Enable Edits</B> toggle is
on, and the register is modifiable. Edits may be directed toward a live target, the trace, or
the emulator. Values changed by the last event are displayed in <FONT color=
"red">red</FONT>.</LI>
<LI>Type - the type of the register as marked up in the trace. There is generally no default
here. Either the user or some automation, e.g., analysis, may set this value. Changes to this
field <EM>do not</EM> affect the target. The selected type is saved to the trace "from this
time on."</LI>
here. Either the user or some automation may set the type. Changes to this field <EM>do
not</EM> affect the target. The selected type is saved to the trace for the current and
future snapshots.</LI>
<LI>Representation - the value of the register as interpreted by its data type. If the value
is an address, double-clicking this field will navigate to it. This field is user modifiable
@ -77,44 +72,38 @@
<P>The register window provides the following actions:</P>
<H3><A name="select_registers"></A><A name="add"></A><A name="remove"></A><IMG alt="" src=
"images/select-registers.png"> Select Registers</H3>
"icon.debugger.select.registers"> Select Registers</H3>
<P>This displays a dialog for selecting which registers to display in the table.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerAvailableRegistersDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerAvailableRegistersDialog.png">
</DIV>
<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 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-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
registers cannot affect the target. Register sets are memorized per compiler specification.</P>
<P>The dialog provides more information about each register, displays a potentially larger set
of registers, and permits the selection of registers to include in the window. This is a more
persistent and more precise means of removing registers from the window, compared with
filtering. Note that deselecting a register does not necessarily prevent that register from
being read. Nor does it prohibit other components from reading that register. For example, the
program counter and stack pointer are recorded by the target 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-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. Modifying the values of unknown registers cannot affect the target. Selected registers
are memorized per platform.</P>
<H3><A name="type_settings"></A>Register Type Settings</H3>
<P>This action is available on the context menu when there is a single register selected with a
data type assigned. It permits the adjustment of that data type's settings, e.g., to display
decimal vs hexadecimal. The settings are saved to the data unit for the register.</P>
decimal vs hexadecimal. The settings are saved to the trace's data unit for the register.</P>
<H3><A name="enable_edits"></A>Enable Edits</H3>
<H3><A name="enable_edits"></A><IMG alt="" src="icon.debugger.enable.edits"> Enable Edits</H3>
<P>This toggle is a write protector for machine state. To modify register values, this toggle
must be enabled. Edits are directed according the to <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control and Machine State
Plugin</A>. <B>Note:</B> Only the raw "Value" column can be edited directly. The "Repr" column
cannot be edited, yet.</P>
Plugin</A>.</P>
<H3><A name="clone_window"></A>Clone Window</H3>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegistersPlugin/images/DebuggerAvailableRegistersDialog.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 42 KiB

After

Width:  |  Height:  |  Size: 40 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerRegistersPlugin/images/DebuggerRegistersPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 28 KiB

66
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html
View file

@ -13,27 +13,22 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Stack</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerStackPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerStackPlugin.png">
</DIV>
<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 only
the innermost frame. When emulation is used to generate the current machine state, only a
single synthetic frame is shown. See the <A href="#unwind_stack">Unwind Stack</A> action for an
alternative mechanism that unwinds using Ghidra's program databases and works with emulation.
alternative mechanism that unwinds using Ghidra's program databases and works during emulation.
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." Double-clicking 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>
tool's current <EM>coordinates</EM>. Double-clicking a frame <EM>activates</EM> new
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>
@ -43,12 +38,12 @@
<LI>Level - the level of the frame, counting 0-up starting at the innermost frame.</LI>
<LI>PC - the address of the instruction to execute next, or upon return of the callee for
non-0 frames. Different platforms may have different subtleties in how they report PC.</LI>
non-0 frames. Different debuggers may have different subtleties in how they report PC.</LI>
<LI>Function - the name of the containing function, if Ghidra has the corresponding module
image imported and analyzed.</LI>
<LI>Function - the name of the function containing the PC, if Ghidra has the corresponding
module image imported, analyzed, and mapped.</LI>
<LI>Comment - a user-modifiable comment.</LI>
<LI>Module - the name of the module containing the PC.</LI>
</UL>
<H2>Action</H2>
@ -57,27 +52,22 @@
<H3><A name="unwind_stack">Unwind Stack (U)</A></H3>
<P>This action is in the main menu: <SPAN class="menu">Debugger &rarr; Analysis &rarr; Unwind
from frame 0</SPAN>. It attempts to unwind the current thread's stack segment, creating frame
data units in the listing. It starts by reading the program counter and stack pointer from the
innermost frame of the current thread. It then maps the program counter to the program database
and analyzes the function containing it. If successful, it can determine the frame's base
address and locate variables, saved registers, and the return address. Knowing the return
address and frame depth, it can derive the program counter and stack pointer of the next frame
and unwind it in the same manner. This proceeds until analysis fails or the stack segment is
exhausted. For best results, ensure you have imported and opened the Ghidra program database
for every module, or at least the subset you expect to see in your stack. To view the results,
navigate to or follow the stack pointer in a Dynamic Listing. The Stack window <EM>does
not</EM> display Ghidra's unwinding results.</P>
<P>This action is in the main menu: <B>Debugger &rarr; Analysis &rarr; Unwind from frame 0</B>.
It attempts to unwind the current thread's stack segment, creating frame data units in the
listing. It starts by reading the program counter and stack pointer from the innermost frame of
the current thread. It then maps the program counter to the program database and analyzes the
function containing it. If successful, it can determine the frame's base address then locate
variables, saved registers, and the return address. Knowing the return address and frame depth,
it can derive the program counter and stack pointer of the next frame and unwind it in the same
manner. This proceeds until analysis fails or the stack segment is exhausted. For best results,
ensure you have imported and opened the Ghidra program database for every module, or at least
the subset you expect to see in your stack. To view the results, navigate to or follow the
stack pointer in a Dynamic Listing. The Stack window <EM>does not</EM> display Ghidra's
unwinding results.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerStackUnwindInListing.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerStackUnwindInListing.png">
</DIV>
<P>Each call record generates a structure data unit derived from the function's frame. The
exact contents of the structure depend on the current program counter within that function.

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStackPlugin/images/DebuggerStackPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.8 KiB

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStackPlugin/images/DebuggerStackUnwindInListing.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 46 KiB

42
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStaticMappingPlugin/DebuggerStaticMappingPlugin.html
View file

@ -13,25 +13,20 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Static Mappings</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerStaticMappingPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerStaticMappingPlugin.png">
</DIV>
<P>A static mapping refers to a range of addresses in the dynamic listing and its corresponding
range in the static listing. These mappings provide a flexible means of mapping imported
images, i.e., Ghidra Program Databases, into a trace. Typically, this table is populated by
automation, e.g., the <A href=
"help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html#auto_map">Auto-Map</A> action, or
by manual user actions, e.g., the <A href=
range in the static listing. These mappings provide a flexible means of mapping Ghidra program
databases into a trace database. Typically, this table is populated automatically. See the <A
href="help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html#auto_map">Auto-Map</A>
action. Common mapping schemes are available in user actions, e.g., <A href=
"help/topics/DebuggerModulesPlugin/DebuggerModulesPlugin.html#map_modules">Map Modules</A>.
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>
developers to diagnose image mapping issues and manually specify mappings, regardless of
reported modules, sections, regions, etc. For most users, there is no reason to access this
window.</P>
<H2>Table Columns</H2>
@ -40,29 +35,30 @@
<UL>
<LI>Dynamic Address - the minimum address in the dynamic address range.</LI>
<LI>Static Program - the Ghidra URL of the imported static image.</LI>
<LI>Static Program - the Ghidra URL of the program database, i.e., the imported static
image.</LI>
<LI>Static Address - the minimum address in the static address range.</LI>
<LI>Length - the number of bytes in each address range.</LI>
<LI>Length - the number of bytes in the mapping.</LI>
<LI>Shift - the offset from static address to dynamic address.</LI>
<LI>Lifespan - the span of time for which this mapping is applicable.</LI>
<LI>Lifespan - the span of snapshots for which this mapping is applicable.</LI>
</UL>
<H2>Actions</H2>
<P>This window provides actions for finding, adding, and removing mappings. Note that entries
cannot be modified.</P>
<P>This window provides actions for finding, adding, and removing mappings. <B>NOTE:</B> To
"modify" an entry, delete and re-add it.</P>
<H3><A name="select_rows"></A>Select Rows</H3>
<H3><A name="select_rows"></A><IMG alt="" src="icon.debugger.select.rows"> Select Rows</H3>
<P>This action is available when the active listing's (dynamic or static) cursor is at a valid
location. It selects the mapping containing that cursor. If the active listing has a selection,
it selects all mappings intersecting that selection.</P>
<H3><A name="add"></A>Add Mapping</H3>
<H3><A name="add"></A><IMG alt="" src="icon.debugger.add"> Add Mapping</H3>
<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
@ -70,7 +66,7 @@
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>
<H3><A name="remove"></A><IMG alt="" src="icon.debugger.delete"> Remove Mapping</H3>
<P>This action is available when at least one mapping is selected. It removes those
mappings.</P>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerStaticMappingPlugin/images/DebuggerStaticMappingPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

28
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTargetsPlugin/DebuggerTargetsPlugin.html
View file

@ -13,14 +13,12 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Targets</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerTargetsPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerTargetsPlugin.png">
</DIV>
<P><IMG alt="" src="help/shared/note.png">This window only supports the older "Recorder-based"
targets. For newer "TraceRmi-based" targets, see the Connection Manager window.</P>
<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
@ -33,17 +31,13 @@
<P>This window provides the following actions for managing connections.</P>
<H3><A name="connect"></A><IMG alt="" src="images/connect.png"> Connect</H3>
<H3><A name="connect"></A><IMG alt="" src="icon.debugger.connect"> Connect</H3>
<P>Prompts the user to select a connector and configure its parameters.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src="images/DebuggerConnectDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerConnectDialog.png">
</DIV>
<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
@ -52,7 +46,7 @@
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>
<H3><A name="disconnect"></A><IMG alt="" src="icon.debugger.disconnect"> Disconnect</H3>
<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

117
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html
View file

@ -5,98 +5,73 @@
<META name="generator" content=
"HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">
<TITLE>Debugger: Threads and Traces</TITLE>
<TITLE>Debugger: Threads</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
<LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
</HEAD>
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Threads and Traces</H1>
<H1><A name="plugin"></A>Debugger: Threads</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerThreadsPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerThreadsPlugin.png">
</DIV>
<P>In general, a thread refers to a unit of concurrent execution within a target. Typically,
each thread carries its own execution context, so this window provides a means of navigating
those contexts. Furthermore, this window provides a means of navigating and managing open
traces, much like the static listing provides a means of navigating open programs. The window
also plots a timeline showing thread lifespans, and displays a caret which can be used to
navigate the current point in time. This window, the <A href=
"help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html">Stack</A> window, and the <A href=
those contexts. The window also plots a timeline showing thread lifespans, and displays a caret
which can be used to navigate the current point in time. This window, the <A href=
"help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html">Stack</A> window, the <A href=
"help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A> window, and the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Dynamic Listing</A> window
provide a complete trace navigation system.</P>
<H2>Trace Tabs</H2>
<H2>Table Columns</H2>
<P>The trace tab bar is displayed when at least one trace is open. It displays the name of each
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 not
record any new target information.</P>
<UL>
<LI>Name - the name or summary of the thread given by the debugger. If a name is not given,
this is just an index or unique id assigned to the thread. This field can be modified, but it
has no effect on the target.</LI>
<H3><A name="close_trace"></A><A name="close_all_traces"></A><A name=
"close_other_traces"></A><A name="close_dead_traces"></A>Close Trace / All / Other / Dead
Traces</H3>
<LI>PC - the program counter of the thread. This is typically the address of the next
instruction it will execute. If the debugger records frames, this is the PC of the innermost
frame.</LI>
<P>In most cases, a trace is ephemeral, but occasionally, interesting behavior is observed that
is difficult to store as static mark-up. When traces are no longer needed, they can be closed
by right-clicking a tab and selecting one of the actions. See <A href=
"help/topics/DebuggerTraceManagerServicePlugin/DebuggerTraceManagerServicePlugin.html#close_trace">Trace
Management</A> for details of each action.</P>
<LI>Function - the name of the function containing the PC, if Ghidra has the corresponding
module image imported, analyzed, and mapped.</LI>
<LI>Module - the name of the module containing the PC. This column is hidden by default.</LI>
<LI>SP - the stack pointer for the thread. If the debugger records per-frame registers, this
is the SP from the innermost frame. This column is hidden by default.</LI>
<LI>State - the thread's current state. Depending on what is reported by the debugger, this
should be either RUNNING, STOPPED, or TERMINATED. It might also be ALIVE, if the debugger
cannot determine whether or not it is running; or UNKNOWN, if the debugger has lost
track.</LI>
<LI>Plot - a graphical representation of the thread's lifespan. Threads which are alive will
appear to extend to the end of time. Unlike other column headers, clicking and dragging in
this one may navigate trace snapshots. To rearrange this column, hold <B>SHIFT</B> while
dragging.</LI>
<LI>Comment - a user-modifiable comment about the thread. This column is hidden by
default.</LI>
<LI>Path - the path of the thread object in the target's model. This is hidden by default.
See the <A href="help/topics/DebuggerModelPlugin/DebuggerModelPlugin.html">Model</A>
window.</LI>
</UL>
<H2>Navigating Threads</H2>
<P>Double-clicking a thread in the table will navigate to (or "activate" or "focus") that
thread. Windows which are sensitive to the current thread will update. Notably, the <A href=
<P>Double-clicking a thread in the table will <EM>activate</EM> that thread, i.e., it becomes
the current thread throughout the Debugger UI, usually including the debugger's command-line
interface. 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 thread's context and
navigate to it. The thread timeline plots 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, but it has no effect on the
target.</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 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,
and depends solely on whether or not a destruction time was recorded. For a live trace, this
may also take RUNNING, STOPPED, or UNKNOWN, depending on what is reported by the debugger.
The state always reflects the present, or latest known, state.</LI>
<LI>Comment - a user-modifiable comment about the thread.</LI>
<LI>Plot - a graphical representation of the thread's lifespan. Unlike other column headers,
clicking and dragging in this one will navigate trace snapshots. To rearrange this column,
hold SHIFT while dragging.</LI>
</UL>
<H2>Actions</H2>
<H3><A name="sync_target"></A>Synchronize Trace and Target Activation</H3>
<P>This toggle is always available and is enabled by default. While enabled, any changes in
navigation coordinates are translated, to the extent possible, and sent to the connected
debugger. This may, for example, issue <CODE>thread</CODE> and/or <CODE>frame</CODE> commands
to GDB so that commands typed into its CLI will refer to the same thread and frame as is active
in Ghidra. Conversely, any target events which indicate a change in activation are translated,
to the extent possible, into navigation coordinates and activated in Ghidra. For example, if
the user issues a <CODE>frame</CODE> command to the CLI of a GDB connection, then Ghidra will
navigate to that same frame.</P>
navigate to it.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerThreadsPlugin/images/DebuggerThreadsPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 16 KiB

69
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html
View file

@ -13,22 +13,19 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Time</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerTimePlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerTimePlugin.png">
</DIV>
<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. Double-clicking a snapshot
navigates to the selected point in time. Note that navigating to the past may change your <A
href="help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control mode</A>.</P>
time ranges to describe lifespans of various objects. Those times refer to the <EM>snap</EM>,
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. Double-clicking a
snapshot <EM>activates</EM> the selected point in time, i.e., the entire Debugger UI will
navigate to the selected snapshot. <B>NOTE:</B> Navigating through time is not permitted while
in <B>Control Target</B> <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html#control_mode">mode</A>.</P>
<H2>Table Columns</H2>
@ -45,11 +42,9 @@
creation, this should probably be the spawned thread, not the parent.</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. See the <A href="#goto_time">Go To Time</A>
action.</LI>
snapshot. This always applies to <EM>scratch</EM> snapshots produced by emulation, but may
(rarely) apply to recorded events if the stepping schedule between them is somehow known. See
the <A href="#goto_time">Go To Time</A> action for a description of the notation.</LI>
<LI>Description - a user-modifiable description of the snapshot or event. This defaults to
the debugger's description of the event.</LI>
@ -66,43 +61,43 @@
<H3><A name="goto_time"></A>Go To Time</H3>
<P>This action is available when a trace is active. It prompts for a <B>Time Schedule</B>
expression. This is the same form as the expression in the sub-title of the <A href=
<P>This action is available when a trace is active. It prompts for a <EM>time schedule</EM>.
This is the same form as the notation in the sub-title of the <A href=
"help/topics/DebuggerThreadsPlugin/DebuggerThreadsPlugin.html">Threads</A> window. In many
cases, it is simply the snapshot number, e.g., <CODE>3</CODE>, which will go to the snapshot
with key 3. It may optionally include an emulation schedule, for example, <CODE>3:10</CODE>
with key 3. It may optionally include an emulation schedule. For example, <CODE>3:10</CODE>
will use snapshot 3 for an emulator's initial state and step 10 machine instructions on
snapshot 3's event thread. If the snapshot does not give an event thread, then the thread must
be specified in the expression, e.g., <CODE>3:t1-10</CODE>. That expression will start at
snapshot 3, get the thread with key 1, and step it 10 machine instructions. The stepping
commands can be repeated any number of times, separated by semicolons, to step threads in a
specified sequence, e.g., <CODE>3:t1-10;t2-5</CODE> will do the same as before, then get thread
2 and step it 5 times.</P>
specified sequence. For example, <CODE>3:t1-10;t2-5</CODE> will do the same as before, then get
thread 2 and step it 5 times.</P>
<P>The emulator's state can also be modified by the schedule. Instead of specifying a number of
steps, write a <B>Sleigh</B> statement, e.g., <CODE>3:t1-{r0=0x1234};10</CODE>. This will start
at snapshot 3, patch thread 1's r0 to 0x1234, then step 10 instructions. Like stepping
commands, the thread may be omitted for Sleigh commands. Each command without a thread
specified implicitly uses the one from the previous command, or in the case of the first
command, the event thread. Only one Sleigh statement is permitted per command.</P>
<P>The emulator's state can also be patched by the schedule. Instead of specifying the number
of steps, write a <EM>Sleigh</EM> statement, e.g., <CODE>3:t1-{r0=0x1234};10</CODE>. This will
start at snapshot 3, patch thread 1's r0 to 0x1234, then step 10 instructions. As for steps,
the thread key may be omitted for Sleigh commands. Each command without a thread specified
implicitly uses the one from the previous command, or in the case of the first command, the
event thread. Only one Sleigh statement is permitted per command.</P>
<P>A second command sequence may be appended, following a dot, to command the emulator at the
level of p-code operations as well. This is particularly useful when debugging a processor
specification. See also the <A href=
specification. See the <A href=
"help/topics/DebuggerPcodeStepperPlugin/DebuggerPcodeStepperPlugin.html">P-code Stepper</A>
window. For example, <CODE>3:2.10</CODE> will start at snapshot 3 and step the event thread 2
machine instructions then 10 p-code operations. The same thread-by-thread sequencing and state
patching commands are allowed in the p-code command sequence. The <EM>entire</EM> instruction
sequence precedes the entire p-code sequence, i.e., only a single dot is allowed. Once the
expression enters p-code mode, it cannot re-enter instruction mode.</P>
patching commands are allowed in the p-code command sequence. <B>NOTE:</B> the entire
instruction sequence precedes the entire p-code sequence, i.e., only a single dot is allowed.
Once the schedule enters p-code mode, it cannot re-enter instruction mode.</P>
<H3><A name="hide_scratch"></A>Hide Scratch</H3>
<P>This toggle action is always available in the drop-down actions of the Time window. It is
enabled by default. The emulation service, 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 interaction with the target.</P>
writes emulated state into the trace's <EM>scratch space</EM>, 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 interaction with the target.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTimePlugin/images/DebuggerTimePlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

22
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTraceManagerServicePlugin/DebuggerTraceManagerServicePlugin.html
View file

@ -14,10 +14,10 @@
<H1><A name="plugin"></A>Debugger: Trace Management</H1>
<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>
via the <A href="help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Listing</A>
window's tab panel. It maintains a list of open traces, the active trace coordinates (trace,
time, object), and permits saving, opening, and closing traces. To some extent, it also tracks
which traces have live targets.</P>
<H2>Actions</H2>
@ -26,7 +26,7 @@
<H3><A name="open_trace"></A>Open Trace</H3>
<P>This action is always available. It prompts for a trace in the current project and opens
that trace in the tool.</P>
that trace in the Debugger tool.</P>
<H3><A name="save_trace"></A>Save Trace</H3>
@ -37,26 +37,22 @@
<H3><A name="close_trace"></A>Close Trace</H3>
<P>This action is available whenever at least one trace is open and active. It closes the
current trace. <FONT color="red">WARNING:</FONT> If the trace has not been saved, it will be
lost, even when Save by Default is active.</P>
current trace.</P>
<H3><A name="close_all_traces"></A>Close All Traces</H3>
<P>This action is available whenever at least one trace is open. It closes all traces in this
tool. <FONT color="red">WARNING:</FONT> Any trace that has not been saved will be lost, even
when Save by Default is active.</P>
tool.</P>
<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. 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>
closes all traces in this tool, except the active trace.</P>
<H3><A name="close_dead_traces"></A>Close Dead Traces</H3>
<P>This action is available whenever at least one trace is open. It closes all dead traces in
this tool. <FONT color="red">WARNING:</FONT> Any closed trace that has not been saved will be
lost, even when Save by Default is active.</P>
this tool.</P>
<H3><A name="save_by_default"></A>Save by Default</H3>

53
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTraceViewDiffPlugin/DebuggerTraceViewDiffPlugin.html
View file

@ -13,27 +13,21 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Comparing Times</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerTraceViewDiffPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerTraceViewDiffPlugin.png">
</DIV>
<P><A name="Toggle_Header"></A>A common strategy in dynamic analysis is to compare machine
state between two points in time. To this end, to support comparison of bytes in memory, the
"trace diff" plugin extends the <A href=
state between two points in time. To this end, the "trace diff" plugin extends the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html">Dynamic Listing</A> to provide
side-by-side comparison of two different points in time. When active, listings for both points
in time are displayed and the byte value differences between them are highlighted. <B>NOTE:</B>
This does not compare annotations. It only compares raw byte values. Additionally, all stale
values are ignored, i.e., to show as a difference, the memory must be observed at <EM>both</EM>
points in time, and the values must differ.</P>
side-by-side comparison of bytes between points in time. When active, listings for both times
are displayed, and the byte value differences between them are highlighted. <B>NOTE:</B> This
does not compare annotations. It only compares raw byte values. Additionally, all stale values
are ignored, i.e., to show as a difference, the memory must be observed at <EM>both</EM> points
in time, and the values must differ.</P>
<P><B>NOTE:</B> This plugin only facilitates the comparison of memory displayed in listings. To
compare registers or SLEIGH expressions, use the respective windows: <A href=
compare registers or expressions, use the respective windows: <A href=
"help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A> and <A href=
"help/topics/DebuggerWatchesPlugin/DebuggerWatchesPlugin.html">Watches</A>. By navigating back
and forth between two points in time, using the <A href=
@ -50,14 +44,9 @@
<P>This action is available whenever a trace is active in the main listing. It prompts for an
alternative point in time:</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" src=
"images/DebuggerTimeSelectionDialog.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerTimeSelectionDialog.png">
</DIV>
<P>The snapshot table is exactly the same as that in the <A href=
"help/topics/DebuggerTimePlugin/DebuggerTimePlugin.html">Time Window</A>. In most cases, simply
@ -68,11 +57,11 @@
snapshots thus identifies changes over time; however, there is no guarantee that the desired
variable was ever observed. Assuming the general vicinity of the variable is known, e.g.,
"somewhere in the .data section," the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#read_memory">Read Selected
Memory</A> action can ensure its value is recorded. Of course, it can also read "all memory,"
but that operation and the follow-on comparison could take time. In general, the procedure to
locate a variable is to capture a baseline, execute the target until the variable has changed,
capture again, then compare:</P>
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#read_memory">Read Memory</A>
action can ensure its value is recorded. Of course, it can also read "all memory," but that
operation and the follow-on comparison could take time. In general, the procedure to locate a
variable is to capture a baseline, execute the target until the variable has changed, capture
again, then compare:</P>
<OL>
<LI>Execute the target up to a baseline, and take note of the variable's value, as displayed
@ -88,8 +77,8 @@
selection.</LI>
<LI>Use the <A href=
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#read_memory">Read Selected
Memory</A> action to ensure the variable's value is stored in the trace.</LI>
"help/topics/DebuggerListingPlugin/DebuggerListingPlugin.html#read_memory">Read Memory</A>
action to ensure the variable's value is stored in the trace.</LI>
<LI>Allow the target to execute until the variable has changed. Ideally, execute as little as
necessary, so that few or no other variables change.</LI>
@ -134,7 +123,7 @@
<P>Alternatively, if the number of steps to reach the end of the block is already known, just
use the emulation expression in the <B>Compare</B> action's dialog. <B>NOTE:</B> When used this
way, the baseline snapshot will be in the left pane, and the emulated snapshot in the right,
which is opposite the result from the steps above.</P>
which is opposite the result from the previous procedure.</P>
<P>In either case, this will highlight any memory that was modified by the emulated code. Of
course, this could also be accomplished by setting a second breakpoint and allowing the target

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTraceViewDiffPlugin/images/DebuggerTimeSelectionDialog.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 19 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerTraceViewDiffPlugin/images/DebuggerTraceViewDiffPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 45 KiB

36
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerWatchesPlugin/DebuggerWatchesPlugin.html
View file

@ -13,14 +13,9 @@
<BODY lang="EN-US">
<H1><A name="plugin"></A>Debugger: Watches</H1>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/DebuggerWatchesPlugin.png"></TD>
</TR>
</TBODY>
</TABLE>
<DIV class="image">
<IMG alt="" src="images/DebuggerWatchesPlugin.png">
</DIV>
<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
@ -32,15 +27,15 @@
<P>The watch window uses colors to hint about changes in and freshness of displayed values. By
default, changed values are displayed in red, and stale values are displayed in dark grey. A
"stale" value is one which depends on any register or memory whose contents are not known. The
value displayed is that computed from the last recorded contents, defaulting to 0 when never
recorded. Simply, a "changed" watch is one whose value has just changed. For example, if a
value changes as result of stepping, then that watch is changed. However, given the possibility
of rewinding, changing thread focus, etc., "changed" is actually subtly more flexible. The
watch remembers the evaluation from the user's last coordinates (time, thread, frame, etc.) as
well as the current coordinates. So, "changed" more precisely refers to a watch whose value
differs between those two coordinates. This permits the user to switch focus between different
coordinates and quickly identify what is different.</P>
<EM>stale</EM> value is one which depends on any register or memory whose contents are not
known. The value displayed is that computed from the last recorded contents, defaulting to 0
when never recorded. A <EM>changed</EM> watch is one whose value has just changed. For example,
if a value changes as result of stepping, then that watch is changed. However, given the
possibility of rewinding, changing thread focus, etc., "changed" is actually subtly more
flexible. The watch remembers the evaluation from the user's last coordinates (time, thread,
frame, etc.) as well as the current coordinates. So, "changed" more precisely refers to a watch
whose value differs between those two coordinates. This permits the user to switch focus
between different coordinates and quickly identify what is different.</P>
<H2>Examples</H2>
@ -95,8 +90,8 @@
rendered in <FONT color="red">red</FONT>.</LI>
<LI>Type - the user-modifiable type of the watch. Note the type is not marked up in the
trace. Clicking the Apply Data Type action will apply it to the current trace, if
possible.</LI>
trace. Clicking the <A href="#apply_data_type">Apply Data Type</A> action will apply it to
the current trace, if possible.</LI>
<LI>Representation - the value of the watch as interpreted by the selected data type. If the
value is an address, i.e., Type is a pointer, then double-clicking this cell will navigate
@ -172,7 +167,6 @@
<P>This toggle is a write protector for machine state. To modify a watch's value, this toggle
must be enabled. Edits are directed according the to <A href=
"help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html">Control and Machine State
Plugin</A>. <B>Note:</B> Only the raw "Value" column can be edited directly. The "Repr" column
cannot be edited, yet.</P>
Plugin</A>.</P>
</BODY>
</HTML>

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/DebuggerWatchesPlugin/images/DebuggerWatchesPlugin.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

47
Ghidra/Debug/Debugger/src/main/help/help/topics/VariableValueHoverPlugin/VariableValueHoverPlugin.html
View file

@ -27,7 +27,7 @@
functions to follow certain conventions. Thus, it's very easy to break and may frequently be
incorrect. For hovers that include a <B>Frame</B> row, the displayed value depends on an
accurately unwound stack. Take the value with a grain of salt, especially if the hover also
includes a <B>Warnings:</B> row. To diagnose the unwound stack, use the <A href=
includes a <B>Warnings</B> row. To diagnose the unwound stack, use the <A href=
"help/topics/DebuggerStackPlugin/DebuggerStackPlugin.html#unwind_stack">Unwind Stack</A>
action.</P>
@ -72,18 +72,11 @@
<H2>Examples</H2>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/VariableValueHoverPluginListing.png"></TD>
</TR>
<DIV class="image">
<IMG alt="" src="images/VariableValueHoverPluginListing.png">
<TR>
<TD align="center">A register operand in the Dynamic Listing</TD>
</TR>
</TBODY>
</TABLE>
<P>A register operand in the Dynamic Listing</P>
</DIV>
<P>When hovering over operands in the Dynamic Listing, that operand is most likely a register.
The register's value is displayed without regard to the stack frame. It will always use the
@ -94,18 +87,11 @@
window, and so the service cannot interpret the value except as an integer. Register values are
never displayed as raw byte arrays.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/VariableValueHoverPluginBrowser.png"></TD>
</TR>
<DIV class="image">
<IMG alt="" src="images/VariableValueHoverPluginBrowser.png">
<TR>
<TD align="center">A stack variable in the Static Listing</TD>
</TR>
</TBODY>
</TABLE>
<P>A stack variable in the Static Listing</P>
</DIV>
<P>When hovering over operands in the Static Listing, the service will gather context about the
operand and find a frame for the relevant function. It will take the first appropriate frame it
@ -120,18 +106,11 @@
computes the integer value <CODE>1</CODE>. It also interprets the value using the assigned data
type, giving <CODE>1h</CODE>.</P>
<TABLE width="100%">
<TBODY>
<TR>
<TD align="center" width="100%"><IMG alt="" border="1" src=
"images/VariableValueHoverPluginDecompiler.png"></TD>
</TR>
<DIV class="image">
<IMG alt="" src="images/VariableValueHoverPluginDecompiler.png">
<TR>
<TD align="center">A stack variable in the Decompiler</TD>
</TR>
</TBODY>
</TABLE>
<P>A stack variable in the Decompiler</P>
</DIV>
<P>When hovering over variables in the Decompiler, the service behaves similarly to how it does
for operands in the Static Listing. It locates the appropriate frame and attempts to derive the

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/VariableValueHoverPlugin/images/VariableValueHoverPluginBrowser.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 62 KiB

After

Width:  |  Height:  |  Size: 61 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/VariableValueHoverPlugin/images/VariableValueHoverPluginDecompiler.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 31 KiB

BIN
Ghidra/Debug/Debugger/src/main/help/help/topics/VariableValueHoverPlugin/images/VariableValueHoverPluginListing.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 54 KiB

6
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/DebuggerResources.java
View file

@ -119,7 +119,7 @@ public interface DebuggerResources {
Icon ICON_STACK = new GIcon("icon.debugger.provider.stack");
Icon ICON_BREAKPOINTS = new GIcon("icon.debugger.provider.breakpoints");
Icon ICON_MODULES = new GIcon("icon.debugger.provider.modules");
Icon ICON_MAPPINGS = ICON_PROGRAM; // TODO: A better icon
Icon ICON_MAPPINGS = new GIcon("icon.debugger.provider.mappings"); // TODO: A better icon
Icon ICON_PCODE = new GIcon("icon.debugger.provider.pcode"); // TODO
Icon ICON_REGIONS = new GIcon("icon.debugger.provider.regions");
Icon ICON_TIME = new GIcon("icon.debugger.provider.time");
@ -132,7 +132,7 @@ public interface DebuggerResources {
Icon ICON_DELETE = new GIcon("icon.debugger.delete");
Icon ICON_CLEAR = new GIcon("icon.debugger.clear");
Icon ICON_REFRESH = new GIcon("icon.debugger.refresh");
Icon ICON_FILTER = new GIcon("icon.debugger.filter"); // Eww.
Icon ICON_FILTER = new GIcon("icon.debugger.filter");
Icon ICON_SELECT_ROWS = new GIcon("icon.debugger.select.rows");
Icon ICON_AUTOREAD = new GIcon("icon.debugger.autoread");
@ -149,6 +149,8 @@ public interface DebuggerResources {
Icon ICON_MAP_MODULES = new GIcon("icon.debugger.map.modules");
Icon ICON_MAP_SECTIONS = new GIcon("icon.debugger.map.sections"); // TODO
Icon ICON_MAP_REGIONS = new GIcon("icon.debugger.map.regions"); // TODO
Icon ICON_MAP_AUTO = new GIcon("icon.debugger.map.auto");
Icon ICON_MAP_MANUALLY = new GIcon("icon.debugger.map.manual");
Icon ICON_BLOCK = new GIcon("icon.debugger.block"); // TODO
// TODO: Draw an icon
Icon ICON_SELECT_ADDRESSES = new GIcon("icon.debugger.select.addresses");

35
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/breakpoint/DebuggerBreakpointsProvider.java
View file

@ -155,34 +155,36 @@ public class DebuggerBreakpointsProvider extends ComponentProviderAdapter
protected enum BreakpointLocationTableColumns
implements EnumeratedTableColumn<BreakpointLocationTableColumns, BreakpointLocationRow> {
STATE("State", State.class, BreakpointLocationRow::getState, BreakpointLocationRow::setState, true),
NAME("Name", String.class, BreakpointLocationRow::getName, BreakpointLocationRow::setName, true),
ADDRESS("Address", Address.class, BreakpointLocationRow::getAddress, true),
TRACE("Trace", String.class, BreakpointLocationRow::getTraceName, true),
THREADS("Threads", String.class, BreakpointLocationRow::getThreads, true),
COMMENT("Comment", String.class, BreakpointLocationRow::getComment, BreakpointLocationRow::setComment, true),
SLEIGH("Sleigh", Boolean.class, BreakpointLocationRow::hasSleigh, true);
STATE("State", State.class, BreakpointLocationRow::getState, BreakpointLocationRow::setState, true, true),
NAME("Name", String.class, BreakpointLocationRow::getName, BreakpointLocationRow::setName, true, true),
ADDRESS("Address", Address.class, BreakpointLocationRow::getAddress, true, true),
TRACE("Trace", String.class, BreakpointLocationRow::getTraceName, true, true),
THREADS("Threads", String.class, BreakpointLocationRow::getThreads, true, false),
COMMENT("Comment", String.class, BreakpointLocationRow::getComment, BreakpointLocationRow::setComment, true, true),
SLEIGH("Sleigh", Boolean.class, BreakpointLocationRow::hasSleigh, true, true);
private final String header;
private final Function<BreakpointLocationRow, ?> getter;
private final BiConsumer<BreakpointLocationRow, Object> setter;
private final boolean sortable;
private final boolean visible;
private final Class<?> cls;
<T> BreakpointLocationTableColumns(String header, Class<T> cls,
Function<BreakpointLocationRow, T> getter, boolean sortable) {
this(header, cls, getter, null, sortable);
Function<BreakpointLocationRow, T> getter, boolean sortable, boolean visible) {
this(header, cls, getter, null, sortable, visible);
}
@SuppressWarnings("unchecked")
<T> BreakpointLocationTableColumns(String header, Class<T> cls,
Function<BreakpointLocationRow, T> getter,
BiConsumer<BreakpointLocationRow, T> setter, boolean sortable) {
BiConsumer<BreakpointLocationRow, T> setter, boolean sortable, boolean visible) {
this.header = header;
this.cls = cls;
this.getter = getter;
this.setter = (BiConsumer<BreakpointLocationRow, Object>) setter;
this.sortable = sortable;
this.visible = visible;
}
@Override
@ -210,6 +212,11 @@ public class DebuggerBreakpointsProvider extends ComponentProviderAdapter
return sortable;
}
@Override
public boolean isVisible() {
return visible;
}
@Override
public void setValueOf(BreakpointLocationRow row, Object value) {
setter.accept(row, value);
@ -1076,8 +1083,8 @@ public class DebuggerBreakpointsProvider extends ComponentProviderAdapter
locsCol.setPreferredWidth(20);
TableColumn bptSleighCol =
bptColModel.getColumn(LogicalBreakpointTableColumns.SLEIGH.ordinal());
bptSleighCol.setMaxWidth(24);
bptSleighCol.setMinWidth(24);
bptSleighCol.setMaxWidth(30);
bptSleighCol.setMinWidth(30);
GTableColumnModel locColModel = (GTableColumnModel) locationTable.getColumnModel();
TableColumn locEnCol =
@ -1098,8 +1105,8 @@ public class DebuggerBreakpointsProvider extends ComponentProviderAdapter
locColModel.getColumn(BreakpointLocationTableColumns.THREADS.ordinal());
TableColumn locSleighCol =
locColModel.getColumn(BreakpointLocationTableColumns.SLEIGH.ordinal());
locSleighCol.setMaxWidth(24);
locSleighCol.setMinWidth(24);
locSleighCol.setMaxWidth(30);
locSleighCol.setMinWidth(30);
locColModel.setVisible(locThreadsCol, false);
locColModel.setVisible(locSleighCol, false);

10
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/model/ModelQuery.java
View file

@ -145,9 +145,13 @@ public class ModelQuery {
public Stream<AttributeSchema> computeAttributes(Trace trace) {
TargetObjectSchema schema = computeSingleSchema(trace);
return schema.getAttributeSchemas()
.values()
.entrySet()
.stream()
.filter(as -> !"".equals(as.getName()));
.filter(ent -> {
String attrName = ent.getValue().getName();
return !"".equals(attrName) && ent.getKey().equals(attrName);
})
.map(e -> e.getValue());
}
protected static boolean includes(Lifespan span, PathPattern pattern, TraceObjectValue value) {
@ -221,6 +225,8 @@ public class ModelQuery {
/**
* Determine whether the query results could depend on the given value
*
* @param span the lifespan of interest, e.g., the span being displayed
* @param value the value that has changed
* @return true if the query results depend on the given value
*/
public boolean involves(Lifespan span, TraceObjectValue value) {

5
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/model/columns/AbstractTraceValueObjectAddressColumn.java
View file

@ -42,6 +42,11 @@ public abstract class AbstractTraceValueObjectAddressColumn
}
return fromRange(range);
}
@Override
public boolean isModified() {
return row.isAttributeModified(attributeName);
}
};
}
}

5
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/model/columns/AbstractTraceValueObjectLengthColumn.java
View file

@ -58,6 +58,11 @@ public abstract class AbstractTraceValueObjectLengthColumn
: ("<html><body style='font-family:monospaced'>0x" +
Long.toUnsignedString(value, 16));
}
@Override
public boolean isModified() {
return row.isAttributeModified(attributeName);
}
};
}
}

7
Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/model/columns/TraceValueObjectPropertyColumn.java
View file

@ -82,7 +82,6 @@ public abstract class TraceValueObjectPropertyColumn<T>
public class BooleanPropertyRenderer extends PropertyRenderer {
protected GCheckBox cb;
{
setLayout(new BorderLayout());
cb = new GCheckBox();
cb.setHorizontalAlignment(CENTER);
cb.setOpaque(false);
@ -103,14 +102,14 @@ public abstract class TraceValueObjectPropertyColumn<T>
else {
cb.setVisible(false);
}
setVisible(true);
invalidate();
return this;
}
@Override
public void validate() {
synchronized (getTreeLock()) {
validateTree();
}
cb.setBounds(0, 0, getWidth(), getHeight());
}
}

Some files were not shown because too many files have changed in this diff Show more