跳转至

PINE64 Ox64 / BL808

默认实例 ox64 在 BL808 的 D0 C906(RV64,Sv39 MMU) 上运行 A20OS 单核内核初始化配置。ox64-nommu 在同一 D0 上使用 satp=Bare,用于 RV64 MMU/NoMMU 对照。两者都通过 OpenSBI 进入 S-mode,检查早期内存分配后结束;没有交互 shell、持久 rootfs 或完整 Linux 用户空间。构建、封装及宿主协议测试可执行,尚未在 Ox64 实机验证。源码提供的寄存器与启动接口不能代替串口验收。

串口交互 shell 配置

ox64-shell 实例嵌入静态链接的 /bin/init、sh(BusyBox)和基本命令工具集。它采用完整用户态启动路径(bringup=false、ramfs_user=true),不需要根磁盘。默认嵌入 init、sh、help、ls、cat、ps、sleep、echo、uname、mkdir、rm、cp、sync、poweroff、reboot 等基础命令。启动时保留 RAMFS 的 /bin,不会把含内核与 DTB 的启动 FAT 分区自动覆盖挂载到这里。原 ox64 实例仍用于内核初始化验收,二者不能互换验收标准。

tools/a20 prepare ox64
tools/a20 build ox64-shell
tools/a20 package ox64-shell
tools/a20 console ox64-shell

SD 镜像是 build/ox64/a20os-ox64-shell-sdcard.img,部署时使用tools/a20 deploy ox64-shell --media-device /dev/实际卡设备。打包会重新生成所选实例对应的内核与 handoff,公共 handoff 目录不得混用旧包。

串口接线、电平、波特率和固件要求沿用本文。System ready 只表示内核就绪;验收还须看到 init 启动交互式 shell,实际输入并检查输出:

echo A20_SERIAL_OK
uname -a
ls /bin
cat /proc/meminfo
mkdir /tmp/check
echo hello > /tmp/check/message
cat /tmp/check/message
rm /tmp/check/message
sync
poweroff

文件系统为 RAM-only,重启后丢失写入。最小用户构建仅编译嵌入命令,不构建 fastfetch、FFmpeg 或完整发行版。这个配置不包含 SSH 服务,也不承诺网卡、显示或音频可用。当前状态为交叉构建与封装检查;板上执行仍须实机验收。

Ox64 只使用 D0/RV64 Sv39 配置;M0/E907 不运行此用户态。打包器依据内核包含 BSS 的完整 Image footprint 检查 0x50200000..0x53800000,DTB 位于0x53800000,0x53f00000..0x54000000 始终保留给 M0。越界会拒绝打包。

核心与设备范围

项目 配置及边界
D0 C906 RV64IMAFDC、Sv39;内核装载地址 0x50200000
PSRAM 物理 0x50000000..0x54000000,共 64 MiB;末尾 1 MiB 为 M0 固件保留
内核内存 从 DTB 读取 RAM、memreserve、reserved-memory,保留 DTB 自身;保留扣除固件占用后的多个可用区间,并限制在 64 MiB 板级窗口内
控制台 BL808 UART3 0x30002000、32 位 FIFO 寄存器;不是 16550。保留 U-Boot 的时钟与波特率配置,支持轮询收发及 RX FIFO 中断
中断/时钟 D0 PLIC 0xe0000000,UART IRQ 20;time CSR / SBI 定时器,DTB timebase 1 MHz
SD bflb,bl808-sdhci,0x20060000;A20OS sdhci 驱动提供 1-bit、3.3 V、最高 24 MHz 的 PIO 读写,尚未实机验证
USB / Ethernet / Wi-Fi A20OS 尚无 BL808 对应驱动;固件装载能力不等于内核接管后可用
显示 / 音频 裸板没有 HDMI、显示屏或扬声器;I2S 等接口可接扩展设备,当前没有对应扩展模块驱动
M0 E907(RV32) 无 MMU,M/U-mode;当前没有该核的 A20OS RV32 NoMMU 移植,上述 Ox64 实例都不运行在此核
LP E902 不作为 A20OS 执行核

M0 使用现有 OpenBouffalo 固件,承担跨核外设中断转发等平台工作。它与 D0 不是对称多核,不能设置 machine.smp=2 将其并入 RV64 内核。现有通用 RV32 内核依赖 S-mode/SBI/PLIC;E907 的 M-mode/CLIC、异常入口和片内 SRAM 布局需要独立实现。ox64-nommu 只表示 D0 RV64 不启用分页,不表示这些 RV32 工作已完成。原有 m0sense-bl702-probe 是另一块 BL702 板的早期探针,也不替代 E907 的操作系统移植。

