Mass Storage 与存储类 Function

1. 组成

文件	职责
function/f_mass_storage.c	BOT(Bulk-Only Transport) + SCSI 命令仿真主体
function/storage_common.c	LUN 抽象：backing file/block device、只读/可移除属性
function/f_tcm.c	接入 LIO target core 的 BOT/UAS fabric（可选）
legacy/mass_storage.c	预组装g_mass_storage模块

Rockchip defconfig 启用USB_CONFIGFS_MASS_STORAGE；f_tcm未启用。

2. 运行模型

f_mass_storage 每个 common 一个内核线程，串行处理 BOT 事务：

fsg_main_thread()                 f_mass_storage.c:2560
 loop:
   get_next_command()             :2253   收 CBW (bulk-out)
   do_scsi_command()                      解析 SCSI CDB
     do_read()                    :605    文件读 -> bulk-in
     do_write()                   :736    bulk-out -> 文件写
     INQUIRY/READ_CAPACITY/MODE_SENSE/START_STOP/...
   发送 CSW (状态)
 异常: handle_exception()         :2425   reset/config变化/信号

EP0 侧fsg_setup()（456 行）处理 class 请求Bulk-Only Mass Storage Reset与Get Max LUN；fsg_bind()（3026 行）分配 bulk 端点并起线程。

3. LUN 配置

ConfigFS 路径：

functions/mass_storage.0/
├── stall                  是否允许bulk stall
├── luns 默认 lun.0/
│   ├── file               backing 文件或块设备路径
│   ├── ro                 只读
│   ├── removable          可移除介质语义
│   ├── cdrom              模拟CD-ROM
│   └── nofua              忽略FUA

file可在绑定后动态换（模拟换盘），前提removable=1。写file时内核 open 该路径，失败即拒绝。

4. 数据一致性核心问题

Backing 存储在 Host 眼中是裸块设备，Host 端文件系统直接写扇区：

• 绝不允许设备本机同时挂载读写同一 backing 文件/分区，否则两侧页缓存不一致必然损坏文件系统；
• 切换所有权（本机用 ↔ Host 用）必须先卸载一侧并 sync；
• nofua/写缓存意味着掉电可能丢数据，量产建议尊重 FUA 并评估断电场景；
• 只读导出（ro=1）是最安全模式。

5. 性能相关

• CONFIG_USB_GADGET_STORAGE_NUM_BUFFERS（默认 2）决定流水线缓冲数，VFS 突发延迟大时可增大；
• 吞吐路径：Host ↔ DWC3 bulk ↔ 内核线程 ↔ VFS/块层，瓶颈通常在存储介质而非 USB；
• SuperSpeed 下 bulk 1024B×burst，backing 为 eMMC/NVMe 时可达数百 MB/s。

6. f_tcm 简述

f_tcm.c把 gadget 作为 LIO target 的 fabric，支持 BOT（alt 0）与 UAS（alt 1）。UAS 使用 SS streams，需要 UDC 支持（DWC3 支持）。适合需要完整 SCSI target 语义（多 initiator、PR 等）的场景；简单 U 盘导出用 f_mass_storage 足够。

7. 排障

现象	检查
Host 识别但无盘符	lun file 是否设置、大小是否非零
写入后文件损坏	双侧同时挂载（见第4节）
拷贝中途 I/O 错误	backing 介质错误、common 线程信号/异常日志
速度慢	协商速度（lsusb -t）、NUM_BUFFERS、介质本身
弹出后无法再绑定	removable/退出状态、重新写 file