企业官网建设流程全解析

1. 为什么是caveman：一颗"够小但完整"的教学内核

1.1 从xv6、uCore到caveman：我为什么最终选了它

先说结论：如果你和我一样，不想一上来就被《操作系统导论》里几百页的进程调度、虚拟内存、文件系统劝退，只想在最短时间内亲手把一个内核从零跑起来，那么caveman这个"穴居人"项目会是一个非常合适的入口。

我最早接触的是MIT的xv6。说实话，xv6作为教学系统确实经典，riscv版用起来也很舒服，但它的目录里有kernel/、user/、mkfs/，还涉及文件系统镜像、用户态加载、系统调用表，对第一次写内核的人来说，有太多"不是内核本身"的复杂度。你明明只是想看"CPU怎么跳到我的代码、串口怎么吐字符"，结果先得折腾编译脚本和文件系统工具。

后来我也试过uCore、rCore这类更完整的教学OS。它们的中文文档确实很友好，但工程结构已经接近一个"真正的操作系统"，进程模型、内存管理、并发锁全都有，读起来容易陷入细节，反而看不清楚主线。

caveman这个名字起得很诚实——它就是一个"原始人"级别的内核。我拿到的这个工程总共就十几个文件，核心代码量大概千行以内，没有虚拟内存，没有文件系统，没有用户态进程，有的只是最朴素的那条链路：复位、链接、串口、中断、任务切换。但恰恰是这条链路，把"操作系统到底在干什么"讲明白了。如果你已经熟悉C语言和RISC-V汇编的基本指令，花一个周末把它跑通，收获会比翻十篇博客都大。

1.2 caveman的"最小可行性"边界：哪些有、哪些砍掉

我很喜欢这个项目的一点，是它对功能边界的克制。

它保留了五样东西：

• 串口输出模块，让内核能和外界说话；
• 时钟中断处理，让CPU能"到点做事"；
• 上下文切换，让多个任务能轮流用CPU；
• 极简的任务调度器，至少证明了"进程调度"不是玄学；
• 一段能讲清楚"固件如何把控制权交给我们"的启动代码。

它砍掉的也很果断：

• 没有虚拟内存，所有地址都是物理地址，省掉了页表、TLB、缺页异常这一整套东西；
• 没有用户态/内核态的完整切换，任务都跑在内核态，省掉了syscall设计和权限检查；
• 没有文件系统，省掉了磁盘驱动、inode、块缓存这些大头。

砍掉这些不是偷懒，而是刻意把"与硬件直接对话的最小闭环"暴露给你。我后来在调试更复杂的内核时，很多问题追根到底还是落在这条最小闭环上——栈没设对、中断没委托、上下文没保存完整。先把caveman啃下来，后面调试任何系统都能少走弯路。

2. 搭好交叉编译环境：工具链、目录结构与Makefile

2.1 riscv64-unknown-elf工具链的安装与验证

caveman的目标平台是64位RISC-V，所以我们不能在普通x86机器上直接编译，必须用交叉编译工具链。这里的工具链命名要认准：riscv64-unknown-elf-gcc，它不是Linux工具链，而是裸机工具链，不带glibc，只带newlib和最基本的启动文件。因为没有操作系统介入，你不需要动态链接器、不需要标准C库的完整实现，裸机工具链正好。

安装方式很简单，Debian/Ubuntu系可以直接：

sudo apt-get update sudo apt-get install gcc-riscv64-unknown-elf gdb-multiarch

如果你用的不是APT体系，也可以从bootlin工具链下载预编译包，解压后把bin/目录加进PATH。装完后验证一下：

riscv64-unknown-elf-gcc -v

看到gcc version X.X.X (x86_64-pc-linux-gnu)但target为riscv64就说明OK。

这里有个我自己踩过的坑：千万别用gcc-riscv64-linux-gnu替代。它是给Linux系统编译程序用的，会隐含链接glibc和Linux启动代码，编译裸机内核时会报一堆莫名其妙的undefined reference。工具链版本不用追新，稳定即可，我用的11.x和13.x都能编过。

2.2 Makefile的三层分工：编译、链接、运行

caveman的Makefile建议拆成三块功能：编译目标文件、链接成内核镜像、启动QEMU运行。这样职责清晰，调试时也容易定位问题。我整理的版本大概是这样的：