BL808 的 DMA 为非一致性内存路径;SDHCI 当前仅使用 PIO,没有发布 DMA 或网络驱动能力。内核保持 OpenSBI 提供的 T-Head 初始化,不使用 C906 的旧版向量扩展。电源关闭依赖固件 SBI 支持;某些固件可能只停机,板上电源仍在。

可选显示与音频设备

PINE64 官方硬件说明将麦克风和扬声器列为可选摄像头模块上的设备,GPIO 还可扩展 I2S。 USB-C 处的双 lane MIPI 接口是摄像头输入,不能视为已连接的显示输出。接入屏幕或音频模块时,需要其型号、总线、引脚、时钟、供电及复位描述;裸板配置不会仅凭 BL808 数据手册中的外设名称创建显示或音频设备。现有 RAM 串口 shell 不依赖这些附件,BL808 非一致性 DMA 与跨核外设所有权仍需在相应原生驱动中解决。

SD 存储驱动契约

公共 kernel/drivers/block/sdhci_core.c 实现 SDHCI/SD 卡协议,sdhci.c 负责固件节点匹配、块 class 和受管资源;arch/riscv64/boards/ox64/storage.c 负责 GLB 时钟门/复位、GPIO0..5 引脚、TX 时钟和厂商初始 80 时钟脉冲。选择 OpenBouffalo 固件已建立的 WIFIPLL/96 MHz 时钟源,使用 SDHCI 的老式分频器取得 375 kHz 初始化时钟和 24 MHz 数据时钟;没有可用固件 PLL/电源状态时不承诺启动。控制器没有标准版本寄存器,板层显式指定旧分频格式,不读取不存在的寄存器。

旧 OpenBouffalo DT 只发布 0x100 字节的标准 host 范围;板层单独映射已核实的厂商寄存器范围,公共驱动不会越过 DT resource。轮询 PIO 不依赖 M0 的 SD IRQ 转发,也不把普通内存交给 DMA;未知 IRQ domain 可按 polling 驱动契约省略,错误的 IRQ 描述仍拒绝绑定。

支持 SDSC、SDHC/SDXC 的容量解码、512 字节扇区读写和写卡编程完成检查。不支持 eMMC、SDIO、SDUC、4-bit、1.8 V/UHS、DMA、热插拔自动重枚举或睡眠恢复。初始化完整成功才发布块设备;所有等待有截止时间。遵守 CSD 永久/临时写保护、固件 read-only与内核只读存储配置;传输错误后停止后续 I/O,需重新绑定再初始化。默认实例依旧只做内核初始化后关机,不会因为加入存储驱动就自动提供 shell 或 rootfs。

python3 -m unittest tools.tests.test_sdhci 用宿主硬件模型检查生产协议和板级寄存器操作;实际卡上的读数据哈希、专用测试分区写入/读回、长时间稳定性仍待实机验收。[SDHCI] ... sectors 只表示识别完成,不能单独作为存储通过的证据。

板型和接线

使用带 **16 MiB SPI flash、64 MiB PSRAM 和 microSD 卡槽**的 Ox64。 2 MiB flash 版本不提供本页 SD 部署路径,不能刷入下列约 15 MiB 的固件布局。

准备 microSD 卡、读卡器、5 V 电源、3.3 V 逻辑 UART 适配器和三根杜邦线。 UART 信号禁止使用 RS-232 电平或 5 V 逻辑。USB-C/microUSB 用于供电,不能假设出厂固件会通过同一个 USB 接口提供串口或 UF2 磁盘。

用途 Ox64 输出 TX → 适配器 RX Ox64 输入 RX ← 适配器 TX 串口速率
D0 U-Boot / A20OS 控制台 GPIO16,物理 pin 32 GPIO17,物理 pin 31 2000000,8N1
ROM SPI 编程 GPIO14,物理 pin 1 GPIO15,物理 pin 2 恢复脚本默认 115200

GND 接 pin 3、33 或 38。控制台和 ROM 编程是两组不同引脚,恢复完成后必须换线。 PINE 文档列出 Pico UART bridge、部分 FT232H/CP2102 的可用情况;FT232RL 不适合 BL808 ROM 下载,CH340 的结果因型号而异。选择适配器时同时核对 ROM 下载兼容性和主机驱动是否支持运行时 2 Mbaud。CP2102 在 ROM 下载时可能只能使用 115200。

保留 SPI 固件并准备 SD

部署链为:

ROM → SPI M0 lowload + D0 lowload → OpenSBI + U-Boot → SD boot.scr → A20OS D0

