GP-6174: docs

GP-6174: host->device GP-6174: bug fixes GP-6174: extra commands GP-6174: first pass
2026-01-09 14:08:03 -05:00 · 2025-12-02 12:19:30 -05:00
parent 14ead1aabc
commit d278340d56
7 changed files with 213 additions and 7 deletions
--- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb-attach.ps1
+++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb-attach.ps1
@@ -0,0 +1,48 @@
+## ###
+# 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.
+##
+#@title lldb Android (Attach)
+#@image-opt arg:1
+#@desc <html><body width="300px">
+#@desc   <h3>Launch with local <tt>lldb</tt> and attach to an Android target.</h3>
+#@desc   <p>
+#@desc     This will start <tt>lldb</tt> on the local system and then use it to connect to the remote system.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
+#@desc </body></html>
+#@menu-group lldb
+#@icon icon.debugger
+#@help lldb#android-attach
+#@depends Debugger-rmi-trace
+#@env OPT_TARGET_PID:int=0 "Process id" "The target process id"
+#@env OPT_DEVICE:str="" "Device" "The device name (e.g. from 'adb devices')"
+#@env OPT_PORT:str="9999" "Port" "The host's listening port"
+#@env OPT_ARCH:str="" "Architecture" "Target architecture override"
+#@env OPT_LLDB_PATH:file="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH."
+#@env OPT_EXTRA_CMDS:str="" "Additional commands" "Follow-up lldb commands."
+
+. ..\support\lldbsetuputils.ps1
+
+$pypathTrace = Ghidra-Module-PyPath "Debugger-rmi-trace"
+$pypathLldb = Ghidra-Module-PyPath
+$Env:PYTHONPATH = "$pypathLldb;$pypathTrace;$Env:PYTHONPATH"
+
+$arglist = Compute-Lldb-Platform-Args-Attach `
+    -TargetPid "$Env:OPT_TARGET_PID" `
+    -TargetType "remote-android" `
+    -TargetUrl "connect://$Env:OPT_DEVICE`:$Env:OPT_PORT" `
+    -RmiAddress "$Env:GHIDRA_TRACE_RMI_ADDR"
+
+Start-Process -FilePath $arglist[0] -ArgumentList $arglist[1..$arglist.Count] -NoNewWindow -Wait
--- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb-attach.sh
+++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb-attach.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+## ###
+# 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.
+##
+#@title lldb Android (Attach)
+#@image-opt arg:1
+#@desc <html><body width="300px">
+#@desc   <h3>Launch with local <tt>lldb</tt> and attach to an Android target.</h3>
+#@desc   <p>
+#@desc     This will start <tt>lldb</tt> on the local system and then use it to connect to the remote system.
+#@desc     For setup instructions, press <b>F1</b>.
+#@desc   </p>
+#@desc </body></html>
+#@menu-group lldb
+#@icon icon.debugger
+#@help lldb#android-attach
+#@depends Debugger-rmi-trace
+#@env OPT_TARGET_PID:int=0 "Process id" "The target process id"
+#@env OPT_DEVICE:str="" "Device" "The device name (e.g. from 'adb devices')"
+#@env OPT_PORT:str="9999" "Port" "The host's listening port"
+#@env OPT_ARCH:str="" "Architecture" "Target architecture override"
+#@env OPT_LLDB_PATH:file="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH."
+#@env OPT_EXTRA_CMDS:str="" "Additional commands" "Follow-up lldb commands."
+
+. ../support/lldbsetuputils.sh
+
+pypathTrace=$(ghidra-module-pypath "Debugger-rmi-trace")
+pypathLldb=$(ghidra-module-pypath)
+export PYTHONPATH=$pypathLldb:$pypathTrace:$PYTHONPATH
+
+function launch-lldb() {
+	local -a args
+	compute-lldb-platform-args-attach "$OPT_TARGET_PID" remote-android "connect://$OPT_DEVICE:$OPT_PORT" "$GHIDRA_TRACE_RMI_ADDR" "$@"
+
+	"${args[@]}"
+}
+launch-lldb "$@"
--- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.ps1
+++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.ps1
@@ -29,7 +29,7 @@
 #@enum StartCmd:str "process launch" "process launch --stop-at-entry"
 #@arg :file "Image" "The target binary executable image"
 #@env OPT_TARGET_ARGS:str="" "Arguments" "Command-line arguments to pass to the target"
-#@env OPT_HOST:str="localhost" "Host" "The hostname of the target"
+#@env OPT_DEVICE:str="" "Device" "The device name (e.g. from 'adb devices')"
 #@env OPT_PORT:str="9999" "Port" "The host's listening port"
 #@env OPT_ARCH:str="" "Architecture" "Target architecture override"
 #@env OPT_LLDB_PATH:file="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH."
