bot_driver.h

This software package contains the USB framework core developped by ATMEL, as well as a Mass stora

/* ----------------------------------------------------------------------------
 *         ATMEL Microcontroller Software Support  -  ROUSSET  -
 * ----------------------------------------------------------------------------
 * Copyright (c) 2006, 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 disclaiimer below.
 *
 * - Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the disclaimer below in the documentation and/or
 * other materials provided with the distribution.
 *
 * 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.
 * ----------------------------------------------------------------------------
 */

/*
$Id: bot_driver.h 198 2006-10-30 10:01:09Z jjoannic $
*/

#ifndef _MSD_DRIVER_H
#define _MSD_DRIVER_H

//------------------------------------------------------------------------------
//      Definitions
//------------------------------------------------------------------------------

//! \brief  Product ID used by the driver
#define BOT_PRODUCT_ID                  0x6202

//! \brief  Total number of endpoints used by the MSD driver
#define BOT_NUM_ENDPOINTS               3

//! \brief  Address of Bulk OUT endpoint
#define BOT_EPT_BULK_OUT                0x01

//! \brief  Address of Bulk IN endpoint
#define BOT_EPT_BULK_IN                 0x02

//! \brief  Possible states of the MSD driver
//! \brief  Driver is expecting a command block wrapper
#define BOT_STATE_READ_CBW              (1 << 0)

//! \brief  Driver is waiting for the transfer to finish
#define BOT_STATE_WAIT_CBW              (1 << 1)

//! \brief  Driver is processing the received command
#define BOT_STATE_PROCESS_CBW           (1 << 2)

//! \brief  Driver is starting the transmission of a command status wrapper
#define BOT_STATE_SEND_CSW              (1 << 3)

//! \brief  Driver is waiting for the CSW transmission to finish
#define BOT_STATE_WAIT_CSW              (1 << 4)

//! \brief  Result codes for MSD functions
//! \brief  Method was successful
#define BOT_STATUS_SUCCESS              0x00

//! \brief  There was an error when trying to perform a method
#define BOT_STATUS_ERROR                0x01

//! \brief  No error was encountered but the application should call the
//!         method again to continue the operation
#define BOT_STATUS_INCOMPLETE           0x02

//! \brief  A wrong parameter has been passed to the method
#define BOT_STATUS_PARAMETER            0x03

//! \brief  Actions to perform during the post-processing phase of a command
//! \brief  Indicates that the CSW should report a phase error
#define BOT_CASE_PHASE_ERROR            (1 << 0)

//! \brief  The driver should halt the Bulk IN pipe after the transfer
#define BOT_CASE_STALL_IN               (1 << 1)

//! \brief  The driver should halt the Bulk OUT pipe after the transfer
#define BOT_CASE_STALL_OUT              (1 << 2)

//! \brief  Possible direction values for a data transfer
#define BOT_DEVICE_TO_HOST              0
#define BOT_HOST_TO_DEVICE              1
#define BOT_NO_TRANSFER                 2

//------------------------------------------------------------------------------
//      Structures
//------------------------------------------------------------------------------

//! \brief  Structure for holding the result of a USB transfer
//! \see    MSD_Callback
typedef struct {

    unsigned int  dBytesTransferred; //!< Number of bytes transferred
    unsigned int  dBytesRemaining;   //!< Number of bytes not transferred
    unsigned char bSemaphore;        //!< Semaphore to indicate transfer completion
    unsigned char bStatus;           //!< Operation result code

} S_bot_transfer;

//! \brief  Status of an executing command
//! \see    S_msd_cbw
//! \see    S_msd_csw
//! \see    S_bot_transfer
typedef struct {

    S_bot_transfer sTransfer; //!< Current transfer status
    S_msd_cbw      sCbw;      //!< Received CBW
    S_msd_csw      sCsw;      //!< CSW to send
    unsigned char  bState;    //!< Current command state
    unsigned char  bCase;     //!< Actions to perform when command is complete
    unsigned int   dLength;   //!< Remaining length of command

} S_bot_command_state;

//! \brief  MSD driver state variables
//! \see    S_bot_command_state
//! \see    S_std_class
//! \see    S_lun
typedef struct {

    S_std_class         sClass;              //!< Standard class attributes
    S_lun               *pLun;               //!< Pointer to a list of LUNs
    S_bot_command_state sCommandState;       //!< State of the currently executing command
    unsigned char       bMaxLun;             //!< Maximum LUN index
    unsigned char       bState;              //!< Current state of the driver
    bool                isWaitResetRecovery; //!< Indicates if the driver is
                                             //!< waiting for a reset recovery
} S_bot;

//! \brief  Configuration descriptor used by the MSD driver
//! \see    S_usb_configuration_descriptor
//! \see    S_usb_interface_descriptor
//! \see    S_usb_endpoint_descriptor
typedef struct {

    S_usb_configuration_descriptor sConfiguration; //!< Configuration descriptor
    S_usb_interface_descriptor     sInterface;     //!< Interface descriptor
    S_usb_endpoint_descriptor      sBulkOut;       //!< Bulk OUT endpoint
    S_usb_endpoint_descriptor      sBulkIn;        //!< Bulk IN endpoint

} S_bot_configuration_descriptor;

//------------------------------------------------------------------------------
//      Inline functions
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
//! \brief  This function is to be used as a callback for USB or LUN transfers.
//!
//!         A S_bot_transfer structure is updated with the method results.
//! \param  S_bot_transfer    Pointer to the transfer structure to update
//! \param  bStatus           Operation result code
//! \param  dBytesTransferred Number of bytes transferred by the command
//! \param  dBytesRemaining   Number of bytes not transferred
//------------------------------------------------------------------------------
static inline void BOT_Callback(S_bot_transfer *pTransfer,
                                unsigned char  bStatus,
                                unsigned int   dBytesTransferred,
                                unsigned int   dBytesRemaining)
{
    TRACE_DEBUG_M("Cbk ");
    pTransfer->bSemaphore++;
    pTransfer->bStatus = bStatus;
    pTransfer->dBytesTransferred = dBytesTransferred;
    pTransfer->dBytesRemaining = dBytesRemaining;
}

//------------------------------------------------------------------------------
//      Exported functions
//------------------------------------------------------------------------------
extern void BOT_Reset(S_bot *pBot);
extern void BOT_Init(S_bot *pBot,
                     const S_usb *pUsb,
                     S_lun *pLun,
                     unsigned char bNumLun);
extern void BOT_RequestHandler(S_bot *pBot);
extern void BOT_StateMachine(S_bot *pBot);

#endif