From 889caa3552c8fd305120d38f934c607b04a1636c Mon Sep 17 00:00:00 2001
From: Wei Gao <gaowei66@huawei.com>
Date: Fri, 2 Apr 2021 11:11:31 +0800
Subject: [PATCH 2/2] docs: update quickstart.md to use openEuler 21.03
 stratovirt_img.

Signed-off-by: Wei Gao <gaowei66@huawei.com>
---
 docs/boot_source.md |  96 ++++++++++++++++++
 docs/build_guide.md |  47 +++++++++
 docs/quickstart.md  | 240 ++++++++++----------------------------------
 3 files changed, 196 insertions(+), 187 deletions(-)
 create mode 100644 docs/boot_source.md
 create mode 100644 docs/build_guide.md

diff --git a/docs/boot_source.md b/docs/boot_source.md
new file mode 100644
index 00000000..36ca7286
--- /dev/null
+++ b/docs/boot_source.md
@@ -0,0 +1,96 @@
+# Build StratoVirt Boot Souce
+
+## 1. Build kernel
+
+The StratoVirt in current version supports PE or bzImage (only x86_64) format kernel images on
+both x86_64 and aarch64 platforms, which can be built with:
+
+1. Firstly, get the openEuler kernel source code with:
+
+   ```shell
+   $ git clone -b kernel-5.10 --depth=1 https://gitee.com/openeuler/kernel
+   $ cd kernel
+   ```
+
+   If you use our openEuler 21.03, you can also acquire kernel source with yum:
+   
+   ```shell
+   $ sudo yum install kernel-source
+   $ cd /usr/src/linux-5.10.0-0.0.0.7.oe1.$(uname -m)/
+   ```
+
+2. 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
+   ```
+
+3. Build and transform kernel image to PE format.
+
+   ```shell
+   $ make -j vmlinux && objcopy -O binary vmlinux vmlinux.bin
+   ```
+
+5. If you want compile bzImage format kernel in x86_64.
+   ```shell
+   $ make -j bzImage
+   ```
+
+## 2. Make rootfs
+
+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):
+
+   ```shell
+   $ dd if=/dev/zero of=./rootfs.ext4 bs=1G count=20
+   ```
+
+2. Create an empty EXT4 file system on this file:
+
+   ```shell
+   $ mkfs.ext4 ./rootfs.ext4
+   ```
+
+3. Mount the file image:
+
+   ```shell
+   $ mkdir -p /mnt/rootfs
+   $ sudo mount ./rootfs.ext4 /mnt/rootfs && cd /mnt/rootfs
+   ```
+
+4. Get the [latest alpine-minirootfs](http://dl-cdn.alpinelinux.org/alpine):
+
+   ```shell
+   $ arch=`uname -m`
+   $ wget http://dl-cdn.alpinelinux.org/alpine/latest-stable/releases/$arch/alpine-minirootfs-3.13.0-$arch.tar.gz -O alpine-minirootfs.tar.gz
+   $ tar -zxvf alpine-minirootfs.tar.gz
+   $ rm alpine-minirootfs.tar.gz
+   ```
+
+   Make a simple `/sbin/init` for EXT4 file image.
+
+   ```shell
+   $ rm sbin/init && touch sbin/init && cat > sbin/init <<EOF
+   #! /bin/sh
+   mount -t devtmpfs dev /dev
+   mount -t proc proc /proc
+   mount -t sysfs sysfs /sys
+   ip link set up dev lo
+
+   exec /sbin/getty -n -l /bin/sh 115200 /dev/ttyS0
+   poweroff -f
+   EOF
+
+   $ sudo chmod +x sbin/init
+   ```
+
+   **Notice: alpine is an example. You can use any open rootfs filesystem with init/systemd as rootfs image.**
+
+5.  Unmount rootfs image:
+
+    ```shell
+    $ cd ~ && umount /mnt/rootfs
+    ```
diff --git a/docs/build_guide.md b/docs/build_guide.md
new file mode 100644
index 00000000..356095ce
--- /dev/null
+++ b/docs/build_guide.md
@@ -0,0 +1,47 @@
+
+# Build StratoVirt from source
+
+## 1. Check rust environment
+
+To build StratoVirt, make sure that Rust language environment and Cargo have already been installed.
+ The recommended version of rustc is 1.45.2 or later.
+
+```shell
+$ rustc --version
+rustc 1.45.2
+```
+
+If you want to deploy rust environment, the following link will help you:
+
+<https://www.rust-lang.org/tools/install>
+
+## 2. Build with glibc
+
+With glibc, StratoVirt is linked dynamically. It's the default target to build StratoVirt.
+
+```shell
+# Add musl rust tool-chain, if installed, skip
+$ arch=`uname -m`
+$ rustup target add ${arch}-unknown-linux-gnu
+
+# Build StratoVirt
+$ cargo build --release --target ${arch}-unknown-linux-gnu
+```
+
+Now you can find StratoVirt binary file in `target/${arch}-unknown-linux-gnu/release/stratovirt`.
+
+## 3. Build with musl-libc
+
+StratoVirt can also be built using musl-libc toolchains. By this way, StratoVirt is linked statically 
+and has no library dependencies.
+
+```shell
+# Add gnu rust tool-chain, if installed, skip
+$ arch=`uname -m`
+$ rustup target add ${arch}-unknown-linux-musl
+
+# Build StratoVirt
+$ cargo build --release --target ${arch}-unknown-linux-musl
+```
+
+Now you can find StratoVirt static binary file in `target/${arch}-unknown-linux-musl/release/stratovirt`.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index d3ccc76c..22d61894 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -15,213 +15,79 @@
     ```shell
     $ sudo setfacl -m u:${USER}:rw /dev/kvm
     ```
-## 2. Build StratoVirt from source
 
-### 2.1 Check rust environment
+## 2. Getting the StratoVirt Binary
 
-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.
+StratoVirt is offerred by OpenEuler 20.09 or later. You can install by yum directly.
 
 ```shell
