RISC-V裸机NAS实战：OpenSBI引导+C++17异步运行时

如果你最近也在折腾 RISC-V 开发板，大概率见过 OpenSBI 这个词。我这次的目的是完全不用现成 Linux，直接在 OpenSBI 引导后跑一套自写的 C++17 异步运行时，再把 FAT 文件系统、TCP/IP 协议栈和 FTP/HTTP 服务叠上去，做一个只服务内网的嵌入式专有 NAS。整个过程从烧录固件到跑通 7MB/s 的 FTP 下载，前后折腾了三周，其中一半时间都花在“为什么没输出”和“为什么连接就断”这类问题上。

这篇记录适合两种人：一种是手里已经有 RISC-V 板子、想过从固件层面自己搞点东西的开发；另一种是被各种启动流程绕晕、想找我这种已经踩过坑的人要一份直白路线图的入门者。我不会把每个寄存器的值都背给你们，但会给出我认为最重要的取舍逻辑和调试方法，尽量让文档里查不到的那些经验一次性讲透。

1. 项目概述：一块 RISC-V 板的自托管 NAS

1.1 项目目标和最原始的动机

做这个项目的起因很简单：手头有一块 4 核 RISC-V SoC 的开发板，标称 800MHz，板上带了千兆 PHY 的 PCB 焊盘、两个 USB 和 SD 卡槽，但官方 SDK 基本都是 Linux 或者裸机 Hello World。我想验证一下：在没有 MMU 之后的内存管理、没有现成操作系统的情况下，能不能靠一个自写的运行时把网络存储服务跑起来？

这个目标听起来有点反常规。NAS 这种产品在商业方案里几乎都用完整 Linux + Samba，我做纯裸机方案并不是为了替代产品，而是想确认一条“从 OpenSBI 到业务代码”的最小链路到底有多复杂。实测下来，复杂度比我预想的高一截，但也没高到不可完成。整个过程涉及四块内容：OpenSBI 引导、C++17 运行时、文件系统、TCP/IP 协议栈。任何一块单独拿出来都能写几篇，合在一起就非常考验人的排错顺序感。

我也对这块板的定位有个默认假设：不指望它做多盘 RAID，也不指望多用户并发读写。它就是一个放在家里、只绑定内网 IP 的备份节点，随手扔几个文件进去，能在局域网里用 FTP 拉出来就行。这个定位直接决定了我后面很多设计选择，比如没有上 SMB、没有实现磁盘阵列、没有做多核负载均衡。

1.2 系统分层与选型逻辑

从开机到文件下载，实际数据流向是这样的：板子通电后，固化 ROM 先做基本初始化，然后把 OpenSBI 从 SPI Flash 拷贝到 DDR 指定位置并跳转；OpenSBI 完成机器态环境初始化，跳转到我的应用固件；应用固件以 S 模式运行，负责所有驱动、协议栈和业务逻辑。

具体分层如下表：

这个分层最大的优势是“每层都能独立验证”。OpenSBI 起来后，先验证 SBI 的 putchar 可以打字符；再把 UART 驱动调通；然后才是文件系统和网络。如果你跳过中间验证直接往上层堆代码，出了问题根本不知道是硬件初始化不对还是文件系统回调没触发。

选型上我也做了几个很实际的判断题：文件系统用 FatFs 而不是 ext4，因为裸机下 ext4 的复杂度太高，而 FatFs 单片就能搞定，移植资料也最多；网络协议栈用 lwIP 而不是自己写 TCP，因为 TCP 的丢包重传、窗口管理、超时定时器这些细节自己写要命；NAS 协议先用 FTP 和 HTTP，不做 SMB，因为 SMB 的状态机复杂度对裸机环境极不友好。这些选择都会在后面的章节具体展开。

2. OpenSBI 引导：从开机到第一个检查点

2.1 编译固件和选择跳转策略

OpenSBI 最常见的用法是作为 M 模式固件，替 S 模式准备好环境后，再跳到你的内核或裸机程序。它对外暴露一套 SBI 系统调用接口，包括定时器、IPI、远程内存栅栏、系统复位等。我的应用跑在 S 模式，所以和 OpenSBI 的关系非常明确：需要特权操作时，用ecall陷到 M 模式让它处理。

OpenSBI 有三种固件模式：FW_JUMP、FW_PAYLOAD、FW_DYNAMIC。这里我选FW_JUMP，因为它最干净：OpenSBI 完成初始化后直接跳到预设地址，跳转目标不被打包进 OpenSBI 镜像。这样开发和调试应用时，只需要重新烧应用固件，不用每次都重新生成 OpenSBI，省掉了很多重复劳动。