CROSS = riscv64-unknown-elf- CC = $(CROSS)gcc LD = $(CROSS)ld OBJCOPY = $(CROSS)objcopy CFLAGS = -march=rv64gc -mabi=lp64 -mcmodel=medany CFLAGS += -ffreestanding -nostdlib -fno-pic -fno-stack-protector CFLAGS += -Wall -Werror -O2 -g SRCS = start.s main.c uart.c trap.c timer.c task.c OBJS = $(SRCS:.c=.o) kernel.bin: kernel.elf $(OBJCOPY) -O binary kernel.elf kernel.bin kernel.elf: $(OBJS) $(LD) -T linker.ld -o kernel.elf $(OBJS) %.o: %.c $(CC) $(CFLAGS) -c $< -o $@ %.o: %.s $(CC) $(CFLAGS) -c $< -o $@ run: kernel.bin qemu-system-riscv64 -machine virt \ -bios default \ -kernel kernel.bin \ -nographic

几个关键点：

• -ffreestanding告诉编译器"这里没有标准库，你不要假设printf、memcpy这些是现成的"；
• -nostdlib让链接器不自动找libc；
• -mcmodel=medany允许代码用任意范围的PC相对寻址，后面细说；
• -bios default让QEMU自动加载OpenSBI，OpenSBI启动后会找到我们的内核入口。

2.3 一个关键的编译选项：为什么必须用 -mcmodel=medany

这个选项我从最开始就给大家标了重点。RISC-V的可执行文件模型分两种：medlow要求代码必须链接在2GB范围以内，PC相对跳转用短指令；medany则允许代码放在任意地址，通过auipc+addi组合完成寻址。

我们的内核要链接到0x80200000附近，这已经接近4GB边界了，用medlow编译时gcc会生成指令序列，在取指或访问全局变量时报"relocation truncated to fit: R_RISCV_HI20 against ..."之类的链接错误。我最初图省事没加这个参数，链接器直接给我一堆error，改成medany后整个世界清净了。这个选项对于那些要跑在树莓派、裸机开发板上的项目同样适用，先记住结论：裸机RISC-V内核起步就用-mcmodel=medany。

3. 从复位向量到C世界入口：链接脚本与SBI交接

3.1 链接脚本：把每一段放在该在的地方

在裸机环境里，没有操作系统帮你"安排"内存布局，必须自己告诉链接器代码放哪、数据放哪。caveman的linker.ld核心内容如下：

OUTPUT_ARCH(riscv) ENTRY(_start) BASE_ADDR = 0x80200000; SECTIONS { . = BASE_ADDR; .text : { *(.text._start) *(.text*) } .rodata : { *(.rodata*) } .data : { *(.data*) } .bss : { *(.bss*) } }

这里有个所有人都要理解的点：为什么内核入口是0x80200000而不是0x80000000？

QEMU的virt机器把物理内存起点定在0x80000000。当我们用-bios default启动时，OpenSBI固件会被放在0x80000000开始的位置，它承担了复位后最早期初始化的任务。OpenSBI运行完自己的初始化后，会跳到0x80200000这个地址，把控制权移交给我们编译出来的内核。所以如果你的链接脚本入口设成了0x80000000，运行时大概率会直接跑飞或者crash——因为那个地址已经被固件占用。

如果你不用OpenSBI、用-bios none加载裸内核，那么入口确实可以设成0x80000000，但你就得自己处理M态下的各种CSR初始化，反而失去了SBI带来的便利。教学内核通常都选择"站在OpenSBI肩膀上"，所以0x80200000是更合适的默认值。

3.2 复位那段汇编：_start到底做了什么

链接器通过ENTRY(_start)找到入口，那么_start那段汇编就是内核的"第一个呼吸"。caveman的start.s关键部分大概是这样的：

.section .text._start .globl _start _start: csrr a0, mhartid # 保存CPU核心编号 csrr a1, mstatus # 先保存M态状态 la sp, _stack_top # 设置栈指针 call clear_bss # 清零BSS段 call main loop: wfi j loop

你可能会问：main不是C函数吗，为什么前面要做这么多事？

