RIOT native64 板卡详解:在 64 位宿主机上以进程方式运行完整 IoT 软件栈

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

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/common/native/board_init.c 负责 native 板卡的初始化逻辑,include/gpio_params.h 与 include/eui_provider_params.h 分别提供 GPIO 参数与 EUI-64 提供者参数的默认定义,它们共同支撑了上文所述的外设仿真能力。

已知问题与注意事项

官方文档明确提示,使用 native 板卡时应关注 GitHub issue tracker 中带有 Platform: native 标签的已知问题列表(例如时序、信号处理在极端负载下的行为等)。结合源码与文档,以下几点是实际使用中值得留意的:

  1. 时区假设:多数 pkg 与系统模块假定"无时区的嵌入式环境",显式设置 TZ 后 mktime 等函数的行为可能与嵌入式目标不一致;
  2. 宿主相关外设:SPI(/dev/spidev*)与 GPIO(/dev/gpiochip*)仅支持 Linux 宿主;
  3. 调度与定时器:native 定时器依赖宿主定时器,ztimer 的最小粒度配置在 board.h 中被设为 CONFIG_ZTIMER_USEC_MIN = 64,注释中直言"on native, anything can happen...",暗示宿主机调度抖动可能影响微秒级时序仿真精度。

总的来说,native64 为开发者提供了一条"零硬件"的 RIOT 开发与调试路径:无论是想快速上手 RIOT、在 IDE 中单步调试内核,还是搭建多实例虚拟网络验证协议栈,只需 make BOARD=native64,即可把完整的 RIOT 系统作为宿主机进程运行起来,而这正是 RIOT 生态中极具特色的"友好"所在。

登录后查看全文
RIOT