K3 COM260 Kit 部署 StarryOS 启动指南

文档信息

项目	内容
文档性质	K3 COM260 Kit 真板部署与启动基线
适用范围	硬件准备、StarryOS 构建、U-Boot 加载、UFS rootfs、启动验证与故障排查
成功判据	StarryOS 在真板启动并进入 `root@starry:/root #` shell

状态标签

标签	含义
`[官方资料]`	来源于 K3 COM260 用户手册或官方 BSP 资料
`[待确认]`	资料尚不足，或仍需结合当前制品、分区和真板继续核对

本文只记录已有资料和已完成结果。不同技术来源存在差异时保留来源与差异；目标配置不会写成当前已生效配置。

1. 背景

1.1 平台与适配目标

[官方资料] SpacemiT K3 COM260 Kit 是 RISC-V 平台，板载 UFS 2.2 存储，启动环境包含 U-Boot。K3 是本文所针对的真板运行平台。

tgoskits 的 feat/k3-board-support 分支提供了 K3 板级支持，并已有在 K3 COM260 Kit 上构建、加载和进入 StarryOS shell 的复现记录。

本项目已经完成以下主线：

text

K3 COM260 Kit
      |
      v
U-Boot 接收内存镜像
      |
      v
StarryOS kernel
      |
      v
K3 UFS / GPT / Ext4 rootfs
      |
      v
StarryOS shell

1.2 本文解决的问题

本文用于帮助后续人员：

正确连接 K3 COM260 的供电、串口和 USB Type-C；
准备 tgoskits、Rust 和必要的构建依赖；
构建 K3 对应的 StarryOS 镜像；
通过 U-Boot 与 fastboot 将镜像加载到内存；
让 StarryOS 识别 UFS 上的 rootfs 并进入 shell；
根据已发生的失败现象排查镜像地址、root 参数、UFS 状态和默认启动路径。

本文目标是让 StarryOS 在 K3 真板启动并进入 shell，不覆盖产品化自动启动、量产刷写和性能验收。

1.3 快速开始（推荐）

第一次启动建议使用 FIT 单文件流程。完整操作只需要完成以下步骤。

第 1 步：连接硬件

text

DC 电源    ---> K3 COM260 供电
USB-TTL    ---> 12 Pin UART，查看串口输出
USB Type-C ---> Host 与 U-Boot fastboot 通信

串口参数：

text

115200 baud

第 2 步：构建 StarryOS

bash

cd tgoskits
cargo starry build \
--config os/StarryOS/configs/board/spacemitk3-com260kit.toml

确认生成：

text

target/riscv64gc-unknown-none-elf/release/starryos.uimg

第 3 步：U-Boot 接收 FIT

在 K3 的 U-Boot 命令行执行：

bash

fastboot -l 0x180000000 -s 0x04000000 usb 0

第 4 步：Host 上传 FIT

在 Host 的 tgoskits 目录执行：

bash

fastboot stage \
target/riscv64gc-unknown-none-elf/release/starryos.uimg

第 5 步：启动

回到 U-Boot 执行：

bash

bootm 0x180000000

第 6 步：确认进入 shell

串口看到以下提示即完成首次启动：

text

Welcome to Starry OS!
root@starry:/root #

如果当前分支没有生成 starryos.uimg，但生成了 starryos.bin，不要改名套用 FIT 流程；请使用第 8 章的 kernel 与 dtb 分离启动流程。

2. K3 COM260 硬件准备

2.1 供电

[官方资料] K3 COM260 Kit 使用独立 DC IN 供电。用户手册给出的电源规格为：

供电方式	规格
DC IN	`19V / 2.37A`
DC IN	`12V / 5A`

[官方资料] USB 3.0 Type-C 是 OTG 与固件升级通道，不支持作为开发板供电输入。

正确职责划分：

text

DC 圆孔电源  --->  K3 COM260 供电
USB Type-C   --->  OTG / fastboot / 固件升级数据
USB-TTL      --->  UART Console

不要只连接 Type-C 后等待开发板上电。进行加载操作时，应先保证 DC 电源稳定接入。

2.2 串口连接

[官方资料] 12 Pin 接口的完整公开定义如下，其中串口使用 Pin 3、Pin 4 和任一 GND：

