RIOT native64 板卡详解:在 64 位宿主机上以进程方式运行完整 IoT 软件栈
RIOT native64 板卡详解:在 64 位宿主机上以进程方式运行完整 IoT 软件栈
RIOT 的 native64 板卡通过系统调用与信号在 API 层面仿真硬件,让开发者可以把完整的 RIOT 软件栈编译成本机可执行文件并直接作为进程运行。本文围绕 native64 板卡文档 展开,结合 common native 板卡文档 与仓库源码,系统讲解 native64 的原理、硬件抽象映射、编译运行方法、运行时配置参数、时区处理与网络仿真方式,帮助你在没有真实硬件的情况下完成 RIOT 应用开发、调试与协议实验。
概述:什么是 native 板卡
RIOT 的 native 板卡是面向 *NIX(Linux、macOS 等)宿主平台的特殊"板卡"。与真实硬件板卡通过寄存器、中断驱动外设不同,native 板卡使用系统调用(system calls)和信号(signals)在 API 层面仿真硬件。这意味着你可以把 RIOT 的完整软件栈编译成一个宿主机可执行文件,并以普通进程的形式运行它。
官方文档(boards/common/native/doc.md)明确列出了选择 native 板卡的典型理由:
- 想尝试 RIOT,但手头没有受支持的硬件平台;
- 正在为 RIOT 开发应用或修改 RIOT 内核本身,希望在不受真实硬件调试限制的前提下进行测试与调试;
- 希望在受控环境中实验网络协议(例如构建虚拟 RIOT 网络)。
native64 是两种 native 变体之一,专门编译并执行 64 位可执行文件。另一种变体是 native32 板卡,用于生成 32 位可执行文件。当使用 BOARD=native 时,RIOT 会根据宿主平台自动选择正确的变体。
三种板卡名之间的关系
| 板卡名 | 用途 | 说明 |
|---|---|---|
BOARD=native |
自动选择 | 根据宿主平台自动选择 native32 或 native64 |
BOARD=native64 |
显式指定 64 位 | 编译为 64 位宿主机可执行文件 |
BOARD=native32 |
显式指定 32 位 | 编译为 32 位宿主机可执行文件 |
从 native64 的 Makefile.features 可以看到,它设置 CPU = native、NATIVE_ARCH_BIT = 64,并声明提供 arch_64bit 特性;而 native32 的 Makefile.features 则设置 NATIVE_ARCH_BIT = 32 并声明 arch_32bit。两个板卡的其余配置全部复用 boards/common/native/ 目录下的共享文件——native64 的 Makefile 通过 DIRS += $(RIOTBOARD)/common/native 引入共享目录,Makefile.include 也直接 include 了 $(RIOTBOARD)/common/native/Makefile.include。
硬件抽象:native64 如何映射宿主机资源
从 common native 板卡文档 的 Hardware 一节可以看到,native 板卡的"硬件"全部由宿主机资源承担:
| native "外设" | 宿主机资源 |
|---|---|
| CPU | 宿主 CPU |
| RAM | 宿主内存 |
| Flash(程序执行) | 宿主文件系统 |
| Flash(periph_flashpage) | RAM 中仿真 |
| 网络 | Tap 接口 |
| UART | 运行时配置,支持 /dev/tty* |
| 定时器 | 宿主定时器 |
| RTC | 宿主时间(UTC) |
| LED | 一个红色、一个绿色,状态变化打印到 UART |
| PWM | 虚拟 PWM(Dummy PWM) |
| QDEC | 按 PWM 方式仿真 |
| SPI | 运行时配置,支持 /dev/spidev*(仅 Linux 宿主) |
| GPIO | 运行时配置,支持 /dev/gpiochip*(仅 Linux 宿主) |
这一映射在源码层面同样可以得到印证:boards/common/native/include/board.h 中定义了 LED 处理函数 _native_LED_RED_ON、_native_LED_GREEN_OFF 等,并把 LED0_ON 等宏映射到这些函数(状态变化会通过 UART 打印);drivers/native-led.c 则实现了 LED 的打印行为。该头文件还定义了宿主机文件系统访问配置 FS_NATIVE_DIR(默认导出宿主目录 "nvm0" 给 RIOT 使用)以及 MTD(内存存储设备)仿真参数——例如默认 MTD_PAGE_SIZE = 256、MTD_SECTOR_SIZE = 4096、MTD_SECTOR_NUM = 2048,而当启用 FATFS 或 LWExt4 文件系统模块时,这些参数会分别变为 512、512 和 32768 以贴近真实介质规格。
此外,common/native 的 Makefile.features 声明了该板卡提供的特性清单,包括 periph_rtc、periph_rtc_ms、periph_timer、periph_uart、periph_gpio、periph_pwm、periph_qdec、motor_driver 与 netif_ethernet。也就是说,一个 native64 程序在 RIOT 层面看起来与真实板卡完全一致,上层模块无需任何修改即可运行。
编译与运行:把 RIOT 应用跑成本机进程
以官方示例 examples/basic/default 为例,编译 native64 版本:
make BOARD=native64 -C examples/basic/default
生成的 ELF 可执行文件位于 examples/basic/default/bin/native64/default.elf,可以直接运行:
./examples/basic/default/bin/native64/default.elf
也可以使用 make term 启动。从 common/native 的 Makefile.include 可以看到终端工具的选择逻辑:只有当 make 目标包含 term 时,RIOT_TERMINAL 才默认为 pyterm(RIOT 自带的 Python 终端封装),否则默认使用 native 直接运行 ELF。该文件还设置了 PORT ?= tap0(默认 Tap 接口)、EEPROM_FILE ?= $(BINDIR)/native.eeprom(EEPROM 仿真文件)等默认值。
值得强调的是:native 板卡与真实平台一样,可以通过栈大小配置控制应用可用的地址空间,但官方文档建议,如果希望结果更贴近真实嵌入式环境,可以使用比 native 默认的 THREAD_STACKSIZE_DEFAULT 更接近实际硬件限制的栈大小,以提高仿真的真实感。
运行时配置:-h 参数详解
native 实例的许多行为可以在运行时配置。调用程序时传入 -h 即可查看完整帮助。以下以官方文档中的输出为基准(文档原文来自 boards/common/native/doc.md),逐一说明各参数的作用:
usage: examples/basic/default/bin/native64/default.elf <tap interface 1> [-i <id>] [-d] [-e|-E] [-o] [-c <tty>] [-g <gpiochip>] [--eui64 <eui64> …]
Options:
-h, --help
打印本帮助信息
-i <id>, --id=<id>
指定实例 ID(由 config 模块使用)
-s <seed>, --seed=<seed>
指定 srandom(3) 的随机种子;若省略该选项,
将使用 /dev/random 而非 random(3)
-d, --daemonize
将 native 实例守护进程化
-e, --stderr-pipe
将 stderr 重定向到文件
-E, --stderr-noredirect
不重定向 stderr(即使处于守护进程/socket IO
模式下也保持 stderr 不变)
-o, --stdout-pipe
未连接 socket 时将 stdout 重定向到文件
(/tmp/riot.stdout.PID)
-c <tty>, --uart-tty=<tty>
指定 UART 使用的 TTY 设备;该参数可多次
使用(最多 UART_NUMOF 次)
-g <gpio>, --gpio=<gpio>
指定 GPIO 访问使用的 gpiochip 设备;
该参数可多次使用。
例如:--gpio=/dev/gpiochip0 表示端口 0 使用
gpiochip0
-U <eui64>, --eui64=<eui64>
为 ZEP 接口提供 EUI-64(MAC 地址);
该参数可多次提供
-w <tap>
将一个 tap 接口添加为无线接口
实际运行中,位置参数 <tap interface 1> 是第一个 Tap 接口名(默认 tap0),用于以太网仿真。使用示例:
./examples/basic/default/bin/native64/default.elf tap0 -c /dev/ttyUSB0
以上命令在把 tap0 作为网络接口的同时,把 /dev/ttyUSB0 作为 UART 设备接入。这些运行参数与 common/native 的 Makefile.include 中的默认值形成对应:例如默认 PORT = tap0、ZEP 默认地址 [::1]:17754、启用 periph_can 时默认附加 --can 0:vcan0 参数、启用 periph_eeprom 时默认附加 --eeprom 参数并指向 EEPROM 仿真文件。
设置时区:保持与嵌入式环境一致
RIOT native 在环境变量 TZ 未设置时默认使用 UTC 时区,这是为了让 time.h 中如 mktime 等函数的行文与通常不使用时区的嵌入式环境保持一致。
如果应用需要使用与宿主机相同时区,则应显式设置 TZ 环境变量。官方文档给出了三种方式:
# 方式一:在运行 make term 的同一个 shell 中先导出
export TZ=":/etc/localtime"
make term
# 方式二:将导出语句写入 ~/.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。
⚠️ 文档同时给出了重要警告:由于大多数 pkg 和系统模块都假定运行在没有设置时区的嵌入式系统上,设置时区后某些功能可能出现异常行为,一个常见例子就是会受时区设置影响的 mktime。
网络仿真:Tap、ZEP 与 vcan
native 板卡是 RIOT 网络协议栈调试的重要工具,common/native 的 Makefile.include 集中体现了网络仿真相关的默认配置:
- Tap 接口(以太网):默认
PORT = tap0,程序启动时的位置参数即指定该接口;netif_ethernet特性在 Makefile.features 中声明。 - ZEP(ZeroMQ Emulation Protocol):默认 ZEP 地址
ZEP_IP = [::1]、端口基准ZEP_PORT_BASE = 17754;使用USE_ZEP=1时,make term会自动追加-z [::1]:17754参数;ZEP_MAC变量可通过--eui64为 ZEP 接口指定 EUI-64(MAC 地址)。-w <tap>参数则可以把 Tap 接口作为无线接口加入。 - CAN(vcan):当启用
periph_can特性时,默认使用vcan0(VCAN_IFNAME ?= vcan0),并通过--can 0:vcan0参数挂接虚拟 CAN 接口。
利用这些能力,开发者可以在宿主机上启动多个 native64 实例、通过 Tap 接口或 ZEP 把它们互联,构造受控的"虚拟 RIOT 网络",从而在没有射频硬件的情况下验证 802.15.4、6LoWPAN、CoAP 等网络协议栈行为。
配置体系:Kconfig 与构建变量
native64 在 Kconfig 层面通过 boards/native64/Kconfig 注册:config BOARD_NATIVE64 默认为 y,BOARD 的默认值设置为 "native64",并 select CPU_MODEL_NATIVE。这意味着当以 native64 为目标平台时,CPU 模型会被解析为 native。
结合前面提到的构建文件,native64 的配置体系可归纳为:
- boards/native64/Makefile:声明
MODULE = board,并引入boards/common/native共享目录; - boards/native64/Makefile.features:设置
CPU = native、NATIVE_ARCH_BIT = 64、arch_64bit特性; - boards/native64/Makefile.include:复用 common native 的 include 逻辑;
- boards/common/native/Makefile.include:终端、Tap、ZEP、EEPROM、vcan 等运行参数默认值;
- boards/common/native/include/board.h:LED、MTD 仿真、宿主文件系统目录、SPIFFS 与 ztimer 的板级默认配置。
此外,boards/common/native/board_init.c 负责 native 板卡的初始化逻辑,include/gpio_params.h 与 include/eui_provider_params.h 分别提供 GPIO 参数与 EUI-64 提供者参数的默认定义,它们共同支撑了上文所述的外设仿真能力。
已知问题与注意事项
官方文档明确提示,使用 native 板卡时应关注 GitHub issue tracker 中带有 Platform: native 标签的已知问题列表(例如时序、信号处理在极端负载下的行为等)。结合源码与文档,以下几点是实际使用中值得留意的:
- 时区假设:多数 pkg 与系统模块假定"无时区的嵌入式环境",显式设置
TZ后mktime等函数的行为可能与嵌入式目标不一致; - 宿主相关外设:SPI(
/dev/spidev*)与 GPIO(/dev/gpiochip*)仅支持 Linux 宿主; - 调度与定时器:native 定时器依赖宿主定时器,ztimer 的最小粒度配置在 board.h 中被设为
CONFIG_ZTIMER_USEC_MIN = 64,注释中直言"on native, anything can happen...",暗示宿主机调度抖动可能影响微秒级时序仿真精度。
总的来说,native64 为开发者提供了一条"零硬件"的 RIOT 开发与调试路径:无论是想快速上手 RIOT、在 IDE 中单步调试内核,还是搭建多实例虚拟网络验证协议栈,只需 make BOARD=native64,即可把完整的 RIOT 系统作为宿主机进程运行起来,而这正是 RIOT 生态中极具特色的"友好"所在。