Add documentation

Author: dominikmascherbauer

docs/reference-manual/native-image/guides/debug-native-executables-with-gdb.md

@@ -528,6 +528,155 @@ void svm_dbg_print_fatalErrorDiagnostics(graal_isolatethread_t* thread, size_t s
 void svm_dbg_print_locationInfo(graal_isolatethread_t* thread, size_t mem);
 ```
 
+### Debugging with `svmhelpers.py`
+
+To provide a reasonably good experience for debugging native images [GDBs Python API](https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html) is used.
+This requires GDB with python support, the debugging extension is tested against GDB 13.2 and supports the new debuginfo generation introduced in GraalVM for JDK 17 and GraalVM for JDK 20.
+
+##### ⚠️ The `svmhelpers.py` file does not work with older versions than GDB 13.2 and GraalVM for JDK17/GraalVM for JDK 20.
+
+The python script `svmhelpers.py` can be found in `<GRAALVM_HOME>/lib/svm/debug`.
+If debug info generation is enabled, the script is copied to the build directory.
+The native image generator adds the debugging section `.debug_gdb_scripts` to the debug info file, which causes GDB to automatically load `svmhelpers.py` from the current working directory.
+
+For [security reasons](https://sourceware.org/gdb/current/onlinedocs/gdb/Auto_002dloading-safe-path.html)
+the first time GDB encounters an image that requests a specific python file to be loaded it will complain:
+
+>     Reading symbols from svmbuild/images/<imagename>...
+>     warning: File "<CWD>/svmhelpers.py" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
+>
+>     To enable execution of this file add
+>             add-auto-load-safe-path <CWD>/svmhelpers.py
+>     line to your configuration file "<HOME>/.gdbinit".
+>     To completely disable this security protection add
+>             add-auto-load-safe-path /
+>     line to your configuration file "<HOME>/.gdbinit".
+>     For more information about this security protection see the
+>     "Auto-loading safe path" section in the GDB manual.  E.g., run from the shell:
+>             info "(gdb)Auto-loading safe path"
+
+To solve this, either add the current working directory to `~\.gdbinit`,
+    
+    echo "add-auto-load-safe-path <CWD>" >> ~/.gdbinit
+
+or, for a more permanent solution add
+
+    echo "add-auto-load-safe-path ./svmhelpers.py" >> ~/.gdbinit
+
+which allows GDB to auto-load `svmhelpers.py` from the current working directory in all debugging sessions.
+
+Auto-loading is the recommended way to provide the script to GDB.
+However, it is possible to manually load the script from GDB explicitly with:
+    
+    (gdb) source svmhelpers.py
+
+
+#### SVM Pretty Printing Support
+
+The loading of `svmhelpers.py` registers a new pretty printer to GDB, which adds an extra level of convenience for debugging native images.
+This pretty printer handles the printing of Java Objects, Arrays, Strings and Enums for debugging native images.
+If the Java application uses `@CStruct` and `@CPointer` annotations for accessing C data structures, the pretty printer will also try to print them as if they were Java data structures.
+If the C data structures cannot be printed by the SVM pretty printer, printing is done by GDB.
+
+The pretty printer also supports printing of the primitive value instead of a Java Object for boxed primitives.
+
+Whenever printing is done via the `p` (alias for `print`) the pretty printer intercepts that call to perform type casts to the respective runtime types of Java Objects.
+This also applies for auto-completion when using the `p` command.
+This means, if the static type is different to the runtime type, `print` uses the static types, which leaves finding out the runtime types and type casting to the user.
+Additionally, the `p` command understands Java field and array access and function calls for Java Objects.
+
+##### Limitations
+
+The `print` still uses its default implementation, as there is no way to overwrite it, while still keeping the capability of the default `print` command.
+This would cause printing non-Java Objects to not work properly.
+Therefore, only the alias `p` for the `print` command is overwritten by the SVM pretty printer, such that the user can still make use of GDBs default `print` command.
+
+
+#### Options for controlling the behavior of the SVM Pretty Printer
+
+In addition to the enhanced `p` command `svmhelpers.py` introduces some GDB parameters to customize the behavior of the SVM Pretty Printer.
+Parameters in GDB can be interacted with `set <param> <value>` and `show <param>` and therefore, integrates into GDBs customization options.
+
+* ##### svm-print on/off
+
+Use this command to enable/disable the SVM Pretty Printer.
+This also resets the `print` command alias `p` to its default behavior.
+Alternatively SVM pretty printing can be suppressed with the
+[raw printing option of GDBs print command](https://sourceware.org/gdb/current/onlinedocs/gdb/Output-Formats.html):
+
+    (gdb) show svm-print
+    The current value of 'svm-print' is "on".
+    (gdb) print str
+    $1 = "string"
+    (gdb) print/r str
+    $2 = (java.lang.String *) 0x7ffff689d2d0
+      (gdb) set svm-print off
+    1 printer disabled
+    1 of 2 printers enabled
+    
+    (gdb) print str
+    $3 = (java.lang.String *) 0x7ffff689d2d0
+
+* ##### svm-print-string-limit &lt;int&gt;
+
+Allows to customize the maximum length for pretty printing Java Strings.
+The default value is 200, set to -1 or _unlimited_ for unlimited printing of Java Strings. 
+This does not change the limit for c strings, which can be controlled with GDBs `set print characters`.
+
+* ##### svm-print-element-limit &lt;int&gt;
+
+Allows to customize the maximum number of elements for pretty printing Java Arrays, ArrayLists and HashMaps.
+The default value is 10, set to -1 or _unlimited_ for printing unlimited number of elements.
+This does not change the limit for c arrays, which can be controlled with GDBs `set print elements`.
+However, GDBs parameter `print elements` is the upper bound for `svm-print-element-limit`.
+
+* ##### svm-print-field-limit &lt;int&gt;
+
+Allows to customize the maximum number of elements for pretty printing fields of Java Objects.
+The default value is 50, set to -1 or _unlimited_ for printing unlimited number of fields.
+GDBs parameter `print elements` is the upper bound for `svm-print-field-limit`.
+
+* ##### svm-print-depth-limit &lt;int&gt;
+
+Allows to customize the maximum depth of recursive svm pretty printing.
+The default value is 1. 
+The children of direct children are printed (a sane default to make contents of boxed values visible).
+Set to -1 or _unlimited_ for printing unlimited depth.
+GDBs parameter `print max-depth` is the upper bound for `svm-print-depth-limit`.
+
+* ##### svm-use-hlrep on/off
+
+Use this command to enable/disable pretty printing for higher level representations. 
+It provides a more data oriented view on some Java data structures with a known internal structure such as Lists or Maps.
+Currently supports ArrayList and HashMap.
+
+* ##### svm-infer-generics &lt;int&gt;
+
+Allows to customize the amount of elements taken into account for inferring the generic type of higher level representations.
+The default value is 10.
+Set to 0 for not inferring generic types and -1 or _unlimited_ for inferring the generic type over all elements.
+
+* ##### svm-print-address absolute/on/off
+
+Use this command to enable/disable printing of addresses in addition to regular pretty printing. 
+When `absolute` mode is used even compressed references are shown as absolute addresses. 
+Printing addresses is disabled by default.
+
+* ##### svm-print-static-fields on/off
+
+Per default static field members are not shown during pretty printing of Java objects. 
+This command allows to customize this behavior.
+
+* ##### svm-complete-static-variables on/off
+
+Per default static field members completion is provided by the **p** command. 
+This command allows to enable/disable completion for static field members.
+
+* ##### svm-selfref-check on/off
+
+To avoid endless recursion in pretty printing self-referential data structures `svmhelpers.py` detects such cases and prevents further expansion. 
+For testing, this feature can be temporary disabled (usually you wouldn't want to do this).
+
 ### Related Documentation
 
 * [Debug Info Feature](../DebugInfo.md)