Pin	信号	功能
1	`PC_LED-`	LED 负极
2	`PC_LED+`	LED 正极
3	`UART0_RXD`	DEBUG UART RX
4	`UART0_TXD`	DEBUG UART TX
5	`BMCU_ACOK`	设置为按键开机
6	`AUTO_ON_DIS`	与 `BMCU_ACOK` 短接，设置按键开机
7	`GND`	电源地
8	`PMIC_RST_Out`	复位
9	`GND`	电源地
10	`FORCE_RECOVERY`	Download
11	`GND`	电源地
12	`SLEEP/WAKE`	开机/关机

[官方资料] 用户手册要求通过 USB 转 TTL 设备连接 12 Pin 接口的 TX、RX、GND。接线时 TX 与 RX 交叉：

开发板	USB-TTL
Pin 4 `UART0_TXD`	TTL RX
Pin 3 `UART0_RXD`	TTL TX
Pin 7、9 或 11 `GND`	TTL GND

当前串口参数：

text

115200 baud

当前设备树启动参数也使用 console=ttyS0,115200。串口用于观察 BootROM 后续启动日志、操作 U-Boot 和进入 StarryOS shell。

2.3 USB Type-C 用途

[官方资料] 板载 USB Type-C 的定位是：

USB 3.0 Type-C OTG；
系统固件升级通道；
USB Gadget 通信通道；
当前流程中的 fastboot 数据连接。

当前 StarryOS 内存加载流程使用该 Type-C 连接 Host 与 U-Boot fastboot。

Type-C 不承担开发板供电。本文也不把它描述为 12 Pin 串口的替代接口。

3. 软件环境准备

3.1 仓库来源

当前资料涉及两组来源，不能混写为同一分支：

资料来源	仓库/分支	用途
K3 成功复现资料	`https://github.com/Oveln/tgoskits/tree/feat/k3-board-support`	K3 板级支持、`starryos.uimg`、`bootm` 流程
K3 与 AI runtime 复现资料	`https://github.com/Dirinkbottle/tgoskits/tree/dev`	`starryos.bin`、分离 DTB、`booti` 流程
配套运行时仓库	`https://github.com/Dirinkbottle/k3x-HERA-RT`	K3 AI runtime 相关组件
当前本地 `tgoskits`	`dev`，commit `4b232082d9cc37a286d2993d5302583ec98b0212`	当前构建与源码核对基线
当前本地 `k3x-HERA-RT`	`main`，commit `fec2ae5172577d6a06b29d35dcbbee437fe28b13`	当前配套组件基线

当前两个本地工程需要放在同一级目录：

text

workspace/
├── tgoskits/
└── k3x-HERA-RT/

旧代码曾引用绝对路径：

text

/home/inkbottle/othersrc/k3x-HERA-RT

当前环境使用的相对依赖关系为：

text

../../../../k3x-HERA-RT/

切换 feat/k3-board-support 与 dev 时，应同时核对板级配置、目标三元组和配套仓库版本，不要只替换启动命令。

3.2 Rust 环境

当前仓库的 rust-toolchain.toml 固定：

项目	当前配置
Channel	`nightly-2026-05-28`
Profile	`minimal`
Components	`rust-src`、`llvm-tools`、`rustfmt`、`clippy`
K3 bare-metal target	`riscv64gc-unknown-none-elf`

仓库资料给出的 Rust 安装入口：

bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装二进制工具：

bash

cargo install cargo-binutils

构建资料中出现两个目标：

text

riscv64gc-unknown-none-elf
riscv64gc-unknown-linux-musl

实际构建时，以所用分支的 rust-toolchain.toml、板级 TOML 和 cargo starry build 输出为准，不要仅按产物目录猜测目标。

3.3 编译依赖

仓库资料给出的基础依赖：

bash

sudo apt update
sudo apt install -y cmake make ninja-build pkg-config

当前环境第一次构建曾出现：

text

libudev-sys build failed

安装依赖：

bash

sudo apt install libudev-dev pkg-config

验证结果：

bash

pkg-config --modversion libudev

当时输出：

text

构建还要求能够找到：

text

riscv64-linux-musl-cc
riscv64-linux-musl-ar

当前环境曾使用以下兼容入口恢复 C 编译器查找：

bash

sudo ln -s \
  "$(which riscv64-linux-gnu-gcc)" \
  /usr/local/bin/riscv64-linux-musl-cc

如果构建继续提示缺少 riscv64-linux-musl-ar，应补齐所用分支要求的完整 RISC-V musl 工具链；现有记录没有保存对应 ar 工具的设置命令。

4. StarryOS K3 支持说明

