> $GITHUB_OUTPUT
-
- - name: Create GitHub Release
- uses: softprops/action-gh-release@v2
- with:
- draft: false
- prerelease: ${{ needs.verify-tag.outputs.is_prerelease == 'true' }}
- body: |
- ## Changes
- ${{ steps.release_notes.outputs.changelog }}
- env:
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
- publish:
- name: Publish to crates.io
- runs-on: ubuntu-latest
- needs: [verify-tag, check]
- if: needs.verify-tag.outputs.should_release == 'true'
-
- steps:
- - name: Checkout code
- uses: actions/checkout@v4
-
- - name: Install Rust toolchain
- uses: dtolnay/rust-toolchain@nightly
-
- - name: Dry run publish
- run: cargo publish --dry-run
-
- - name: Publish to crates.io
- run: cargo publish --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
+ needs: [check, test]
+ uses: arceos-hypervisor/axci/.github/workflows/release.yml@main
+ with:
+ verify_branch: true
+ verify_version: true
+ secrets:
+ CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index dc3b293..6a58ef8 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,3 +1,6 @@
+# Integration Test Workflow
+# References shared workflow from axci
+
name: Test
on:
@@ -7,44 +10,8 @@ on:
tags-ignore:
- '**'
pull_request:
- workflow_call:
+ workflow_dispatch:
jobs:
- load-config:
- name: Load CI Configuration
- runs-on: ubuntu-latest
- outputs:
- targets: ${{ steps.config.outputs.targets }}
- steps:
- - name: Checkout code
- uses: actions/checkout@v4
-
- - name: Load configuration
- id: config
- run: |
- TARGETS=$(jq -c '.targets' .github/config.json)
- echo "targets=$TARGETS" >> $GITHUB_OUTPUT
-
test:
- name: Test
- runs-on: ubuntu-latest
- needs: load-config
- strategy:
- fail-fast: false
- matrix:
- target: ${{ fromJson(needs.load-config.outputs.targets) }}
-
- steps:
- - name: Checkout code
- uses: actions/checkout@v4
-
- - name: Install Rust toolchain
- uses: dtolnay/rust-toolchain@nightly
-
- # - name: Run tests
- # run: cargo test --target ${{ matrix.target }} --all-features -- --nocapture
-
- # - name: Run doc tests
- # run: cargo test --target ${{ matrix.target }} --doc
- - name: Run tests
- run: echo "Tests are skipped!"
+ uses: arceos-hypervisor/axci/.github/workflows/test.yml@main
diff --git a/.gitignore b/.gitignore
index 55c0d45..39ee779 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,11 @@ rusty-tags.vi
# We ignore Cargo.lock because `axvcpu` is just a library
Cargo.lock
+
+# Test results (generated by shared test framework)
+/test-results/
+/test_repos/
+*.log
+
+# Downloaded test framework
+/scripts/.axci/
diff --git a/README.md b/README.md
index 18b69b2..c359be8 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,122 @@
-# AxVM
+axvm
-Virtual Machine **resource management** crate for [`ArceOS`](https://github.com/arceos-org/arceos)'s hypervisor variant.
+Virtual Machine Resource Management for ArceOS Hypervisors
-* resources:
- * vcpu: [axvcpu](https://github.com/arceos-hypervisor/axvcpu) list
- * memory: [axaddrspace](https://github.com/arceos-hypervisor/axaddrspace) for guest memory management
- * device: [axdevice](https://github.com/arceos-hypervisor/axdevice) list
+
-## License
+[](https://crates.io/crates/axvm)
+[](https://docs.rs/axvm)
+[](https://www.rust-lang.org/)
+[](https://github.com/arceos-hypervisor/axvm/blob/main/LICENSE)
-Axvm is licensed under the Apache License, Version 2.0. See the [LICENSE](./LICENSE) file for details.
+
+
+English | [中文](README_CN.md)
+
+# Introduction
+
+`axvm` is a `#![no_std]` virtual machine resource management crate for ArceOS hypervisors. It coordinates guest address space setup, virtual CPU initialization, emulated device management, and VM lifecycle control on top of `axaddrspace`, `axvcpu`, `axdevice`, and `axvmconfig`.
+
+This library exports five core public types:
+
+- **`AxVM`** - Main virtual machine object
+- **`AxVMRef`** - Shared reference type for an `AxVM`
+- **`AxVCpuRef`** - Shared reference type for a VM vCPU
+- **`VMMemoryRegion`** - Describes a mapped guest memory region
+- **`VMStatus`** - Represents VM lifecycle states such as loading, running, and stopped
+
+It also provides:
+
+- **`config`** - VM configuration types such as `AxVMConfig` and `AxVMCrateConfig`
+- **`AxVMPerCpu`** - Architecture-independent per-CPU virtualization helper type
+- **`has_hardware_support()`** - Checks whether the current hardware supports virtualization
+
+## Quick Start
+
+### Requirements
+
+- Rust nightly toolchain
+- Rust components: rust-src, clippy, rustfmt
+
+```bash
+# Install rustup (if not installed)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Install nightly toolchain and components
+rustup install nightly
+rustup component add rust-src clippy rustfmt --toolchain nightly
+```
+
+### Run Check and Test
+
+```bash
+# 1. Enter the repository
+cd axvm
+
+# 2. Code check
+./scripts/check.sh
+
+# 3. Run tests
+./scripts/test.sh
+```
+
+## Integration
+
+### Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+axvm = "0.3.0"
+```
+
+### Example
+
+```rust
+use axvm::{
+ config::{AxVMConfig, AxVMCrateConfig},
+ AxVM, VMStatus,
+};
+
+fn main() {
+ let crate_config = AxVMCrateConfig::default();
+ let config = AxVMConfig::from(crate_config);
+
+ let vm = AxVM::new(config).unwrap();
+ assert_eq!(vm.vm_status(), VMStatus::Loading);
+
+ // Initialize guest resources such as address space, vCPUs, and devices.
+ vm.init().unwrap();
+
+ // Boot the VM after initialization.
+ vm.boot().unwrap();
+ assert_eq!(vm.vm_status(), VMStatus::Running);
+
+ // Query resources managed by the VM object.
+ let _vcpu_num = vm.vcpu_num();
+ let _ept_root = vm.ept_root();
+ let _devices = vm.get_devices();
+}
+```
+
+### Documentation
+
+Generate and view API documentation:
+
+```bash
+cargo doc --no-deps --open
+```
+
+Online documentation: [docs.rs/axvm](https://docs.rs/axvm)
+
+# Contributing
+
+1. Fork the repository and create a branch
+2. Run local check: `./scripts/check.sh`
+3. Run local tests: `./scripts/test.sh`
+4. Submit PR and pass CI checks
+
+# License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
diff --git a/README_CN.md b/README_CN.md
new file mode 100644
index 0000000..007cb40
--- /dev/null
+++ b/README_CN.md
@@ -0,0 +1,122 @@
+axvm
+
+面向 ArceOS Hypervisor 的虚拟机资源管理
+
+
+
+[](https://crates.io/crates/axvm)
+[](https://docs.rs/axvm)
+[](https://www.rust-lang.org/)
+[](https://github.com/arceos-hypervisor/axvm/blob/main/LICENSE)
+
+
+
+[English](README.md) | 中文
+
+# Introduction
+
+`axvm` 是一个面向 ArceOS hypervisor 的 `#![no_std]` 虚拟机资源管理 crate。它建立在 `axaddrspace`、`axvcpu`、`axdevice` 和 `axvmconfig` 之上，用于统一协调 guest 地址空间构建、虚拟 CPU 初始化、模拟设备管理以及虚拟机生命周期控制。
+
+该库导出五个核心公开类型：
+
+- **`AxVM`** - 主要的虚拟机对象
+- **`AxVMRef`** - `AxVM` 的共享引用类型
+- **`AxVCpuRef`** - VM 中 vCPU 的共享引用类型
+- **`VMMemoryRegion`** - 描述 guest 内存映射区域
+- **`VMStatus`** - 表示 loading、running、stopped 等虚拟机生命周期状态
+
+此外还提供：
+
+- **`config`** - 包含 `AxVMConfig`、`AxVMCrateConfig` 等 VM 配置类型
+- **`AxVMPerCpu`** - 与架构无关的每 CPU 虚拟化辅助类型
+- **`has_hardware_support()`** - 检查当前硬件是否支持虚拟化
+
+## Quick Start
+
+### Requirements
+
+- Rust nightly 工具链
+- Rust 组件：rust-src、clippy、rustfmt
+
+```bash
+# 安装 rustup（如果尚未安装）
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# 安装 nightly 工具链与所需组件
+rustup install nightly
+rustup component add rust-src clippy rustfmt --toolchain nightly
+```
+
+### Run Check and Test
+
+```bash
+# 1. 进入仓库目录
+cd axvm
+
+# 2. 代码检查
+./scripts/check.sh
+
+# 3. 运行测试
+./scripts/test.sh
+```
+
+## Integration
+
+### Installation
+
+将以下依赖加入 `Cargo.toml`：
+
+```toml
+[dependencies]
+axvm = "0.3.0"
+```
+
+### Example
+
+```rust
+use axvm::{
+ config::{AxVMConfig, AxVMCrateConfig},
+ AxVM, VMStatus,
+};
+
+fn main() {
+ let crate_config = AxVMCrateConfig::default();
+ let config = AxVMConfig::from(crate_config);
+
+ let vm = AxVM::new(config).unwrap();
+ assert_eq!(vm.vm_status(), VMStatus::Loading);
+
+ // 初始化 guest 资源，例如地址空间、vCPU 和设备。
+ vm.init().unwrap();
+
+ // 初始化完成后启动虚拟机。
+ vm.boot().unwrap();
+ assert_eq!(vm.vm_status(), VMStatus::Running);
+
+ // 查询由 VM 对象管理的资源。
+ let _vcpu_num = vm.vcpu_num();
+ let _ept_root = vm.ept_root();
+ let _devices = vm.get_devices();
+}
+```
+
+### Documentation
+
+生成并查看 API 文档：
+
+```bash
+cargo doc --no-deps --open
+```
+
+在线文档： [docs.rs/axvm](https://docs.rs/axvm)
+
+# Contributing
+
+1. Fork 仓库并创建分支
+2. 本地运行检查：`./scripts/check.sh`
+3. 本地运行测试：`./scripts/test.sh`
+4. 提交 PR 并通过 CI 检查
+
+# License
+
+本项目基于 Apache License 2.0 许可证发布。详见 [LICENSE](LICENSE)。
diff --git a/scripts/check.sh b/scripts/check.sh
new file mode 100755
index 0000000..6075bc5
--- /dev/null
+++ b/scripts/check.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+#
+# axvm 代码检查脚本
+# 下载并调用 axci 仓库中的检查脚本
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMPONENT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+COMPONENT_NAME="$(basename "$COMPONENT_DIR")"
+AXCI_DIR="${SCRIPT_DIR}/.axci"
+AXCI_REPO="https://github.com/arceos-hypervisor/axci.git"
+
+# 下载或更新 axci 仓库
+download_axci() {
+ if [ -d "$AXCI_DIR" ]; then
+ echo "Updating axci repository..."
+ cd "$AXCI_DIR" && git pull --quiet
+ else
+ echo "Downloading axci repository..."
+ git clone --quiet "$AXCI_REPO" "$AXCI_DIR"
+ fi
+}
+
+# 主函数
+main() {
+ download_axci
+
+ # 在组件目录中运行检查
+ cd "$COMPONENT_DIR"
+ exec bash "$AXCI_DIR/check.sh" --component-dir "$COMPONENT_DIR" "$@"
+}
+
+main "$@"
diff --git a/scripts/test.sh b/scripts/test.sh
new file mode 100755
index 0000000..31aa756
--- /dev/null
+++ b/scripts/test.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+#
+# axvm 测试脚本
+# 下载并调用 axci 仓库中的测试框架
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMPONENT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+AXCI_DIR="${SCRIPT_DIR}/.axci"
+AXCI_REPO="https://github.com/arceos-hypervisor/axci.git"
+
+# 下载或更新 axci 仓库
+download_axci() {
+ if [ -d "$AXCI_DIR" ]; then
+ echo "Updating axci repository..."
+ cd "$AXCI_DIR" && git pull --quiet
+ else
+ echo "Downloading axci repository..."
+ git clone --quiet "$AXCI_REPO" "$AXCI_DIR"
+ fi
+}
+
+# 主函数
+main() {
+ download_axci
+
+ # 在组件目录中运行测试，自动指定当前组件
+ cd "$COMPONENT_DIR"
+ exec bash "$AXCI_DIR/tests.sh" --component-dir "$COMPONENT_DIR" "$@"
+}
+
+main "$@"