GP-2495: Add documentation and curate other script.

Ghidra/Debug/Debugger-agent-gdb/certification.manifest

@@ -1,4 +1,6 @@
 ##VERSION: 2.0
 ##MODULE IP: JSch License
 Module.manifest||GHIDRA||||END|
-data/scripts/define_info_proc_mappings||GHIDRA||||END|
+data/scripts/fallback_info_proc_mappings.gdb||GHIDRA||||END|
+data/scripts/getpid-linux-i386.gdb||GHIDRA||||END|
+data/scripts/wine32_info_proc_mappings.gdb||GHIDRA||||END|

Ghidra/Debug/Debugger-agent-gdb/data/scripts/define_info_proc_mappings

@@ -1,4 +0,0 @@
-define info proc mappings
-echo 0x0 0x7FFFFFFFFFFFFFFF 0x8000000000000000 0x0 lomem \n
-echo 0x8000000000000000 0xFFFFFFFFFFFFFFFF 0x8000000000000000 0x0 himem
-end

Ghidra/Debug/Debugger-agent-gdb/data/scripts/fallback_info_proc_mappings.gdb

@@ -0,0 +1,26 @@
+# Override the "info proc mappings" command in GDB to report the full 64-bit address space
+#
+# This presents the space in two regions, low and high, to avoid signedness bugs in Ghidra.
+#
+# To use:
+#  1. Consider the actual memory size of your target and copy and/or adjust this script
+#  2. Connect Ghidra to GDB on Linux
+#  3. From the interpreter, run:
+#
+#        source fallback_info_proc_mappings.gdb
+#
+#     Note that you may need to provide the full path to the script
+#
+# You can now launch or connect to your target in the usual way. This may cause Ghidra to display
+# more memory than is actually present on the target. As a result, randomly scrolling in the
+# dynamic listing may cause several erroneous reads, which may in turn may cause the target and/or
+# GDB to crash. Use with caution. The more accurate your memory map, the safer.
+#
+# Note that the connection should only be used with the target for which this script was tailored.
+# Re-using the connection for another target may result in sub-optimal performance and/or undefined
+# behavior.
+
+define info proc mappings
+echo 0x0 0x7FFFFFFFFFFFFFFF 0x8000000000000000 0x0 lomem \n
+echo 0x8000000000000000 0xFFFFFFFFFFFFFFFF 0x8000000000000000 0x0 himem
+end

Ghidra/Debug/Debugger-agent-gdb/data/scripts/remote-proc-mappings.py

@@ -1,3 +1,18 @@
+## ###
+#  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.
+##
 # A GDB command for fetching /proc/{pid}/maps from a remote gdbserver,
 # formatted in the style of `info proc mappings`.
 #

Ghidra/Debug/Debugger-agent-gdb/data/scripts/wine32_info_proc_mappings.gdb

@@ -1,3 +1,24 @@
+# Override the "info proc mappings" command in GDB to fetch them from a remote wine32 target
+#
+# To use:
+#  1. Read the documentation for getpid-linux-i386.gdb carefully! You may need to copy and/or make
+#     target-specific adjustments, since it needs to inject machine code. Some preliminary static
+#     analysis may be required.
+#  2. Use Wine on Linux to launch gdbserver.exe with your target binary
+#  3. Connect Ghidra to GDB on Linux
+#  4. From the interpreter, run:
+#
+#        source getpid-linux-i386.gdb
+#        source remote-proc-mappings.py
+#        source wine32_info_proc_mappings.gdb
+#
+#     Note that you may need to provide full paths to the scripts
+#
+# You can now connect to the "remote" gdbserver.exe in the usual way, and Ghidra's Debugger should
+# work as usual. Note that the connection should only be used for 32-bit x86 Windows targets
+# running under Wine for Linux. Re-using the connection for another target may result in undefined
+# behavior.
+
 define info proc mappings
   python
 remote_pid = gdb.execute("getpid-linux-i386", to_string=True).strip()