跳转至

LS2K1000-DP-V10 / LoongArch LA264

本页适用于已验收的 **LS2K1000-DP-V10、Loongson-2K1001/LA264、1 GiB RAM**板型及其厂商 U-Boot/Linux 启动环境。不是龙芯 2K0300 的部署流程,也不适用于其他使用“2K1000”名称但指令集、固件或内存布局不同的板子。

A20OS 在此板已有真机验收:RAM-only shell、四级用户页表/TLB refill、系统调用、本地定时器、单核抢占/超时/idle 唤醒、UART0 LIOINTC 中断,以及 SATA/ext4 只读路径。 GMAC 无网线探测与 link-down 集成已验收;网络数据传输、PCI 配置和 SMP 尚未完成验收。

系统配置与硬件边界

项目 当前实现
CPU LoongArch LA264;默认 NR_CPUS=1,板级没有 SMP 启动操作
RAM 硬件 1 GiB;A20OS 只使用物理 0x00200000..0x0b000000 安全窗口,DTB 只能收窄
装载/入口 cached DMW 0x9000000002000000,对应物理 0x02000000
RAM / MMIO 别名 RAM 为 VSEG9 cached;MMIO 为 VSEG8 uncached
DTB 缓冲 0x900000000a000000;板级入口从此处读取固件 DTB
UART NS16550A,物理 0x1fe20000,115200/8N1;正常配置使用 LIOINTC,cooperative 配置轮询
timer rdtime.d,100 MHz;正常配置支持单核抢占
GMAC 0x40040000/0x40050000,DWMAC1000;embedded 驱动、轮询数据面,未验收收发
AHCI 0x400e0000,仅 STORAGE_READ_ONLY=1 配置开放,轮询,保留 U-Boot 建立的 PHY 链路
电源管理 poweroff/reboot 回退为停机;恢复通常需要物理复位

内存窗口避开显示缓冲与厂商固件驻留区,不因 DTB 声明完整 1 GiB 而扩大。链接脚本检查内核末尾不越过安全上限。LoongArch 编译使用 -mstrict-align;不能把厂商盘上的二进制直接当成兼容程序。已有外部程序验收使用相同的严格对齐条件。

依赖与恢复基线

以下包名以 Debian 13 为例,Python 需为 3.11 或更新版本:

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  build-essential git curl ca-certificates xz-utils file python3 \
  dosfstools e2fsprogs mtools util-linux openssh-client minicom picocom \
  gcc-loongarch64-linux-gnu binutils-loongarch64-linux-gnu libc6-dev-loong64-cross

Ubuntu 24.04 不提供上述 LoongArch 交叉 GCC 包;不能跳过工具链继续构建。可改用 Debian 13 构建环境,或自行安装龙芯匹配的 LoongArch64 Linux 工具链,确保 loongarch64-linux-gnu-gcc、objcopy、readelf 及交叉 libc 头位于搜索路径。

在已取得的 A20OS 源码根目录更新子模块;以下步骤假定当前目录包含仓库 Makefile:

git submodule update --init --recursive

尚无 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 loongarch64-unknown-none

文件上传示例使用能访问厂商 Linux 的网络和 SSH;缺少 SSH 时须自行准备等效的非覆盖式文件传输。其他宿主选项见构建指南。

板端应先能启动原厂 Linux,并能进入厂商 U-Boot 控制台。已验收固件为 2022.04-v2.1.0-00583-g2ed41674;下面的 sf read <地址> dtb是此固件按分区名读取的语法,不能不经核对地套到通用 U-Boot。串口使用原厂 Linux 可登录的同一调试接口,115200/8N1、无流控;具体连接器电平/引脚依板卡接口核实,TTL 与 RS-232 不能混接。

试启动前在厂商 Linux 中保存恢复资料,并把整份资料复制到板外:

