Update OSDK reference

docs/src/SUMMARY.md

@@ -24,13 +24,13 @@
     * [Creating an OS Project](osdk/guide/create-project.md)
     * [Testing or Running an OS Project](osdk/guide/run-project.md)
     * [Working in a Workspace](osdk/guide/work-in-workspace.md)
-* [OSDK User Reference]()
+* [OSDK User Reference](osdk/reference/README.md)
-    * [Commands]()
+    * [Commands](osdk/reference/commands/README.md)
-        * [cargo osdk new]()
+        * [cargo osdk new](osdk/reference/commands/new.md)
-        * [cargo osdk build]()
+        * [cargo osdk build](osdk/reference/commands/build.md)
-        * [cargo osdk run]()
+        * [cargo osdk run](osdk/reference/commands/run.md)
-        * [cargo osdk test]()
+        * [cargo osdk test](osdk/reference/commands/test.md)
-    * [Manifest]()
+    * [Manifest](osdk/reference/manifest.md)
 
 # How to Contribute
 

docs/src/osdk/reference/README.md

@@ -1 +1,28 @@
 # OSDK User Reference
+
+OSDK is a command line tool that can be used as a subcommand of Cargo. The common usage of OSDK is:
+
+```bash
+cargo osdk <COMMAND>
+```
+
+You can use `cargo osdk -h` to see the full list of available commands. For the specific usage of a subcommand, you can use `cargo osdk help <COMMAND>`.
+
+## Manifest
+
+OSDK utilizes a manifest named `OSDK.toml` to define its precise behavior regarding how to run a kernel with QEMU. The `OSDK.toml` file should be placed in the same folder as the project's `Cargo.toml`. The [Manifest documentation](manifest.md) provides an introduction to all the available configuration options.
+
+The command line tool can also be used to set the options in the manifest. If both occur, the command line options will always take priority over the options in the manifest. For example, if the manifest defines the path of QEMU as:
+
+```toml
+[qemu]
+path = "/usr/bin/qemu-system-x86_64"
+```
+
+But the user provides a new QEMU path when running the project using:
+
+```bash
+cargo osdk run --qemu.path="/usr/local/qemu-kvm"
+```
+
+Then, the actual path of QEMU should be `/usr/local/qemu-kvm` since command line options have higher priority.

docs/src/osdk/reference/commands/README.md

@@ -1 +1,14 @@
 # Commands
+
+OSDK provides similar commands as Cargo, and these commands have simalar meanings as corresponding Cargo commands.
+
+Currently, OSDK supports the following commands: 
+
+- **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
+- **check**: Analyze the current package and report errors
+- **clippy**: Check the current package and catch common mistakes
+
+The **new**, **build**, **run** and **test** commands can accept additional options, while the **check** and **clippy** commands cannot.

docs/src/osdk/reference/commands/build.md

@@ -1 +1,46 @@
 # cargo osdk build
+
+## Overview
+
+The `cargo osdk build` command is used to compile the project and its dependencies. The usage is as follows:
+
+```bash
+cargo osdk build [OPTIONS]
+```
+
+## Options
+The options can be divided into two types: Cargo options that can be accepted by Cargo, and Manifest options that can also be defined in the manifest named `OSDK.toml`.
+
+### Cargo options
+
+- `--profile <PROFILE>`: Build artifacts with the specified Cargo profile (built-in candidates are 'dev', 'release', 'test', and 'bench') [default: dev]
+- `--release`: Build artifacts in release mode, with optimizations
+- `--features <FEATURES>`: Space or comma separated list of features to activate
+
+### Manifest options
+
+These options can also be defined in the project's manifest named `OSDK.toml`. Command line options are used to override or append values in `OSDK.toml`. The allowed values for each option can be found in the [Manifest Documentation](../manifest.md).
+
+- `--kcmd_args <ARGS>`: Command line arguments for the guest kernel
+- `--init_args <ARGS>`: Command line arguments for the init process
+- `--initramfs <PATH>`: Path of the initramfs
+- `--boot.ovmf <PATH>`: Path of the OVMF directory
+- `--boot.loader <LOADER>`: Loader for booting the kernel
+- `--boot.protocol <PROTOCOL>`: Protocol for booting the kernel
+- `--qemu.path <PATH>`: Path of QEMU
+- `--qemu.machine <MACHINE>`: QEMU machine type
+- `--qemu.args <ARGS>`: Arguments for running QEMU
+
+## Examples
+
+- Build a project with `./initramfs.cpio.gz` as the initramfs and `multiboot2` as the boot portocol: 
+
+```bash
+cargo osdk build --initramfs="./initramfs.cpio.gz" --boot.protocol="multiboot2"
+```
+
+- Build a project and append `sh`, `-l` to init process arguments: 
+
+```bash
+cargo osdk build --init_args="sh" --init_args="-l"
+```

docs/src/osdk/reference/commands/new.md

@@ -1 +1,31 @@
 # cargo osdk new
+
+## Overview
+
+The `cargo osdk new` command is used to create a kernel project or a new library project. The usage is as follows:
+
+```bash
+cargo osdk new [OPTIONS] <name>
+```
+
+## Arguments
+
+`<name>`: the name of the crate. 
+
+## Options
+
+`--kernel`: Use the kernel template. If this option is not set, the library template will be used by default.
+
+## Examples
+
+- Create a new kernel named `myos`: 
+
+```bash
+cargo osdk new --kernel myos
+```
+
+- Create a new library named `mymodule`: 
+
+```bash
+cargo osdk new mymodule
+```

