Add gdb script and update docs

Signed-off-by: Simon Davies <[email protected]>

Author: simongdavies

docs/how-to-debug-a-hyperlight-guest.md

@@ -226,14 +226,14 @@ To selectively disable this feature for a specific sandbox, you can set the `gue
     cfg.set_guest_core_dump(false); // Disable core dump for this sandbox
 ```
 
-### Creating a dump on demand
+## Creating a dump on demand
 
 You can also create a core dump of the current state of the guest on demand by calling the `generate_crashdump` method on the `InitializedMultiUseSandbox` instance. This can be useful for debugging issues in the guest that do not cause crashes (e.g., a guest function that does not return).
 
 This is only available when the `crashdump` feature is enabled and then only if the sandbox
 is also configured to allow core dumps (which is the default behavior).
 
-# Examples
+### Example
 
 Attach to your running process with gdb and call this function:
 
@@ -252,7 +252,12 @@ sudo gdb -p <pid_of_your_process>
     # Call the crashdump function 
 call sandbox.generate_crashdump()
 ```
-The crashdump should be available in crash dump directory (see `HYPERLIGHT_CORE_DUMP_DIR` env var).
+The crashdump should be available `/tmp` or in the crash dump directory (see `HYPERLIGHT_CORE_DUMP_DIR` env var). To make this process easier, you can also create a gdb script that automates these steps. You can find an example script [here](../scripts/dump_all_sandboxes.gdb). This script will try and generate a crashdump for every active thread except thread 1 , it assumes that the variable sandbox exists in frame 15 on every thread. You can edit it to fit your needs. Then use it like this:
+
+```shell
+(gdb) source scripts/dump_all_sandboxes.gdb
+(gdb) dump_all_sandboxes
+```
 
 ### Inspecting the core dump
 

src/hyperlight_host/scripts/dump_all_sandboxes.gdb

@@ -0,0 +1,41 @@
+define dump_all_sandboxes
+  set pagination off
+  
+  # Get the total number of threads
+  info threads
+  
+  # Loop through all threads (adjust max if you have more than 200 threads)
+  set $thread_num = 2
+  while $thread_num <= 200
+    # Try to switch to this thread
+    thread $thread_num
+    
+    # Check if thread switch succeeded (GDB sets $_thread to current thread)
+    if $_thread == $thread_num
+      echo \n=== Thread 
+      p $thread_num
+      echo ===\n
+      
+      # Go to frame 15
+      frame 15
+      
+      
+      set $sb = &sandbox
+      call sandbox.generate_crashdump()
+      
+      set $thread_num = $thread_num + 1
+    else
+      # No more threads, exit loop
+      set $thread_num = 201
+    end
+  end
+  
+  echo \nDone dumping all sandboxes\n
+  set pagination on
+end
+
+document dump_all_sandboxes
+Dump crashdumps for sandboxes on all threads (except thread 1).
+Assumes sandbox is in frame 15 on each thread.
+Usage: dump_all_sandboxes
+end