From 45a7aba5c9a89995bcf2dab33441c5cf81dbe267 Mon Sep 17 00:00:00 2001
From: fgh1999 <fgh@stu.pku.edu.cn>
Date: Thu, 21 Mar 2024 20:08:22 +0000
Subject: [PATCH] Add docs for OSDK `debug` and `run`

---
 docs/src/osdk/reference/commands/debug.md | 30 ++++++++++++++++++++
 docs/src/osdk/reference/commands/run.md   | 34 ++++++++++++++++++++++-
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/osdk/reference/commands/debug.md

diff --git a/docs/src/osdk/reference/commands/debug.md b/docs/src/osdk/reference/commands/debug.md
new file mode 100644
index 000000000..d21a19b6d
--- /dev/null
+++ b/docs/src/osdk/reference/commands/debug.md
@@ -0,0 +1,30 @@
+# cargo osdk debug
+
+## Overview
+
+`cargo osdk debug` is used to debug a remote target via GDB.
+The usage is as follows:
+
+```bash
+cargo osdk debug [OPTIONS]
+```
+
+## Options
+
+`--remote <REMOTE>`:
+Specify the address of the remote target [default: .aster-gdb-socket].
+The address can be either a path for the UNIX domain socket
+or a TCP port on an IP address.
+
+## Examples
+
+- To debug a remote target via a
+[QEMU GDB stub](https://www.qemu.org/docs/master/system/gdb.html),
+    - connect to an unix socket, e.g., `./debug`;
+    ```bash
+    cargo osdk debug --remote ./debug
+    ```
+    - connect to a TCP port (`[IP]:PORT`), e.g., `localhost:1234`.
+    ```bash
+    cargo osdk debug --remote localhost:1234
+    ```
diff --git a/docs/src/osdk/reference/commands/run.md b/docs/src/osdk/reference/commands/run.md
index 6dbab73c0..e7296b9a1 100644
--- a/docs/src/osdk/reference/commands/run.md
+++ b/docs/src/osdk/reference/commands/run.md
@@ -11,6 +11,38 @@ cargo osdk run [OPTIONS]
 
 ## Options
 
-The options are the same as those of `cargo osdk build`.
+Most options are the same as those of `cargo osdk build`.
 Refer to the [documentation](build.md) of `cargo osdk build`
 for more details.
+
+Options related with debugging:
+
+- `-G, --enable-gdb`: Enable QEMU GDB server for debugging.
+- `--vsc`: Generate a '.vscode/launch.json' for debugging kernel with Visual Studio Code
+(only works when QEMU GDB server is enabled, i.e., `--enable-gdb`).
+Requires [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb).
+- `--gdb-server-addr <ADDR>`: The network address on which the GDB server listens,
+it can be either a path for the UNIX domain socket or a TCP port on an IP address.
+[default: .aster-gdb-socket]
+
+See [Debug Command](debug.md) to interact with the GDB server in terminal.
+
+## Examples
+
+- Launch a debug server via QEMU with an unix socket stub, e.g. `.debug`:
+
+```bash
+cargo osdk run --enable-gdb --gdb-server-addr .debug
+```
+
+- Launch a debug server via QEMU with a TCP stub, e.g., `localhost:1234`:
+
+```bash
+cargo osdk run --enable-gdb --gdb-server-addr :1234
+```
+
+- Launch a debug server via QEMU and use VSCode to interact:
+
+```bash
+cargo osdk run --enable-gdb --vsc --gdb-server-addr :1234
+```