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),然后执行:
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 变量构建实验镜像:
预期串口输出包含 [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 后再次启动,以及从备份恢复原厂固件。
实现与参考¶
- 板级资源、UART/定时器寄存器和复位路径:
kernel/arch/riscv32/boards/hi3861/ - 公共 RV32 M-mode 执行层:
kernel/arch/riscv32/mcu/ - 实例裁剪选择:
components/trim.toml的profile.mcu.boards - 镜像打包与校验:
tools/boards/hi3861.py - HiSilicon Hi3861V100 产品页:https://www.hisilicon.com/cn/products/connectivity/short-range-IoT/wifi-nearlink-ble/Hi3861LV100
- OpenHarmony Hi3861V100 SDK(FlashBoot、分区表和 UART 寄存器):https://github.com/openharmony/device_soc_hisilicon/tree/master/hi3861v100
- 独立 Hi3861 启动与寄存器说明:https://github.com/koendv/hi3861_notes
- Zephyr Hi3861 移植(timer、pinctrl 和 SoC 地址参考):https://github.com/xingrz/zephyr/tree/hi3861/soc/riscv/riscv-privilege/hi3861