docs/src/osdk/reference/commands/run.md

@@ -1 +1,13 @@
 # cargo osdk run
+
+## Overview
+
+`cargo osdk run` is used to run the kernel with QEMU. The usage is as follows:
+
+```bash
+cargo osdk run [OPTIONS]
+```
+
+## Options
+
+The options are the same as those of `cargo osdk build`. Refer to the [documentation](build.md) of `cargo osdk build` for more details.

docs/src/osdk/reference/commands/test.md

@@ -1 +1,22 @@
 # cargo osdk test
+
+`cargo osdk test` is used to execute kernel mode unit test by starting QEMU. The usage is as follows:
+
+```bash
+cargo osdk test [OPTIONS] [TESTNAME]
+```
+
+## Arguments 
+
+[TESTNAME]: Only run tests containing this string in their names
+
+## Options
+
+The options are the same as those of `cargo osdk build`. 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: 
+
+```bash
+cargo osdk test foo --qemu.machine="q35"
+```

docs/src/osdk/reference/manifest.md

@@ -1 +1,64 @@
 # Manifest
+
+## Overview
+
+OSDK utilizes a manifest to define its precise behavior. Typically, the configuration file is named `OSDK.toml` and is placed in the root directory of the workspace (the same directory as the workspace's `Cargo.toml`). If there is only one crate and no workspace, the file is placed in the crate's root directory.
+
+For a crate inside workspace, it may have two related manifests, one is of the workspace (the `OSDK.toml` in the same directory as the workspace's `Cargo.toml`) and one of the crate (in the same directory as the crate's `Cargo.toml`). So which manifest should be used? The rules are
+- If running commands in the workspace root directory, the `OSDK.toml` of the workspace will be used
+- If running commands in the crate directory
+  - If the crate has `OSDK.toml`, the `OSDK.toml` of the crate will be used. 
+  - Otherwise, `the OSDK.toml` of the workspace will be used.
+
+## Configurations
+
+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>
+
+[boot]
+loader = "grub" # <4>
+protocol = "multiboot2" # <5>
+grub-mkrescue = "/usr/bin/grub-mkrescue" # <6>
+ovmf = "/usr/bin/ovmf" # <7>
+
+[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"
+] 
+```
+
+1. The arguments provided will be passed to the guest kernel.   
+Optional. The default value is empty.   
+Each argument should be in one of the following two forms: `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, usually, the init shell.   
+Optional. The default value is empty.
+3. The path to the built initramfs.  
+Optional. The default value is empty.
+4. 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.    
+Optional. The default value is `multiboot2`.    
+The allowed values are `linux-efi-handover64`, `linux-legacy32`, `multiboot`, and `multiboot2`.
+6. The path of `grub-mkrescue`, which is used to create a GRUB CD_ROM.   
+Optional. The default value is system path, determined using `which grub-mkrescue`.   
+This argument only takes effect when the bootloader is `grub`.   
+7. 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.  
+Optional. The default value is system path, determined using `which qemu-system-x86_64`.  
+9. The machine type of QEMU.  
+Optional. Default is `q35`.  
+The allowed values are `q35` and `microvm`.  
+10. Additional arguments passed to QEMU.   
+Optional. The default value is empty.   
+Each argument should be in the form `KEY VALUE` (separated by space), or `KEY` if no value is required. Some keys can appear multiple times (e.g., `-device`, `-netdev`), while other keys can appear at most once. Certain keys, such as `-cpu` and `-machine`, are not allowed to be set here as they may conflict with the internal settings of OSDK.  

osdk/README.md

@@ -146,7 +146,7 @@ Optional. Default is `q35`.
 The allowed values are `q35` and `microvm`.  
 10. Additional arguments passed to QEMU.   
 Optional. The default value is empty.   
-Each argument should be in the form `KEY VALUE` (separated by space), or `KEY` if no value is required. Some keys can appear multiple times (e.g., `-device`, `-netdev`), while other keys can appear at most once. Certain keys, such as `-cpu` and `-machine`, are not allowed to be set here as they may conflict with the internal settings of `cargo-osdk`.
+Each argument should be in the form `KEY VALUE` (separated by space), or `KEY` if no value is required. Some keys can appear multiple times (e.g., `-device`, `-netdev`), while other keys can appear at most once. Certain keys, such as `-cpu` and `-machine`, are not allowed to be set here as they may conflict with the internal settings of `cargo-osdk`.  
 11. Conditional QEMU settings.   
 Optional. The default value is empty.   
 Conditional QEMU settings allow for a condition to be specified after `qemu`. Currently, `cargo-osdk` only supports the condition `cfg(feature="FEATURE")`, which activates the QEMU settings only if the `FEATURE` is set. The `FEATURE` must be defined in the project's `Cargo.toml`. At most one conditional setting can be activated at a time. If multiple conditional settings can be activated simultaneously, `cargo-osdk` will report an error. In the future, `cargo-osdk` will support all possible conditions that [Rust conditional compilation](https://doc.rust-lang.org/reference/conditional-compilation.html) supports.