diff --git a/docs/src/osdk/reference/manifest.md b/docs/src/osdk/reference/manifest.md index 538c76a1..c284b1c6 100644 --- a/docs/src/osdk/reference/manifest.md +++ b/docs/src/osdk/reference/manifest.md @@ -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).