4.1 板级支持内容

feat/k3-board-support 资料记录的主要支持项：

类型	模块	作用
串口	PXA UART	K3 UART 通信
块设备	K3 SDHCI	SD/eMMC 访问
块设备	K3 UFS	UFS 存储访问
网卡	K3 GMAC	千兆以太网
引脚	K3 pinctrl	K3 引脚配置
中断	APLIC	RISC-V 中断控制
指令扩展	zicbom CBO	RISC-V cache block operation 支持

当前 spacemitk3-com260kit.toml 明确启用的相关特性为：

text

ax-driver/serial
ax-driver/k3-pxa-uart
ax-driver/k3-ufs
starry-kernel/vector

因此，源码中存在某个模块不等于当前板级配置已经启用该模块。

4.2 设备树

K3 适配资料使用的设备树源路径：

text

os/StarryOS/configs/board/spacemit-k3-com260-ifx.dts

当前分离启动使用的 DTB 路径：

text

os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

设备树负责描述 K3 硬件，并通过 /chosen/bootargs 传递 console 与 rootfs 选择信息。

4.3 当前支持状态摘要

能力	说明
K3 UART	U-Boot 和 StarryOS 串口输出正常
K3 UFS	已完成初始化、GPT 识别和 Ext4 rootfs 启动
AI runner 设备节点	`/dev/k3_airunner` 存在
APLIC	K3 支持分支资料记录已增加
zicbom	K3 支持分支资料记录已增加
K3 GMAC	源码有支持项，但当前板级配置未启用，真板网络未在现有记录中验收
K3 SDHCI	源码有支持项，但当前板级配置未启用，真板读写未在现有记录中验收

5. rootfs 准备

5.1 UFS 分区要求

[官方资料] K3 COM260 使用 UFS 2.2，本地存储容量资料为 128 GB 或 256 GB。

[官方资料] 官方 Yocto BSP 的 partition_universal.json 记录了下列分区布局：

分区	起始位置	大小/范围
`env`	640 KiB	64 KiB
`bootinfo`	1 MiB	128 KiB
`fsbl`	1536 KiB	512 KiB
`esos`	4 MiB	3 MiB
`opensbi`	7 MiB	1 MiB
`uboot`	8 MiB	4 MiB
`ESP`	12 MiB	256 MiB
`bootfs`	268 MiB	256 MiB
`rootfs`	524 MiB	剩余空间

StarryOS 使用官方 Yocto BSP 的 UFS 分区结构，只替换 rootfs 分区，保留前级固件、U-Boot 环境和 boot 分区。

目标 root 参数：

text

root=PARTLABEL=rootfs

这要求 GPT 中目标分区的 label 实际为：

text

rootfs

[待确认] 刷写前必须按当前 BSP 的 partition_universal.json 和实际 GPT 核对 rootfs 目标分区。不同设备不能直接复用固定块设备节点或整盘写入命令。

5.2 rootfs 镜像

已有资料记录两种镜像名称：

text

tgoskits/root_fs.img

以及构建/下载目录中的：

text

rootfs-riscv64-alpine.img

上述 rootfs 镜像用于 K3 StarryOS 的用户空间准备。

写入原则：

只写入 GPT 的 rootfs 分区；
不覆盖 fsbl、esos、opensbi、uboot；
不覆盖 ESP、bootfs 和设备树所在区域；
写入后确认分区 label 与 /chosen/bootargs 中的 root 选择一致；
没有确认设备节点和分区布局时，不执行整盘写入。

当前成功启动链已完成 K3 UFS、GPT、rootfs 分区和 Ext4 rootfs 识别。

6. StarryOS 构建

6.1 完整构建命令

进入仓库：

bash

cd tgoskits

执行 K3 板级构建：

bash

cargo starry build \
--config os/StarryOS/configs/board/spacemitk3-com260kit.toml

6.2 标准 K3 支持流程产物

feat/k3-board-support 资料记录的单文件产物：

text

target/riscv64gc-unknown-none-elf/release/starryos.uimg

该制品按 FIT 方式由 U-Boot bootm 启动。

6.3 当前兼容启动流程产物

当前环境成功生成：

text

target/riscv64gc-unknown-linux-musl/release/starryos.bin

一次已记录构建结果：

项目	结果
退出码	`0`
文件大小	约 13 MB
SHA-256	`bec0a546984ebfe1fde0cb6ee10b63e0da50f530f8defc4a7fad0af0f7343c20`

