diff options
Diffstat (limited to 'usb_1.1.0/host/class/usb_host_msd.h')
-rw-r--r-- | usb_1.1.0/host/class/usb_host_msd.h | 872 |
1 files changed, 872 insertions, 0 deletions
diff --git a/usb_1.1.0/host/class/usb_host_msd.h b/usb_1.1.0/host/class/usb_host_msd.h new file mode 100644 index 0000000..b062d9a --- /dev/null +++ b/usb_1.1.0/host/class/usb_host_msd.h @@ -0,0 +1,872 @@ +/* + * Copyright (c) 2015, Freescale Semiconductor, Inc. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * o Redistributions of source code must retain the above copyright notice, this list + * of conditions and the following disclaimer. + * + * o Redistributions in binary form must reproduce the above copyright notice, this + * list of conditions and the following disclaimer in the documentation and/or + * other materials provided with the distribution. + * + * o Neither the name of Freescale Semiconductor, Inc. nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS 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. + */ + +#ifndef _USB_HOST_MSD_H_ +#define _USB_HOST_MSD_H_ + +/******************************************************************************* + * MSD class private structure, enumeration, macro + ******************************************************************************/ + +/******************************************************************************* + * Definitions + ******************************************************************************/ + +/* CBW and CSW Macros */ +#define USB_HOST_MSD_CBW_FLAGS_DIRECTION_OUT (0x00U) +#define USB_HOST_MSD_CBW_FLAGS_DIRECTION_IN (0x80U) +#define USB_HOST_MSD_CBW_SIGNATURE (0x43425355U) +#define USB_HOST_MSD_CSW_SIGNATURE (0x53425355U) + +/* UFI data bit macro */ +#define USB_HOST_UFI_BLOCK_DATA_VALID_LENGTH (10U) +#define USB_HOST_UFI_LOGICAL_UNIT_POSITION (5U) +#define USB_HOST_UFI_CBW_LENGTH (31U) +#define USB_HOST_UFI_MODE_SENSE_PAGE_CONTROL_SHIFT (6U) +#define USB_HOST_UFI_MODE_SENSE_PAGE_CODE_SHIFT (0U) +#define USB_HOST_UFI_START_STOP_UNIT_LOEJ_SHIFT (1U) +#define USB_HOST_UFI_START_STOP_UNIT_START_SHIFT (0U) +#define USB_HOST_UFI_SEND_DIAGNOSTIC_SELF_TEST_SHIFT (2U) + +/******************************************************************************* + * MSD class public structure, enumeration, macro, function + ******************************************************************************/ +/*! + * @addtogroup usb_host_msc_drv + * @{ + */ + +/*! @brief retry time when transfer fail, when all the retries fail the transfer callback with error status */ +#define USB_HOST_MSD_RETRY_MAX_TIME (1U) +/*! @brief mass storage block size */ +#define USB_HOST_MSD_BLOCK_SIZE (512U) + +/*! @brief MSD class code */ +#define USB_HOST_MSD_CLASS_CODE (8U) +/*! @brief MSD sub-class code */ +#define USB_HOST_MSD_SUBCLASS_CODE_UFI (4U) +/*! @brief MSD sub-class code */ +#define USB_HOST_MSD_SUBCLASS_CODE_SCSI (6U) +/*! @brief MSD protocol code */ +#define USB_HOST_MSD_PROTOCOL_BULK (0x50U) + +/*! @brief MSD class-specific request (mass storage reset) */ +#define USB_HOST_HID_MASS_STORAGE_RESET (0xFFU) +/*! @brief MSD class-specific request (get maximum logical unit number) */ +#define USB_HOST_HID_GET_MAX_LUN (0xFEU) + +/*! @brief UFI command process status */ +typedef enum _usb_host_msd_command_status +{ + kMSD_CommandIdle = 0, + kMSD_CommandTransferCBW, + kMSD_CommandTransferData, + kMSD_CommandTransferCSW, + kMSD_CommandDone, + kMSD_CommandCancel, + kMSD_CommandErrorDone, +} usb_host_msd_command_status_t; + +/*! @brief MSC Bulk-Only command block wrapper (CBW) */ +typedef struct _usb_host_cbw +{ + uint32_t CBWSignature; /*!< Signature that helps identify this data packet as a CBW. The signature field shall + contain the value 43425355h (little endian), indicating a CBW */ + uint32_t + CBWTag; /*!< A Command Block Tag sent by the host. The device shall echo the contents of this field back to the + host in the dCSWTag field of the associated CSW */ + uint32_t CBWDataTransferLength; /*!< The number of bytes of data that the host expects to transfer on the Bulk-In or + Bulk-Out endpoint during the execution of this command */ + uint8_t CBWFlags; /*!< + Bit 7 Direction - the device shall ignore this bit if the dCBWDataTransferLength field is + zero, otherwise: + 0 = Data-Out from host to the device, + 1 = Data-In from the device to the host. + Bit 6 Obsolete. The host shall set this bit to zero. + Bits 5..0 Reserved - the host shall set these bits to zero. + */ + uint8_t CBWLun; /*!< The device Logical Unit Number (LUN) to which the command block is being sent */ + uint8_t CBWCBLength; /*!< The valid length of the CBWCB in bytes. This defines the valid length of the command + block. The only legal values are 1 through 16 (01h through 10h).*/ + uint8_t CBWCB[16]; /*!< The command block to be executed by the device*/ +} usb_host_cbw_t; + +/*! @brief MSC Bulk-Only command status wrapper (CSW) */ +typedef struct _usb_host_csw +{ + uint32_t CSWSignature; /*!< Signature that helps identify this data packet as a CSW. The signature field shall + contain the value 53425355h (little endian), indicating CSW.*/ + uint32_t CSWTag; /*!< The device shall set this field to the value received in the dCBWTag of the associated CBW*/ + uint32_t CSWDataResidue; /*!< the difference between the amount of data expected as stated in the + dCBWDataTransferLength and the actual amount of relevant data processed by the device.*/ + uint8_t CSWStatus; /*!< + bCSWStatus indicates the success or failure of the command. + 00h - Command passed. + 01h - Command Failed. + 02h - Phase error. + others - Reserved. + */ +} usb_host_csw_t; + +/*! @brief MSC UFI command information structure */ +typedef struct _usb_host_msd_command +{ + usb_host_cbw_t cbwBlock; /*!< CBW data block*/ + usb_host_csw_t cswBlock; /*!< CSW data block*/ + uint8_t *dataBuffer; /*!< Data buffer pointer*/ + uint32_t dataLength; /*!< Data buffer length*/ + uint32_t dataSofar; /*!< Successful transfer data length*/ + usb_host_transfer_t *transfer; /*!< The transfer is used for processing the UFI command*/ + uint8_t retryTime; /*!< The UFI command residual retry time, when it reduce to zero the UFI command fail */ + uint8_t dataDirection; /*!< The data direction, its value is USB_OUT or USB_IN*/ +} usb_host_msd_command_t; + +/*! @brief MSD instance structure, MSD usb_host_class_handle pointer to this structure */ +typedef struct _usb_host_msd_instance +{ + usb_host_handle hostHandle; /*!< This instance's related host handle*/ + usb_device_handle deviceHandle; /*!< This instance's related device handle*/ + usb_host_interface_handle interfaceHandle; /*!< This instance's related interface handle*/ + usb_host_pipe_handle controlPipe; /*!< This instance's related device control pipe*/ + usb_host_pipe_handle outPipe; /*!< MSD bulk out pipe*/ + usb_host_pipe_handle inPipe; /*!< MSD bulk in pipe*/ + transfer_callback_t commandCallbackFn; /*!< MSD UFI command callback function pointer*/ + void *commandCallbackParam; /*!< MSD UFI command callback parameter*/ + transfer_callback_t controlCallbackFn; /*!< MSD control transfer callback function pointer*/ + void *controlCallbackParam; /*!< MSD control transfer callback parameter*/ + usb_host_transfer_t *controlTransfer; /*!< Ongoing control transfer*/ + usb_host_msd_command_t msdCommand; /*!< Ongoing MSD UFI command information*/ + uint8_t commandStatus; /*!< UFI command process status, see command_status_t*/ + uint8_t internalResetRecovery; /*!< 1 - class driver internal mass storage reset recovery is on-going; 0 - + application call USB_HostMsdMassStorageReset to reset or there is no reset*/ +} usb_host_msd_instance_t; + +/*! @brief UFI standard sense data structure */ +typedef struct _usb_host_ufi_sense_data +{ + uint8_t errorCode; /*!< This field shall contain a value of 70h to indicate current errors*/ + uint8_t reserved1; /*!< Reserved field*/ + uint8_t senseKey; /*!< Provide a hierarchy of error or command result information*/ + uint8_t information[4]; /*!< This field is command-specific; it is typically used by some commands to return a + logical block address denoting where an error occurred*/ + uint8_t additionalSenseLength; /*!< The UFI device sets the value of this field to ten, to indicate that ten more + bytes of sense data follow this field*/ + uint8_t reserved2[4]; /*!< Reserved field*/ + uint8_t additionalSenseCode; /*!< Provide a hierarchy of error or command result information*/ + uint8_t additionalSenseCodeQualifier; /*!< Provide a hierarchy of error or command result information*/ + uint8_t reserved3[4]; /*!< Reserved field*/ +} usb_host_ufi_sense_data_t; + +/*! @brief UFI standard inquiry data structure */ +typedef struct _usb_host_ufi_inquiry_data +{ + uint8_t peripheralDeviceType; /*!< Identifies the device currently connected to the requested logical unit*/ + uint8_t removableMediaBit; /*!< This shall be set to one to indicate removable media*/ + uint8_t version; /*!< Version*/ + uint8_t responseDataFormat; /*!< A value of 01h shall be used for UFI device*/ + uint8_t additionalLength; /*!< Specify the length in bytes of the parameters*/ + uint8_t reserved1[3]; /*!< Reserved field*/ + uint8_t vendorInformation[8]; /*!< Contains 8 bytes of ASCII data identifying the vendor of the product*/ + uint8_t productIdentification[16]; /*!< Contains 16 bytes of ASCII data as defined by the vendor*/ + uint8_t productRevisionLevel[4]; /*!< Contains 4 bytes of ASCII data as defined by the vendor*/ +} usb_host_ufi_inquiry_data_t; + +/*! @brief UFI read capacity data structure */ +typedef struct _usb_host_ufi_read_capacity +{ + uint8_t lastLogicalBlockAddress[4]; /*!< The logical block number*/ + uint8_t blockLengthInBytes[4]; /*!< Block size*/ +} usb_host_ufi_read_capacity_t; + +#ifdef __cplusplus +extern "C" { +#endif + +/******************************************************************************* + * API + ******************************************************************************/ + +/*! + * @name USB host MSD class APIs + * @{ + */ + +/*! + * @brief Initializes the MSD instance. + * + * This function allocates the resources for the MSD instance. + * + * @param[in] deviceHandle The device handle. + * @param[out] classHandle Return class handle. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_AllocFail Allocate memory fail. + */ +extern usb_status_t USB_HostMsdInit(usb_device_handle deviceHandle, usb_host_class_handle *classHandle); + +/*! + * @brief Sets the interface. + * + * This function binds the interface with the MSD instance. + * + * @param[in] classHandle The class handle. + * @param[in] interfaceHandle The interface handle. + * @param[in] alternateSetting The alternate setting value. + * @param[in] callbackFn This callback is called after this function completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy There is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. + * @retval kStatus_USB_Success Callback return status, the command succeeded. + * @retval kStatus_USB_Busy Callback return status, there is no idle pipe. + * @retval kStatus_USB_TransferStall Callback return status, the transfer is stalled by the device. + * @retval kStatus_USB_Error Callback return status, open pipe fail. See the USB_HostOpenPipe. + */ +extern usb_status_t USB_HostMsdSetInterface(usb_host_class_handle classHandle, + usb_host_interface_handle interfaceHandle, + uint8_t alternateSetting, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Deinitializes the MSD instance. + * + * This function frees the resource for the MSD instance. + * + * @param[in] deviceHandle The device handle. + * @param[in] classHandle The class handle. + * + * @retval kStatus_USB_Success The device is de-initialized successfully. + */ +extern usb_status_t USB_HostMsdDeinit(usb_device_handle deviceHandle, usb_host_class_handle classHandle); + +/*! + * @brief Mass storage reset. + * + * This function implements the mass storage reset request. + * + * @param[in] classHandle The class handle. + * @param[in] callbackFn This callback is called after this function completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy There is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. + */ +extern usb_status_t USB_HostMsdMassStorageReset(usb_host_class_handle classHandle, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Gets the maximum logical unit number. + * + * This function implements the get maximum LUN request. + * + * @param[in] classHandle The class handle. + * @param[out] logicalUnitNumber Return logical unit number value. + * @param[in] callbackFn This callback is called after this function completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy There is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdGetMaxLun(usb_host_class_handle classHandle, + uint8_t *logicalUnitNumber, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage read (10). + * + * This function implements the UFI READ(10) command. This command requests that the UFI + * device transfer data to the host. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] blockNumber Read block number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdRead10(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + uint8_t *buffer, + uint32_t bufferLength, + uint32_t blockNumber, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage read (12). + * + * This function implements the UFI READ(12) command and requests that the UFI + * device transfer data to the host. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] blockNumber Read block number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdRead12(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + uint8_t *buffer, + uint32_t bufferLength, + uint32_t blockNumber, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage write (10). + * + * This function implements the UFI WRITE(10) command and requests that the UFI device + * write the data transferred by the host to the medium. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[in] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] blockNumber Write block number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdWrite10(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + uint8_t *buffer, + uint32_t bufferLength, + uint32_t blockNumber, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage write (12). + * + * This function implements the UFI WRITE(12) command and requests that the UFI device + * write the data transferred by the host to the medium. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[in] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] blockNumber Write block number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdWrite12(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + uint8_t *buffer, + uint32_t bufferLength, + uint32_t blockNumber, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage read capacity. + * + * This function implements the UFI READ CAPACITY command and allows the host to request + * capacities of the currently installed medium. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdReadCapacity(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage test unit ready. + * + * This function implements the UFI TEST UNIT READY command and + * checks if the UFI device is ready. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdTestUnitReady(usb_host_class_handle classHandle, + uint8_t logicalUnit, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief mass storage request sense. + * + * This function implements the UFI REQUEST SENSE command, this command instructs + * the UFI device to transfer sense data to the host for the specified logical unit. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdRequestSense(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage mode select. + * + * This function implements the UFI MODE SELECT command and allows the host + * to specify medium or device parameters to the UFI device. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdModeSelect(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage mode sense. + * + * This function implements the UFI MODE SENSE command and allows the UFI + * device to report medium or device parameters to the host. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] pageControl The page control field specifies the type of mode parameters to return. + * @param[in] pageCode Buffer pointer. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdModeSense(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t pageControl, + uint8_t pageCode, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage inquiry. + * + * This function implements the UFI INQUIRY command and requests that information regarding + * parameters of the UFI device itself be sent to the host. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdInquiry(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage read format capacities. + * + * This function implements the UFI READ FORMAT CAPACITIES command and allows the host to request + * a list of the possible capacities that can be formatted on the currently installed medium. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[out] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdReadFormatCapacities(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage format unit. + * + * This function implements the UFI FORMAT UNIT command and the host sends this command to physically format one + * track of a diskette according to the selected options. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] trackNumber This specifies which track is to be formatted. + * @param[in] interLeave This specifies the interleave that shall be used for formatting. + * @param[in] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdFormatUnit(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t trackNumber, + uint16_t interLeave, + uint8_t *buffer, + uint32_t bufferLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage prevents/allows a medium removal. + * + * This function implements the UFI PREVENT-ALLOW MEDIUM REMOVAL command and notifies the FUI device + * to enable or disable the removal of the medium in the logical unit. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] prevent Prevent or allow + * - 0: enable (allow) the removal of the medium + * - 1: disable (prevent) removal of the medium + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdPreventAllowRemoval(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t prevent, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage write and verify. + * + * This function implements the UFI WRITE AND VERIFY command and requests that the UFI device + * writes the data transferred by the host to the medium, then verifies the data on the medium. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[in] buffer Buffer pointer. + * @param[in] bufferLength The buffer length. + * @param[in] blockNumber Write and verify block number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdWriteAndVerify(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + uint8_t *buffer, + uint32_t bufferLength, + uint32_t blockNumber, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage start stop unit. + * + * This function implements the UFI START-STOP UNIT command and instructs the UFI device + * to enable or disable media access operations . + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] loadEject A Load Eject (LoEj) bit of zero requests that no eject action be performed. A LoEj bit of + * one, with the + * Start bit cleared to zero, which instructs the UFI device to eject the media. + * @param[in] start A Start bit of one instructs the UFI device to enable media access operations. A Start bit + * of zero instructs the UFI device to disable media access operations. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdStartStopUnit(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t loadEject, + uint8_t start, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage verify. + * + * This function implements the UFI VERIFY command and requests that the UFI device + * verify the data on the medium. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[in] verificationLength The data length that need to be verified. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdVerify(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + uint16_t verificationLength, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage rezero. + * + * This function implements the UFI REZERO UNIT command. This command positions the head of + * the drive to the cylinder 0. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdRezeroUnit(usb_host_class_handle classHandle, + uint8_t logicalUnit, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage seek(10). + * + * This function implements the UFI SEEK(10) command and requests that the UFI device + * seek to the specified Logical Block Address. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] blockAddress The start block address. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdSeek10(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint32_t blockAddress, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! + * @brief Mass storage send diagnostic. + * + * This function implements the UFI SEND DIAGNOSTIC command. This command requests the UFI device + * to do a reset or perform a self-test. + * + * @param[in] classHandle The class MSD handle. + * @param[in] logicalUnit Logical unit number. + * @param[in] selfTest 0 = perform special diagnostic test; 1 = perform default self-test. + * @param[in] callbackFn This callback is called after this command completes. + * @param[in] callbackParam The first parameter in the callback function. + * + * @retval kStatus_USB_Success The device is initialized successfully. + * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. + * @retval kStatus_USB_Busy The previous command is executing or there is no idle transfer. + * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSend/USB_HostRecv. + * @retval kStatus_USB_Success Callback return status, the command succeed. + * @retval kStatus_USB_MSDStatusFail Callback return status, the CSW status indicate this command fail. + * @retval kStatus_USB_Error Callback return status, the command fail. + */ +extern usb_status_t USB_HostMsdSendDiagnostic(usb_host_class_handle classHandle, + uint8_t logicalUnit, + uint8_t selfTest, + transfer_callback_t callbackFn, + void *callbackParam); + +/*! @}*/ + +#ifdef __cplusplus +} +#endif + +/*! @}*/ + +#endif /* _USB_HOST_MSD_H_ */ |