fix(axvisor): correct cargo commands and update image layout in scripts and docs

os/axvisor/.cargo/config.toml

@@ -32,6 +32,3 @@ rustflags = [
 
 [target.'cfg(target_os = "none")']
 runner = "cargo osrun"
-
-[alias]
-xtask = "run --features host-xtask --bin xtask --"

os/axvisor/README.md

@@ -85,15 +85,15 @@ On x86_64, `boot_protocol` selects the guest firmware flow. `multiboot` keeps th
 
 AxVisor uses the xtask tool for build management, supporting multiple hardware platforms and configuration options. For a quick build and run of AxVisor, please refer to the [Quick Start](https://arceos-hypervisor.github.io/axvisorbook/docs/quickstart) chapter in the configuration documentation.
 
-1. **List Available Boards**: Use `cargo xtask config ls` to view the available board names under `configs/board/`.
+1. **List Available Boards**: Use `cargo xtask axvisor config ls` to view the available board names under `configs/board/`.
 
-2. **Generate Configuration**: Use `cargo xtask defconfig <board_name>` to copy the selected board-level configuration to `.build.toml`.
+2. **Generate Configuration**: Use `cargo xtask axvisor defconfig <board_name>` to copy the selected board-level configuration to `.build.toml`.
 
-3. **Execute Build**: Use `cargo xtask build` to compile AxVisor according to `.build.toml`. You can also pass an explicit config file via `cargo xtask build --config configs/board/<board_name>.toml`.
+3. **Execute Build**: Use `cargo xtask axvisor build` to compile AxVisor according to `.build.toml`. You can also pass an explicit config file via `cargo xtask axvisor build --config configs/board/<board_name>.toml`.
 
 4. **Run on QEMU or Board**:
-   - QEMU: `cargo xtask qemu --config configs/board/qemu-aarch64.toml --qemu-config .github/workflows/qemu-aarch64.toml --vmconfigs configs/vms/qemu/aarch64/arceos-smp1.toml`
-   - U-Boot board flow: `cargo xtask uboot --config configs/board/roc-rk3568-pc.toml --uboot-config .github/workflows/uboot.toml --vmconfigs configs/vms/roc-rk3568-pc/arceos-smp1.toml`
+   - QEMU: `cargo xtask axvisor qemu --config configs/board/qemu-aarch64.toml --qemu-config .github/workflows/qemu-aarch64.toml --vmconfigs configs/vms/qemu/aarch64/arceos-smp1.toml`
+   - U-Boot board flow: `cargo xtask axvisor uboot --config configs/board/roc-rk3568-pc.toml --uboot-config .github/workflows/uboot.toml --vmconfigs configs/vms/roc-rk3568-pc/arceos-smp1.toml`
 
 For local bring-up, you can also use `./scripts/quick-start.sh` for the supported QEMU and board platforms. See the [QEMU Quickstart Guide](doc/qemu-quickstart.md) for examples.
 

os/axvisor/README_CN.md

@@ -83,15 +83,15 @@ Board 运行配置位于 `configs/board/` 目录下，每个配置文件都对
 
 AxVisor 使用 xtask 工具进行构建管理，支持多种硬件平台和配置选项。快速构建及运行 AxVisor，请参见配置套文档中的[快速上手](https://arceos-hypervisor.github.io/axvisorbook/docs/quickstart)章节。
 
-1. **查看可用板级配置**：使用 `cargo xtask config ls` 查看 `configs/board/` 目录下可用的板级配置名。
+1. **查看可用板级配置**：使用 `cargo xtask axvisor config ls` 查看 `configs/board/` 目录下可用的板级配置名。
 
-2. **生成配置**：使用 `cargo xtask defconfig <board_name>` 选择目标硬件平台配置。此命令会将对应板级配置复制为 `.build.toml`。
+2. **生成配置**：使用 `cargo xtask axvisor defconfig <board_name>` 选择目标硬件平台配置。此命令会将对应板级配置复制为 `.build.toml`。
 
-3. **执行构建**：使用 `cargo xtask build` 根据 `.build.toml` 编译 AxVisor。若不想依赖 `.build.toml`，也可以直接指定配置文件，例如：`cargo xtask build --config configs/board/<board_name>.toml`。
+3. **执行构建**：使用 `cargo xtask axvisor build` 根据 `.build.toml` 编译 AxVisor。若不想依赖 `.build.toml`，也可以直接指定配置文件，例如：`cargo xtask axvisor build --config configs/board/<board_name>.toml`。
 
 4. **运行 QEMU 或开发板**：
-   - QEMU：`cargo xtask qemu --config configs/board/qemu-aarch64.toml --qemu-config .github/workflows/qemu-aarch64.toml --vmconfigs configs/vms/qemu/aarch64/arceos-smp1.toml`
-   - U-Boot 开发板流程：`cargo xtask uboot --config configs/board/roc-rk3568-pc.toml --uboot-config .github/workflows/uboot.toml --vmconfigs configs/vms/roc-rk3568-pc/arceos-smp1.toml`
+   - QEMU：`cargo xtask axvisor qemu --config configs/board/qemu-aarch64.toml --qemu-config .github/workflows/qemu-aarch64.toml --vmconfigs configs/vms/qemu/aarch64/arceos-smp1.toml`
+   - U-Boot 开发板流程：`cargo xtask axvisor uboot --config configs/board/roc-rk3568-pc.toml --uboot-config .github/workflows/uboot.toml --vmconfigs configs/vms/roc-rk3568-pc/arceos-smp1.toml`
 
 如果是本地快速验证，也可以直接使用 `./scripts/quick-start.sh` 启动当前脚本支持的 QEMU 和开发板平台。具体示例见 [QEMU 快速上手指南](doc/qemu-quickstart_cn.md)。
 

os/axvisor/doc/qemu-quickstart.md

@@ -79,117 +79,78 @@ export AXVISOR_X86_64_UEFI_FIRMWARE=/path/to/OVMF_CODE.fd
 
 ## 4. Running Guest OSes
 
-This branch provides a one-click setup script `scripts/setup_qemu.sh` that automatically downloads guest images, patches configuration paths, and prepares the rootfs.
+> **Note**: All commands in this section are run from the **axvisor directory** (`os/axvisor/`). If you are in the tgoskits repository root, run `cd os/axvisor` first.
 
-LoongArch64 AxVisor shell smoke is a separate path: it does not need guest images, but it does require a virtualization-capable LoongArch QEMU build such as QEMU-LVZ. It also does not use `scripts/setup_qemu.sh`; if you try `./scripts/setup_qemu.sh loongarch64`, the script will point you back to `./scripts/quick-start.sh qemu-loongarch64 start`.
+This branch provides a one-click setup script `scripts/quick-start.sh` that automatically downloads guest images, generates configs, builds, and launches QEMU.
 
 ### ArceOS (AArch64)
 
 ```bash
-./scripts/setup_qemu.sh arceos
-
-cargo xtask qemu \
-  --config configs/board/qemu-aarch64.toml \
-  --qemu-config .github/workflows/qemu-aarch64.toml \
-  --vmconfigs tmp/vmconfigs/arceos-aarch64-qemu-smp1.generated.toml
+./scripts/quick-start.sh qemu-aarch64 start --arceos
 ```
 
-Success indicator: `Hello, world!` appears in the output.
+ArceOS is a lightweight unikernel. It prints `Hello, world!` and exits immediately. After the guest exits, you land in the **AxVisor management shell** (`axvisor:/$`).
 
 ### Linux (AArch64)
 
 ```bash
-./scripts/setup_qemu.sh linux
-
-cargo xtask qemu \
-  --config configs/board/qemu-aarch64.toml \
-  --qemu-config .github/workflows/qemu-aarch64.toml \
-  --vmconfigs tmp/vmconfigs/linux-aarch64-qemu-smp1.generated.toml
+./scripts/quick-start.sh qemu-aarch64 start --linux
 ```
 
-Success indicator: `test pass!` appears in the output.
+You land in the **Linux guest's BusyBox interactive shell** (prompt `~ #`). Run `pkill qemu` from another terminal or close the QEMU window to exit.
 
 ### NimbOS (x86_64, requires KVM)
 
+NimbOS images are not available through the standard registry. Use the two-step approach:
+
 ```bash
+# Step 1: download images + generate configs
 ./scripts/setup_qemu.sh nimbos
 
-cargo xtask qemu \
-  --config configs/board/qemu-x86_64.toml \
-  --qemu-config .github/workflows/qemu-x86_64-kvm.toml \
-  --vmconfigs tmp/vmconfigs/nimbos-x86_64-qemu-smp1.generated.toml
+# Step 2: copy the absolute-path command printed by the script
 ```
 
-After booting, you will enter the Rust user shell (`>>` prompt). Type `usertests` to run the test suite. All tests passing will print `usertests passed!`
+After booting, you enter the **Rust user shell** (`>>` prompt). Try commands like `usertests` to explore.
 
 > **Note**: NimbOS requires VT-x/KVM. If `/dev/kvm` does not exist or has insufficient permissions, you will get a `Permission denied` error. WSL2 requires nested virtualization support in the kernel to use KVM.
 
-### Linux UEFI (x86_64, requires KVM and OVMF)
+### AxVisor Shell (LoongArch64, requires QEMU-LVZ)
 
 ```bash
-./scripts/setup_qemu.sh linux-x86_64-uefi
-
-cargo xtask qemu \
-  --config configs/board/qemu-x86_64.toml \
-  --qemu-config .github/workflows/qemu-x86_64-uefi.toml \
-  --vmconfigs tmp/vmconfigs/linux-x86_64-qemu-uefi-smp1.generated.toml
+./scripts/quick-start.sh qemu-loongarch64 start
 ```
 
-The UEFI VM config sets `boot_protocol = "uefi"` and `uefi_firmware_path`, which tells AxVisor to load the external firmware image without applying the legacy axvm-bios multiboot patch. This Linux guest also provides `ramdisk_path` so the initramfs is available before boot.
+This command launches AxVisor directly without booting a guest image. You enter the **AxVisor management shell** (`axvisor:/$`), preceded by `Welcome to AxVisor Shell!` in the output.
 
-### ArceOS UEFI (x86_64, requires KVM, OVMF, and a local guest image)
+> **Note**: Stock `qemu-system-loongarch64` usually does not expose LoongArch virtualization extensions. Use `QEMU-LVZ`, or set `AXBUILD_QEMU_SYSTEM_LOONGARCH64=/path/to/qemu-system-loongarch64` to a validated virtualization-capable binary.
 
-The ArceOS x86_64 UEFI path is provided as a local bring-up flow because the image registry does not currently publish a prebuilt ArceOS x86_64 UEFI guest. Build or place the guest image locally, then export:
+## 5. Step-by-Step Execution (for Development)
 
-```bash
-export AXVISOR_X86_64_ARCEOS_UEFI_KERNEL=/path/to/arceos-x86_64-uefi.bin
-export AXVISOR_X86_64_UEFI_FIRMWARE=/path/to/OVMF_CODE.fd
-```
+If you need to rebuild repeatedly without re-downloading images every time, split into two steps:
 
-Then run:
+**Step 1**: Download images + generate configs (run once)
 
 ```bash
-./scripts/quick-start.sh qemu-x86_64 start --arceos-uefi
+./scripts/setup_qemu.sh <guest>
+# Example: ./scripts/setup_qemu.sh linux
 ```
 
-This flow uses `configs/vms/qemu/x86_64/arceos-uefi-smp1.toml` with `.github/workflows/qemu-x86_64-arceos-uefi.toml`, sets `boot_protocol = "uefi"`, and loads the configured firmware image from `uefi_firmware_path`.
+**Step 2**: Build + launch (repeat as needed)
 
-### ArceOS (RISC-V64)
+`setup_qemu.sh` prints the full `cargo xtask axvisor qemu` command with absolute paths — copy and paste it directly. Example:
 
 ```bash
-./scripts/setup_qemu.sh arceos-riscv64
-
-cargo xtask qemu \
-  --build-config configs/board/qemu-riscv64.toml \
-  --qemu-config .github/workflows/qemu-riscv64.toml \
-  --vmconfigs tmp/vmconfigs/arceos-riscv64-qemu-smp1.generated.toml
+cargo xtask axvisor qemu \
+  --config /home/user/tgoskits/os/axvisor/configs/board/qemu-aarch64.toml \
+  --qemu-config /home/user/tgoskits/os/axvisor/.github/workflows/qemu-aarch64.toml \
+  --vmconfigs /home/user/tgoskits/os/axvisor/tmp/vmconfigs/linux-aarch64-qemu-smp1.generated.toml
 ```
 
-Success indicator: `Hello, world!` appears in the output.
+`setup_qemu.sh` automates three steps:
 
-`qemu-riscv64` currently supports the RISC-V ArceOS guest path. Cross-ISA boot such as `riscv64 AxVisor -> aarch64 ArceOS` is not wired up in the current hypervisor stack.
-
-### AxVisor Shell (LoongArch64, requires QEMU-LVZ)
-
-```bash
-./scripts/quick-start.sh qemu-loongarch64 start
-```
-
-This command launches AxVisor directly and enters the built-in shell instead of booting a guest image.
-
-Success indicator: `Welcome to AxVisor Shell!` appears in the output.
-
-> **Note**: Stock `qemu-system-loongarch64` usually does not expose LoongArch virtualization extensions. Use `QEMU-LVZ`, or set `AXBUILD_QEMU_SYSTEM_LOONGARCH64=/path/to/qemu-system-loongarch64` to a validated virtualization-capable binary.
-
-## 5. What Does setup_qemu.sh Do?
-
-For guest-image flows, the script automates three steps, eliminating manual work:
-
-1. **Download images**: calls `cargo axvisor image pull` to fetch and extract guest images to `/tmp/.axvisor-images/`
-2. **Generate temp configs**: copies VM config templates to `tmp/vmconfigs/*.generated.toml`, then uses `sed` to update `kernel_path` and firmware paths (`bios_path` for legacy NimbOS BIOS mode, `uefi_firmware_path` for UEFI mode) to actual image paths without modifying tracked files in `configs/vms/**/*.toml`
-3. **Prepare rootfs**: copies `rootfs.img` to the project's `tmp/` directory for QEMU to use
-
-You can also perform these steps manually if you prefer not to use the script.
+1. **Download images**: calls `cargo xtask image pull` to fetch and extract guest images and rootfs to the axbuild image cache
+2. **Generate temp configs**: copies VM config templates to `tmp/vmconfigs/*.generated.toml`, then uses `sed` to update `kernel_path` and firmware paths to actual image paths without modifying tracked files in `configs/vms/**/*.toml`
+3. **Prepare rootfs**: copies the rootfs image to the project's `tmp/` directory for QEMU to use
 
 ## Troubleshooting
 
@@ -215,14 +176,7 @@ AxVisor was launched with a LoongArch QEMU binary that does not provide virtuali
 
 ### `Auto syncing from registry ... timed out`
 
-This usually indicates unstable access to GitHub Raw endpoints. `cargo axvisor image pull` now handles registry bootstrap internally: it prefers the default registry, follows the included registry when present, and falls back to the built-in fallback registry (`v0.0.25.toml`) when the default endpoint is unavailable.
-
-If your network is unstable for specific registry URLs, you can override the fallback registry:
-
-```bash
-export AXVISOR_REGISTRY_FALLBACK_URL="https://raw.githubusercontent.com/arceos-hypervisor/axvisor-guest/refs/heads/main/registry/v0.0.25.toml"
-./scripts/setup_qemu.sh arceos
-```
+This usually indicates unstable access to GitHub Raw endpoints. `cargo xtask image pull` handles registry bootstrap internally and falls back to the built-in fallback registry when the default endpoint is unavailable.
 
 ### First build is very slow