From 3788b2c96fd2d2957d5a8490f06f67fa7f32d3bc Mon Sep 17 00:00:00 2001 From: Zhigang Wang Date: Wed, 23 Sep 2020 16:26:07 +0800 Subject: [PATCH] doc: adding more details and fix typo in docs 1. Delete README.en.md 2. Refactor README.md(adding links for design.md and guide.md) 3. Update docs/ 4. Refactor log-level env to "STRATOVIRT_LOG_LEVEL" Signed-off-by: Yang Xiaohe Signed-off-by: Zhigang Wang --- README.en.md | 36 ------- README.md | 45 +++++---- ...oVirt-Guidebook.md => config_guidebook.md} | 99 ++++++++++--------- docs/default.json | 4 +- docs/design.md | 37 ++++--- docs/mk_initrd.md | 2 +- docs/quickstart.md | 59 ++++++----- util/src/logger.rs | 2 +- 8 files changed, 127 insertions(+), 157 deletions(-) delete mode 100644 README.en.md rename docs/{StratoVirt-Guidebook.md => config_guidebook.md} (76%) diff --git a/README.en.md b/README.en.md deleted file mode 100644 index 36050c796..000000000 --- a/README.en.md +++ /dev/null @@ -1,36 +0,0 @@ -# stratovirt - -#### Description -StratoVirt is an opensource VMM(Virtual Machine Manager) which aims to perform next generation virtualization.StratoVirt is based on Rust programming language.StratoVirt is lightweight, efficient and safe.It also has features like Full Sence Support and Modules Flexible Splitting. - -#### Software Architecture -Software architecture description - -#### Installation - -1. xxxx -2. xxxx -3. xxxx - -#### Instructions - -1. xxxx -2. xxxx -3. xxxx - -#### Contribution - -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request - - -#### Gitee Feature - -1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md -2. Gitee blog [blog.gitee.com](https://blog.gitee.com) -3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) -4. The most valuable open source project [GVP](https://gitee.com/gvp) -5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) -6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/README.md b/README.md index 0810b3ff7..7ac244519 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,32 @@ # StratoVirt - StratoVirt is an opensource VMM(Virtual Machine Manager) which aims to perform -next generation virtualization.StratoVirt is based on Rust programming -language.StratoVirt is lightweight, efficient and safe.It also has features like -Full Sence Support and Modules Flexible Splitting. +next generation virtualization. -StratoVirt is based on Rust language, which ensures the high performance in -safety and efficiency. +Based on Rust programming language, StratoVirt is lightweight, efficient and safe. +StratoVirt reduces memory resource consumption and improves VM startup speed while +retains isolation capability and security capability of traditional virtualization. -StratoVirt supports live-time remote control with qmp commands. +StratoVirt supports communicating with external systems using OCI compatible Interface, +and can be applied to microservices or serverless scenarios. -In the future, StratoVirt would be capable of virtualizing normal machines -with specific hardware emulators. +StratoVirt reserves interface and design for importing more features, even standard virtualization. ## How to start ### Preparation Before building StratoVirt, make sure that Rust language and Cargo have already -been installed, if not, you can install Rust and cargo from following links: +been installed. If not, you can find installation guidance from the following link: https://www.rust-lang.org/tools/install ### Build StratoVirt -To build StratoVirt, go to the project's directory and make use of Cargo: +To build StratoVirt, clone the project and build it first: ```sh -$ git clone https://gitee.com/src-openeuler/stratovirt.git +$ git clone https://gitee.com/openeuler/stratovirt.git $ cd stratovirt $ cargo build --release ``` -Now you can find StratoVirt binary in `target/debug/stratovirt` +Now you can find StratoVirt binary in `target/release/stratovirt`. ### Run a VM with StratoVirt To run StratoVirt quickly, requires @@ -36,6 +34,7 @@ To run StratoVirt quickly, requires * An EXT4-format rootfs image ```shell +# If the socket of api-channel exists, remove if first. $ ./target/release/stratovirt \ -kernel /path/to/kernel \ -append console=ttyS0 root=/dev/vda reboot=k panic=1 \ @@ -44,19 +43,25 @@ $ ./target/release/stratovirt \ -serial stdio ``` -Running a VM with json configuration file is also supported, -please refer to [quickstart guide](./docs/quickstart.md) for more details. +The detailed guidance of making rootfs, compiling kernel and building StratoVirt can be found +in [StratoVirt QuickStart](./docs/quickstart.md). + +StratoVirt supports much more features, the detailed guidance can be found in [Configuration Guidebook](docs/config_guidebook.md). + +## Design + +To get more details about StratoVirt's core architecture design, refer to [StratoVirt design](./docs/design.md). ## How to contribute -We welcome new contributors! If you want to join us, please -take a glance at the Rust formatting guidance first: +We welcome new contributors! And we are happy to provide guidance and help for new contributors. +StratoVirt follows Rust formatting conventions, which can be found at: https://github.com/rust-dev-tools/fmt-rfcs/tree/master/guide +https://github.com/rust-lang/rust-clippy -Use `cargo clippy` to check and improve your code, the installation guidance -and usage is as below: +You can get more information about StratoVirt at: -https://github.com/rust-lang/rust-clippy +https://gitee.com/openeuler/stratovirt/wikis ## Licensing StratoVirt is licensed under the Mulan PSL v2. diff --git a/docs/StratoVirt-Guidebook.md b/docs/config_guidebook.md similarity index 76% rename from docs/StratoVirt-Guidebook.md rename to docs/config_guidebook.md index 5e94eb669..00641e8c0 100644 --- a/docs/StratoVirt-Guidebook.md +++ b/docs/config_guidebook.md @@ -10,10 +10,9 @@ StratoVirt supports json configuration file and cmdline arguments. If you set th StratoVirt supports to set the number of VCPUs(**nr_vcpus**). -This allows you to set the maximum number of VCPUs that VM will support. The maximum supported - value is 254 and the minimum value that makes sense is 1. +This allows you to set the maximum number of VCPUs that VM will support. The maximum value is 254 and the minimum value that makes sense is 1. -By default, after booted, VM will online all cpu you set. +By default, after booted, VM will online all CPUs you set. ```shell # cmdline @@ -31,11 +30,12 @@ By default, after booted, VM will online all cpu you set. ### 1.2 Memory Size -StratoVirt supports to set the size of VM's memory. +StratoVirt supports to set the size of VM's memory in cmdline. This allows you to set the size of memory that VM will support. -If you use cmdline arguments to set it, you can give `M` or `G` as units (default units is `Kib`). -For json configuration file, memory unit is not supported. +You can choose `M` or `G` as unit (default unit is `Kib`). + +But unfortunately, in json configuration file, only `byte` are supported as unit. ```shell # cmdline @@ -56,12 +56,12 @@ For json configuration file, memory unit is not supported. ### 1.3 Kernel and Kernel Parameters -StratoVirt supports to launch (PE format) linux kernel 4.19 and can also set kernel +StratoVirt supports to launch PE-format linux kernel 4.19 and can also set kernel parameters for VM. -This allows you to give a path to linux kernel, the path can be absolute path or relative path. +This allows you to give a path to linux kernel, the path can be either absolute path or relative path. -And given kernel parameters will be actually interpreted by boot loader. +And the given kernel parameters will be actually analyzed by boot loader. ``` shell # cmdline @@ -81,20 +81,19 @@ And given kernel parameters will be actually interpreted by boot loader. ### 1.4 Initrd Configuration -StratoVirt supports to launch VM by a initrd (boot loader initialized RAM disk). +StratoVirt supports to launch VM by a initrd (boot loader initialized RAM disk) as well. -This allows you to give a path to initrd image. This image will be loaded to ram by boot loader. +If the path to initrd image is configured, it will be loaded to ram by boot loader. -If you want to use initrd as rootfs, you can add `root=` and `rdinit=` in Kernel Parameters. +If you want to use initrd as rootfs, `root=/dev/ram` and `rdinit=/bin/sh` must be added in Kernel Parameters. ```shell # cmdline --initrd /Images/initrd +-initrd /path/to/initrd # json { "boot-source": { - "boot_args": "console=ttyS0 reboot=k panic=1 pci=off tsc=reliable ipv6.disable=1 root=/dev/ram rdinit=/bin/sh", "initrd_fs_path": "/path/to/initrd", ... }, @@ -104,20 +103,19 @@ If you want to use initrd as rootfs, you can add `root=` and `rdinit=` in Kernel ## 2. Device Configuration -StratoVirt supports to deploy one kind of legacy device and four kinds of virtio-mmio device. +StratoVirt supports to deploy one kind of legacy device and four kinds of virtio-mmio devices. -The max number of device is 16 in x86_64 platform and 32 in aarch64 platform. +The max number of devices is 16 on x86_64 platform and 32 on aarch64 platform. ### 2.1 Virtio-blk -Virtio block device is a virtual block device, instead of placing write and read requests with the - actual device. +Virtio block device is a virtual block device, which process read and write requests in virtio queue from guest. -Five properties are supported for virtio block device you can set. +Five properties are supported for virtio block device. -* drive_id: unique device-id presented for StratoVirt +* drive_id: unique device-id in StratoVirt * path_on_host: the path of block device in host -* serial_num: serial number for virtio block (Optional) +* serial_num: serial number of virtio block (Optional) * read_only: whether virtio block device is read_only or not * direct: open block device with `O_DIRECT` mode or not @@ -146,11 +144,11 @@ If you want to boot VM with a virtio block device as rootfs, you should add `roo ### 2.2 Virtio-net -Virtio-net is a virtual Ethernet card in VM. It can enable VM network capability. +Virtio-net is a virtual Ethernet card in VM. It can enable the network capability of VM. Three properties are supported for virtio net device. -* iface_id: unique device-id presented for StratoVirt +* iface_id: unique device-id in StratoVirt * host_dev_name: name of tap device in host * mac: set mac address in VM (Optional) @@ -171,7 +169,7 @@ Three properties are supported for virtio net device. } ``` -StratoVirt also supports vhost-net to get a higher-performance in network. +StratoVirt also supports vhost-net to get a higher performance in network. It can be set by given `vhost` property. @@ -199,7 +197,7 @@ It can be set by given `vhost` property. # In host $ brctl addbr qbr0 $ ip tuntap add tap0 mode tap -$ brctl addif qbr0 +$ brctl addif qbr0 tap0 $ ifconfig qbr0 up; ifconfig tap0 up $ ifconfig qbr0 1.1.1.1 @@ -217,12 +215,12 @@ $ ping 1.1.1.1 ### 2.3 Virtio-console Virtio console is a general-purpose serial device for data transfer between the guest and host. - Character devices at /dev/hvc0 to /dev/hvc7 in guest will be created once setting it. In host, - it will be presented as a UnixSocket. +Character devices at /dev/hvc0 to /dev/hvc7 in guest will be created once setting it. +In host, it will be presented as a UnixSocket. Two properties can be set for virtio console device. -* console_id: unique device-id presented for StratoVirt +* console_id: unique device-id in StratoVirt * socket_path: the path of virtio console socket in the host ```shell @@ -243,7 +241,7 @@ Two properties can be set for virtio console device. ### 2.4 Virtio-vsock -Virtio vsock is a host/guest communications device like virtio console, but higher performance. +Virtio vsock is a host/guest communication device like virtio console, but it has higher performance. If you want use it, need: @@ -254,7 +252,7 @@ And `modprobe vhost_vsock` in the host. Two properties can be set for virtio vsock device. -* vsock_id: unique device-id presented for StratoVirt +* vsock_id: unique device-id in StratoVirt * guest_cid: a unique Context-ID in host to each guest, it should satisfy `3<=guest_cid /tmp/StratoVirt-initrd ``` -## 6. Running StratoVirt with initrd +## 6. Run StratoVirt with initrd ```shell $ ./stratovirt \ diff --git a/docs/quickstart.md b/docs/quickstart.md index bc8cefb57..142c9ab71 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,13 +4,13 @@ * Host os - StratoVirt supports host os Linux 4.19 in both x86_64 and aarch64 platform. + You can run StratoVirt on both x86_64 and aarch64 platforms. - KVM mod should be supported in your host Linux kernel. + And on top of that, the StratoVirt is based on KVM, so please make sure you have KVM module on your platform. * Authority - You should have read/write access to `/dev/kvm`. If not, you can get your access by: + You should have read/write permissions to `/dev/kvm`. If not, you can get your permissions by: ```shell $ sudo setfacl -m u:${USER}:rw /dev/kvm @@ -19,8 +19,8 @@ ### 2.1 Check rust environment -To build StratoVirt, make sure that Rust language environment and Cargo have already installed. - The version of rustc is suggested up to 1.42. +To build StratoVirt, make sure that Rust language environment and Cargo have already been installed. + The recommended version of rustc is 1.42 or later. ```shell $ rustc -version @@ -33,7 +33,7 @@ If you want to deploy rust environment, the following link will help you: ### 2.2 Build with musl-libc -With musl-libc, StratoVirt is linked statically and having no library dependencies. It's the +With musl-libc, StratoVirt is linked statically and has no library dependencies. It's the default target to build StratoVirt. ```shell @@ -45,11 +45,11 @@ $ rustup target add ${arch}-unknown-linux-musl $ cargo build --release --target ${arch}-unknown-linux-musl ``` -Now you can find StratoVirt binary in `target/${arch}-unknown-linux-musl/release/stratovirt`. +Now you can find StratoVirt binary file in `target/${arch}-unknown-linux-musl/release/stratovirt`. ### 2.3 Build with glibc -StratoVirt can also build using glibc toolchains. By this way, StratoVirt is linked dynamically. +StratoVirt can also be built using glibc toolchains. By this way, StratoVirt is linked dynamically. ```shell # Add gnu rust tool-chain, if installed, skip @@ -60,13 +60,13 @@ $ rustup target add ${arch}-unknown-linux-gnu $ cargo build --release --target ${arch}-unknown-linux-gnu ``` -Now you can find StratoVirt binary in `target/${arch}-unknown-linux-gnu/release/stratovirt`. +Now you can find StratoVirt binary file in `target/${arch}-unknown-linux-gnu/release/stratovirt`. -## 3. Get Kernel and rootfs Image +## 3. Prepare Kernel and rootfs Image ### 3.1 Build kernel -The current version StratoVirt supports only PE-format kernel images in both x86_64 and aarch64 +The StratoVirt in current version supports only PE-format kernel images on both x86_64 and aarch64 platforms, which can be built with: 1. Firstly, get the openEuler kernel source code: @@ -76,14 +76,14 @@ platforms, which can be built with: $ cd kernel ``` -2. Check out the kernel version to kernel-4.19: +2. Switch the kernel version to kernel-4.19: ```shell $ git checkout kernel-4.19 ``` -3. Configure your linux kernel build. You can use [our recommended config](./kernel_config) and -copy it to `kernel` path as `.config`. You can interactive config by: +3. Configure your linux kernel. You can use [our recommended config](./kernel_config) and +copy it to `kernel` path as `.config`. You can also modify config options by: ```shell $ make menuconfig @@ -97,7 +97,7 @@ copy it to `kernel` path as `.config`. You can interactive config by: ### 3.2 Make rootfs -Rootfs image is a file system image. An EXT4-format image with an `init` can be mounted at +Rootfs image is a file system image. An EXT4-format image with `/sbin/init` can be mounted at boot time in StratoVirt. Below is a simple way to make a EXT4 rootfs image: 1. Prepare a properly-sized file(e.g. 1G): @@ -115,6 +115,7 @@ Rootfs image is a file system image. An EXT4-format image with an `init` can be 3. Mount the file image: ```shell + $ mkdir -p /mnt/rootfs $ sudo mount ./rootfs.ext4 /mnt/rootfs && cd /mnt/rootfs ``` @@ -130,7 +131,7 @@ Rootfs image is a file system image. An EXT4-format image with an `init` can be 5. Make a simple `/sbin/init` for EXT4 file image. ```shell - $ cat > sbin/init < sbin/init <>) -> Result<(), SetLoggerError> { - let level = match std::env::var("QUANTVISOR_LOG_LEVEL") { + let level = match std::env::var("STRATOVIRT_LOG_LEVEL") { Ok(l) => match l.to_lowercase().as_str() { "trace" => Level::Trace, "debug" => Level::Debug, -- Gitee