axcrates

---

一、简介

ArceOS 组件统一管理仓库，通过 Git Submodule 关联所有组件，提供统一的版本管理和协同开发脚本。

📋 详细文档请参考 组件开发方案 和 组件开发及管理规范。

1.1 目录结构

axcrates/
├── components/                     # 独立组件（共 60 个 submodules）
│   ├── arceos/                     # ArceOS 主仓库（含 16 个组件）
│   ├── axmm_crates/                # 内存管理（memory_addr, memory_set）
│   ├── axplat_crates/              # 平台抽象层（axplat 及多个平台实现）
│   ├── axdriver_crates/            # 驱动框架（base, pci, block, virtio）
│   ├── page_table_multiarch/       # 多架构页表
│   ├── percpu/                     # Per-CPU 变量
│   ├── ctor_bare/                  # 裸机构造器
│   ├── somehal/                    # 硬件抽象层（含 8 个子组件）
│   ├── axvcpu/                     # VCPU 抽象层 [arceos-hypervisor]
│   ├── axvm/                       # VM 资源管理 [arceos-hypervisor]
│   ├── axdevice/                   # 设备抽象层 [arceos-hypervisor]
│   ├── axvisor_api/                # Hypervisor API [arceos-hypervisor]
│   ├── arm_vcpu/                   # ARM VCPU 实现 [arceos-hypervisor]
│   ├── riscv_vcpu/                 # RISC-V VCPU 实现 [arceos-hypervisor]
│   ├── x86_vcpu/                   # x86 VCPU 实现 [arceos-hypervisor]
│   ├── axallocator/                # 内存分配器接口 [arceos-org]
│   ├── axconfig-gen/               # 配置生成工具 [arceos-org]
│   ├── axcpu/                      # CPU 抽象层 [arceos-org]
│   ├── axsched/                    # 调度器 [arceos-org]
│   ├── bitmap-allocator/           # 位图分配器 [rcore-os]
│   ├── virtio-drivers/             # VirtIO 驱动 [rcore-os]
│   ├── any-uart/                   # 通用 UART 驱动 [rcore-os]
│   ├── axbacktrace/                # 调用栈回溯 [Starry-OS]
│   ├── starry-process/             # 进程管理 [Starry-OS]
│   ├── starry-vm/                  # 虚拟内存管理 [Starry-OS]
│   ├── starry-smoltcp/             # 网络协议栈 [Starry-OS]
│   └── ...                         # 更多组件详见第二章组件表格
├── os/                             # 顶层操作系统
│   ├── axvisor/                    # ArceOS Hypervisor [arceos-hypervisor]
│   └── StarryOS/                   # Starry 操作系统 [Starry-OS]
├── scripts/                        # 维护脚本
│   ├── checkout.sh                 # 批量切换分支
│   ├── check.sh                    # 批量代码检查
│   ├── commit.sh                   # 批量提交
│   ├── push.sh                     # 批量推送
│   ├── sync.sh                     # 同步子模块
│   ├── version.sh                  # 批量更新版本号
│   ├── tag.sh                      # 批量创建标签
│   ├── publish.sh                  # 发布到 crates.io
│   ├── pack.sh                     # 打包子模块
│   └── unpack.sh                   # 解包子模块
├── docs/                           # 文档
│   ├── axvisor-dependency.md       # Axvisor 组件依赖关系
│   ├── 协同开发方案.md              # 协同开发方案
│   ├── 组件开发及管理规范.md         # 组件开发规范
│   ├── 组件开发方案.md              # 组件开发方案
│   └── 组件测试方案.md              # 组件测试方案
├── Cargo.toml                      # Workspace 配置
├── README.md                       # 项目说明
├── LICENSE                         # 许可证
└── .gitmodules                     # Submodule 配置

说明：[组织名] 标注表示该组件所属的 GitHub 组织。部分仓库（如 arceos、axplat_crates 等）包含多个 crate，在表格中以"与 xxx 同仓库"标注。

1.2 维护脚本