-$ rustc -version
-rustc 1.42.0
+$ sudo yum install stratovirt
 ```
 
-If you want to deploy rust environment, the following link will help you:
+Now you can find StratoVirt binary with path: `/usr/bin/stratovirt`.
 
-<https://www.rust-lang.org/tools/install>
+If you'd like to build StratoVirt yourself, you should check out the [build_guide](../build_guide.md).
 
-### 2.2 Build with musl-libc
+## 3. Running StratoVirt
 
-With musl-libc, StratoVirt is linked statically and has no library dependencies. It's the
- default target to build StratoVirt.
+With StratoVirt binary (either installed with yum, or built from source), we can boot a guest linux machine
+ by StratoVirt.
 
-```shell
-# Add musl rust tool-chain, if installed, skip
-$ arch=`uname -m`
-$ rustup target add ${arch}-unknown-linux-musl
-
-# Build StratoVirt
-$ cargo build --release --target ${arch}-unknown-linux-musl
-```
+First, you will need an PE format Linux kernel binary, and an ext4 file system image (as rootfs).
+* `x86_64` boot source: [kernel](https://repo.openeuler.org/openEuler-21.03/stratovirt_img/x86_64/vmlinux.bin) and [rootfs](https://repo.openeuler.org/openEuler-21.03/stratovirt_img/x86_64/openEuler-21.03-stratovirt-x86_64.img.xz).
+* `aarch64` boot source: [kernel](https://repo.openeuler.org/openEuler-21.03/stratovirt_img/aarch64/vmlinux.bin) and [rootfs](https://repo.openeuler.org/openEuler-21.03/stratovirt_img/aarch64/openEuler-21.03-stratovirt-aarch64.img.xz).
 
-Now you can find StratoVirt binary file in `target/${arch}-unknown-linux-musl/release/stratovirt`.
-
-### 2.3 Build with glibc
-
-StratoVirt can also be built using glibc toolchains. By this way, StratoVirt is linked dynamically.
+Or get the kernel and rootfs with shell:
 
 ```shell