因为C语言运行的三个基本前提是：栈可用的、BSS段已清零、全局指针寄存器就绪。la sp, _stack_top就是让CPU知道"你的临时舞台在哪"；clear_bss是遍历.bss段逐字节清零，否则未初始化全局变量里残留的旧数据会把程序搞挂。mhartid是RISC-V的硬件线程ID寄存器，多核情况下每个核都会走到_start，我们需要知道自己是几号核。

还有个细节：la sp, _stack_top用的地址必须在链接脚本里定义，比如_stack_top = 0x80208000;或者专门分配一个.stack段。如果你没分配栈或者栈指针设错，第一个函数调用就会把返回地址写到非法内存，然后整段崩溃。这是我见过最多的新手事故之一。

3.3 与OpenSBI的第一次握手：a0和a1的含义

启动一个运行在S模式的内核，_start进来时寄存器并不是空的。OpenSBI在跳转到0x80200000之前，会在寄存器里给你捎两样东西：

• a0 = hartid：当前CPU核心编号；
• a1 = dtb：设备树二进制地址，描述内存大小、外设位置等硬件信息。

虽然caveman这种极简内核心率上不会真的去解析DTB，但把这两个值保存下来是个好习惯。到了更复杂的项目，你要从DTB里读出串口地址、内存范围，就是从这一刻开始的。

我们后续代码如果想让OpenSBI帮忙打印字符、设置时钟，就要通过ecall进入M态调用SBI服务。以打印字符为例，把字符放a0，功能号放a7，然后ecall：

static inline void sbi_console_putchar(int ch) { register int a0 asm("a0") = ch; register int a7 asm("a7") = 1; asm volatile("ecall" : : "r"(a0), "r"(a7) : "memory"); }

第一次把这段代码跑通的时候，我盯着终端里冒出第一个字符，那种感觉和当年折腾单片机点亮LED差不多——你不是在用别人封装好的API，而是在最底层亲眼看着一行代码变成硬件上的电平变化。

4. 点亮第一块"屏幕"：QEMU串口上的Hello World

4.1 16550 UART的最小驱动：寄存器只有八个

在QEMU virt机器里，串口是一个标准的16550 UART，MMIO基址是0x10000000。这个外设很古老，但正因为古老，驱动反而简单。你只需要知道几个偏移量：

• 0x00：发送/接收数据寄存器（THR/RBR）；
• 0x05：线路状态寄存器（LSR），bit5为1表示发送缓冲区空。

轮询发送一个字符的代码就非常直接：

#define UART_BASE 0x10000000UL #define UART_THR (UART_BASE + 0x00) #define UART_LSR (UART_BASE + 0x05) static inline void uart_putc(char c) { while (((*(volatile uint8_t *)UART_LSR) & (1 << 5)) == 0) ; *(volatile uint8_t *)UART_THR = c; }

那个volatile非常重要。如果你不加，编译器优化时可能认为循环里读的地址"看起来没变"，把读操作优化成一次，导致死循环或者漏写。我在-O2下跑的时候遇到过这种诡异现象，去掉优化就好，加上volatile就稳了，原理就是告诉编译器"这个值随时可能被硬件改变，别给我瞎优化"。

4.2 printf的"丐版"实现：从%d到十六进制

裸机环境下没有stdio，想打印数字就得自己写。最省事的做法是只实现putchar和print_hex，需要打印寄存器值时转成十六进制。我学习时写过一个极简版本：

void print_hex(unsigned long val) { static const char hex[] = "0123456789abcdef"; int started = 0; for (int i = 15; i >= 0; i--) { char nibble = (val >> (i * 4)) & 0xf; if (nibble || started || i == 0) { started = 1; uart_putc(hex[nibble]); } } }

为什么先做hex而不是整数的%d？因为内核调试时最常看的就是地址、寄存器值、状态位，十六进制恰好能一位对四位，肉眼转换方便。真要用%d，就得处理负数、除法和取余，在RISC-V上除法指令是有的，但对一个教学内核来说，print_hex已经能覆盖95%的调试场景了。

我建议你把这个模块单独放一个uart.c文件，接口只暴露uart_putc、print_hex、print_str。后面所有模块通过这三个函数打印日志，一旦输出乱了，排查范围立刻缩小到串口驱动和调用点，不会满世界找bug。

4.3 验证输出：QEMU的串口重定向与退出

编出kernel.bin后，运行：

qemu-system-riscv64 -machine virt -bios default -kernel kernel.bin -nographic

