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

Update documents for the OSDK overhaul

Browse Source
This commit is contained in:
Zhang Junyang 2024-03-22 17:33:32 +08:00 committed by Tate, Hongliang Tian
parent 33c53dcf2b
commit dcab4e1039
1 changed files with 88 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -32,27 +32,70 @@ Below, you will find a comprehensive version of
the available configuration options in the manifest.
```toml
kcmd_args = ["init=/bin/busybox", "path=/usr/local/bin"] # <1>
init_args = ["sh", "-l"] # <2>
initramfs="./build/initramfs.cpio.gz" # <3>
[project] # <1>
type = "kernel"
[boot]
loader = "grub" # <4>
protocol = "multiboot2" # <5>
grub-mkrescue = "/usr/bin/grub-mkrescue" # <6>
ovmf = "/usr/bin/ovmf" # <7>
[run] # <2>
kcmd_args = ["init=/bin/busybox", "path=/usr/local/bin"] # <3>
init_args = ["sh", "-l"] # <4>
initramfs="./build/initramfs.cpio.gz" # <5>
bootloader = "grub" # <6>
boot_protocol = "multiboot2" # <7>
grub-mkrescue = "/usr/bin/grub-mkrescue" # <8>
ovmf = "/usr/bin/ovmf" # <9>
qemu_path = "/usr/bin/qemu-system-x86_64" # <10>
qemu_args = [ # <11>
"-machine q35,kernel-irqchip=split",
"-cpu Icelake-Server,+x2apic",
"-m 2G",
]
[qemu]
path = "/usr/bin/qemu-system-x86_64" # <8>
machine = "q35" # <9>
args = [ # <10>
"-enable-kvm",
"-m 2G",
"-device virtio-keyboard-pci,disable-legacy=on,disable-modern=off"
]
[test] # <2>
bootloader = "qemu"
qemu_args = [ # <10>
"-machine q35,kernel-irqchip=split",
"-cpu Icelake-Server,+x2apic",
"-m 2G",
]
['cfg(arch="x86_64", schema=microvm)'.run] # <12>
bootloader = "qemu"
qemu_args = [ # <10>
"-machine microvm,rtc=on",
"-cpu Icelake-Server,+x2apic",
"-m 2G",
]
```
1. The arguments provided will be passed to the guest kernel.
### Root level configurations
Fields in the given manifest marked with "1", "2" and "12" are
root level configurations.
1. The OSDK project specs `project`.
Currently, OSDK only need to know the type of the project.
We have two types of projects introduced with OSDK, which
are `kernel` and `library`. An OSDK project should be a
crate that reside in the directory of a crate or a workspace.
2. Running and testing actions settings `run` and `test`.
These two fields describe the action that are needed to
perform running or testing commands. The configurable values
of the actions are described by 3~11, which specifies how
would the OSDK invoke the VMM. The build action refers to
the run action and smartly build anything that the run action
need (e.g. a VM image or a kernel image with the appropriate
format).
Also, you can specify different actions depending on the
scenarios. You can do that by the `cfg` feature described
in the section [Cfg](#Cfg).
### Action configurations
3. The arguments provided will be passed to the guest kernel.
Optional. The default value is empty.
@ -60,30 +103,32 @@ args = [ # <10>
`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,
4. The arguments provided will be passed to the init process,
usually, the init shell.
Optional. The default value is empty.
3. The path to the built initramfs.
5. The path to the built initramfs.
Optional. The default value is empty.
4. The bootloader used to boot the kernel.
6. The bootloader used to boot the kernel.
Optional. The default value is `grub`.
The allowed values are `grub` and `qemu`
(`qemu` indicates that QEMU directly boots the kernel).
5. The boot protocol used to boot the kernel.
7. The boot protocol used to boot the kernel.
Optional. The default value is `multiboot2`.
Except that for QEMU direct boot (when `bootloader` is "qemu"`),
`multiboot` will be used.
The allowed values are `linux-efi-handover64`,
`linux-legacy32`, `multiboot`, and `multiboot2`.
6. The path of `grub-mkrescue`,
8. The path of `grub-mkrescue`,
which is used to create a GRUB CD_ROM.
Optional. The default value is system path,
@ -92,25 +137,21 @@ which is used to create a GRUB CD_ROM.
This argument only takes effect
when the bootloader is `grub`.
7. The path of OVMF. OVMF enables UEFI support for QEMU.
9. The path of OVMF. OVMF enables UEFI support for QEMU.
Optional. The default value is empty.
This argument only takes effect
when the boot protocol is `linux-efi-handover64`.
8. The path of QEMU.
10. The path of QEMU.
Optional. The default value is system path,
determined using `which qemu-system-x86_64`.
Optional. If you want to use a customized QEMU this
is the way. Otherwise we will look from the `PATH`
environment variable for the QEMU command with appropriate
architecture.
9. The machine type of QEMU.
Optional. Default is `q35`.
The allowed values are `q35` and `microvm`.
10. Additional arguments passed to QEMU.
11. Additional arguments passed to QEMU.
Optional. The default value is empty.
@ -123,3 +164,17 @@ which is used to create a GRUB CD_ROM.
Certain keys, such as `-cpu` and `-machine`,
are not allowed to be set here
as they may conflict with the internal settings of OSDK.
### Cfg
Cfg is an advanced feature to create multiple profiles for
the same actions under different scenarios. Currently we
have two configurable keys, which are `arch` and `schema`.
The key `arch` has a fixed set of values which is aligned
with the CLI `--arch` argument. If an action has no specified
arch, it matches all the architectures. The key `schema` allows
user-defined values and can be selected by the `--schema` CLI
argument. The key `schema` can be used to create special settings
(especially special QEMU configurations). If a cfg action is
matched, unspecified and required arguments will be inherited
from the action that has no cfg (i.e. the default action setting).