编译 OpenSBI 时我用的配置大致如下：

make CROSS_COMPILE=riscv64-linux-gnu- \ PLATFORM=generic \ FW_TEXT_START=0x80000000 \ FW_JUMP_ADDR=0x80200000 \ -j16

FW_TEXT_START是 OpenSBI 自己的加载地址，FW_JUMP_ADDR是它初始化完成后跳转的目标地址。我这里把应用入口固定放在0x80200000，这是 QEMU virt 平台上内核默认的加载点，也符合这块板子的 DDR 地址布局。如果你的板子内存基址不同，一定要查手册，别照抄这个数字。

每次编译完会得到build/platform/generic/firmware/fw_jump.bin。 在没有真实硬件的情况下，建议先用 QEMU 验证流程：

qemu-system-riscv64 -M virt -m 1G -smp 4 \ -bios fw_jump.bin -kernel app.bin \ -serial mon:stdio -display none

QEMU 能模拟部分裸机行为，尤其是 OpenSBI 跳转后的第一个打印，在 QEMU 上通了对后面真板调试帮助极大。我要提醒一句：QEMU 和真实 SoC 的差异主要在外设，启动顺序这部分几乎一致，所以把 QEMU 当作“启动检查器”非常划算。

2.2 最小 S 模式程序的启动汇编和链接脚本

OpenSBI 跳转时，a0是当前 hart id，a1是指向设备树二进制的指针。很多教程会忽略这两个寄存器，但它们在裸机环境里非常关键，尤其是我后面想识别“当前核是不是 CPU0”时，直接读a0保存到全局变量就行，否则还得通过 SBI 调用去查。

S 模式的第一个程序，我不建议上来就写 C++，而是先写一个最小 C 程序配启动汇编。原因是启动汇编决定了栈、BSS、全局构造函数这些运行时的地基，这些地方出了问题，C++ 根本跑不起来，而且报错方式通常是“完全没输出”。

最小启动汇编长这样：

.section .text.init,"ax" .globl _start _start: la sp, __stack_top la t0, __bss_start la t1, __bss_end 1: bgeu t0, t1, 2f sd zero, 0(t0) addi t0, t0, 8 j 1b 2: call _init_ctors call main 3: wfi j 3b

_init_ctors遍历.init_array，把全局对象的构造函数全部跑一遍。这在 C++ 里是必修课，很多裸机 C++ 程序“看起来启动了但全局对象全没初始化”，就是因为没做这一步。

对应的链接脚本简化后如下：

OUTPUT_ARCH(riscv) ENTRY(_start) MEMORY { RAM (rwxa) : ORIGIN = 0x80200000, LENGTH = 256M } SECTIONS { .text : ALIGN(4) { KEEP(*(.text.init)) *(.text .text.*) } > RAM .rodata : ALIGN(4) { *(.rodata .rodata.*) } > RAM .data : ALIGN(4) { __data_start = .; *(.data .data.*) __init_array_start = .; KEEP(*(.init_array*)) __init_array_end = .; } > RAM .bss : ALIGN(4) { __bss_start = .; *(.bss .bss.*) __bss_end = .; } > RAM __stack_top = ORIGIN(RAM) + LENGTH(RAM); }

这里有两个细节容易出事：一是.init_array必须放在可写段里，有些工具链默认放.text.init_array，如果链接脚本没有包含它，构造函数就不会被调用；二是栈顶放在内存尾部会自然向下增长，如果你在 BM 系统里同时放了很多大数组，要估算栈用量，我因为这个吃过大亏，后面内存溢出问题里会细说。

2.3 引导阶段我踩过的几个大坑

第一个坑是“S 模式访问 M 模式寄存器”。OpenSBI 已经把 CPU 切换到 S 模式，我在早期代码里手贱去读mhartid，结果直接异常。后来才意识到，OpenSBI 跳转时给的a0就是 hart id，正确做法是启动汇编里老实保存它，而不是去访问权限之外的 CSR。

第二个坑更隐蔽：S 模式的 trap vector 默认是 0。程序一旦发生未处理异常，CPU 会跳到零地址开始“执行”，结果就是你看到程序像死了一样，没有任何日志。后来我在启动流程里手动设置stvec，指向一个简单的异常打印函数，再配合sepc寄存器来定位出错指令。这一步对后续开发效率提升极大，强烈建议所有裸机 RISC-V 项目都把 trap dump 放在第一优先级。