-nographic有两个作用：把串口输出重定向到当前终端，同时把QEMU的监控交给stdio。如果你看到类似这样的输出：

caveman: booting on hart 0 caveman: dtb @ 0x87e00000 caveman: hello world

恭喜你，整个"从编译到运行"的链路已经通了。之后每次改动，这套验证路径都能帮你快速确认"我没把更早的东西弄坏"。

一个小技巧：QEMU里退出虚拟机不是Ctrl+C直接杀，而是先按Ctrl+A然后按X。如果不小心只按了Ctrl+C，有时会直接把QEMU进程终止，终端可能残留异常状态。记一次这个快捷键，调试体验会顺很多。

5. 让CPU学会"到点做事"：时钟中断与特权级切换

5.1 中断委托：为什么M态不直接处理，而要交给S态

RISC-V有M、S、U三个特权级。OpenSBI运行在M态，我们的caveman内核运行在S态。硬件定时器中断本来会进入M态，如果我们不加任何处理，每次时钟中断都得让OpenSBI的M态代码帮忙转发到S态，效率低且绕。更干净的做法是配置中断委托，让硬件直接把特定中断路由到S态。

RISC-V提供了mideleg（机器中断委托寄存器）和medeleg（机器异常委托寄存器）。我们要把S模式定时器中断（中断号5）委托给S态，只需要在初始化时写：

static inline void delegate_interrupts(void) { asm volatile("csrw mideleg, %0" ::"r"(1 << 5)); }

等等，这里有个大家容易搞混的地方。caveman是跑在S态的，为什么它能写mideleg？这是因为OpenSBI启动时把部分M态能力暴露给了S态，S态可以在mstatus.MPRV等约束下访问M态CSR吗？

不对，准确说，如果一个内核运行在S态，它本身不能直接写mideleg，只有M态代码才有权限。所以OpenSBI通常在启动早期就把中断委托配置好了。我们在caveman里写csrw mideleg的代码，要么是OpenSBI封装了SBI调用，要么我们在演示环境里通过M态跳转前执行的初始化代码来做。

实践上更常见的方法：OpenSBI默认就会把定时器中断委托给S态处理，所以我们在S态只需要配置S态的CSR：sie.STIE=1打开S模式定时器中断，sstatus.SIE=1打开S模式全局中断。而M态那侧，OpenSBI已经替我们代劳了。

用一个生活类比：M态就像前台保安，S态像经理。所有访客（硬件中断）本来要先找前台，前台登记后再汇报给经理。委托之后，相当于前台直接把某些访客放进经理办公室，省了中间传话。这个"传话"在系统里就是一次ecall往返，每次中断都来一次，性能上得不偿失。

5.2 从trap入口到C处理函数：那段保存现场的汇编

中断来了之后，CPU会把当前指令流打断，跳到stvec指向的地址。我们需要在这里保存现场，调C函数，再恢复现场。

RISC-V的通用寄存器有32个，保存它们的标准做法是把整个上下文压到栈上：

.section .text .globl trap_entry trap_entry: # 为上下文腾出空间 addi sp, sp, -256 sd x1, 0(sp) # ra sd x2, 8(sp) # sp # ... 逐个保存 x3~x31 csrr a0, scause csrr a1, sepc call handle_trap # 恢复现场 ld x1, 0(sp) # ... addi sp, sp, 256 sret

这个"保存-处理-恢复"模型一定要亲手写一遍。不写你永远体会不到一个问题：C函数调用约定里，ra（返回地址）是被调用者保存的，保存现场时必须把它压栈，否则中断处理里的函数调用会把ra覆盖，回到用户代码时程序就疯了。我在第一次跑多任务时遇到"任务A执行一会儿突然跳到别的地址乱飞"，最后用gdb查出来就是上下文保存少了几个关键寄存器。

5.3 定时器中断的初始化顺序：一种容易被忽略的"先使能后设置"

定时器中断初始化的顺序是新手最容易踩的坑。正确顺序大概是：

