Developer Docs · BSP Porting

BSP 移植与适配

BSP 不是一个整机镜像，而是五层产物的组合。每一层有独立版本、独立校验与独立回退方式，换板型时优先只改需要改的那一层，不要整机重来。

适用版本BSP v2.4.0 · huayun-cli ≥ 2.4.0

端点约定：本文档中的 mqtt.huayuniot.com.cn、api.huayuniot.com.cn、get.huayuniot.com.cn、manifest.huayuniot.com.cn 为接入点命名约定；正式环境地址以交付时随附的《接入信息表》为准。命令名 huayun-cli / hy-rt / huayun-bsp-info 沿用历史命名，以保证客户既有脚本向后兼容。

适用板型HY-Edge X1（NPU-v2）· HY-Gateway G3 · HY-MCU M55 · HY-DevKit C1

最近更新2026-09-08 · 对应 BSP v2.4.0

反馈入口contact@huayuniot.com.cn · 1 个工作日

Layers · 五层与升级边界

每一层能单独升级，也就能单独回退

量产维护的成本主要来自「只能整机重刷」。这张表写清哪些层可以单独升级、回退动作是什么、回退需要多久。

层	产物	版本示例	可单独升级	回退方式
Bootloader	`u-boot.bin` + `env.bin`	v2023.10-hy2	否，随整机槽	A/B 槽切换；env 独立分区不随升级覆盖
Kernel	`Image` + `*.dtb`	5.15.148-rt	是（内核包）	重启切回旧槽，`env` 保留
Drivers	`hy_npu.ko` `hy_isp.ko` `hy_canfd.ko` 等	drivers-2.4.0	是（按模块）	卸载后回装上一版本 ko，无需重启
Rootfs / Runtime	`rootfs.squashfs` + `libhy-npu` + `hy-rt`	rootfs-kirkstone-2.4	是（只读层替换）	非活跃槽保留上一版本，切换即回退
Model / Config	`/data/models/.hyb` + `.json`	随项目	是（模型双槽）	`current` 软链切回 a/b 槽，<1s

判断原则：改动落在哪一层，就只出那一层的升级包。整机镜像只在出厂首刷与跨大版本（如 2.2 → 2.4）时使用，因为整机包会连带覆盖 env 与本地校准数据，现场重做标定的成本远高于分层升级。

Porting Check · 移植前置检查

换板型先对硬件，再动软件

这六项对不上，编译能过、板子也能亮，但会在压力测试或批量后暴露。建议在打样前逐项签字确认。

01 MEMORY

DDR 容量与频率

容量决定能跑几个模型实例，频率决定 DDR 带宽是否够多路视频。

单路 1080p 解码 + YOLOv8n 推理，DDR 带宽峰值约 1.2 GB/s
容量低于 2 GB 时，模型槽只保留 a/b 两份

02 POWER

PMIC 时序与供电范围

上电时序错会导致内核随机挂死，且很难从日志看出原因。

核对各电源域上电顺序与复位释放时刻
供电范围按现场定：整机为 9~36 V，宽压需加防反接

03 CLOCK

时钟树与晶振

NPU 与 ISP 对时钟抖动敏感，晶振负载电容按厂家推荐值取。

NPU 目标频率 1 GHz，降频会直接体现在单帧延迟上
确认 PTP/NTP 授时使用的时钟源，避免时间戳漂移

04 PINMUX

引脚复用

同一个引脚在不同板型上可能已经复用，改引脚必须同步改 overlay。

串口、CAN、网口 PHY 逐一对照原理图网络名
保留调试串口，量产后仍要能进 U-Boot

05 STORAGE

存储分区表

A/B 分区大小按「当前镜像 ×1.3」预留，留出模型与缓存空间。

根文件系统只读（squashfs），/data 可写
/data 至少预留 2 倍最大模型体积 + 72 小时本地缓存

06 WATCHDOG

看门狗与恢复

看门狗 30s，启动失败自动切 B 槽；这一条必须在打样阶段验证。

人为打断启动 3 次，确认自动切换且日志留存
记录切换耗时，纳入验收记录

Build · 构建

用 manifest 锁版本，产物由清单索引

构建入口是 repo + manifest。版本号写在 manifest 里，构建产物由 bsp-manifest.json 索引，校验以清单为准而不是以目录名为准。

