From 9f490d16fef91c472d139ccf35ed98b7def820e1 Mon Sep 17 00:00:00 2001 From: Chao Wu Date: Mon, 16 Jan 2023 16:40:38 +0800 Subject: [PATCH] upcall: add document for upcall In order for users to get better understand of upcall features, we add this document for upcall to illustrate what is upcall and how to enable upcall. fixes: #6054 Signed-off-by: Chao Wu --- src/dragonball/README.md | 1 + .../docs/images/upcall-architecture.svg | 177 ++++++++++++++++++ src/dragonball/docs/upcall.md | 30 +++ 3 files changed, 208 insertions(+) create mode 100644 src/dragonball/docs/images/upcall-architecture.svg create mode 100644 src/dragonball/docs/upcall.md diff --git a/src/dragonball/README.md b/src/dragonball/README.md index c9d7e5119c..3fde0782e0 100644 --- a/src/dragonball/README.md +++ b/src/dragonball/README.md @@ -19,6 +19,7 @@ and configuration process. Device: [Device Document](docs/device.md) vCPU: [vCPU Document](docs/vcpu.md) API: [API Document](docs/api.md) +`Upcall`: [`Upcall` Document](docs/upcall.md) Currently, the documents are still actively adding. You could see the [official documentation](docs/) page for more details. diff --git a/src/dragonball/docs/images/upcall-architecture.svg b/src/dragonball/docs/images/upcall-architecture.svg new file mode 100644 index 0000000000..a74c37f455 --- /dev/null +++ b/src/dragonball/docs/images/upcall-architecture.svg @@ -0,0 +1,177 @@ + + + + + + + + + + + + + + + + + Canvas 1 + + + Layer 1 + + + + + + Guest User + + + + + Guest Kernel + + + + + + + + Hypervisor + + + + + + + + socket + + + + + + Device + Manager + Service + + + + + bind + + + + + listen + + + + + accept + + + + + new kthread + + + + + + virtio-vsocket + + + + + + virtio-vsocket backend + + + + + + + + + + + + + + + + + + Port + + + + + + Device + Manager + Backend + + + + + + + + + Service B + + + + + + Backend B + + + + + + + + …… + + + + + …… + + + + + Upcall Server + + + + + + + + Service handler + + + + + + Conn + + + + + + Conn + + + + + + + + + + + diff --git a/src/dragonball/docs/upcall.md b/src/dragonball/docs/upcall.md new file mode 100644 index 0000000000..292b33d270 --- /dev/null +++ b/src/dragonball/docs/upcall.md @@ -0,0 +1,30 @@ +# `Upcall` + +## What is `Upcall`? + +`Upcall` is a direct communication tool between VMM and guest developed upon `vsock`. The server side of the `upcall` is a driver in guest kernel (kernel patches are needed for this feature) and it'll start to serve the requests after the kernel starts. And the client side is in Dragonball VMM , it'll be a thread that communicates with `vsock` through `uds`. + +We want to keep the lightweight of the VM through the implementation of the `upcall`. + +![architecture overview](images/upcall-architecture.svg) +## What can `upcall` do? + +We define specific operations in the device manager service (one of the services in `upcall` we developed) to perform device hotplug / hot-unplug including vCPU hotplug, `virtio-mmio` hotplug, and memory hotplug. We have accomplished device hotplug / hot-unplug directly through `upcall` in order to avoid the virtualization of ACPI to minimize virtual machines overhead. And there could be many other uses if other services are implemented. + +## How to enable `upcall`? + +`Upcall` needs a server in the guest kernel which will be several kernel patches for the `upcall` server itself and different services registered in the `upcall` server. It's currently tested on upstream Linux kernel 5.10. + +To make it easy for users to use, we have open-source the `upcall` guest patches in [Dragonball experimental guest patches](../../../tools/packaging/kernel/patches/5.10.x/dragonball-experimental) and develop `upcall` support in [Kata guest kernel building script](../../../tools/packaging/kernel/build-kernel.sh). + +You could use following command to download the upstream kernel (currently Dragonball uses 5.10.25) and put the `upcall` patches and other Kata patches into kernel code. + +`sh build-kernel.sh -e -t dragonball -f setup` + +`-e` here means experimental, mainly because `upcall` patches are not in upstream Linux kernel. +`-t dragonball` is for specifying hypervisor type +`-f` is for generating `.config` file + +After this command, the kernel code with `upcall` and related `.config` file are all set up in the directory `kata-linux-dragonball-experimental-5.10.25-[config version]`. You can either manually compile the kernel with `make` command or following [Document for build-kernel.sh](../../../tools/packaging/kernel/README.md) to build and use this guest kernel. + +Also, a client-side is also needed in VMM. Dragonball has already open-source the way to implement `upcall` client and Dragonball compiled with `dbs-upcall` feature will enable Dragonball client side. \ No newline at end of file