Core Capabilities
可组合的系统软件基础能力
工作区按领域划分出 components/、memory/、drivers/、fs/、net/、virtualization/ 与 platforms/ 七类目录，每一类只暴露明确的能力边界。三套系统按各自需求选择组合这些能力，组件本身不绑定任何一套系统的运行语义。
010203040506
统一工程编排
cargo xtask 是三套系统共用的命令入口，覆盖配置生成、构建、镜像处理、QEMU 与板卡运行以及分层测试，同一条命令 在不同目标架构间保持相同的参数约定与判定方式。
内存基础能力
memory/ 收录分配器、地址类型、memory set、多架构页表以及 DMA 与 MMIO API，把物理地址转换和资源映射的差异收敛在明确的能力边界内。
任务与调度原语
ax-task、axsched、cpumask、ax-lazyinit 与 timer_list 提供与具体系统无关的任务调度核心、调度算法、CPU 掩码、惰性初始化和定时事件。
文件与进程组件
axfs-ng-vfs、ax-fs-ng 与 rsext4 组成文件系统层，StarryOS 侧的 starry-kernel、starry-signal 与 starry-vm 承载进程、信号和地址空间语义。
虚拟化基础对象
virtualization/ 提供 axvm、axaddrspace 与 axdevice 等基础对象，以及 arm_vgic、riscv_vplic、x86_vlapic 虚拟中断控制器，由 Axvisor 组合成完整的 VMM。
设备能力接口
dma-api、mmio-api、irq-framework 与 drivers/interface/ 下的 rdif-* 接口 crate 描述设备能力，使具体驱动实现不必依赖某一个系统的运行时。
Systems
面向不同运行目标的三套系统
三套系统各自维护启动入口、配置集合、运行时语义和测试套件，同时复用同一批组件与 ArceOS 基础能力。每张卡片自下而上展示该系统的复用基础、实现主体和运行目标。
Architecture
四层职责架构
四层描述的是职责归属而不是目录等级：场景入口选择能力与运行配置，系统语义定义接口行为和生命周期策略，领域能力沉淀可跨系统复用的实现，平台边界隔离 CPU、固件与板级差异。层与层之间只通过依赖声明、trait 和能力接口连接，完整依赖关系以组件关系图和构建配置为准。
ENTRY
场景入口
定义目标系统的能力选择、构建参数与运行场景，同一批领域实现通过不同的 package 与 feature 组合装配成面向该场景的镜像。
feature / package selectionboard / VM configurationSYSTEM
系统语义
实现内核生命周期、接口语义与运行策略：ArceOS 的模块化运行时、StarryOS 的 Linux 兼容语义和 Axvisor 的 VMM 都位于这一层。
OS lifecycle / syscall semanticscrate composition / policySHARED
领域能力
沉淀跨系统复用的内存、调度、I/O 与虚拟化机制，通过 no_std crate 与 trait 暴露能力，不引入具体系统的运行策略。
no_std reusable cratestraits / capability APIsPLATFORM
平台边界
适配 CPU 架构、固件、板级资源与设备访问，把启动、内存布局、时钟、中断和设备发现事实转换为上层可消费的稳定接口。
arch / board adaptersMMIO / DMA / IRQ contracts职责分层与实际依赖
四层用于解释代码应该放在哪里、允许依赖谁，不是严格的 Cargo 拓扑。例如 axvm 依赖 ArceOS 的运行时服务，部分领域组件之间也存在直接依赖；评估改动影响时，应核对直接依赖与 feature 条件，而不是只看目录层级。
水平切分的复用边界
同一层的 crate 通过 trait 或能力接口解耦，系统以组合方式获取能力，而不是通过继承或全局单例；新的系统集成需求应落在接口层，而不是扩散到具体实现。
副作用止于边界
MMIO、DMA、IRQ、固件与调度能力只通过显式 API 跨层传递，避免组件内部隐式访问硬件。能力契约可以隔离大部分系统与平台差异，但具体耦合仍需按组件逐一审查。
Component Workspace
Git Subtree 组件同步工作流
scripts/repo/repos.csv 登记组件来源映射，每条记录包含上游地址、分支、目标目录与分类；同步前应先确认目标目录有效。同步动作由维护者通过 repo.py 显式执行，组件改动不会自动写回上游仓库。
Git Subtree 映射：外部仓库 ↔ 统一工作区 ↔ 上游
axcpucomponents/axcpuarm_vgicvirtualization/arm_vgicrockchip-npudrivers/npu/rockchip-npuTGOSKits统一集成工作区
外部仓库汇聚登记上游来源与目标目录按领域分类维护组件映射
Subtree 同步工具repo.py list / pull / push集成验证后同步回上游
来源边界清晰repos.csv · target_dir · category
axcpu独立仓库arm_vgic独立仓库rockchip-npu独立仓库$ python3 scripts/repo/repo.py list查看组件仓库映射与同步状态← 组件仓库集成验证上游仓库 →
$ repo.py pull$ repo.py pushrepos.csvHardware Enablement
四架构平台与设备使能
四种架构都具备 ArceOS、StarryOS 与 Axvisor 的 QEMU 构建与 测试入口，差异集中在虚拟平台模型和启动路径上。drivers/ 按设备类型组织驱动核心与具体实现，通过 rdif-* 等能力接口接入系统。物理板卡用例登记在 CI 清单中，实际执行取决于变更路由、自托管运行器和硬件可用性。
01
四架构 QEMU 配置
三套系统均有对应构建与测试入口
aarch64-unknown-none-softfloatQEMU virt；板卡验证以 OrangePi-5-Plus 为主riscv64gc-unknown-none-elfQEMU virt；Axvisor 启用 sstcx86_64-unknown-noneq35 · ACPI；Axvisor 的 QEMU 用例需要 KVM 与 Intel VMX / AMD SVMloongarch64-unknown-none-softfloatQEMU virt；Axvisor 使用动态 UEFI/OVMF，需要 LVZ 容器02
drivers/ 设备类别
设备核心实现通过 RDIF 等能力接口接入系统
块设备
sdhci-host · dwmmc-host · phytium-mci-host · nvme-driver
网络
realtek-rtl8125 · eth-intel · fxmac_rs · rd-net
中断控制器
arm-gic-driver · ax-riscv-plic · rdif-intc
PCIe
pcie · rk3588-pci · rdif-pcie
USB
crab-usb · usb-if · usb-serial
AI 与多媒体
rockchip-npu · k230-kpu · sg2002-tpu · rockchip-rga · rockchip-jpeg
平台设备
rockchip-pwm · ax-arm-pl031 · some-serial · arm-scmi-rs
Self-hosted CI
实体板卡验证
当前 CI 清单登记的板卡与验证场景
OrangePi-5-Plus
- ArceOS PMU
- StarryOS suites
- Axvisor Linux/Starry Guest
Phytium Pi
- Axvisor Linux Guest
ROC-RK3568-PC
- Axvisor Linux Guest
ASUS NUC15 CRH
- Axvisor Linux Guest
AKA-00-SG2002
- StarryOS suites
VisionFive 2
- StarryOS suites
JL LSGD2K10
- StarryOS suites
Verification
从组件检查到真实板卡的三级验证
验 证按成本和覆盖面从低到高分为三级：先在宿主机上以最短反馈路径发现组件问题，再用 QEMU 运行完整系统镜像检查集成与运行语义，最后在自托管板卡上确认平台适配和真实设备行为。CI 按改动的影响范围选择其中若干级执行。
01快速反馈
Host 侧组件验证
按 std_crates.csv 白名单在宿主机上运行标准库测试，并对改动包执行静态检查，不需要目标系统或模拟器即可发现组件级问题。
- cargo xtask clippy
- cargo xtask test
- 按项目清单展开功能与目标组合
02完整语义
QEMU 系统级验证
构建目标系统镜像并在 QEMU 中运行，由 test-suit 配置中的成功与失败规则判定 syscall、进程、设备和 Guest 引导行为是否符合预期。
- ArceOS Rust / C / axtest 用例
- StarryOS grouped system + TTY 输入
- Axvisor Guest 引导与交互
03真实设备
板级场景回归
在自托管板卡上执行端到端场景，确认启动、设备与 Guest 行为在真实硬件上与 QEMU 的结论一致；执行与否取决于硬件可用性。
- platforms/* 编译与启动验证
- VM / Guest 配置兼容性回归
- 共享 crate 的多系统影响面检查
Documentation Map
面向研发任务的文档导航
文档按研发任务组织：从环境准备和快速上手，到构建配置与测试判定，再到架构说明和仓库协作流程，每类任务的入口如下。