From cec6a8154e1e61a6f11b4c1be7d16e0ec4a9f55c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Doru=20Bl=C3=A2nzeanu?= Date: Tue, 17 Dec 2024 18:04:51 +0200 Subject: [PATCH] add information on how to setup debugging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Doru Blânzeanu --- docs/README.md | 1 + docs/how-to-debug-a-hyperlight-guest.md | 26 +++++++++++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 docs/how-to-debug-a-hyperlight-guest.md diff --git a/docs/README.md b/docs/README.md index 1b1572dd..fff51c66 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 00000000..6791478d --- /dev/null +++ b/docs/how-to-debug-a-hyperlight-guest.md @@ -0,0 +1,26 @@ +# How to debug a Hyperlight guest + +Currently Hyperlight support gdb debugging of a guest running inside a Hyperlight sandbox. +When the option is enabled Hyperlight starts listening on port `8081` for a gdb connection. + +Note: It will only accept one connection, if the connection is closed, the debug session is also closed. + +## Example +```bash +cargo run --example hello-world --features gdb +``` +The execution will wait for gdb to attach. + +One can use a simple gdb config to provide the symbols and desired configuration: + +For the above example, when running from the repository root directory, the below contents +of `.gdbinit` file can be used. +```gdb +file src/tests/rust_guests/bin/debug/simpleguest +target remote :8081 +set disassembly-flavor intel +set disassemble-next-line on +enable pretty-printer +layout regs +layout src +``` \ No newline at end of file