脚本	用法	说明
checkout.sh	bash scripts/checkout.sh all dev	批量切换分支
	bash scripts/checkout.sh reset all	恢复所有组件到默认分支
check.sh	bash scripts/check.sh all	批量代码检查（fmt/clippy/doc）
reset.sh	bash scripts/reset.sh all	撤销所有组件的更改
commit.sh	bash scripts/commit.sh all "msg"	批量提交组件变更
push.sh	bash scripts/push.sh all	批量推送组件
sync.sh	bash scripts/sync.sh all dev	同步子模块到远程最新
version.sh	bash scripts/version.sh all 0.2.0	批量更新版本号
tag.sh	bash scripts/tag.sh all v0.2.0	批量创建标签
publish.sh	bash scripts/publish.sh	发布到 crates.io
pack.sh	bash scripts/pack.sh	打包子模块
unpack.sh	bash scripts/unpack.sh	解包子模块

---

二、组件

组织	组件数量	Submodule 数量	备注
arceos-hypervisor	20	19	axvisor_api： axvisor_api、axvisor_api_proc arm_vcpu： arm_vcpu、arm_vgic riscv_vcpu： riscv_vcpu、riscv_vplic、riscv-h x86_vcpu： x86_vcpu、x86_vlapic 其他组件为独立仓库
arceos-org	57	26	arceos： arceos_api、axalloc、axconfig、axdriver、axfeat、axhal、axlog、axmm、axruntime、axstd、axsync、axtask、axfs、axfs_devfs、axfs_ramfs、axfs_vfs、axplat-dyn axmm_crates： memory_addr、memory_set axplat_crates： axplat、axplat-macros、axplat-aarch64-、axplat-riscv64-、axplat-loongarch64-、axplat-x86- page_table_multiarch： page_table_entry、page_table_multiarch percpu： percpu、percpu-macros ctor_bare： ctor_bare、ctor_bare_macros axdriver_crates： axdriver_base、axdriver_pci、axdriver_block、axdriver_virtio 其他组件为独立仓库
rcore-os	13	5	somehal： somehal、page-table-generic、bindeps-simple、kasm-、kdef-、num-align、pie-* 其他组件为独立仓库
Starry-OS	10	10	组件均为独立仓库
drivercraft	22	0	rdrive： rdrive、rdrive-macros、rdif-base、rdif-block、rdif-clk、rdif-def、rdif-intc、rdif-pcie ostool： fitimage、jkconfig、ostool、uboot-shell 其他组件为独立仓库
总计	121	60

注：此外还依赖约 400+ 个第三方库，主要包括：

• rust-embedded：aarch64-cpu, riscv, x86_64 等架构特定库
• rust-osdev：x86 等底层硬件库
• 其他 crates.io 库：log, spin, bitflags, cfg-if, hashbrown, fdt-parser 等

2.1 arceos-hypervisor 组织组件

