Skip to content

Translation update pending. The Chinese source has changed; the current Chinese version is shown below.

A20OS 文档首页

欢迎查阅 A20OS 设计与开发技术文档。系统 1.0 范围与技术决策见 1.0 计划 与 验收计划。

  • 首次体验与快速开始:推荐阅读 构建与运行指南,按步骤准备环境并通过 tools/a20 run qemu-riscv64 -- -j4 启动 RISC-V 64 交互系统。进入 shell 后输入 poweroff 正常关机。
  • 系统架构概览:阅读 architecture.md 了解混合内核设计、双 ABI 机制以及模块划分;启动与硬件发现机制见 启动模型。
  • 文档站点:在线文档使用 MkDocs Material 构建,本地预览可运行 mkdocs serve 或 bash site/build.sh。

这里汇集了 A20OS 的设计与开发文档。A20OS 是一个**混合内核**:性能关键路径(调度、MM、VFS、页缓存)留在内核态,驱动既可按 generic profile 作为内核 .a20drv 包部署,也可按 embedded profile 静态链接;Native ABI 还提供用户态驱动服务与文件系统宿主机制(uxfs/ufsd)。Linux ABI兼容现有 musl 生态,Native ABI提供面向能力、句柄与事件的新接口;登记入口以各自 syscall_table.def 为准,数量不等同于语义完整性。混合内核的设计参考见 hybrid-kernel/00-design.md。

文档范围与权威性

  • 当前事实文档:本页、architecture.md、dev/build.md、dev/instances.md、kernel/process-scheduler.md 和 testing-gates.md 以当前源码接口为目标;它们不单独证明运行结果。
  • 目录分工:根目录只放入口文档(本页、贡献指南、架构总览、测试门禁与致谢/许可声明);dev/ 放构建、运行、调试与外部依赖;kernel/ 放核心内核参考(调度、内存管理、Linux ABI 细节、架构特性);其余按子系统分目录(drivers/、fs/、net/、graphics/、native-abi/、cluster/、hypervisor/、platforms/ 等)。
  • 设计与规划文档:hybrid-kernel/、hypervisor/ 以及标题或正文明确标为 plan/design 的页面可以描述目标能力;未在源码和测试入口中落地的内容不能当作当前功能。
  • 研究笔记:research/ 是 A20OS 研究方向的主张与设计材料(能力信封、预算能力、形式化议程)。其中标注"未开始/进行中"的内容是研究计划,不是系统功能。
  • 第三方材料:kernel/external/、user/external/ 中的 vendor 文档解释上游背景,不定义 A20OS 当前接口。
  • 冲突时的顺序:HEAD 源码和头文件优先,其次是根 Makefile 与 tools/*.mk/测试脚本,再其次是与当前提交匹配的运行日志,最后才是叙述性文档。

按读者选择参考页

用户操作路径只承载用途、前提、命令、可观察结果与失败语义。锁序、引用/所有权、内部状态与回滚机制属于技术参考页或源码注释;操作页用链接引导需要实现细节的读者。驱动开发教程中的寄存器与 DMA 契约、调试命令需要的参数布局属于其读者完成操作的前提。

文档时效性约定

为避免每篇文档各自维护核对基线,统一约定如下:

  • 文档描述的是**接口与设计契约**,以 HEAD 源码为最终依据;发现文档与源码不一致时,以源码为准,并欢迎直接修正文档。
  • 单篇文档头部的"最后核实"日期表示内容在该时点与源码核对过;日期久远不等于内容失效。
  • 运行类结论不写入文档,运行产物也不随仓库保存。任何结论在作为当前事实引用前,必须按 testing-gates.md 的入口在**当前提交**上实际重跑。

刚接触项目的话,下面几条路径可能用得上。

快速开始(给新贡献者)

如果你准备第一次看代码、改 bug 或者提交补丁:

驱动开发

如果你要添加或维护某个设备驱动:

平台移植与运行

  • 平台文档约定:单平台页面的范围、支持状态与操作要求。
  • 移植指南:板级接口、构建接入与验证要求。
  • tools/a20 boards 和 tools/a20 list:查询当前源码中的板配置及实例;部署步骤分别写在对应的平台页面中。

用户态、桌面与发行版

  • packaging/overview.md:包管理与镜像分发体系(apk 打包、world 组装、仓库签名、CI/CD)
  • distro/README.md:Alpine rootfs 发行版路径(A20OS 作内核、原生发行版作用户态)
  • distro/source-software-porting.md:把新软件接进 A20OS(Alpine 上游包写进 world 清单;仍需从源码构建的只有 user/cmds/ 与 fastfetch)与运行时验证

实时操作系统(RTOS)

CMSIS-RTOS2 是独立的第三方 source-level ABI,不属于 Native ABI;完整子系统见 实时执行与 RTOS 子系统。

Native ABI 与子系统细节

如果你想深入 Native ABI 或具体内核子系统:

外来架构翻译通道(exec-xlator)

execve 一个外来架构(x86_64 / aarch64)的 Linux 可执行文件,内核把它改写成一次对用户态翻译器的就地 re-exec。不了解本系统的人从索引点进来可以按角色直接选入口:

Linux ABI 兼容层

  • kernel/abi/linux/syscall_coverage.md:Linux syscall 的逐项兼容等级与证据(含四主线架构编号覆盖说明)
  • kernel/abi/linux/compat_notes.md:Linux ABI 兼容性说明(高风险 partial 区域、文件化接口、占位符决策记录)
  • architecture.md:ABI 分层原则(核心实现、ABI 薄包装)与两套 ABI 对比

虚拟化(hypervisor)

共享 VM/vCPU 核心现有 RV64 H、RV32 H、AArch64 EL2、ARM32 HYP、AMD SVM 与 Intel VMX 后端,多架构小载荷的双 vCPU 并行运行已验证。Intel VMX 使用 Bochs 软件 CPU 验证。LoongArch LVZ 是默认关闭的实验实现,已完成编译与无 LVZ 禁用回退验证,尚未在物理硬件上执行。完整 OS guest 的 ELF/FDT 装载和管理器工作流仍面向 RV64,完整 OS SMP、虚拟 GIC/APIC 和长稳压测属于后续规划。

多架构运行入口为 python3 tools/qemu/check_hyp_multiarch.py --arch ARCH --cpus 2 --build,VMX 另用 Bochs runner。旧 smoke-hyp-* 门禁保留 RV64 完整 guest 场景覆盖;不能将多架构小载荷通过等同于这些完整 guest 场景全部通过。 Native 与 Linux 扩展 ABI 共享内核核心,但编号、handle 和权限包装各自独立;当前没有 A20 /dev/kvm 兼容层。

当前契约与边界记录

研究与项目背景

如果你关注研究思路或工程路线图:


这些文档既包含当前接口说明,也包含研究设计与历史记录。引用能力或测试结论时,先按上面的范围和时效性约定判断其性质。