Skip to content

Translation pending. This page is currently available in Chinese.

Hi3861V100 / HiSpark Pegasus

Hi3861V100 是 HiSilicon 的 2.4 GHz WLAN SoC:32 位 RISC-V 核、160 MHz、 2 MiB SPI Flash、288 KiB ROM 和 352 KiB SRAM。当前 A20OS 使用其 RV32IMC M-mode 执行环境,运行单核、NOMMU 的 MCU 内核,并在 UART0 上提供现有 MCU 命令行 shell。它不是 Linux 用户态镜像,也没有 MMU、块设备、Wi-Fi 或 Alpine 用户空间。

目标与支持状态

项目 当前实现
CPU RV32IMC + Zicsr/Zifencei,ILP32 软浮点,M-mode 异常和整数上下文切换
内核 单核任务、堆、睡眠队列、completion、抢占式 IRQ 返回调度、MCU 命令行
串口 UART0,GPIO3 TX / GPIO4 RX,115200 8N1;由定时器中断轮询接收
定时器 0x40050028 的硬件 timer 2(CLDO_CTL_CLKEN bit 8 使能时钟),24 MHz 计数,装载值 240000,控制寄存器 0x3(使能 + 32 位重装载),100 Hz 周期中断;HimiDeer local IRQ 28,locie0 bits [11:8] 优先级 2
启动 保留原厂 ROM/FlashBoot,只替换 kernel A 分区中的内核镜像
存储与网络 未接入 Flash 文件系统、Wi-Fi/BLE、USB 或完整 TCP/IP
用户程序 受信任的 RV32 U-mode flat program:静态 PIE、按 manifest 生成的 Native syscall 子集、a20_flat_space 范围校验;CMSIS 实验 4.1–4.5 已在 QEMU 上验证,实板为 opt-in

验证分为主机检查、构建/打包检查和实板启动检查。仓库内没有 Hi3861 的 QEMU 模型,因此构建成功或镜像哈希一致不代表已经启动。当前状态:

  • shell 镜像已通过 Hi3861 实板串口验收——启动打印A20OS RV32 M-mode MCU board=hi3861、[MCU TEST] PASS、A20OS MCU READY,a20> 下 info/heap/ticks/tasks/test均正常返回;ticks 显示 hz=100。
  • U-mode 实验镜像只在 QEMU 的 qemu-virt-riscv32-mcu 上验证过,实板尚未记录启动日志;烧录后按下面的命令确认再更新本页状态。

重新上板仍应按本文步骤记录本次镜像的启动日志。

本页适用于 Hi3861V100 模组和 HiSpark Pegasus 类开发板,不适用于 Hi3861L、 Hi3881 或其他 Wi-Fi SoC。板载 USB 口通常经 USB-UART 桥连接 UART0;具体引脚、电平跳线和复位方式以实际板卡原理图为准。

宿主依赖

在 Linux 主机的 A20OS 源码根目录操作。需要 Python 3.11 或更新版本、GNU make、riscv64-unknown-elf-gcc/binutils,以及能生成 RV32IMC 多库的 RISC-V 工具链。共享调度/任务模块仍使用 Rust core,因此还需要仓库 rust-toolchain.toml 指定的 Rust 工具链和 rust-src 组件(自定义 riscv32imc-a20.json 目标用 -Z build-std构建 core,不依赖预装 target):

sudo apt-get install build-essential git python3 python3-venv python3-serial \
  gcc-riscv64-unknown-elf binutils-riscv64-unknown-elf
git submodule update --init --recursive
rustup component add rust-src

如果系统只有 riscv32-unknown-elf- 或 riscv64-elf- 前缀,可用RISCV_ELF_PREFIX=... 指向同一套 GCC/binutils。工具链必须支持-march=rv32imc_zicsr_zifencei -mabi=ilp32。tools/a20 本身只需要 Python 标准库。

构建与产物

从仓库根目录执行:

tools/a20 check hi3861
tools/a20 trim hi3861
tools/a20 build hi3861 -- -j4
tools/a20 package hi3861 -- -j4
python3 tools/boards/hi3861.py verify

