# micro-kernel-riscv **Repository Path**: jinghang/micro-kernel-riscv ## Basic Information - **Project Name**: micro-kernel-riscv - **Description**: 用C语言实现,基于 RISC-V 64 位指令集架构的微内核操作系统 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-18 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MK-RV64:RISC-V 教学微内核 MK-RV64 是一个面向 QEMU `virt` 的 RV64 教学微内核。它在 OpenSBI 之后的单 hart、S 态环境中运行,为每个用户服务建立独立 Sv39 页表,通过定长 IPC、服务名注册/查找以及 MMIO/IRQ 最小授权,把普通服务和 NS16550A 串口驱动放到用户态。 当前源码已实际构建并在 QEMU 中完成用户态 echo 往返自检,关键结果为: ```text MK_SELF_TEST: PASS ``` 想理解微内核与宏内核的区别、完整设计方法和成熟系统对照,请继续阅读 **[微内核原理与源码解析](docs/microkernel.md)**。本 README 主要说明源码结构、构建运行、接口和扩展方法。 ## 1. 已实现特性 - **启动与平台**:QEMU `virt`,OpenSBI `fw_dynamic`,单 hart,S 态内核,128 MiB RAM; - **隔离**:Sv39 三级页表、独立用户页表、trampoline/trapframe、内核文本 RX、用户镜像 RX/RW 分区; - **用户任务**:最多 8 个静态任务,每任务一页内核栈、两页用户栈、栈下保护区域; - **调度**:SBI TIME 扩展,QEMU `virt` 上约 10 ms 时钟,单核轮转抢占,阻塞时睡眠、全部阻塞时 `wfi`; - **IPC**:72 字节固定消息、48 字节内联负载、每任务 4 条内核邮箱、发送队列满/接收空阻塞; - **RPC**:`ipc_call` 发送后过滤指定服务 tid 的回复,发送者 `source` 由内核覆写; - **服务发现**:16 字节名称缓冲区,注册、查找和用户态轮询让出式等待; - **用户态驱动**:静态 MMIO 能力与地址范围、IRQ 能力与位图、独占 IRQ 所有者、PLIC claim/ack/complete 协作; - **静态用户服务**:`uart`(构建目标 `serial`)、`echo`、`init`,分别链接为用户 ELF、转换为 `.bin` 后嵌入内核; - **日志分离**:内核早期诊断串口只服务启动/`panic`,正常用户打印通过 IPC 交给 `uart` 服务; - **开发工具**:并行构建、QEMU 启动、GDB 远程调试脚本和自动烟雾自检。 > 本项目没有实现 `fork`/`exec`、动态 ELF 加载、文件系统、SMP、共享内存、网络、POSIX、按需分页或通用 seL4 式能力空间。当前能力字段只是面向 MMIO/IRQ 的静态最小授权。 ## 2. 系统结构与启动路径 ![MK-RV64 启动流程](docs/images/boot-flow.svg) 启动链路如下: 1. QEMU 加载 [`/home/hang/qemu-11.1.1/pc-bios/opensbi-riscv64-generic-fw_dynamic.bin`](Makefile#L8) 和 `build/kernel/kernel.elf`; 2. OpenSBI 从 `0x80000000` 开始执行,在 M 态完成初始化后,以 S 态跳到 `0x80200000` 的内核 `_entry`; 3. [`kernel/entry.S`](kernel/entry.S) 保留 hart 0、设置 `gp` 和启动栈、清零 BSS,再调用 [`kmain`](kernel/main.c#L5-L25); 4. 内核依次初始化早期串口、物理页、Sv39 内核页表、trap、PLIC、IPC/IRQ 状态和四个用户任务; 5. 每个用户 bin 被复制到独立物理页,从虚拟地址 `0x400000` 的 `_start` 开始执行; 6. SBI 设置约 10 ms 时钟,轮转调度器通过 trampoline 在用户态和内核态之间切换; 7. `uart` 与 `echo` 注册服务,`init` 查找并调用 `echo`,校验回复后输出 `MK_SELF_TEST: PASS` 并退出; 8. 用户态应用 `echo` 打印内核传入的 `argc/argv` 后退出,演示"应用"与"服务"的区别。 四个初始任务的关系是: | 初始 tid | 类型 | 构建目标 / 诊断名 | 注册服务名 | 作用 | 硬件权限 | | ---: | --- | --- | --- | --- | --- | | 1 | 服务 | `serial` / `uart` | `uart` | NS16550A 初始化、轮询发送、接收日志 IPC | UART0 一页 MMIO;IRQ 10 授权,但当前未 attach | | 2 | 服务 | `echosrv` / `echosrv` | `echo` | 接收 `MK_MSG_ECHO` 并原样回复 | 无 | | 3 | 服务 | `init` / `init` | 无 | 发现 `echo`,执行 RPC 并检查端到端结果 | 无 | | 4 | 应用 | `echo` / `echo-app` | 无 | 打印 `argv` 后 `task_exit`,不常驻 | 无 | **服务与应用的区别**:服务常驻并注册服务名,通过 IPC 向其他任务提供能力(如 `echosrv`);应用执行一次性任务,不注册服务名,结束后退出(如 `apps/echo`)。两者共用用户库和镜像加载机制,但位于不同目录、使用不同构建列表。 tid 由静态创建顺序产生;客户端应通过 `service_lookup` 或 `service_wait` 发现服务,而不是把 tid 当作永久协议常量。 ## 3. 完整源码架构 ```text micro-kernel-riscv/ ├── Makefile # 交叉编译、静态服务聚合、QEMU/GDB/自检入口 ├── README.md # 本文:使用、接口和扩展指南 ├── common/ │ └── string.c # 内核与用户共享的 freestanding 字符串/内存函数 ├── include/mk/ │ ├── abi.h # 72 字节消息、名称长度、MMIO/IRQ 能力位 │ ├── driver.h # 用户驱动 API、8/32 位 MMIO 与屏障 │ ├── platform.h # 平台无关常量、用户布局、消息标签(设备参数由 FDT 提供) │ ├── string.h # 公共字符串函数声明 │ ├── syscall.h # 系统调用号与负错误码 │ ├── types.h # u8/u16/u32/u64、usize 等公共 ABI 类型 │ └── user.h # IPC、任务、服务和用户日志 API ├── kernel/ │ ├── entry.S # OpenSBI 后的 S 态入口、BSS、启动栈、单 hart │ ├── fdt.c # 解析 OpenSBI 传入的 FDT,取得 RAM/UART/PLIC │ ├── images.S # .incbin 嵌入 serial/echosrv/init/echo 用户 bin │ ├── ipc.c # 邮箱、阻塞 IPC、IRQ 所有权/等待/ack/分发 │ ├── kernel.h # 内核子系统接口 │ ├── kernel.ld # 0x80200000 内核布局、RX/RW、trampoline 断言 │ ├── kernelvec.S # 已处于 S 态时的中断/异常入口 │ ├── main.c # kmain 初始化顺序与调度入口 │ ├── plic.c # QEMU virt S 态 PLIC enable/claim/complete │ ├── pmm.c # 4 KiB 物理页空闲链表、分配清零与释放 │ ├── printf.c # kprintf 与 panic,走早期诊断串口 │ ├── riscv.h # Sv39 PTE、CSR、SSTATUS/SIE、内联汇编 │ ├── sbi.c # OpenSBI TIME 扩展调用 │ ├── swtch.S # 调度器/任务内核上下文切换 │ ├── syscall.c # 11 个系统调用、服务注册/查找、MMIO 检查 │ ├── task.c # 静态镜像描述、argc/argv 入栈、轮转调度 │ ├── task.h # trapframe/context/task、任务与邮箱上限 │ ├── trampoline.S # uservec/userret、satp 切换和用户寄存器恢复 │ ├── trap.c # 用户/内核 trap、SBI 时钟、外部中断与抢占 │ ├── uart.c # 仅供内核启动和致命错误的早期 UART 输出 │ └── vm.c # Sv39 walk/map、内核/用户页表、copyin/copyout ├── user/ │ ├── user.ld # 0x400000 用户布局、0x408000 数据边界、64 KiB 断言 │ ├── services/ # 常驻服务:注册服务名并通过 IPC 提供能力 │ │ ├── serial/main.c # 带详细中文注释的用户态 NS16550A/uart 服务 │ │ ├── echosrv/main.c # 用户态 echo RPC 服务(注册名 "echo") │ │ └── init/main.c # 端到端自检客户端 │ ├── apps/ # 一次性用户应用:执行完任务后退出 │ │ └── echo/main.c # 参考 xv6 user/echo.c 的参数打印应用 │ └── lib/ │ ├── start.S # 用户 _start、gp 初始化、argc/argv 透传、main 后 task_exit │ ├── syscall.c # a7/a0..a2/ecall 内联系统调用封装 │ ├── ipc.c # IPC、RPC、yield、exit 用户封装 │ ├── service.c # 服务注册、查找与等待 │ ├── driver.c # MMIO/IRQ 系统调用封装 │ └── printf.c # uprintf/uputs,格式化并拆分 UART IPC ├── scripts/ │ ├── gdbinit # GDB 远程连接、内核断点、用户符号加载提示 │ └── smoke_test.py # 限时运行 QEMU 并检查关键服务/PASS 输出 ├── docs/ │ ├── microkernel.md # 微内核原理、设计方法与源码详解 │ └── images/ # 本地 SVG:启动、对比、IPC、地址空间、IRQ └── build/ # 生成物,不是手写源码;make clean 会删除 ├── kernel/kernel.elf # 最终内核,含静态嵌入的用户 bin └── user/ # 各服务 main.o、ELF、bin 与用户库对象 ``` 构建时会为内核和每个用户服务生成 `.o`、`.d`,用户服务还保留带调试符号的 `.elf` 和供 `.incbin` 使用的扁平 `.bin`。`common/string.c` 分别编译进内核和用户库,不依赖宿主 libc。 ## 4. WSL Ubuntu 26.04 开发环境 以下命令在 **WSL 的 Ubuntu 26.04 终端**中执行,不是在 Windows PowerShell 中执行。项目路径为 `/home/hang/micro-kernel-riscv`。 ### 4.1 安装工具 ```bash sudo apt update sudo apt install -y \ build-essential \ gcc-riscv64-unknown-elf \ binutils-riscv64-unknown-elf \ gdb-multiarch \ python3 \ qemu-system-misc \ opensbi ``` 默认交叉工具前缀是 `riscv64-unknown-elf-`,因此应能找到: ```bash riscv64-unknown-elf-gcc --version riscv64-unknown-elf-ld --version riscv64-unknown-elf-objcopy --version gdb-multiarch --version python3 --version ``` 编译只需要 bare-metal GCC/binutils;不需要 RISC-V Linux glibc。自动自检需要 Python 3,调试需要 `gdb-multiarch`。 ### 4.2 QEMU 与 OpenSBI 的两种配置 **配置 A:使用当前机器已有的 QEMU 11.1.1。** Makefile 默认路径为: ```text QEMU=/home/hang/qemu-11.1.1/build/qemu-system-riscv64 OPENSBI=/home/hang/qemu-11.1.1/pc-bios/opensbi-riscv64-generic-fw_dynamic.bin ``` 在这台开发机上无需覆盖变量。 **配置 B:使用 apt 安装的系统 QEMU/OpenSBI。** Ubuntu 常见固件路径如下,可用 `dpkg -L opensbi` 确认实际位置: ```bash QEMU=/usr/bin/qemu-system-riscv64 OPENSBI=/usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin export QEMU OPENSBI make info ``` `make qemu` 的 Makefile 变量会读取环境值。如果环境没有被当前 shell/构建工具保留,也可在命令行显式覆盖: ```bash make qemu \ QEMU=/usr/bin/qemu-system-riscv64 \ OPENSBI=/usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin ``` 建议把项目放在 WSL Linux 文件系统内(当前 `/home/hang/...` 即符合),避免跨 Windows 文件系统编译带来的额外开销。 ## 5. 快速开始:编译、运行与自检 ### 5.1 编译 ```bash cd /home/hang/micro-kernel-riscv make -j4 ``` 默认目标会依次构建用户库、四个用户程序 ELF、四个 bin,最后链接 `build/kernel/kernel.elf`。编译参数包括 RV64GC/LP64D、freestanding、关闭 PIE、`-O2 -g3`,并把警告视为错误。 如需从干净状态重建: ```bash make clean make -j4 ``` `make clean` 只删除生成目录 `build/`。 ### 5.2 运行 ```bash make qemu ``` `make run` 是同一操作的别名。实际 QEMU 参数等价于: ```bash /home/hang/qemu-11.1.1/build/qemu-system-riscv64 \ -machine virt -smp 1 -m 128M -nographic \ -bios /home/hang/qemu-11.1.1/pc-bios/opensbi-riscv64-generic-fw_dynamic.bin \ -kernel build/kernel/kernel.elf -no-reboot ``` OpenSBI 的版本横幅、物理页数量等输出会随环境和镜像大小变化。关键输出应包含以下行(这里仅列关键内容,用户 IPC 日志与内核早期日志的相对顺序可能不同): ```text MK-RV64: educational microkernel [boot] OpenSBI -> supervisor mode, hart 0 [vm] Sv39 kernel page table enabled [task] tid=1 name=uart ... [task] tid=2 name=echo ... [task] tid=3 name=init ... [uart] user-mode NS16550A service ready [echo] service ready, waiting for RPC [task] tid=3 (init) exited [init] echo RPC verified from tid=2 MK_SELF_TEST: PASS ``` `...` 表示此处省略随构建变化的数值,并非固定输出文本。自检后 `uart` 和 `echo` 继续运行,所以 QEMU 不会自行退出。使用 `-nographic` 时按 **Ctrl-a,然后按 x** 退出 QEMU。 ### 5.3 自动自检 ```bash make check ``` 该目标先确保内核已构建,再运行 [`scripts/smoke_test.py`](scripts/smoke_test.py)。脚本最多运行 QEMU 约 5 秒;服务持续运行导致的超时终止是正常测试结束方式。脚本要求看到: - 用户态 UART 服务就绪; - echo 服务就绪; - init 收到来自 tid 2 的正确回复; - `MK_SELF_TEST: PASS`。 成功末尾还会输出: ```text smoke test: PASS ``` 如果使用 apt 的 QEMU/OpenSBI,而默认 `/home/hang/qemu-11.1.1/...` 不存在,可直接向自检脚本传入环境变量: ```bash make -j4 QEMU=/usr/bin/qemu-system-riscv64 \ OPENSBI=/usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin \ python3 scripts/smoke_test.py ``` 自检失败时脚本会打印完整 QEMU 输出和缺失标记,便于区分启动失败、服务注册失败与 IPC 回归。 ## 6. 微内核用户接口 公共声明位于 [`include/mk/user.h`](include/mk/user.h)、[`include/mk/driver.h`](include/mk/driver.h) 和 [`include/mk/syscall.h`](include/mk/syscall.h)。底层 ABI 是 `a7=系统调用号`、`a0..a2=参数`、`a0=long 返回值`;普通服务优先使用下列封装,而不是直接写内联汇编。 ### 6.1 IPC 与任务 | 系统调用号 | 用户接口 | 成功返回与阻塞语义 | | ---: | --- | --- | | 0 `IPC_SEND` | `int ipc_send(u32 tid, const struct mk_message *msg)` | 成功为 0;目标邮箱满时阻塞;不能发给自己 | | 1 `IPC_RECV` | `int ipc_recv(struct mk_message *msg)` | 接收任意来源,返回负载字节数;无消息时阻塞 | | 1 `IPC_RECV` | `int ipc_recv_from(u32 tid, struct mk_message *msg)` | 只接收指定 tid;没有匹配消息时阻塞,返回负载字节数 | | 2 `IPC_CALL` | `int ipc_call(u32 tid, const struct mk_message *req, struct mk_message *reply)` | 先发送,再只接收目标 tid 的回复;返回回复负载字节数,无超时 | | 3 `YIELD` | `void task_yield(void)` | 当前任务回到可运行队列,让调度器选择后续任务 | | 4 `EXIT` | `void task_exit(int status)` | 不返回;任务成为 `ZOMBIE`,当前资源不回收 | `MK_TID_ANY` 为 0,用于任意来源接收。`ipc_call` 只过滤回复来源,不匹配请求 ID 或 label,也不提供取消、超时和死锁检测。 ### 6.2 服务发现 | 系统调用号 | 用户接口 | 语义 | | ---: | --- | --- | | 9 `SERVICE_REGISTER` | `int service_register(const char *name)` | 为当前任务注册唯一非空名称;每任务最多一个服务名 | | 10 `SERVICE_LOOKUP` | `int service_lookup(const char *name)` | 成功返回正 tid,不存在返回 `-MK_ENOENT` | | 由用户库组合 | `int service_wait(const char *name)` | 反复 lookup,失败时 `task_yield`,发现后返回 tid;没有超时 | 名称缓冲区 `MK_SERVICE_NAME_SIZE` 为 16,包含结尾 NUL。空名、重复名或字符串无法安全复制都会失败。 ### 6.3 用户驱动 | 系统调用号 | 用户接口 | 语义 | | ---: | --- | --- | | 5 `MAP_MMIO` | `void *driver_map_mmio(u64 pa, u64 size)` | 成功返回与物理地址相同的用户虚拟地址,失败为 `NULL`;要求页对齐且在授权窗口内 | | 6 `IRQ_ATTACH` | `int driver_irq_attach(u32 irq)` | 独占接管被授权的 IRQ,成功为 0;已有所有者为 `-MK_EBUSY` | | 7 `IRQ_WAIT` | `u32 driver_irq_wait(void)` | 没有 pending IRQ 时阻塞;返回 pending 位图并清除 pending | | 8 `IRQ_ACK` | `int driver_irq_ack(u32 irq)` | 清设备源后调用;校验所有者/inflight,再让内核 PLIC complete | MMIO 访问使用 `mmio_read8/write8`、`mmio_read32/write32` 和必要的 `mmio_fence()`。这些函数通过 `volatile` 保留硬件访问语义。 ### 6.4 IPC 消息布局 [`struct mk_message`](include/mk/abi.h#L15-L20) 总计 72 字节: | 字段 | 偏移 | 大小 | 说明 | | --- | ---: | ---: | --- | | `source` | 0 | 8 | 发送者 tid,由内核在发送时覆写 | | `label` | 8 | 8 | 服务双方约定,内核不解释 | | `size` | 16 | 8 | 有效负载长度,范围 0~48 | | `data` | 24 | 48 | 内联负载,可包含 NUL | 每任务邮箱深度为 4,邮箱位于内核任务控制块,不是用户共享内存。发送和接收都通过 `copyin`/`copyout` 复制。长协议消息由服务自行分段;当前没有零拷贝或共享内存接口。 ### 6.5 负错误码 错误定义见 [`include/mk/syscall.h`](include/mk/syscall.h#L17-L25),接口以负值返回: | 常量 | 数值 | 常见原因 | | --- | ---: | --- | | `MK_EPERM` | 1 | 无 MMIO 能力或请求超出授权范围 | | `MK_EINVAL` | 2 | 参数、对齐、长度、来源 tid 或 IRQ 不合法,未知系统调用也返回此错误 | | `MK_EAGAIN` | 3 | 已保留的错误码,当前主要路径未使用 | | `MK_ENOENT` | 4 | 服务名不存在 | | `MK_EBUSY` | 5 | 服务名重复、任务已注册、IRQ 有所有者或映射冲突 | | `MK_EFAULT` | 6 | 用户指针/字符串复制失败或名称无效 | | `MK_ENOSPC` | 7 | 已保留的错误码,当前主要路径未使用 | | `MK_ENODEV` | 8 | 目标任务不存在或已退出 | 不要只检查 `!= 0` 来判断 `ipc_recv` 或 `service_lookup` 是否成功:前者成功可返回非负长度,后者成功返回正 tid。通常用 `< 0` 判断错误。 ## 7. 新增用户服务或应用程序 当前任务创建是静态的,因此新增程序需要同时更新**用户目录、构建列表、嵌入镜像符号、启动镜像表**。以下以服务名 `hello` 为例,将新项追加在现有 `init` 后,保持现有 tid 1~3 和自检逻辑不变。 先决定类型: - **服务**:需要注册服务名、常驻并响应 IPC,放在 `user/services//main.c`,加入 `SERVICES`; - **应用**:一次性执行、不注册服务,放在 `user/apps//main.c`,加入 `APPS`。 ### 步骤 1:创建服务入口 新建 `user/services/hello/main.c`。最小服务骨架如下;示例在本地定义协议标签 3,真实的多服务协议可把共享标签集中放入 `include/mk/platform.h`: ```c #include #include #define MK_MSG_HELLO 3UL int main(void) { if (service_register("hello") < 0) task_exit(-1); uprintf("[hello] service ready\n"); for (;;) { struct mk_message request; if (ipc_recv(&request) < 0 || request.label != MK_MSG_HELLO) continue; struct mk_message reply; memset(&reply, 0, sizeof(reply)); reply.label = MK_MSG_HELLO; const char text[] = "hello from user space"; memcpy(reply.data, text, sizeof(text)); reply.size = sizeof(text); if (ipc_send((u32)request.source, &reply) < 0) uprintf("[hello] client disconnected\n"); } } ``` `user/lib/start.S` 已提供 `_start`;入口仍写 `main`,`main` 返回后会自动调用 `task_exit`。 ### 步骤 2:加入构建列表 在 Makefile 的 `SERVICES` 末尾追加 `hello`(若是应用则追加到 `APPS`): ```make SERVICES := serial echosrv init hello APPS := echo ``` 现有模式规则会自动生成: ```text build/user/services/hello/main.o build/user/hello.elf build/user/hello.bin ``` ### 步骤 3:把 bin 嵌入内核 在 [`kernel/images.S`](kernel/images.S) 增加与文件名一致的符号: ```asm .globl hello_image_start, hello_image_end hello_image_start: .incbin "build/user/hello.bin" hello_image_end: ``` ### 步骤 4:注册静态任务镜像 在 [`kernel/task.c`](kernel/task.c) 顶部增加: ```c extern u8 hello_image_start[], hello_image_end[]; ``` 再在 `task_bootstrap` 的 `images[]` 中、现有 `init` 项之后追加: ```c { .name = "hello", .start = hello_image_start, .end = hello_image_end, }, ``` 普通服务不需要 MMIO/IRQ 权限,其余字段保持零初始化。`.name` 用于任务诊断,`service_register("hello")` 注册的是客户端查找所用服务名,两者用途不同。 若新增的是**应用**且需要命令行参数,在同一 `task_image` 中提供 `.argc` 和 `.argv`: ```c static const char *const hello_argv[] = { "hello", "world" }; { .name = "hello-app", .start = hello_app_image_start, .end = hello_app_image_end, .argc = 2, .argv = hello_argv, }, ``` 内核会把字符串和 `argv` 指针数组写入用户栈顶,并以 `a0=argc`、`a1=argv` 进入 `main`,因此应用可写成 `int main(int argc, char **argv)`。不设置这两个字段时 `argc` 为 0,`main(void)` 行为不变。 ### 步骤 5:重建并验证 ```bash make clean make -j4 make check riscv64-unknown-elf-size build/user/hello.elf ``` 用户镜像总布局不能超过 64 KiB:前 32 KiB RX、后 32 KiB RW,链接脚本会检查上限。新服务会阻塞在 `ipc_recv`,所以原 `init`/`echo` 自检仍应通过;新应用执行完会退出,不影响其他任务。 另一个静态客户端服务可按相同步骤加入,使用: ```c int tid = service_wait("hello"); ``` 然后发送符合约定 label/size 的请求。`service_wait` 没有超时,服务名拼写错误会一直等待,因此名称和协议标签应由通信双方共同维护。 ## 8. 新增一个用户态设备驱动 普通服务的四个接入步骤同样适用,区别是驱动还要描述硬件权限,并按设备协议处理 MMIO/IRQ。 ### 步骤 1:确定真实平台参数 从 QEMU 设备模型、设备树或硬件手册确认: - MMIO 物理基址和所需页对齐长度; - 外设 IRQ 编号; - 寄存器宽度、偏移、中断状态位和清中断方式。 设备物理基址和 IRQ 由内核启动时从 OpenSBI 传入的设备树解析,串口服务通过启动参数取得自己的 MMIO 窗口。新设备应扩展 [`kernel/fdt.c`](../kernel/fdt.c) 的解析规则,并在 `task_bootstrap` 中授予真实窗口,不能把占位地址当成已存在硬件。 ### 步骤 2:授予最小 MMIO/IRQ 权限 在 `task_bootstrap` 的该驱动镜像项中填写能力和范围。以下 `MYDEV_*` 只是需要替换为真实值的占位符: ```c { .name = "mydev", .start = mydev_image_start, .end = mydev_image_end, .capabilities = MK_CAP_MMIO | MK_CAP_IRQ, .mmio_base = MYDEV_BASE, .mmio_size = MYDEV_WINDOW_SIZE, .irq_allowed = 1U << MYDEV_IRQ, }, ``` `MYDEV_BASE` 和窗口长度必须页对齐,IRQ 必须在 1~31 且能由 `u32` 位图表示。如果驱动只轮询,不需要 IRQ,可去掉 `MK_CAP_IRQ`、`irq_allowed` 及所有 IRQ 调用。 ### 步骤 3:按顺序初始化驱动 用户 `main` 的推荐顺序: 1. `driver_map_mmio(MYDEV_BASE, MYDEV_WINDOW_SIZE)`; 2. 初始化设备,但先保持设备自身 IRQ 禁止; 3. 如需中断,调用 `driver_irq_attach(MYDEV_IRQ)`; 4. 初始化其余状态并注册服务名; 5. 最后按设备手册使能设备 IRQ。 所有返回值的错误路径都应明确处理。普通日志可用 `uprintf`,但不能在 `uart` 服务自身的早期初始化阶段依赖尚未建立的日志服务;现有串口代码选择直接退出并让内核报告错误。 ### 步骤 4:处理中断并完成 ack 中断循环的核心顺序为: ```c u32 pending = driver_irq_wait(); if (pending & (1U << MYDEV_IRQ)) { /* 读取设备状态、处理数据,并按硬件要求清除设备中断源。 */ clear_mydev_interrupt(); driver_irq_ack(MYDEV_IRQ); /* ack 后内核才执行 PLIC complete。 */ } ``` `clear_mydev_interrupt()` 是示意函数,必须用该设备真实的 MMIO 状态/确认寄存器实现。**先清设备源,后 `driver_irq_ack`**;不要 claim 后立即 complete,也不要忘记 ack。 可以参考 [`user/services/serial/main.c`](user/services/serial/main.c) 的页对齐 MMIO 映射、8 位寄存器访问、DLAB/8N1/FIFO 初始化和错误处理。它当前采用轮询发送,因此不是 IRQ 示例;IRQ 内核路径见 [`kernel/ipc.c`](kernel/ipc.c#L71-L126) 和 [`kernel/trap.c`](kernel/trap.c#L12-L42)。 ### 步骤 5:验证授权与故障路径 除正常 I/O 外,至少检查: - 未授权普通任务映射同一 MMIO 会被拒绝; - 超出窗口一页或一字节未对齐的请求会被拒绝; - 重复 attach 同一 IRQ 返回 `-MK_EBUSY`; - 非所有者或未 inflight 的 ack 返回 `-MK_EINVAL`; - 清中断源后 ack,设备不会形成持续中断风暴。 现有 `make check` 主要覆盖启动、命名、UART 轮询输出和 echo IPC;新增设备应增加对应可观察测试,不能把原 PASS 当成新驱动 IRQ 已验证的证明。 ## 9. 构建变量与常用目标 ### 9.1 变量 | 变量 | 默认值 | 用途 | | --- | --- | --- | | `CROSS_COMPILE` | `riscv64-unknown-elf-` | 派生 GCC、LD、OBJCOPY、OBJDUMP 前缀 | | `QEMU` | `/home/hang/qemu-11.1.1/build/qemu-system-riscv64` | QEMU 可执行文件 | | `OPENSBI` | `/home/hang/qemu-11.1.1/pc-bios/opensbi-riscv64-generic-fw_dynamic.bin` | M 态动态固件 | | `GDB` | `gdb-multiarch` | 远程调试器 | | `GDBPORT` | `1234` | `make qemu-gdb` 的 GDB TCP 监听端口 | 示例: ```bash make -j4 CROSS_COMPILE=riscv64-unknown-elf- make info make qemu QEMU=/usr/bin/qemu-system-riscv64 \ OPENSBI=/usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin ``` `make info` 显示当前编译器、QEMU、OpenSBI、GDB 和端口配置。 ### 9.2 目标 | 命令 | 作用 | | --- | --- | | `make` / `make all` | 构建用户服务及最终内核 ELF | | `make -j4` | 四路并行构建 | | `make clean` | 删除 `build/` 生成物和 `compile_commands.json` | | `make compiledb` | 生成 clangd 用的 `compile_commands.json` | | `make qemu` / `make run` | 启动单 hart、128 MiB、无图形界面的 QEMU | | `make qemu-gdb` | 添加 `-S -gdb tcp::1234`,启动即暂停等待 GDB | | `make gdb` | 加载内核符号并执行 `scripts/gdbinit` | | `make check` | 构建后运行限时 QEMU 自动烟雾自检 | | `make info` | 输出关键工具配置 | 需要查看反汇编时可直接使用交叉工具: ```bash riscv64-unknown-elf-objdump -d build/kernel/kernel.elf riscv64-unknown-elf-objdump -d build/user/echo.elf ``` ## 10. IDE / clangd 代码导航 本项目提供 clangd 配置,可在 VS Code / Cursor / CLion 等 IDE 中实现"转到定义""查找引用""自动补全"等功能。配置思路与 [`xv6-riscv-dev`](https://github.com/mit-pdos/xv6-riscv) 一致:用 `.clangd` 指定 RISC-V 目标参数,用 `compile_commands.json` 提供真实编译命令。 ### 10.1 一次性生成编译数据库 ```bash make compiledb ``` 该目标通过 `make -B -n` 打印所有编译命令,再由 [`scripts/gen_compiledb.py`](scripts/gen_compiledb.py) 提取每个 `.c` 文件的编译行,剥离 `env -i` 前缀和 clangd 不支持的 GCC 特有选项(如 `-msmall-data-limit`、`-fno-pie`、`-MMD` 等),保留 `-Iinclude`、`-Ikernel`、`-march` 等参数,以 `arguments` 数组形式写入 `compile_commands.json`。 修改源文件列表或编译选项后需要重新执行 `make compiledb`。该文件已加入 `.gitignore`,不会入库。 ### 10.2 `.clangd` 配置 [`.clangd`](.clangd) 已预置: - `--target=riscv64-unknown-elf`、`-march=rv64gc`、`-mabi=lp64d`、`-mcmodel=medany`:与构建参数一致; - `-ffreestanding`、`-fms-extensions`:适配内核内联汇编; - `-isystem` 指向本机 GCC 内置头目录,让 `` 等可解析; - `Remove` 去掉 clangd 不支持的 GCC 特有 flag(如 `-msmall-data-limit`、`-fno-common`); - `Index.Background: Build` 开启后台索引; - 屏蔽 `pp_file_not_found` 等误报,避免干扰跳转。 ### 10.3 在 VS Code / Cursor 中使用 1. 安装 **clangd** 扩展(同时建议禁用 Microsoft C/C++ 扩展的 IntelliSense,避免冲突); 2. 打开项目根目录(包含 `.clangd` 和 `compile_commands.json`); 3. 等待 clangd 完成索引(首次较慢); 4. 即可对 `ipc_send`、`task_create`、`kmain` 等符号使用 F12 跳转、Shift+F12 查找引用。 若跳转异常,可检查: ```bash # 确认编译数据库存在且非空 ls -l compile_commands.json && python3 -c "import json;print(len(json.load(open('compile_commands.json'))), 'entries')" # 重新生成 make clean && make compiledb ``` ## 11. GDB 远程调试 ### 11.1 双终端流程 **终端 1:启动暂停的 QEMU。** ```bash cd /home/hang/micro-kernel-riscv make qemu-gdb ``` QEMU 使用 `-S`,会在执行固件前暂停,并在本机 TCP 1234 等待 GDB。此终端保持运行。 **终端 2:连接 GDB。** ```bash cd /home/hang/micro-kernel-riscv make gdb ``` [`scripts/gdbinit`](scripts/gdbinit) 会设置 RV64 架构、执行 `target remote :1234`,并设置 `kmain`、`usertrap`、`syscall_dispatch` 断点。在 GDB 提示符输入: ```gdb continue ``` 继续执行后会先在内核 `kmain` 断点停下。常用命令: ```gdb break ipc_send continue info registers a0 a1 a2 a7 sepc scause satp x/10i $pc backtrace ``` 调试用户服务时,可在 GDB 中加载对应 ELF 符号: ```gdb add-symbol-file build/user/echo.elf ``` 也可替换为 `serial.elf` 或 `init.elf`。所有用户服务使用相同链接虚拟地址,但页表不同,建议**一次只加载一个服务的符号**,并结合当前 tid 判断地址属于哪个任务。 如改用系统 QEMU,只需在终端 1 覆盖工具变量: ```bash make qemu-gdb \ QEMU=/usr/bin/qemu-system-riscv64 \ OPENSBI=/usr/lib/riscv64-linux-gnu/opensbi/generic/fw_dynamic.bin ``` 终端 2 仍执行 `make gdb`。`GDBPORT` 变量控制 QEMU 监听端口,而当前 `scripts/gdbinit` 的 `target remote :1234` 是固定值;若更改端口,需要同步调整该连接地址,不能只改 Makefile 变量。 ### 11.2 调试时最值得观察的状态 - `_entry`/`kmain`:hartid、启动栈、BSS 和内核入口地址; - `vm_user_create`:根页表、trampoline 与 trapframe 映射; - `task_first_entry`:首次返回用户态的 `sepc=0x400000` 和 `sp=0x800000`; - `usertrap`:`scause`、保存的 `sepc`、当前任务 tid; - `syscall_dispatch`:`a7` 调用号及 `a0..a2` 参数; - `ipc_send`/`ipc_receive`:`source`、邮箱计数和睡眠原因; - `device_interrupt`:时钟与外部中断分支、PLIC claim; - `irq_ack`:所有者、inflight 位与 complete 顺序。 内核早期输出和用户 `uprintf` 使用不同代码路径。定位打印问题时,先判断是 `kprintf` 的直接早期 MMIO,还是 `uprintf -> IPC -> uart 服务` 的用户路径。 ## 12. 自检覆盖范围与故障排查 ### 12.1 PASS 能说明什么 当前 PASS 路径覆盖: - OpenSBI 到 S 态内核、页表启用和用户态进入; - 三个静态用户任务创建与轮转执行; - `uart` 的 MMIO 映射、NS16550A 初始化和轮询输出; - 服务注册/查找/等待; - init 到 echo 的请求与回复、来源 tid、长度和负载校验; - `uprintf` 的消息拆分发送路径。 正常启动时,init 会在打印 PASS 后调用 `task_exit`;当前自动脚本不单独断言退出后的资源状态。 它不能单独证明 IRQ 驱动路径、所有非法指针检查、长时间调度公平性、资源回收、SMP 或安全性。当前实现也没有这些未声明功能。 ### 12.2 常见问题 | 现象 | 检查方法 | | --- | --- | | `riscv64-unknown-elf-gcc: command not found` | 安装 `gcc-riscv64-unknown-elf`,检查 `CROSS_COMPILE` 是否多了或少了前缀 | | 默认 QEMU 路径不存在 | 用 `make QEMU=/usr/bin/qemu-system-riscv64 ... qemu` 覆盖,或确认本地 QEMU 11.1.1 路径 | | OpenSBI 文件不存在 | 用 `dpkg -L opensbi` 找到 `fw_dynamic.bin`,覆盖 `OPENSBI` | | GDB 显示连接拒绝 | 先运行 `make qemu-gdb` 并保持终端;确认监听端口与 `gdbinit` 都是 1234 | | `make check` 报缺失标记 | 阅读脚本打印的完整 QEMU 输出,再运行 `make qemu` 观察最早出现的 panic/trap/服务错误 | | 没有 `MK_SELF_TEST: PASS` | 检查 `uart`/`echo` 是否注册成功、init 是否找到 echo、请求回复 tid 是否为 2,以及是否发生异常退出 | | 用户符号看起来属于错误服务 | 所有服务链接地址相同;只加载当前任务对应的一个用户 ELF,并核对 tid | | 修改后旧镜像仍运行 | 执行 `make clean && make -j4`,确认 `.bin`、`.incbin` 对象和最终内核都重新生成 | ## 13. 设计边界与后续扩展 当前实现有意保持小而可观察,主要边界如下: 1. **单核固定模型**:QEMU `-smp 1`,其他 hart 停车,内核数据结构没有 SMP 并发保护; 2. **静态任务模型**:最多 8 个任务,启动时从嵌入 bin 创建,没有运行时 `fork`/`exec`; 3. **有限回收**:退出任务保留 `ZOMBIE` 控制块,页表、镜像和栈没有逐项回收; 4. **固定 IPC**:72 字节消息、48 字节负载、四项邮箱,无共享内存、零拷贝、大消息对象或请求 ID; 5. **简单同步 RPC**:无超时、取消、死锁检测、优先级继承和自动重连; 6. **简单调度**:单核轮转,无优先级、CPU 亲和性或实时保证; 7. **最小驱动授权**:MMIO/IRQ 权限来自静态镜像,不是可派生、可传递的通用 capability space; 8. **有限 FDT 支持**:只解析内存、ns16550a 串口和 PLIC 节点,未覆盖通用设备树与其它中断控制器; 9. **服务恢复未实现**:用户服务退出后没有自动重启、状态恢复和客户端重连; 10. **系统服务有限**:没有文件系统、虚拟文件接口、网络、动态加载器、POSIX 进程模型或用户堆管理。 后续扩展建议按依赖顺序进行: - 先实现任务退出资源回收、IPC 超时和服务崩溃通知; - 再实现服务重启/客户端重连、更多轮询与中断驱动及相应测试; - 在确有大数据需求时设计共享内存对象或授权缓冲区,并同步定义生命周期与权限; - 然后考虑运行时程序加载及其背后的文件/存储服务; - 最后再评估 SMP、优先级实时调度、复杂 capability 模型或形式化验证。 扩展时应保持微内核边界:**内核增加可验证的最小机制,用户服务承载可演化的策略。** 更深入的机制说明和成熟微内核对照见 [docs/microkernel.md](docs/microkernel.md)。