Add use openRuyi in QEMU/virt-manager

docs/guide/how-to-install/qemu.md

@@ -0,0 +1,58 @@
+---
+id: how-to-use-openruyi-qemu
+title: How to use openRuyi in QEMU
+description: This section provides a guide on how to use openRuyi in QEMU.
+slug: /guide/how-to-install/qemu
+---
+
+# How to use openRuyi in QEMU
+
+## Environment preparation
+
+To use openRuyi in QEMU, install the following packages:
+
+- `qemu-system-riscv64` requires QEMU 10.1 or later. If your QEMU version is preceding, you need to manually build QEMU or update your system version to support the RVA23S64 ISA. For example, Ubuntu requires version 25.10 or later has QEMU 10.1 or later.
+- `qemu-efi-riscv64/edk2-riscv64` EDK II is the reference implementation of the UEFI API. If your distribution does not package it, you can download the UEFI firmware from the [openRuyi download page](https://releases.openruyi.cn/creek/).
+
+## Download the image
+
+You will first need to obtain the openRuyi image files and the corresponding checksum files. Please visit our news site and refer to the latest release article, where you can find the qcow2 image and the checksums for the installation media.
+
+We provide SHA256 checksums for all image files. You may use any tool that supports the SHA256 algorithm to verify the integrity of the downloaded files.
+
+If the sha256sum command is available on your current system, place the checksum file in the same directory as the installation image and run the following command:
+
+```sh
+$ sha256sum openRuyi-xxxx.xx-Server-cloud.qcow2
+```
+
+## Run via QEMU
+
+The command for qcow2 images is as follows:
+
+```sh
+qemu-system-riscv64 \
+  -nographic -machine virt,pflash0=pflash0,pflash1=pflash1 \
+  -smp 8 -m 12G \
+  -cpu rva23s64 \
+  -blockdev node-name=pflash0,driver=file,read-only=on,filename="RISCV_VIRT_CODE.fd" \
+  -blockdev node-name=pflash1,driver=file,filename="RISCV_VIRT_VARS.fd" \
+  -drive file="openRuyi-2026.03-Server-cloud.qcow2",format=qcow2,id=hd0,if=none \
+  -object rng-random,filename=/dev/urandom,id=rng0 \
+  -device virtio-vga \
+  -device virtio-rng-device,rng=rng0 \
+  -device virtio-blk-device,drive=hd0 \
+  -device virtio-net-device,netdev=usernet \
+  -netdev user,id=usernet,hostfwd=tcp::12055-:22 \
+  -device qemu-xhci -usb -device usb-kbd -device usb-tablet
+```
+
+Important options include:
+
+- `-nographic` uses the current terminal to log in through the serial console. Remove this option to log in through the QEMU GUI.
+- `-cpu` controls the emulated CPU architecture. `rva23s64` requires QEMU 10.1 or later.
+- `-m` and `-smp` specify the amount of memory and the number of CPU cores available to openRuyi.
+- `-blockdev node-name=pflash0,driver=file,read-only=on,filename="RISCV_VIRT_CODE.fd"` and `-blockdev node-name=pflash1,driver=file,filename="RISCV_VIRT_VARS.fd"` specify the [RISC-V EDK II firmware](https://github.com/tianocore/tianocore.github.io/wiki/RiscVPkg).
+- `netdev user,id=usernet,hostfwd=tcp::12055-:22` configures QEMU port forwarding. You can log in with `ssh -p 12055 root@localhost`.
+
+After startup, log in as user `root` with the default password `openruyi`. In the terminal, press `C-a x` to exit QEMU.

docs/guide/how-to-install/virt.md

@@ -0,0 +1,97 @@
+---
+id: how-to-use-openruyi-virt
+title: How to use openRuyi in virt-manager
+description: This section provides a guide on how to use openRuyi in virt-manager.
+slug: /guide/how-to-install/virt
+---
+
+# How to use openRuyi in virt-manager
+
+## Environment preparation
+
+To use openRuyi in virt-manager, install the following packages:
+
+- `libvirt` and `virt-manager`. Install them and enable the libvirt service.
+- `qemu-system-riscv64` requires QEMU 10.1 or later. If your QEMU version is too old, you need to manually build QEMU or update your system version to support the RVA23S64 ISA. For example, Ubuntu requires version 25.10 or later.
+- `qemu-efi-riscv64/edk2-riscv64`. EDK II is the reference implementation of the UEFI API. If your distribution does not package it, you can download the UEFI firmware from the [openRuyi download page](https://releases.openruyi.cn/creek/).
+
+## Download the image
+
+You will first need to obtain the openRuyi image files and the corresponding checksum files. Please visit our news site and refer to the latest release article, where you can find the ISO or qcow2 image and the checksums for the installation media.
+
+We provide SHA256 checksums for all image files. You may use any tool that supports the SHA256 algorithm to verify the integrity of the downloaded files.
+
+If the sha256sum command is available on your current system, place the checksum file in the same directory as the installation image and run the following command:
+```sh
+$ sha256sum openruyi-xxxx.xx-Server-dvd.iso
+```
+
+## Configure virt-manager
+
+Open virt-manager, click `+` to create a new virtual machine, and select `riscv64` in the architecture option at the bottom.
+
+![step1](/img/how-to-run/virt/image-1-create-vm.png)
+
+Proceed to select the operating system type (you can specify Generic Linux 2024), memory and processor settings, and storage space. If you use a qcow2 image, you can specify it here. In Step 5, check `Customize configuration before install`, and then click Finish to enter the virtual machine details page.
+
+![step5](/img/how-to-run/virt/image-2-customize-config.png)
+
+### Configure the CPU
+
+On the `CPUs` page, set Model to `rva23s64`. When virt-manager creates a virtual machine, even if you select rva23s64, it still uses Sv39 by default, which may cause some issues. To enable Sv48, add the following content to the CPU parameters:
+
+```xml
+  <cpu mode="custom" match="exact" check="none">
+    <model fallback="allow">rva23s64</model>
+    <feature policy="require" name="sv48"/>
+  </cpu>
+```
+
+This is equivalent to `qemu-system-riscv64 -cpu rva23s64,sv48=on`.
+
+![cpu](/img/how-to-run/virt/image-3-cpu-config.png)
+
+### Configure the RISC-V EDK II firmware
+
+:::warning
+This subsection applies only to distributions that do not package the EDK2 firmware. If virt-manager reports that it cannot find a UEFI binary when creating the virtual machine, follow the steps below. If no such prompt appears, you can skip this section because virt-manager will automatically use the installed UEFI firmware.
+:::
+
+Because this part cannot be configured in the virt-manager graphical interface, you need to manually edit the libvirt XML.(Need to enable the XML editing option in virt-manager preference)
+
+Modify the existing `<os>` node as follows, and update the paths to point to the UEFI EDK II firmware:
+
+```xml
+  <os>
+    <type arch="riscv64" machine="virt">hvm</type>
+    <loader readonly="yes" type="pflash" format="raw">/path/to/RISCV_VIRT_CODE.fd</loader>
+    <nvram format="raw">/path/to/RISCV_VIRT_VARS.fd</nvram>
+  </os>
+```
+
+![xml](/img/how-to-run/virt/image-7-edk2-xml.png)
+
+### Configure the install image
+
+If you use an openRuyi Server qcow2 image, you can skip the CDROM configuration in this section.
+
+If you boot from an ISO image, as shown in the figure, click `Add Hardware` -> `Storage` -> `Select or create custom storage` to select the downloaded ISO image, and set `Device Type` to `CDROM Device`.
+
+![CDROM](/img/how-to-run/virt/image-5-cdrom-storage.png)
+
+After clicking Finish, adjust the boot order. In `Boot Options`, enable `Enable boot menu`, and place `SATA CDROM *` before the empty disk image `VirtIO Disk *` that was created when creating the virtual machine.
+
+### Enable 3D graphics rendering (optional)
+
+By enabling `virtio-gl`, you can use the virtual GPU for graphics rendering. This can avoid graphics rendering issues and accelerate graphics rendering. The host hardware must support OpenGL and have mesa installed.
+
+In `Video Virtio`, check `3D acceleration`. Then, in `Display Spice`, set `Listen Type` to `None`, check `OpenGL`, and select the host display output device below.
+
+![virtgl](/img/how-to-run/virt/image-6-virtio-gl.png)
+
+### Start openRuyi
+
+Click Start Installation. If there are no errors, the virtual machine will boot. In `View` -> `Consoles`, you can switch between graphical output and the serial console.
+
+- If you use an ISO image, you can install openRuyi according to the version of the openRuyi image you downloaded. For reference, see installing openRuyi on physical machines: [Workstation Edition](./workstation) and [Server Edition](./server).
+- If you use a qcow2 image, you can run openRuyi directly.

i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/how-to-install/qemu.md

@@ -0,0 +1,58 @@
+---
+id: how-to-use-openruyi-qemu
+title: 如何在 QEMU 内使用 openRuyi
+description: 这篇文章教学如何在 QEMU 内使用 openRuyi。
+slug: /guide/how-to-install/qemu
+---
+
+# 如何在 QEMU 内使用 openRuyi
+
+## 环境准备
+
+要在 QEMU 内使用 openRuyi，需要安装如下软件包。
+
+- `qemu-system-riscv64` 需要使用 QEMU 10.1 或更高版本，若版本过低需要手动编译或更新系统版本来支持 RVA23S64 ISA（例如 Ubuntu 需要 25.10 及更高版本）。
+- `qemu-efi-riscv64/edk2-riscv64` EDK II 是 UEFI API 的参考实现，若发行版未打包，则可在[openRuyi 下载页](https://releases.openruyi.cn/creek/)下载 UEFI 固件。
+
+## 下载镜像 
+
+您需要先获取 openRuyi 的镜像文件和对应校验文件。请访问我们的新闻页，在最新的版本文章下方获取 qcow2 文件以及相应的安装映像的校验和。
+
+我们对于所有的镜像文件都提供了安装映像的基于 SHA256 算法的校验和。您可以使用任何支持该算法的检验工具来检查文件校验和是否正确。
+
+如果您正在使用的系统上安装了 sha256sum 命令，则可以将校验和文件放在安装映像的同一个目录下，然后运行一下命令来验证：
+
+```sh
+$ sha256sum openRuyi-xxxx.xx-Server-cloud.qcow2
+```
+
+## 通过 QEMU 运行
+
+适用于 qcow2 镜像的命令如下。
+
+```sh
+qemu-system-riscv64 \
+  -nographic -machine virt,pflash0=pflash0,pflash1=pflash1 \
+  -smp 8 -m 12G \
+  -cpu rva23s64 \
+  -blockdev node-name=pflash0,driver=file,read-only=on,filename="RISCV_VIRT_CODE.fd" \
+  -blockdev node-name=pflash1,driver=file,filename="RISCV_VIRT_VARS.fd" \
+  -drive file="openRuyi-2026.03-Server-cloud.qcow2",format=qcow2,id=hd0,if=none \
+  -object rng-random,filename=/dev/urandom,id=rng0 \
+  -device virtio-vga \
+  -device virtio-rng-device,rng=rng0 \
+  -device virtio-blk-device,drive=hd0 \
+  -device virtio-net-device,netdev=usernet \
+  -netdev user,id=usernet,hostfwd=tcp::12055-:22 \
+  -device qemu-xhci -usb -device usb-kbd -device usb-tablet
+```
+
+重要的选项包括:
+
+- `-nographic` 使用当前终端登录串口，删除后可使用 QEMU GUI 登录。
+- `-cpu` 控制模拟的 CPU 架构，rva23s64 需要 QEMU 10.1 或更高版本。
+- `-m` `-smp` 指定 openRuyi 可使用的内存和 CPU 核心数量。
+- `-blockdev node-name=pflash0,driver=file,read-only=on,filename="RISCV_VIRT_CODE.fd"`，`-blockdev node-name=pflash1,driver=file,filename="RISCV_VIRT_VARS.fd"` 指定 [RISCV EDK II 固件](https://github.com/tianocore/tianocore.github.io/wiki/RiscVPkg)。
+- `netdev user,id=usernet,hostfwd=tcp::12055-:22` 配置 QEMU 端口转发，可通过 `ssh -p 12055 root@localhost` 登录。
+
+启动后，使用用户 `root` 登录，默认密码为 `openruyi`，在终端中可按 `C-a x` 退出 QEMU。

i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/how-to-install/virt.md

@@ -0,0 +1,96 @@
+---
+id: how-to-use-openruyi-virt
+title: 如何在 virt-manager 内使用 openRuyi
+description: 这篇文章介绍如何在 virt-manager 内使用 openRuyi。
+slug: /guide/how-to-install/virt
+---
+
+# 如何在 virt-manager 内使用 openRuyi
+
+## 环境准备
+
+要在 virt-manager 内使用 openRuyi，需要安装如下软件包。
+
+- `libvirt`、`virt-manager` 安装并启用 libvirt 服务。
+- `qemu-system-riscv64` 需要使用 QEMU 10.1 或更高版本，若版本过低需要手动编译或更新系统版本来支持 RVA23S64 ISA（例如 Ubuntu 需要 25.10 及更高版本）。
+- `qemu-efi-riscv64/edk2-riscv64` EDK II 是 UEFI API 的参考实现，若发行版未打包，则可在 [openRuyi 下载页](https://releases.openruyi.cn/creek/)下载 UEFI 固件。
+
+## 下载镜像 
+
+您需要先获取 openRuyi 的镜像文件和对应校验文件，其中 ISO 可用于安装 openRuyi，qcow2 可直接启动 openRuyi，请访问我们的新闻页，在最新的版本文章下方获取 ISO 或 qcow2 文件以及相应的安装映像的校验和。
+
+我们对于所有的镜像文件都提供了安装映像的基于 SHA256 算法的校验和。您可以使用任何支持该算法的检验工具来检查文件校验和是否正确。
+
+如果您正在使用的系统上安装了 sha256sum 命令，则可以将校验和文件放在安装映像的同一个目录下，然后运行一下命令来验证：
+```sh
+$ sha256sum openruyi-xxxx.xx-Server-dvd.iso
+```
+
+## 配置 virt-manager
+
+进入 virt-manager 点击“+”创建新的虚拟机，在下方架构选项中选择架构：`riscv64`。
+
+![step1](/img/how-to-run/virt/image-1-create-vm.png)
+
+前进选择系统种类（可指定为 Generic Linux 2024）、内存和处理器设置、存储空间（若使用 qcow2 可在此指定），在 Step 5 中勾选 `Customize configuration before install` 后点击完成进入虚拟机详细设置界面。
+
+![step5](/img/how-to-run/virt/image-2-customize-config.png)
+
+### 配置 CPU
+在 `CPUs` 页面中配置 Model 为`rva23s64`，virt-manager 默认创建虚拟机时如果选择了 rva23s64，默认仍然会采用 Sv39，这可能会造成一些问题，开启 Sv48 则需要在 CPU 参数部分添加如下内容：
+
+```xml
+  <cpu mode="custom" match="exact" check="none">
+    <model fallback="allow">rva23s64</model>
+    <feature policy="require" name="sv48"/>
+  </cpu>
+```
+
+其等价于 `qemu-system-riscv64 -cpu rva23s64,sv48=on`。
+
+![cpu](/img/how-to-run/virt/image-3-cpu-config.png)
+
+### 配置 RISCV EDK II 固件
+
+:::warning
+此小节仅适用于发行版没有打包 EDK2 固件的发行版，若创建虚拟机时 virt-manager 提示找不到 UEFI 二进制，则请按照以下步骤操作；若没有相关提示，可跳过这一节，virt-manager 会自动使用已安装的 UEFI 固件。
+:::
+
+该选项在 virt-manager 图形界面内无法配置，需要手动修改 libvirt XML（需要在 virt-manager 中启用 XML 编辑选项）。
+
+在现有 `<os>` 节点中修改为如下配置，并修改指向 UEFI EDK II 固件的路径。
+
+```xml
+  <os>
+    <type arch="riscv64" machine="virt">hvm</type>
+    <loader readonly="yes" type="pflash" format="raw">/path/to/RISCV_VIRT_CODE.fd</loader>
+    <nvram format="raw">/path/to/RISCV_VIRT_VARS.fd</nvram>
+  </os>
+```
+
+![xml](/img/how-to-run/virt/image-7-edk2-xml.png)
+
+### 配置安装盘
+
+如使用 openRuyi server qcow2 可跳过本节的 CDROM 配置。
+
+如使用 ISO 镜像进行启动，如图所示，需要依次点击 `Add Hardware`、`Storage`、`Select or create custom storage` 选择下载的 ISO 镜像，并将 `Device Type` 置于 `CDROM Device`。
+
+![CDROM](/img/how-to-run/virt/image-5-cdrom-storage.png)
+
+点击完成后，需要调整启动顺序，在 `Boot Options` 启用 `Enable boot menu`，将 `SATA CDROM *` 至于在虚拟机创建引导时创建的空硬盘镜像 `VirtIO Disk *`之前。
+
+### 启用 3D 图形渲染（可选）
+
+通过启用 `virtio-gl` 可使用虚拟 GPU 进行图形渲染，避免图形渲染问题并加速图形渲染（需要宿主机硬件支持 OpenGL 并安装 mesa）。
+
+在 `Video Virtio` 中勾选启用 `3D acceleration`，然后在 `Display Spice` 将 `Listen Type` 修改为  `None` 并勾选 `OpenGL`，在下方选择宿主机的显示输出设备。
+
+![virtgl](/img/how-to-run/virt/image-6-virtio-gl.png)
+
+### 启动 openRuyi
+
+点击开始安装后无报错会进行启动，在 `View` 菜单中选择 `Consoles` 可切换显示图形输出或串口控制台。
+
+- 如使用 iso 镜像，稍后可根据您下载的 openRuyi 镜像版本进行安装，可参考在实机安装 openRuyi [工作站版](./workstation)、[服务器版](./server)。
+- 如使用 qcow2，则可直接使用 openRuyi。