mirror of
https://github.com/asterinas/asterinas.git
synced 2025-06-09 13:26:48 +00:00
Add documentation for OSDK profiling
This commit is contained in:
parent
eca9aacbf0
commit
a67a6e6a38
@ -11,6 +11,7 @@ Currently, OSDK supports the following subcommands:
|
|||||||
- **run**: Run the kernel with a VMM
|
- **run**: Run the kernel with a VMM
|
||||||
- **test**: Execute kernel mode unit test by starting a VMM
|
- **test**: Execute kernel mode unit test by starting a VMM
|
||||||
- **debug**: Debug a remote target via GDB
|
- **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
|
- **check**: Analyze the current package and report errors
|
||||||
- **clippy**: Check the current package and catch common mistakes
|
- **clippy**: Check the current package and catch common mistakes
|
||||||
|
|
||||||
|
@ -2,13 +2,18 @@
|
|||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
`cargo osdk debug` is used to debug a remote target via GDB.
|
`cargo osdk debug` is used to debug a remote target via GDB. You need to start
|
||||||
The usage is as follows:
|
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
|
```bash
|
||||||
cargo osdk debug [OPTIONS]
|
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
|
## Options
|
||||||
|
|
||||||
`--remote <REMOTE>`:
|
`--remote <REMOTE>`:
|
||||||
@ -18,13 +23,18 @@ or a TCP port on an IP address.
|
|||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
- To debug a remote target via a
|
To debug a remote target started with
|
||||||
[QEMU GDB stub](https://www.qemu.org/docs/master/system/gdb.html),
|
[QEMU GDB stub](https://www.qemu.org/docs/master/system/gdb.html) or the `run`
|
||||||
- connect to an unix socket, e.g., `./debug`;
|
subcommand, use the following commands.
|
||||||
```bash
|
|
||||||
cargo osdk debug --remote ./debug
|
Connect to an unix socket, e.g., `./debug`:
|
||||||
```
|
|
||||||
- connect to a TCP port (`[IP]:PORT`), e.g., `localhost:1234`.
|
```bash
|
||||||
```bash
|
cargo osdk debug --remote ./debug
|
||||||
cargo osdk debug --remote localhost:1234
|
```
|
||||||
```
|
|
||||||
|
Connect to a TCP port (`[IP]:PORT`), e.g., `localhost:1234`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo osdk debug --remote localhost:1234
|
||||||
|
```
|
||||||
|
74
docs/src/osdk/reference/commands/profile.md
Normal file
74
docs/src/osdk/reference/commands/profile.md
Normal file
@ -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
|
||||||
|
```
|
@ -17,9 +17,10 @@ for more details.
|
|||||||
|
|
||||||
Options related with debugging:
|
Options related with debugging:
|
||||||
|
|
||||||
- `-G, --enable-gdb`: Enable QEMU GDB server for debugging.
|
- `--gdb-server`: Enable QEMU GDB server for debugging.
|
||||||
- `--vsc`: Generate a '.vscode/launch.json' for debugging kernel with Visual Studio Code
|
- `--gdb-wait-client`: Let the QEMU GDB server wait for the client connection before execution.
|
||||||
(only works when QEMU GDB server is enabled, i.e., `--enable-gdb`).
|
- `--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).
|
Requires [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb).
|
||||||
- `--gdb-server-addr <ADDR>`: The network address on which the GDB server listens,
|
- `--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.
|
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
|
## 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
|
```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
|
```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
|
```bash
|
||||||
cargo osdk run --enable-gdb --vsc --gdb-server-addr :1234
|
cargo osdk run --gdb-server --gdb-vsc --gdb-server-addr :1234
|
||||||
```
|
```
|
||||||
|
@ -224,7 +224,7 @@ mod vsc {
|
|||||||
exit(Errno::ParseMetadata as _);
|
exit(Errno::ParseMetadata as _);
|
||||||
}
|
}
|
||||||
if gdb::stub_type_of(gdb_stub_addr) != gdb::StubAddrType::Tcp {
|
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 _);
|
exit(Errno::ParseMetadata as _);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
Loading…
x
Reference in New Issue
Block a user