组件名称	crates.io	仓库地址	Submodule 路径	描述
axvisor		https://github.com/arceos-hypervisor/axvisor	os/axvisor	ArceOS Hypervisor 主项目
aarch64_sysreg		https://github.com/arceos-hypervisor/aarch64_sysreg	components/aarch64_sysreg	系统寄存器地址转换
axaddrspace		https://github.com/arceos-hypervisor/axaddrspace	components/axaddrspace	Guest 地址空间管理
axdevice		https://github.com/arceos-hypervisor/axdevice	components/axdevice	设备抽象层
axdevice_base		https://github.com/arceos-hypervisor/axdevice_base	components/axdevice_base	设备模拟基础 trait
axhvc		https://github.com/arceos-hypervisor/axhvc	components/axhvc	HyperCall 定义
axklib		https://github.com/arceos-hypervisor/axklib	components/axklib	内核库
axvcpu		https://github.com/arceos-hypervisor/axvcpu	components/axvcpu	VCPU 抽象层
axvisor_api		https://github.com/arceos-hypervisor/axvisor_api	components/axvisor_api	Hypervisor API
axvisor_api_proc		https://github.com/arceos-hypervisor/axvisor_api	与 axvisor_api 同仓库	Hypervisor API 宏
axvm		https://github.com/arceos-hypervisor/axvm	components/axvm	VM 资源管理
axvmconfig		https://github.com/arceos-hypervisor/axvmconfig	components/axvmconfig	VM 配置工具
range-alloc-arceos		https://github.com/arceos-hypervisor/range-alloc	components/range-alloc-arceos	范围分配器
x86_vcpu		https://github.com/arceos-hypervisor/x86_vcpu	components/x86_vcpu	x86 VCPU 实现
x86_vlapic		https://github.com/arceos-hypervisor/x86_vlapic	components/x86_vlapic	x86 虚拟 Local APIC
arm_vcpu		https://github.com/arceos-hypervisor/arm_vcpu	components/arm_vcpu	ARM VCPU 实现
arm_vgic		https://github.com/arceos-hypervisor/arm_vgic	components/arm_vgic	ARM 虚拟中断控制器
riscv_vcpu		https://github.com/arceos-hypervisor/riscv_vcpu	components/riscv_vcpu	RISC-V VCPU 实现
riscv-h		https://github.com/arceos-hypervisor/riscv-h	components/riscv-h	RISC-V H 扩展寄存器
riscv_vplic		https://github.com/arceos-hypervisor/riscv_vplic	components/riscv_vplic	RISC-V 虚拟 PLIC

2.2 arceos-org 组织组件

