当前位置：首页 > news >正文

USB大容量存储设备(MSD)固件开发：SCSI命令解析与状态机实现详解

news 2026/6/7 16:09:45

1. 项目概述与核心价值

在嵌入式系统开发中，实现一个USB大容量存储设备（USB Mass Storage Device, MSD）是一个既经典又充满挑战的任务。它不仅仅是让一块SD卡通过USB线在电脑上显示为一个“U盘”那么简单，其背后涉及USB协议栈的驱动、SCSI命令集的解析、块设备的底层读写以及文件系统的挂载等一系列复杂技术的无缝衔接。我最近在为一个基于PIC微控制器的项目实现MSD功能时，重新梳理了整个过程，特别是对SCSI命令的响应与数据流控制有了更深刻的理解。这份笔记将聚焦于MSD固件实现的核心机制，尤其是ProcessIO()这个状态机如何作为“中枢神经”，协调USB端点、SCSI命令解析与SD卡物理操作。无论你是正在调试自己的MSD设备，还是对USB设备端开发感兴趣，希望这篇结合了协议原理与实战踩坑经验的总结，能帮你少走弯路。

2. SCSI命令集深度解析与设备响应逻辑

在USB Mass Storage Bulk-Only Transport（BOT）协议中，主机与设备之间的所有对话都通过命令块包装（Command Block Wrapper, CBW）和命令状态包装（Command Status Wrapper, CSW）进行，而真正的“指令”则藏在CBW内部的命令描述块（CDB）中，这些指令绝大多数来自SCSI命令集。理解并正确响应这些命令，是设备能够被操作系统识别和使用的基石。

2.1 关键SCSI命令详解与实现要点

上一节我们列举了部分命令，这里我们深入几个最核心的命令，看看在固件里究竟该如何处理。

READ(10) (Opcode 0x28) 与 WRITE(10) (Opcode 0x2A)这是数据读写的核心。CDB为10字节，其中：

逻辑块地址（LBA）：通常位于第2-5字节（32位），指示从哪个逻辑扇区开始读写。这里需要注意字节序（Endianness），SCSI通常使用大端序（Big-Endian），而我们的微控制器很可能是小端序（Little-Endian），因此在解析时必须进行转换。
传输长度（Transfer Length）：位于第7-8字节（16位），表示要连续读写的逻辑块数量。一个逻辑块的大小（Block Size）在READ CAPACITY命令的响应中告知主机，通常是512字节。

实操心得：在实现READ(10)时，最常见的坑是数据阶段（Data-In）的数据传输量。它必须严格等于Transfer Length * Block Size。如果SD卡读取速度跟不上USB的传输节奏，导致无法及时提供数据，设备必须通过STALL端点来报告错误，并在后续的REQUEST SENSE中提供准确的感知键（Sense Key），如HARDWARE ERROR或NOT READY。我曾因为SD卡初始化不彻底，在连续读操作中后期返回错误数据，导致Windows提示“设备未就绪”，排查了很久才发现是SD卡驱动层的状态机在高压下出了错。

REQUEST SENSE (Opcode 0x03)这是主机用于获取详细错误信息的命令。当任何命令执行失败（CSW中的Status字段为FAILED）后，主机一定会发来这个命令。设备的响应是一个18字节或更长的固定格式数据块，其中必须包含：

响应代码（Response Code）：当前常用的是0x70（表示当前错误）或0x71（表示已修复的错误）。
感知键（Sense Key）：这是错误分类，如ILLEGAL REQUEST（非法请求，CDB参数不对）、NOT READY（设备未就绪）、MEDIUM ERROR（介质错误，如读扇区失败）。
附加感知码（ASC）和限定码（ASCQ）：提供更具体的错误信息，例如ASC=0x3A, ASCQ=0x00表示“介质不存在”。

注意事项：REQUEST SENSE的数据缓冲区应该在命令失败时就被预先准备好，而不是收到命令时才去组织。因为失败可能发生在复杂的多步操作中，你需要及时保存错误上下文。一个健壮的实现是，在ProcessIO()状态机的任何错误分支里，都立即调用一个SetSenseData()函数来填充这个缓冲区。

TEST UNIT READY (Opcode 0x00)这个命令最简单，也最常用。主机用它来轮询设备是否已准备好接受后续命令。成功的响应就是一个状态为PASSED的CSW，没有任何数据阶段。实现时，你需要检查底层存储介质（如SD卡）是否初始化成功且可访问。如果卡被拔出或初始化失败，应返回FAILED的CSW，这样主机下次就会发REQUEST SENSE来查询原因。

