Proka Kernel

欢迎阅读 Proka Kernel 开发文档。Proka Kernel 是一个为 ProkaOS 设计的基于 Rust 的内核，旨在探索 x86_64 裸机上的内存安全与模块化设计。

Proka Kernel 由 RainSTR Studio 的年轻开发者们共同维护。

Vision

Conventions

快速开始

本章节将引导你完成开发环境的搭建、内核的编译以及在模拟器中运行。

环境配置

核心构建工具

• Rust Toolchain: nightly 版本，目标平台 x86_64-unknown-none。
• GCC: 用于编译 C 代码。
• Make: 构建自动化。

模拟与镜像工具

• QEMU: 内核模拟运行。
• xorriso: 创建 ISO 镜像。
• cpio: 创建 initrd 镜像。

编译与运行

编译内核

make

创建 ISO 镜像

make iso

在 QEMU 中运行

make run

Debugging

内核架构

本章节深入探讨 Proka Kernel 的内部实现，从引导协议到各核心系统的协作。

引导协议 (Limine)

Proka Kernel 严格遵循 Limine Boot Protocol。

关键请求

• Base Revision: 内核通过 BASE_REVISION 请求告知引导程序其支持的协议版本。
• Framebuffer Request: 请求图形帧缓冲区信息。
• Memory Map Request: 获取物理内存布局。

Initialization

Interrupts

Gdt Idt

Apic

内存管理

Proka Kernel 的内存管理分为以下几个层次：

1. 物理页分配 (PMM): 管理物理内存帧。
2. 虚拟内存分页 (VMM): 实现页表映射与保护。
3. 内核堆 (Heap): 提供动态内存分配功能。

Frame Allocator

Paging

Heap

Process

Graphics

设备驱动

介绍 Proka Kernel 的驱动框架以及已支持的硬件驱动实现。

Overview

Serial

Input

Timer

文件系统

介绍 Proka Kernel 的文件系统层次结构、VFS 以及 Initrd。

Vfs

Initrd

基础设施

Proka Kernel 使用了一套现代化的基础设施来简化内核的配置、构建和自动化测试流程。

本章节涵盖：

• 配置系统：如何使用 TUI 界面配置内核特性。
• 构建系统：Makefile 和 Cargo 的协作方式。
• CI/CD：自动化的集成测试流程。
• 目录结构：项目源代码的组织方式。

配置系统 (Kconfig)

Proka Kernel 借鉴了 Linux 内核的配置思路，使用 Kconfig.toml 文件定义内核的可配置选项，并提供类似 menuconfig 的交互界面。

技术栈

• cargo-anaxa: 一个基于 Rust 的内核配置工具，读取 Kconfig.toml 并生成 Rust 代码。
• Kconfig.toml: 采用 TOML 格式定义配置项及其依赖关系。

如何配置

运行以下命令进入 TUI 配置界面：

make menuconfig

原理

1. make menuconfig 启动 cargo-anaxa。
2. 用户在界面中选择配置。
3. 工具生成一个临时的 .config 文件（或直接导出）。
4. 在构建过程中，Rust 代码通过 include! 宏包含生成的配置常量。

构建系统 (Makefile)

项目采用 Makefile 作为顶层调度器，配合 Cargo 完成 Rust 内核的编译。

顶层 Makefile

位于项目根目录，负责：

• 调度内核编译。
• 调用 xorriso 生成 ISO。
• 管理 scripts 下的辅助工具。
• 启动 QEMU。

内核 Makefile

位于 kernel/Makefile，专注于：

• 处理 cargo 编译参数。
• 链接内核二进制文件。

构建流程

1. 预处理：生成配置头文件。
2. 内核编译：cargo build 编译 Rust 源码为 ELF。
3. Initrd 创建：打包 assets 中的必要文件。
4. 镜像合成：将 Limine 引导程序、内核 ELF 和 Initrd 合并为 ISO。

CI/CD 与工作流

我们使用 GitHub Actions 来确保代码质量。

自动化流水线

每当有代码推送到 main 分支或提交 PR 时，CI 会触发以下流程：

• 代码检查：运行 cargo fmt 和 cargo clippy。
• 内核构建：尝试编译 x86_64-unknown-none 目标。
• 测试运行：在 headless 模式下运行自动化测试脚本。

配置文件

流水线定义在 .github/workflows/test.yml。

项目目录结构

Proka Kernel 的代码组织遵循模块化原则。

.
├── assets/             # 引导配置、initrd 资源及固件 (OVMF)
├── docs/               # mdBook 文档源码
├── kernel/             # 内核核心源码 (Rust)
│   ├── src/            # 源代码
│   │   ├── drivers/    # 硬件驱动
│   │   ├── memory/     # 内存管理 (Paging, Allocator)
│   │   ├── interrupts/ # IDT, GDT, APIC
│   │   └── ...
│   └── Makefile        # 内核特定构建逻辑
├── scripts/            # 开发与构建辅助脚本
├── tests/              # 集成测试 (C/Rust)
├── Makefile            # 根目录 Makefile (总控)
└── book.toml           # mdBook 配置文件

更多细节请参考各目录下的 AGENTS.md 文件。

开发手册

面向开发者的指南，包括如何贡献代码、编写驱动以及使用测试框架。

New-Driver

Testing

贡献指南

感谢你抽出时间为 Proka Kernel 做出贡献！❤️

如何参与

提问

在提问之前，请先搜索已有的 Issues。如果没能找到答案，欢迎提交新的 Issue。

报告 Bug

好的 Bug 报告应包含：

• 预期的行为与实际行为。
• 复现步骤。
• 操作系统、平台以及相关工具的版本。

提交功能建议

功能建议也通过 GitHub Issues 进行跟踪。请提供清晰的标题和详细的描述，解释为什么该功能对大多数用户有用。

开发环境搭建

请参考环境配置章节。

代码质量与格式

我们使用 pre-commit 来确保代码质量和格式的一致性。

1. 安装 pre-commit。
2. 初始化 Hook：

   uvx pre-commit install
   

3. 自动检查：每次 git commit 时都会运行自动检查，包括 Rust 格式化等。

提交 PR 的流程

1. Fork 仓库并从 main 分支创建你的特性分支。
2. 实现 更改并确保符合现有风格。
3. 测试 更改（使用 make run）。
4. 提交 更改。
5. 推送 到你的 Fork 并提交 Pull Request。

附录

包含 API 参考链接、术语表及其他辅助信息。

API 参考

Glossary