From d0db26e11d20454105d42d47be0bed6e06baac6a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Doru=20Bl=C3=A2nzeanu?= <dblnz@pm.me>
Date: Tue, 4 Feb 2025 22:50:41 +0200
Subject: [PATCH] add documentation about the gdb debugging feature
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Doru Blânzeanu <dblnz@pm.me>
---
 docs/README.md                          |  1 +
 docs/how-to-debug-a-hyperlight-guest.md | 41 +++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 docs/how-to-debug-a-hyperlight-guest.md

diff --git a/docs/README.md b/docs/README.md
index 1b1572dda..fff51c662 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -34,6 +34,7 @@ This project is composed internally of several internal components, depicted in
 
 * [Security guidance for developers](./security-guidance-for-developers.md)
 * [Paging Development Notes](./paging-development-notes.md)
+* [How to debug a Hyperlight guest](./how-to-debug-a-hyperlight-guest.md)
 * [How to use Flatbuffers in Hyperlight](./how-to-use-flatbuffers.md)
 * [How to make a Hyperlight release](./how-to-make-releases.md)
 * [Getting Hyperlight Metrics, Logs, and Traces](./hyperlight-metrics-logs-and-traces.md)
diff --git a/docs/how-to-debug-a-hyperlight-guest.md b/docs/how-to-debug-a-hyperlight-guest.md
new file mode 100644
index 000000000..19d5914eb
--- /dev/null
+++ b/docs/how-to-debug-a-hyperlight-guest.md
@@ -0,0 +1,41 @@
+# How to debug a Hyperlight guest
+
+Hyperlight supports gdb debugging of a guest running inside a Hyperlight sandbox.
+When Hyperlight is compiled with the `gdb` feature enabled, a Hyperlight sandbox can be configured
+to start listening for a gdb connection.
+
+## Example
+The snipped of a rust host application below configures the Hyperlight Sandbox to
+listen on port `9050` for a gdb client to connect.
+
+```rust
+    let mut cfg = SandboxConfiguration::default();
+    cfg.set_guest_debug_port(9050);
+
+    // Create an uninitialized sandbox with a guest binary
+    let mut uninitialized_sandbox = UninitializedSandbox::new(
+        hyperlight_host::GuestBinary::FilePath(
+            hyperlight_testing::simple_guest_as_string().unwrap(),
+        ),
+        Some(cfg), // configuration
+        None, // default run options
+        None, // default host print function
+    )?;
+```
+
+The execution of the guest will wait for gdb to attach.
+
+One can use a simple gdb config to provide the symbols and desired configuration:
+
+For the above snippet, the below contents of the `.gdbinit` file can be used to
+provide configuration to gdb startup.
+```gdb
+file path/to/symbols.elf
+target remote :9050
+set disassembly-flavor intel
+set disassemble-next-line on
+enable pretty-printer
+layout src
+```
+
+One can find more information about the `.gdbinit` file at [gdbinit(5)](https://www.man7.org/linux/man-pages/man5/gdbinit.5.html).