# ZVM-RK3568v2.1 发行版部署指南

## 一、ZVM-RK3568v2.1 简介

ZVM-RK3568v2.1 发行版是一款面向瑞芯微 RK3568 处理器芯片的 ZVM 定制化版本，于 2026 年 6 月发布。

### 1. 支持板卡与镜像说明

| 板卡 | 下载链接 | 适配说明 |
|---|---|---|
| LubanCat RK3568 | https://doc.embedfire.com/linux/rk356x/quick_start/zh/latest/index.html | 默认支持。需要替换 `zvm_release_rk3568v2.1.bin` 和 `boot.scr`；如果替换后不能自动启动 ZVM，需要替换 `uboot_emmc_rk3568.img`。 |

本文使用的镜像分为公共镜像和板卡适配镜像。公共镜像提供通用发行版内容；板卡适配镜像用于适配特定板卡，主要包含 ZVM 针对板卡硬件差异做的少量修改，例如网卡频率、启动脚本和 U-Boot 文件。

| 序号 | 镜像名称 | 下载链接 |
|---|---|---|
| 1 | ZVM-RK3568v2.1 发行版镜像包 | 官方下载地址 |
| 2 | VisualZVMv2.1 可视化管理软件 | 官方下载地址 |

以 LubanCat RK3568 为例：

1. 下载并解压 ZVM-RK3568v2.1 发行版镜像包。
2. 若使用默认支持的 LubanCat RK3568 板卡，直接使用发行包中的文件。
3. 按照后续步骤完成 TF 卡部署和启动。

### 2. 多 OS 混合部署

ZVM-RK3568v2.1 支持多个客户 OS 混合部署。可同时启动的客户 OS 数量需结合 RK3568 板卡内存、核数和镜像配置确认。

| 客户 OS | 可分配核数 | 内存大小 |
|---|---:|---:|
| Zephyr | 1/2/3 核 | 128M |
| FreeRTOS | 1 核 | 128M |
| Linux | 1/2 核 | 512M |

### 3. 多核 OS 支持

RK3568 为 4 核 Cortex-A55 处理器。ZVM 默认占用 0 核，客户 OS 可部署在其余 A55 核心上。

| 处理器型号 | 核号 | 分配说明 |
|---|---:|---|
| Cortex-A55 | 0 | ZVM |
| Cortex-A55 | 1-3 | 客户 OS |

### 4. 外设共享

ZVM-RK3568v2.1 支持完全虚拟化、半虚拟化等外设共享方式，用于解决复杂系统中的外设资源分配冲突。

| 序号 | 类别 | 支持外设 |
|---|---|---|
| 1 | 完全虚拟化外设 | UART、GPIO、I2C 等 |
| 2 | 半虚拟化 VirtIO 外设 | NIC、SDMMC、GPIO、I2C 等 |

## 二、ZVM-RK3568v2.1 部署教程

### 1. 准备硬件

| 硬件 | 说明 |
|---|---|
| 开发板 | LubanCat RK3568，建议 2G 内存版本 |
| TF 卡 | 32GB 及以上 |
| 读卡器 | 用于在主机上制作 TF 卡 |
| USB 转 TTL 模块 | 用于串口调试 |
| Type-C 数据线 | 用于可选的 U-Boot 烧写 |
| 网线 | 用于 VisualZVM 或网络测试 |

### 2. 使用 DiskGenius 给 TF 卡分区

如果 TF 卡已经按本发行版要求分区，可以直接跳到第 3 步。

在 Windows 主机上将 TF 卡插入读卡器，打开 DiskGenius，选中 TF 卡后使用 Quick Partition 快速分区。

注意：

- 请务必确认选择的是 TF 卡，避免误操作其他磁盘。
- ZVM 要求第一个分区为 8G，第二个分区大于 21G。
- 第一个分区用于存放 `zvm_release_rk3568v2.1.bin` 和 `boot.scr`。
- 第二个分区用于写入 NRTOS 镜像、客户 OS 文件系统镜像和 Guest 运行记录。

### 3. 客户 OS 文件系统镜像烧录

如果 TF 卡中已经成功写入过文件系统镜像，可以直接跳到第 4 步。

在 Linux 主机上解压发行包后，先在仓库根目录执行：

```bash
./extract_images.sh
```

该脚本会解压并校验大文件，生成：

```text
file_system_images/linux_diskimg_br.bin
kernel_images/raw_kernel_images/zvm_host.bin
```

进入 `file_system_images` 目录，使用 `lsblk` 或 `df` 确认 TF 卡第二分区的设备名。以下示例使用 `/dev/sdX2`，实际使用时请替换为自己的设备名：

```bash
cd file_system_images
sudo ./auto_dd.sh /dev/sdX2
```

`auto_dd.sh` 会将同一个 Linux VirtIO rootfs 写入第二分区中的两个槽位：

| VirtIO 槽位 | 第二分区内偏移 |
|---|---:|
| Linux slot 0 | 3072 MiB |
| Linux slot 1 | 6144 MiB |

注意：

- 请务必确认目标设备名正确，否则可能误写入其他磁盘导致数据丢失。
- 第二分区需要有足够容量存放 rootfs 槽位。
- ZVM 会将运行过且未删除的 Guest 信息保存在 TF 卡第二分区的前 3GB 空间中，因此 rootfs 第一个写入位置必须从 3GB 之后开始。
- 脚本会要求输入 `WRITE-/dev/sdX2` 才会继续写入。

### 4. 准备 ZVM 启动镜像

回到发行包根目录。`kernel_images` 目录中包含 ZVM 启动所需文件，主要使用：