-# Add gnu rust tool-chain, if installed, skip
-$ arch=`uname -m`
-$ rustup target add ${arch}-unknown-linux-gnu
-
-# Build StratoVirt
-$ cargo build --release --target ${arch}-unknown-linux-gnu
+arch=`uname -m`
+dest_kernel="vmlinux.bin"
+dest_rootfs="rootfs.ext4"
+image_bucket_url="https://repo.openeuler.org/openEuler-21.03/stratovirt_img"
+
+if [ ${arch} = "x86_64" ] || [ ${arch} = "aarch64" ]; then
+    kernel="${image_bucket_url}/${arch}/vmlinux.bin"
+    rootfs="${image_bucket_url}/${arch}/openEuler-21.03-stratovirt-${arch}.img.xz"
+else
+    echo "Cannot run StratoVirt on ${arch} architecture!"
+    exit 1
+fi
+
+echo "Downloading $kernel..."
+wget ${kernel} -O ${dest_kernel} --no-check-certificate
+
+echo "Downloading $rootfs..."
+wget ${rootfs} -O ${dest_rootfs}.xz --no-check-certificate
+xz -d ${dest_rootfs}.xz
+
+echo "kernel file: ${dest_kernel} and rootfs image: ${dest_rootfs} download over."
 ```
 
-Now you can find StratoVirt binary file in `target/${arch}-unknown-linux-gnu/release/stratovirt`.
-
-## 3. Prepare kernel and rootfs image
-
-### 3.1 Build kernel
-
-The StratoVirt in current version supports PE or bzImage (only x86_64) format kernel images on
-both x86_64 and aarch64 platforms, which can be built with:
-
-1. Firstly, get the openEuler kernel source code:
-
-   ```shell
-   $ git clone -b kernel-4.19 --depth=1 https://gitee.com/openeuler/kernel
-   $ cd kernel
-   ```
-
-2. 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
-   ```
-
-3. Build and transform kernel image to PE format.
-
-   ```shell
-   $ make -j vmlinux && objcopy -O binary vmlinux vmlinux.bin
-   ```
-
-5. If you want compile bzImage format kernel in x86_64.
-   ```shell
-   $ make -j bzImage
-   ```
-
-### 3.2 Make rootfs
-
-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):
-
-   ```shell
-   $ dd if=/dev/zero of=./rootfs.ext4 bs=1G count=20
-   ```
-
-2. Create an empty EXT4 file system on this file:
-
-   ```shell
-   $ mkfs.ext4 ./rootfs.ext4
-   ```
-
-3. Mount the file image:
-
-   ```shell
-   $ mkdir -p /mnt/rootfs
-   $ sudo mount ./rootfs.ext4 /mnt/rootfs && cd /mnt/rootfs
-   ```
-
-4. Get the [latest alpine-minirootfs](http://dl-cdn.alpinelinux.org/alpine) for your platform(e.g.
- aarch64 3.12.0):
-
-   ```shell
-   $ wget http://dl-cdn.alpinelinux.org/alpine/latest-stable/releases/aarch64/alpine-minirootfs-3.12.0-aarch64.tar.gz
-   $ tar -zxvf alpine-minirootfs-3.12.0-aarch64.tar.gz
-   $ rm alpine-minirootfs-3.12.0-aarch64.tar.gz
-   ```
-
-5. Make a simple `/sbin/init` for EXT4 file image.
-
-   ```shell
-   $ rm sbin/init && touch sbin/init && cat > sbin/init <<EOF
-   #! /bin/sh
-   mount -t devtmpfs dev /dev
-   mount -t proc proc /proc
-   mount -t sysfs sysfs /sys
-   ip link set up dev lo
-
-   exec /sbin/getty -n -l /bin/sh 115200 /dev/ttyS0
-   poweroff -f
-   EOF
-
-   $ sudo chmod +x sbin/init
-   ```
-
-6.  Unmount rootfs image:
-
-    ```shell
-    $ cd ~ && umount /mnt/rootfs
-    ```
-
-## 4. Run StratoVirt
-
-With kernel and rootfs image, we can boot a guest linux machine by StratoVirt.
-
-### 4.1 Run with cmdline
-
-The minimum configuration for StratoVirt is:
-
-* A PE or bzImage (only x86_64) format linux kernel
-* A rootfs image as virtio-blk device, which has to be added to kernel parameters
-* Api-channel to control StratoVirt
-* If you want to login with ttyS0, you may need a serial and add ttyS0 to kernel parameters
-
-You can deploy StratoVirt with cmdline arguments:
-
+Start guest linux machine with StratoVirt:
 ```shell
+socket_path=`pwd`"/stratovirt.sock"
+kernel_path=`pwd`"/vmlinux.bin"
+rootfs_path=`pwd`"/rootfs.ext4"
+
 # Make sure api-channel can be created.
-$ rm -f /path/to/socket
-
-# Start StratoVirt
-$ ./stratovirt \
-    -kernel /path/to/vmlinux.bin \
-    -append console=ttyS0 pci=off reboot=k panic=1 root=/dev/vda \
-    -drive file=/path/to/rootfs,id=rootfs,readonly=off \
-    -api-channel unix:/path/to/socket \
+rm -f ${socket_path}
+
+# Start StratoVirt guest linux machine.
+/usr/bin/stratovirt \
+    -kernel ${kernel_path} \
+    -smp 1 \
+    -m 1024m \
+    -append console=ttyS0 pci=off reboot=k quiet panic=1 root=/dev/vda \
+    -drive file=${rootfs_path},id=rootfs,readonly=off,direct=off \
+    -api-channel unix:${socket_path} \
     -serial stdio
 ```
 