(
set -eu
mkdir -p a20-recovery
cat /proc/mtd > a20-recovery/mtd-layout.txt
cat /proc/cmdline > a20-recovery/linux-cmdline.txt
cp /sys/firmware/fdt a20-recovery/runtime.dtb
awk -F: '/^mtd[0-9]+:/ {print $1}' /proc/mtd | while read -r part; do
  dd if="/dev/$part" of="a20-recovery/$part.bin" bs=64K
done
(cd a20-recovery && sha256sum *.bin runtime.dtb mtd-layout.txt linux-cmdline.txt > SHA256SUMS)
(cd a20-recovery && sha256sum -c SHA256SUMS)
)

这些命令只读取 MTD,但恢复目录需要足够空间;确认所有读取成功、哈希校验通过,再将目录复制到独立主机或另一块介质。记录原 /boot/uImage 的校验值和 U-Boot 环境输出。只有同盘副本不能应对系统盘损坏。

本页部署仅向 RAM 装载 A20OS。保持 /boot/uImage 和厂商启动环境不变,不执行 saveenv、sf write、sf erase,不尝试从运行中的 A20OS 跳回 U-Boot。

构建与产物

当前仓库没有预置的 LS2K1000 实例或完整 a20 deploy 路径;ls2k0300 实例属于另一颗 SoC,不能代用。使用板级 Make 目标:

make ARCH=loongarch64 BOARD=ls2k1000 ABI=linux BRINGUP=1 \
  RAMFS_USER=1 DRIVER_DEPLOYMENT=embedded kernel-only

LS2K_BUILD_DIR=$(make -s ARCH=loongarch64 BOARD=ls2k1000 ABI=linux BRINGUP=1 \
  RAMFS_USER=1 DRIVER_DEPLOYMENT=embedded print-build-dir)
sha256sum "$LS2K_BUILD_DIR/kernel.bin"
loongarch64-linux-gnu-readelf -h "$LS2K_BUILD_DIR/kernel.elf"

kernel.bin 是交给 U-Boot go 的原始镜像,kernel.elf 用于符号和异常定位;二者位于查询得到的目录,不要手写会随构建选项变化的 .kernel-build 路径。BRINGUP=1 RAMFS_USER=1 提供 RAM 用户态;不带 RAMFS_USER=1 的 bringup 只执行早期自检,不会产生 shell。

将镜像以新名字放到厂商根文件系统,不替换原内核。例如宿主执行:

scp "$LS2K_BUILD_DIR/kernel.bin" root@BOARD_IPV4:/boot/a20os-ls2k1000-bringup.bin

BOARD_IPV4 必须替换为实际地址;厂商 Linux 中对上传文件重新计算 SHA-256,与宿主结果相同后执行 sync。文件长度和哈希随构建现算,不使用旧候选的固定数值。

RAM-only 启动与串口检查

打开串口并记录完整日志。此厂商固件用小写 c 进入控制台,倒计时窗口极短;应在物理复位前准备连续发送 c。不要用 Ctrl-C 中断 USB 初始化。

仓库提供 tools/boards/ls2k1000-uboot-stop.runscript,适用于**当前停在厂商 Linux shell**的会话:它先发送 sync/reboot,看到菜单提示后重复发送 c,最后等待 =>。例如先把 minicom 的软/硬流控都关闭,再运行:

minicom -D /dev/ttyUSB0 -b 115200 -8 -o -S tools/boards/ls2k1000-uboot-stop.runscript

若已在 U-Boot,不运行这个会发送 Linux 命令的脚本,直接继续。以下全部为 RAM 试启动,不保存环境:

setenv fdt_addr 0x900000000a000000
sf probe
sf read ${fdt_addr} dtb
scsi reset
ext4load scsi 0:1 0x9000000002000000 /boot/a20os-ls2k1000-bringup.bin
go 0x9000000002000000

每一步成功才继续,尤其核对 ext4load 的长度及所读文件;go 没有替你验证 Linux Image/ELF 格式。这里使用板级入口约定,不用 booti,也不把内核装载地址当作 DTB。若实际根盘不是 scsi 0:1,先从厂商配置确认设备/分区,不盲改去读取其他盘。

正常配置应看到 A20OS 内存初始化、LS2K1000 timer interrupts enabled、System ready 和 RAM shell。进入 shell 后检查:

cat /etc/os-release
cat /proc/interrupts