PREVENT ALLOW MEDIUM REMOVAL (Opcode 0x1E)这个命令用于锁定或解锁存储介质，防止在读写过程中被意外移除。对于像SD卡这样的可移动介质，实现其“阻止”功能通常意味着在收到“阻止”命令后，如果后续有读写操作进行，则拒绝物理上弹出卡座的请求（如果有硬件支持），或者在软件上标记一个锁定标志。在很多简易实现中，这个命令可以被直接响应为成功，而不做实际硬件操作，但这可能会影响操作系统（如Windows）的“安全删除硬件”流程的严谨性。

2.2 不支持的命令与错误处理规范

当设备收到一个其CDB中操作码（Opcode）不支持的命令时，绝不能简单地忽略。根据BOT协议和SCSI标准，设备必须：

将CSW的状态（Status）设置为FAILED。
在感知数据中，将感知键（Sense Key）设置为ILLEGAL REQUEST（非法请求）。
通常，附加感知码（ASC）可设置为INVALID COMMAND OPERATION CODE（无效命令操作码）。

在固件中，这体现为一个默认的命令处理分支：

switch (cbw.CDB[0]) { // 检查操作码 case 0x28: // READ(10) HandleRead10(); break; case 0x2A: // WRITE(10) HandleWrite10(); break; // ... 其他支持的命令 default: // 不支持的命令 msdSenseKey = SENSE_KEY_ILLEGAL_REQUEST; msdASC = 0x20; // INVALID COMMAND OPERATION CODE msdCSWStatus = CSW_FAILED; break; }

这种明确的错误报告机制，使得主机操作系统能够理解设备的能力边界，而不是将其视为一个无响应的“死”设备。

3. MSD固件架构与内存管理剖析

一个典型的MSD固件，如基于Microchip PIC微控制器的实现，其代码结构是分层且模块化的。理解这个架构，对于调试和移植至关重要。

3.1 固件目录结构与模块职责

参考常见的实现，固件通常包含以下核心模块：

main.c：程序入口，包含主循环while(1)，交替调用USBTasks()（处理USB中断和事件）和ProcessIO()（处理MSD应用逻辑）。这是调度核心。
usb_device.c/usb_hal.c：USB设备层和硬件抽象层驱动，负责底层的USB寄存器操作、端点配置、中断处理。这部分通常由芯片原厂提供。
msd.c/msd.h：Mass Storage设备类的核心实现文件。包含ProcessIO()状态机、CBW/CSW解析、SCSI命令分发器（如MSDCommandHandler()），以及USBCheckMSDRequest()函数用于处理类特定请求（如Bulk-Only Mass Storage Reset）。
sdcard.c/sdcard.h：SD/MMC卡底层驱动。实现SPI或SDIO通信协议，提供SD_ReadBlock()、SD_WriteBlock()、SD_Initialize()等函数。这是与物理存储介质打交道的“司机”。
usb9.c：处理USB标准请求，如设备描述符、配置描述符、字符串描述符的获取，以及设置地址、设置配置等。USBStdSetCfgHandler()函数会在设备配置成功后调用MSD的端点初始化函数。

各文件间的调用关系清晰：main循环调度USB和MSD任务；MSD在需要读写数据时调用SDCard驱动；USB底层驱动在收到数据包时通过回调或全局变量通知MSD层。

3.2 双端口RAM与端点缓冲区管理

这是嵌入式USB设备开发中的一个关键硬件特性，常被初学者忽略。许多微控制器（如PIC18、PIC32）的USB模块集成了一个专用的双端口RAM（DPRAM）。这块内存空间被硬件映射到特定的数据存储区（Data Bank），例如Bank 4-7。

它的工作模式如下：

USB禁用时：这些Bank可以作为普通的通用寄存器（GPR）使用，存放变量。
USB使能后：这些Bank被硬件“征用”为端点缓冲区。例如，端点1的Bulk-In和Bulk-Out端点各需要一块512字节的缓冲区，它们就位于这块DPRAM中。
共享访问：CPU内核和USB模块的SIE（串行接口引擎）都可以直接访问这块RAM。CPU将待发送的数据（Data-In）写入Bulk-In缓冲区，然后通知USB硬件；USB硬件收到主机数据（Data-Out）后，直接存入Bulk-Out缓冲区，并产生中断通知CPU来读取。

在链接器脚本（.ld或.lkr文件）中，我们需要精确定义这块内存的用途。例如：

DATABANK NAME=MSD_BANK START=0x400 END=0x5FF SECTION NAME=MSD_DATA RAM=MSD_BANK

然后在代码中声明一个对齐到该区域的缓冲区：

#pragma udata MSD_DATA unsigned char msd_buffer[512]; // 用于临时存储一个扇区数据 #pragma udata

msd_buffer这个512字节的数组，通常用作数据搬运的中转站。例如，处理READ(10)命令时，流程是：SD_ReadBlock(lba, msd_buffer)-> 将msd_buffer中的数据复制到USB Bulk-In端点缓冲区-> 启动USB传输。

踩坑记录：务必确保端点缓冲区的地址和大小符合USB硬件模块的要求。我曾经因为链接器脚本配置错误，导致端点缓冲区地址越界，结果USB数据传输完全混乱，电脑只能识别到设备但无法枚举。调试这类问题，需要仔细对照数据手册中的USB缓冲区地址映射表。

4. 核心状态机：ProcessIO() 流程全解析

ProcessIO()函数是整个MSD固件的“大脑”，它本质上是一个状态机（State Machine），在MSD_WAIT、MSD_DATA_IN、MSD_DATA_OUT、MSD_SEND_CSW等状态间迁移，驱动着一次完整的SCSI命令执行流程。

4.1 状态迁移与数据流协同

让我们结合一个READ(10)命令的完整生命周期，来看状态机如何工作：

初始状态MSD_WAIT：
- 固件初始化后，状态机停留在此状态。
- 它持续检查Bulk-Out端点是否收到一个有效的、长度为31字节的CBW包（通过USBHandleBusy()或类似标志判断）。
- 一旦收到，解析CBW头（包括签名0x43425355、标签dCBWTag、数据长度dCBWDataTransferLength和方向位bmCBWFlags）。
解析命令与设置状态：
- 从CBW中提取CDB（命令描述块）。
- 根据CDB的操作码调用相应的命令处理函数（如HandleRead10）。
- 关键一步：根据CBW中的方向位（bmCBWFlagsbit 7），决定下一个状态。对于READ(10)（主机读设备数据），方向位为1（In），状态设为MSD_DATA_IN。对于WRITE(10)，方向位为0（Out），状态设为MSD_DATA_OUT。对于无数据阶段的命令（如TEST UNIT READY），则直接准备进入MSD_SEND_CSW。
数据阶段MSD_DATA_IN/MSD_DATA_OUT：
- MSD_DATA_IN(以READ为例)： a. 命令处理函数根据CDB中的LBA和传输长度，计算出需要读取的总字节数（bytesToSend）。 b. 在状态机循环中，每次判断Bulk-In端点是否就绪（上次发送完成）。 c. 如果就绪，则从SD卡读取一个扇区（512字节）到msd_buffer，再将这部分数据加载到USB的Bulk-In端点缓冲区，并启动USB传输。 d. 更新已发送字节数，直到bytesToSend归零。然后状态迁移至MSD_SEND_CSW。
- MSD_DATA_OUT(以WRITE为例)： a. 判断Bulk-Out端点是否有数据到达。 b. 如果有，将数据从端点缓冲区读出，写入msd_buffer，攒够一个扇区（512字节）后，调用SD_WriteBlock写入SD卡。 c. 更新已接收字节数，直到达到CBW中指定的数据长度。然后状态迁移至MSD_SEND_CSW。
状态阶段MSD_SEND_CSW：
- 准备CSW包（命令状态包装）。必须将CBW中的dCBWTag原样拷贝到CSW的dCSWTag中，这是主机匹配命令与状态的唯一标识。
- CSW的签名固定为0x53425355。
- dCSWDataResidue字段填写实际传输的数据量与请求的数据量之间的差值（残留值）。如果一切顺利，这里填0。
- bCSWStatus字段填写命令执行状态：0x00（PASSED成功）,0x01（FAILED失败）,0x02（PHASE ERROR阶段错误，如CBW无效）。
- 将CSW包（13字节）加载到Bulk-In端点缓冲区，发送给主机。
返回MSD_WAIT：
- 发送完CSW后，状态机重置回MSD_WAIT，等待下一个CBW，开始新的循环。

4.2 关键代码片段与避坑指南

以下是ProcessIO()状态机核心逻辑的简化伪代码，体现了上述流程：

void ProcessIO(void) { switch (msdState) { case MSD_WAIT: if (USBOutEndpointIsReady() && ReceivedCBWIsValid()) { ParseCBW(&cbw); // 保存Tag，用于后续CSW csw.dCSWTag = cbw.dCBWTag; // 根据CDB命令码处理 status = HandleSCSICommand(cbw.CDB); // 根据方向位设置下一个状态 if (cbw.bmCBWFlags & 0x80) { // 数据输入阶段（设备到主机） bytesToTransfer = cbw.dCBWDataTransferLength; msdState = MSD_DATA_IN; } else if (cbw.dCBWDataTransferLength > 0) { // 数据输出阶段（主机到设备） bytesToTransfer = cbw.dCBWDataTransferLength; msdState = MSD_DATA_OUT; } else { // 无数据阶段，直接发送CSW msdState = MSD_SEND_CSW; } } break; case MSD_DATA_IN: if (USBInEndpointIsReady()) { // 计算本次要发送的数据量（不超过端点大小和剩余总量） chunkSize = MIN(EP1_IN_SIZE, bytesToTransfer); if (chunkSize > 0) { // 从存储介质读取数据到发送缓冲区 ReadDataFromStorage(msdInBuffer, chunkSize); // 启动USB发送 USBLoadInEndpoint(EP1_IN, msdInBuffer, chunkSize); bytesToTransfer -= chunkSize; } if (bytesToTransfer == 0) { // 数据阶段完成 msdState = MSD_SEND_CSW; } } break; case MSD_DATA_OUT: if (USBOutEndpointHasData()) { // 从USB端点读取数据 chunkSize = USBReadOutEndpoint(EP1_OUT, msdOutBuffer); // 将数据写入存储介质 WriteDataToStorage(msdOutBuffer, chunkSize); bytesToTransfer -= chunkSize; if (bytesToTransfer == 0) { // 数据阶段完成 msdState = MSD_SEND_CSW; } } break; case MSD_SEND_CSW: // 准备CSW csw.dCSWSignature = CSW_SIGNATURE; csw.dCSWDataResidue = CalculateResidue(); // 计算残留值 csw.bCSWStatus = GetCommandStatus(); // 获取最终命令状态 // 发送CSW if (USBInEndpointIsReady()) { USBLoadInEndpoint(EP1_IN, (uint8_t*)&csw, sizeof(CSW)); // 回到等待状态，准备接收下一个CBW msdState = MSD_WAIT; } break; } }

避坑指南：数据残留值（dCSWDataResidue）的处理这是一个极易出错且被忽视的细节。dCSWDataResidue必须反映主机期望传输的数据量与设备实际传输的数据量之间的差值。例如，主机请求读取1000字节，但你的设备因为某种错误只成功发送了512字节就失败了，那么dCSWDataResidue应该设为488（1000-512）。如果传输成功完成，则设为0。许多简单的固件实现会直接将其设为0，这在大多数情况下可行，但不符合协议规范，在某些严格的主机控制器或操作系统下可能导致问题。正确的做法是在状态机中实时跟踪bytesToTransfer，并在发送CSW时将其值赋给dCSWDataResidue。

5. 实战调试：常见问题与排查技巧实录

开发MSD设备时，你会遇到各种各样的问题，从电脑完全无法识别，到能识别但无法格式化，再到读写文件时随机出错。下面是我总结的一些典型问题及其排查思路。

5.1 枚举失败：设备管理器出现“未知USB设备”

症状：插入设备，电脑有提示音，但设备管理器显示黄色叹号，错误代码可能是“设备描述符请求失败”。
排查步骤：
1. 检查硬件：确保USB的D+、D-数据线连接正确，上拉电阻（1.5kΩ）是否接在D+（全速设备）上。电源是否稳定。
2. 抓取USB数据包：使用硬件USB分析仪（如Beagle, Ellisys）或软件工具（配合特定芯片的调试功能）。这是最直接的证据。查看设备是否对主机发出的第一个GET_DESCRIPTOR (Device)请求做出了正确响应。如果没有响应，问题出在USB控制器初始化或端点0（控制端点）的设置上。
3. 核对描述符：逐字节检查你的设备描述符、配置描述符、接口描述符、端点描述符。特别是：
  - bDeviceClass、bDeviceSubClass、bDeviceProtocol：对于MSD，设备类通常设为0x00（在接口中定义），或者在设备级设为0x08（Mass Storage）。
  - 接口描述符中：bInterfaceClass必须为0x08（Mass Storage），bInterfaceSubClass通常为0x06（SCSI Transparent Command Set），bInterfaceProtocol为0x50（Bulk-Only Transport）。
  - 端点描述符：确保Bulk-In和Bulk-Out端点的地址、方向、属性（0x02表示Bulk）、最大包大小正确。

5.2 枚举成功但无法弹出磁盘或提示“需要格式化”

症状：电脑识别出“大容量存储设备”，盘符出现，但双击时提示“磁盘未格式化”或“请插入磁盘”。
排查步骤：
1. 检查INQUIRY命令响应：这是主机枚举后发的第一个SCSI命令。确保你的INQUIRY数据符合规范。Peripheral Device Type（外设类型）应设为0x00（可移动的直接访问块设备，如U盘）或0x05（CD-ROM）。Vendor Identification和Product Identification字段最好填上可读的ASCII字符串。
2. 检查READ CAPACITY命令响应：这是主机获取磁盘大小的命令。响应为8字节：前4字节是最大LBA号（注意是最大编号，不是总扇区数。总扇区数 = 最大LBA + 1），后4字节是块大小（通常是512）。必须确保这两个值是从你的SD卡CSD寄存器正确计算出来的。如果返回全0或错误值，主机就会认为介质容量为0。
3. 检查TEST UNIT READY命令：主机会频繁发送此命令。确保你的SD卡初始化成功，并且在此命令的处理中返回PASSED的CSW。如果卡未就绪，应返回FAILED，并设置正确的Sense Key。

5.3 读写文件不稳定、速度慢或中途出错

症状：可以格式化，复制小文件正常，但复制大文件时速度极慢、卡住，或提示“数据错误循环冗余检查”。
排查步骤：
1. SD卡驱动稳定性：这是最常见的原因。SD卡操作（特别是SPI模式）有严格的时序要求。确保你的SPI时钟在初始化时足够慢（通常<400kHz），初始化成功后可以提高到较高频率。检查SD_ReadBlock/SD_WriteBlock函数是否有超时和重试机制。强烈建议在每次读写命令后检查SD卡的响应令牌和CRC状态。
2. USB端点缓冲区管理：确保在MSD_DATA_IN状态，只有在上一次Bulk-In传输完成（USBHandleBusy()为假）后，才加载下一包数据。否则会导致数据覆盖或丢失。同理，在MSD_DATA_OUT状态，要及时从Bulk-Out端点缓冲区取走数据，避免缓冲区溢出。
3. 中断优先级：如果USB中断和SD卡操作（可能使用SPI中断或DMA）存在，要合理设置中断优先级，避免长时间关中断导致USB数据传输超时（主机通常等待几毫秒后就会放弃，导致传输失败）。
4. 数据对齐与内存访问：确保用于USB端点缓冲区和SD卡读写缓冲区的内存地址是对齐的（例如32位对齐），特别是使用DMA时。非对齐访问在某些架构上会导致硬件错误或性能下降。
5. 使用REQUEST SENSE定位错误：当读写出错时，主机一定会发REQUEST SENSE。在你的固件中，确保在SD卡读写失败、命令不支持等任何错误发生时，都精确地设置Sense Key、ASC、ASCQ。例如，SD卡读超时可以设置为MEDIUM ERROR+0x31（MEDIUM FORMAT CORRUPTED？更准确的是HARDWARE ERROR）。在电脑的“事件查看器”中有时可以找到这些SCSI感知信息，对定位问题非常有帮助。

实现一个稳定可靠的USB Mass Storage设备，是对开发者综合能力的考验，它要求你对USB协议、SCSI命令集、底层存储介质驱动以及实时状态机编程都有扎实的理解。从理清CBW/CSW的数据流，到精心设计ProcessIO()状态机的每一个状态迁移，再到为每一个可能的错误路径设置恰当的感知数据，每一步都需要耐心和细致。当你第一次看到自己的设备在电脑上被顺利识别、格式化并稳定传输文件时，那种成就感是对所有调试工作的最好回报。这个过程积累下来的对协议细节的把握和调试经验，会让你在后续从事任何嵌入式设备开发时都受益匪浅。

查看全文

http://www.rkmt.cn/news/1480755.html