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¶
部署链为:
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 控制台并启动记录,再给板上电:
手工重置/上电需要在串口检查的 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 自动启动是默认路径。卡准备好并插回板后,需要定位载入失败时,使用:
命令启动后重新上电/复位板子;它在同一串口会话截停 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 对照使用:
两个实例共用板级输出文件名,后一次打包替换镜像和 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 下载。
- PINE64 Ox64 文档:板型、引脚、UART 下载、固件布局和接线。
- OpenBouffalo 固定 v1.0.1 release:所用三份 SPI 固件。
- OpenBouffalo Buildroot 板级配置:默认启动脚本、U-Boot 配置和 M0 PSRAM 保留区补丁。
- BL808 Linux DTS:D0 ISA、Sv39、timebase、UART3、PLIC 和非一致性 DMA。
- OpenBouffalo Linux SDHCI与 BL808 DT:兼容串、标准寄存器、版本/电压/忙状态差异。
- Bouffalo SDK 的 GLB 寄存器与 SDH 寄存器:板级 clock/reset/pinmux/pad clock。
- Zephyr BL808 SDHC 驱动:厂商 TX 时钟和初始脉冲的交叉核对;A20OS 不使用其 ADMA 路径。
- Bouffalo UART 驱动、NuttX UART 寄存器:FIFO、访问宽度和 RX 中断。
- 平台文档约定、实例工具。