@@ -44,7 +44,7 @@ $Env:PYTHONPATH = "$pypathLldb;$pypathTrace;$Env:PYTHONPATH"
 $arglist = Compute-Lldb-Platform-Args `
    -TargetImage $args[0] `
    -TargetType "remote-android" `
-    -TargetUrl "connect://$Env:OPT_HOST`:$Env:OPT_PORT" `
+    -TargetUrl "connect://$Env:OPT_DEVICE`:$Env:OPT_PORT" `
    -RmiAddress "$Env:GHIDRA_TRACE_RMI_ADDR"

 Start-Process -FilePath $arglist[0] -ArgumentList $arglist[1..$arglist.Count] -NoNewWindow -Wait
--- a/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.sh
+++ b/Ghidra/Debug/Debugger-agent-lldb/data/debugger-launchers/android-lldb.sh
@@ -30,7 +30,7 @@
 #@enum StartCmd:str "process launch" "process launch --stop-at-entry"
 #@arg :file "Image" "The target binary executable image"
 #@args "Arguments" "Command-line arguments to pass to the target"
-#@env OPT_HOST:str="localhost" "Host" "The hostname of the target"
+#@env OPT_DEVICE:str="" "Device" "The device name (e.g. from 'adb devices')"
 #@env OPT_PORT:str="9999" "Port" "The host's listening port"
 #@env OPT_ARCH:str="" "Architecture" "Target architecture override"
 #@env OPT_LLDB_PATH:file="lldb" "lldb command" "The path to lldb on the local system. Omit the full path to resolve using the system PATH."
@@ -48,7 +48,7 @@ target_args="$@"

 function launch-lldb() {
 	local -a args
-	compute-lldb-platform-args "$target_image" remote-android "connect://$OPT_HOST:$OPT_PORT" "$GHIDRA_TRACE_RMI_ADDR" "$@"
+	compute-lldb-platform-args "$target_image" remote-android "connect://$OPT_DEVICE:$OPT_PORT" "$GHIDRA_TRACE_RMI_ADDR" "$@"

 	"${args[@]}"
 }
--- a/Ghidra/Debug/Debugger-agent-lldb/data/support/lldbsetuputils.ps1
+++ b/Ghidra/Debug/Debugger-agent-lldb/data/support/lldbsetuputils.ps1
@@ -44,6 +44,19 @@ function Add-Lldb-Image-And-Args {
 	}
 }

+function Add-Lldb-Pid {
+	param([ref]$ArgList, $TargetPid)
+
+	if ("$TargetPid" -ne "") {
+		$ArgList.Value+=("-o", "`"process attach --pid '$TargetPid'`"")
+	}
+	if ("$TargetArgs" -ne "") {
+		$tgtargs = $TargetArgs -replace "`"", "\`""
+		# Escaping parentheses in the arguments is no longer necessary in powershell vs cmd
+		$ArgList.Value+=("-o", "`"settings set target.run-args $tgtargs`"")
+	}
+}
+
 function Add-Lldb-Connect-And-Sync {
 	param([ref]$ArgList, $Address)

@@ -60,6 +73,14 @@ function Add-Lldb-Start-If-Image {
 	}
 }