```text
kernel_images/nrtos_images.bin
kernel_images/boot.scr
kernel_images/zvm_release_rk3568v2.1.bin
```

#### 4.1 写入 nrtos_images.bin

将 Non-RTOS 镜像包写入 TF 卡第二分区。以下示例使用 `/dev/sdX2`，实际使用时请替换为自己的设备名：

```bash
sudo dd if=kernel_images/nrtos_images.bin of=/dev/sdX2 \
  bs=1M seek=1024 conv=fsync status=progress
sync
```

#### 4.2 复制启动文件

将以下两个文件复制到 TF 卡第一个分区：

```text
kernel_images/zvm_release_rk3568v2.1.bin
kernel_images/boot.scr
```

复制完成后安全弹出 TF 卡，插入开发板。

开发板上电时按 `Ctrl+C` 进入 U-Boot 命令行，然后执行：

```text
run distro_bootcmd
```

如果板卡不支持该命令，或需要手动加载启动脚本，可以使用：

```text
mmc list
mmc dev 1
fatload mmc 1:1 0x00c00000 boot.scr
source 0x00c00000
```

ZVM 正常启动后会进入 `zvm_host:~#` 命令行。

#### 4.3 自行编译镜像

`kernel_images/raw_kernel_images` 目录中包含制作 ZVM 镜像所需的二进制输入和打包脚本。可以替换其中对应文件，例如 Linux 内核镜像 `Image_5.15`、initramfs、DTB、Zephyr 或 FreeRTOS 镜像，然后重新打包。

进入 `kernel_images` 后执行：

```bash
./auto_py.sh
```

交互菜单中输入 `3` 可生成全部镜像。也可以直接使用参数：

```bash
./auto_py.sh all
```

执行完成后会生成新的：

```text
kernel_images/zvm_release_rk3568v2.1.bin
kernel_images/boot.scr
kernel_images/nrtos_images.bin
```

重新生成后，请按 4.1 和 4.2 重新写入 TF 卡。

#### 4.4 LubanCat RK3568 更换 U-Boot

LubanCat RK3568 开发板默认 U-Boot 可能只进入官方 Android 或 Ubuntu 的默认启动环境，导致不能稳定自动查找并启动 TF 卡中的 ZVM 镜像。发行包提供了适配 RK3568 eMMC 启动环境的 U-Boot 文件：

```text
file_system_images/uboot_emmc_rk3568.img
```

如果按 4.2 复制启动文件后，开发板仍不能自动进入 ZVM，可以使用该文件替换开发板 U-Boot。

注意：

- `uboot_emmc_rk3568.img` 仅用于 LubanCat RK3568 的 eMMC U-Boot 替换。
- 该 U-Boot 替换流程适用于 Android 固件环境。如果开发板当前是 Ubuntu 或其他 Linux U-Boot 环境，建议先刷入 LubanCat 官方 Android 固件环境，再替换该 U-Boot。
- 烧写前请参考 LubanCat/Firefly 官方刷机教程，确认板卡型号、烧写工具和连接方式。

##### 4.4.1 准备工具

| 项目 | 说明 |
|---|---|
| LubanCat RK3568 开发板 | 目标板卡 |
| `uboot_emmc_rk3568.img` | 发行包提供，位于 `file_system_images` 目录 |
| Windows 主机 | 用于运行 RK USB 烧写工具 |
| Type-C 数据线 | 用于连接主机和开发板 |

##### 4.4.2 安装烧写工具

在 Windows 上安装 RK USB 驱动。解压 `Release_DriverAssistant.zip` 后运行 `DriverInstall.exe`。建议先选择“驱动卸载”，再选择“驱动安装”。

安装完成后运行 AndroidTool 的 `RKDevTool.exe`。

##### 4.4.3 进入 Loader 模式

硬件方式：

1. 断开电源适配器。
2. 使用 Type-C 数据线连接主机和开发板。
3. 按住开发板上的 RECOVERY 键。
4. 接上电源。
5. 大约两秒后松开 RECOVERY 键。

也可以在串口调试终端或 `adb shell` 中执行重启到 Loader 模式的命令，具体命令以板卡官方文档为准。

进入 Loader 模式后，Windows 设备管理器中应能看到 `Rockusb Device`，AndroidTool 中应显示 `Found One LOADER Device`。

##### 4.4.4 烧写 U-Boot

在 AndroidTool 的“下载镜像”页面中勾选 `uboot` 行，选择：

```text
file_system_images/uboot_emmc_rk3568.img
```

点击“执行”开始烧写。烧写完成后重启开发板。如果 TF 卡中已经准备好 `boot.scr` 和 `zvm_release_rk3568v2.1.bin`，开发板会自动查找并启动 ZVM。

## 三、部署后的使用教程

| 项目名称 | 链接地址 |
|---|---|
| VisualZVM 使用指南 | http://esnl.hnu.edu.cn/zvm/features/visual-zvm-v2.1.html |
| 基于 VisualZVM 的自动化测试系统 | http://esnl.hnu.edu.cn/zvm/features/auto-test-v2.1.html |

## 四、目录说明

```text
extract_images.sh
file_system_images/
  auto_dd.sh
  linux_diskimg_br.7z.001
  uboot_emmc_rk3568.img
kernel_images/
  auto_py.sh
  boot.scr
  boot.txt
  nrtos_images.bin
  zvm_release_rk3568v2.1.bin
  raw_kernel_images/
```

部署前可以执行：

```bash
sha256sum -c SHA256SUMS
```

祝您开发顺利。