该制品与独立 DTB 配合，由 U-Boot booti 启动。

6.4 启动方式与地址速查

启动方式	上传内容	RAM 地址	启动命令
FIT 单文件	`starryos.uimg`	`0x180000000`	`bootm 0x180000000`
kernel 与 dtb 分离	`starryos.bin`	`0x140000000`	`booti 0x140000000 - 0x138000000`
kernel 与 dtb 分离	`spacemit-k3-com260-ifx.dtb`	`0x138000000`	与上一行的 kernel 一起启动

使用 FIT 时，只需要记住上传地址 0x180000000，内部 kernel 与 device tree 由 bootm 按 FIT 描述处理。

使用分离流程时，kernel 放在 0x140000000，DTB 放在 0x138000000。

两种方式都有 K3 启动记录，但制品格式、目标目录和启动命令不能交叉使用。开始加载前，应先确认本次构建实际生成的是哪一种制品。

6.5 进入 U-Boot 命令行

在执行 fastboot、bootm 或 booti 前，需要先进入 U-Boot 命令行环境。

操作步骤：

连接 UART 串口终端，波特率设置为 115200；
给开发板上电；
等待进入 U-Boot 启动阶段；
在自动启动倒计时阶段输入字符：

text

该字符用于停止当前 K3 COM260 验证环境中的自动启动流程。

成功后，串口终端出现：

text

=>

这表示已经进入 U-Boot 命令行环境。之后可以执行：

text

fastboot
bootm
booti
printenv

不同 U-Boot 版本的行为可能不同。本文以当前 K3 COM260 实际验证环境为准，应输入字符 s，不将其改写为“任意键打断 autoboot”。

7. 标准单文件启动：FIT 镜像

7.1 FIT 结构与上传地址

标准 K3 支持流程使用：

text

starryos.uimg

FIT 负责组合：

text

FIT
├── kernel
└── device tree

FIT 文件上传到：

text

0x180000000

首次启动不需要手工处理 FIT 内部地址。U-Boot bootm 会解析 FIT 中的 kernel 和 device tree 描述。

7.2 fastboot 上传与启动

在 U-Boot 中启动 fastboot 接收，地址为 0x180000000，窗口大小为 0x04000000：

bash

fastboot -l 0x180000000 -s 0x04000000 usb 0

在 Host 的 tgoskits 目录上传 FIT：

bash

fastboot stage \
target/riscv64gc-unknown-none-elf/release/starryos.uimg

回到 U-Boot 启动 FIT：

bash

bootm 0x180000000

bootm 解析 FIT 中的 kernel 与 device tree 描述，并按 FIT 自身配置完成加载。

以上是 feat/k3-board-support 资料记录的标准 K3 流程。若当前分支未生成 starryos.uimg，不要将 starryos.bin 改名后套用该流程。

8. kernel 与 dtb 分离启动

当前项目实际使用的制品：

kernel：

text

target/riscv64gc-unknown-linux-musl/release/starryos.bin

device tree：

text

os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

完整步骤如下。

8.1 上传 kernel

U-Boot：

bash

fastboot -l 0x140000000 -s 0x02000000 usb 0

Host：

bash

fastboot stage \
target/riscv64gc-unknown-linux-musl/release/starryos.bin

8.2 上传 DTB

U-Boot：

bash

fastboot -l 0x138000000 -s 0x00800000 usb 0

Host：

bash

fastboot stage \
os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

8.3 启动

U-Boot：

bash

booti 0x140000000 - 0x138000000

其中：

0x140000000：kernel 地址；
-：不提供 initrd；
0x138000000：DTB 地址。

当前已验证启动链：

text

BootROM
   |
   v
FSBL / OpenSBI
   |
   v
U-Boot
   |
   +-- fastboot stage starryos.bin --> 0x140000000
   |
   +-- fastboot stage DTB ----------> 0x138000000
   |
   v
booti 0x140000000 - 0x138000000
   |
   v
StarryOS kernel
   |
   v
UFS GPT / Ext4 rootfs
   |
   v
root@starry:/root #

9. 设备树配置

9.1 文件路径

设备树源资料路径：

text

os/StarryOS/configs/board/spacemit-k3-com260-ifx.dts

分离启动使用的编译产物：

text

os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

修改设备树前，应确认 DTS 与 kernel 来自同一个 K3 支持分支。

9.2 `/chosen/bootargs`

当前资料要求的目标参数为：