build hi3861 走 PROFILE=mcu、NOMMU=1、BRINGUP=1 和DRIVER_DEPLOYMENT=embedded,只生成内核,不组文件系统镜像。package 调用hi3861-package,产物固定在 build/hi3861/handoff/:

文件 用途
a20os.hupg 实际写入 kernel A 分区 0x00D000 的标准 Hi3861 内核镜像
kernel-flat.bin 去掉 0x3c0 字节头的 XIP 平坦负载,仅用于核对,不可直接当启动镜像
kernel.elf 含地址和调试信息的 ELF;入口 0x0040D3C0
image.json 分区、偏移、长度、SHA256、验证边界和 hardware_validated=false
README.md 本操作说明的副本

构建目录会随实例参数变化;需要脚本化路径时用make -s ARCH=riscv32 BOARD=hi3861 PROFILE=mcu BRINGUP=1 NOMMU=1 ABI=native print-build-dir查询,不要照抄历史目录名。普通 kernel.bin 是链接器输出的平坦二进制,不带 Hi3861 固件头,不能直接写到 Flash 的 kernel A 起点。

镜像布局与启动协议

Hi3861 的原厂启动链是 ROM → FlashBoot → kernel A/B。A20OS 保留原厂 ROM/FlashBoot,只生成 kernel A 的内容:

区域 地址/大小 说明
SPI Flash 映射 0x00400000 起,2 MiB 整片容量按实际模组核对
kernel A 分区 Flash 偏移 0x00D000,912 KiB 原厂分区表约定的内核 A
固件头 分区起点起 0x3C0 标准 image_id=0x3C78961E、file_type=0xF0
内核负载 0x0040D3C0 起 原地执行,.data 由入口代码复制到 SRAM
SRAM 内核窗口 0x000D8000..0x0011A000 264 KiB,留出 ROM/FlashBoot 的 0x11A9C0..0x11E000 数据/check-info 区
内核栈 窗口顶部 8 KiB 位于 _stack_top 之下
MCU 堆 .bss 之后到栈前 链接器要求至少 64 KiB

a20os.hupg 使用非加密 SHA256 头,不依赖签名密钥;hi3861.py 会重新计算common 段和 section 段的 SHA256,检查内核 A 的 912 KiB 上限,并确认 ELF 的软浮点 ABI、入口和加载范围。它不包含 FlashBoot、loaderboot、NV 分区或整片 Flash 镜像,也不会覆盖原厂 bootloader。

写入 kernel A

先用厂商工具或已经验证的恢复流程备份整片 2 MiB Flash。不同批次的 HiSpark/Hi3861 底板可能预装 OpenHarmony、LiteOS 或其他 AT 固件,备份内容和分区布局必须按实际板卡保存。

Linux 下可以通过 ROM 串口把 kernel A 直接写入 0x00D000。先准备与板卡 UART0 相连的串口设备(常见为 /dev/ttyUSB0),然后执行:

tools/a20 package hi3861
tools/a20 prepare hi3861
tools/a20 flash hi3861

prepare 把固定版本的 loaderboot 下载到 build/hi3861/loader.bin 并校验 SHA256;flash 会重新构建 kernel A,提示后等待 Hi3861 复位进入 ROM 下载模式,载入 loaderboot,擦除 0xD000 起的内核 A 区间,写入 a20os.hupg 后复位。它**只写 kernel A,不写 Flash 偏移 0x0**,因此不会覆盖原厂 ROM/FlashBoot、 NV 或 kernel B。串口不是 /dev/ttyUSB0 时,用tools/a20 flash hi3861 -- HI3861_PORT=/dev/ttyUSB1,或修改实例的[flash].serial。

如果离线或必须使用厂商 SDK 的 loaderboot,可把它复制到build/hi3861/loader.bin,或用:

python3 tools/boards/hi3861_flash.py prepare --loader-source /path/to/loader.bin
python3 tools/boards/hi3861_flash.py flash --port /dev/ttyUSB0 \
  --loader build/hi3861/loader.bin

厂商的 HiBurn/DevEco 路线同样有效:选择 kernel A 分区写入build/hi3861/handoff/a20os.hupg;工具若要求地址,使用 Flash 偏移**0x00D000**。不要写 0x0,那会覆盖 ROM 之后的 FlashBoot。工具若只接受整片 allinone/burn 镜像,必须先用厂商 SDK 生成包含原厂 loaderboot、 FlashBoot 和 NV 的完整镜像,再把本文件作为 kernel 部分替换;本仓库不提供这些厂商二进制,也不猜测其分区偏移。启用安全启动或 Flash 加密的板卡只能走匹配其 eFuse/密钥配置的厂商流程。

定时器与中断参数

下表的值来自板载 LiteOS SDK 的二进制和源码(libbsp_base.o、liblitekernel_base.o、include/hi3861_platform_base.h 以及vendor/hisilicon/hispark_pegasus/demo/interrupt_demo),不是试出来的:

参数 值 依据
timer 基址 0x40050028(timer 2) g_timer_property[2],与官方 interrupt_demo 一致
装载/当前值/控制/EOI/状态 0x00/0x04/0x08/0x0C/0x10 hi3861_platform_base.h
时钟 24 MHz 晶振 HI_TIMER_CLOCK_BASE;40 MHz 晶振板需按实测调整
tick 100 Hz(ARCH_TIMER_FREQ=100,装载 240000) 1 kHz 时 tick handler 与周期相当,会在 __switch 的 ret 前反复进中断
中断号 28 g_timer_property[2].irq
控制寄存器 0x3:bit0 使能,bit1 置 1 为 32 位重装载(否则是 free-run),bit2=0 不屏蔽中断 hwtimer_set_oneshot/hwtimer_enable 和官方 interrupt_demo
中断使能 mie bit 28 OsIrqEnable:IRQ ≤ 31 用 mie,> 31 用 CSR 0xbe0
中断优先级 CSR locie0(0xbc0)bits [11:8] = 2 LOS_AdapIrqEnable:IRQ 26–33 对应 0xbc0,每 4 位一个优先级,取值 1–7
时钟门控 CLDO_CTL_CLKEN(0x40010030)bit 8 hi_hwtimer_init_new:timer 1 用 bit 7,timer 2 用 bit 8;timer 0 没有这段门控代码
清中断 读 0x0C(EOI) hwtimer_lisr

串口、启动和可观察验收

UART0 使用 GPIO3=TX、GPIO4=RX,115200 8N1、无流控,3.3 V TTL 电平, TX/RX 交叉并共地,不连接 RS-232 电平。开发板若已把 UART0 接到 USB-UART 桥,直接使用桥接串口;否则使用外置 3.3 V USB-UART。按实际设备替换 tty:

picocom --baud 115200 --flow n /dev/ttyUSB0
# 或在打开串口后按开发板复位,再运行实例控制台检查:
tools/a20 console hi3861 --serial /dev/ttyUSB0

实例没有声明自动复位命令,console 会打开串口、等待启动标记,然后注入info、heap、ticks、tasks、test。开始监听后手动按 RESET;如果先复位再启动控制台,会错过一次性的启动日志。

预期看到:

A20OS RV32 M-mode MCU board=hi3861
[BOOT] scheduler initialized heap=... bytes
[MCU TEST] preemption=irq-return
[MCU TEST] PASS heap atomics timer sleep context-switch completion worker=...
A20OS MCU READY
help: help info heap ticks tasks test reboot
a20>

help、info、heap、ticks、tasks、test、reboot 是当前命令。它们来自仓库已有的 MCU 命令行实现kernel/arch/riscv32/mcu/main.c,不是重新实现的厂商 shell。test 会检查堆读写、软件原子、同步对象、定时睡眠、上下文切换和 worker 进展;如果没有主动让出 CPU 的忙循环仍能让 worker 前进,说明 IRQ 返回点抢占生效。

出现 [RV32 MCU] TRAP cause=... pc=... addr=...、panic、看门狗复位或只有镜像校验成功而没有启动标记,均不能记为实板启动通过。日志保存在.kernel-build/hi3861/console.log;构建输出中的 SHA256 和 image.json才是该次镜像的身份,不能用旧日志代替当前提交。

为什么没有 Alpine/musl shell

Hi3861 是 280 KiB 级 SRAM、无 MMU 的 MCU。Alpine 的 apk/musl 用户态依赖 Linux 系统调用、进程地址空间和文件系统;当前 MCU 裁剪没有这些设施,直接把 Alpine 包放到 Hi3861 上不能形成可运行的串口 shell。因此这里复用的是 A20OS 已有的 MCU 内核命令行,而不是引入一个无法启动的用户态包。后续若需要更完整的 shell,应先补齐文件系统、用户态 ABI 和内存模型,而不是只复制一个 busybox 二进制。

外设驱动

MCU 镜像使用 A20OS 标准驱动模型,而不是在 board.c 里直接堆寄存器访问:

kernel/drivers/core/driver_core.c + platform_bus.c
        │  device_register / driver_register / probe / remove
kernel/drivers/<class>/hi3861_*.c      驱动:只 include driver_core.h、
        │                               driver_hwapi.h、自己的 class 头
        ▼
kernel/arch/riscv32/boards/hi3861/devices.c
        board = topology:platform_device_t + RES_MMIO
  • 驱动用 DRIVER_REGISTER() 放进 .driver_init,由 driver_core_init()注册;Hi3861 的 ldscript.ld 已加入该段。
  • 板级 hi3861_enumerate_devices() 只发布资源和 software_id;驱动 probe 通过 device_map_mmio() 取得映射,不包含任何 arch 头文件。
  • MCU 没有 devfs/sysfs,driver_class_mcu.c 只保留类发布钩子的空实现。
  • platform_match() 支持没有 firmware node 的静态板级设备:software_id与驱动的 firmware_ids 匹配,driver_data 用于区分 I2C0/I2C1、SPI0/SPI1。
设备 驱动 MMIO 资源 已实现
GPIO + pinmux hi3861-gpio 0x50006000 + 0x5000A000 方向、输出/输入、上下拉、复用、输入使能;15 pin
I2C0 / I2C1 hi3861-i2c 0x40018000 / 0x40019000 + CRG 7-bit 写、读、写-读,100 kHz 轮询
SPI0 / SPI1 hi3861-spi 0x40058000 / 0x40059000 + CRG 8-bit 全双工轮询,2.4 kHz–40 MHz
PWM0–PWM5 hi3861-pwm 0x40040000 + CRG duty/period 计数、启停、160 MHz 源
ADC hi3861-adc 0x40070000 + CRG 7 通道,原始码和 mV
UART0 console 仍是 arch UART 0x40008000 早期 console;尚未改成 driver_t

尚未移植:GPIO 中断模式(hi_gpio_register_isr_function 所需的 HimiDeer local vector 45 映射)、UART½ 的 driver_t、I2C 10-bit、SPI IRQ/DMA、Flash 擦写、DMA、SDIO、tsensor/cipher、Wi-Fi/BLE。

引脚复用

驱动只控制外设块,引脚复用由 GPIO/pinctrl 显式设置,和 SDK demo 一致。常用组合:

功能 设置
I2C0 gpio func 13 6(SDA)、gpio func 14 6(SCL),并 gpio pull 13 up/14 up
I2C1 gpio func 0 5(SDA)、gpio func 1 5(SCL)
SPI0 gpio func 5 3(CSN)、6 3(CK)、7 3(RXD)、8 3(TXD)
SPI1 gpio func 0 2(CK)、1 2(RXD)、2 2(TXD)、3 3(CSN)
PWM0–5 例如 PWM1 = GPIO8/GPIO10 func 5,PWM3 = GPIO0 func 4 或 GPIO6 func 5

串口驱动命令

help 会列出驱动命令;drivers 打印已注册驱动,devs 打印设备、状态和绑定的驱动。设备 probe 成功时状态为 1:

a20> drivers
hi3861-gpio
hi3861-i2c
hi3861-spi
hi3861-pwm
hi3861-adc
a20> devs
hi3861_gpio state=1 drv=hi3861-gpio
...

常用冒烟命令:

gpio set 9 1            # 先把 GPIO9 mux 回 GPIO,输出高
gpio get 9
gpio pull 9 up
gpio func 6 3           # GPIO6 -> SPI0_CK
adc 0                   # raw/mV
pwm 1 250 1000          # 先把 GPIO8/10 mux 成 PWM1;duty 250 / period 1000
pwm stop 1
i2c scan 0              # I2C0 扫描 0x08..0x77
i2c rd 0 0x50 0x00 4
spi loop 0              # SPI0 MOSI/MISO 短接后回环

验证

# 驱动寄存器级主机测试(probe、GPIO/I2C/SPI/PWM/ADC 编程、匹配规则)
python3 -m unittest tools.tests.test_hi3861_drivers tools.tests.test_platform_bus_match

# 构建/打包;实板用上面的 drivers/devs/… 命令验收
tools/a20 package hi3861

主机测试把每个 platform resource 映射到普通内存,包含真实驱动 .c,因此能验证寄存器序列和错误路径;它不能替代实板的总线电气、时钟门控和引脚复用检查。QEMU 没有 Hi3861 模型,qemu-virt-riscv32-mcu 只用于内核/CMSIS 回归。

故障与边界

现象 检查
构建找不到 RISC-V 编译器 riscv64-unknown-elf-gcc 前缀、binutils 和 RV32IMC 多库;必要时设置 RISCV_ELF_PREFIX
打包报入口/加载范围错误 确认 BOARD=hi3861、PROFILE=mcu,入口应为 0x0040D3C0,负载不得越过 kernel A 的 912 KiB
写入后没有启动日志 确认写入的是 kernel A 0xD000、a20os.hupg 带 0x3c0 头、原厂 FlashBoot 未被覆盖、UART0 接线和波特率正确
有早期日志但 a20> 不出现,且反复在 __switch 的 ret 进中断 检查 timer 是否真的在计数:timer 0 没有 CLDO_CTL_CLKEN 门控,SDK 只给 timer ½ 开时钟;本移植使用 timer 2 + bit 8
只有一个任务可运行时 tick 仍频繁抢占 kernel_preempt_at_irq_return() 在 proc_runq_load_sum()==0 或任务尚未 proc_task_first_entry() 时不做抢占
循环重启或运行一段时间后复位 首先检查是否仍在运行原厂看门狗或写入了错误分区;内核在 early init 中关闭 WDT reset select,但原厂 FlashBoot 仍可能复位
串口键入无响应 先输入 help 并回车;确认终端没有流控、没有其他程序占用同一 tty
需要恢复原固件 用写入前保存的整片备份和厂商工具恢复;不要用 kernel-flat.bin 或 a20os.hupg 当整片镜像

内核镜像已经编入 RV32 flat-program 基础设施(U-mode 入口、按 manifest 生成的 Native syscall 子集、a20_flat_space)。同一套 CMSIS-RTOS2 Native 后端已在 QEMU 的 qemu-virt-riscv32-mcu 上跑通实验 4.1–4.5:

tools/a20 test qemu-riscv32-mcu
# [4.5] PASS create=1 setprio=1 lock=1 inherit=1 chain=1 init=1
# [DEMO] experiments 4.1-4.5: PASS

Hi3861 板默认不打开 CONFIG_MCU_USER_DEMO,因此实板仍先进入现有串口 shell。确认 U-mode 行为后,用同一个 make 变量构建实验镜像:

tools/a20 package hi3861 -- HI3861_LITEOS_DEMO=1
tools/a20 flash   hi3861 -- HI3861_LITEOS_DEMO=1

预期串口输出包含 [4.1] PASS、[4.2] PASS、[4.3] PASS、[4.4] PASS、[4.5] PASS 和 [DEMO] experiments 4.1-4.5: PASS。若实板在进入 U-mode 时停住,重新执行不带 HI3861_LITEOS_DEMO=1 的 tools/a20 flash hi3861 即可回到纯 shell 镜像;烧录工具只写 kernel A(0xD000),不会动 FlashBoot 和 NV 分区。

当前没有 SMP、MMU、用户态隔离、Flash 写入、Wi-Fi/BLE、USB CDC、RTC 或持久化文件系统。内核能打印、计数器增长或一次镜像校验通过,都不等于这些外设已经接管。实板验收至少应覆盖:冷启动到 shell、test 通过、串口键入回显、reboot 后再次启动,以及从备份恢复原厂固件。

实现与参考