组件名称	crates.io	仓库地址	Submodule 路径	描述
arceos_api		https://github.com/arceos-org/arceos	与 arceos 同仓库	ArceOS API
axalloc		https://github.com/arceos-org/arceos	与 arceos 同仓库	内存分配模块
axallocator		https://github.com/arceos-org/allocator	components/axallocator	内存分配器接口
axconfig		https://github.com/arceos-org/arceos	与 arceos 同仓库	配置模块
axconfig-gen		https://github.com/arceos-org/axconfig-gen	components/axconfig-gen	配置生成工具
axconfig-macros		https://github.com/arceos-org/axconfig-gen	components/axconfig-gen (同仓库)	配置宏
axcpu		https://github.com/arceos-org/axcpu	components/axcpu	CPU 抽象层
axerrno		https://github.com/arceos-org/axerrno	components/axerrno	错误码定义
axfeat		https://github.com/arceos-org/arceos	与 arceos 同仓库	特性管理
axhal		https://github.com/arceos-org/arceos	与 arceos 同仓库	硬件抽象层
axio		https://github.com/arceos-org/axio	components/axio	IO 抽象
axlog		https://github.com/arceos-org/arceos	与 arceos 同仓库	日志模块
axmm		https://github.com/arceos-org/arceos	与 arceos 同仓库	内存管理模块
axplat		https://github.com/arceos-org/axplat_crates	components/axplat_crates	平台抽象层
axplat-macros		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	平台抽象层宏
axruntime		https://github.com/arceos-org/arceos	与 arceos 同仓库	运行时模块
axsched		https://github.com/arceos-org/axsched	components/axsched	调度器
axstd		https://github.com/arceos-org/arceos	与 arceos 同仓库	标准库
axsync		https://github.com/arceos-org/arceos	与 arceos 同仓库	同步原语
axtask		https://github.com/arceos-org/arceos	与 arceos 同仓库	任务管理
cpumask		https://github.com/arceos-org/cpumask	components/cpumask	CPU 掩码
crate_interface		https://github.com/arceos-org/crate_interface	components/crate_interface	Crate 接口宏
ctor_bare_macros		https://github.com/arceos-org/ctor_bare	与 ctor_bare 同仓库	裸机构造器宏
ctor_bare		https://github.com/arceos-org/ctor_bare	components/ctor_bare	裸机构造器
handler_table		https://github.com/arceos-org/handler_table	components/handler_table	处理函数表
kernel_guard		https://github.com/arceos-org/kernel_guard	components/kernel_guard	内核临界区保护
kspin		https://github.com/arceos-org/kspin	components/kspin	内核自旋锁
lazyinit		https://github.com/arceos-org/lazyinit	components/lazyinit	延迟初始化
linked_list_r4l		https://github.com/arceos-org/linked_list_r4l	components/linked_list_r4l	链表实现
memory_addr		https://github.com/arceos-org/axmm_crates	components/axmm_crates	内存地址类型
memory_set		https://github.com/arceos-org/axmm_crates	components/axmm_crates (同仓库)	内存区域集合
page_table_entry		https://github.com/arceos-org/page_table_multiarch	components/page_table_multiarch	页表项
page_table_multiarch		https://github.com/arceos-org/page_table_multiarch	components/page_table_multiarch (同仓库)	多架构页表
percpu		https://github.com/arceos-org/percpu	components/percpu	Per-CPU 变量
percpu-macros		https://github.com/arceos-org/percpu	components/percpu (同仓库)	Per-CPU 宏
timer_list		https://github.com/arceos-org/timer_list	components/timer_list	定时器列表
axdriver		https://github.com/arceos-org/arceos	与 arceos 同仓库	ArceOS 驱动框架
axdriver_base		https://github.com/arceos-org/axdriver_crates	components/axdriver_crates	驱动基础 trait
axdriver_pci		https://github.com/arceos-org/axdriver_crates	components/axdriver_crates (同仓库)	PCI 驱动
axdriver_block		https://github.com/arceos-org/axdriver_crates	components/axdriver_crates (同仓库)	块设备驱动
axdriver_virtio		https://github.com/arceos-org/axdriver_crates	components/axdriver_crates (同仓库)	VirtIO 驱动
axfs		https://github.com/arceos-org/arceos	与 arceos 同仓库	文件系统
axfs_devfs		https://github.com/arceos-org/arceos	与 arceos 同仓库	设备文件系统
axfs_ramfs		https://github.com/arceos-org/arceos	与 arceos 同仓库	内存文件系统
axfs_vfs		https://github.com/arceos-org/arceos	与 arceos 同仓库	虚拟文件系统
axplat-dyn		https://github.com/arceos-org/arceos	与 arceos 同仓库	动态平台抽象层
axplat-aarch64-peripherals		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	ARM64 外设平台
axplat-aarch64-qemu-virt		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	ARM64 QEMU 平台
axplat-riscv64-qemu-virt		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	RISC-V QEMU 平台
axplat-riscv64-visionfive2		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	VisionFive2 RISC-V 平台
axplat-loongarch64-qemu-virt		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	LoongArch QEMU 平台
axplat-x86-pc		https://github.com/arceos-org/axplat_crates	与 axplat_crates 同仓库	x86 PC 平台
int_ratio		https://github.com/arceos-org/int_ratio	components/int_ratio	整数比例
cap_access		https://github.com/arceos-org/cap_access	components/cap_access	能力访问控制
arm_pl011		https://github.com/arceos-org/arm_pl011	components/arm_pl011	ARM PL011 UART
arm_pl031		https://github.com/arceos-org/arm_pl031	components/arm_pl031	ARM PL031 RTC
riscv_plic		https://github.com/arceos-org/riscv_plic	components/riscv_plic	RISC-V PLIC

2.3 rcore-os 组织组件

