SAMV71 Xplained Ultra Software Package 1.3

massstorage.dir

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 */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines