From 9e4414cdbe1a108300ae2fd5bdf56823e33d1624 Mon Sep 17 00:00:00 2001
From: wzm <1156033953@qq.conm>
Date: Mon, 24 Aug 2026 23:08:22 +0800
Subject: [PATCH] docs: document dynamic virtio add

---
 README-zh.md | 16 ++++++++++++++++
 README.md    | 18 +++++++++++++++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/README-zh.md b/README-zh.md
index b5eb892a..4bc5c356 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -147,6 +147,22 @@ nohup ./hvisor virtio start virtio_cfg.json &
 
 要使用virtio-gpu设备，需要在hvisor-tool编译命令中加入`VIRTIO_GPU=y`字段，同时还需安装`libdrm`并进行其他配置，具体请见[hvisor-book](https://hvisor.syswonder.org/chap04/subchap03/VirtIO/GPUDevice.html)和[配置文件示例](./examples/qemu-aarch64/with_virtio_gpu/README.md)。配置文件中如果`gpu`设备`status`属性为`enable`，则会创建一个 Virtio-gpu 设备，其 MMIO 区域从 `0xa003400` 开始，长度为 `0x200`，中断号为 74。默认的扫描输出(scanout)尺寸为宽度 `1280px`，高度 `800px`。
 
+#### 向运行中的守护进程添加 Virtio 设备
+
+使用`virtio start`启动Virtio守护进程后，可以通过`virtio add`向运行中的守护进程发送新的Virtio设备配置：
+
+```bash
+nohup ./hvisor virtio start virtio_cfg.json &
+./hvisor virtio add virtio_add_config.json
+./hvisor zone start <vm_config.json>
+```
+
+`virtio add`使用与`virtio start`相同的`zones`、`memory_region`和`devices` JSON结构。配置文件应描述目标zone使用的内存区域和已启用的Virtio设备。守护进程通过`/run/hvisor-virtio.sock`接收请求；该Unix domain socket由`virtio start`创建，不需要手动管理。
+
+命令成功时输出`virtio add succeeded`，如果配置校验、内存映射或设备初始化失败，则输出`virtio add failed`。一次请求包含多个已启用设备时，守护进程会先创建临时设备，只有全部初始化成功后才发布这些设备。如果其中一个设备失败，本次请求创建的临时设备及其资源会被清理，已有的设备表不会被修改。
+
+该流程是在对应zone启动前向守护进程添加Virtio设备，不表示可以向已经运行的guest热插拔此前不存在的MMIO设备。
+
 #### 关闭Virtio设备
 
 执行该命令即可关闭Virtio守护进程及所有创建的设备：
diff --git a/README.md b/README.md
index 276bd42e..4f69766e 100644
--- a/README.md
+++ b/README.md
@@ -147,10 +147,26 @@ If the `net` device's `status` attribute is set to `enable`, a Virtio-net device
 
 To use the Virtio-gpu device, the `VIRTIO_GPU=y` option must be added to the `hvisor-tool` compile command, and `libdrm` should be installed along with other configurations. For more details, please refer to [hvisor-book](https://hvisor.syswonder.org/chap04/subchap03/VirtIO/GPUDevice.html) and the [configuration example](./examples/qemu-aarch64/with_virtio_gpu/README.md). If the `gpu` device's `status` attribute is set to `enable`, a Virtio-gpu device will be created, with the MMIO region starting at `0xa003400`, the length set to `0x200`, and the interrupt number set to 74. The default scanout dimensions are a width of `1280px` and a height of `800px`.
 
+#### Adding Virtio Devices to a Running Daemon
+
+After the Virtio daemon has been started with `virtio start`, additional Virtio devices can be sent to the running daemon with `virtio add`:
+
+```bash
+nohup ./hvisor virtio start virtio_cfg.json &
+./hvisor virtio add virtio_add_config.json
+./hvisor zone start <vm_config.json>
+```
+
+The `virtio add` configuration uses the same `zones`, `memory_region`, and `devices` JSON structure as `virtio start`. It should describe the memory regions and enabled Virtio devices for the zone that will use them. The daemon receives requests through the Unix domain socket at `/run/hvisor-virtio.sock`; the socket is created by `virtio start` and does not need to be managed manually.
+
+The command prints `virtio add succeeded` when the request is accepted, or `virtio add failed` when validation, memory mapping, or device initialization fails. When one request contains multiple enabled devices, the devices are created temporarily and published only after all of them have initialized successfully. If any device fails, the temporary devices and their resources are cleaned up, and the existing device table is left unchanged.
+
+This flow adds Virtio devices to the daemon before the corresponding zone is started. It does not promise hot-plugging an MMIO device into a guest that is already running.
+
 #### Shut down Virtio Devices
 
 To shut down the Virtio daemon and all the created devices, execute the following command:
 
 ```
 pkill hvisor-virtio
-``` 
\ No newline at end of file
+```