text

console=ttyS0,115200 earlycon=sbi root=PARTLABEL=rootfs rw

参数作用：

参数	作用
`console=ttyS0,115200`	使用 UART0，波特率 115200
`earlycon=sbi`	启用 SBI early console
`root=PARTLABEL=rootfs`	按 GPT 分区 label 查找 rootfs
`rw`	以可读写方式挂载 rootfs

[待确认] 当前可检查到的一份 DTB 仍使用固定 PARTUUID，并非上述 PARTLABEL=rootfs。因此，不能仅修改文档或 U-Boot 临时变量后就认为 DTB 已更新。采用 PARTLABEL 路线时应完成：

确认 UFS GPT 中目标分区 label 确实是 rootfs；
修改正确版本 DTS 的 /chosen/bootargs；
重新生成 DTB；
上传新 DTB；
从串口启动日志再次确认实际生效的 command line。

如果修改 rootfs、console 或其他 boot 参数，应修改 DTS 后重新构建 DTB；不要直接编辑二进制 DTB。

9.3 DTB 检查

可用 dtc 将 DTB 反编译到临时文件，用于检查 /chosen/bootargs：

bash

dtc -I dtb -O dts \
  -o /tmp/spacemit-k3-com260-ifx.dts \
  os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

正式重新生成 DTB 时，应使用所用 K3 分支的构建流程；上述命令只用于反编译检查。

10. U-Boot 相关说明

10.1 常用命令

命令	用途
`printenv`	查看当前 U-Boot 环境变量
`printenv bootcmd ufs_boot`	查看默认启动入口和 UFS 启动脚本
`fastboot`	通过 USB 接收 Host 上传的镜像
`bootm`	解析并启动 FIT 格式镜像
`booti`	启动 Image/bin 与独立 DTB 组合

10.2 不直接执行默认 `ufs_boot`

不要把以下命令当作 StarryOS 启动命令：

bash

run ufs_boot

当前 U-Boot 环境中的 ufs_boot 是官方 Linux 启动路径，会从 UFS 加载默认 kernel、DTB 和相关制品。直接执行可能进入 Bianbu，而不是当前内存中的 StarryOS。

StarryOS 应使用与制品格式对应的流程：

text

starryos.uimg  --> fastboot stage --> bootm
starryos.bin + dtb --> 分别 fastboot stage --> booti

10.3 `bootdelay`

已有资料记录：

bash

setenv bootdelay -1
saveenv

该操作会保存 U-Boot 环境并禁止启动等待。

注意：

它不等价于自动启动 StarryOS；
它可能使人工进入 U-Boot 命令行更困难；
修改的是持久 U-Boot 环境，执行前应先保存当前 printenv；
本文的手动 fastboot 流程不要求设置 bootdelay=-1。

11. 启动验证

11.1 串口成功标志

StarryOS kernel 和用户空间成功启动时，串口出现：

text

Welcome to Starry OS!

随后进入：

text

root@starry:/root #

这确认：

StarryOS kernel 已运行；
用户空间已启动；
shell 已可用；
真板基本启动链成功。

11.2 AI runner 设备节点

执行：

bash

ls /dev/k3_airunner

输出：

text

/dev/k3_airunner

该结果只确认设备节点存在，不扩展为所有 AI 负载均已验收。

11.3 CPU 信息

执行：

bash

cat /proc/cpuinfo

已确认系统可以读取 CPU 信息；现有资料未保存本次完整输出，因此本文不填充未经记录的 hart 数、频率或扩展列表。

11.4 rootfs 挂载

执行：

bash

mount

检查当前根文件系统是否来自预期的 UFS rootfs，并确认文件系统类型与挂载属性。

已完成 UFS 初始化、GPT 分区识别、rootfs 分区识别和 Ext4 rootfs 启动。

11.5 建议的最小验收表

检查项	验收方法
串口	出现 `Welcome to Starry OS!`
shell	出现 `root@starry:/root #`
AI runner 节点	`ls /dev/k3_airunner`
CPU 信息	`cat /proc/cpuinfo`
rootfs	`mount` 并核对根挂载

12. 常见问题

Q1：`configured root device was not found in discovered block devices`

完整现象：

text

configured root device was not found in discovered block devices

该报错在已有记录中出现过两类原因，不能只凭这一行直接判断 UFS 驱动失败。

原因 A：root 选择参数与实际 GPT 不匹配

旧配置使用固定：

text