host — 拉取与构建Ubuntu 22.04

# 1) 拉取 BSP（manifest 锁定全部仓库版本）
repo init -u https://manifest.huayuniot.com.cn/bsp \
  -b v2.4.0 -m hy-edge-x1.xml
repo sync -j8

# 2) 验签与依赖自检
huayun bsp verify --manifest manifest/bsp-manifest.json
huayun env check --board hy-edge-x1

# 3) 全量构建（Yocto Kirkstone）
huayun bsp build --board hy-edge-x1 \
  --variant yocto --jobs 8

# 首次约 18 分钟；改一个驱动后增量约 2 分钟

# 4) 只出内核包（换 dts 或内核补丁时）
huayun bsp build --board hy-edge-x1 --kernel-only

一次构建的六类产物

产物	文件	说明
Bootloader	`u-boot.bin` `env.bin`	A/B 槽，支持回滚
Kernel	`Image` `*.dtb`	含 Device Tree overlay
Rootfs	`rootfs.squashfs`	只读层 + `/data` 可写叠加
整机镜像	`hy-edge-x1_v2.4.0.img`	出厂首刷使用
交叉 SDK	`sdk-aarch64.sh`	工具链 + sysroot
清单	`bsp-manifest.json`	版本 / SHA256 / 签名

可复现性：同一 manifest 在同一宿主机镜像上重复构建，产物哈希一致。改了 dts/overlays/ 或 kernel/fragments/ 之后，清单里的哈希会变，升级包必须重新生成，不要沿用旧包。

Device Tree · 板级描述

改 overlay，不改 defconfig

板型差异写在 overlay 与 fragments 里：overlay 描述硬件，fragments 增量打开内核配置。两者的改动范围都能单独评审。

dts/overlays/hy-edge-x1-canfd.dtsi硬件描述

/ {
    fragment@0 {
        target = <&canfd0>;
        __overlay__ {
            hy,bitrate = <1000000>;
            hy,sample-point = <875>;  /* 千分比 */
            status = "okay";
        };
    };

    fragment@1 {
        target = <&pinctrl>;
        __overlay__ {
            canfd0_pins: canfd0-pins {
                hy,pins = "gpio3-12", "gpio3-13";
                hy,function = "canfd0";
                hy,bias = "pull-up";
            };
        };
    };
};

kernel/fragments/hy-edge-x1.config增量配置

# 增量片段：与 defconfig 合并，不改 defconfig 本体
CONFIG_HY_NPU=m
CONFIG_HY_ISP=m
CONFIG_HY_VPU=m
CONFIG_HY_CANFD=y
CONFIG_PREEMPT_RT=y
CONFIG_WATCHDOG_NOWAYOUT=n

# 编译进树或按模块加载：
#  =m 便于单层升级与回退；=y 用于启动必需项

# 应用片段
huayun bsp config --board hy-edge-x1 \
  --fragment kernel/fragments/hy-edge-x1.config

# 可视化裁剪（生成新的 fragment 文件）
huayun bsp kernel-menuconfig --board hy-edge-x1

三条约定：① overlay 文件名与板型一致（hy-edge-x1-*.dtsi），构建脚本按板型自动加载；② 不在 arch/arm64/configs/ 下改 defconfig，避免与上游合并冲突；③ 引脚命名用原理图网络名，不用 SoC 引脚编号，评审时对得上图。

Drivers & Rollback · 驱动与单层回退

驱动按模块升级，回退不用重刷

驱动全部编成模块（=m），升级就是换一个 .ko，回退就是换回来。每换一次都跑一次对应的校验命令。

驱动	内核模块	版本	接口	校验命令
NPU-v2	`hy_npu.ko`	2.4.1	`/dev/hy-npu0` + `libhy-npu.so`	`hy-npu-test --burn 100`
ISP / Camera	`hy_isp.ko`	1.8.3	V4L2 `/dev/video0-3`	`v4l2-ctl --stream-mmap`
VPU 编解码	`hy_vpu.ko`	1.6.0	V4L2 M2M	`hy-vpu-bench`
CAN FD	`hy_canfd.ko`	2.1.0	`can0` / `can1`	`ip -details -s link show can0`
Wi-Fi / BT	`rtl88x2cs.ko`	5.12	`cfg80211`	`iw dev wlan0 scan`
4G Modem	`qmi_wwan`	随内核	QMI / AT	`uqmi -d /dev/cdc-wdm0 --get-data-status`