SD 镜像只包含内核、匹配 DTB、脚本和分区表,不初始化 SPI。已经能正常启动兼容 OpenBouffalo 固件的板无需重刷。未知出厂固件若只有 MCU 演示程序、没有 OpenSBI/U-Boot,应先执行下一节的 SPI 初始化,再使用 SD。

Linux 主机需要 RV64 裸机 ELF 工具链、Python 3.11+ 和 FAT 工具;SPI 固件直接使用经校验的发行文件,无须编译厂商 SDK。Debian/Ubuntu 安装:

sudo apt-get install build-essential git curl ca-certificates python3 python3-venv \
  gcc-riscv64-unknown-elf binutils-riscv64-unknown-elf dosfstools mtools

安装 rustup 后配置仓库指定的 Rust 1.96.0;若尚无 rustup,可先执行下面前两条命令。已有 rustup 时可跳过安装器:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/a20-rustup-init.sh
sh /tmp/a20-rustup-init.sh -y --profile minimal --default-toolchain 1.96.0
. "$HOME/.cargo/env"
rustup toolchain install 1.96.0 --profile minimal
rustup target add --toolchain 1.96.0 riscv64imac-unknown-none-elf riscv64gc-unknown-none-elf

下列仓库命令均在 A20OS 源码根目录执行;首次构建先运行 git submodule update --init --recursive。主机 Python 必须为 3.11 或更新版本,可用 python3 --version 确认。首次下载源码、Rust 组件和 Cargo 依赖需要联网。

tools/a20 check instances/ox64.toml
tools/a20 prepare ox64
tools/a20 build ox64
tools/a20 package ox64

prepare 下载固定 OpenBouffalo v1.0.1 release,验证归档与三份固件的 SHA-256,从其固件容器提取匹配的 Ox64 DTB,补入 0x53f00000..0x54000000 的 M0 PSRAM 保留区。它只创建普通文件,不打开串口、不刷 SPI、不写物理卡。

输出:

  • build/ox64/firmware/:固定 SPI 恢复文件、匹配 DTB、哈希清单和 RECOVERY.txt。
  • build/ox64/handoff/:kernel.elf、带 RISC-V Image 头的 kernel.bin、DTB、uboot.cmd 和清单。
  • build/ox64/a20os-ox64-sdcard.img:128 MiB 普通文件镜像;首个可启动 FAT32 分区从 8 MiB 开始。
  • 镜像同名 .json:输入固件、内核、FAT 文件与镜像校验值。

固定固件的默认 bootcmd 执行 distro_bootcmd,扫描 MMC 可启动分区的 boot.scr。镜像脚本在执行 booti 前检查两个文件的大小和 CRC32;DTB 放在 0x53800000,封装时检查它与包含 BSS 的整个内核 Image 范围及 M0 保留区不重叠。固定旧版 U-Boot 没有 crc32 -v,脚本使用其原生 crc32 写入临时地址后比较结果。更换 SPI U-Boot 后,应使用下述自动交接或逐项验证兼容性。

先核对读卡器设备身份并卸载卡上所有分区。把占位符替换为实际整卡设备:

tools/a20 deploy ox64 --dry-run --no-build \
  --media-device /dev/disk/by-id/REPLACE_WITH_OX64_SD --no-console
sudo tools/a20 deploy ox64 --no-build \
  --media-device /dev/disk/by-id/REPLACE_WITH_OX64_SD --no-console

第二条会覆盖所选卡的分区表和前 128 MiB 内容。退出并安全移除卡,插入 Ox64;先连接 D0 控制台并启动记录,再给板上电:

tools/a20 console ox64 --serial /dev/ttyUSB0

手工重置/上电需要在串口检查的 120 秒超时内完成;实例没有假定适配器的 DTR/RTS 能复位板子。验收须看到 [Ox64] D0 C906、[FDT] RAM range、System ready (bringup, no userspace) 和分配器自检的 part ok。只看到 U-Boot、Starting kernel 或脚本自己的 echo 不代表 A20OS 已启动。日志保存在 .kernel-build/console/ox64.log。

首次初始化 / 恢复 SPI

此过程用于没有兼容启动链或 SPI 固件损坏的 16 MiB flash 版本。它会覆盖 SPI 中的启动固件;已有定制固件应先通过原有工具备份,保留原文件。prepare 仍只下载文件,下面默认命令也只显示计划。

安装 PINE 文档采用的 bflb-iot-tool,例如使用独立 Python 环境:

python3 -m venv build/ox64/flasher-venv
build/ox64/flasher-venv/bin/pip install bflb-iot-tool==1.10.0 \
  "standard-telnetlib==3.13.0; python_version >= '3.13'"
