git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Host mode driver for the library USB Mass Storage Class driver\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6  * Copyright(C) Dean Camera, 2011, 2012\r
   7  * All rights reserved.\r
   8  *\r
   9  * @par\r
  10  * Software that is described herein is for illustrative purposes only\r
  11  * which provides customers with programming information regarding the\r
  12  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  13  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  14  * all warranties, express or implied, including all implied warranties of\r
  15  * merchantability, fitness for a particular purpose and non-infringement of\r
  16  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  17  * or liability for the use of the software, conveys no license or rights under any\r
  18  * patent, copyright, mask work right, or any other intellectual property rights in\r
  19  * or to any products. NXP Semiconductors reserves the right to make changes\r
  20  * in the software without notification. NXP Semiconductors also makes no\r
  21  * representation or warranty that such application will be suitable for the\r
  22  * specified use without further testing or modification.\r
  23  *\r
  24  * @par\r
  25  * Permission to use, copy, modify, and distribute this software and its\r
  26  * documentation is hereby granted, under NXP Semiconductors' and its\r
  27  * licensor's relevant copyrights in the software, without fee, provided that it\r
  28  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  29  * copyright, permission, and disclaimer notice must appear in all copies of\r
  30  * this code.\r
  31  */\r
  32 \r
  33 /** @ingroup Group_USBClassMS\r
  34  *  @defgroup Group_USBClassMassStorageHost Mass Storage Class Host Mode Driver\r
  35  *\r
  36  *  @section Sec_Dependencies Module Source Dependencies\r
  37  *  The following files must be built with any user project that uses this module:\r
  38  *    - LPCUSBlib/Drivers/USB/Class/Host/MassStorage.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>\r
  39  *\r
  40  *  @section Sec_ModDescription Module Description\r
  41  *  Host Mode USB Class driver framework interface, for the Mass Storage USB Class driver.\r
  42  *\r
  43  *  @{\r
  44  */\r
  45 \r
  46 #ifndef __MS_CLASS_HOST_H__\r
  47 #define __MS_CLASS_HOST_H__\r
  48 \r
  49         /* Includes: */\r
  50                 #include "../../USB.h"\r
  51                 #include "../Common/MassStorageClassCommon.h"\r
  52 \r
  53         /* Enable C linkage for C++ Compilers: */\r
  54                 #if defined(__cplusplus)\r
  55                         extern "C" {\r
  56                 #endif\r
  57 \r
  58         /* Preprocessor Checks: */\r
  59                 #if !defined(__INCLUDE_FROM_MS_DRIVER)\r
  60                         #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.\r
  61                 #endif\r
  62 \r
  63         /* Public Interface - May be used in end-application: */\r
  64                 /* Macros: */\r
  65                         /** Error code for some Mass Storage Host functions, indicating a logical (and not hardware) error. */\r
  66                         #define MS_ERROR_LOGICAL_CMD_FAILED              0x80\r
  67 \r
  68                 /* Type Defines: */\r
  69                         /** @brief Mass Storage Class Host Mode Configuration and State Structure.\r
  70                          *\r
  71                          *  Class state structure. An instance of this structure should be made within the user application,\r
  72                          *  and passed to each of the Mass Storage class driver functions as the \c MSInterfaceInfo parameter. This\r
  73                          *  stores each Mass Storage interface's configuration and state information.\r
  74                          */\r
  75                         typedef struct\r
  76                         {\r
  77                                 struct\r
  78                                 {\r
  79                                         uint8_t  DataINPipeNumber; /**< Pipe number of the Mass Storage interface's IN data pipe. */\r
  80                                         bool     DataINPipeDoubleBank; /**< Indicates if the Mass Storage interface's IN data pipe should use double banking. */\r
  81 \r
  82                                         uint8_t  DataOUTPipeNumber; /**< Pipe number of the Mass Storage interface's OUT data pipe. */\r
  83                                         bool     DataOUTPipeDoubleBank; /**< Indicates if the Mass Storage interface's OUT data pipe should use double banking. */\r
  84                                         uint8_t  PortNumber;            /**< Port number that this interface is running.\r
  85                                                                                                 */\r
  86                                 } Config; /**< Config data for the USB class interface within the device. All elements in this section\r
  87                                            *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.\r
  88                                            */\r
  89                                 struct\r
  90                                 {\r
  91                                         bool     IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid\r
  92                                                             *   after @ref MS_Host_ConfigurePipes() is called and the Host state machine is in the\r
  93                                                             *   Configured state.\r
  94                                                             */\r
  95                                         uint8_t  InterfaceNumber; /**< Interface index of the Mass Storage interface within the attached device. */\r
  96 \r
  97                                         uint16_t DataINPipeSize; /**< Size in bytes of the Mass Storage interface's IN data pipe. */\r
  98                                         uint16_t DataOUTPipeSize;  /**< Size in bytes of the Mass Storage interface's OUT data pipe. */\r
  99 \r
 100                                         uint32_t TransactionTag; /**< Current transaction tag for data synchronizing of packets. */\r
 101                                 } State; /**< State data for the USB class interface within the device. All elements in this section\r
 102                                                   *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when\r
 103                                                   *   the interface is enumerated.\r
 104                                                   */\r
 105                         } USB_ClassInfo_MS_Host_t;\r
 106 \r
 107                         /** @brief SCSI Device LUN Capacity Structure.\r
 108                          *\r
 109                          *  SCSI capacity structure, to hold the total capacity of the device in both the number\r
 110                          *  of blocks in the current LUN, and the size of each block. This structure is filled by\r
 111                          *  the device when the @ref MS_Host_ReadDeviceCapacity() function is called.\r
 112                          */\r
 113                         typedef struct\r
 114                         {\r
 115                                 uint32_t Blocks; /**< Number of blocks in the addressed LUN of the device. */\r
 116                                 uint32_t BlockSize; /**< Number of bytes in each block in the addressed LUN. */\r
 117                         } SCSI_Capacity_t;\r
 118 \r
 119                 /* Enums: */\r
 120                         enum MS_Host_EnumerationFailure_ErrorCodes_t\r
 121                         {\r
 122                                 MS_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully. */\r
 123                                 MS_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor. */\r
 124                                 MS_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible Mass Storage interface was not found in the device's Configuration Descriptor. */\r
 125                                 MS_ENUMERROR_PipeConfigurationFailed    = 3, /**< One or more pipes for the specified interface could not be configured correctly. */\r
 126                         };\r
 127 \r
 128                 /* Function Prototypes: */\r
 129                         /** @brief Host interface configuration routine, to configure a given Mass Storage host interface instance using the\r
 130                          *  Configuration Descriptor read from an attached USB device. This function automatically updates the given Mass\r
 131                          *  Storage Host instance's state values and configures the pipes required to communicate with the interface if it\r
 132                          *  is found within the device. This should be called once after the stack has enumerated the attached device, while\r
 133                          *  the host state machine is in the Addressed state.\r
 134                          *\r
 135                          *  @param MSInterfaceInfo      : Pointer to a structure containing an MS Class host configuration and state.\r
 136                          *  @param ConfigDescriptorSize : Length of the attached device's Configuration Descriptor.\r
 137                          *  @param ConfigDescriptorData : Pointer to a buffer containing the attached device's Configuration Descriptor.\r
 138                          *\r
 139                          *  @return A value from the @ref MS_Host_EnumerationFailure_ErrorCodes_t enum.\r
 140                          */\r
 141                         uint8_t MS_Host_ConfigurePipes(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 142                                                        uint16_t ConfigDescriptorSize,\r
 143                                                        void* ConfigDescriptorData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r
 144 \r
 145                         /** @brief Sends a MASS STORAGE RESET control request to the attached device, resetting the Mass Storage Interface\r
 146                          *  and readying it for the next Mass Storage command. This should be called after a failed SCSI request to \r
 147                          *  ensure the attached Mass Storage device is ready to receive the next command.\r
 148                          *\r
 149                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 150                          *\r
 151                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.\r
 152                          */\r
 153                         uint8_t MS_Host_ResetMSInterface(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 154 \r
 155                         /** @brief Sends a GET MAX LUN control request to the attached device, retrieving the index of the highest LUN (Logical\r
 156                          *  UNit, a logical drive) in the device. This value can then be used in the other functions of the Mass Storage\r
 157                          *  Host mode Class driver to address a specific LUN within the device.\r
 158                          *\r
 159                          *  @note Some devices do not support this request, and will STALL it when issued. To get around this,\r
 160                          *        on unsupported devices the max LUN index will be reported as zero and no error will be returned\r
 161                          *        if the device STALLs the request.\r
 162                          *\r
 163                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 164                          *  @param MaxLUNIndex     : Pointer to a location where the highest LUN index value should be stored.\r
 165                          *\r
 166                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.\r
 167                          */\r
 168                         uint8_t MS_Host_GetMaxLUN(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 169                                                   uint8_t* const MaxLUNIndex) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 170 \r
 171                         /** @brief Retrieves the Mass Storage device's inquiry data for the specified LUN, indicating the device characteristics and\r
 172                          *  properties.\r
 173                          *\r
 174                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 175                          *       call will fail.\r
 176                          *\r
 177                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 178                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 179                          *  @param InquiryData     : Location where the read inquiry data should be stored.\r
 180                          *\r
 181                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED.\r
 182                          */\r
 183                         uint8_t MS_Host_GetInquiryData(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 184                                                        const uint8_t LUNIndex,\r
 185                                                        SCSI_Inquiry_Response_t* const InquiryData) ATTR_NON_NULL_PTR_ARG(1)\r
 186                                                        ATTR_NON_NULL_PTR_ARG(3);\r
 187 \r
 188                         /** @brief Sends a TEST UNIT READY command to the device, to determine if it is ready to accept other SCSI commands.\r
 189                          *\r
 190                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 191                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 192                          *\r
 193                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.\r
 194                          */\r
 195                         uint8_t MS_Host_TestUnitReady(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 196                                                       const uint8_t LUNIndex) ATTR_NON_NULL_PTR_ARG(1);\r
 197 \r
 198                         /** @brief Retrieves the total capacity of the attached USB Mass Storage device, in blocks, and block size.\r
 199                          *\r
 200                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 201                          *       call will fail.\r
 202                          *\r
 203                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 204                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 205                          *  @param DeviceCapacity  : Pointer to the location where the capacity information should be stored.\r
 206                          *\r
 207                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.\r
 208                          */\r
 209                         uint8_t MS_Host_ReadDeviceCapacity(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 210                                                            const uint8_t LUNIndex,\r
 211                                                            SCSI_Capacity_t* const DeviceCapacity) ATTR_NON_NULL_PTR_ARG(1)\r
 212                                                            ATTR_NON_NULL_PTR_ARG(3);\r
 213 \r
 214                         /** @brief Retrieves the device sense data, indicating the current device state and error codes for the previously\r
 215                          *  issued command.\r
 216                          *\r
 217                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 218                          *       call will fail.\r
 219                          *\r
 220                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 221                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 222                          *  @param SenseData       : Pointer to the location where the sense information should be stored.\r
 223                          *\r
 224                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.\r
 225                          */\r
 226                         uint8_t MS_Host_RequestSense(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 227                                                      const uint8_t LUNIndex,\r
 228                                                      SCSI_Request_Sense_Response_t* const SenseData) ATTR_NON_NULL_PTR_ARG(1)\r
 229                                                      ATTR_NON_NULL_PTR_ARG(3);\r
 230 \r
 231                         /** @brief Issues a PREVENT MEDIUM REMOVAL command, to logically (or, depending on the type of device, physically) lock\r
 232                          *  the device from removal so that blocks of data on the medium can be read or altered.\r
 233                          *\r
 234                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 235                          *       call will fail.\r
 236                          *\r
 237                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 238                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 239                          *  @param PreventRemoval  : Boolean \c true if the device should be locked from removal, \c false otherwise.\r
 240                          *\r
 241                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.\r
 242                          */\r
 243                         uint8_t MS_Host_PreventAllowMediumRemoval(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 244                                                                   const uint8_t LUNIndex,\r
 245                                                                   const bool PreventRemoval) ATTR_NON_NULL_PTR_ARG(1);\r
 246 \r
 247                         /** @brief Reads blocks of data from the attached Mass Storage device's medium.\r
 248                          *\r
 249                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 250                          *       call will fail.\r
 251                          *\r
 252                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 253                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 254                          *  @param BlockAddress    : Starting block address within the device to read from.\r
 255                          *  @param Blocks          : Total number of blocks to read.\r
 256                          *  @param BlockSize       : Size in bytes of each block within the device.\r
 257                          *  @param BlockBuffer     : Pointer to where the read data from the device should be stored.\r
 258                          *\r
 259                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.\r
 260                          */\r
 261                         uint8_t MS_Host_ReadDeviceBlocks(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 262                                                          const uint8_t LUNIndex,\r
 263                                                          const uint32_t BlockAddress,\r
 264                                                          const uint8_t Blocks,\r
 265                                                          const uint16_t BlockSize,\r
 266                                                          void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6);\r
 267 \r
 268                         /** @brief Writes blocks of data to the attached Mass Storage device's medium.\r
 269                          *\r
 270                          *  @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the\r
 271                          *       call will fail.\r
 272                          *\r
 273                          *  @param MSInterfaceInfo : Pointer to a structure containing a MS Class host configuration and state.\r
 274                          *  @param LUNIndex        : LUN index within the device the command is being issued to.\r
 275                          *  @param BlockAddress    : Starting block address within the device to write to.\r
 276                          *  @param Blocks          : Total number of blocks to read.\r
 277                          *  @param BlockSize       : Size in bytes of each block within the device.\r
 278                          *  @param BlockBuffer     : Pointer to where the data to write should be sourced from.\r
 279                          *\r
 280                          *  @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum or @ref MS_ERROR_LOGICAL_CMD_FAILED if not ready.\r
 281                          */\r
 282                         uint8_t MS_Host_WriteDeviceBlocks(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 283                                                           const uint8_t LUNIndex,\r
 284                                                           const uint32_t BlockAddress,\r
 285                                                           const uint8_t Blocks,\r
 286                                                           const uint16_t BlockSize,\r
 287                                                           const void* BlockBuffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(6);\r
 288 \r
 289                 /* Inline Functions: */\r
 290                         /** @brief General management task for a given Mass Storage host class interface, required for the correct operation of\r
 291                          *  the interface. This should be called frequently in the main program loop, before the master USB management task\r
 292                          *  @ref USB_USBTask().\r
 293                          *\r
 294                          *  @param MSInterfaceInfo : Pointer to a structure containing an Mass Storage Class host configuration and state.\r
 295                          *      @return Nothing\r
 296                          */\r
 297                         static inline void MS_Host_USBTask(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1) ATTR_ALWAYS_INLINE;\r
 298                         static inline void MS_Host_USBTask(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo)\r
 299                         {\r
 300                                 (void)MSInterfaceInfo;\r
 301                         }\r
 302 \r
 303         /* Private Interface - For use in library only: */\r
 304         #if !defined(__DOXYGEN__)\r
 305                 /* Macros: */\r
 306                         #define MS_COMMAND_DATA_TIMEOUT_MS        10000\r
 307 \r
 308                 /* Function Prototypes: */\r
 309                         #if defined(__INCLUDE_FROM_MASSSTORAGE_HOST_C)\r
 310                                 static uint8_t MS_Host_SendCommand(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 311                                                                    MS_CommandBlockWrapper_t* const SCSICommandBlock,\r
 312                                                                    const void* const BufferPtr) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 313                                 static uint8_t MS_Host_WaitForDataReceived(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 314                                 static uint8_t MS_Host_SendReceiveData(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 315                                                                        MS_CommandBlockWrapper_t* const SCSICommandBlock,\r
 316                                                                        void* BufferPtr) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 317                                 static uint8_t MS_Host_GetReturnedStatus(USB_ClassInfo_MS_Host_t* const MSInterfaceInfo,\r
 318                                                                          MS_CommandStatusWrapper_t* const SCSICommandStatus)\r
 319                                                                          ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
 320 \r
 321                                 static uint8_t DCOMP_MS_Host_NextMSInterface(void* const CurrentDescriptor)\r
 322                                                                              ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 323                                 static uint8_t DCOMP_MS_Host_NextMSInterfaceEndpoint(void* const CurrentDescriptor)\r
 324                                                                                      ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);\r
 325                         #endif\r
 326         #endif\r
 327 \r
 328         /* Disable C linkage for C++ Compilers: */\r
 329                 #if defined(__cplusplus)\r
 330                         }\r
 331                 #endif\r
 332 \r
 333 #endif\r
 334 \r
 335 /** @} */\r
 336 \r