第三个坑是“输出方式”。OpenSBI 提供了 legacy console 扩展，可以用ecall打字符，速度慢但稳定；一旦我的 UART 驱动还没写好，这个功能就是救命稻草。一个很实用的策略是：早期全部通过 SBI console 打日志，等到 UART 驱动调通后再切换回直接操作寄存器，但把 SBI console 作为 panic 时的兜底输出保留。

3. C++17 异步运行时：裸机上的“操作系统替身”

3.1 工具链与编译参数怎么配

项目要跑 C++17，但没有 Linux，没有 libc 的完整环境。工具链我选的是裸机版本的 RISC-V GCC，编译时关键参数如下：

riscv64-unknown-elf-g++ \ -march=rv64gc -mabi=lp64d -mcmodel=medany \ -ffreestanding -fno-rtti -fno-exceptions \ -fno-threadsafe-statics -fno-use-cxa-atexit \ -nostdlib -nostartfiles -std=c++17 -O2 \ -T linker.ld -Wl,--gc-sections -c main.cpp

-mcmodel=medany主要是让代码可以放到链接地址附近的任意位置，避免中大型程序链接时出现高 16 位地址溢出问题。-fno-exceptions和-fno-rtti可以砍掉大量运行时开销，C++ 裸机项目没有异常展开表的环境，开启异常等于给自己埋雷。-fno-use-cxa-atexit是避免链接器引用__cxa_atexit这类 C++ 运行时符号，这些在裸机上默认不存在，需要额外实现。

如果你的工具链带 newlib，可以链接进去用标准库的malloc和部分字符串函数；如果完全-nostdlib，那memcpy、strlen这些都要自己实现或者至少链接时给个桩。我这里用了 newlib，但只启用其中很小一部分，后面内存堆的配置也需要配合 newlib 的sbrk实现。

3.2 运行时初始化：全局构造、栈、堆、异常辅助函数

C++ 程序在进入main前要完成的事情比 C 多。核心顺序：

1. 从 OpenSBI 接收a0/a1并保存；
2. 设置栈指针；
3. 清理 BSS；
4. 调用.init_array里的全局构造器；
5. 调用main。

全局构造器遍历的汇编我已经在上一节给了。这里再补一个问题：销毁顺序。项目里我直接用-fno-use-cxa-atexit，也就是说环境不支持退出时的析构。这在嵌入式裸机里完全合理，因为这个系统根本没有正常退出路径，只有复位和断电。

异常辅助函数也不能缺。最简单环境下，你至少要有这么几个符号，否则链接会失败：

extern "C" void __cxa_pure_virtual() { for (;;) {} } extern "C" void _exit(int) { for (;;) {} } extern "C" void __stack_chk_fail() { for (;;) {} }

这些函数的核心思想就一句话：出问题就“死给看”。嵌入式系统没有进程这个概念，崩溃后最好让看门狗复位，而不是停在未定义状态。

堆的设置也很容易翻车。newlib 提供_sbrk来向操作系统申请内存，在裸机环境下没有操作系统，所以你要自己实现一个极简的堆指针递增函数：

extern char _heap_start; extern char _heap_end; void *_sbrk(ptrdiff_t incr) { static char *heap_ptr = &_heap_start; char *base = heap_ptr; if (heap_ptr + incr > &_heap_end) { return (void *)-1; } heap_ptr += incr; return base; }

然后链接脚本里把_heap_start和_heap_end标出来，放在 BSS 之后、栈底之前。堆和栈共用一块内存时，最好给栈留足空间；我一开始把堆设得特别大，结果某次深递归导致栈越界，直接覆盖了堆顶的数据，查了半天才定位到是 linker script 里没有预留栈保护边界。

3.3 事件循环和任务调度器：一个最小能用的异步骨架

所谓“C++17 异步运行时”，落到裸机上最核心的不是协程，而是一个“事件循环 + 任务队列”的模型。模块之间的交互方式很简单：中断只负责置标志位和提交任务，真正的协议解析和文件读写都在主循环里完成。

我用 C++17 写了一个很窄的调度器骨架：

#include <deque> #include <functional> #include <cstdint> class TaskRunner { public: void post(std::function<void()> task) { queue_.push_back(std::move(task)); } void run() { while (running_) { processTaskQueue(); processNetwork(); processTimers(); } } private: void processTaskQueue() { while (!queue_.empty()) { auto task = std::move(queue_.front()); queue_.pop_front(); task(); } } std::deque<std::function<void()>> queue_; bool running_ = true; };