组件名称	crates.io	仓库地址	Submodule 路径	描述
bitmap-allocator		https://github.com/rcore-os/bitmap-allocator	components/bitmap-allocator	位图分配器
virtio-drivers		https://github.com/rcore-os/virtio-drivers	components/virtio-drivers	VirtIO 驱动
arm-gic-driver		https://github.com/rcore-os/arm-gic-driver	components/arm-gic-driver	ARM GIC 驱动
any-uart		https://github.com/rcore-os/any-uart	components/any-uart	通用 UART 驱动
somehal		https://github.com/rcore-os/somehal	components/somehal	硬件抽象层
page-table-generic		https://github.com/rcore-os/somehal	与 somehal 同仓库	通用页表
bindeps-simple		https://github.com/rcore-os/somehal	与 somehal 同仓库	简单二进制依赖
kasm-aarch64		https://github.com/rcore-os/somehal	与 somehal 同仓库	ARM64 汇编
kdef-pgtable		https://github.com/rcore-os/somehal	与 somehal 同仓库	页表定义
num-align		https://github.com/rcore-os/somehal	与 somehal 同仓库	数字对齐
pie-boot-if		https://github.com/rcore-os/somehal	与 somehal 同仓库	PIE 启动接口
pie-boot-loader-aarch64		https://github.com/rcore-os/somehal	与 somehal 同仓库	ARM64 PIE 加载器
pie-boot-macros		https://github.com/rcore-os/somehal	与 somehal 同仓库	PIE 启动宏

2.4 Starry-OS 组织组件

组件名称	crates.io	仓库地址	Submodule 路径	描述
axbacktrace		https://github.com/Starry-OS/axbacktrace	components/axbacktrace	调用栈回溯
axpoll		https://github.com/Starry-OS/axpoll	components/axpoll	IO 多路复用
axfs-ng-vfs		https://github.com/Starry-OS/axfs-ng-vfs	components/axfs-ng-vfs	虚拟文件系统层
rsext4		https://github.com/Starry-OS/rsext4	components/rsext4	轻量级 ext4 文件系统
scope-local		https://github.com/Starry-OS/scope-local	components/scope-local	作用域本地存储
starry-process		https://github.com/Starry-OS/starry-process	components/starry-process	进程管理
starry-signal		https://github.com/Starry-OS/starry-signal	components/starry-signal	信号处理
starry-vm		https://github.com/Starry-OS/starry-vm	components/starry-vm	虚拟内存管理
starry-smoltcp		https://github.com/Starry-OS/smoltcp	components/starry-smoltcp	网络协议栈
StarryOS	N/A	https://github.com/Starry-OS/StarryOS	os/StarryOS	Starry 操作系统

2.5 drivercraft 组织组件

组件名称	crates.io	仓库地址	Submodule 路径	描述
rdrive		https://github.com/drivercraft/rdrive	暂不添加为 SUBMODULE	Rust 驱动框架
rdrive-macros		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	驱动框架宏
rdif-base		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	驱动接口基础
rdif-block		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	块设备接口
rdif-clk		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	时钟接口
rdif-def		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	接口定义
rdif-intc		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	中断控制器接口
rdif-pcie		https://github.com/drivercraft/rdrive	与 rdrive 同仓库	PCIe 接口
dma-api		https://github.com/drivercraft/dma-api	暂不添加为 SUBMODULE	DMA API
aarch64-cpu-ext		https://github.com/drivercraft/aarch64-cpu-ext	暂不添加为 SUBMODULE	ARM64 CPU 扩展
pcie		https://github.com/drivercraft/pcie	暂不添加为 SUBMODULE	PCIe 驱动
release-dep		https://github.com/drivercraft/release-dep	暂不添加为 SUBMODULE	发布依赖
fitimage		https://github.com/drivercraft/ostool	与 ostool 同仓库	FIT 镜像工具
jkconfig		https://github.com/drivercraft/ostool	与 ostool 同仓库	配置工具
mbarrier		https://github.com/drivercraft/mbarrier	暂不添加为 SUBMODULE	内存屏障
ostool		https://github.com/drivercraft/ostool	暂不添加为 SUBMODULE	操作系统工具
phytium-mci		https://github.com/drivercraft/phytium-mci	暂不添加为 SUBMODULE	Phytium MCI 驱动
rk3568_clk		https://github.com/drivercraft/rk3568-clk	暂不添加为 SUBMODULE	RK3568 时钟驱动
rk3588-clk		https://github.com/drivercraft/rk3588-clk	暂不添加为 SUBMODULE	RK3588 时钟驱动
rockchip-pm		https://github.com/drivercraft/rockchip-pm	暂不添加为 SUBMODULE	Rockchip 电源管理
sdmmc		https://github.com/drivercraft/sdmmc	暂不添加为 SUBMODULE	SD/MMC 驱动
uboot-shell		https://github.com/drivercraft/ostool	与 ostool 同仓库	U-Boot Shell 工具