root=PARTUUID=...

如果重新分区或写入后 UUID 改变，固定 PARTUUID 将不再匹配。当前资料要求的目标配置是：

text

root=PARTLABEL=rootfs

处理顺序：

确认 GPT 分区 label 是 rootfs；
确认实际上传的 DTB 中 /chosen/bootargs 使用 root=PARTLABEL=rootfs；
重新加载 DTB 并启动；
从串口核对实际生效的 command line。

如果当前 DTB 仍使用 PARTUUID，这项修正只有在重新构建并上传 DTB 后才会生效。

原因 B：devfs 未映射真实 K3 UFS 块设备

早期问题中，以下链路已经正常：

text

k3-ufs
   |
   v
block device
   |
   v
GPT
   |
   v
rootfs partition

但 /dev/vda 仍是占位设备，没有绑定真实 k3-ufs。本项目在下列位置补充了块设备运行时与 devfs 的映射：

text

os/arceos/modules/axfs-ng
os/StarryOS/kernel/src/pseudofs/dev

因此，如果 UFS、GPT 和 rootfs 分区日志都正常，仍出现该错误，应继续检查 devfs 块设备映射，而不是立即修改 UFS 驱动。

Q2：`ERROR: new format image overwritten - must RESET the board`

现象：

text

ERROR: new format image overwritten - must RESET the board

已有失败经验表明，FIT 接收地址与 kernel/DTB 加载区域重叠会覆盖新格式镜像。

处理：

按错误提示复位开发板；
将 FIT 文件接收到独立地址：

bash

fastboot -l 0x180000000 -s 0x04000000 usb 0

重新上传：

bash

fastboot stage \
target/riscv64gc-unknown-none-elf/release/starryos.uimg

启动：

bash

bootm 0x180000000

不要把 FIT 文件本身接收到 0x140000000 或 0x138000000。

Q3：`TEST_UNIT_READY failed`

现象：

text

TEST_UNIT_READY failed

已有 K3 UFS 记录将该现象与 UFS 上电后的 UNIT_ATTENTION 联系起来；当前驱动代码对 UNIT_ATTENTION/NOT_READY 包含重试处理。

处理原则：

如果后续重试恢复并继续识别容量、GPT 和 rootfs，可继续观察完整日志；
如果持续失败，检查供电稳定性和 UFS 初始化前后日志；
不要仅凭一次 TEST_UNIT_READY failed 就判断 GPT 或 Ext4 已损坏；
也不要忽略持续失败后仍无法发现块设备的情况。

Q4：启动后进入 Bianbu

原因：

U-Boot 默认 bootcmd/ufs_boot 走官方 Linux 路径。执行：

bash

run ufs_boot

会加载默认系统，而不是刚才通过 fastboot stage 放入 RAM 的 StarryOS。

解决：

FIT 制品使用 bootm 0x180000000；
分离制品使用 booti 0x140000000 - 0x138000000；
执行前用 printenv bootcmd ufs_boot 核对默认脚本，不将默认脚本误当作 StarryOS 启动入口。

Q5：串口无输出

按顺序检查：

开发板是否使用独立 DC 电源供电；
开发板 Pin 4 UART0_TXD 是否连接 TTL RX；
开发板 Pin 3 UART0_RXD 是否连接 TTL TX；
是否连接 Pin 7、9 或 11 的 GND；
串口波特率是否为 115200；
串口工具是否选择了正确的 USB-TTL 设备；
复位后是否能看到 U-Boot 前后的输出。

USB-TTL 的 Host 端口名称随设备和系统变化，不要硬编码 /dev/ttyUSB* 或 Windows COM 号。

Q6：Host 执行 `fastboot stage` 后没有进入下一步

检查：

U-Boot 端是否已经先执行对应的 fastboot -l ... -s ... usb 0；
Type-C 数据线是否支持数据传输；
Host 上传的文件是否是本次构建实际生成的制品；
U-Boot 接收窗口是否大于镜像大小；
每次 stage 后是否按流程返回 U-Boot，再启动下一次接收或执行启动命令。

如果 Host 无法枚举 fastboot 设备，需要检查 Host 的 fastboot 工具、USB 数据线和 USB 权限。

13. 已知限制

