Embed GDB helper

* Add GDB helper script

Pretty printing of some common argument types

Need to add a line to ~/.gdbinit

> add-auto-load-safe-path /path/to/base/checkout/

afterwards verify at GDB shell with

> info auto-load python-scripts
> info pretty-printer

Tested with GDB 16.3 circa Debian 13

Add $rcast(dbCommon) to up-cast
Add $record("name") to lookup record
Add $elln(ELLLIST,#) to index into list

documentation/Makefile

@@ -23,6 +23,7 @@ DOCS += README.md
 DOCS += ca-cli.md
 DOCS += RELEASE_NOTES.md
 DOCS += ReleaseChecklist.md
+DOCS += gdb.md
 
 OLD_NOTES = $(wildcard ../RELEASE-*.md)
 DOCS += $(OLD_NOTES:../%=%)

documentation/gdb.md

@@ -0,0 +1,114 @@
+# Debugging with GDB
+
+Starts a process in [GDB](https://sourceware.org/gdb/current/onlinedocs/gdb.html/):
+
+```sh
+gdb --args ../../bin/linux-x86_64-debug/myioc ./st.cmd
+```
+
+Attach to a running process by numeric PID:
+
+```sh
+gdb --pid=##
+```
+
+Shorthand if only one instance is running:
+
+```sh
+gdb --pid=`pgrep myioc`
+```
+
+## GDB shell Cheat sheet
+
+Print stack traces of all threads.  Optionally with pagination disabled:
+
+```gdb
+(gdb) set pagination off
+
+(gdb) thread apply all backtrace
+
+(gdb) set pagination on
+```
+
+Note: consider sending or posting this very long output as an attachment file.
+
+Break when a certain record begins processing:
+
+```gdb
+(gdb) break dbProcess if $_streq(precord.name, "my:record")
+```
+
+Break when a `PACT` field changes:
+
+```gdb
+(gdb) watch -l $record("my:record").pact
+```
+
+Note: Uses custom `$record()` helper.  See below.
+
+## Helpers
+
+If the bundled `epics-gdb-helper.py` is [enabled](#helper-enable),
+then a set of pretty printers are registered for some common database types.
+eg. `dbCommon*` will show the record name.
+`DBLINK*` will show the associated record name, and the link target.
+Also, several convenience are available.
+
+
+Use `$record()` to lookup a record by name:
+
+```gdb
+(gdb) print $record("my:record")
+$1 = (calcRecord*)(0x55555562f6f8, "my:record")
+```
+
+Note: `$record()` may only be called after record allocation during `iocInit()`.
+
+Use `$rcast()` to up-cast `dbCommon*` to the specific record type:
+
+```gdb
+(gdb) print precord
+$1 = (dbCommon*)(0x55555562f6f8, "my:record")
+(gdb) print $rcast(precord)
+$2 = (calcRecord*)(0x55555562f6f8, "my:record")
+```
+
+Use `$elln()` to index into `ELLLIST` linked lists.
+
+```gdb
+(gdb) print $elln(pdbbase.recordTypeList, 2)
+```
+
+### Enable (helper-enable)
+
+
+To automatically [enable](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Auto_002dloading-safe-path.html),
+add a line to `~/.gdbinit`.
+
+```
+add-auto-load-safe-path /path/to/base/checkout/
+```
+
+Or each time run:
+
+```
+(gdb) source /path/to/base/checkout/modules/database/src/ioc/epics-gdb-helper.py
+```
+
+Note: Entries in the `safe-path` list may be files (`.so` or `.py`), or directories.
+      When a directory is included, sub-directories are also trusted.
+      eg. `add-auto-load-safe-path /opt/epics` would also trust a `/opt/epics/lib`.
+
+Afterwards verify at GDB shell by running:
+
+```gdb
+(gdb) info auto-load python-scripts
+Loaded  Script
+...
+Yes     epics-gdb-helper.py
+
+(gdb) info pretty-printer
+global pretty-printers:
+  EPICS
+...
+```

documentation/index.rst

@@ -14,6 +14,7 @@ EPICS Base Documentation
    README
    RELEASE_NOTES
    ACF-Language
+   gdb
 
 .. toctree::
    :maxdepth: 2

documentation/new-notes/PR-110.md

@@ -0,0 +1,7 @@
+## Add GDB Helper Script
+
+Add [Debugging with GDB](gdb.md) section in documentation.
+
+Add GDB helper script to pretty print some common database types.
+Tested with GDB 16.3.
+Compatible with python 3.