{"id":49316510,"url":"https://github.com/syswonder/hvisor-tool","last_synced_at":"2026-04-26T16:00:28.814Z","repository":{"id":241273604,"uuid":"804657927","full_name":"syswonder/hvisor-tool","owner":"syswonder","description":"hvisor tool for root linux, includes CLI, Virtio daemon and hvisor kernel module","archived":false,"fork":false,"pushed_at":"2026-04-22T07:21:10.000Z","size":581,"stargazers_count":14,"open_issues_count":3,"forks_count":24,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-22T09:29:25.094Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syswonder.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-23T02:34:59.000Z","updated_at":"2026-04-22T07:21:15.000Z","dependencies_parsed_at":"2024-11-17T09:20:55.975Z","dependency_job_id":"8d1b7271-3e7a-4484-b190-c6fa8d1a22e7","html_url":"https://github.com/syswonder/hvisor-tool","commit_stats":null,"previous_names":["syswonder/hvisor-tool"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/syswonder/hvisor-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syswonder%2Fhvisor-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syswonder%2Fhvisor-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syswonder%2Fhvisor-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syswonder%2Fhvisor-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syswonder","download_url":"https://codeload.github.com/syswonder/hvisor-tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syswonder%2Fhvisor-tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32303177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-26T16:00:18.138Z","updated_at":"2026-04-26T16:00:28.797Z","avatar_url":"https://github.com/syswonder.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# README\nREADME：[中文](./README-zh.md) | [English](./README.md)\n\n本仓库包含附属于[hvisor](https://github.com/syswonder/hvisor)的命令行工具及内核模块，命令行工具中还包含了Virtio守护进程，用于提供Virtio设备。命令行工具以及内核模块需要单独编译后，在管理虚拟机root linux-zone0上使用。整个仓库结构为：\n\n```\nhvisor-tool\n\t-tools: 包含命令行工具以及Virtio守护进程\n\t-driver: hvisor对应的内核模块\n\t-examples: 不同运行环境下的配置文件示例\n```\n\n## 编译步骤\n\n以下操作均在x86主机的目录`hvisor-tool`下，进行交叉编译。\n\n* 编译命令行工具及内核模块\n\n```bash\nmake all ARCH=\u003carch\u003e LOG=\u003clog\u003e KDIR=/path/to/your-linux LIBC=[gnu/musl] VIRTIO_GPU=[y/n] ROOT=/path/to/target_rootfs\n```\n\n其中，`\u003carch\u003e`应该为`arm64`和`riscv`之一。\n\n`\u003clog\u003e`为`LOG_TRACE`、`LOG_DEBUG`、`LOG_INFO`、`LOG_WARN`、`LOG_ERROR`、`LOG_FATAL`之一，用来控制Virtio守护进程的日志输出等级。\n\n`/path/to/your-linux`为root linux的kernel源码目录。具体的编译选项请见[Makefile](./Makefile)、[tools/Makefile](./tools/Makefile)、[driver/Makefile](./driver/Makefile)。\n\n`LIBC`指定编译`hvisor-tool`时使用的`libc`库，可为`gnu`或`musl`。\n\n例如，要编译面向`arm64`的命令行工具，可以执行：\n\n```bash\nmake all ARCH=arm64 LOG=LOG_WARN KDIR=~/linux\n```\n\n即可在`tools/hvisor`和`driver/hvisor.ko`，将其复制到root linux的根文件系统，使用即可。\n\n## 使用步骤\n\n### 内核模块\n\n使用命令行工具、Virtio守护进程之前，需要在zone0上加载内核模块，便于用户态程序与Hypervisor进行交互：\n\n```\ninsmod hvisor.ko\n```\n\n卸载内核模块的操作为：\n\n```\nrmmod hvisor.ko\n```\n\n### 命令行工具\n\n在root linux-zone0中，使用命令行工具可以创建、关闭其他虚拟机。\n\n* 启动新的虚拟机\n\n  hvisor-tool通过一个配置文件启动一个新的虚拟机：\n\n  ```\n  ./hvisor zone start \u003cvm_config.json\u003e\n  ```\n\n  `\u003cvm_config.json\u003e`是描述一个虚拟机配置的文件，例如：\n\n  * [在QEMU-aarch64上启动zone1](./examples/qemu-aarch64/with_virtio_blk_console/zone1_linux.json)：可参考[这里](./examples/qemu-aarch64/with_virtio_blk_console/README.md)了解如何配置并在zone1上启动一个linux。\n\n  * [在NXP-aarch64上启动zone1](./examples/nxp-aarch64/zone1_linux.json)：使用该文件直接启动zone1时，需首先启动Virtio守护进程，对应的配置文件为[virtio_cfg.json](./examples/nxp-aarch64/virtio_cfg.json)。\n\n* 关闭id为1的虚拟机：\n\n```\n./hvisor zone shutdown -id 1\n```\n\n* 打印当前所有虚拟机的信息：\n\n```\n./hvisor zone list\n```\n\n### Virtio守护进程\n\nVirtio守护进程可为虚拟机提供Virtio MMIO设备，目前支持四种设备：Virtio-blk、Virtio-net、Virtio-console和Virtio-gpu设备。\n\n#### 前置条件\n\n要使用Virtio守护进程，需要在**Root Linux的设备树**中增加一个名为`hvisor_virtio_device`的节点，例如：\n\n```dts\nhvisor_virtio_device {\n    compatible = \"hvisor\";\n    interrupt-parent = \u003c0x01\u003e;\n    interrupts = \u003c0x00 0x20 0x01\u003e;\n};\n```\n\n这样，当hvisor向Root Linux注入中断号为`32+0x20`的中断时，便会进入`hvisor.ko`中注册的中断处理函数，唤醒Virtio守护进程。\n\n如果`32+0x20`号中断已经被某个设备占用了，除了修改上述设备树节点，还需要修改hvisor主仓库中`IRQ_WAKEUP_VIRTIO_DEVICE`变量。对arm来说，如果`interrupts`中填写的值为`0xa`则`IRQ_WAKEUP_VIRTIO_DEVICE`需要为`32+0xa`；如果是riscv架构，则不需要增加32，使二者相等即可。\n\n#### Virtio设备的启动和创建\n\n在Root Linux上，执行以下示例指令：\n\n```c\n// 注意要先启动守护进程，再启动各个zones\nnohup ./hvisor virtio start virtio_cfg.json \u0026\n./hvisor zone start \u003cvm_config.json\u003e\n```\n\n其中 `\u0026` 说明该命令会在后台运行。由于 Virtio 守护进程使用 `syslog` 记录日志，使用以下命令查看 `hvisor-tool` 的日志：\n\n*   **对于使用 `systemd` 的系统：**\n    ```bash\n    journalctl -t hvisor-tool -f\n    ```\n*   **对于没有 `systemd` 的系统（日志由 `rsyslog` 处理）：**\n    ```bash\n    tail -f /var/log/syslog | grep hvisor-tool\n    ```\n\n`virtio_cfg.json` 则是一个描述Virtio设备的JSON file，例如[virtio_cfg.json](./examples/nxp-aarch64/virtio_cfg.json)。该示例文件会依次执行：\n\n1. 地址空间映射\n\n首先将id为1的虚拟机`zone1`的RAM内存区域通过mmap映射到Virtio守护进程的地址空间。\n\n2. 创建Virtio-blk设备\n\n创建一个Virtio-blk设备，`zone1`会通过一片MMIO区域与该设备通信，这片MMIO区域的起始地址为`0xa003c00`，长度为`0x200`。同时设置设备中断号为78，对应磁盘镜像为`rootfs2.ext4`。\n\n3. 创建Virtio-console设备\n\n创建一个Virtio-console设备，用于`zone1`主串口的输出。root linux需要执行`screen /dev/pts/x`命令进入该虚拟控制台，其中`x`可通过syslog日志查看。\n\n如要退回到主控制台，按下快捷键`ctrl+a+d`。如果在qemu中，则需要按下`ctrl+a ctrl+a+d`。如要再次进入虚拟控制台，执行`screen -r [SID]`，其中SID为该screen会话的进程ID。\n\n4. 创建Virtio-net设备\n\n由于`net`设备的`status`属性为`disable`，因此不会创建Virtio-net设备。如果`net`设备的`status`属性为`enable`，那么会创建一个Virtio-net设备，MMIO区域的起始地址为`0xa003600`，长度为`0x200`，设备中断号为75，MAC地址为`00:16:3e:10:10:10`，由id为1的虚拟机使用，连接到名为`tap0`的Tap设备。\n\n5. 创建Virtio-gpu设备\n\n要使用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`。\n\n#### 关闭Virtio设备\n\n执行该命令即可关闭Virtio守护进程及所有创建的设备：\n\n```\npkill hvisor-virtio\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyswonder%2Fhvisor-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyswonder%2Fhvisor-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyswonder%2Fhvisor-tool/lists"}