2.6 组件依赖关系

AxVisor

参见 Axvisor 组件依赖关系与层级图

Starry

参见 Starry 组件依赖关系与层级图

---

三、环境准备

3.1 Git 配置

# 配置用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 配置 SSH 密钥（如已有可跳过）
ssh-keygen -t ed25519 -C "your.email@example.com"
cat ~/.ssh/id_ed25519.pub  # 添加到 GitHub SSH keys

3.2 Rust 工具链

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装目标架构
rustup target add aarch64-unknown-none-softfloat
rustup target add x86_64-unknown-none
rustup target add riscv64gc-unknown-none-elf

# 安装必要组件
rustup component add rust-src llvm-tools rustfmt clippy

---

四、快速开始

# 通过 crates.io 下载
cargo install cargo-clone
cargo clone axcrates
cd axcrates
bash scripts/unpack.sh

# 查看文档
cd axvcpu && cargo doc --open

# 编译组件
cd arm_vcpu && cargo build --target aarch64-unknown-none-softfloat

---

五、开发

5.1 开发方式选择

方式	适用场景	特点
独立子仓库开发	单组件修改	直接克隆子仓库，轻量快捷
axcrates 统一仓库开发	跨组件协作	通过主仓库统一管理所有组件

开始开发
    │
    ├── 只修改单个组件？ ──► 独立子仓库开发 (5.2)
    │
    └── 需要修改多个组件？ ──► axcrates 统一开发 (5.3)

5.2 单组件开发

适用于只修改单个组件的场景：

# 1. 克隆子仓库
git clone git@github.com:arceos-hypervisor/axvcpu.git
cd axvcpu

# 2. 创建功能分支
git checkout dev && git pull
git checkout -b feature/new-api

# 3. 修改代码并检查
cargo fmt --check
cargo clippy -- -D warnings
cargo build

# 4. 提交并推送
git add . && git commit -m "feat: add new API"
git push origin feature/new-api

# 5. 创建 PR（dev 分支可直接合并，main 分支需 review）

5.3 多组件开发

适用于跨组件协作或版本发布：

# 1. 克隆主仓库（包含所有子模块）
git clone --recurse-submodules git@github.com:arceos-hypervisor/axcrates.git
cd axcrates

# 2. 切换所有组件到目标分支
bash scripts/checkout.sh all dev

# 3. 修改组件代码...

# 4. 批量代码检查
bash scripts/check.sh all

# 5. 批量提交
bash scripts/commit.sh all "feat: update APIs"

# 6. 批量推送
bash scripts/push.sh all

5.4 版本发布

所有组件使用相同版本号，通过 axcrates 仓库统一发布：

5.4.1 预览版（dev 分支）

# 1. 升级版本号
bash scripts/version.sh all 0.2.0-preview.1

# 2. 提交并推送
bash scripts/commit.sh all "chore: release v0.2.0-preview.1"
bash scripts/push.sh all

# 3. 创建标签（可选）
bash scripts/tag.sh all v0.2.0-preview.1

# 4. 发布到 crates.io（可选）
cargo login && bash scripts/publish.sh

5.4.2 稳定版（main 分支）

# 1. 升级版本号
bash scripts/version.sh all 0.2.0

# 2. 提交
bash scripts/commit.sh all "chore: release v0.2.0"

# 3. 创建 PR 到 main 分支并合并

# 4. 合并后，同步并打标签
git checkout main && git pull --recurse-submodules
bash scripts/sync.sh all main
bash scripts/tag.sh all v0.2.0

# 5. 发布到 crates.io
cargo login && bash scripts/publish.sh

---

六、许可证

Apache-2.0