模块	限制说明
K3 UFS	已满足基本启动、GPT 和 Ext4 rootfs；外部资料仍将其描述为测试版，未完成生产级压力、断电恢复和长期稳定性验收
K3 GMAC	支持代码存在，但当前 `spacemitk3-com260kit.toml` 未启用，现有记录没有真板网络验收结果
K3 SDMMC/SDHCI	支持代码存在，但当前板级配置未启用，现有记录没有真板读写验收结果
AI runner	`/dev/k3_airunner` 节点已确认；设备节点存在不代表所有模型、内存规模和长期运行均已验证
FIT `starryos.uimg`	单文件启动流程已有确认记录；使用前仍需核对当前分支是否实际生成该制品
DTB root 参数	目标是 `PARTLABEL=rootfs`，但当前检查到的一份 DTB 仍使用固定 `PARTUUID`，部署前必须核对实际制品
自动启动	本文只确认手动 fastboot 内存加载，不将 `bootdelay=-1` 视为 StarryOS 自动启动方案

14. 附录：完整命令速查

14.1 环境与依赖

bash

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

bash

sudo apt update
sudo apt install -y cmake make ninja-build pkg-config
sudo apt install libudev-dev pkg-config
cargo install cargo-binutils

bash

pkg-config --modversion libudev

当前环境曾使用的 C 编译器兼容入口：

bash

sudo ln -s \
  "$(which riscv64-linux-gnu-gcc)" \
  /usr/local/bin/riscv64-linux-musl-cc

14.2 构建

bash

cd tgoskits

bash

cargo starry build \
--config os/StarryOS/configs/board/spacemitk3-com260kit.toml

14.3 FIT 单文件流程

U-Boot：

bash

fastboot -l 0x180000000 -s 0x04000000 usb 0

Host：

bash

fastboot stage \
target/riscv64gc-unknown-none-elf/release/starryos.uimg

U-Boot：

bash

bootm 0x180000000

14.4 kernel + dtb 分离流程

U-Boot 接收 kernel：

bash

fastboot -l 0x140000000 -s 0x02000000 usb 0

Host 上传 kernel：

bash

fastboot stage \
target/riscv64gc-unknown-linux-musl/release/starryos.bin

U-Boot 接收 DTB：

bash

fastboot -l 0x138000000 -s 0x00800000 usb 0

Host 上传 DTB：

bash

fastboot stage \
os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

U-Boot 启动：

bash

booti 0x140000000 - 0x138000000

14.5 U-Boot 环境检查

bash

printenv

bash

printenv bootcmd ufs_boot

非必需、谨慎使用：

bash

setenv bootdelay -1
saveenv

14.6 DTB 检查

bash

dtc -I dtb -O dts \
  -o /tmp/spacemit-k3-com260-ifx.dts \
  os/StarryOS/configs/board/spacemit-k3-com260-ifx.dtb

14.7 启动后验证

bash

ls /dev/k3_airunner
cat /proc/cpuinfo
mount

14.8 操作前最终核对

核对项	FIT 单文件	kernel + dtb 分离
制品	`starryos.uimg`	`starryos.bin` + `spacemit-k3-com260-ifx.dtb`
上传地址	`0x180000000`	kernel `0x140000000`；DTB `0x138000000`
接收窗口	`0x04000000`	kernel `0x02000000`；DTB `0x00800000`
启动命令	`bootm 0x180000000`	`booti 0x140000000 - 0x138000000`

最终原则：先核对制品格式、实际 DTB bootargs 和 UFS GPT，再执行与制品匹配的加载流程。出现 rootfs 错误时，应分开判断 root 选择、devfs 映射和 UFS 初始化状态。

K3 COM260 Kit 部署 StarryOS 启动指南 ​

文档信息 ​

状态标签 ​

1. 背景 ​

1.1 平台与适配目标 ​

1.2 本文解决的问题 ​

1.3 快速开始（推荐） ​

第 1 步：连接硬件 ​

第 2 步：构建 StarryOS ​

第 3 步：U-Boot 接收 FIT ​

第 4 步：Host 上传 FIT ​

第 5 步：启动 ​

第 6 步：确认进入 shell ​

2. K3 COM260 硬件准备 ​

2.1 供电 ​

2.2 串口连接 ​

2.3 USB Type-C 用途 ​

3. 软件环境准备 ​

3.1 仓库来源 ​

3.2 Rust 环境 ​

3.3 编译依赖 ​

4. StarryOS K3 支持说明 ​

4.1 板级支持内容 ​

4.2 设备树 ​

4.3 当前支持状态摘要 ​

5. rootfs 准备 ​

5.1 UFS 分区要求 ​