-### 4.2 Running with json
-
-StratoVirt can also boot from a json configuration file like provided [sample default.json](./default.json).
-
-```shell
-# Json configuration file
-$ cat default.json
-{
-  "boot-source": {
-    "kernel_image_path": "/path/to/kernel",
-    "boot_args": "console=ttyS0 reboot=k panic=1 pci=off tsc=reliable ipv6.disable=1 root=/dev/vda"
-  },
-  "machine-config": {
-    "vcpu_count": 1,
-    "mem_size": 268435456
-  },
-  "drive": [
-    {
-      "drive_id": "rootfs",
-      "path_on_host": "/path/to/rootfs/image",
-      "direct": false,
-      "read_only": false
-    }
-  ],
-  "balloon": {
-    "deflate_on_oom": true
-  },
-  "serial": {
-    "stdio": true
-  }
-}
-
-# Start StratoVirt
-$ ./stratovirt \
-    -config ./default.json \
-    -api-channel unix:/path/to/socket
-```
-
-You can also run StratoVirt with initrdfs, read [initrd_guide](./mk_initrd.md).
-
-### 4.3 Close the VM
+You should now see a serial in stdio prompting you to log into the guest machine. If you used our 
+`openEuler-21.03-stratovirt-aarch64.img` image, you can login as `root`, using the password 
+`openEuler12#$`.
 
-ACPI(Advanced Configuration and Power Interface) has not been implemented yet in StratoVirt. Power management, such as `shutdown` 
-or `reboot` behavior, is not allowed. So it is not feasible to use `shutdown` or `poweroff` command to close the VM.
-Instead, use `reboot` command in the guest or `quit` command with QMP to close the VM.
+If you want to quit the guest machine, using a `reboot` command inside the guest will actually shutdown
+StratoVirt. This is due to that StratoVirt didn't implement guest power management in microvm type.
 
 If you want to know more information on running StratoVirt, go to the [Configuration Guidebook](./config_guidebook.md).
-- 
2.30.0