host — 单层升级不停机可回退

# 只升内核层（不动 rootfs）
huayun ota build --board hy-edge-x1 \
  --layer kernel --from v2.3.0 --to v2.4.0 --diff --sign

# 推到单台设备并等待结果
huayun ota push --device gw-line3-cabinet \
  --layer kernel --wait --timeout 15m

# 校验：版本与清单一致
huayun-bsp-info --json | jq '.layers.kernel'
hy-rt --version

host — 回退保留旧槽

# 回退到上一版本内核（非活跃槽仍在）
huayun ota rollback --device gw-line3-cabinet --layer kernel

# 单独换一个驱动模块
huayun ota push --device gw-line3-cabinet \
  --layer driver --module hy_npu --version 2.4.0

# 板端确认模块载入与版本
lsmod | grep hy_npu
modinfo hy_npu | head -3

失败自动回退：升级后 3 分钟内健康检查（NPU 自检 + 模型 warmup 3 帧 + 数据回传）任一项失败，设备自动切回旧槽并上报失败码，不需要人工介入。失败码表见运维、OTA 与 SLA。

Bring-up Checklist · 最小可启动验证

从串口到推理，五项按顺序验

每一项都有明确的日志特征或命令输出，不靠「能亮机」判断。前一项不过就不要做后一项。

Bootloader：串口出现验签通过行，且能进入命令行。
Kernel：版本行为 5.15.148-rt，dtb 名称与板型一致。
驱动：NPU、ISP、CAN 模块全部载入，无 probe failed。
Rootfs：只读层挂载正常，/data 可写且容量符合预留。
Runtime：hy-rt 能加载样例模型并跑出首帧结果。

board — 五项验证命令串口 / SSH

# 1) 五层版本（与 bsp-manifest.json 逐项比对）
huayun-bsp-info --json | jq '.layers'

# 2) 内核与 dtb
uname -r                 # 5.15.148-rt
cat /proc/device-tree/model

# 3) 驱动就绪
dmesg | grep -E 'hy_(npu|isp|vpu)|canfd'
lsmod | grep -E 'hy_|canfd'

# 4) 存储
mount | grep -E ' / | /data '
df -h /data

# 5) 运行时首帧
hy-rt verify --model /data/models/*.hyb
hy-rt bench --model /data/models/*.hyb --warmup 3
#  X1 预期 p50 < 4 ms

防静电袋上放着一块黑色开发板，两侧排针与 USB-C 口朝向镜头，旁边是镊子、彩色杜邦线与贴片元件料盒 — 新板首启：先确认串口与供电，再逐层验证驱动，最后才装模型。

现象	根因	处置
卡在 `Starting kernel ...`	dtb 与板型不匹配	确认 dtb 名称，`huayun bsp build --kernel-only` 重建
`/dev/hy-npu0` 不存在	未开 `CONFIG_HY_NPU=m` 或电源域未上电	查 `dmesg \| grep hy_npu`；`hy-pm npu on`
CAN 报文 CRC 错误	终端电阻缺失或位时序偏差	两端各 120 Ω；`sample-point` 调到 875
启动时间超过 8 s	服务阻塞在等待网络	`systemd-analyze blame` 定位，改为按需启动
反复看门狗复位	首启健康检查失败	看 B 槽日志；确认健康检查脚本的输出

Next · 下一步

板子起来之后

端侧运行时与模型部署模型产物、双槽切换、精度与性能阈值 协议接入Modbus / OPC UA / MQTT 的寄存器与主题约定 运维、OTA 与 SLA灰度批次、失败码、回滚与可用性口径

本文档由平台研发组维护，最近复核 2026-09-08。移植过程中遇到与文档不符的现象，请附串口完整启动日志与 huayun-bsp-info --json 输出发至 contact@huayuniot.com.cn。

2026-09-08：五层表补充 Drivers 层可单独升级说明；新增 CAN FD 驱动校验命令。
2026-07-30：构建章节改为 repo + manifest 口径。