Add documentation for OSDK profiling

docs/src/osdk/reference/commands/README.md

@@ -11,6 +11,7 @@ Currently, OSDK supports the following subcommands:
 - **run**: Run the kernel with a VMM
 - **test**: Execute kernel mode unit test by starting a VMM
 - **debug**: Debug a remote target via GDB
+- **profile**: Profile a remote GDB debug target to collect stack traces
 - **check**: Analyze the current package and report errors
 - **clippy**: Check the current package and catch common mistakes
 

docs/src/osdk/reference/commands/debug.md

@@ -2,13 +2,18 @@
 
 ## Overview
 
-`cargo osdk debug` is used to debug a remote target via GDB.
-The usage is as follows:
+`cargo osdk debug` is used to debug a remote target via GDB. You need to start
+a running server to debug with. This is accomplished by the `run` subcommand
+with `--gdb-server`. Then you can use the following command to attach to the
+server and do debugging.
 
 ```bash
 cargo osdk debug [OPTIONS]
 ```
 
+Note that when KVM is enabled, hardware-assisted break points (`hbreak`) are
+needed instead of the normal break points (`break`/`b`) in GDB.
+
 ## Options
 
 `--remote <REMOTE>`:
@@ -18,13 +23,18 @@ 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
-    ```
+To debug a remote target started with
+[QEMU GDB stub](https://www.qemu.org/docs/master/system/gdb.html) or the `run`
+subcommand, use the following commands.
+
+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
+```

docs/src/osdk/reference/commands/profile.md

@@ -0,0 +1,74 @@
+# cargo osdk profile
+
+## Overview
+
+The profile command is used to collect stack traces when running the target
+kernel in QEMU. It attaches to the GDB server initiated with the run subcommand
+and collects the stack trace periodically. The collected data can be
+further analyzed using tools like
+[flame graph](https://github.com/brendangregg/FlameGraph).
+
+## Options
+
+`--remote <REMOTE>`:
+
+Specify the address of the remote target.
+By default this is `.aster-gdb-socket`
+
+`--samples <SAMPLES>`:
+
+The number of samples to collect (default 200).
+It is recommended to go beyond 100 for performance analysis.
+
+`--interval <INTERVAL>`:
+
+The interval between samples in seconds (default 0.1).
+
+`--parse <PATH>`:
+
+Parse a collected JSON profile file into other formats.
+
+`--format <FORMAT>`:
+
+Possible values:
+    - `json`:   The parsed stack trace log from GDB in JSON.
+    - `folded`: The folded stack trace for flame graph.
+
+If the user does not specify the format, it will be inferred from the
+output file extension. If the output file does not have an extension,
+the default format is folded stack traces.
+
+`--cpu-mask <CPU_MASK>`:
+
+The mask of the CPU to generate traces for in the output profile data
+(default first 128 cores). This mask is presented as an integer.
+
+`--output <PATH>`:
+
+The path to the output profile data file.
+
+If the user does not specify the output path, it will be generated from
+the crate name, current time stamp and the format.
+
+## Examples
+
+To profile a remote QEMU GDB server running some workload for flame graph, do:
+
+```bash
+cargo osdk profile --remote :1234 \
+	--samples 100 --interval 0.01
+```
+
+If wanted a detailed analysis, do:
+
+```bash
+cargo osdk profile --remote :1234 \
+	--samples 100 --interval 0.01 --output trace.json
+```
+
+When you get the above detailed analysis, you can also use the JSON file
+to generate the folded format for flame graph.
+
+```bash
+cargo osdk profile --parse trace.json --output trace.folded
+```

docs/src/osdk/reference/commands/run.md

@@ -17,9 +17,10 @@ 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`).
+- `--gdb-server`: Enable QEMU GDB server for debugging.
+- `--gdb-wait-client`: Let the QEMU GDB server wait for the client connection before execution.
+- `--gdb-vsc`: Generate a '.vscode/launch.json' for debugging kernel with Visual Studio Code
+(only works when QEMU GDB server is enabled, i.e., `--gdb-server`).
 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.
@@ -29,20 +30,20 @@ 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`:
+Launch a debug server via QEMU with an unix socket stub, e.g. `.debug`:
 
 ```bash
-cargo osdk run --enable-gdb --gdb-server-addr .debug
+cargo osdk run --gdb-server --gdb-server-addr .debug
 ```
 
-- Launch a debug server via QEMU with a TCP stub, e.g., `localhost:1234`:
+Launch a debug server via QEMU with a TCP stub, e.g., `localhost:1234`:
 
 ```bash
-cargo osdk run --enable-gdb --gdb-server-addr :1234
+cargo osdk run --gdb-server --gdb-server-addr :1234
 ```
 
-- Launch a debug server via QEMU and use VSCode to interact:
+Launch a debug server via QEMU and use VSCode to interact:
 
 ```bash
-cargo osdk run --enable-gdb --vsc --gdb-server-addr :1234
+cargo osdk run --gdb-server --gdb-vsc --gdb-server-addr :1234
 ```

osdk/src/commands/run.rs

@@ -224,7 +224,7 @@ mod vsc {
             exit(Errno::ParseMetadata as _);
         }
         if gdb::stub_type_of(gdb_stub_addr) != gdb::StubAddrType::Tcp {
-            error_msg!("Non-TCP GDB server address is not supported under '--vsc' currently");
+            error_msg!("Non-TCP GDB server address is not supported under '--gdb-vsc' currently");
             exit(Errno::ParseMetadata as _);
         }
     }