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

NationalSecurityAgency · Apr 15, 2024 · 636dc6f · 636dc6f
2 parents 4e6e847 + c634283
commit 636dc6f
Show file tree

Hide file tree

Showing 134 changed files with 3,231 additions and 1,567 deletions.
diff --git a/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-ttd.bat b/Ghidra/Debug/Debugger-agent-dbgeng/data/debugger-launchers/local-ttd.bat
@@ -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"

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/local-gdb.sh
@@ -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
 

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/qemu-gdb.sh
@@ -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

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/raw-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/raw-gdb.sh
@@ -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"
 

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/remote-gdb.sh
@@ -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. 

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdb.sh
@@ -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"

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/ssh-gdbserver.sh
@@ -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"

diff --git a/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh b/Ghidra/Debug/Debugger-agent-gdb/data/debugger-launchers/wine-gdb.sh
@@ -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."

diff --git a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/remote-lldb.sh
@@ -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"

diff --git a/Ghidra/Debug/Debugger-rmi-trace/build.gradle b/Ghidra/Debug/Debugger-rmi-trace/build.gradle
@@ -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"

diff --git a/Ghidra/Debug/Debugger-rmi-trace/certification.manifest b/Ghidra/Debug/Debugger-rmi-trace/certification.manifest
@@ -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|

diff --git a/Ghidra/Debug/Debugger-rmi-trace/data/debugger-launchers/raw-python3.sh b/Ghidra/Debug/Debugger-rmi-trace/data/debugger-launchers/raw-python3.sh
@@ -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"

diff --git a/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml b/Ghidra/Debug/Debugger-rmi-trace/src/main/help/help/TOC_Source.xml
@@ -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>
diff --git a/...ain/help/help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionManagerPlugin.html b/...ain/help/help/topics/TraceRmiConnectionManagerPlugin/TraceRmiConnectionManagerPlugin.html
@@ -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>
diff --git a/.../main/help/help/topics/TraceRmiConnectionManagerPlugin/images/ConnectDialog.png b/.../main/help/help/topics/TraceRmiConnectionManagerPlugin/images/ConnectDialog.png
diff --git a/...pics/TraceRmiConnectionManagerPlugin/images/TraceRmiConnectionManagerPlugin.png b/...pics/TraceRmiConnectionManagerPlugin/images/TraceRmiConnectionManagerPlugin.png