UART0/cascade 计数应随接收增加,spurious/storm 不应持续增加。定时器重复触发、异常返回、单核抢占和 idle/timeout 唤醒已有验收基线;具体应用仍应在当前候选上复测,不能仅凭 System ready 判断。

只读 SATA 配置

该配置与 cooperative 恢复配置互斥,须独立构建、独立命名上传:

make ARCH=loongarch64 BOARD=ls2k1000 ABI=linux BRINGUP=1 \
  RAMFS_USER=1 DRIVER_DEPLOYMENT=embedded STORAGE_READ_ONLY=1 kernel-only

用相同选项执行 make -s ... print-build-dir 查询产物目录,上传为/boot/a20os-ls2k1000-storage-ro.bin;启动步骤与前节相同,仅替换 ext4load 文件名。必须保留 scsi reset:A20OS 的平台路径跳过首次通用 AHCI reset/COMRESET,继承 U-Boot 已建立的 SATA PHY 链路。AHCI/LIOINTC 中断保持屏蔽。

已有 QEMU 和真机验收包括 IDENTIFY、容量识别、MBR 0x83 主分区、干净 ext4 挂载 /extra、只读写封锁及大文件读取。AHCI 命令层、分区包装层和 VFS 都拒绝写入。 ext4 带 needs_recovery 时必须拒绝挂载并继续 RAM shell,不回放日志,也不修复厂商根盘。不要为了挂载方便从 A20OS 清除恢复标志。磁盘/分区容量从当前探测结果确认,不要求与某次验收使用的磁盘扇区数相同。

中断、网络与兼容性限制

LIOINTC 与 QEMU 的 PCH-PIC/EIOINTC 不同,以下为本板厂商 DTB/Linux 与真机核对的值:

项目 值
主寄存器 物理 0x1fe01400
CPU0 / CPU1 pending 0x1fe01040 / 0x1fe01140
父中断 HWI1,ESTAT.IS[3]
UART0 source / CPU0 route 0 / 0x21
GMAC0 / GMAC1 sources 12,13 / 14,15
AHCI source 19,当前屏蔽

寄存器 bank0 的 route 为 +0x00..0x1f、enable/status 为 +0x24、 set 为 +0x28、clear 为 +0x2c、polarity 为 +0x30、edge 为 +0x34; bank1 对应偏移再加 0x40。与本板实况冲突的 0x1fe11400/0x1fe11040不用于实现。正常初始化清除固件遗留设备使能,仅重新开放 UART0;其他源不能在没有针对性设备验收时开放。

GMAC 使用 16 字节基本 ring 描述符、私有锁、缓存同步和轮询, PHY carrier down 作为非致命状态向 lwIP 报告。无网线探测已验证; link-up、DMA 收发、ping/socket 流量尚未验证。PCI 仍缺 Loongson 配置窗口前端,板级不调用 QEMU ECAM 枚举。硬件双核不等于当前 A20OS 支持 SMP。

故障与恢复

  • 无 U-Boot 输出:先恢复原厂可用的供电/串口连接,核对终端波特率和流控。
  • 截停失败:复位前准备小写 c;脚本只在厂商 Linux shell 开始执行。
  • sf read/ext4load 失败:停止,不执行 go;检查固件语法、分区名和新文件路径。
  • 早期异常:保存完整 CSR/寄存器日志,用同一构建目录的 kernel.elf 做 addr2line;核对加载地址、安全内存窗口与严格对齐,不扩大可用 RAM 掩盖故障。
  • cooperative 兜底需另加 COOPERATIVE_BOOT=1 构建;它关闭抢占定时器、轮询 UART,输入须限速,突发接收可能丢字。不能与 STORAGE_READ_ONLY=1 合用。
  • A20OS 挂起或结束:物理复位。未保存环境、未覆盖原内核时,默认路径仍启动原厂 Linux。

恢复验收应重新启动厂商 Linux、核对原 /boot/uImage,并确认恢复资料校验通过。本页没有提供自动 Flash 重刷工具;如原启动链已损坏,使用板厂匹配的恢复方法及板外备份。构建门禁为 make check-ls2k1000-build;接口说明见板级接口参考、其他平台约定见平台约定。