From a67a6e6a38cc7c086588a87988f06afafa80f1e3 Mon Sep 17 00:00:00 2001 From: Zhang Junyang Date: Sat, 21 Sep 2024 22:31:03 +0800 Subject: [PATCH] Add documentation for OSDK profiling --- docs/src/osdk/reference/commands/README.md | 1 + docs/src/osdk/reference/commands/debug.md | 34 ++++++---- docs/src/osdk/reference/commands/profile.md | 74 +++++++++++++++++++++ docs/src/osdk/reference/commands/run.md | 19 +++--- osdk/src/commands/run.rs | 2 +- 5 files changed, 108 insertions(+), 22 deletions(-) create mode 100644 docs/src/osdk/reference/commands/profile.md diff --git a/docs/src/osdk/reference/commands/README.md b/docs/src/osdk/reference/commands/README.md index a2c6a915..fc8abb4c 100644 --- a/docs/src/osdk/reference/commands/README.md +++ b/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 diff --git a/docs/src/osdk/reference/commands/debug.md b/docs/src/osdk/reference/commands/debug.md index d21a19b6..73539bad 100644 --- a/docs/src/osdk/reference/commands/debug.md +++ b/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 `: @@ -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 +``` diff --git a/docs/src/osdk/reference/commands/profile.md b/docs/src/osdk/reference/commands/profile.md new file mode 100644 index 00000000..96de52ce --- /dev/null +++ b/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 `: + +Specify the address of the remote target. +By default this is `.aster-gdb-socket` + +`--samples `: + +The number of samples to collect (default 200). +It is recommended to go beyond 100 for performance analysis. + +`--interval `: + +The interval between samples in seconds (default 0.1). + +`--parse `: + +Parse a collected JSON profile file into other formats. + +`--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 `: + +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 `: + +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 +``` diff --git a/docs/src/osdk/reference/commands/run.md b/docs/src/osdk/reference/commands/run.md index 049ac598..cc643542 100644 --- a/docs/src/osdk/reference/commands/run.md +++ b/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 `: 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 ``` diff --git a/osdk/src/commands/run.rs b/osdk/src/commands/run.rs index af5adb60..3bbb9d7f 100644 --- a/osdk/src/commands/run.rs +++ b/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 _); } }