看起来非常简单，但实际工程里要严谨得多。主要有三个问题：第一是任务队列无限增长，如果网络中断不断产生新任务，而主循环处理不过来，内存很快耗尽。我加了一个“背压”机制，当队列深度超过 64，就暂时不再从网卡中断里继续投递读事件，等队列消化到低于阈值再重启，否则只能眼睁睁看内存撑爆。

第二是定时器。lwIP 处理 TCP 超时重传需要定时回调，我的做法是在 TaskRunner 里维护一个按到期时间排序的最小堆，每次算好离最近定时器的剩余毫秒数，传给后面的poll作为等待超时。这样网络事件、任务队列、定时器三者在同一个线程里被统一驱动，不会出现某个模块饿死的情况。

第三是中断上下文和主循环的竞态。RISC-V 的中断如果不加临界区，中断处理函数里访问队列时，主循环也在操作同一个队列，就会出问题。最简单的方案是在中断入口关掉全局中断，或者用无锁的 ring buffer；我早期图省事直接disable_irq_save/enable_irq_restore，实测在 100MHz 外设中断频率下没有明显性能损失，所以就保留了关中断的做法。

3.4 多核与中断：先单核跑通的务实选择

这块板子有 4 个核，看起来很适合做真并行，但裸机做 SMP 意味着要处理跨核 IPI、核间任务分发、锁的管理，以及 OpenSBI IPI 扩展的正确调用。我权衡之后决定第一版只在 CPU0 上跑所有任务，其他核通过 WFI 休眠。理由很简单：NAS 这类 IO 密集场景，瓶颈在网络和存储，不在 CPU 算力；单核先把逻辑理顺，比四核乱成一锅粥有价值得多。

中断初始化也踩了一个典型坑：RISC-V S 模式要收到外设中断，除了要设置 PLIC 的优先级和使能位，还必须在sie里打开外部中断使能位，最后还要开全局sstatus.SIE。我一开始只配了 PLIC，发现网卡中断完全不触发，后来翻芯片手册才看到sie没设置。这类问题在 RISC-V 上尤其常见，因为 PLIC 和 CSR 各管一段，哪个漏了都不行。

4. 文件系统与 NAS 服务：从 SD 卡到 FTP/HTTP

4.1 SD 卡驱动和 FatFs 移植

存储介质的选择上，我一开始图省心用 SPI 模式读 SD 卡，以为能避开 SDIO 时序的复杂度，实际被现实打了脸：SPI 模式读大文件速度只有几百 KB/s，而且有的卡写入时 CRC 校验老不过。后来老老实实切回 SD 4-bit 模式，访问 SDHCI 控制器寄存器，配 DMA，速度一下就上来了。

SDHCI 驱动本身不复杂，无非是卡初始化、命令发送、数据传输。真正麻烦的是 DMA 缓冲区的物理地址对齐和 cache 一致性问题。我出现过一个很经典的现象：第一次读数据正常，第二次读到一半数据全是老数据，怀疑是 cache 没刷。解决方式是每次 DMA 传出之前，对目标 buffer 做一次 cache clean，DMA 完成后做一次 invalidate。如果你的 SoC 把 DMA 描述符和 buffer 放在非 cacheable 区域，可以不处理，否则这一项必踩。

FatFs 移植需要实现底层 diskio 接口：

FatFs 的扇区缓存机制会在写操作时先缓存再回写，所以要把f_sync放到关键操作之后。尤其在 NAS 场景，掉电瞬间如果有数据还停留在 FatFs 的缓冲区，FAT 表损坏几率极高。我后来在每次 FTP 文件关闭后强制f_sync，目录项修改后也同步一次，才把掉电损坏概率降下来。

4.2 为什么没有直接上 SMB：协议选择思考

很多人一听 NAS 第一反应是 SMB，也就是 Windows 网络共享。但 SMB 协议远不止“开个共享”那么简单：协商、认证、会话建立、文件句柄语义、锁、ACL、断线重连，这些状态机在裸机上实现一遍，开发量基本等于再写一个操作系统模块。我用 lwIP 的 RAW API 做 SMB，光是 SMB2 的帧格式就能让人崩溃。

所以这个项目的 NAS 服务是“专有”的，意思是面向自己的设备，而不是为了兼容所有操作系统。我实际做的是：

