RIOT OS native32 板卡详解:在 32 位主机上以进程方式运行完整物联网软件栈
RIOT OS native32 板卡详解:在 32 位主机上以进程方式运行完整物联网软件栈
RIOT 的 native 系列板卡通过系统调用与信号在 API 层模拟硬件,使开发者无需任何嵌入式硬件,即可把完整的 RIOT 软件栈编译为 *NIX 系统上的普通进程直接运行。本文以 boards/native32/doc.md 为核心,结合 boards/common/native/doc.md 及仓库源码,系统讲解 native32 板卡的定位、环境准备、构建运行方式、运行时配置与源码级实现原理,帮助你在 32 位主机(或通过多库交叉编译的 64 位主机)上完成 RIOT 应用的开发、调试与网络协议实验。
native32 板卡是什么
RIOT 提供了一组特殊的 "native" 板卡,它们并不对应任何真实物理硬件,而是把宿主机本身当作一块开发板:
The RIOT native boards use system calls and signals to emulate hardware at the API level. That means that you can compile the complete RIOT software stack for your *NIX system and run it as a process.
也就是说,native 板卡是调用级(call level)硬件模拟——boards/common/native/include/board.h 中的注释明确写道 "The native boards use call level hardware simulation"。RIOT 的外设抽象层(periph)与内核原语被直接映射到宿主机的系统调用上,因此编译产物就是一个可执行的进程,而非烧写到芯片上的固件镜像。
native 系列包含两个变体:
| 变体 | 编译目标 | 适用场景 |
|---|---|---|
BOARD=native32 |
32 位可执行文件 | 32 位主机,或在 64 位主机上交叉编译 32 位程序 |
BOARD=native64 |
64 位可执行文件 | 64 位主机(推荐) |
BOARD=native |
自动选择 | 根据宿主平台架构自动选择 native32 或 native64 |
从 boards/native32/Makefile.features 可以看到 native32 的定义方式:设置 CPU = native、提供 arch_32bit 特性并声明 NATIVE_ARCH_BIT = 32,随后引入 common/native 的公共配置。而其 Makefile 仅有三行——声明 MODULE = board 并把 $(RIOTBOARD)/common/native 纳入构建目录,说明 native32 的所有实质逻辑都复用于 common 层。
值得注意的是,BOARD=native 会自动选择正确变体。文档明确建议:64 位系统上优先使用 BOARD=native64,native32 更多用于需要 32 位二进制(例如模拟 32 位 MCU 的寻址模型、测试 32 位专用代码路径或复用 32 位库)的场景。
为什么要在宿主机上"跑板卡"
boards/common/native/doc.md 给出了三个典型动机:
- 没有硬件也能体验 RIOT:手头没有任何受支持的开发板时,依然可以完整编译、运行和交互;
- 无硬件约束的开发与调试:开发 RIOT 应用或修改 RIOT 内核本身时,可以在主机上用 gdb/lldb、valgrind 等成熟工具调试,免去烧录、串口、JTAG 等硬件调试的繁琐;
- 在受控环境中做网络协议实验:借助 tap 虚拟网卡在主机上搭建多个 RIOT 实例组成的虚拟网络,验证路由、CoAP、6LoWPAN 等协议栈行为。
native 板卡在 "硬件" 层面模拟的内容(摘自 common/native doc):
- CPU / RAM:宿主机 CPU 与内存;
- Flash:程序执行部分使用宿主文件系统;drivers/periph_flashpage 的 flashpage 则是在 RAM 中模拟;
- 网络:Tap 接口(虚拟网卡);
- UART:运行时配置,支持
/dev/tty*; - 定时器:宿主定时器;RTC 默认使用宿主机
UTC时间; - LED:一红一绿两盏,状态变化直接打印到 UART 输出;
- PWM / QDEC:哑 PWM(dummy),QDEC 按 PWM 方式模拟;
- SPI / GPIO(仅 Linux):运行时配置,分别支持
/dev/spidev*与/dev/gpiochip*。
这些外设特性在 boards/common/native/Makefile.features 中以 FEATURES_PROVIDED 声明,包括 periph_rtc、periph_rtc_ms、periph_timer、periph_uart、periph_gpio、periph_pwm、periph_qdec,以及 motor_driver 和 netif_ethernet——这也是 native 板卡上 periph_* 模块默认可用的根源。
环境准备:32 位交叉编译依赖
由于 native32 要生成 32 位可执行文件,在 64 位宿主机上需要额外的多库(multilib)支持。文档给出的 Debian/Ubuntu 安装命令:
sudo apt install gcc-multilib g++-multilib lib32asan5
参数说明:
gcc-multilib:必装,提供 32 位 C 编译与链接支持;g++-multilib:仅当需要 C++ 支持时安装(例如使用 C++ 编写的应用或依赖 C++ 的软件包);lib32asan5:32 位 AddressSanitizer 运行库,用于 32 位二进制的单元测试(unittest)执行。
这一依赖关系在构建系统中也有印证:makefiles/arch/native.inc.mk 根据 NATIVE_ARCH_BIT 分别注入 -m32(32 位)或 -m64(64 位)到 CFLAGS 与 LINKFLAGS;cpu/native/Makefile.include 中,当 Linux x86_64 主机配合 arch_32bit 特性时,Rust 目标平台会被设为 i686-unknown-linux-gnu,即 Rust 组件也会随之交叉到 32 位。
如果你使用的是 FreeBSD amd64 平台,构建系统同样会为 32 位模式追加 -DCOMPAT_32BIT -B/usr/lib32 及对应链接路径(见 makefiles/arch/native.inc.mk 的 FreeBSD 分支),保持跨平台一致性。
构建与运行 native32 应用
构建
使用 BOARD=native32 即可完成交叉编译,产物是一个 ELF 可执行文件:
# 以 hello-world 为例(其余 examples 同理)
make -C examples/basic/hello-world BOARD=native32
构建产物位于应用的 bin/native32/ 目录下(如 bin/native32/hello-world.elf),而不是 .bin 固件。BOARD=native 会在 32 位主机上自动等效于 native32,在 64 位主机上自动等效于 native64。
运行与终端
native 板卡的串口交互由终端脚本处理,其规则定义在 boards/common/native/Makefile.include:
- 未请求
term目标时,RIOT_TERMINAL默认是native(直接执行 ELF); - 请求
term目标时,默认切换为pyterm包装器,并把可执行文件与端口参数一并传给 pyterm; - 默认
PORT为tap0,即运行时会默认挂载一个 tap 虚拟网卡接口。
因此最常用的运行方式仍是 RIOT 一贯的 make term:
make -C examples/basic/hello-world BOARD=native32 term
运行时配置:完整的命令行选项
native 实例支持在运行时进行大量配置。文档建议先用 -h 查看完整帮助,以 native64 的默认示例输出如下(native32 选项完全一致):
$ examples/basic/default/bin/native64/default.elf -h
usage: examples/basic/default/bin/native64/default.elf <tap interface 1> [-i <id>] [-d] [-e|-E] [-o] [-c <tty>] [-g <gpiochip>] [-i <id>] [-d] [-e|-E] [-o] [-c <tty>] [--eui64 <eui64> …]
help: examples/basic/default/bin/native64/default.elf -h
Options:
-h, --help
print this help message
-i <id>, --id=<id>
specify instance id (set by config module)
-s <seed>, --seed=<seed>
specify srandom(3) seed (/dev/random is used instead of random(3) if
the option is omitted)
-d, --daemonize
daemonize native instance
-e, --stderr-pipe
redirect stderr to file
-E, --stderr-noredirect
do not redirect stderr (i.e. leave sterr unchanged despite
daemon/socket io)
-o, --stdout-pipe
redirect stdout to file (/tmp/riot.stdout.PID) when not attached
to socket
-c <tty>, --uart-tty=<tty>
specify TTY device for UART. This argument can be used multiple
times (up to UART_NUMOF)
-g <gpio>, --gpio=<gpio>
specify gpiochip device for GPIO access.
This argument can be used multiple times.
Example: --gpio=/dev/gpiochip0 uses gpiochip0 for port 0
-U <eui64>, --eui64=<eui64>
provide a ZEP interface with EUI-64 (MAC address)
This argument can be provided multiple times
-w <tap>
Add a tap interface as a wireless interface
各选项的实战含义:
| 选项 | 作用 |
|---|---|
<tap interface>(位置参数) |
指定网络所用的 tap 接口名,默认 tap0 |
-i <id> |
指定实例 ID,由 config 模块使用,便于多实例区分 |
-s <seed> |
指定 srandom(3) 随机种子;省略时使用 /dev/random 而非 random(3),保证随机性质量 |
-d |
守护进程化(daemonize),后台运行 |
-e / -E |
将 stderr 重定向到文件 / 保持 stderr 不重定向 |
-o |
未挂接 socket 时把 stdout 重定向到 /tmp/riot.stdout.PID |
-c <tty> |
指定 UART 对应的 TTY 设备,可重复指定(最多 UART_NUMOF 个),从而把 RIOT 的 UART 外设映射到真实串口设备 |
-g <gpio> |
指定 GPIO 访问所用的 gpiochip 设备,可重复;例如 --gpio=/dev/gpiochip0 将 gpiochip0 用作 port 0 |
-U <eui64> |
提供一个带 EUI-64(MAC 地址)的 ZEP 接口,可重复,用于构建 802.15.4 虚拟网络 |
-w <tap> |
把一个 tap 接口添加为无线接口 |
上述部分选项会由 make 系统自动拼接。例如 boards/common/native/Makefile.include 中:TERMFLAGS += $(PROCARGS) $(PORT) 自动传入默认 tap 接口;启用 ZEP(USE_ZEP=1)时追加 -z <ZEP_IP>:<ZEP_PORT_BASE>,默认 ZEP_IP=[::1]、ZEP_PORT_BASE=17754;指定 ZEP_MAC 时追加 --eui64=;使用 periph_eeprom 时追加 --eeprom $(EEPROM_FILE)(默认 bin/.../native.eeprom);使用 periph_can 时追加 --can <vcannum>:<vcanifname>(默认 0:vcan0)。
栈大小与"真实感"
文档特别提醒:与任何平台一样,你可以通过配置指定栈大小。native 板卡的默认栈是 THREAD_STACKSIZE_DEFAULT,它通常偏大以容纳宿主机环境的调用开销。如果希望提高运行的真实感(更接近真实 MCU 的紧张栈空间),应当显式配置更贴近实际的栈大小,从而尽早暴露潜在的栈溢出类问题。
时区(TZ)行为与配置
为保证与嵌入式系统行为一致,native 默认在未设置环境变量 TZ 时使用 UTC 时区——因为嵌入式设备通常不使用时区,time.h 中的 mktime 等函数若受宿主时区影响,会导致跨平台行为不一致。
如果应用确实需要与宿主机相同的时区,有以下三种设置方式:
# 方式一:在运行 make term 的同一 shell 中先导出
export TZ=":/etc/localtime"
make term
# 方式二:写入 ~/.profile 持久生效
# export TZ=":/etc/localtime" (追加到 ~/.profile)
# 方式三:单次运行时临时指定
TZ=":/etc/localtime" make term
此外,时区也可以在运行时由应用自身设置(对 native 与嵌入式设备均适用):
setenv("TZ", <timezonestring>, 1);
注意 <timezonestring> 的格式要求:picolibc 与 newlibc 期望形如 NAME+/-hh:mm:ss<DST-handling>,其中 + 表示向西(例如 CET-1 表示相对 UTC 增加 1 小时,参见 man timezone)。一个完整的示例:
ACST-9:30ACDT-10:30,M10.1.0,M4.1.0
若 TZ 字符串无法被所用 libc(newlib、picolibc、glibc)解析,会回退到 UTC。
⚠️ 需要留意:大多数软件包与系统模块的假设是"运行在未设置时区的嵌入式系统上",因此部分函数(尤其是 mktime)在遵循宿主时区后可能表现"异常",这是已知的取舍,见 common/native doc 的警告段落。
从源码看 native 板卡的实现机制
板卡层级与配置组织
native32 的代码组织是典型的"薄壳 + 公共层"结构:
boards/native32/
├── Kconfig # BOARD=native32 默认 y,select CPU_MODEL_NATIVE
├── Makefile # MODULE = board;DIRS += common/native
├── Makefile.dep # USEMODULE += boards_common_native
├── Makefile.features # CPU=native;arch_32bit;NATIVE_ARCH_BIT=32
├── Makefile.include # 透传 common/native 的配置
└── doc.md # 板卡文档(本文核心)
从 boards/native32/Kconfig 可以看到,BOARD_NATIVE32 默认开启并 select CPU_MODEL_NATIVE;boards/native32/Makefile.dep 引入 boards_common_native 模块。这意味着 native32 与 native64 共享同一套板级实现,两者唯一的本质差异就是 NATIVE_ARCH_BIT 与 arch_32bit 特性带来的 -m32/-m64 编译开关(见 makefiles/arch/native.inc.mk)。
构建期自动注入的编译与链接选项
makefiles/arch/native.inc.mk 还揭示了 native 板卡构建的更多细节:
- 默认
-std=gnu11,-Og优化(使用backtrace模块时强制-fno-omit-frame-pointer),-g3调试信息; - 启用 DEVELHELP 时追加
-fstack-protector-all; - 固定追加
-no-pie以避免 32 位重定位告警;-ffunction-sections -fdata-sections配合--gc-sections裁剪未用函数; - 使用 XFA(cross file array)链接脚本
cpu/native/ldscripts/xfa.ld,这是 RIOT 模块自动注册机制在 native 上的实现基础; - 定义了完整的工具链目标:
all-asan(AddressSanitizer)、all-valgrind、all-gprof、all-cachegrind、debug-valgrind-server、term-gprof等,说明 native 板卡天然支持在主机上做内存检查、性能剖析与覆盖率类工作。
板级外设模拟的默认配置
boards/common/native/include/board.h 给出了板级外设的模拟参数:
- LED:红绿两盏 LED 的开关/翻转由
_native_LED_*函数实现,状态变化打印到 UART; - MTD(存储器设备)模拟:默认页大小 256 字节、扇区 4096 字节、2048 扇区(启用 FATFS/LittleFS-ext4 时分别变为 512 / 512 / 32768),模拟文件名为
MEMORY.bin,写粒度 1 字节;应用可通过MTD_PAGE_SIZE、MTD_SECTOR_SIZE、MTD_SECTOR_NUM、MTD_WRITE_SIZE、MTD_NATIVE_FILENAME覆盖; - 宿主文件系统访问:默认把工作目录下的
nvm0文件夹导出给 RIOT(FS_NATIVE_DIR),用于模拟掉电不丢失的存储; - ztimer 精度:
CONFIG_ZTIMER_USEC_MIN设为 64,注释直言 "on native, anything can happen...",即 native 上最小定时粒度受宿主机调度影响,不应假设过高的定时精度。
网络:tap 与 ZEP 虚拟化
native 板卡把 RIOT 的网络栈接到宿主机的虚拟网络设备上:默认使用 tap 接口(netif_ethernet 特性),并支持以 -w 添加无线接口;通过 -U/--eui64 提供带 EUI-64 的 ZEP(ZigBee Encapsulation Protocol)接口。结合 boards/common/native/Makefile.include 中的 ZEP 默认参数([::1]:17754),你可以在单台主机上启动多个 native 实例,组成受控的虚拟 802.15.4/以太网网络进行协议实验,这也是官方 wiki 中 "Virtual riot network" 方案的基础。
常见问题与排障建议
- 64 位主机上缺少 32 位库导致链接失败:确认已安装
gcc-multilib;报错涉及libasan时补装lib32asan5;C++ 应用链接失败时补装g++-multilib。 - 构建告警 "module backtrace is used, do not omit frame pointers":native 构建在启用
backtrace时会强制-fno-omit-frame-pointer,这是为保留下钻回溯所需栈帧,属预期行为。 - 时区相关函数行为不符预期:检查
TZ是否被导出(RIOT 默认 UTC),参照上文三种方式显式设置;嵌入式场景建议保持 UTC。 - 多实例冲突:运行多个 native 实例时,使用
-i <id>区分实例、-s <seed>固定随机种子,并为每个实例分配独立的 tap 接口与 ZEP 端口,避免端口与接口冲突。 - 已知问题跟踪:native 平台相关的已知问题可检索官方 issue 跟踪器中标记为 "Platform: native" 的条目(见 boards/common/native/doc.md 末尾的 Known Issues 指引)。
总结
BOARD=native32 是 RIOT native 板卡体系的 32 位变体,它把宿主机的系统调用与信号抽象为 RIOT 的外设 API,让完整的 RIOT 软件栈以普通进程形式在 *NIX 上运行。通过本文你应该已经掌握:native32 与 native64/BOARD=native 的关系、Debian/Ubuntu 上的 32 位交叉编译依赖、构建运行流程、-h 列出的全部运行时选项(tap 网络、UART TTY、gpiochip、ZEP 无线接口、EEPROM/CAN 模拟等)、TZ 时区语义,以及背后 makefiles/arch/native.inc.mk、boards/common/native/Makefile.include 与 boards/common/native/include/board.h 中可验证的实现细节。无论你是刚接触 RIOT、需要无硬件调试应用,还是要搭建虚拟网络实验协议栈,native32 都是一条低摩擦、可调试、可重复的快速路径。