SpaceMiT K3-COM260 快速上手

本文档介绍如何在 SpaceMiT K3-COM260 开发板上部署并启动 hvisor。K3 是目前率先支持 RVA23 Profile 的 RISC-V 平台，hvisor 对该板卡的适配具有代表性意义。

平台简介

K3-COM260 使用进迭时空（SpaceMiT）K3 SoC，包含 8 个 X100 通用核与 8 个 A100 AI 核。

其中 X100 带硬件虚拟化扩展（RISC-V Hypervisor），A100 不含该扩展，因此 hvisor 当前仅管理 X100 核。

默认划分如下：

Zone	CPU	外设
zone0（Root Linux）	hart 0 ~ 3	串口、网卡、UFS、MMC 等直通
zone1（Non-root Linux）	hart 4 ~ 7	virtio-blk、virtio-console

相关 Kconfig 位于 platform/riscv64/k3-com260/kconfig/defconfig：

CONFIG_AIA=y
CONFIG_ARCH_RISCV64=y
CONFIG_RVA23=y

设备支持

zone0 支持网卡与块设备直通（以太网 ethernet@cac82000、UFS ufshc@c0e00000、MMC mmc@d4280000）。
zone1 目前仅支持 virtio 设备。

注意： SD 卡的直通需要支持 SBI 3.0 引入的 MPXY 扩展，经测试可以实现直通，由于工具链等原因目前并未合入主线。若需支持，需要 hvisor 向 Guest 报告 SBI 3.0，并将 MPXY 调用转发给 OpenSBI。

软件依赖

Linux 源码：建议使用进迭官方内核 spacemit-com/linux-6.18，Tag k3-br-v1.0.0
Linux 配置：k3_bianbu_defconfig
交叉编译工具链：进迭官方工具链，见 archive.spacemit.com/toolchain
主机还需安装 device-tree-compiler、u-boot-tools

编译 Hvisor 和设备树

拉取 hvisor 最新代码，仓库地址：syswonder/hvisor。建议使用 dev 分支：
```
git clone -b dev https://github.com/syswonder/hvisor.git
cd hvisor
```
编译 hvisor。先载入板级 defconfig，再以 release 模式编译。本平台会通过 mkimage 将原始二进制封装为 U-Boot FIT 镜像，产物仍名为 hvisor.bin：
```
make BID=riscv64/k3-com260 defconfig
make BID=riscv64/k3-com260 all MODE=release
```
编译产生的文件位于 target/riscv64gc-unknown-none-elf/release/hvisor.bin。
编译设备树：
```
make BID=riscv64/k3-com260 dtb
```
将得到 zone0.dtb、zone1-linux.dtb 等。其中：
- zone0.dts：zone0 Linux 使用的设备树
- zone1-linux.dts：zone1 Linux 使用的设备树（virtio-blk / virtio-console）
- k3_com260_ifx.dts：完整硬件参考设备树

编译 Linux 内核

zone0 与 zone1 可使用同一份内核镜像。以官方 linux-6.18 为例：

# 安装并配置交叉工具链，将 bin 目录加入 PATH
# 例如：export PATH=/opt/spacemit-toolchain-linux-glibc-x86_64-v1.2.4/bin:$PATH

git clone https://github.com/spacemit-com/linux-6.18.git -b k3-br-v1.0.0 --depth=1
cd linux-6.18
export ARCH=riscv
export CROSS_COMPILE=riscv64-unknown-linux-gnu-
make k3_bianbu_defconfig
make -j$(nproc) Image

编译完成后，内核镜像位于 arch/riscv/boot/Image。

制作 Zone1 文件系统

zone0 直接使用开发板 UFS 上已有的 Bianbu 根文件系统，无需另行制作。zone1 需要一份独立的 rootfs2.ext4。

可以复制一份较小的根文件系统镜像，也可以参考 Qemu RISC-V 快速上手中“制作 ubuntu 根文件系统”一节自行制作。制作完成后将其命名为 rootfs2.ext4，与 configs/virtio-backend.json 中的配置保持一致。

编译 hvisor-tool

拉取 hvisor-tool 最新代码。

请务必保证 hvisor 中的 Root Linux 镜像，是由编译 hvisor-tool 时 KDIR 所指向的 Linux 源码目录编译产生：

