Samuka007/asterinas
1
0
Fork 0
mirror of https://github.com/asterinas/asterinas.git synced 2025-06-21 08:26:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Polish OSDK documentation

Browse Source
This commit is contained in:
Jianfeng Jiang
2024-05-22 06:04:36 +00:00
committed by Tate, Hongliang Tian
parent 07caaa5b3f
commit 1391ff59f2
20 changed files with 253 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/src/SUMMARY.md
View File

@ -30,6 +30,7 @@
* [cargo osdk build](osdk/reference/commands/build.md)
* [cargo osdk run](osdk/reference/commands/run.md)
* [cargo osdk test](osdk/reference/commands/test.md)
* [cargo osdk debug](osdk/reference/commands/debug.md)
* [Manifest](osdk/reference/manifest.md)
# How to Contribute

15
docs/src/osdk/guide/README.md
View File

@ -26,11 +26,18 @@ the following tools need to be installed:
- Rust >= 1.75.0
- cargo-binutils
- gcc
- qemu-system-x86_64
- gdb
- grub
- ovmf
- qemu-system-x86_64
- xorriso
The dependencies required for installing Rust and running QEMU can be installed by:
```bash
apt install build-essential curl gdb grub-efi-amd64 grub2-common \
libpixman-1-dev mtools ovmf qemu-system-x86 xorriso
```
About how to install Rust, you can refer to
the [official site](https://www.rust-lang.org/tools/install).
@ -40,12 +47,6 @@ after Rust is installed by
cargo install cargo-binutils
```
Other tools can be installed by
```bash
apt install build-essential grub-efi-amd64 grub2-common \
libpixman-1-dev mtools qemu-system-x86 ovmf xorriso
```
### Install
`cargo-osdk` is published on [crates.io](https://crates.io/),

23
docs/src/osdk/guide/create-project.md
View File

@ -57,12 +57,6 @@ The kernel
will print `Hello world from the guest kernel!`to the console
and then abort.
There is also a code snippet that demonstrates
how to write kernel mode unit tests.
It follows a similar code pattern as user mode unit tests.
The test module is marked with the `#[cfg(ktest)]` macro,
and each test case is marked with `#[ktest]`.
```rust
{{#include ../../../../osdk/src/commands/new/kernel.template}}
```
@ -71,6 +65,9 @@ and each test case is marked with `#[ktest]`.
The `src/lib.rs` of library project only contains
a simple kernel mode unit test.
It follows a similar code pattern as user mode unit tests.
The test module is marked with the `#[cfg(ktest)]` macro,
and each test case is marked with `#[ktest]`.
```rust
{{#include ../../../../osdk/src/commands/new/lib.template}}
@ -93,19 +90,27 @@ git = "https://github.com/asterinas/asterinas"
branch = "main"
```
OSDK will also exclude the directory
which is used to generate temporary files.
```toml
[workspace]
exclude = ["target/osdk/base"]
```
### `OSDK.toml`
The `OSDK.toml` file is a manifest
that defines the exact behavior of OSDK.
By default, it contains the following contents.
It includes settings on how to start QEMU to run a kernel.
By default, it includes settings on how to start QEMU to run a kernel.
The meaning of each key can be found
in the [manifest documentation](../reference/manifest.md).
Please avoid changing the default settings
unless you know what you are doing.
The default manifest of a kernel project:
```toml
{{#include ../../../../osdk/src/commands/new/lib.OSDK.toml.template}}
{{#include ../../../../osdk/src/commands/new/kernel.OSDK.toml.template}}
```
### `rust-toolchain.toml`

18
docs/src/osdk/guide/run-project.md
View File

@ -1,4 +1,4 @@
# Testing or Running an OS Project
# Running or Testing an OS Project
OSDK allows for convenient building, running,
and testing of an OS project.
@ -20,6 +20,11 @@ simply type:
cargo osdk build
```
The initial build of an OSDK project
may take a considerable amount of time
as it involves downloading the Rust toolchain used by the framekernel.
However, this is a one-time process.
## Run the project
To launch the kernel with QEMU,
@ -42,6 +47,14 @@ library projects cannot.
## Test the project
Suppose you have created a new library project named `mylib`
which contains a default test case
and you are in the project directory.
```bash
cargo osdk new --lib mylib && cd mylib
```
To run the kernel mode tests, use the following command:
```bash
@ -50,6 +63,9 @@ cargo osdk test
OSDK will run all the kernel mode tests in the crate.
Test cases can be added not only in library projects
but also in kernel projects.
If you want to run a specific test with a given name,
for example, if the test is named `foo`,
use the following command:

24
docs/src/osdk/guide/work-in-workspace.md
View File

@ -17,7 +17,9 @@ touch Cargo.toml
Then, add the following content to `Cargo.toml`:
```toml
{{#include ../../../../osdk/tests/examples_in_book/work_in_workspace_templates/Cargo.toml}}
```
## Creating a kernel project and a library project
@ -25,7 +27,7 @@ The two projects can be created using the following commands:
```bash
cargo osdk new --kernel myos
cargo osdk new mymodule
cargo osdk new mylib
```
The generated directory structure will be as follows:
@ -39,7 +41,7 @@ myworkspace/
│ ├── Cargo.toml
│ └── src/
│ └── lib.rs
└── mymodule/
└── mylib/
├── Cargo.toml
└── src/
└── lib.rs
@ -52,21 +54,27 @@ In addition to the two projects,
OSDK will also generate `OSDK.toml` and `rust-toolchain.toml`
at the root of the workspace.
Next, add the following function to `mymodule/src/lib.rs`.
Next, add the following function to `mylib/src/lib.rs`.
This function will calculate the available memory
after booting:
{{#include ../../../../osdk/tests/examples_in_book/work_in_workspace_templates/mymodule/src/lib.rs}}
```rust
{{#include ../../../../osdk/tests/examples_in_book/work_in_workspace_templates/mylib/src/lib.rs}}
```
Then, add a dependency on `mymodule` to `myos/Cargo.toml`:
Then, add a dependency on `mylib` to `myos/Cargo.toml`:
```toml
{{#include ../../../../osdk/tests/examples_in_book/work_in_workspace_templates/myos/Cargo.toml}}
```
In `myos/src/lib.rs`,
modify the file content as follows.
This main function will call the function from `mymodule`:
This main function will call the function from `mylib`:
```rust
{{#include ../../../../osdk/tests/examples_in_book/work_in_workspace_templates/myos/src/lib.rs}}
```
## Building and Running the kernel
@ -92,9 +100,9 @@ cargo osdk test
If you want to run test cases from a specific crate,
navigate to the crate's folder
and run `cargo osdk test`.
For example, if you want to test `myos`,
For example, if you want to test `mylib`,
use the following command:
```bash
cd myos && cargo osdk test
cd mylib && cargo osdk test
```

14
docs/src/osdk/reference/commands/README.md
View File

@ -1,18 +1,20 @@
# Commands
OSDK provides similar commands as Cargo,
and these commands have simalar meanings
as corresponding Cargo commands.
OSDK provides similar subcommands as Cargo,
and these subcommands have simalar meanings
as corresponding Cargo subcommands.
Currently, OSDK supports the following commands:
Currently, OSDK supports the following subcommands:
- **new**: Create a new kernel package or library package
- **build**: Compile the project and its dependencies
- **run**: Run the kernel with a VMM
- **test**: Execute kernel mode unit test by starting a VMM
- **debug**: Debug a remote target via GDB
- **check**: Analyze the current package and report errors
- **clippy**: Check the current package and catch common mistakes
The **new**, **build**, **run** and **test** commands
The **new**, **build**, **run**, **test** and **debug** subcommands
can accept additional options,
while the **check** and **clippy** commands cannot.
while the **check** and **clippy** subcommands can only accept arguments
that are compatible with the corresponding Cargo subcommands.

17
docs/src/osdk/reference/commands/build.md
View File

@ -29,6 +29,14 @@ Build artifacts in release mode, with optimizations
- `--features <FEATURES>`:
Space or comma separated list of features to activate
- `--no-default-features`:
Do not activate the `default` features
- `--config <KEY=VALUE>`:
Override a configuration value
More Cargo options will be supported in future versions of OSDK.
### Manifest options
These options can also be defined
@ -46,16 +54,21 @@ Command line arguments for the init process
Path of the initramfs
- `--boot-method <METHOD>`:
The method to boot the kernel
- `--grub-mkrescue <PATH>`:
Path of grub-mkrescue
- `--grub-boot-protocol <PROTOCOL>`:
The boot protocol for booting the kernel
- `--display-grub-menu`:
To display the GRUB menu if booting with GRUB
- `--qemu-path <PATH>`:
Path of QEMU
- `--qemu-exe <FILE>`:
The QEMU executable file
- `--qemu-args <ARGS>`:
Extra arguments for running QEMU
- `--strip-elf`:
Whether to strip the built kernel ELF using `rust-strip`
- `--scheme <SCHEME>`:
Select the specific configuration scheme provided in the OSDK manifest
## Examples

4
docs/src/osdk/reference/commands/new.md
View File

@ -30,8 +30,8 @@ the library template will be used by default.
cargo osdk new --kernel myos
```
- Create a new library named `mymodule`:
- Create a new library named `mylib`:
```bash
cargo osdk new mymodule
cargo osdk new mylib
```

6
docs/src/osdk/reference/commands/test.md
View File

@ -20,9 +20,9 @@ Refer to the [documentation](build.md) of `cargo osdk build`
for more details.
## Examples
- Execute tests containing foo in their names
with q35 as the QEMU machine type:
- Execute tests that include *foo* in their names
using QEMU with 3GB of memory
```bash
cargo osdk test foo --qemu.machine="q35"
cargo osdk test foo --qemu-args="-m 3G"
```

235
docs/src/osdk/reference/manifest.md
View File

@ -25,58 +25,100 @@ will inherit values from the workspace manifest.
Below, you will find a comprehensive version of
the available configurations in the manifest.
Here are notes for some fields with special value treatings:
- `*` marks the field as "will be evaluated", that the final
value of string `"S"` will be the output of `echo "S"` using the
host's shell.
- `+` marks the path fields. The relative paths written in the
path fields will be relative to the manifest's enclosing directory.
If values are given in the tree that's the default value inferred
if that the field is not explicitly stated.
```
project_type = "kernel" # The type of the current crate. Can be lib/kernel[/module]
```toml
project_type = "kernel" # <1>
# --------------------------- the default schema settings -------------------------------
supported_archs = ["x86_64"]# List of strings, that the arch the schema can apply to
[build]
features = [] # List of strings, the same as Cargo
profile = "dev" # String, the same as Cargo
strip_elf = false # Whether to strip the built kernel ELF using `rust-strip`
[boot]
method = "qemu-direct" # "grub-rescue-iso"/"qemu-direct"/"grub-qcow2"
kcmd_args = [] # <1>
init_args = [] # <2>
initramfs = "path/to/it" # + The path to the initramfs
[grub] # Grub options are only needed if boot method is related to GRUB
mkrescue_path = "path/to/it"# + The path to the `grub-mkrescue` executable
protocol = "multiboot2" # The protocol GRUB used. "linux"/"multiboot"/"multiboot2"
display_grub_menu = false # To display the GRUB menu when booting with GRUB
[qemu]
path + # The path to the QEMU executable
args * # String. <3>
[run] # Special settings for running, which will override default ones
build # Overriding [build]
boot # Overriding [boot]
grub # Overriding [grub]
qemu # Overriding [qemu]
[test] # Special settings for testing, which will override default ones
build # Overriding [build]
boot # Overriding [boot]
grub # Overriding [grub]
qemu # Overriding [qemu]
supported_archs = ["x86_64", "riscv64"] # <2>
# The common options for all build, run and test subcommands
[build] # <3>
features = ["no_std", "alloc"] # <4>
profile = "dev" # <5>
strip_elf = false # <6>
[boot] # <7>
method = "qemu-direct" # <8>
kcmd_args = ["SHELL=/bin/sh", "HOME=/"] # <9>
init_args = ["sh", "-l"] # <10>
initramfs = "path/to/it" # <11>
[grub] # <12>
mkrescue_path = "path/to/it" # <13>
protocol = "multiboot2" # <14>
display_grub_menu = false # <15>
[qemu] # <16>
path = "path/to/it" # <17>
args = "-machine q35 -m 2G" # <18>
# Special options for run subcommand
[run] # <19>
[run.build] # <3>
[run.boot] # <7>
[run.grub] # <12>
[run.qemu] # <16>
# Special options for test subcommand
[test] # <20>
[test.build] # <3>
[test.boot] # <7>
[test.grub] # <12>
[test.qemu] # <16>
# ----------------------- end of the default schema settings ----------------------------
[schema."user_custom_schema"]
#... # All the other fields in the default schema. Missing but
# needed values will be firstly filled with the default
# value then the corresponding field in the default schema
# A customized schema settings
[schema."custom"] # <21>
[schema."custom".build] # <3>
[schema."custom".run] # <19>
[schema."custom".test] # <20>
```
Here are some additional notes for the fields:
1. The arguments provided will be passed to the guest kernel.
1. The type of current crate.
Optional. If not specified,
the default value is inferred from the usage of the macro `#[aster_main]`.
if the macro is used, the default value is `kernel`.
Otherwise, the default value is `library`.
Possible values are `library` or `kernel`.
2. The architectures that can be supported.
Optional. By default OSDK supports all architectures.
When building or running,
if not specified in the CLI,
the architecture of the host machine will be used.
Possible values are `aarch64`, `riscv64`, `x86_64`.
3. Options for compilation stage.
4. Cargo features to activate.
Optional. The default value is empty.
Only features defined in `Cargo.toml` can be added to this array.
5. Build artifacts with the specified Cargo profile.
Optional. The default value is `dev`.
Possible values are `dev`, `release`, `test` and `bench`
and other profiles defined in `Cargo.toml`.
6. Whether to strip the built kernel ELF using `rust-strip`.
Optional. The default value is `false`.
7. Options for booting the kernel.
8. The boot method.
Optional. The default value is `qemu-direct`.
Possible values are `grub-rescue-iso`, `grub-qcow2` and `qemu-direct`.
9. The arguments provided will be passed to the guest kernel.
Optional. The default value is empty.
@ -84,12 +126,44 @@ Here are some additional notes for the fields:
`KEY=VALUE` or `KEY` if no value is required.
Each `KEY` can appear at most once.
2. The arguments provided will be passed to the init process,
10. The arguments provided will be passed to the init process,
usually, the init shell.
Optional. The default value is empty.
3. Additional arguments passed to QEMU that is organized in a single string that
11. The path to the initramfs.
Optional. The default value is empty.
If the path is relative, it is relative to the manifest's enclosing directory.
12. Grub options. Only take effect if boot method is `grub-rescue-iso` or `grub-qcow2`.
13. The path to the `grub-mkrescue` executable.
Optional. The default value is the executable in the system path, if any.
If the path is relative, it is relative to the manifest's enclosing directory.
14. The protocol GRUB used.
Optional. The default value is `multiboot2`.
Possible values are `linux`, `multiboot`, `multiboot2`.
15. Whether to display the GRUB menu when booting with GRUB.
Optional. The default value is `false`.
16. Options for finding and starting QEMU.
17. The path to the QEMU executable.
Optional. The default value is the executable in the system path, if any.
If the path is relative, it is relative to the manifest's enclosing directory.
18. Additional arguments passed to QEMU that is organized in a single string that
can have any POSIX shell compliant separators.
Optional. The default value is empty.
@ -108,63 +182,32 @@ can have any POSIX shell compliant separators.
even use this mechanism to read from files by using command replacement
`$(cat path/to/your/custom/args/file)`.
19. Special settings for running. Only take effect when running `cargo osdk run`.
By default, it inherits common options.
Values set here are used to override common options.
20. Special settings for testing.
Similar to `19`, but only take effect when running `cargo osdk test`.
21. The definition of customized schema.
A customized schema has the same fields as the default schema.
By default, a customized schema will inherit all options from the default schema,
unless overrided by new options.
### Example
Here is a sound, self-explanatory example similar to our usage
of OSDK in the Asterinas project.
Here is a sound, self-explanatory example which is used by OSDK
in the Asterinas project.
In the script `./tools/qemu_args.sh`, the environment variables will be
used to determine the actual set of qemu arguments.
```toml
project_type = "kernel"
[boot]
method = "grub-rescue-iso"
[run]
boot.kcmd_args = [
"SHELL=/bin/sh",
"LOGNAME=root",
"HOME=/",
"USER=root",
"PATH=/bin:/benchmark",
"init=/usr/bin/busybox",
]
boot.init_args = ["sh", "-l"]
boot.initramfs = "regression/build/initramfs.cpio.gz"
[test]
boot.method = "qemu-direct"
[grub]
protocol = "multiboot2"
display_grub_menu = true
[qemu]
args = "$(./tools/qemu_args.sh)"
[scheme."microvm"]
boot.method = "qemu-direct"
qemu.args = "$(./tools/qemu_args.sh microvm)"
[scheme."iommu"]
supported_archs = ["x86_64"]
qemu.args = "$(./tools/qemu_args.sh iommu)"
[scheme."intel_tdx"]
supported_archs = ["x86_64"]
build.features = ["intel_tdx"]
boot.method = "grub-qcow2"
grub.mkrescue_path = "~/tdx-tools/grub"
grub.protocol = "linux"
qemu.args = """\
-accel kvm \
-name process=tdxvm,debug-threads=on \
-m ${MEM:-8G} \
-smp $SMP \
-vga none \
"""
{{#include ../../../../OSDK.toml}}
```
### Scheme