{"id":16570330,"url":"https://github.com/kuangjux/hypocaust-2","last_synced_at":"2025-03-21T11:33:50.895Z","repository":{"id":109540384,"uuid":"601182590","full_name":"KuangjuX/hypocaust-2","owner":"KuangjuX","description":"hypocaust-2, a type-1 hypervisor with H extension run on RISC-V machine","archived":false,"fork":false,"pushed_at":"2023-11-30T06:23:48.000Z","size":49457,"stargazers_count":54,"open_issues_count":5,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-18T01:11:13.330Z","etag":null,"topics":["hypervisor","riscv","rust","vmm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KuangjuX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-02-13T14:40:00.000Z","updated_at":"2025-02-07T09:51:34.000Z","dependencies_parsed_at":"2023-11-30T07:38:08.631Z","dependency_job_id":null,"html_url":"https://github.com/KuangjuX/hypocaust-2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KuangjuX%2Fhypocaust-2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KuangjuX%2Fhypocaust-2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KuangjuX%2Fhypocaust-2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KuangjuX%2Fhypocaust-2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KuangjuX","download_url":"https://codeload.github.com/KuangjuX/hypocaust-2/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244792439,"owners_count":20511131,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hypervisor","riscv","rust","vmm"],"created_at":"2024-10-11T21:18:28.113Z","updated_at":"2025-03-21T11:33:46.802Z","avatar_url":"https://github.com/KuangjuX.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hypocaust-2\n## Overview\nHypocaust-2 is an experimental type-1 hypervisor with H extension run on RISC-V machine. It depends on the RISC -V H extension, which currently runs on QEMU 7.1.0 or above. It is the successor of the [hypocaust](https://github.com/KuangjuX/hypocaust) project.  \n\n  \nMy plan is to build a high-performance riscv64 hypervisor that physically maps the cpu cores, so there is no need to schedule guests in the hypervisor. In addition, the passthrough method for IO devices has achieved good performance.  \n  \nThe purpose of this project is to run on bare metal or embedded devices, but it is not ruled out that kvm technology will be used and run on linux in the future.  \n  \n[![asciicast](https://asciinema.org/a/564050.png)](https://asciinema.org/a/564050)\n\n\n\n## Environment\n- QEMU 7.1.0\n- RustSBI-QEMU Prereleased 2023-02-01\n- Rust 1.66.0 \n\n\n## Examples \n\n### rCore-Tutorial-v3\n```\n./srcipts/rCore-Tutorial-v3.sh \u0026\u0026 make qemu PLATFORM=rCore-Tutorial-v3\n```\n\n### RT-Thread\n```\n./srcipts/rt-thread.sh \u0026\u0026 make qemu PLATFORM=rt-thread\n```\n\n### Linux\n**Toolchains:**\n```\n$ sudo apt install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \\\n                 gawk build-essential bison flex texinfo gperf libtool patchutils bc \\\n                 zlib1g-dev libexpat-dev git \\\n                 libglib2.0-dev libfdt-dev libpixman-1-dev \\\n                 libncurses5-dev libncursesw5-dev\n\n# install riscv linux toolchain\n$ git clone https://gitee.com/mirrors/riscv-gnu-toolchain --depth=1\n$ cd riscv-gnu-toolchain\n$ git rm qemu\n$ git submodule update --init --recursive\n$ ./configure --prefix=/opt/riscv64 --with-arch=rv64imac --with-abi=lp64\n$ sudo make linux -j8\n$ export PATH=$PATH:/opt/riscv64/bin\n```\n\n**Build Linux:**\n```\n$ git clone https://github.com/torvalds/linux -b v6.2\n$ cd linux\n$ git am ${HYPOCAUST_2_DIR}/guest/linux/patches/*.patch\n$ make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- defconfig\n$ make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- menuconfig\n$ make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- all -j8\n```\n\n**Run bare Linux on qemu:**\n```\n$ qemu-system-riscv64 -M virt -m 256M -nographic -bios $(BOOTLOADER)/rustsbi-qemu.bin -kernel $(linux)/arch/riscv/boot/Image\n```\n\n**Docker Command（MacOS/Windows）:**\n```\n# run docker container, mount workspace in docker\n\ndocker run -itd --name riscv-env --privileged -v {WORKSPACE}:/workspace riscv-gnu-toolchain /bin/bash\n\n# run docker\ndocker exec -it riscv-env /bin/bash\n```\n\n**Make rootfs:**\n```\ngit clone https://gitee.com/mirrors/busyboxsource.git\ncd busyboxsource\n\n# Select: Settings -\u003e Build Options -\u003e Build static binary\nCROSS_COMPILE=riscv64-unknown-linux-gnu- make menuconfig\n\n## Build \u0026\u0026 Install\nCROSS_COMPILE=riscv64-unknown-linux-gnu- make -j10\nCROSS_COMPILE=riscv64-unknown-linux-gnu- make install\n\n# Make minimal root file system\ncd ../\nqemu-img create rootfs.img  1g\nmkfs.ext4 rootfs.img\n\n# mount file system \u0026\u0026 copy busybox\nmkdir rootfs\nmount -o loop rootfs.img rootfs\ncd rootfs\ncp -r ../busyboxsource/_install/* .\nmkdir proc dev tec etc/init.d\n\ncd etc/init.d/\ntouch rcS\nvim rcS\n\n#####\n#!/bin/sh\nmount -t proc none /proc\nmount -t sysfs none /sys\n/sbin/mdev -s\n#####\n\nchmod +x rcS\n\numount rootfs\n\nqemu-system-riscv64 -M virt -m 256M -nographic -bios {BOOTLOADR} -kernel {KERNEL_ELF} -drive file=rootfs.img,format=raw,id=hd0  -device virtio-blk-device,drive=hd0 -append \"root=/dev/vda rw console=ttyS0\"\n\n```\n\n## RoadMap\n- [x] Load guest elf image.\n- [x] Jump guest loaded to a VM while enabling guest physical address translation by `hgatp`.\n- [x] Run a tiny kernel that does not require any external hardware like disk devices.\n- [x] Handle read/write requests for CSRs from a guest\n- [x] Handle SBI calls(currently only `console_putchar`, `console_getchar` and `set_timer` and `base` related)\n- [x] Guest enable paging \u0026 setup 2-stage page table translation.\n- [x] Jump VU mode and run user applications\n- [x] Timers\n- [x] Passthrough virtio block device\n- [x] Configure hypervisor and guest memory addresses and peripheral space mapping by device tree.\n- [x] Emulate PLIC \u0026\u0026 Forward interrupts\n- [x] Expose and/or emulate peripherals\n- [x] run rCore-Tutorial-v3\n- [x] run RT-Thread\n- [x] run Linux\n- [ ] IOMMU enabled\n- [ ] AIA support\n- [ ] multicore supported\n- [ ] multiguest supported\n\n## Features\n### Doamin Isolation\n- [ ] VCPU and Host Interrupt Affinity\n- [ ] Spatial and Temporal Memory Isolation\n\n### Device Virtualization\n- [ ] Pass-through device support(enable IOMMU)\n- [ ] Block device virtualization\n- [ ] Network device virtualization\n- [ ] Input device virtualization\n- [ ] Display device virtualization\n\n## Configuration\n### Device Tree\n\nTwo types of device tree(DT):\n1. **Host DT:** \n- Device tree which describes underlying host HW to hypocaust-2\n- Used by hypocaust-2 at boot-time\n\n2. **Guest DT:**\n- Device tree which dscribes Guest virtual HW to hypocaust-2\n- Used by hypocaust-2 to create Guest\n\n## Tips\n- When the hypervisor is initialized, it is necessary to write the `hcounteren` register to all 1, because it is possible to read the `time` register in VU mode or VS mode.(refs: The counter-enable register `hcounteren` is a 32-bit register that controls the availability of the hardware performance monitoring counters to the guest virtual machine.  \nWhen the CY, TM, IR, or HPMn bit in the hcounteren register is clear, attempts to read the\ncycle, time, instret, or hpmcountern register while V=1 will cause a virtual instruction exception\nif the same bit in mcounteren is 1. When one of these bits is set, access to the corresponding register\nis permitted when V=1, unless prevented for some other reason. In VU-mode, a counter is not\nreadable unless the applicable bits are set in both `hcounteren` and `scounteren`.  \n`hcounteren` must be implemented. However, any of the bits may be read-only zero, indicating\nreads to the corresponding counter will cause an exception when V=1. Hence, they are effectively\nWARL fields.) \n- When the hypervisor initializes the memory for the guest, it needs to set all the mapping flags of the guest memory to RWX, although it needs to be modified in the end. Otherwise, when the guest allocates memory for the application, it will not be executable, causing `InstructionGuestPageFault`. \n- The hypervisor currently does not support IOMMU, so it is necessary to have all its memory configured with identify mapping when guest wishes to use a DMA device.\n\n## Design Docs\n- [Trap Design](docs/trap.md)\n- [Guest Page Table Design](docs/guest_page_table.md)\n\n## References\n- [hypocaust](https://github.com/KuangjuX/hypocaust)\n- [rustyvisor](https://github.com/stemnic/rustyvisor)\n- [bao-hypervisor](https://github.com/bao-project/bao-hypervisor)\n- [salus](https://github.com/rivosinc/salus)\n\n## Relative Links\n- [QEMU 运行 RISC-V linux 总结](http://www.icfgblog.com/index.php/software/324.html)\n- [QEMU 启动方式分析(1): QEMU 及 RISC-V 启动流程简介](https://gitee.com/YJMSTR/riscv-linux/blob/master/articles/20220816-introduction-to-qemu-and-riscv-upstream-boot-flow.md#https://gitee.com/link?target=https%3A%2F%2Ftinylab.org%2Friscv-uefi-part1%2F)\n- [QEMU 启动方式分析(2): QEMU virt 平台下通过 OpenSBI + U-Boot 引导 RISC-V 64 Linux](https://gitee.com/YJMSTR/riscv-linux/blob/master/articles/20220823-boot-riscv-linux-kernel-with-uboot-on-qemu-virt-machine.md)\n\n- [Virtual Memory Layout on RISC-V Linux](https://www.kernel.org/doc/html/latest/riscv/vm-layout.html)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuangjux%2Fhypocaust-2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuangjux%2Fhypocaust-2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuangjux%2Fhypocaust-2/lists"}