+function Add-Lldb-Extra-Cmds {
+	param([ref]$ArgList)
+
+	if ("$Env:OPT_EXTRA_CMDS" -ne "") {
+		$ArgList.Value+=("-o", "`"$Env:OPT_EXTRA_CMDS`"")
+	}
+}
+
 function Add-Lldb-Tail-Args {
 	param([ref]$ArgList)
 	# NOP
@@ -93,12 +114,27 @@ function Compute-Lldb-Platform-Args {
 	return $arglist
 }

+function Compute-Lldb-Platform-Args-Attach {
+	param($TargetPid, $TargetType, $TargetUrl, $RmiAddress)
+
+	$arglist = @("`"$Env:OPT_LLDB_PATH`"")
+	Add-Lldb-Init-Args -ArgList ([ref]$arglist)
+	$arglist+=("-o", "`"platform select '$TargetType'`"")
+	$arglist+=("-o", "`"platform connect '$TargetUrl'`"")
+	Add-Lldb-Pid -ArgList ([ref]$arglist) -TargetPid $TargetPid -TargetArgs $Env:OPT_TARGET_ARGS
+	Add-Lldb-Connect-And-Sync -ArgList ([ref]$arglist) -Address $RmiAddress
+	Add-Lldb-Extra-Cmds -ArgList ([ref]$arglist)
+	Add-Lldb-Tail-Args -ArgList ([ref]$arglist)
+
+	return $arglist
+}
+
 function Compute-Lldb-Remote-Args {
 	param($TargetImage, $TargetCx, $RmiAddress)

 	$arglist = @("`"$Env:OPT_LLDB_PATH`"")
 	Add-Lldb-Init-Args -ArgList ([ref]$arglist)
-	Add-Lldb-Image-And-Args -ArgList ([ref]$arglist) -TargetImge $TargetImage -TargetArgs ""
+	Add-Lldb-Image-And-Args -ArgList ([ref]$arglist) -TargetImage $TargetImage -TargetArgs ""
 	$arglist+=("-o", "`"$TargetCx`"")
 	Add-Lldb-Connect-And-Sync -ArgList ([ref]$arglist) -Address $RmiAddress
 	$arglist+=("-o", "`"ghidra trace sync-synth-stopped`"")
@@ -107,6 +143,21 @@ function Compute-Lldb-Remote-Args {
 	return $arglist
 }

+function Compute-Lldb-Remote-Args-Attach {
+	param($TargetPid, $TargetCx, $RmiAddress)
+
+	$arglist = @("`"$Env:OPT_LLDB_PATH`"")
+	Add-Lldb-Init-Args -ArgList ([ref]$arglist)
+	Add-Lldb-Pid -ArgList ([ref]$arglist) -TargetPid $TargetPid 
+	$arglist+=("-o", "`"$TargetCx`"")
+	Add-Lldb-Connect-And-Sync -ArgList ([ref]$arglist) -Address $RmiAddress
+	$arglist+=("-o", "`"ghidra trace sync-synth-stopped`"")
+	Add-Lldb-Extra-Cmds -ArgList ([ref]$arglist)
+	Add-Lldb-Tail-Args -ArgList ([ref]$arglist)
+
+	return $arglist
+}
+
 function Compute-Lldb-PipInstall-Args {
 	$argvpart = $args -join ", "
 	$arglist = @("`"$Env:OPT_LLDB_PATH`"")
--- a/Ghidra/Debug/Debugger-agent-lldb/data/support/lldbsetuputils.sh
+++ b/Ghidra/Debug/Debugger-agent-lldb/data/support/lldbsetuputils.sh
@@ -43,6 +43,15 @@ add-lldb-image-and-args() {
 	fi
 }

+add-lldb-pid() {
+	target_pid=$1
+	shift
+
+	if [ -n "$target_pid" ]; then
+		args+=(-o "process attach --pid '$target_pid'")
+	fi
+}
+
 add-lldb-io-tty() {
 	if [ -n "$TTY_TARGET" ]; then
 		args+=(-o "settings set target.output-path '$TTY_TARGET'")
@@ -66,6 +75,12 @@ add-lldb-start-if-image() {
 	fi
 }

+add-lldb-extra-cmds() {
+	if [ -n "$OPT_EXTRA_CMDS" ]; then
+		args+=(-o "$OPT_EXTRA_CMDS")
+	fi
+}
+
 add-lldb-tail-args() {
 	true
 }
@@ -105,6 +120,26 @@ compute-lldb-platform-args() {
 	add-lldb-tail-args
 }

+compute-lldb-platform-args-attach() {
+	target_pid=$1
+	target_type=$2
+	target_url=$3
+	rmi_address=$4
+	shift
+	shift
+	shift
+	shift
+
+	args+=("$OPT_LLDB_PATH")
+	add-lldb-init-args
+	args+=(-o "platform select '$target_type'")
+	args+=(-o "platform connect '$target_url'")
+	add-lldb-pid "$target_pid"
+	add-lldb-connect-and-sync "$rmi_address"
+	add-lldb-extra-cmds
+	add-lldb-tail-args
+}
+
 compute-lldb-remote-args() {
 	target_image=$1
 	target_cx=$2
@@ -119,6 +154,21 @@ compute-lldb-remote-args() {
 	add-lldb-tail-args
 }

+compute-lldb-remote-args-attach() {
+	target_pid=$1
+	target_cx=$2
+	rmi_address=$3
+
+	args+=("$OPT_LLDB_PATH")
+	add-lldb-init-args
+	add-lldb-pid "$target_pid" ""
+	args+=(-o "$target_cx")
+	add-lldb-connect-and-sync "$rmi_address"
+	args+=(-o "ghidra trace sync-synth-stopped")
+	add-lldb-extra-cmds
+	add-lldb-tail-args
+}
+
 compute-lldb-pipinstall-args() {
 	local argvpart
 	printf -v argvpart ", %s" "$@"
--- a/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/topics/lldb/lldb.html
+++ b/Ghidra/Debug/Debugger-agent-lldb/src/main/help/help/topics/lldb/lldb.html
@@ -206,8 +206,8 @@ perl -i -pe 's/(?&lt;=pendingNMI\x00{4})\x00/\x01/' macOS_15-1234567.vmss
    <H2><A name="android"></A>Android</H2>

    <P>This has the same options as the <A href="#ssh">LLDB via SSH</A> launcher, which are
-    necessary for connecting to the Android debugger, but executes via the normal lldb
-    mechanism.</P>
+    necessary for connecting to the Android debugger, but uses <B>Device</B> in place of <B>Host</B>
+    (typically retrieved using 'adb devices').</P>

    <H3><A name="setup_ndk"></A>Setup for Android NDK</H3>

@@ -266,5 +266,13 @@ PS&gt; C:\path\to\android-ndk\...\python -m pip install ...
        ...</TT>.
      </LI>
    </OL>
+    
+    <H2><A name="android-attach"></A>Android (Attach)</H2>
+
+    <P>This has the same options as the <A href="#android">Andoid</A> launcher, but uses the 
+    target's <B>Process Id</B> instead of the executable <B>Image</B>.  <B>Additional commands</B> has been added 
+    to allow commands like 'process handle --pass true --stop false --notify false SIGSEGV'
+    to be saved and executed for each run.</P>
+
  </BODY>
 </HTML>