RIOT OS native32 板卡详解:在 32 位主机上以进程方式运行完整物联网软件栈

原创2026-09-17 13:43:041,649 阅读
文章标签:物联网嵌入式操作系统实时系统

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 都是一条低摩擦、可调试、可重复的快速路径。

登录后查看全文
RIOT