make all ARCH=riscv LOG=LOG_INFO KDIR=/path/to/linux-6.18

编译结果位于 output/hvisor 和 output/hvisor.ko。更多细节请参考 hvisor-tool 的 README。

文件准备

1. 放入 TFTP 服务器

先在主机上搭建 TFTP 服务，再将启动文件放到 TFTP 根目录。

Windows： 可使用 Tftpd64 作为 TFTP 服务器。安装后打开软件，将 Current Directory 指向存放镜像的目录（例如 D:\tftp）。

hvisor.bin
zone0 Linux Image
zone0.dtb

2. 放入 zone0 文件系统

将下列文件放到 zone0 根文件系统中的同一工作目录（可在 Bianbu 系统中通过 scp 拷贝，例如 /home/bianbu/zone1）：

zone1 Linux Image、zone1-linux.dtb、rootfs2.ext4
hvisor-tool 编译得到的 hvisor 可执行文件和 hvisor.ko
configs/virtio-backend.json、configs/zone1-linux-virtio.json

若 zone1 与 zone0 使用同一内核，将 Image 再复制一份即可。zone1-linux-virtio.json 中的文件名需与实际文件名匹配：

"kernel_filepath": "./Image",
"dtb_filepath": "./zone1-linux.dtb",

另外，建议在 zone0 中提前安装 screen 工具，后续连接 zone1 的 virtio-console 需要使用。

通过 TFTP 启动 Zone0-Linux

串口连接

使用 USB 转 TTL 连接载板调试串口（TX、RX、GND）。默认串口参数如下：

参数项	参数值
波特率 (Baud Rate)	`115200`
数据位 (Data Bits)	`8`
停止位 (Stop Bits)	`1`
校验位 (Parity)	`None`

串口工具很多，Windows 上推荐 MobaXterm：新建 Session → Serial，选择对应 COM 口，Speed 设为 115200。Ubuntu 上推荐 minicom：

sudo apt-get install minicom
sudo minicom -b 115200 -D /dev/ttyUSB0

网络配置

用网线连接主机与开发板。boot.txt 中的默认地址为：

主机（TFTP 服务器）：192.168.137.1
开发板：192.168.137.200
子网掩码：255.255.255.0

执行启动命令

开发板上电后，在 U-Boot 启动阶段按下 s 打断自动启动，然后执行 platform/riscv64/k3-com260/boot.txt 中的命令：

setenv serverip 192.168.137.1;
setenv ipaddr 192.168.137.200;
setenv netmask 255.255.255.0;

setenv hvisor_fit_addr 0x122200000;
tftpboot ${hvisor_fit_addr} ${serverip}:hvisor.bin;

setenv zone0_fdt_addr 0x10f000000;
tftpboot ${zone0_fdt_addr} ${serverip}:zone0.dtb;

setenv zone0_kernel_addr 0x110000000;
tftpboot ${zone0_kernel_addr} ${serverip}:Image;

bootm ${hvisor_fit_addr} - ${zone0_fdt_addr};

最后一条 bootm 会启动 hvisor，再由 hvisor 拉起 zone0。进入 Linux 登录界面即表示 zone0 启动成功。

Bianbu 默认 root 密码为 bianbu。

上述加载地址与 board.rs 中的配置一致：

hvisor FIT 镜像：0x122200000（链接地址 0x102200000）
zone0 DTB：0x10f000000
zone0 内核：0x110000000

启动 Zone1-Linux

zone0 启动后，切换到先前准备好的工作目录，按 scripts/boot_zone1.sh 执行：

su root   # passwd: bianbu

insmod hvisor.ko

nohup ./hvisor virtio start virtio-backend.json &
./hvisor zone start zone1-linux-virtio.json

./hvisor zone list

screen /dev/pts/0

virtio-backend.json 为 zone1 提供 virtio-blk 和 virtio-console 的后端。zone1-linux-virtio.json 将 hart 4 ~ 7 分配给 zone1，并使用 AIA。

./hvisor zone list 可用于确认 zone0 / zone1 均已运行。随后执行 screen /dev/pts/0 即可连接 zone1 串口。

hvisor 手册