/* ----------------------------------------------------------------------------
 *         ATMEL Microcontroller Software Support 
 * ----------------------------------------------------------------------------
 * Copyright (c) 2008, Atmel Corporation
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the disclaimer below.
 *
 * Atmel's name may not be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
 * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ----------------------------------------------------------------------------
 */

//------------------------------------------------------------------------------
/// \dir
///
/// !!!Purpose
///
/// This directory provides definitions, structs and functions for a USB Mass
/// Storage %device (MSD) - USB Mass Storage demo.
///
/// !!!Contents
///
/// There are four things for the implement of the USB MSD driver:
/// - Implement the MSD driver structs and functions for the %device,
///   to initialize, to handle MSD-specific requests and dispach
///   standard requests in USBD callbacks, to read/write through assigned USB
///   %endpoints,
/// - Create the MSD device's descriptors that should be passed to
///   the USBDDriver instance on initialization, so that the host can 
///   recognize the %device as a USB Mass Storage %device.
/// - Implement state machine for MSD command/data/status handling.
/// - Implement storage media interface for MSD disk accessing.
///
/// For more information about what a particular group contains, please refer to
/// "USB MSD Driver".
//------------------------------------------------------------------------------

/**
 \page "USB MSD Driver"
 This page describes how to use the USB framework to produce a USB MSD driver,
 which appears as a USB Disk on host.

 !!!References
 - "AT91 USB device framework"
 - "USB Device Enumeration"
 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip">
   Universal Serial Bus Revision 2.0 specification
   </a> (.zip file format, size 9.80 MB)
 - <a href="http://www.usb.org/developers/devclass_docs/usb_msc_overview_1.2.pdf">
   Mass Storage Overview 1.2</a>
 - <a href="http://www.usb.org/developers/devclass_docs/usbmassbulk_10.pdf">
   Mass Storage Bulk Only 1.0</a>
 - <a href="http://www.t10.org/scsi-3.htm">SCSI Standards</a>
    - SCSI Block Commands - 3 (SBC-3)
    - SCSI Primary Commands - 4 (SPC-4)

 !!!Mass Storage Class Basic
 This section gives generic details on the MSD class.

 See "USB MSD Basic".

 !!!Mass Storage SCSI Disk

 This section describes how to implement a USB disk by using the MSD class with
 the SCSI transparent command set and the AT91 USB Framework. For more
 information about the framework, please refer to the "AT91 USB device
 framework" application note; details about the USB and the Mass Storage class
 can be found in the USB specification 2.0 and the MSC Bulk-Only Transport
 specification 1.0 documents, respectively.

 The software example provided with this document uses the ram disk of the chip
 as its storage medium, but has been designed in a modular way to allow easy
 modification for any medium, e.g. internal flash, DataFlash, SD card, external
 Flash chip.

 !!Architecture
 The MSD driver is based on framework, See "USB Device Framework Architecture".

 The internal architecture of the Application layer is extended for the
 following factors:
 - The Command/Data/Status flow described in "USB MSD Basic" requires the use
   of a #state machine# for non-blocking operation.
 - The example software has been designed to be easily extended with support
   for other media.
 - The example software has been designed to support multiple LUNs on one or
   more media.

 \image MSDAppArch.png "Application Layer Architecture"

 !!Descriptors
 There are no class-specific descriptors for a device using the MSD class with
 the Bulk-only transport protocol. This section thus only details the values
 which must be set in the standard descriptors.

 !Device Descriptor
\code
static const USBDeviceDescriptor deviceDescriptor = {

    sizeof(USBDeviceDescriptor), // bLength: Size of descriptor (18 bytes)
    USBGenericDescriptor_DEVICE, // bDescriptorType: Device descriptor
    USBDeviceDescriptor_USB2_00, // bcdUSB: USB 2.00
    MSDeviceDescriptor_CLASS,    // bDeviceClass: 0
    MSDeviceDescriptor_SUBCLASS, // bDeviceSubClass: 0
    MSDeviceDescriptor_PROTOCOL, // bDeviceProtocol: 0
    BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0), // bMaxPacketSize0: Max Size EP0
    MSDDriverDescriptors_VENDORID, // idVendor: Vendor ID ATMEL (0x03eb)
    MSDDriverDescriptors_PRODUCTID,// idProduct: Product ID (0x6202)
    MSDDriverDescriptors_RELEASE,  // bcdDevice: 0x0001, Version 0.01
    1, // iManufacturer: Manufacturer string (manufacturerDescriptor) index.
    2, // iProduct: Product string (productDescriptor) index.
    3, // iSerialNumber: Serial number string (serialNumberDescriptor) index.
    1  // bNumConfigurations: Device has one possible configuration.
};
\endcode
 Note that the Vendor ID is a special value attributed by the USB-IF
 organization. The product ID can be chosen freely by the vendor.

 !Configuration Descriptor
 The descriptors are defined as:
\code
const MSDConfigurationDescriptors configurationDescriptorsFS;
\endcode

 Configuration descriptor
\code
// Standard configuration descriptor.
{
    sizeof(USBConfigurationDescriptor), // bLength: 9 bytes
    USBGenericDescriptor_CONFIGURATION, // bDescriptorType: Configuration
    sizeof(MSDConfigurationDescriptors),// wTotalLength: Length of all
    1, // bNumInterface: Configuration has one interface.
    1, // bConfigurationValue: This is configuration #1.
    0, // iConfiguration: No string descriptor for configuration.
    BOARD_USB_BMATTRIBUTES, // bmAttributes: Power and remote wakeup
    USBConfigurationDescriptor_POWER(100) // 100mA max power
},
\endcode

 !Interface Descriptor
 The interface descriptor must indicate several features:
 - #Mass Storage Device# class code (08h) in the }bInterfaceClass} field
 - #Data Transport Protocol# code in the }bInterfaceSubclass} field
 - #Bulk-Only Transport# protocol code (50h) in the }bInterfaceProtocol} field
 This example uses the SCSI transparent command set (code 06h). This is the
 most appropriate setting for a Flash %device, given that the RBC command set
 is not supported by Microsoft Windows.
\code
// Mass Storage interface descriptor.
{
    sizeof(USBInterfaceDescriptor), // bLength: Size of descriptor(9 bytes)
    USBGenericDescriptor_INTERFACE, // bDescriptorType: Interface descriptor
    0, // bInterfaceNumber: This is interface #0.
    0, // bAlternateSetting: This is alternate setting #0.
    2, // bNumEndpoints: Interface uses two endpoints.
    MSInterfaceDescriptor_CLASS, // bInterfaceClass: Mass Storage Device Class
    MSInterfaceDescriptor_SCSI, // bInterfaceSubClass: SCSI transparent command
    MSInterfaceDescriptor_BULKONLY,// bInterfaceProtocol: Bulk-Only transport
    0 // iInterface: No string descriptor for interface.
},
\endcode

 !Endpoint Descriptors
 No special requirements on these apart from being Bulk-IN and Bulk-OUT.
\code
// Bulk-OUT endpoint descriptor
{
    sizeof(USBEndpointDescriptor), // bLength: 7 bytes
    USBGenericDescriptor_ENDPOINT, // bDescriptorType: Endpoint descriptor
    USBEndpointDescriptor_ADDRESS(
        USBEndpointDescriptor_OUT,
        MSDDriverDescriptors_BULKOUT), // bEndpointAddress: OUT 0x01
    USBEndpointDescriptor_BULK, // bmAttributes: Bulk endpoint
    MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(MSDDriverDescriptors_BULKOUT),
        USBEndpointDescriptor_MAXBULKSIZE_FS), // wMaxPacketSize: 64 bytes
    0 // bInterval: Must be 0 for full-speed Bulk endpoints.
},
// Bulk-IN endpoint descriptor
{
    sizeof(USBEndpointDescriptor), // bLength: 7 bytes
    USBGenericDescriptor_ENDPOINT, // bDescriptorType: Endpoint descriptor
    USBEndpointDescriptor_ADDRESS(
        USBEndpointDescriptor_IN,
        MSDDriverDescriptors_BULKIN), // bEndpointAddress: IN 0x82
    USBEndpointDescriptor_BULK, // bmAttributes: Bulk endpoint
    MIN(BOARD_USB_ENDPOINTS_MAXPACKETSIZE(MSDDriverDescriptors_BULKIN),
        USBEndpointDescriptor_MAXBULKSIZE_FS), // wMaxPacketSize: 64
    0 // bInterval: Must be 0 for full-speed Bulk endpoints.
}
\endcode

 !String descriptors
 Several descriptors can be commented with a String descriptor. The latter are
 completely optional and do not influence the detection of the device by the
 operating system. Whether or not to include them is entirely up to the
 programmer.

 There is one exception to this rule when using the MSD class. According to the
 specification, there must be a Serial Number string. It must contains at least
 12 characters, and these characters must only be either letters (a-z, A-Z) or
 numbers (0-9). This cause no problem for the driver in practice, but this is a
 strict requirement for certification. Also remember that string descriptors
 use the Unicode format.

 See manufacturerDescriptor, productDescriptor, serialNumberDescriptor.

 !!Class-specific Requests
 There are two Mass Storage-specific requests:
 - GetMaxLUN
 - Bulk-Only Mass Storage Reset

 Standard requests can be forwarded to the USBDDriver_RequestHandler, with one
 exception: #CLEAR_FEATURE#. This is necessary for Reset Recovery sequence.

 !ClearFeature
 As previously stated, the CLEAR_FEATURE request must be handled in a
 particular way, depending on whether or not the device is waiting for a Reset
 Recovery sequence. If it is, then CLEAR_FEATURE requests to unhalt a Bulk
 endpoint must be discarded.

 In the example software, this behavior is indicated by a boolean field in the
 driver structure, named waitResetRecovery. The handler only has to check this
 field value to decide whether to forward the request to the standard handler
 or to discard it.
\code
// Handle requests
switch (USBGenericRequest_GetRequest(request)) {
//---------------------
case USBGenericRequest_CLEARFEATURE:
//---------------------

    switch (USBFeatureRequest_GetFeatureSelector(request)) {

    //---------------------
    case USBFeatureRequest_ENDPOINTHALT:
    //---------------------

        // Do not clear the endpoint halt status if the device is waiting
        // for a reset recovery sequence
        if (!msdDriver.waitResetRecovery) {

            // Forward the request to the standard handler
            USBDDriver_RequestHandler(&usbdDriver, request);
        }

        USBD_Write(0, 0, 0, 0, 0);
        break;

    //------
    default:
    //------
        // Forward the request to the standard handler
        USBDDriver_RequestHandler(&usbdDriver, request);
    }
    break;
}
\endcode

 !GetMaxLUN
 Usually, the first request issued by the host right after the enumeration
 phase will be a GET_MAX_LUN request. It enables it to discover how many
 different logical units the device has; each of these LUNs can then be queried
 in turn by the host when needed.

 After the request is received by the device, it should return one byte of data
 indicating the maximum Logical Unit Number (LUN). It is equal to the number of
 LUNs used by the device minus one. For example, a device with three LUNs shall
 return a GET_MAX_LUN value of two.

 Sending this byte is done by calling the USBD_Write method on Control endpoint
 0. Note that the data must be held in a permanent buffer (since the transfer
 is asynchronous); in the software provided with this application note, a
 dedicated field is used in the driver structure (MSDDriver) to store this
 value.

 In addition due to the }Mass Storage Bulk-Only Transport} specification the
 }wValue} should be 0, }wLength} should be 1, }wIndex} should be the interface
 number also 0. A request which does not comply to these requirements must be
 STALLed.
\code
//-------------------
case MSD_GET_MAX_LUN:
//-------------------
    // Check request parameters
    if ((request->wValue == 0)
        && (request->wIndex == 0)
        && (request->wLength == 1)) {
        USBD_Write(0, &(msdDriver.maxLun), 1, 0, 0);
    }
    else {
        USBD_Stall(0);
    }
    break;
\endcode

 !Bulk-Only Mass Storage Reset
 The host issues #RESET# requests to return the MSD driver of the device to its
 initial state, i.e., ready to receive a new command. However, this request
 does not impact the USB controller state; in particular, endpoints must not be
 reset. This means the data toggle bit must not be altered, and Halted endpoint
 must not be returned to a normal state. After processing the reset, the device
 must return a Zero-Length Packet (ZLP) to acknowledge the SETUP transfer.

 Like GET_MAX_LUN, this request must be issued with specific parameters -
 wValue, wIndex and wLength should be zero. A request which does not have valid
 values in its field must be acknowledged with a STALL handshake from the
 %device.

 The handler for this request must return the state machine to its initial state.
\code
//-----------------------
case MSD_BULK_ONLY_RESET:
//-----------------------
    // Check parameters
    if ((request->wValue == 0)
        && (request->wIndex == 0)
        && (request->wLength == 0)) {

        // Reset the MSD driver
        MSDDriver_Reset();
        USBD_Write(0, 0, 0, 0, 0);
    }
    else {
        USBD_Stall(0);
    }
    break;
\endcode

 !!State Machine
 ...

 !Rationale
 A state machine is necessary for #non-blocking# operation of the driver. As
 previously stated, there are three steps when processing a command:
 - Reception of the CBW
 - Processing of the command (with data transfers if required)
 - Emission of the CSW

 Without a state machine, the program execution would be stopped at each step
 to wait for transfers completion or command processing. For example, reception
 of a CBW does not always happen immediately (the host does not have to issue
 commands regularly) and can block the system for a long time.

 Developing an asynchronous design based on a state machine is made easier when
 using Atmel "AT91 USB device framework", as most methods are asynchronous. For
 example, a write operation (using the USBD_Write function) returns
 immediately; a callback function can then be invoked when the transfer
 actually completes.

 !States
 Apart from the three states corresponding to the command processing flow (CBW,
 command processing and CSW), two more can be identified. The
 reception/emission of CBW/CSW will be broken down into two different states:
 the first state is used to issue the read/write operation, while the second
 one waits for the transfer to finish. This can be done by monitoring a
 "transfer complete" flag which is set using a callback function.

 In addition, some commands can be quite complicated to process: they may
 require several consecutive data transfers mixed with media access. Each
 command thus has its own second-tier state machine. During execution of a
 command, the main state machine remains in the "processing" state, and
 proceeds to the next one (CSW emission) only when the command is complete.

 Here is the states list:
 - MSDDriver_STATE_READ_CBW: Start of CBW reception
   (initial state after reset)
 - MSDDriver_STATE_WAIT_CBW: Waiting for CBW reception
 - MSDDriver_STATE_PROCESS_CBW: Command processing
 - MSDDriver_STATE_SEND_CSW: Start of CSW emission
 - MSDDriver_STATE_WAIT_CSW: Waiting for CSW emission

 A single function, named MSDDriver_StateMachine, is provided by the driver. It
 must be called regularly during the program execution. The following
 subsections describe the actions that must be performed during each state.

 \image MSDDriverStates.png "MSD Driver State Machine"

 #MSDDriver_STATE_READ_CBW#

 As said previously, this state is used to start the reception of a new Command
 Block Wrapper. This is done using the USB_Read method of the USB framework.
 The result code of the function is checked for any error; the
 USB_STATUS_SUCCESS code indicates that the transfer has been successfully
 started.
\code
//----------------------
case MSDDriver_STATE_READ_CBW:
//----------------------
    // Start the CBW read operation
    transfer->semaphore = 0;
    status = USBD_Read(MSDDriverDescriptors_BULKOUT,
                       cbw,
                       MSD_CBW_SIZE,
                       (TransferCallback) MSDDriver_Callback,
                       (void *) transfer);

    // Check operation result code
    if (status == USBD_STATUS_SUCCESS) {

        // If the command was successful, wait for transfer
        msdDriver.state = MSDDriver_STATE_WAIT_CBW;
    }
    break;
\endcode
 A callback function to invoke when the transfer is complete is provided to the
 USBD_Read method, to update a MSDTransfer structure. This structure
 indicates the transfer completion, the returned result code and the number of
 transferred and remaining bytes.
\code
typedef struct {
    unsigned int  transferred; //!< Number of bytes transferred
    unsigned int  remaining;   //!< Number of bytes not transferred
    unsigned char semaphore;   //!< Semaphore to indicate transfer completion
    unsigned char status;      //!< Operation result code
} MSDTransfer;
\endcode
 The callback function is trivial and thus not listed here.

 #MSDDriver_STATE_WAIT_CBW#

 The first step here is to monitor the }semaphore} field of the MSDTransfer
 structure (see above); this will enable detection of the transfer end. Please
 note that this field must be declared as volatile in C, or accesses to it
 might get optimized by the compiler; this can result in endless loops.

 If the transfer is complete, then the result code must be checked to see if
 there was an error. If the operation is successful, the state machine can
 proceed to command processing. Otherwise, it returns to the READ_CBW state.
\code
//----------------------
case MSDDriver_STATE_WAIT_CBW:
//----------------------
    // Check transfer semaphore
    if (transfer->semaphore > 0) {

        // Take semaphore and terminate transfer
        transfer->semaphore--;

        // Check if transfer was successful
        if (transfer->status == USBD_STATUS_SUCCESS) {

            // Process received command
            msdDriver.state = MSDDriver_STATE_PROCESS_CBW;
        }
        else if (transfer->status == USBD_STATUS_RESET) {

            msdDriver.state = MSDDriver_STATE_READ_CBW;
        }
        else {

            msdDriver.state = MSDDriver_STATE_READ_CBW;
        }
    }
    break;
\endcode

 #MSDDriver_STATE_PROCESS_CBW#

 Once the CBW has been received, its validity must be checked. A CBW is not
 valid if:
 - it has not been received right after a CSW was sent or a reset occured or
 - it is not exactly 31 bytes long or
 - its signature field is not equal to 43425355h

 The state machine prevents the first case from happening, so only the two
 other cases have to be verified.

 The number of bytes transferred during a USBD_Read operation is passed as an
 argument to the callback function, if one has been specified. As stated
 previously, such a function is used to fill a MSDTransfer structure.
 Therefore, it is trivial to check that the CBW is indeed 31 bytes by verifying
 that the number of bytes transferred is 31, and that there are no remaining
 bytes. The following table illustrates the three cases which may happen:
||Number of bytes transferred||Number of bytes remaining||Meaning
|transferred<31|remaining==0|CBW is too short
|transferred==31|remaining>0|CBW is too long
|transferred==31|remaining==0|CBW length is correct

 Checking the signature is simply done by comparing the dCBWSignature field
 with the expected value (43425355h).

 If the CBW is not valid, then the device must immediately halt both Bulk
 endpoints, to STALL further traffic from the host. In addition, it should stay
 in this state until a Reset Recovery is performed by the host. This is done by
 setting the waitResetRecovery flag in the MSDDriver structure. Finally, the
 CSW status is set to report an error, and the state machine is returned to
 MSDDriver_STATE_READ_CBW.

 Otherwise, if the CBW is correct, then the command can be processed. Remember
 the CBW tag must be copied regardless of the validity of the CBW.

 Note that these steps are only necessary for a new command (remember commands
 are asynchronous and are carried out in several calls, so a check can be
 performed to avoid useless processing. A value of zero for the internal
 command state indicates a new command.
\code
//-------------------------
case MSDDriver_STATE_PROCESS_CBW:
//-------------------------
    // Check if this is a new command
    if (commandState->state == 0) {

        // Copy the CBW tag
        csw->dCSWTag = cbw->dCBWTag;

        // Check that the CBW is 31 bytes long
        if ((transfer->transferred != MSD_CBW_SIZE) ||
            (transfer->remaining != 0)) {

            // Wait for a reset recovery
            msdDriver.waitResetRecovery = 1;

            // Halt the Bulk-IN and Bulk-OUT pipes
            USBD_Halt(MSDDriverDescriptors_BULKOUT);
            USBD_Halt(MSDDriverDescriptors_BULKIN);

            csw->bCSWStatus = MSD_CSW_COMMAND_FAILED;
            msdDriver.state = MSDDriver_STATE_READ_CBW;

        }
        // Check the CBW Signature
        else if (cbw->dCBWSignature != MSD_CBW_SIGNATURE) {

            // Wait for a reset recovery
            msdDriver.waitResetRecovery = 1;

            // Halt the Bulk-IN and Bulk-OUT pipes
            USBD_Halt(MSDDriverDescriptors_BULKOUT);
            USBD_Halt(MSDDriverDescriptors_BULKIN);

            csw->bCSWStatus = MSD_CSW_COMMAND_FAILED;
            msdDriver.state = MSDDriver_STATE_READ_CBW;
        }
        else {

            // Pre-process command
            MSDDriver_PreProcessCommand();
        }
    }

    // Process command
    if (csw->bCSWStatus == MSDDriver_STATUS_SUCCESS) {

        if (MSDDriver_ProcessCommand()) {

            // Post-process command if it is finished
            MSDDriver_PostProcessCommand();
            msdDriver.state = MSDDriver_STATE_SEND_CSW;
        }
    }

    break;
\endcode

 #MSDDriver_STATE_SEND_CSW#

 This state is similar to MSDDriver_STATE_READ_CBW, except that a write
 operation is performed instead of a read and the CSW is sent, not the CBW. The
 same callback function is used to fill the transfer structure, which is
 checked in the next state:
\code
//----------------------
case MSDDriver_STATE_SEND_CSW:
//----------------------
    // Set signature
    csw->dCSWSignature = MSD_CSW_SIGNATURE;

    // Start the CSW write operation
    status = USBD_Write(MSDDriverDescriptors_BULKIN,
                        csw,
                        MSD_CSW_SIZE,
                        (TransferCallback) MSDDriver_Callback,
                        (void *) transfer);

    // Check operation result code
    if (status == USBD_STATUS_SUCCESS) {

        // Wait for end of transfer
        msdDriver.state = MSDDriver_STATE_WAIT_CSW;
    }
    break;
\endcode

 #MSDDriver_STATE_WAIT_CSW#

 Again, this state is very similar to MSDDriver_STATE_WAIT_CBW. The only
 difference is that the state machine is set to MSDDriver_STATE_READ_CBW
 regardless of the operation result code:
\code
//----------------------
case MSDDriver_STATE_WAIT_CSW:
//----------------------
    // Check transfer semaphore
    if (transfer->semaphore > 0) {

        // Take semaphore and terminate transfer
        transfer->semaphore--;

        // Read new CBW
        msdDriver.state = MSDDriver_STATE_READ_CBW;
    }
    break;
\endcode

 !!Media

 USB MSD Media access is three-level abstraction.

 \image MSDMediaArch.png "Media Architecture"

 The bottom level is the specific driver for each media type (See memories).

 In the middle, a structure Media is used to hide which specific driver a media
 instance is using. This enables transparent use of any media driver once it
 has been initialized (See _Media).

 Finally, a LUN abstraction is made over the media structure to allow multiple
 partitions over one media. This also makes it possible to place the LUN at any
 address and use any block size. When performing a write or read operation on a
 LUN, it forwards the operation to the underlying media while translating it to
 the correct address and length.

 !Media Drivers
 A media driver must provide several functions for:
 - Reading data from the media
 - Writing data on the media
 - Handling interrupts on the media
 The last function may be empty if the media does not require interrupts for
 asynchronous operation, or if synchronous operation produces an acceptable
 delay.

 In addition, it should also define a function for initializing a Media
 structure with the correct values, as well as perform the necessary step for
 the media to be useable.

 For the drivers see:
 - MEDSdram.h: }Internal Flash Driver}
 - MEDFlash.h: }SDRAM disk driver}

 !!SCSI Commands

 The example software described in this application note uses SCSI commands
 with the MSD class, since this is the most appropriate setting for a Flash
 device. This section details how SCSI commands are processed.

 !Documents

 There are several documents covering SCSI commands. In this application note,
 the reference document used is SCSI Block Commands - 3 (SBC-3). However, it
 makes many references to another SCSI document, SCSI Primary Commands - 4
 (SPC-4). Both are needed for full details on required commands.

 !Endianness

 SCSI commands use the big-endian format for storing word- and double word-
 sized data. This means the Most Significant Bit (MSB) is stored at the
 lowest address, and the Least Significant Bit (LSB) at the highest one.

 On ARM Thumb microcontrollers, the endianness of the core is selectable.
 However, the little-endian mode is most often used. Therefore, SCSI command
 data must be converted before being usable. This is done by declaring
 word- and dword-sized fields as byte arrays, and then using a macro for
 loading or storing data. Several of them are available in the provided
 software:
 - Load
    - WORDB: Converts a big-endian word value to little-endian
    - DWORDB: Converts a big-endian double-word value to little-endian
 - Store
    - STORE_WORDB: Stores a little-endian word value in big-endian format
    - STORE_DWORDB: Stores a little-endian double-word value in big-endian format

 !Sense Data

 When an error happens during the execution of a command, it is recorded by the
 device. The host may then issue a Request Sense command to retrieve
 #Sense Data#, i.e., information about previous errors.

 While the sense data structure has many fields, only three are really
 important. The first one is the Sense Key. It indicates the result of the last
 command performed: success, media not ready, hardware error, etc. Two other
 fields can then be specified to give a more accurate description of the
 problem. They are named }Additional Sense Code} and }Additional Sense Code
 Qualifier}.

 In the example application, each LUN has its own sense data. It is updated
 during command execution if there is any error.

 !Commands

 The SBC-3 specification gives a list of mandatory and optional commands that
 are relevant for a block device (like a Flash drive). In practice, only a
 subset of the mandatory commands is effectively used by operating systems;
 conversely, several commands which are supposed to be optional are required.
 The software provided with this application note implements the following list
 of commands:
 - SBC-3
    - Prevent/Allow Medium Removal
    - Read (10)
    - Read Capacity (10)
    - Verify (10)
    - Write (10)
 - SPC-4
    - Inquiry
    - Mode Sense (6)
    - Request Sense
    - Test Unit Ready
 The commands are actually processed in SBC_ProcessCommand.

 }Internal State Machine}

 As previously stated, most commands have an internal state machine to prevent
 blocking the whole system during a data transfer (on the USB or when accessing
 a media). A result code is used to indicate that the corresponding function
 must be called again for the command to complete (MSDDriver_STATUS_SUCCESS).

 A command state structure is used by the driver to record several parameters
 during command processing:
\code
typedef struct {

    MSDTransfer transfer;       //!< Current transfer status
    MSCbw      cbw;             //!< Received CBW
    MSCsw      csw;             //!< CSW to send
    unsigned char  state;       //!< Current command state
    unsigned char  postprocess; //!< Actions to perform when command is complete
    unsigned int   length;      //!< Remaining length of command

} MSDCommandState;
\endcode

 Note that the }state} field must be initialized when the command is first
 called. A value of 0 means that no command is currently being executed.

 For the commands descriptions and implementation, please reffer to the SCSI
 spec. and source code.

 Functions to handle SCSI commands:
 - SBC_Inquiry
 - SBC_Read10
 - SBC_ReadCapacity10
 - SBC_RequestSense
 - SBC_TestUnitReady
 - SBC_Write10
 - SBC_ModeSense6

 !Command Processing

 }Flow}

 Command processing is actually divided into three phases in the example
 software:
 - Pre-processing: MSDDriver_PreProcessCommand
 - Processing: MSDDriver_ProcessCommand
 - Post-processing: MSDDriver_PostProcessCommand

 }The Thirteen Cases}

 There are basically three actions that should be performed depending on the
 case:
 - STALL the Bulk-IN endpoint
 - STALL the Bulk-OUT endpoint
 - Report a Phase Error in the CSW

 The table below lists all cases along with the actions which must be taken
 after the command, including the correct length/direction of the transfer. The
 following notation is used to characterize host and %device expectations:

 Data %Transfer Characterization
||Notation||Meaning||Notation||Meaning
|Hn|Host expects no data transfer|Dn|Device expects no data transfer
|Hi|Host expects to #receive# data|Di|Device expects to #send# data
|Ho|Host expects to #send# data|Do|Device expects to #receive# data
|Lh|Length of data expected by the host|Ld|Length of data expected by the %device

|Hx=Dx|Host and %device agree on transfer length and direction (x is either n, i or o)
|Hx>Dx|Host and %device agree on transfer direction, host expects a larger transfer than %device
|Hx<Dx|Host and %device agree on transfer direction, %device expects a larger transfer than host
|Hx<>Dx|Host and %device disagree on transfer direction

 The Thirteen Cases
||\#||Case||Length||Residue||Direction||STALL IN?||STALL OUT?||Phase Error?
|1|Hn = Dn|0|0|Irrelevant| | | 
|2|Hn < Di|0|Ld - Lh|Irrelevant| | |X
|3|Hn < Do|0|Ld - Lh|Irrelevant| | |X
|4|Hi > Dn|0|Lh|Irrelevant|X| | 
|5|Hi > Di|Ld|Lh - Ld|In|X| | 
|6|Hi = Di|Ld|0|In| | | 
|7|Hi < Di|Lh|Ld - Lh|In| | |X
|8|Hi <> Do|0|0|Irrelevant|X| |X
|9|Ho > Dn|0|Lh|Irrelevant| |X| 
|10|Ho <> Di|0|0|Irrelevant| |X|X
|11|Ho > Do|Ld|Lh - Ld|Out| |X| 
|12|Ho = Do|Ld|0|Out| | | 
|13|Ho < Do|Lh|Lh - Ld|Out| | |X

 !!Main Application
 After the MSD driver and the media have been initialized using the
 corresponding functions, the only requirement for the main application is to
 regularly call the state machine function. This is necessary for processing
 received commands in a fully asynchronous way.

 The application is otherwise free of doing any other task; for example, it
 could implement a filesystem and a serial port interface to be accessed with a
 standard terminal. An MP3 player could also continue playing a song while its
 memory is accessed like an external hard disk.

 \image MSDDriverClasses.png "Driver Class Diagram"

*/
/**
 \page "USB MSD Basic"

 This page gives generic details on the MSD class.

 !!!Purpose

 The MSD class defines how devices such as a hard disk, a USB floppy disk drive
 or a disk-on-key shall operate on the USB. These devices are referred to as
 mass storage devices, since they usually offer a high storage capacity. When
 plugged to a PC, a %device complying to the MSD specification is accessed like
 any other disk on the system.

 In practice, the specification only defines a way to wrap existing data
 transfer protocols, such as SCSI or the Reduced Block Commands (RBC) set. A
 list of the supported protocols and their uses will be given in the following
 section.

 !!!Data Transfer Protocols

 The }Mass Storagae Class Specification Overview 1.2} supports the following
 set of %devices:

 Protocols for MSD %devices
||Subclass Code||Command Block Spec.||Used by
|01h|Reduced Block Commands(RBC)|Flash %devices
|02h|SFF-8020i, MMC-2|CD & DVD %devices
|03h|QIC-157|Tape %devices
|04h|UFI|Floppy disk drives
|05h|SFF-8070i|Floppy disk drives
|06h|SCSI transparent command set|Any

 The SCSI transparent command set comprises all SCSI-related specifications,
 such as SCSI Primary Commands (SPC), SCSI Block Commands (SBC), and so on. A
 command will be issued by the host to determine exactly with which standard
 the %device is compliant.

 The protocol used by the %device is specified in its Interface descriptor, in
 the }bInterfaceSubclass} field.

 !!!Transfer Protocols

 There are actually two different transport protocols for the MSD class:
 - Control/Bulk/Interface (CBI) transport
 - Bulk-Only Transport (BOT)

 These two methods are described in two separate stand-alone documents. CBI can
 be considered obsolete and is being completely replaced by BOT. It was
 originally targeted at full-speed floppy disk drives. Therefore, the rest of
 this document will talk about Bulk-Only Transport exclusively.

 Transport Protocol Codes
||bInterfaceProtocol||Protocol Implementation
|00h|Control/Bulk/Interrupt protocol (with command completion interrupt)
|01h|Control/Bulk/Interrupt protocol (without command completion interrupt)
|50h|Bulk-only transport

 !!!Architecture
 ...

 !!Interfaces & Endpoints

 An MSD %device only needs one single interface. The bInterfaceClass field of
 the interface descriptor should be set to MSD class code (0x08), the
 corresponding data transfer protocol code in the }bInterfaceSubclass} field
 and transport protocol code in the }bInterfaceProtocol} field can be found in
 the tables on above.

 Exactly three %endpoints (when using the Bulk-Only Transport protocol) are
 necessary for MSD %devices.

 The first one is the Control endpoint 0, and is used for class-specific
 requests and for clearing Halt conditions on the other two %endpoints.
 Endpoints are halted in response to errors and host bad behavior during data
 transfers, and the CLEAR_FEATURE request is consequently used to return them
 to a functional state.

 The other two %endpoints, which are of type Bulk, are used for transferring
 commands and data over the bus. There must be one Bulk-IN and one Bulk-OUT
 endpoint.

 \image MSDDriverArch.png "Mass Storage Device Driver Architecture"

 !!Class-Specific Descriptors
 No class-specific descriptors for an MSD %device using the Bulk-only transfport
 protocol.

 !!Class-Specific Requests
 Two class specific requests should be handled.

 !GetMaxLUN
 A %device can feature one or more Logical Unit (LU). Each of these units will
 be treated as a separate disk when plugged to a computer. A %device can have up
 to 15 logical units.

 The GET_MAX_LUN request is issued by the host to determine the maximum Logical
 Unit Number (LUN) supported by the %device. This is not equivalent to the
 number of LU on the %device; since units are numbered starting from 0, a %device
 with 5 LUs should report a value of 4, which will be the index of the fifth
 unit.

 Optionally, a %device with only one LUN may STALL this request instead of
 returning a value of zero.

 !Bulk-Only Mass Storage Reset
 This request is used to reset the state of the %device and prepare it to
 receive commands and data. Note that the data toggle bits must not be altered
 by a RESET command; same for the Halt state of %endpoints, i.e., halted
 %endpoints must not be reset to a normal state.

 !!Command/Data/Status
 Each MSD transaction is divided into three steps:
 - Command stage
 - Data stage (optional)
 - Status stage

 During the command stage, a Command Block Wrapper (CBW) is transmitted by the
 host to the %device. The CBW describes several parameters of the transaction
 (direction, length, LUN) and carries a variable-length command block. The
 command block contains data in the format defined by the transfer protocol
 used by the %device.

 Command Block Wrapper Data Format
||Offset||Field Name||Length||Comment
|0|dCBWSignature|4 bytes|Signature to identify CBW, must be 43425355h
|4|dCBWTag|4 bytes|Tag sent by the host, echoed in the CSW
|8|dCBWTransferLength|4 bytes|Length of transfer during the data stage
|12|bmCBWFlags|1 byte|Bits 0-6: Reserved/obsolete\n
                      Bit 7: Transfer direction (0 = OUT, 1 = IN)
|13|bCBWLUN|1 byte|Bits 0-3: LUN to which the command is sent\n
                   Bits 4-7: Reserved
|14|bCBWCBLength|1 byte|Bits 0-5: Length of command block in bytes\n
                        Bits 6-7: Reserved
|15|CBWCB|0-16 bytes|Command block to be executed by the %device

 After the %device has received and interpreted the command, an optional data
 stage may take place if the command requires it. During this step, data is
 transferred either to or from the %device depending on the command, in several
 IN/OUT transfers.

 Once the data stage is complete, the host issues a final IN request on the
 Bulk-IN endpoint of the %device to request the Command Status Wrapper (CSW).
 The CSW is used to report correct or incorrect execution of the command, as
 well as indicating the length of remaining data that has not been transferred.

 Command Status Wrapper
||Offset||Field Name||Length||Comment
|0|dCSWSignature|4 bytes|Signature to identify CSW, must be 53425355h
|4|dCSWTag|4 bytes|Copy of previous CBW tag
|8|dCSWDataResidue|4 bytes|Difference between expected and real transfer length
|12|bCSWStatus|1 byte|Indicates the success or failure of the command

 These steps are all performed on the two Bulk %endpoints, and do not involve
 Control endpoint 0 at all.

 !!Reset Recovery
 When severe errors occur during command or data transfers (as defined in the
 }Mass Storage Bulk-only Transport 1.0} document), the %device must halt both
 Bulk %endpoints and wait for a #Reset Recovery# procedure. The Reset Recovery
 sequence goes as follows:
 - The host issues a Bulk-Only Mass Storage Reset request
 - The host issues two #CLEAR_FEATURE# requests to unhalt each endpoint

 A %device waiting for a Reset Recovery must not carry out CLEAR_FEATURE
 requests trying to unhalt either Bulk endpoint until after a Reset request has
 been received. This enables the host to distinguish between severe and minor
 errors.

 The only major error defined by the Bulk-Only Transport standard is when a CBW
 is not valid. This means one or more of the following:
 - The CBW is not received after a CSW has been sent or a reset.
 - The CBW is not exactly 31 bytes in length.
 - The dCBWSignature field of the CBW is not equal to 43425355h.

 !!!Host Drivers
 Almost all operating systems now provide a generic driver for the MSD class.
 However, the set of supported data transfer protocols may vary. For example,
 Microsoft Windows does not currently support the Reduced Block Command set.

*/