python3 tools/boards/ox64.py recovery --port /dev/ttyUSB0

Python 3.13 移除了 telnetlib,上面的条件依赖为旧版下载工具补齐该模块; Python 3.12 及以前会跳过它。可用 build/ox64/flasher-venv/bin/bflb-iot-tool --help先验证工具能启动,再连接硬件。

确认板型,断电,将 UART 换到 GPIO14/15,接公共地;按住 BOOT,接通电源或按 RESET,然后松开 BOOT。关闭占用这个串口的监视程序。明确请求写入时执行:

python3 tools/boards/ox64.py recovery --port /dev/ttyUSB0 --flash-mib 16 --execute \
  --tool build/ox64/flasher-venv/bin/bflb-iot-tool

工具按顺序调用厂商 ROM 下载协议,任何一步未确认成功都会停止。固定版厂商 CLI 部分错误仍返回退出码 0,因此包装器还要求每步出现[All Successful] 完成标志;完整输出保存在 build/ox64/recovery-logs/:

文件 SPI 地址 SHA-256
m0_lowload_bl808_m0.bin 0x0 f9d5a1b38367b0e6f85691c395caa79987dc92f8e08cad0314f39a88e86d629d
d0_lowload_bl808_d0.bin 0x100000 2a662c9467fa2dfb56f585be7d60cdfd491640360b43fd09414ff21906beba22
bl808-firmware.bin 0x800000 447d6b818d98690c9bdb13ebe4b97a75cd3642838ab535d6b389bf1e1551c6f3

下载成功后断电,确认 BOOT 已释放,UART 换回 GPIO16/17,插 SD 卡,重新上电。运行时仍使用 2000000 波特;ROM 下载速率与控制台速率无需相同。若下载失败:断电后重新进入 BOOT 模式,检查 GPIO14/15 的 TX/RX 方向、地线、独立供电和适配器兼容性;默认 115200 已适用于受限的 CP2102。串口权限不足时加入相应 dialout/uucp 组,或仅为具体恢复命令提供设备访问权限。刷坏 SPI 不会删除片上 ROM,仍可通过同一 BOOT/UART 路径重试。

U-Boot 自动交接与手工排查

SD 自动启动是默认路径。卡准备好并插回板后,需要定位载入失败时,使用:

tools/a20 console ox64 --auto-handoff --serial /dev/ttyUSB0

命令启动后重新上电/复位板子;它在同一串口会话截停 U-Boot、检查文件长度和 CRC32,再执行包内 uboot.cmd,不再次写 SD。a20 deploy --no-build 只跳过构建,仍会执行已声明的介质写入;因此重新启动板子时用 console。

手工操作时,上电后在 5 秒倒计时内按键,确认 mmc list、mmc rescan 成功, SD 第一分区包含 kernel.bin 与 bl808-pine64-ox64.dtb:

setenv loadaddr 0x50200000
setenv fdt_addr_r 0x53800000
setenv fdt_high 0xffffffffffffffff
fatload mmc 0:1 ${loadaddr} kernel.bin
fatload mmc 0:1 ${fdt_addr_r} bl808-pine64-ox64.dtb
fdt addr ${fdt_addr_r}
fdt print /memory
booti ${loadaddr} - ${fdt_addr_r}

逐项检查装载结果;任意失败都不继续 booti。完整尺寸/校验值见包清单和卡内boot.cmd。不要将 Image 装载地址当成 DTB,也不要传 U-Boot 的控制树内部地址。不要将 A20OS 的内核文件刷到 SPI 中的 bl808-firmware.bin 地址:两者格式和职责不同。如果没有倒计时/U-Boot 提示,应先排查供电、D0 UART 接线和 SPI 启动链。在正确的 2 Mbaud 下乱码可能是适配器限制;完全无输出也可能是 UART 接到了 ROM 引脚。

NoMMU 对照使用:

tools/a20 build ox64-nommu
tools/a20 package ox64-nommu

两个实例共用板级输出文件名,后一次打包替换镜像和 handoff 内容;部署时选择同一实例,不要用 --no-build 把上一个实例的产物当成当前配置。它仍运行 RV64 D0 和 SBI,没有获得内存隔离或 RV32 MCU 支持。

验证及一手资料

python3 tools/tests/test_ox64.py 覆盖生产 UART FIFO 路径、保留固件波特率、 M0/DTB 内存保留、无 DTB 回退、脚本头与 CRC、MBR 分区、镜像/BSS/DTB 冲突和恢复命令的默认只读行为。宿主测试不模拟 BL808 时序、PSRAM、缓存或 ROM 下载。