TSV 文件详解与应用指南#
一、TSV 文件基础#
1.1 文件性质#
文件类型：STM32CubeProgrammer 烧录脚本文件
扩展名：
.tsv编写方式：手动编写（通常基于模板修改）
分隔符：必须使用制表符（TAB），不能使用空格
注释：以
#开头的行被视为注释
1.2 文件位置#
示例通常放在烧录工具包的
flashlayout文件夹下根据存储介质不同，通常包含
sd卡和emmc两种版本
二、TSV 文件结构解析#
2.1 基本格式（7 列）#
#Opt Id Name Type IP Offset Binary
- 0x01 fsbl1-boot Binary none 0x0 Ram/tf-a-stm32mp157c-100ask-512d-v1-serialboot.stm32
- 0x03 ssbl-boot Binary none 0x0 Ram/u-boot.stm32
P 0x04 fsbl1 Binary mmc1 boot1 tf-a-stm32mp157c-100ask-512d-v1.stm32
P 0x05 fsbl2 Binary mmc1 boot2 tf-a-stm32mp157c-100ask-512d-v1.stm32
PD 0x06 ssbl Binary mmc1 0x00080000 u-boot.stm32
P 0x21 rootfs1 System mmc1 0x00280000 bootfs.ext4
P 0x22 rootfs2 FileSystem mmc1 0x08280000 rootfs.ext4
2.2 各列含义#
列名 |
含义 |
说明 |
|---|---|---|
Opt |
操作选项 |
|
Id |
标识符 |
十六进制编号，决定烧录顺序和方式 |
Name |
分区名称 |
分区标识名 |
Type |
数据类型 |
Binary：二进制文件；System：系统分区；FileSystem：文件系统 |
IP |
存储设备 |
none：RAM；mmc1：eMMC/SD 卡；nor：NOR Flash |
Offset |
偏移地址 |
在存储设备中的起始位置（十六进制或特殊标识） |
Binary |
文件名 |
要烧录的文件路径（支持相对/绝对路径） |
2.3 关键 ID 说明#
ID |
用途 |
说明 |
|---|---|---|
0x01 |
fsbl1-boot |
TF-A 串行启动加载器（加载到 RAM） |
0x03 |
ssbl-boot |
U-Boot 串行启动（加载到 RAM） |
0x04 |
fsbl1 |
TF-A 主分区（烧写到 eMMC boot1） |
0x05 |
fsbl2 |
TF-A 备份分区（烧写到 eMMC boot2） |
0x06 |
ssbl |
U-Boot 持久化分区 |
0x21 |
rootfs1 |
引导文件系统分区 |
0x22 |
rootfs2 |
根文件系统分区 |
三、文件编写方法#
3.1 编写步骤#
复制模板：从已有 TSV 文件复制
修改路径：调整 Binary 列的相对/绝对路径
配置分区：根据硬件选择 mmc1（eMMC/SD）或其他存储介质
设置 Offset：按分区规划设置偏移地址（支持 boot1/boot2 标识符）
保存文件：使用制表符分隔，UTF-8 编码
3.2 注意事项#
必须使用制表符：空格会导致 STM32CubeProgrammer 报错
第一行注释：建议保留说明行，便于维护
文件顺序：按烧录顺序排列，先烧 TF-A，再烧 U-Boot，最后烧文件系统
特殊 Offset：
boot1和boot2是 eMMC 的特殊分区标识符
3.3 示例配置详解#
# 第一行：串行启动加载器到 RAM
- 0x01 fsbl1-boot Binary none 0x0 Ram/tf-a-serialboot.stm32
# 第二行：U-Boot 串行启动到 RAM
- 0x03 ssbl-boot Binary none 0x0 Ram/u-boot.stm32
# 第三行：TF-A 主分区烧写到 eMMC boot1
P 0x04 fsbl1 Binary mmc1 boot1 tf-a.stm32
# 第四行：TF-A 备份分区烧写到 eMMC boot2
P 0x05 fsbl2 Binary mmc1 boot2 tf-a.stm32
# 第五行：U-Boot 持久化分区（编程后删除缓存）
PD 0x06 ssbl Binary mmc1 0x00080000 u-boot.stm32
# 第六行：引导文件系统分区
P 0x21 rootfs1 System mmc1 0x00280000 bootfs.ext4
# 第七行：根文件系统分区
P 0x22 rootfs2 FileSystem mmc1 0x08280000 rootfs.ext4
四、烧录文件详解#
4.1 必须烧录的文件#
文件 |
作用 |
烧录位置 |
|---|---|---|
tf-a-serialboot.stm32 |
串行启动 TF-A |
加载到 RAM（临时） |
u-boot.stm32 |
串行启动 U-Boot |
加载到 RAM（临时） |
tf-a.stm32 |
安全启动固件 |
eMMC boot1/boot2 分区 |
u-boot.stm32 |
引导加载程序 |
eMMC user area (0x00080000) |
bootfs.ext4 |
引导文件系统 |
eMMC (0x00280000) |
rootfs.ext4 |
根文件系统 |
eMMC (0x08280000) |
4.2 串行启动与持久化启动的区别#
版本 |
用途 |
说明 |
|---|---|---|
tf-a-serialboot.stm32 |
串行启动 TF-A |
通过 USB/UART 加载到 RAM，用于初始烧录 |
u-boot.stm32（ID 0x03） |
串行启动 U-Boot |
加载到 RAM，协助烧录过程 |
tf-a.stm32（ID 0x04/0x05） |
持久化 TF-A |
烧写到 eMMC boot 分区，用于正常启动 |
u-boot.stm32（ID 0x06） |
持久化 U-Boot |
烧写到 eMMC user area，用于正常启动 |
4.3 Offset 设置规则#
分区 |
Offset 值 |
说明 |
|---|---|---|
TF-A（boot1） |
boot1 |
eMMC boot area 主分区 |
TF-A（boot2） |
boot2 |
eMMC boot area 备份分区 |
U-Boot |
0x00080000 |
user area 标准位置（512KB 偏移） |
bootfs |
0x00280000 |
引导文件系统（2.5MB 偏移） |
rootfs |
0x08280000 |
根文件系统（130.5MB 偏移） |
五、操作选项详解#
5.1 Opt 字段类型#
选项 |
含义 |
使用场景 |
|---|---|---|
- |
加载到 RAM |
临时运行程序，不写入持久存储 |
P |
编程到 Flash |
将文件写入持久存储设备 |
PD |
编程后删除 |
写入后删除缓存文件，节省空间 |
D |
删除分区 |
清空指定分区内容 |
5.2 Type 字段类型#
类型 |
含义 |
适用文件 |
|---|---|---|
Binary |
二进制文件 |
.stm32、.bin 等可执行文件 |
System |
系统分区 |
包含引导相关文件的文件系统 |
FileSystem |
文件系统 |
完整的 Linux 根文件系统 |
六、开发板适配#
6.1 典型开发板配置#
基础方案：基于 ST 官方 OpenSTLinux BSP 修改
存储方案：支持 eMMC boot 分区双备份
文件系统：分离的 bootfs 和 rootfs 设计
可靠性：支持 A/B 系统切换，防变砖
6.2 烧录准备#
准备串行启动文件（放置在 Ram/ 目录下）
准备持久化固件文件（主烧录文件）
准备文件系统镜像（.ext4 格式）
连接 USB 线到开发板
提供外部供电（12V DC 或 USB）
启动 STM32CubeProgrammer 软件
选择 TSV 文件开始烧录
七、总结#
问题 |
回答 |
|---|---|
TSV 文件生成方式 |
半自动/手写，基于模板修改 |
制表符 vs 空格 |
必须使用制表符，空格会报错 |
串行启动的作用 |
通过 USB/UART 临时加载引导程序，用于初始烧录 |
boot1/boot2 意义 |
eMMC 的特殊 boot 分区，用于存放 TF-A |
PD 选项的作用 |
编程后删除缓存文件，适用于大文件烧录 |
Offset 0x00080000 |
U-Boot 在 eMMC user area 的标准存放位置 |
分离的 bootfs/rootfs |
bootfs 包含内核和设备树，rootfs 包含系统应用 |
编写建议：
始终从可靠模板开始，逐步修改配置
使用文本编辑器显示制表符功能确保格式正确
注意文件路径的正确性，特别是相对路径的使用
按照烧录顺序排列：串行启动 → TF-A → U-Boot → 文件系统
合理规划分区大小和偏移地址，避免重叠