void timer_init(void) { // 1. 打开S模式定时器中断位 asm volatile("csrs sie, %0" ::"r"(1 << 5)); // 2. 设置下一个中断时间 set_timer_interval(TIMER_INTERVAL); // 3. 最后才打开全局中断 asm volatile("csrs sstatus, %0" ::"r"(1 << 1)); }

为什么顺序重要？如果你先把sstatus.SIE（全局中断）打开了，但定时器还没设置，OpenSBI和硬件里残留的旧定时配置可能会立刻产生一个中断。这个中断触发后，你的处理函数还没准备好，于是一边初始化一边被打断，轻则打印一堆乱序日志，重则直接死循环。

还有一种更狠的坑是：定时器中断处理函数里没有重新设置下一次中断时间，导致中断一触发马上又触发，形成中断风暴，整个系统看起来就像死机。怎么判断是中断风暴？串口上如果有办法打印计数，会发现数字疯狂滚动。如果没有打印，一个快速判断是：在中断处理函数里加一个空循环，看系统是否"稍微慢一点但还是死"。实际我遇到过的情况是，qemu的-gdb挂上去，单步执行发现反复进入trap_entry，基本就能断定是没重新武装定时器。

void handle_trap(uint64_t scause, uint64_t sepc) { if (scause == 0x8000000000000005UL) { // S-mode timer interrupt timer_tick(); set_timer_interval(TIMER_INTERVAL); // 必须重新武装 } else { print_str("unknown trap: "); print_hex(scause); print_str("\n"); while (1); } }

scause的最高位如果是1，表示这是中断；低位的5对应S模式定时器中断。新手往往会忘记检查最高位，把中断号和异常号混淆，导致永远匹配不上。

6. 三个任务轮转：一个极简调度器的完整实现

6.1 任务控制块：内核里最小的一张"身份证"

进程调度听起来高大上，其实在caveman这种没有任何内存保护的内核里，实现可以极其朴素。每个任务只需要一张"身份证"，记录它自己的栈和上下文。任务控制块的定义可以简化为：

struct task { uint64_t sp; // 内核栈指针 uint64_t ra; // 返回地址 uint64_t counter; // 剩余运行时间片 uint64_t priority; char name[16]; };

为什么核心字段是栈指针和返回地址？

因为当任务A切换到任务B时，我们其实做的事情是：保存A的寄存器到A的上下文，把B的上下文恢复到CPU寄存器里。而B的"上周目"在哪里被打断、下一步要执行哪条指令，这个信息就藏在它栈顶的ra里。所以任务切换本质上是"换栈+换ra"，这是一切调度的地基。

栈的分配也比较直接，给每个任务一块独立的内存区域就行：

// 栈区在链接脚本里预留，或直接开一个全局数组 static char task_stacks[MAX_TASKS][STACK_SIZE];

因为caveman没有用户态，任务都共享地址空间，所以你不需要处理页表切换。这也是我说它"最小但完整"的原因——你能看到调度器的骨干，而不被内存管理的枝叶遮挡。

6.2 时钟中断里完成上下文切换：switch_to的"五步"

在caveman里，任务切换的触发点是时钟中断。每次timer_tick后，调度器会判断当前任务时间片是否用尽，用尽就换人。关键的switch_to用汇编实现，伪代码流程是：

switch_to: # 1. 保存当前任务的通用寄存器到当前task的栈上/上下文数组 sd ra, 0(sp) sd sp, 8(sp) # ... 保存其他寄存器 # 2. 把当前的sp保存到当前task结构体 sd sp, task_current.sp # 3. 从task_next取新的sp ld sp, task_next.sp # 4. 从新栈里恢复新任务的寄存器 ld ra, 0(sp) ld sp, 8(sp) # ... 恢复其他寄存器 # 5. 用ret返回 ret

每次切换发生在中断处理函数里，所以保存现场要小心。一个我反复提醒自己的点是：中断处理函数里我们已经在trap_entry保存过"被打断任务的现场"了，调度器再用switch_to做一次"任务级现场保存"，两层现场是叠在一起的。如果哪天你发现切换后任务状态错乱，先检查trap_entry的帧大小和switch_to的保存范围是不是重复覆盖了。

三个任务轮转的效果大概是：

taskA: tick 1 taskB: tick 1 taskC: tick 1 taskA: tick 2 taskB: tick 2 ...

如果时间片设置太短，串口输出会频繁切换、吞吐极低；如果太长，又看不出"并发"效果。我实测下来，每个任务跑200个tick左右的量级比较舒服，既不闪烁又能明显看到轮转顺序。

6.3 实测三个任务的输出顺序与"卡死"现象

实现完调度器后，我写了三个任务函数，每个函数里循环打印自己的名字。第一次运行输出是正常轮转的，但第二次运行却卡死在某一次切换上了。排查过程很有意思：

一开始我怀疑是任务函数没返回，导致ra被覆盖。每个任务函数确实应该是个死循环，不应该返回，但这不构成卡死原因。后来我加了一个调试打印，把每次切换前后task_current.sp和task_next.sp的值打出来，发现某次切换后sp变成了一个明显越界的地址，才知道是一个任务的栈分配太小，任务函数里的局部数组越界写坏了自己的栈，导致后续切换从坏地址里取数据。

这就是裸机调试最痛苦也最有意思的地方：没有操作系统帮你拦非法内存访问，一切错误都会以"莫名其妙死机"的形式呈现。不过有了串口打印和hex输出这两个武器，大多数问题都能靠二分法定位——哪一行打印是最后一条存在的，问题就在那之后。

7. 编译、链接、运行中的常见问题与排查路径

7.1 高频问题汇总表

我把这段时间折腾caveman遇到的典型问题整理成一张表，按"症状-根因-解法"列出：

这里面有一半以上都是我第一次写时踩过的。每一个问题背后的教训其实都可以归结为一句话：裸机世界里没有默认值，所有寄存器、所有内存地址、所有栈都必须由你明确指定。

7.2 一次"看起来像死机"的调试：原来是中断风暴

我想单独讲一次调试经历，因为它的排查方法可以复用到很多场合。

现象：给caveman加了定时器中断后，系统启动后串口只打印了两行，然后就完全没反应。按任何键都没用，只能强制退出QEMU。

第一反应是"任务调度死锁了"，因为刚加入调度器。但我关掉定时器、只保留手动切换时，系统一切正常。这就把范围缩小到定时器中断链路。

然后我在trap_entry入口处加了一个计数器打印，每进一次中断就打印一次scause。结果终端瞬间被相同的中断号刷屏，说明不是死锁，而是中断反复触发。再去看timer的处理代码，发现我确实设了set_timer_interval，但是把它放在了handle_trap里的中断处理分支之后、却没有在正常路径上执行到——因为那个分支里的if条件写错了，把scause的最高位忽略了，导致定时器分支永远进不去，也就永远没有重新设置下一次中断时间。改掉条件后，输出立刻正常。

这次调试留给我的经验是：裸机开发，打印日志是最后一道防线，而且日志要放在"入口处"而不是"处理完"的地方。只打"处理完"的日志，遇到中断风暴时你会看到大量重复输出，但看不到风暴的源头；在入口处打一次scause，就能判断出中断类型和频率，快速锁定方向。

7.3 给初学者的三条实用建议

这段纯属个人主观经验，但我认为比任何教程都值钱。

第一，先跑通串口，再碰中断。串口是调试的"眼睛"，没有眼睛，后面所有问题都会变成盲人摸象。哪怕你时间再紧，也要把uart_putc这个最小闭环跑通再说。

第二，每次只改一个CSR，然后立刻验证。RISC-V特权指令里CSR与CSR之间常常有依赖关系，比如mideleg和sie、sstatus之间就互相影响。一次改三个寄存器，出问题就不知道是哪个寄存器写错了。我的做法是，每改一个就编译运行，打印出该CSR的当前值确认无误，再改下一个。

第三，用GDB配合QEMU调试，而不是纯靠print。QEMU支持-s -S参数，可以配合gdb-multiarch做源码级调试。比如你要确认某一次任务切换时sp的值，用gdb在switch_to处打断点看寄存器，通常比print更快、更准。print适合观察"发生了什么事"，gdb适合观察"某一刻的精确状态"，两者都用，事半功倍。

最后再留一个小技巧：把QEMU运行参数里的-nographic换成-display none -serial stdio，输出行为基本一样，但如果你后面要在同一终端里跑其他调试工具，终端控制会更干净。这个细节我也是在做了十几次实验后才发现的，像caveman这种教学内核，真正让你成长的不是最后跑起来的那一刹那，而是从第一行汇编到第一个调度器之间反复排查的过程。把这些边角都磨一遍，你收获的就不只是"跑通了一个项目"，而是"我能在最底层自己解决问题"的底气。