• FTP：老牌协议，用来在内网做文件上传下载，Windows、手机文件管理器都能直接连；
• HTTP：只读目录浏览 + Range 请求，浏览器打开直接看视频，拖动进度条可以触发分段请求。

这两个协议加起来的复杂度不到 SMB 的十分之一，效果却完全满足家用备份需求。如果你需要 Windows 原生网络驱动器映射，那还是老老实实上 Linux + Samba，这才是专业 NAS 的路。

4.3 让 FTP 和 HTTP Range 跑起来

FTP 的实现核心不是命令解析，而是主动模式和被动模式的数据连接差异。我一开始只做了主动模式的接收，结果在办公室里换个网络就取不到文件，因为主动模式要求服务器主动连接客户端，中间夹着路由器防火墙基本就废了。后来默认用被动模式：客户端从命令通道告诉服务器一个 IP 和端口，服务器在这个监听端口上等客户端来连，等数据连接建立后再传文件。

协议层的最小实现是这样：

HTTP 那边更简单，监听 80 端口，解析 GET 请求路径，通过 FatFs 打开对应文件，返回Content-Length和Accept-Ranges: bytes，然后根据Range头决定从哪个偏移开始发数据。

4.4 异步状态机如何服务多个连接

这里是最容易写崩的地方。FTP 的数据连接创建后，文件读取不能阻塞主循环。如果我在回调里直接调用f_read然后等它完成，FATFS 在大文件读满一个扇区之前可能阻塞几十毫秒，这段时间网卡事件、控制连接、其他客户端全部卡住。

我的解法是给每个文件传输会话维护一个状态机：

struct FileTransferSession { enum class State { Idle, Opening, Reading, DmaInFlight, Sending, Closing }; State state = State::Idle; FIL file; tcp_pcb *data_pcb = nullptr; uint8_t *buffer = nullptr; size_t file_offset = 0; volatile bool dma_done = false; };

流程是：FTP 收到 RETR 后，会话进入 Opening，打开 FatFs 文件，然后发起点读请求；SD 卡的 DMA 完成中断触发后，把 dma_done 置位，主循环检测到后把数据交给 lwIP 的tcp_write，同时发起下一段读取。这样做的好处是文件 IO 等待时间被 DMA 中断消耗掉，主循环始终能响应其他网络事件。

实际吞吐数据：纯轮询方式下 FTP 下载只有 3.5MB/s 左右，切到 DMA 中断驱动后提升到 7.2MB/s，瓶颈变成了百兆以太网的物理上限，基本满意了。

4.5 传输性能数据：实现进度和瓶颈

项目最终在真板上跑出来的典型数据如下：

瓶颈主要在三处：百兆以太网本身限制了峰值；SD 卡在 FatFs 写文件时要分配簇，随机写入速度上不去；FTP 每个 RETR 都要重新创建数据连接，小文件的握手开销远大于传输本身。

5. 稳定性、性能与踩坑速查表

5.1 稳定性措施：看门狗和掉电保护

裸机 NAS 最怕什么？固件死循环。没有操作系统，没有 kernel panic，一个指针越界就可能让系统卡死，而且卡死时连网线都是通的但服务没响应。所以我在主循环里加了一个简单的软看门狗机制：每次事件循环处理完一批任务后喂狗，如果 Watchdog 超时没被喂到，自动触发系统复位。配合 OpenSBI 的系统复位扩展，panic 后可以立刻重启，而不是永远挂在那里。

掉电保护方面，除了前面提到的f_sync，我还在写文件的流程里安排了“先写临时文件、再改名”的策略。FTP 上传时先写.tmp文件，文件和数据连接都正常关闭后再f_rename成最终名字，这样即使中途断电，目录里最多残留一个临时文件，不会看到半截文件被当做好文件。

5.2 常见问题速查表

5.3 一个实验时的额外体会

最后说一个我自己反复确认过的建议：这种自制 NAS 不要当作唯一存储，尤其不要放重要照片。文件系统、掉电保护、坏块管理这些东西单靠裸机程序很难做到商业水平，我的这台“专有 NAS”定位就是临时中转和实验平台。但如果你的目的和我的类似，是为了把 RISC-V 从固件到网络服务的完整链路走通，那这一套折腾绝对值得。链路打通之后再回头读 OpenSBI 源码、看 lwIP 的 RAW API 实现，感觉和原来对着文档猜完全不同，至少每个模块的真实工作路径已经在脑子里能串联起来了。