5.2 rootfs 镜像 ​

6. StarryOS 构建 ​

6.1 完整构建命令 ​

6.2 标准 K3 支持流程产物 ​

6.3 当前兼容启动流程产物 ​

6.4 启动方式与地址速查 ​

6.5 进入 U-Boot 命令行 ​

7. 标准单文件启动：FIT 镜像 ​

7.1 FIT 结构与上传地址 ​

7.2 fastboot 上传与启动 ​

8. kernel 与 dtb 分离启动 ​

8.1 上传 kernel ​

8.2 上传 DTB ​

8.3 启动 ​

9. 设备树配置 ​

9.1 文件路径 ​

9.2 /chosen/bootargs ​

9.3 DTB 检查 ​

10. U-Boot 相关说明 ​

10.1 常用命令 ​

10.2 不直接执行默认 ufs_boot ​

10.3 bootdelay ​

11. 启动验证 ​

11.1 串口成功标志 ​

11.2 AI runner 设备节点 ​

11.3 CPU 信息 ​

11.4 rootfs 挂载 ​

11.5 建议的最小验收表 ​

12. 常见问题 ​

Q1：configured root device was not found in discovered block devices ​

原因 A：root 选择参数与实际 GPT 不匹配 ​

原因 B：devfs 未映射真实 K3 UFS 块设备 ​

Q2：ERROR: new format image overwritten - must RESET the board ​

Q3：TEST_UNIT_READY failed ​

Q4：启动后进入 Bianbu ​

Q5：串口无输出 ​

Q6：Host 执行 fastboot stage 后没有进入下一步 ​

13. 已知限制 ​

14. 附录：完整命令速查 ​

14.1 环境与依赖 ​

14.2 构建 ​

14.3 FIT 单文件流程 ​

14.4 kernel + dtb 分离流程 ​

14.5 U-Boot 环境检查 ​

14.6 DTB 检查 ​

14.7 启动后验证 ​

14.8 操作前最终核对 ​

K3 COM260 Kit 部署 StarryOS 启动指南

文档信息

状态标签

1. 背景

1.1 平台与适配目标

1.2 本文解决的问题

1.3 快速开始（推荐）

第 1 步：连接硬件

第 2 步：构建 StarryOS

第 3 步：U-Boot 接收 FIT

第 4 步：Host 上传 FIT

第 5 步：启动

第 6 步：确认进入 shell

2. K3 COM260 硬件准备

2.1 供电

2.2 串口连接

2.3 USB Type-C 用途

3. 软件环境准备

3.1 仓库来源

3.2 Rust 环境

3.3 编译依赖

4. StarryOS K3 支持说明

4.1 板级支持内容

4.2 设备树

4.3 当前支持状态摘要

5. rootfs 准备

5.1 UFS 分区要求

5.2 rootfs 镜像

6. StarryOS 构建

6.1 完整构建命令

6.2 标准 K3 支持流程产物

6.3 当前兼容启动流程产物

6.4 启动方式与地址速查

6.5 进入 U-Boot 命令行

7. 标准单文件启动：FIT 镜像

7.1 FIT 结构与上传地址

7.2 fastboot 上传与启动

8. kernel 与 dtb 分离启动

8.1 上传 kernel

8.2 上传 DTB

8.3 启动

9. 设备树配置

9.1 文件路径

9.2 `/chosen/bootargs`

9.3 DTB 检查

10. U-Boot 相关说明

10.1 常用命令

10.2 不直接执行默认 `ufs_boot`

10.3 `bootdelay`

11. 启动验证

11.1 串口成功标志

11.2 AI runner 设备节点

11.3 CPU 信息

11.4 rootfs 挂载

11.5 建议的最小验收表

12. 常见问题

Q1：`configured root device was not found in discovered block devices`

原因 A：root 选择参数与实际 GPT 不匹配

原因 B：devfs 未映射真实 K3 UFS 块设备

Q2：`ERROR: new format image overwritten - must RESET the board`

Q3：`TEST_UNIT_READY failed`

Q4：启动后进入 Bianbu

Q5：串口无输出

Q6：Host 执行 `fastboot stage` 后没有进入下一步

13. 已知限制

14. 附录：完整命令速查

14.1 环境与依赖

14.2 构建

14.3 FIT 单文件流程

14.4 kernel + dtb 分离流程

14.5 U-Boot 环境检查

14.6 DTB 检查

14.7 启动后验证

14.8 操作前最终核对