From a2e0da5f25c00edf5493fec0245338df041b03fc Mon Sep 17 00:00:00 2001 From: YanLien Date: Thu, 19 Mar 2026 17:32:51 +0800 Subject: [PATCH 1/5] refactor(ci): migrate to shared workflows and update docs --- .github/config.json | 1 + .github/workflows/check.yml | 67 ++------------ .github/workflows/deploy.yml | 124 ++------------------------ .github/workflows/push.yml | 145 ++----------------------------- .github/workflows/release.yml | 159 +++------------------------------- .github/workflows/test.yml | 43 ++------- .gitignore | 8 ++ README.md | 126 +++++++++++++++++++++++++-- README_CN.md | 122 ++++++++++++++++++++++++++ scripts/check.sh | 35 ++++++++ scripts/test.sh | 34 ++++++++ 11 files changed, 358 insertions(+), 506 deletions(-) create mode 100644 README_CN.md create mode 100755 scripts/check.sh create mode 100755 scripts/test.sh diff --git a/.github/config.json b/.github/config.json index f347e10..6a33b4a 100644 --- a/.github/config.json +++ b/.github/config.json @@ -5,6 +5,7 @@ "x86_64-unknown-none", "riscv64gc-unknown-none-elf" ], + "unit_test_targets": [], "rust_components": [ "rust-src", "clippy", diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 330fa15..018bbbe 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -1,66 +1,15 @@ -name: Quality Checks +# Quality Check Workflow +# References shared workflow from axci + +name: Check on: push: - branches: - - '**' - tags-ignore: - - '**' + branches: ['**'] + 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 }} - rust_components: ${{ steps.config.outputs.rust_components }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Load configuration - id: config - run: | - TARGETS=$(jq -c '.targets' .github/config.json) - COMPONENTS=$(jq -r '.rust_components | join(", ")' .github/config.json) - - echo "targets=$TARGETS" >> $GITHUB_OUTPUT - echo "rust_components=$COMPONENTS" >> $GITHUB_OUTPUT - check: - name: Check - 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 - with: - components: ${{ needs.load-config.outputs.rust_components }} - targets: ${{ matrix.target }} - - - name: Check rust version - run: rustc --version --verbose - - - name: Check code format - run: cargo fmt --all -- --check - - - name: Build - run: cargo build --target ${{ matrix.target }} --all-features - - - name: Run clippy - run: cargo clippy --target ${{ matrix.target }} --all-features -- -D warnings - - - name: Build documentation - env: - RUSTDOCFLAGS: -D rustdoc::broken_intra_doc_links -D missing-docs - run: cargo doc --no-deps --target ${{ matrix.target }} --all-features + uses: arceos-hypervisor/axci/.github/workflows/check.yml@main diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index fda9a32..37b00c0 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,3 +1,6 @@ +# Deploy Workflow +# References shared workflow from axci + name: Deploy on: @@ -5,122 +8,9 @@ on: tags: - 'v[0-9]+.[0-9]+.[0-9]+' -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: 'pages' - cancel-in-progress: false - -env: - CARGO_TERM_COLOR: always - RUST_BACKTRACE: 1 - jobs: - verify-tag: - name: Verify Tag - runs-on: ubuntu-latest - outputs: - should_deploy: ${{ steps.check.outputs.should_deploy }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Check if tag is on main or master branch - id: check - run: | - git fetch origin main master || true - BRANCHES=$(git branch -r --contains ${{ github.ref }}) - - if echo "$BRANCHES" | grep -qE 'origin/(main|master)'; then - echo "✓ Tag is on main or master branch" - echo "should_deploy=true" >> $GITHUB_OUTPUT - else - echo "✗ Tag is not on main or master branch, skipping deployment" - echo "Tag is on: $BRANCHES" - echo "should_deploy=false" >> $GITHUB_OUTPUT - fi - - - name: Verify version consistency - if: steps.check.outputs.should_deploy == 'true' - run: | - # Extract version from git tag (remove 'v' prefix) - TAG_VERSION="${{ github.ref_name }}" - TAG_VERSION="${TAG_VERSION#v}" - # Extract version from Cargo.toml - CARGO_VERSION=$(grep -m1 '^version' Cargo.toml | sed 's/.*"\(.*\)"/\1/') - echo "Git tag version: $TAG_VERSION" - echo "Cargo.toml version: $CARGO_VERSION" - if [ "$TAG_VERSION" != "$CARGO_VERSION" ]; then - echo "ERROR: Version mismatch! Tag version ($TAG_VERSION) != Cargo.toml version ($CARGO_VERSION)" - exit 1 - fi - echo "✓ Version check passed!" - - check: - uses: ./.github/workflows/check.yml - needs: verify-tag - if: needs.verify-tag.outputs.should_deploy == 'true' - - test: - uses: ./.github/workflows/test.yml - needs: verify-tag - if: needs.verify-tag.outputs.should_deploy == 'true' - - build: - name: Build documentation - runs-on: ubuntu-latest - needs: [verify-tag, check, test] - if: needs.verify-tag.outputs.should_deploy == 'true' - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Install Rust toolchain - uses: dtolnay/rust-toolchain@nightly - - - name: Build docs - env: - RUSTDOCFLAGS: -D rustdoc::broken_intra_doc_links -D missing-docs - run: | - # Build documentation - cargo doc --no-deps --all-features - - # Auto-detect documentation directory - # Check if doc exists in target/doc or target/*/doc - if [ -d "target/doc" ]; then - DOC_DIR="target/doc" - else - # Find doc directory under target/*/doc pattern - DOC_DIR=$(find target -type d -name doc -path "target/*/doc" | head -n 1) - if [ -z "$DOC_DIR" ]; then - echo "Error: Could not find documentation directory" - exit 1 - fi - fi - - echo "Documentation found in: $DOC_DIR" - printf '' $(cargo tree | head -1 | cut -d' ' -f1) > "${DOC_DIR}/index.html" - echo "DOC_DIR=${DOC_DIR}" >> $GITHUB_ENV - - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: ${{ env.DOC_DIR }} - deploy: - name: Deploy to GitHub Pages - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: [verify-tag, build] - if: needs.verify-tag.outputs.should_deploy == 'true' - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 + uses: arceos-hypervisor/axci/.github/workflows/deploy.yml@main + with: + verify_branch: true + verify_version: true diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index a18de4a..3ff391a 100644 --- a/.github/workflows/push.yml +++ b/.github/workflows/push.yml @@ -1,147 +1,16 @@ -# ═══════════════════════════════════════════════════════════════════════════════ -# 组件仓库 GitHub Actions 配置模板 -# ═══════════════════════════════════════════════════════════════════════════════ -# -# 此文件用于子仓库，当子仓库有更新时通知主仓库进行 subtree pull 同步。 -# -# 【使用步骤】 -# ───────────────────────────────────────────────────────────────────────────── -# 1. 将此文件复制到子仓库的 .github/workflows/ 目录： -# cp scripts/push.yml <子仓库>/.github/workflows/push.yml -# -# 2. 在子仓库中配置 Secret： -# GitHub 仓库 → Settings → Secrets → Actions → New repository secret -# 名称: PARENT_REPO_TOKEN -# 值: 具有主仓库 repo 权限的 Personal Access Token -# -# 3. 修改下方 env 块中的一个变量（标注了「需要修改」的行）： -# PARENT_REPO - 主仓库路径，例如 rcore-os/tgoskits -# （subtree 目录由主仓库自动从 git 历史中推断，无需手动指定） -# -# 【Token 权限要求】 -# ───────────────────────────────────────────────────────────────────────────── -# PARENT_REPO_TOKEN 需要 Classic Personal Access Token，权限包括： -# - repo (Full control of private repositories) -# 或 -# - Fine-grained token: Contents (Read and Write) -# -# 【触发条件】 -# ───────────────────────────────────────────────────────────────────────────── -# - 自动触发：推送到 dev 或 main 分支时 -# - 手动触发：Actions → Notify Parent Repository → Run workflow -# -# 【工作流程】 -# ───────────────────────────────────────────────────────────────────────────── -# 子仓库 push → 触发此工作流 → 调用主仓库 API → 主仓库 subtree pull -# -# 【注意事项】 -# ───────────────────────────────────────────────────────────────────────────── -# - 主仓库需要配置接收 repository_dispatch 事件的同步工作流 -# - 如果不需要子仓库到主仓库的同步，可以不使用此文件 -# -# ═══════════════════════════════════════════════════════════════════════════════ - name: Notify Parent Repository -# 当有新的推送时触发 on: push: branches: - main - - master + - zcs workflow_dispatch: jobs: - notify: - runs-on: ubuntu-latest - steps: - - name: Get repository info - id: repo - env: - GH_REPO_NAME: ${{ github.event.repository.name }} - GH_REF_NAME: ${{ github.ref_name }} - GH_SERVER_URL: ${{ github.server_url }} - GH_REPOSITORY: ${{ github.repository }} - run: | - # 直接使用 GitHub Actions 内置变量，通过 env 传入避免 shell 注入 - COMPONENT="$GH_REPO_NAME" - BRANCH="$GH_REF_NAME" - # 构造标准 HTTPS URL，供主仓库按 URL 精确匹配 repos.list - REPO_URL="${GH_SERVER_URL}/${GH_REPOSITORY}" - - echo "component=${COMPONENT}" >> $GITHUB_OUTPUT - echo "branch=${BRANCH}" >> $GITHUB_OUTPUT - echo "repo_url=${REPO_URL}" >> $GITHUB_OUTPUT - - echo "Component: ${COMPONENT}" - echo "Branch: ${BRANCH}" - echo "Repo URL: ${REPO_URL}" - - - name: Notify parent repository - env: - # ── 需要修改 ────────────────────────────────────────────────────────── - PARENT_REPO: "rcore-os/tgoskits" # 主仓库路径 - # ── 无需修改 ────────────────────────────────────────────────────────── - DISPATCH_TOKEN: ${{ secrets.PARENT_REPO_TOKEN }} - # 将用户可控内容通过 env 传入，避免直接插值到 shell 脚本 - COMMIT_MESSAGE: ${{ github.event.head_commit.message }} - GIT_ACTOR: ${{ github.actor }} - GIT_SHA: ${{ github.sha }} - STEP_COMPONENT: ${{ steps.repo.outputs.component }} - STEP_BRANCH: ${{ steps.repo.outputs.branch }} - STEP_REPO_URL: ${{ steps.repo.outputs.repo_url }} - run: | - COMPONENT="$STEP_COMPONENT" - BRANCH="$STEP_BRANCH" - REPO_URL="$STEP_REPO_URL" - - echo "Notifying parent repository about update in ${COMPONENT}:${BRANCH}" - - # 使用 jq 安全构建 JSON，避免 commit message 中任何特殊字符导致注入 - PAYLOAD=$(jq -n \ - --arg component "$COMPONENT" \ - --arg branch "$BRANCH" \ - --arg repo_url "$REPO_URL" \ - --arg commit "$GIT_SHA" \ - --arg message "$COMMIT_MESSAGE" \ - --arg author "$GIT_ACTOR" \ - '{ - event_type: "subtree-update", - client_payload: { - component: $component, - branch: $branch, - repo_url: $repo_url, - commit: $commit, - message: $message, - author: $author - } - }') - - curl --fail --show-error -X POST \ - -H "Accept: application/vnd.github.v3+json" \ - -H "Authorization: token ${DISPATCH_TOKEN}" \ - https://api.github.com/repos/${PARENT_REPO}/dispatches \ - -d "$PAYLOAD" - - echo "Notification sent successfully" - - - name: Create summary - env: - STEP_COMPONENT: ${{ steps.repo.outputs.component }} - STEP_BRANCH: ${{ steps.repo.outputs.branch }} - STEP_REPO_URL: ${{ steps.repo.outputs.repo_url }} - GIT_SHA: ${{ github.sha }} - GIT_ACTOR: ${{ github.actor }} - run: | - COMPONENT="$STEP_COMPONENT" - BRANCH="$STEP_BRANCH" - REPO_URL="$STEP_REPO_URL" - - echo "## Notification Summary" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "- **Component**: ${COMPONENT}" >> $GITHUB_STEP_SUMMARY - echo "- **Branch**: ${BRANCH}" >> $GITHUB_STEP_SUMMARY - echo "- **Repo URL**: ${REPO_URL}" >> $GITHUB_STEP_SUMMARY - echo "- **Commit**: \`${GIT_SHA}\`" >> $GITHUB_STEP_SUMMARY - echo "- **Author**: ${GIT_ACTOR}" >> $GITHUB_STEP_SUMMARY - echo "- **Status**: ✅ Notification sent" >> $GITHUB_STEP_SUMMARY + notify-parent: + name: Notify Parent Repository + # 调用 axci 仓库的可复用工作流 + uses: arceos-hypervisor/axci/.github/workflows/push.yml@main + secrets: + PARENT_REPO_TOKEN: ${{ secrets.PARENT_REPO_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2e857b4..20f1863 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,3 +1,7 @@ +# Release Workflow +# References shared workflow from axci +# check + test must pass before release + name: Release on: @@ -6,155 +10,18 @@ on: - 'v[0-9]+.[0-9]+.[0-9]+' - 'v[0-9]+.[0-9]+.[0-9]+-pre.[0-9]+' -permissions: - contents: write - jobs: - verify-tag: - name: Verify Tag - runs-on: ubuntu-latest - outputs: - should_release: ${{ steps.check.outputs.should_release }} - is_prerelease: ${{ steps.check.outputs.is_prerelease }} - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Check tag type and branch - id: check - run: | - git fetch origin main master dev || true - - TAG="${{ github.ref_name }}" - BRANCHES=$(git branch -r --contains ${{ github.ref }}) - - echo "Tag: $TAG" - echo "Branches containing this tag: $BRANCHES" - - # Check if it's a prerelease tag - if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-pre\.[0-9]+$ ]]; then - echo "📦 Detected prerelease tag" - echo "is_prerelease=true" >> $GITHUB_OUTPUT - - if echo "$BRANCHES" | grep -q 'origin/dev'; then - echo "✓ Prerelease tag is on dev branch" - echo "should_release=true" >> $GITHUB_OUTPUT - else - echo "✗ Prerelease tag must be on dev branch, skipping release" - echo "should_release=false" >> $GITHUB_OUTPUT - fi - elif [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then - echo "📦 Detected stable release tag" - echo "is_prerelease=false" >> $GITHUB_OUTPUT - - if echo "$BRANCHES" | grep -qE 'origin/(main|master)'; then - echo "✓ Stable release tag is on main or master branch" - echo "should_release=true" >> $GITHUB_OUTPUT - else - echo "✗ Stable release tag must be on main or master branch, skipping release" - echo "should_release=false" >> $GITHUB_OUTPUT - fi - else - echo "✗ Unknown tag format, skipping release" - echo "is_prerelease=false" >> $GITHUB_OUTPUT - echo "should_release=false" >> $GITHUB_OUTPUT - fi - - - name: Verify version consistency - if: steps.check.outputs.should_release == 'true' - run: | - # Extract version from git tag (remove 'v' prefix) - TAG_VERSION="${{ github.ref_name }}" - TAG_VERSION="${TAG_VERSION#v}" - # Extract version from Cargo.toml - CARGO_VERSION=$(grep -m1 '^version' Cargo.toml | sed 's/.*"\(.*\)"/\1/') - echo "Git tag version: $TAG_VERSION" - echo "Cargo.toml version: $CARGO_VERSION" - if [ "$TAG_VERSION" != "$CARGO_VERSION" ]; then - echo "ERROR: Version mismatch! Tag version ($TAG_VERSION) != Cargo.toml version ($CARGO_VERSION)" - exit 1 - fi - echo "✓ Version check passed!" - check: - uses: ./.github/workflows/check.yml - needs: verify-tag - if: needs.verify-tag.outputs.should_release == 'true' + uses: arceos-hypervisor/axci/.github/workflows/check.yml@main test: - uses: ./.github/workflows/test.yml - needs: [verify-tag, check] - if: needs.verify-tag.outputs.should_release == 'true' + uses: arceos-hypervisor/axci/.github/workflows/test.yml@main release: - name: Create GitHub Release - runs-on: ubuntu-latest - needs: [verify-tag, check] - if: needs.verify-tag.outputs.should_release == 'true' - - steps: - - name: Checkout code - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Generate release notes - id: release_notes - run: | - CURRENT_TAG="${{ github.ref_name }}" - - # Get previous tag - PREVIOUS_TAG=$(git tag --sort=-version:refname | grep -A1 "^${CURRENT_TAG}$" | tail -n1) - - if [ -z "$PREVIOUS_TAG" ] || [ "$PREVIOUS_TAG" == "$CURRENT_TAG" ]; then - echo "No previous tag found, this is the first release" - CHANGELOG="Initial release" - else - echo "Generating changelog from $PREVIOUS_TAG to $CURRENT_TAG" - - # Generate changelog with commit messages - CHANGELOG=$(git log --pretty=format:"- %s (%h)" "${PREVIOUS_TAG}..${CURRENT_TAG}") - - if [ -z "$CHANGELOG" ]; then - CHANGELOG="No changes" - fi - fi - - # Write changelog to output file (multi-line) - { - echo "changelog<> $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 +[![Crates.io](https://img.shields.io/crates/v/axvm.svg)](https://crates.io/crates/axvm) +[![Docs.rs](https://docs.rs/axvm/badge.svg)](https://docs.rs/axvm) +[![Rust](https://img.shields.io/badge/edition-2024-orange.svg)](https://www.rust-lang.org/) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](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 的虚拟机资源管理

+ +
+ +[![Crates.io](https://img.shields.io/crates/v/axvm.svg)](https://crates.io/crates/axvm) +[![Docs.rs](https://docs.rs/axvm/badge.svg)](https://docs.rs/axvm) +[![Rust](https://img.shields.io/badge/edition-2024-orange.svg)](https://www.rust-lang.org/) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](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..75cb63b --- /dev/null +++ b/scripts/check.sh @@ -0,0 +1,35 @@ +#!/bin/bash +# +# axvisor_api 代码检查脚本 +# 下载并调用 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..e80a4de --- /dev/null +++ b/scripts/test.sh @@ -0,0 +1,34 @@ +#!/bin/bash +# +# axvisor_api 测试脚本 +# 下载并调用 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 "$@" From 840023e59482c4d42507b670e6de46958250b57f Mon Sep 17 00:00:00 2001 From: YanLien Date: Thu, 19 Mar 2026 17:49:42 +0800 Subject: [PATCH 2/5] chore(scripts): update script comments from axvisor_api to axvm --- scripts/check.sh | 2 +- scripts/test.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/check.sh b/scripts/check.sh index 75cb63b..6075bc5 100755 --- a/scripts/check.sh +++ b/scripts/check.sh @@ -1,6 +1,6 @@ #!/bin/bash # -# axvisor_api 代码检查脚本 +# axvm 代码检查脚本 # 下载并调用 axci 仓库中的检查脚本 # diff --git a/scripts/test.sh b/scripts/test.sh index e80a4de..31aa756 100755 --- a/scripts/test.sh +++ b/scripts/test.sh @@ -1,6 +1,6 @@ #!/bin/bash # -# axvisor_api 测试脚本 +# axvm 测试脚本 # 下载并调用 axci 仓库中的测试框架 # From 20f2c753650f131c4154fe14480d7830205562a4 Mon Sep 17 00:00:00 2001 From: YanLien Date: Fri, 20 Mar 2026 14:30:15 +0800 Subject: [PATCH 3/5] ci: update reusable workflows to use ndev branch --- .github/workflows/check.yml | 2 +- .github/workflows/deploy.yml | 2 +- .github/workflows/push.yml | 2 +- .github/workflows/release.yml | 6 +++--- .github/workflows/test.yml | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 018bbbe..de8fa04 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -12,4 +12,4 @@ on: jobs: check: - uses: arceos-hypervisor/axci/.github/workflows/check.yml@main + uses: arceos-hypervisor/axci/.github/workflows/check.yml@ndev diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 37b00c0..3335adf 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -10,7 +10,7 @@ on: jobs: deploy: - uses: arceos-hypervisor/axci/.github/workflows/deploy.yml@main + uses: arceos-hypervisor/axci/.github/workflows/deploy.yml@ndev with: verify_branch: true verify_version: true diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 3ff391a..4cef2b4 100644 --- a/.github/workflows/push.yml +++ b/.github/workflows/push.yml @@ -11,6 +11,6 @@ jobs: notify-parent: name: Notify Parent Repository # 调用 axci 仓库的可复用工作流 - uses: arceos-hypervisor/axci/.github/workflows/push.yml@main + uses: arceos-hypervisor/axci/.github/workflows/push.yml@ndev secrets: PARENT_REPO_TOKEN: ${{ secrets.PARENT_REPO_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 20f1863..23ab16e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,14 +12,14 @@ on: jobs: check: - uses: arceos-hypervisor/axci/.github/workflows/check.yml@main + uses: arceos-hypervisor/axci/.github/workflows/check.yml@ndev test: - uses: arceos-hypervisor/axci/.github/workflows/test.yml@main + uses: arceos-hypervisor/axci/.github/workflows/test.yml@ndev release: needs: [check, test] - uses: arceos-hypervisor/axci/.github/workflows/release.yml@main + uses: arceos-hypervisor/axci/.github/workflows/release.yml@ndev with: verify_branch: true verify_version: true diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 6a58ef8..2363cdf 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -14,4 +14,4 @@ on: jobs: test: - uses: arceos-hypervisor/axci/.github/workflows/test.yml@main + uses: arceos-hypervisor/axci/.github/workflows/test.yml@ndev From 517f8eb8957dccf01f531e080af8352cb7689029 Mon Sep 17 00:00:00 2001 From: YanLien Date: Fri, 20 Mar 2026 14:50:14 +0800 Subject: [PATCH 4/5] ci: update reusable workflows to use main branch --- .github/workflows/deploy.yml | 2 +- .github/workflows/push.yml | 2 +- .github/workflows/release.yml | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 3335adf..37b00c0 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -10,7 +10,7 @@ on: jobs: deploy: - uses: arceos-hypervisor/axci/.github/workflows/deploy.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/deploy.yml@main with: verify_branch: true verify_version: true diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 4cef2b4..3ff391a 100644 --- a/.github/workflows/push.yml +++ b/.github/workflows/push.yml @@ -11,6 +11,6 @@ jobs: notify-parent: name: Notify Parent Repository # 调用 axci 仓库的可复用工作流 - uses: arceos-hypervisor/axci/.github/workflows/push.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/push.yml@main secrets: PARENT_REPO_TOKEN: ${{ secrets.PARENT_REPO_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 23ab16e..20f1863 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,14 +12,14 @@ on: jobs: check: - uses: arceos-hypervisor/axci/.github/workflows/check.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/check.yml@main test: - uses: arceos-hypervisor/axci/.github/workflows/test.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/test.yml@main release: needs: [check, test] - uses: arceos-hypervisor/axci/.github/workflows/release.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/release.yml@main with: verify_branch: true verify_version: true From 81151132889045f435c58d16c72a053df96bd0cc Mon Sep 17 00:00:00 2001 From: YanLien Date: Fri, 20 Mar 2026 15:03:53 +0800 Subject: [PATCH 5/5] ci: update reusable workflows to use main branch --- .github/config.json | 1 - .github/workflows/check.yml | 2 +- .github/workflows/test.yml | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/config.json b/.github/config.json index 6a33b4a..f347e10 100644 --- a/.github/config.json +++ b/.github/config.json @@ -5,7 +5,6 @@ "x86_64-unknown-none", "riscv64gc-unknown-none-elf" ], - "unit_test_targets": [], "rust_components": [ "rust-src", "clippy", diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index de8fa04..018bbbe 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -12,4 +12,4 @@ on: jobs: check: - uses: arceos-hypervisor/axci/.github/workflows/check.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/check.yml@main diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2363cdf..6a58ef8 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -14,4 +14,4 @@ on: jobs: test: - uses: arceos-hypervisor/axci/.github/workflows/test.yml@ndev + uses: arceos-hypervisor/axci/.github/workflows/test.yml@main