00001 /* ---------------------------------------------------------------------------- 00002 * ATMEL Microcontroller Software Support 00003 * ---------------------------------------------------------------------------- 00004 * Copyright (c) 2008, Atmel Corporation 00005 * 00006 * All rights reserved. 00007 * 00008 * Redistribution and use in source and binary forms, with or without 00009 * modification, are permitted provided that the following conditions are met: 00010 * 00011 * - Redistributions of source code must retain the above copyright notice, 00012 * this list of conditions and the disclaimer below. 00013 * 00014 * Atmel's name may not be used to endorse or promote products derived from 00015 * this software without specific prior written permission. 00016 * 00017 * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR 00018 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00019 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 00020 * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, 00021 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00022 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 00023 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 00024 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 00025 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00026 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00027 * ---------------------------------------------------------------------------- 00028 */ 00029 00030 /** 00031 * \dir usb/device/massstorage 00032 * 00033 * \section Purpose 00034 * 00035 * This directory provides definitions, structs and functions for a USB Mass 00036 * Storage device (MSD) - USB Mass Storage demo. 00037 * 00038 * \section Contents 00039 * 00040 * There are four things for the implement of the USB MSD driver: 00041 * - Implement the MSD driver structs and functions for the device, 00042 * to initialize, to handle MSD-specific requests and dispach 00043 * standard requests in USBD callbacks, to read/write through assigned USB 00044 * endpoints, 00045 * - Create the MSD device's descriptors that should be passed to 00046 * the USBDDriver instance on initialization, so that the host can 00047 * recognize the device as a USB Mass Storage device. 00048 * - Implement state machine for MSD command/data/status handling. 00049 * - Implement storage media interface for MSD disk accessing. 00050 * 00051 * For more information about what a particular group contains, please refer to 00052 * \ref usbd_msd_drv "USBD MSD Driver". 00053 */ 00054 00055 /** 00056 \page usbd_msd_drv USB Device Massstorage Driver 00057 This page describes how to use the USB framework to produce a USB Device MSD driver, 00058 which appears as a USB Disk on host. 00059 00060 \section References 00061 - \ref usbd_framework "AT91 USB device framework" 00062 - \ref usbd_enum "USB Device Enumeration" 00063 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip"> 00064 Universal Serial Bus Revision 2.0 specification 00065 </a> (.zip file format, size 9.80 MB) 00066 - <a href="http://www.usb.org/developers/devclass_docs/usb_msc_overview_1.2.pdf"> 00067 Mass Storage Overview 1.2</a> 00068 - <a href="http://www.usb.org/developers/devclass_docs/usbmassbulk_10.pdf"> 00069 Mass Storage Bulk Only 1.0</a> 00070 - <a href="http://www.t10.org/scsi-3.htm">SCSI Standards</a> 00071 - SCSI Block Commands - 3 (SBC-3) 00072 - SCSI Primary Commands - 4 (SPC-4) 00073 00074 \section msc_basic Mass Storage Class Basic 00075 This section gives generic details on the MSD class. 00076 00077 See \subpage usb_msd_basic "USB MSD Basic". 00078 00079 \section msc_scsi_disk Mass Storage SCSI Disk 00080 00081 This section describes how to implement a USB disk by using the MSD class with 00082 the SCSI transparent command set and the AT91 USB Framework. For more 00083 information about the framework, please refer to the "AT91 USB device 00084 framework" application note; details about the USB and the Mass Storage class 00085 can be found in the USB specification 2.0 and the MSC Bulk-Only Transport 00086 specification 1.0 documents, respectively. 00087 00088 The software example provided with this document uses the ram disk of the chip 00089 as its storage medium, but has been designed in a modular way to allow easy 00090 modification for any medium, e.g. internal flash, DataFlash, SD card, external 00091 Flash chip. 00092 00093 \subsection Architecture 00094 The MSD driver is based on framework, See \subpage usbd_framework_arch "USB Device Framework Architecture". 00095 00096 The internal architecture of the Application layer is extended for the 00097 following factors: 00098 - The Command/Data/Status flow described in \ref usb_msd_basic "USB MSD Basic" requires the use 00099 of a <b>state machine</b> for non-blocking operation. 00100 - The example software has been designed to be easily extended with support 00101 for other media. 00102 - The example software has been designed to support multiple LUNs on one or 00103 more media. 00104 00105 \image html MSDAppArch.png "Application Layer Architecture" 00106 00107 \subsection Descriptors 00108 There are no class-specific descriptors for a device using the MSD class with 00109 the Bulk-only transport protocol. This section thus only details the values 00110 which must be set in the standard descriptors. 00111 00112 \subsubsection dev_dsc Device Descriptor 00113 \code 00114 static const USBDeviceDescriptor deviceDescriptor = { 00115 00116 sizeof(USBDeviceDescriptor), // bLength: Size of descriptor (18 bytes) 00117 USBGenericDescriptor_DEVICE, // bDescriptorType: Device descriptor 00118 USBDeviceDescriptor_USB2_00, // bcdUSB: USB 2.00 00119 MSDeviceDescriptor_CLASS, // bDeviceClass: 0 00120 MSDeviceDescriptor_SUBCLASS, // bDeviceSubClass: 0 00121 MSDeviceDescriptor_PROTOCOL, // bDeviceProtocol: 0 00122 BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0), // bMaxPacketSize0: Max Size EP0 00123 MSDDriverDescriptors_VENDORID, // idVendor: Vendor ID ATMEL (0x03eb) 00124 MSDDriverDescriptors_PRODUCTID,// idProduct: Product ID (0x6202) 00125 MSDDriverDescriptors_RELEASE, // bcdDevice: 0x0001, Version 0.01 00126 1, // iManufacturer: Manufacturer string (manufacturerDescriptor) index. 00127 2, // iProduct: Product string (productDescriptor) index. 00128 3, // iSerialNumber: Serial number string (serialNumberDescriptor) index. 00129 1 // bNumConfigurations: Device has one possible configuration. 00130 }; 00131 \endcode 00132 Note that the Vendor ID is a special value attributed by the USB-IF 00133 organization. The product ID can be chosen freely by the vendor. 00134 00135 \subsubsection cfg_dsc Configuration Descriptor 00136 The descriptors are defined as: 00137 \code 00138 const MSDConfigurationDescriptors configurationDescriptorsFS; 00139 \endcode 00140 00141 Configuration descriptor 00142 \code 00143 // Standard configuration descriptor. 00144 { 00145 sizeof(USBConfigurationDescriptor), // bLength: 9 bytes 00146 USBGenericDescriptor_CONFIGURATION, // bDescriptorType: Configuration 00147 sizeof(MSDConfigurationDescriptors),// wTotalLength: Length of all 00148 1, // bNumInterface: Configuration has one interface. 00149 1, // bConfigurationValue: This is configuration #1. 00150 0, // iConfiguration: No string descriptor for configuration. 00151 BOARD_USB_BMATTRIBUTES, // bmAttributes: Power and remote wakeup 00152 USBConfigurationDescriptor_POWER(100) // 100mA max power 00153 }, 00154 \endcode 00155 00156 \subsubsection if_dsc Interface Descriptor 00157 The interface descriptor must indicate several features: 00158 - <b>Mass Storage Device</b> class code (08h) in the <i>bInterfaceClass</i> field 00159 - <b>Data Transport Protocol</b> code in the <i>bInterfaceSubclass</i> field 00160 - <b>Bulk-Only Transport</b> protocol code (50h) in the <i>bInterfaceProtocol</i> field 00161 This example uses the SCSI transparent command set (code 06h). This is the 00162 most appropriate setting for a Flash device, given that the RBC command set 00163 is not supported by Microsoft Windows. 00164 \code 00165 // Mass Storage interface descriptor. 00166 { 00167 sizeof(USBInterfaceDescriptor), // bLength: Size of descriptor(9 bytes) 00168 USBGenericDescriptor_INTERFACE, // bDescriptorType: Interface descriptor 00169 0, // bInterfaceNumber: This is interface #0. 00170 0, // bAlternateSetting: This is alternate setting #0. 00171 2, // bNumEndpoints: Interface uses two endpoints. 00172 MSInterfaceDescriptor_CLASS, // bInterfaceClass: Mass Storage Device Class 00173 MSInterfaceDescriptor_SCSI, // bInterfaceSubClass: SCSI transparent command 00174 MSInterfaceDescriptor_BULKONLY,// bInterfaceProtocol: Bulk-Only transport 00175 0 // iInterface: No string descriptor for interface. 00176 }, 00177 \endcode 00178 00179 \subsubsection ep_dsc Endpoint Descriptors 00180 No special requirements on these apart from being Bulk-IN and Bulk-OUT. 00181 \code 00182 // Bulk-OUT endpoint descriptor 00183 { 00184 sizeof(USBEndpointDescriptor), // bLength: 7 bytes 00185 USBGenericDescriptor_ENDPOINT, // bDescriptorType: Endpoint descriptor 00186 USBEndpointDescriptor_ADDRESS( 00187 USBEndpointDescriptor_OUT, 00188 MSDDriverDescriptors_BULKOUT), // bEndpointAddress: OUT 0x01 00189 USBEndpointDescriptor_BULK, // bmAttributes: Bulk endpoint 00190 MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(MSDDriverDescriptors_BULKOUT), 00191 USBEndpointDescriptor_MAXBULKSIZE_FS), // wMaxPacketSize: 64 bytes 00192 0 // bInterval: Must be 0 for full-speed Bulk endpoints. 00193 }, 00194 // Bulk-IN endpoint descriptor 00195 { 00196 sizeof(USBEndpointDescriptor), // bLength: 7 bytes 00197 USBGenericDescriptor_ENDPOINT, // bDescriptorType: Endpoint descriptor 00198 USBEndpointDescriptor_ADDRESS( 00199 USBEndpointDescriptor_IN, 00200 MSDDriverDescriptors_BULKIN), // bEndpointAddress: IN 0x82 00201 USBEndpointDescriptor_BULK, // bmAttributes: Bulk endpoint 00202 MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(MSDDriverDescriptors_BULKIN), 00203 USBEndpointDescriptor_MAXBULKSIZE_FS), // wMaxPacketSize: 64 00204 0 // bInterval: Must be 0 for full-speed Bulk endpoints. 00205 } 00206 \endcode 00207 00208 \subsubsection str_dsc String descriptors 00209 Several descriptors can be commented with a String descriptor. The latter are 00210 completely optional and do not influence the detection of the device by the 00211 operating system. Whether or not to include them is entirely up to the 00212 programmer. 00213 00214 There is one exception to this rule when using the MSD class. According to the 00215 specification, there must be a Serial Number string. It must contains at least 00216 12 characters, and these characters must only be either letters (a-z, A-Z) or 00217 numbers (0-9). This cause no problem for the driver in practice, but this is a 00218 strict requirement for certification. Also remember that string descriptors 00219 use the Unicode format. 00220 00221 See \ref manufacturerDescriptor, \ref productDescriptor, \ref serialNumberDescriptor. 00222 00223 \subsection Class-specific Requests 00224 There are two Mass Storage-specific requests: 00225 - GetMaxLUN 00226 - Bulk-Only Mass Storage Reset 00227 00228 Standard requests can be forwarded to the \ref USBDDriver_RequestHandler, with one 00229 exception: <b>CLEAR_FEATURE</b>. This is necessary for Reset Recovery sequence. 00230 00231 \subsubsection ClearFeature 00232 As previously stated, the CLEAR_FEATURE request must be handled in a 00233 particular way, depending on whether or not the device is waiting for a Reset 00234 Recovery sequence. If it is, then CLEAR_FEATURE requests to unhalt a Bulk 00235 endpoint must be discarded. 00236 00237 In the example software, this behavior is indicated by a boolean field in the 00238 driver structure, named waitResetRecovery. The handler only has to check this 00239 field value to decide whether to forward the request to the standard handler 00240 or to discard it. 00241 \code 00242 // Handle requests 00243 switch (USBGenericRequest_GetRequest(request)) { 00244 //--------------------- 00245 case USBGenericRequest_CLEARFEATURE: 00246 //--------------------- 00247 00248 switch (USBFeatureRequest_GetFeatureSelector(request)) { 00249 00250 //--------------------- 00251 case USBFeatureRequest_ENDPOINTHALT: 00252 //--------------------- 00253 00254 // Do not clear the endpoint halt status if the device is waiting 00255 // for a reset recovery sequence 00256 if (!msdDriver.waitResetRecovery) { 00257 00258 // Forward the request to the standard handler 00259 USBDDriver_RequestHandler(&usbdDriver, request); 00260 } 00261 00262 USBD_Write(0, 0, 0, 0, 0); 00263 break; 00264 00265 //------ 00266 default: 00267 //------ 00268 // Forward the request to the standard handler 00269 USBDDriver_RequestHandler(&usbdDriver, request); 00270 } 00271 break; 00272 } 00273 \endcode 00274 00275 \subsubsection GetMaxLUN 00276 Usually, the first request issued by the host right after the enumeration 00277 phase will be a GET_MAX_LUN request. It enables it to discover how many 00278 different logical units the device has; each of these LUNs can then be queried 00279 in turn by the host when needed. 00280 00281 After the request is received by the device, it should return one byte of data 00282 indicating the maximum Logical Unit Number (LUN). It is equal to the number of 00283 LUNs used by the device minus one. For example, a device with three LUNs shall 00284 return a GET_MAX_LUN value of two. 00285 00286 Sending this byte is done by calling the \ref USBD_Write method on Control endpoint 00287 0. Note that the data must be held in a permanent buffer (since the transfer 00288 is asynchronous); in the software provided with this application note, a 00289 dedicated field is used in the driver structure (\ref MSDDriver) to store this 00290 value. 00291 00292 In addition due to the <i>Mass Storage Bulk-Only Transport</i> specification the 00293 <i>wValue</i> should be 0, <i>wLength</i> should be 1, <i>wIndex</i> should be the interface 00294 number also 0. A request which does not comply to these requirements must be 00295 STALLed. 00296 \code 00297 //------------------- 00298 case MSD_GET_MAX_LUN: 00299 //------------------- 00300 // Check request parameters 00301 if ((request->wValue == 0) 00302 && (request->wIndex == 0) 00303 && (request->wLength == 1)) { 00304 USBD_Write(0, &(msdDriver.maxLun), 1, 0, 0); 00305 } 00306 else { 00307 USBD_Stall(0); 00308 } 00309 break; 00310 \endcode 00311 00312 \subsubsection Bulk-Only Mass Storage Reset 00313 The host issues <b>RESET</b> requests to return the MSD driver of the device to its 00314 initial state, i.e., ready to receive a new command. However, this request 00315 does not impact the USB controller state; in particular, endpoints must not be 00316 reset. This means the data toggle bit must not be altered, and Halted endpoint 00317 must not be returned to a normal state. After processing the reset, the device 00318 must return a Zero-Length Packet (ZLP) to acknowledge the SETUP transfer. 00319 00320 Like GET_MAX_LUN, this request must be issued with specific parameters - 00321 wValue, wIndex and wLength should be zero. A request which does not have valid 00322 values in its field must be acknowledged with a STALL handshake from the 00323 device. 00324 00325 The handler for this request must return the state machine to its initial state. 00326 \code 00327 //----------------------- 00328 case MSD_BULK_ONLY_RESET: 00329 //----------------------- 00330 // Check parameters 00331 if ((request->wValue == 0) 00332 && (request->wIndex == 0) 00333 && (request->wLength == 0)) { 00334 00335 // Reset the MSD driver 00336 MSDDriver_Reset(); 00337 USBD_Write(0, 0, 0, 0, 0); 00338 } 00339 else { 00340 USBD_Stall(0); 00341 } 00342 break; 00343 \endcode 00344 00345 \subsection state_machine State Machine 00346 ... 00347 00348 \subsubsection Rationale 00349 A state machine is necessary for <b>non-blocking</b> operation of the driver. As 00350 previously stated, there are three steps when processing a command: 00351 - Reception of the CBW 00352 - Processing of the command (with data transfers if required) 00353 - Emission of the CSW 00354 00355 Without a state machine, the program execution would be stopped at each step 00356 to wait for transfers completion or command processing. For example, reception 00357 of a CBW does not always happen immediately (the host does not have to issue 00358 commands regularly) and can block the system for a long time. 00359 00360 Developing an asynchronous design based on a state machine is made easier when 00361 using Atmel \ref usbd_framework "AT91 USB device framework", as most methods are asynchronous. For 00362 example, a write operation (using the \ref USBD_Write function) returns 00363 immediately; a callback function can then be invoked when the transfer 00364 actually completes. 00365 00366 \subsubsection States 00367 Apart from the three states corresponding to the command processing flow (CBW, 00368 command processing and CSW), two more can be identified. The 00369 reception/emission of CBW/CSW will be broken down into two different states: 00370 the first state is used to issue the read/write operation, while the second 00371 one waits for the transfer to finish. This can be done by monitoring a 00372 "transfer complete" flag which is set using a callback function. 00373 00374 In addition, some commands can be quite complicated to process: they may 00375 require several consecutive data transfers mixed with media access. Each 00376 command thus has its own second-tier state machine. During execution of a 00377 command, the main state machine remains in the "processing" state, and 00378 proceeds to the next one (CSW emission) only when the command is complete. 00379 00380 Here is the states list: 00381 - \ref MSDD_STATE_READ_CBW : Start of CBW reception 00382 (initial state after reset) 00383 - \ref MSDD_STATE_WAIT_CBW : Waiting for CBW reception 00384 - \ref MSDD_STATE_PROCESS_CBW : Command processing 00385 - \ref MSDD_STATE_SEND_CSW : Start of CSW emission 00386 - \ref MSDD_STATE_WAIT_CSW : Waiting for CSW emission 00387 00388 A single function, named \ref MSDDriver_StateMachine, is provided by the driver. It 00389 must be called regularly during the program execution. The following 00390 subsections describe the actions that must be performed during each state. 00391 00392 \image html MSDDriverStates.png "MSD Driver State Machine" 00393 00394 <b>MSDD_STATE_READ_CBW</b> 00395 00396 As said previously, this state is used to start the reception of a new Command 00397 Block Wrapper. This is done using the USBD_Read() method of the USB framework. 00398 The result code of the function is checked for any error; the 00399 \ref USBD_STATUS_SUCCESS code indicates that the transfer has been successfully 00400 started. 00401 \code 00402 //---------------------- 00403 case MSDD_STATE_READ_CBW: 00404 //---------------------- 00405 // Start the CBW read operation 00406 transfer->semaphore = 0; 00407 status = USBD_Read(MSDDriverDescriptors_BULKOUT, 00408 cbw, 00409 MSD_CBW_SIZE, 00410 (TransferCallback) MSDDriver_Callback, 00411 (void *) transfer); 00412 00413 // Check operation result code 00414 if (status == USBD_STATUS_SUCCESS) { 00415 00416 // If the command was successful, wait for transfer 00417 msdDriver.state = MSDD_STATE_WAIT_CBW; 00418 } 00419 break; 00420 \endcode 00421 A callback function to invoke when the transfer is complete is provided to the 00422 USBD_Read method, to update a \ref MSDTransfer structure. This structure 00423 indicates the transfer completion, the returned result code and the number of 00424 transferred and remaining bytes. 00425 \code 00426 typedef struct { 00427 unsigned int transferred; //!< Number of bytes transferred 00428 unsigned int remaining; //!< Number of bytes not transferred 00429 unsigned char semaphore; //!< Semaphore to indicate transfer completion 00430 unsigned char status; //!< Operation result code 00431 } MSDTransfer; 00432 \endcode 00433 The callback function is trivial and thus not listed here. 00434 00435 <b>MSDD_STATE_WAIT_CBW</b> 00436 00437 The first step here is to monitor the <i>semaphore</i> field of the \ref MSDTransfer 00438 structure (see above); this will enable detection of the transfer end. Please 00439 note that this field must be declared as volatile in C, or accesses to it 00440 might get optimized by the compiler; this can result in endless loops. 00441 00442 If the transfer is complete, then the result code must be checked to see if 00443 there was an error. If the operation is successful, the state machine can 00444 proceed to command processing. Otherwise, it returns to the 00445 \ref MSDD_STATE_READ_CBW state. 00446 \code 00447 //---------------------- 00448 case MSDD_STATE_WAIT_CBW: 00449 //---------------------- 00450 // Check transfer semaphore 00451 if (transfer->semaphore > 0) { 00452 00453 // Take semaphore and terminate transfer 00454 transfer->semaphore--; 00455 00456 // Check if transfer was successful 00457 if (transfer->status == USBD_STATUS_SUCCESS) { 00458 00459 // Process received command 00460 msdDriver.state = MSDD_STATE_PROCESS_CBW; 00461 } 00462 else if (transfer->status == USBD_STATUS_RESET) { 00463 00464 msdDriver.state = MSDD_STATE_READ_CBW; 00465 } 00466 else { 00467 00468 msdDriver.state = MSDD_STATE_READ_CBW; 00469 } 00470 } 00471 break; 00472 \endcode 00473 00474 <b>MSDD_STATE_PROCESS_CBW</b> 00475 00476 Once the CBW has been received, its validity must be checked. A CBW is not 00477 valid if: 00478 - it has not been received right after a CSW was sent or a reset occured or 00479 - it is not exactly 31 bytes long or 00480 - its signature field is not equal to 43425355h 00481 00482 The state machine prevents the first case from happening, so only the two 00483 other cases have to be verified. 00484 00485 The number of bytes transferred during a USBD_Read() operation is passed as an 00486 argument to the callback function, if one has been specified. As stated 00487 previously, such a function is used to fill a \ref MSDTransfer structure. 00488 Therefore, it is trivial to check that the CBW is indeed 31 bytes by verifying 00489 that the number of bytes transferred is 31, and that there are no remaining 00490 bytes. The following table illustrates the three cases which may happen: 00491 00492 <table><tr> 00493 <td><b>Number of bytes transferred</b></td> 00494 <td><b>Number of bytes remaining</b></td> 00495 <td><b>Meaning</b></td></tr> 00496 <tr> 00497 <td>transferred<31</td> 00498 <td>remaining==0</td> 00499 <td>CBW is too short</td></tr> 00500 <tr> 00501 <td>transferred==31</td> 00502 <td>remaining>0</td> 00503 <td>CBW is too long</td></tr> 00504 <tr> 00505 <td>transferred==31</td> 00506 <td>remaining==0</td> 00507 <td>CBW length is correct</td></tr> 00508 </table> 00509 00510 Checking the signature is simply done by comparing the dCBWSignature field 00511 with the expected value (43425355h). 00512 00513 If the CBW is not valid, then the device must immediately halt both Bulk 00514 endpoints, to STALL further traffic from the host. In addition, it should stay 00515 in this state until a Reset Recovery is performed by the host. This is done by 00516 setting the waitResetRecovery flag in the MSDDriver structure. Finally, the 00517 CSW status is set to report an error, and the state machine is returned to 00518 \ref MSDD_STATE_READ_CBW. 00519 00520 Otherwise, if the CBW is correct, then the command can be processed. Remember 00521 the CBW tag must be copied regardless of the validity of the CBW. 00522 00523 Note that these steps are only necessary for a new command (remember commands 00524 are asynchronous and are carried out in several calls, so a check can be 00525 performed to avoid useless processing. A value of zero for the internal 00526 command state indicates a new command. 00527 \code 00528 //------------------------- 00529 case MSDD_STATE_PROCESS_CBW: 00530 //------------------------- 00531 // Check if this is a new command 00532 if (commandState->state == 0) { 00533 00534 // Copy the CBW tag 00535 csw->dCSWTag = cbw->dCBWTag; 00536 00537 // Check that the CBW is 31 bytes long 00538 if ((transfer->transferred != MSD_CBW_SIZE) || 00539 (transfer->remaining != 0)) { 00540 00541 // Wait for a reset recovery 00542 msdDriver.waitResetRecovery = 1; 00543 00544 // Halt the Bulk-IN and Bulk-OUT pipes 00545 USBD_Halt(MSDDriverDescriptors_BULKOUT); 00546 USBD_Halt(MSDDriverDescriptors_BULKIN); 00547 00548 csw->bCSWStatus = MSD_CSW_COMMAND_FAILED; 00549 msdDriver.state = MSDD_STATE_READ_CBW; 00550 00551 } 00552 // Check the CBW Signature 00553 else if (cbw->dCBWSignature != MSD_CBW_SIGNATURE) { 00554 00555 // Wait for a reset recovery 00556 msdDriver.waitResetRecovery = 1; 00557 00558 // Halt the Bulk-IN and Bulk-OUT pipes 00559 USBD_Halt(MSDDriverDescriptors_BULKOUT); 00560 USBD_Halt(MSDDriverDescriptors_BULKIN); 00561 00562 csw->bCSWStatus = MSD_CSW_COMMAND_FAILED; 00563 msdDriver.state = MSDD_STATE_READ_CBW; 00564 } 00565 else { 00566 00567 // Pre-process command 00568 MSDDriver_PreProcessCommand(); 00569 } 00570 } 00571 00572 // Process command 00573 if (csw->bCSWStatus == MSDD_STATUS_SUCCESS) { 00574 00575 if (MSDDriver_ProcessCommand()) { 00576 00577 // Post-process command if it is finished 00578 MSDDriver_PostProcessCommand(); 00579 msdDriver.state = MSDD_STATE_SEND_CSW; 00580 } 00581 } 00582 00583 break; 00584 \endcode 00585 00586 <b>MSDD_STATE_SEND_CSW</b> 00587 00588 This state is similar to \ref MSDD_STATE_READ_CBW, except that a write 00589 operation is performed instead of a read and the CSW is sent, not the CBW. The 00590 same callback function is used to fill the transfer structure, which is 00591 checked in the next state: 00592 \code 00593 //---------------------- 00594 case MSDD_STATE_SEND_CSW: 00595 //---------------------- 00596 // Set signature 00597 csw->dCSWSignature = MSD_CSW_SIGNATURE; 00598 00599 // Start the CSW write operation 00600 status = USBD_Write(MSDDriverDescriptors_BULKIN, 00601 csw, 00602 MSD_CSW_SIZE, 00603 (TransferCallback) MSDDriver_Callback, 00604 (void *) transfer); 00605 00606 // Check operation result code 00607 if (status == USBD_STATUS_SUCCESS) { 00608 00609 // Wait for end of transfer 00610 msdDriver.state = MSDD_STATE_WAIT_CSW; 00611 } 00612 break; 00613 \endcode 00614 00615 <b>MSDD_STATE_WAIT_CSW</b> 00616 00617 Again, this state is very similar to \ref MSDD_STATE_WAIT_CBW. The only 00618 difference is that the state machine is set to \ref MSDD_STATE_READ_CBW 00619 regardless of the operation result code: 00620 \code 00621 //---------------------- 00622 case MSDD_STATE_WAIT_CSW: 00623 //---------------------- 00624 // Check transfer semaphore 00625 if (transfer->semaphore > 0) { 00626 00627 // Take semaphore and terminate transfer 00628 transfer->semaphore--; 00629 00630 // Read new CBW 00631 msdDriver.state = MSDD_STATE_READ_CBW; 00632 } 00633 break; 00634 \endcode 00635 00636 \subsection Media 00637 00638 USB MSD Media access is three-level abstraction. 00639 00640 \image html MSDMediaArch.png "Media Architecture" 00641 00642 The bottom level is the specific driver for each media type (See memories). 00643 00644 In the middle, a structure \ref Media is used to hide which specific driver a media 00645 instance is using. This enables transparent use of any media driver once it 00646 has been initialized (See _Media). 00647 00648 Finally, a LUN abstraction is made over the media structure to allow multiple 00649 partitions over one media. This also makes it possible to place the LUN at any 00650 address and use any block size. When performing a write or read operation on a 00651 LUN, it forwards the operation to the underlying media while translating it to 00652 the correct address and length. 00653 00654 \subsubsection med_drv Media Drivers 00655 A media driver must provide several functions for: 00656 - Reading data from the media 00657 - Writing data on the media 00658 - Handling interrupts on the media 00659 The last function may be empty if the media does not require interrupts for 00660 asynchronous operation, or if synchronous operation produces an acceptable 00661 delay. 00662 00663 In addition, it should also define a function for initializing a Media 00664 structure with the correct values, as well as perform the necessary step for 00665 the media to be useable. 00666 00667 For the drivers see: 00668 - MEDSdram.h: <i>Internal Flash Driver</i> 00669 - MEDFlash.h: <i>SDRAM disk driver</i> 00670 00671 \subsection scsi_cmd SCSI Commands 00672 00673 The example software described in this application note uses SCSI commands 00674 with the MSD class, since this is the most appropriate setting for a Flash 00675 device. This section details how SCSI commands are processed. 00676 00677 \subsubsection Documents 00678 00679 There are several documents covering SCSI commands. In this application note, 00680 the reference document used is SCSI Block Commands - 3 (SBC-3). However, it 00681 makes many references to another SCSI document, SCSI Primary Commands - 4 00682 (SPC-4). Both are needed for full details on required commands. 00683 00684 \subsubsection Endianness 00685 00686 SCSI commands use the big-endian format for storing word- and double word- 00687 sized data. This means the Most Significant Bit (MSB) is stored at the 00688 lowest address, and the Least Significant Bit (LSB) at the highest one. 00689 00690 On ARM Thumb microcontrollers, the endianness of the core is selectable. 00691 However, the little-endian mode is most often used. Therefore, SCSI command 00692 data must be converted before being usable. This is done by declaring 00693 word- and dword-sized fields as byte arrays, and then using a macro for 00694 loading or storing data. Several of them are available in the provided 00695 software: 00696 - Load 00697 - WORDB: Converts a big-endian word value to little-endian 00698 - DWORDB: Converts a big-endian double-word value to little-endian 00699 - Store 00700 - STORE_WORDB: Stores a little-endian word value in big-endian format 00701 - STORE_DWORDB: Stores a little-endian double-word value in big-endian format 00702 00703 \subsubsection sense_data Sense Data 00704 00705 When an error happens during the execution of a command, it is recorded by the 00706 device. The host may then issue a Request Sense command to retrieve 00707 <b>Sense Data</b>, i.e., information about previous errors. 00708 00709 While the sense data structure has many fields, only three are really 00710 important. The first one is the Sense Key. It indicates the result of the last 00711 command performed: success, media not ready, hardware error, etc. Two other 00712 fields can then be specified to give a more accurate description of the 00713 problem. They are named <i>Additional Sense Code</i> and <i>Additional Sense Code 00714 Qualifier</i>. 00715 00716 In the example application, each LUN has its own sense data. It is updated 00717 during command execution if there is any error. 00718 00719 \subsubsection Commands 00720 00721 The SBC-3 specification gives a list of mandatory and optional commands that 00722 are relevant for a block device (like a Flash drive). In practice, only a 00723 subset of the mandatory commands is effectively used by operating systems; 00724 conversely, several commands which are supposed to be optional are required. 00725 The software provided with this application note implements the following list 00726 of commands: 00727 - SBC-3 00728 - Prevent/Allow Medium Removal 00729 - Read (10) 00730 - Read Capacity (10) 00731 - Verify (10) 00732 - Write (10) 00733 - SPC-4 00734 - Inquiry 00735 - Mode Sense (6) 00736 - Request Sense 00737 - Test Unit Ready 00738 The commands are actually processed in SBC_ProcessCommand. 00739 00740 <i>Internal State Machine</i> 00741 00742 As previously stated, most commands have an internal state machine to prevent 00743 blocking the whole system during a data transfer (on the USB or when accessing 00744 a media). A result code is used to indicate that the corresponding function 00745 must be called again for the command to complete (\ref MSDD_STATUS_SUCCESS). 00746 00747 A command state structure is used by the driver to record several parameters 00748 during command processing: 00749 \code 00750 typedef struct { 00751 00752 MSDTransfer transfer; //!< Current transfer status 00753 MSCbw cbw; //!< Received CBW 00754 MSCsw csw; //!< CSW to send 00755 unsigned char state; //!< Current command state 00756 unsigned char postprocess; //!< Actions to perform when command is complete 00757 unsigned int length; //!< Remaining length of command 00758 00759 } MSDCommandState; 00760 \endcode 00761 00762 Note that the <i>state</i> field must be initialized when the command is first 00763 called. A value of 0 means that no command is currently being executed. 00764 00765 For the commands descriptions and implementation, please reffer to the SCSI 00766 spec. and source code. 00767 00768 Functions to handle SCSI commands: 00769 - SBC_Inquiry 00770 - SBC_Read10 00771 - SBC_ReadCapacity10 00772 - SBC_RequestSense 00773 - SBC_TestUnitReady 00774 - SBC_Write10 00775 - SBC_ModeSense6 00776 00777 \subsubsection cmd_process Command Processing 00778 00779 <i>Flow</i> 00780 00781 Command processing is actually divided into three phases in the example 00782 software: 00783 - Pre-processing: MSDDriver_PreProcessCommand 00784 - Processing: MSDDriver_ProcessCommand 00785 - Post-processing: MSDDriver_PostProcessCommand 00786 00787 <i>The Thirteen Cases</i> 00788 00789 There are basically three actions that should be performed depending on the 00790 case: 00791 - STALL the Bulk-IN endpoint 00792 - STALL the Bulk-OUT endpoint 00793 - Report a Phase Error in the CSW 00794 00795 The table below lists all cases along with the actions which must be taken 00796 after the command, including the correct length/direction of the transfer. The 00797 following notation is used to characterize host and device expectations: 00798 00799 Data Transfer Characterization 00800 <table><tr> 00801 <td><b>Notation</b></td> 00802 <td><b>Meaning</b></td> 00803 <td><b>Notation</b></td> 00804 <td><b>Meaning</b></td></tr> 00805 <tr> 00806 <td>Hn</td> 00807 <td>Host expects no data transfer</td> 00808 <td>Dn</td> 00809 <td>Device expects no data transfer</td></tr> 00810 <tr> 00811 <td>Hi</td> 00812 <td>Host expects to <b>receive</b> data</td> 00813 <td>Di</td> 00814 <td>Device expects to <b>send</b> data</td></tr> 00815 <tr> 00816 <td>Ho</td> 00817 <td>Host expects to <b>send</b> data</td> 00818 <td>Do</td> 00819 <td>Device expects to <b>receive</b> data</td></tr> 00820 <tr> 00821 <td>Lh</td> 00822 <td>Length of data expected by the host</td> 00823 <td>Ld</td> 00824 <td>Length of data expected by the device</td></tr> 00825 00826 <tr> 00827 <td>Hx=Dx</td> 00828 <td>Host and device agree on transfer length and direction (x is either n, i or o)</td> 00829 <td> </td> 00830 <td> </td></tr> 00831 <tr> 00832 <td>Hx>Dx</td> 00833 <td>Host and device agree on transfer direction, host expects a larger transfer than device</td> 00834 <td> </td> 00835 <td> </td></tr> 00836 <tr> 00837 <td>Hx<Dx</td> 00838 <td>Host and device agree on transfer direction, device expects a larger transfer than host</td> 00839 <td> </td> 00840 <td> </td></tr> 00841 <tr> 00842 <td>Hx<>Dx</td> 00843 <td>Host and device disagree on transfer direction</td> 00844 <td> </td> 00845 <td> </td></tr> 00846 </table> 00847 00848 The Thirteen Cases 00849 <table><tr> 00850 <td><b>\#</b></td> 00851 <td><b>Case</b></td> 00852 <td><b>Length</b></td> 00853 <td><b>Residue</b></td> 00854 <td><b>Direction</b></td> 00855 <td><b>STALL IN?</b></td> 00856 <td><b>STALL OUT?</b></td> 00857 <td><b>Phase Error?</b></td></tr> 00858 <tr> 00859 <td>1</td><td>Hn = Dn</td><td>0</td><td>0</td><td>Irrelevant</td><td> </td><td> </td><td> </td></tr> 00860 <tr> 00861 <td>2</td><td>Hn < Di</td><td>0</td><td>Ld - Lh</td><td>Irrelevant</td><td> </td><td> </td><td>X</td></tr> 00862 <tr> 00863 <td>3</td><td>Hn < Do</td><td>0</td><td>Ld - Lh</td><td>Irrelevant</td><td> </td><td> </td><td>X</td></tr> 00864 <tr> 00865 <td>4</td><td>Hi > Dn</td><td>0</td><td>Lh</td><td>Irrelevant</td><td>X</td><td> </td><td> </td></tr> 00866 <tr> 00867 <td>5</td><td>Hi > Di</td><td>Ld</td><td>Lh - Ld</td><td>In</td><td>X</td><td> </td><td> </td></tr> 00868 <tr> 00869 <td>6</td><td>Hi = Di</td><td>Ld</td><td>0</td><td>In</td><td> </td><td> </td><td> </td></tr> 00870 <tr> 00871 <td>7</td><td>Hi < Di</td><td>Lh</td><td>Ld - Lh</td><td>In</td><td> </td><td> </td><td>X</td></tr> 00872 <tr> 00873 <td>8</td><td>Hi <> Do</td><td>0</td><td>0</td><td>Irrelevant</td><td>X</td><td> </td><td>X</td></tr> 00874 <tr> 00875 <td>9</td><td>Ho > Dn</td><td>0</td><td>Lh</td><td>Irrelevant</td><td> </td><td>X</td><td> </td></tr> 00876 <tr> 00877 <td>10</td><td>Ho <> Di</td><td>0</td><td>0</td><td>Irrelevant</td><td> </td><td>X</td><td>X</td></tr> 00878 <tr> 00879 <td>11</td><td>Ho > Do</td><td>Ld</td><td>Lh - Ld</td><td>Out</td><td> </td><td>X</td><td> </td></tr> 00880 <tr> 00881 <td>12</td><td>Ho = Do</td><td>Ld</td><td>0</td><td>Out</td><td> </td><td> </td><td> </td></tr> 00882 <tr> 00883 <td>13</td><td>Ho < Do</td><td>Lh</td><td>Lh - Ld</td><td>Out</td><td> </td><td> </td><td>X</td></tr> 00884 </table> 00885 00886 \subsection main_app Main Application 00887 After the MSD driver and the media have been initialized using the 00888 corresponding functions, the only requirement for the main application is to 00889 regularly call the state machine function. This is necessary for processing 00890 received commands in a fully asynchronous way. 00891 00892 The application is otherwise free of doing any other task; for example, it 00893 could implement a filesystem and a serial port interface to be accessed with a 00894 standard terminal. An MP3 player could also continue playing a song while its 00895 memory is accessed like an external hard disk. 00896 00897 \image html MSDDriverClasses.png "Driver Class Diagram" 00898 00899 */ 00900 /** 00901 \page usb_msd_basic USB MSD Basic 00902 00903 This page gives generic details on the MSD class. 00904 00905 \section Purpose 00906 00907 The MSD class defines how devices such as a hard disk, a USB floppy disk drive 00908 or a disk-on-key shall operate on the USB. These devices are referred to as 00909 mass storage devices, since they usually offer a high storage capacity. When 00910 plugged to a PC, a device complying to the MSD specification is accessed like 00911 any other disk on the system. 00912 00913 In practice, the specification only defines a way to wrap existing data 00914 transfer protocols, such as SCSI or the Reduced Block Commands (RBC) set. A 00915 list of the supported protocols and their uses will be given in the following 00916 section. 00917 00918 \section msc_data_tran_p Data Transfer Protocols 00919 00920 The <i>Mass Storagae Class Specification Overview 1.2</i> supports the following 00921 set of devices: 00922 00923 Protocols for MSD devices 00924 <table><tr> 00925 <td><b>Subclass Code</b></td> 00926 <td><b>Command Block Spec.</b></td> 00927 <td><b>Used by</b></td></tr> 00928 <tr> 00929 <td>01h</td> 00930 <td>Reduced Block Commands(RBC)</td> 00931 <td>Flash devices</td></tr> 00932 <tr> 00933 <td>02h</td> 00934 <td>SFF-8020i, MMC-2</td> 00935 <td>CD & DVD devices</td></tr> 00936 <tr> 00937 <td>03h</td> 00938 <td>QIC-157</td> 00939 <td>Tape devices</td></tr> 00940 <tr> 00941 <td>04h</td> 00942 <td>UFI</td> 00943 <td>Floppy disk drives</td></tr> 00944 <tr> 00945 <td>05h</td> 00946 <td>SFF-8070i</td> 00947 <td>Floppy disk drives</td></tr> 00948 <tr> 00949 <td>06h</td> 00950 <td>SCSI transparent command set</td> 00951 <td>Any</td></tr> 00952 </table> 00953 00954 The SCSI transparent command set comprises all SCSI-related specifications, 00955 such as SCSI Primary Commands (SPC), SCSI Block Commands (SBC), and so on. A 00956 command will be issued by the host to determine exactly with which standard 00957 the device is compliant. 00958 00959 The protocol used by the device is specified in its Interface descriptor, in 00960 the <i>bInterfaceSubclass</i> field. 00961 00962 \section trans_pro Transfer Protocols 00963 00964 There are actually two different transport protocols for the MSD class: 00965 - Control/Bulk/Interface (CBI) transport 00966 - Bulk-Only Transport (BOT) 00967 00968 These two methods are described in two separate stand-alone documents. CBI can 00969 be considered obsolete and is being completely replaced by BOT. It was 00970 originally targeted at full-speed floppy disk drives. Therefore, the rest of 00971 this document will talk about Bulk-Only Transport exclusively. 00972 00973 Transport Protocol Codes 00974 <table><tr> 00975 <td><b>bInterfaceProtocol</b></td> 00976 <td><b>Protocol Implementation</b></td></tr> 00977 <tr> 00978 <td>00h</td> 00979 <td>Control/Bulk/Interrupt protocol (with command completion interrupt)</td></tr> 00980 <tr> 00981 <td>01h</td> 00982 <td>Control/Bulk/Interrupt protocol (without command completion interrupt)</td></tr> 00983 <tr> 00984 <td>50h</td> 00985 <td>Bulk-only transport</td></tr> 00986 </table> 00987 00988 \section Architecture 00989 00990 \subsection msc_if_ep Interfaces & Endpoints 00991 00992 An MSD device only needs one single interface. The bInterfaceClass field of 00993 the interface descriptor should be set to MSD class code (0x08), the 00994 corresponding data transfer protocol code in the <i>bInterfaceSubclass</i> field 00995 and transport protocol code in the <i>bInterfaceProtocol</i> field can be found in 00996 the tables on above. 00997 00998 Exactly three endpoints (when using the Bulk-Only Transport protocol) are 00999 necessary for MSD devices. 01000 01001 The first one is the Control endpoint 0, and is used for class-specific 01002 requests and for clearing Halt conditions on the other two endpoints. 01003 Endpoints are halted in response to errors and host bad behavior during data 01004 transfers, and the CLEAR_FEATURE request is consequently used to return them 01005 to a functional state. 01006 01007 The other two endpoints, which are of type Bulk, are used for transferring 01008 commands and data over the bus. There must be one Bulk-IN and one Bulk-OUT 01009 endpoint. 01010 01011 \image html MSDDriverArch.png "Mass Storage Device Driver Architecture" 01012 01013 \subsection Class-Specific Descriptors 01014 No class-specific descriptors for an MSD device using the Bulk-only transfport 01015 protocol. 01016 01017 \subsection Class-Specific Requests 01018 Two class specific requests should be handled. 01019 01020 \subsubsection GetMaxLUN 01021 A device can feature one or more Logical Unit (LU). Each of these units will 01022 be treated as a separate disk when plugged to a computer. A device can have up 01023 to 15 logical units. 01024 01025 The GET_MAX_LUN request is issued by the host to determine the maximum Logical 01026 Unit Number (LUN) supported by the device. This is not equivalent to the 01027 number of LU on the device; since units are numbered starting from 0, a device 01028 with 5 LUs should report a value of 4, which will be the index of the fifth 01029 unit. 01030 01031 Optionally, a device with only one LUN may STALL this request instead of 01032 returning a value of zero. 01033 01034 \subsubsection Bulk-Only Mass Storage Reset 01035 This request is used to reset the state of the device and prepare it to 01036 receive commands and data. Note that the data toggle bits must not be altered 01037 by a RESET command; same for the Halt state of endpoints, i.e., halted 01038 endpoints must not be reset to a normal state. 01039 01040 \subsection Command/Data/Status 01041 Each MSD transaction is divided into three steps: 01042 - Command stage 01043 - Data stage (optional) 01044 - Status stage 01045 01046 During the command stage, a Command Block Wrapper (CBW) is transmitted by the 01047 host to the device. The CBW describes several parameters of the transaction 01048 (direction, length, LUN) and carries a variable-length command block. The 01049 command block contains data in the format defined by the transfer protocol 01050 used by the device. 01051 01052 Command Block Wrapper Data Format 01053 \if doxys_table 01054 ||Offset||Field Name||Length||Comment 01055 |0|dCBWSignature|4 bytes|Signature to identify CBW, must be 43425355h 01056 |4|dCBWTag|4 bytes|Tag sent by the host, echoed in the CSW 01057 |8|dCBWTransferLength|4 bytes|Length of transfer during the data stage 01058 |12|bmCBWFlags|1 byte|Bits 0-6: Reserved/obsolete\n 01059 Bit 7: Transfer direction (0 = OUT, 1 = IN) 01060 |13|bCBWLUN|1 byte|Bits 0-3: LUN to which the command is sent\n 01061 Bits 4-7: Reserved 01062 |14|bCBWCBLength|1 byte|Bits 0-5: Length of command block in bytes\n 01063 Bits 6-7: Reserved 01064 |15|CBWCB|0-16 bytes|Command block to be executed by the device 01065 \endif 01066 <table><tr> 01067 <td><b>Offset</b></td> 01068 <td><b>Field Name</b></td> 01069 <td><b>Length</b></td> 01070 <td><b>Comment</b></td></tr> 01071 <tr> 01072 <td>0</td> 01073 <td>dCBWSignature</td> 01074 <td>4 bytes</td> 01075 <td>Signature to identify CBW, must be 43425355h</td></tr> 01076 <tr> 01077 <td>4</td> 01078 <td>dCBWTag</td> 01079 <td>4 bytes</td> 01080 <td>Tag sent by the host, echoed in the CSW</td></tr> 01081 <tr> 01082 <td>8</td> 01083 <td>dCBWTransferLength</td> 01084 <td>4 bytes</td> 01085 <td>Length of transfer during the data stage</td></tr> 01086 <tr> 01087 <td>12</td> 01088 <td>bmCBWFlags</td> 01089 <td>1 byte</td> 01090 <td>Bits 0-6: Reserved/obsolete<br>Bit 7: Transfer direction (0 = OUT, 1 = IN)</td></tr> 01091 <tr> 01092 <td>13</td> 01093 <td>bCBWLUN</td> 01094 <td>1 byte</td> 01095 <td>Bits 0-3: LUN to which the command is sent<br>Bits 4-7: Reserved</td></tr> 01096 <tr> 01097 <td>14</td> 01098 <td>bCBWCBLength</td> 01099 <td>1 byte</td> 01100 <td>Bits 0-5: Length of command block in bytes<br>Bits 6-7: Reserved</td></tr> 01101 <tr> 01102 <td>15</td> 01103 <td>CBWCB</td> 01104 <td>0-16 bytes</td> 01105 <td>Command block to be executed by the device</td></tr> 01106 </table> 01107 01108 After the device has received and interpreted the command, an optional data 01109 stage may take place if the command requires it. During this step, data is 01110 transferred either to or from the device depending on the command, in several 01111 IN/OUT transfers. 01112 01113 Once the data stage is complete, the host issues a final IN request on the 01114 Bulk-IN endpoint of the device to request the Command Status Wrapper (CSW). 01115 The CSW is used to report correct or incorrect execution of the command, as 01116 well as indicating the length of remaining data that has not been transferred. 01117 01118 Command Status Wrapper 01119 \if doxys_table 01120 ||Offset||Field Name||Length||Comment 01121 |0|dCSWSignature|4 bytes|Signature to identify CSW, must be 53425355h 01122 |4|dCSWTag|4 bytes|Copy of previous CBW tag 01123 |8|dCSWDataResidue|4 bytes|Difference between expected and real transfer length 01124 |12|bCSWStatus|1 byte|Indicates the success or failure of the command 01125 \endif 01126 <table><tr> 01127 <td><b>Offset</b></td> 01128 <td><b>Field Name</b></td> 01129 <td><b>Length</b></td> 01130 <td><b>Comment</b></td></tr> 01131 <tr> 01132 <td>0</td> 01133 <td>dCSWSignature</td> 01134 <td>4 bytes</td> 01135 <td>Signature to identify CSW, must be 53425355h</td></tr> 01136 <tr> 01137 <td>4</td> 01138 <td>dCSWTag</td> 01139 <td>4 bytes</td> 01140 <td>Copy of previous CBW tag</td></tr> 01141 <tr> 01142 <td>8</td> 01143 <td>dCSWDataResidue</td> 01144 <td>4 bytes</td> 01145 <td>Difference between expected and real transfer length</td></tr> 01146 <tr> 01147 <td>12</td> 01148 <td>bCSWStatus</td> 01149 <td>1 byte</td> 01150 <td>Indicates the success or failure of the command</td></tr> 01151 </table> 01152 These steps are all performed on the two Bulk endpoints, and do not involve 01153 Control endpoint 0 at all. 01154 01155 \subsection Reset Recovery 01156 When severe errors occur during command or data transfers (as defined in the 01157 <i>Mass Storage Bulk-only Transport 1.0</i> document), the device must halt both 01158 Bulk endpoints and wait for a <b>Reset Recovery</b> procedure. The Reset Recovery 01159 sequence goes as follows: 01160 - The host issues a Bulk-Only Mass Storage Reset request 01161 - The host issues two <b>CLEAR_FEATURE</b> requests to unhalt each endpoint 01162 01163 A device waiting for a Reset Recovery must not carry out CLEAR_FEATURE 01164 requests trying to unhalt either Bulk endpoint until after a Reset request has 01165 been received. This enables the host to distinguish between severe and minor 01166 errors. 01167 01168 The only major error defined by the Bulk-Only Transport standard is when a CBW 01169 is not valid. This means one or more of the following: 01170 - The CBW is not received after a CSW has been sent or a reset. 01171 - The CBW is not exactly 31 bytes in length. 01172 - The dCBWSignature field of the CBW is not equal to 43425355h. 01173 01174 \section host_drv Host Drivers 01175 Almost all operating systems now provide a generic driver for the MSD class. 01176 However, the set of supported data transfer protocols may vary. For example, 01177 Microsoft Windows does not currently support the Reduced Block Command set. 01178 01179 */