git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Demo/FreeRTOS_Plus_UDP_and_CLI_LPC1830_GCC/ThirdParty/LPCOpen/LPCUSBLib/Drivers/USB/Class/Common/MassStorageClassCommon.h

   1 /*\r
   2  * @brief Common definitions and declarations 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_USBClassMSCommon  Common Class Definitions\r
  35  *\r
  36  *  @section Sec_ModDescription Module Description\r
  37  *  Constants, Types and Enum definitions that are common to both Device and Host modes for the USB\r
  38  *  Mass Storage Class.\r
  39  *\r
  40  *  @{\r
  41  */\r
  42 \r
  43 #ifndef _MS_CLASS_COMMON_H_\r
  44 #define _MS_CLASS_COMMON_H_\r
  45 \r
  46         /* Includes: */\r
  47                 #include "../../Core/StdDescriptors.h"\r
  48 \r
  49         /* Enable C linkage for C++ Compilers: */\r
  50                 #if defined(__cplusplus)\r
  51                         extern "C" {\r
  52                 #endif\r
  53 \r
  54         /* Preprocessor Checks: */\r
  55                 #if !defined(__INCLUDE_FROM_MS_DRIVER)\r
  56                         #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.\r
  57                 #endif\r
  58 \r
  59         /* Macros: */\r
  60                 /** Magic signature for a Command Block Wrapper used in the Mass Storage Bulk-Only transport protocol. */\r
  61                 #define MS_CBW_SIGNATURE                               0x43425355UL\r
  62 \r
  63                 /** Magic signature for a Command Status Wrapper used in the Mass Storage Bulk-Only transport protocol. */\r
  64                 #define MS_CSW_SIGNATURE                               0x53425355UL\r
  65 \r
  66                 /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from host-to-device. */\r
  67                 #define MS_COMMAND_DIR_DATA_OUT                        (0 << 7)\r
  68 \r
  69                 /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from device-to-host. */\r
  70                 #define MS_COMMAND_DIR_DATA_IN                         (1 << 7)\r
  71 \r
  72                 /** @name SCSI Commands*/\r
  73                 //@{\r
  74                 /** SCSI Command Code for an INQUIRY command. */\r
  75                 #define SCSI_CMD_INQUIRY                               0x12\r
  76 \r
  77                 /** SCSI Command Code for a REQUEST SENSE command. */\r
  78                 #define SCSI_CMD_REQUEST_SENSE                         0x03\r
  79 \r
  80                 /** SCSI Command Code for a TEST UNIT READY command. */\r
  81                 #define SCSI_CMD_TEST_UNIT_READY                       0x00\r
  82 \r
  83                 /** SCSI Command Code for a READ CAPACITY (10) command. */\r
  84                 #define SCSI_CMD_READ_CAPACITY_10                      0x25\r
  85 \r
  86                 /** SCSI Command Code for a SEND DIAGNOSTIC command. */\r
  87                 #define SCSI_CMD_SEND_DIAGNOSTIC                       0x1D\r
  88 \r
  89                 /** SCSI Command Code for a PREVENT ALLOW MEDIUM REMOVAL command. */\r
  90                 #define SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL          0x1E\r
  91 \r
  92                 /** SCSI Command Code for a WRITE (10) command. */\r
  93                 #define SCSI_CMD_WRITE_10                              0x2A\r
  94 \r
  95                 /** SCSI Command Code for a READ (10) command. */\r
  96                 #define SCSI_CMD_READ_10                               0x28\r
  97 \r
  98                 /** SCSI Command Code for a WRITE (6) command. */\r
  99                 #define SCSI_CMD_WRITE_6                               0x0A\r
 100 \r
 101                 /** SCSI Command Code for a READ (6) command. */\r
 102                 #define SCSI_CMD_READ_6                                0x08\r
 103 \r
 104                 /** SCSI Command Code for a VERIFY (10) command. */\r
 105                 #define SCSI_CMD_VERIFY_10                             0x2F\r
 106 \r
 107                 /** SCSI Command Code for a MODE SENSE (6) command. */\r
 108                 #define SCSI_CMD_MODE_SENSE_6                          0x1A\r
 109 \r
 110                 /** SCSI Command Code for a MODE SENSE (10) command. */\r
 111                 #define SCSI_CMD_MODE_SENSE_10                         0x5A\r
 112                 //@}\r
 113                 \r
 114                 /** @name SCSI Sense Key Values */\r
 115                 //@{\r
 116                 /** SCSI Sense Code to indicate no error has occurred. */\r
 117                 #define SCSI_SENSE_KEY_GOOD                            0x00\r
 118 \r
 119                 /** SCSI Sense Code to indicate that the device has recovered from an error. */\r
 120                 #define SCSI_SENSE_KEY_RECOVERED_ERROR                 0x01\r
 121 \r
 122                 /** SCSI Sense Code to indicate that the device is not ready for a new command. */\r
 123                 #define SCSI_SENSE_KEY_NOT_READY                       0x02\r
 124 \r
 125                 /** SCSI Sense Code to indicate an error whilst accessing the medium. */\r
 126                 #define SCSI_SENSE_KEY_MEDIUM_ERROR                    0x03\r
 127 \r
 128                 /** SCSI Sense Code to indicate a hardware error has occurred. */\r
 129                 #define SCSI_SENSE_KEY_HARDWARE_ERROR                  0x04\r
 130 \r
 131                 /** SCSI Sense Code to indicate that an illegal request has been issued. */\r
 132                 #define SCSI_SENSE_KEY_ILLEGAL_REQUEST                 0x05\r
 133 \r
 134                 /** SCSI Sense Code to indicate that the unit requires attention from the host to indicate\r
 135                  *  a reset event, medium removal or other condition.\r
 136                  */\r
 137                 #define SCSI_SENSE_KEY_UNIT_ATTENTION                  0x06\r
 138 \r
 139                 /** SCSI Sense Code to indicate that a write attempt on a protected block has been made. */\r
 140                 #define SCSI_SENSE_KEY_DATA_PROTECT                    0x07\r
 141 \r
 142                 /** SCSI Sense Code to indicate an error while trying to write to a write-once medium. */\r
 143                 #define SCSI_SENSE_KEY_BLANK_CHECK                     0x08\r
 144 \r
 145                 /** SCSI Sense Code to indicate a vendor specific error has occurred. */\r
 146                 #define SCSI_SENSE_KEY_VENDOR_SPECIFIC                 0x09\r
 147 \r
 148                 /** SCSI Sense Code to indicate that an EXTENDED COPY command has aborted due to an error. */\r
 149                 #define SCSI_SENSE_KEY_COPY_ABORTED                    0x0A\r
 150 \r
 151                 /** SCSI Sense Code to indicate that the device has aborted the issued command. */\r
 152                 #define SCSI_SENSE_KEY_ABORTED_COMMAND                 0x0B\r
 153 \r
 154                 /** SCSI Sense Code to indicate an attempt to write past the end of a partition has been made. */\r
 155                 #define SCSI_SENSE_KEY_VOLUME_OVERFLOW                 0x0D\r
 156 \r
 157                 /** SCSI Sense Code to indicate that the source data did not match the data read from the medium. */\r
 158                 #define SCSI_SENSE_KEY_MISCOMPARE                      0x0E\r
 159                 //@}\r
 160                 \r
 161                 /** @name SCSI Additional Sense Codes */\r
 162                 //@{\r
 163                 /** SCSI Additional Sense Code to indicate no additional sense information is available. */\r
 164                 #define SCSI_ASENSE_NO_ADDITIONAL_INFORMATION          0x00\r
 165 \r
 166                 /** SCSI Additional Sense Code to indicate that the logical unit (LUN) addressed is not ready. */\r
 167                 #define SCSI_ASENSE_LOGICAL_UNIT_NOT_READY             0x04\r
 168 \r
 169                 /** SCSI Additional Sense Code to indicate an invalid field was encountered while processing the issued command. */\r
 170                 #define SCSI_ASENSE_INVALID_FIELD_IN_CDB               0x24\r
 171 \r
 172                 /** SCSI Additional Sense Code to indicate that a medium that was previously indicated as not ready has now\r
 173                  *  become ready for use.\r
 174                  */\r
 175                 #define SCSI_ASENSE_NOT_READY_TO_READY_CHANGE          0x28\r
 176 \r
 177                 /** SCSI Additional Sense Code to indicate that an attempt to write to a protected area was made. */\r
 178                 #define SCSI_ASENSE_WRITE_PROTECTED                    0x27\r
 179 \r
 180                 /** SCSI Additional Sense Code to indicate an error whilst formatting the device medium. */\r
 181                 #define SCSI_ASENSE_FORMAT_ERROR                       0x31\r
 182 \r
 183                 /** SCSI Additional Sense Code to indicate an invalid command was issued. */\r
 184                 #define SCSI_ASENSE_INVALID_COMMAND                    0x20\r
 185 \r
 186                 /** SCSI Additional Sense Code to indicate a write to a block out outside of the medium's range was issued. */\r
 187                 #define SCSI_ASENSE_LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE 0x21\r
 188 \r
 189                 /** SCSI Additional Sense Code to indicate that no removable medium is inserted into the device. */\r
 190                 #define SCSI_ASENSE_MEDIUM_NOT_PRESENT                 0x3A\r
 191                 //@}\r
 192                 \r
 193                 /** @name SCSI Additional Sense Key Code Qualifiers */\r
 194                 //@{\r
 195                 /** SCSI Additional Sense Qualifier Code to indicate no additional sense qualifier information is available. */\r
 196                 #define SCSI_ASENSEQ_NO_QUALIFIER                      0x00\r
 197 \r
 198                 /** SCSI Additional Sense Qualifier Code to indicate that a medium format command failed to complete. */\r
 199                 #define SCSI_ASENSEQ_FORMAT_COMMAND_FAILED             0x01\r
 200 \r
 201                 /** SCSI Additional Sense Qualifier Code to indicate that an initializing command must be issued before the issued\r
 202                  *  command can be executed.\r
 203                  */\r
 204                 #define SCSI_ASENSEQ_INITIALIZING_COMMAND_REQUIRED     0x02\r
 205 \r
 206                 /** SCSI Additional Sense Qualifier Code to indicate that an operation is currently in progress. */\r
 207                 #define SCSI_ASENSEQ_OPERATION_IN_PROGRESS             0x07\r
 208                 //@}\r
 209                 \r
 210         /* Enums: */\r
 211                 /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the Mass\r
 212                  *  Storage device class.\r
 213                  */\r
 214                 enum MS_Descriptor_ClassSubclassProtocol_t\r
 215                 {\r
 216                         MS_CSCP_MassStorageClass          = 0x08, /**< Descriptor Class value indicating that the device or interface\r
 217                                                                    *   belongs to the Mass Storage class.\r
 218                                                                    */\r
 219                         MS_CSCP_SCSITransparentSubclass   = 0x06, /**< Descriptor Subclass value indicating that the device or interface\r
 220                                                                    *   belongs to the SCSI Transparent Command Set subclass of the Mass\r
 221                                                                    *   storage class.\r
 222                                                                    */\r
 223                         MS_CSCP_BulkOnlyTransportProtocol = 0x50, /**< Descriptor Protocol value indicating that the device or interface\r
 224                                                                    *   belongs to the Bulk Only Transport protocol of the Mass Storage class.\r
 225                                                                    */\r
 226                 };\r
 227         \r
 228                 /** Enum for the Mass Storage class specific control requests that can be issued by the USB bus host. */\r
 229                 enum MS_ClassRequests_t\r
 230                 {\r
 231                         MS_REQ_GetMaxLUN                  = 0xFE, /**< Mass Storage class-specific request to retrieve the total number of Logical\r
 232                                                                    *   Units (drives) in the SCSI device.\r
 233                                                                    */\r
 234                         MS_REQ_MassStorageReset           = 0xFF, /**< Mass Storage class-specific request to reset the Mass Storage interface,\r
 235                                                                    *   ready for the next command.\r
 236                                                                */\r
 237                 };\r
 238 \r
 239                 /** Enum for the possible command status wrapper return status codes. */\r
 240                 enum MS_CommandStatusCodes_t\r
 241                 {\r
 242                         MS_SCSI_COMMAND_Pass              = 0, /**< Command completed with no error */\r
 243                         MS_SCSI_COMMAND_Fail              = 1, /**< Command failed to complete - host may check the exact error via a\r
 244                                                                 *   SCSI REQUEST SENSE command.\r
 245                                                                 */\r
 246                         MS_SCSI_COMMAND_PhaseError        = 2, /**< Command failed due to being invalid in the current phase. */\r
 247                 };\r
 248 \r
 249         /* Type Defines: */\r
 250                 /** @brief Mass Storage Class Command Block Wrapper.\r
 251                  *\r
 252                  *  Type define for a Command Block Wrapper, used in the Mass Storage Bulk-Only Transport protocol.\r
 253                  *\r
 254                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 255                  */\r
 256                 typedef ATTR_IAR_PACKED struct\r
 257                 {\r
 258                         uint32_t Signature; /**< Command block signature, must be @ref MS_CBW_SIGNATURE to indicate a valid Command Block. */\r
 259                         uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */\r
 260                         uint32_t DataTransferLength; /**< Length of the optional data portion of the issued command, in bytes. */\r
 261                         uint8_t  Flags; /**< Command block flags, indicating command data direction. */\r
 262                         uint8_t  LUN; /**< Logical Unit number this command is issued to. */\r
 263                         uint8_t  SCSICommandLength; /**< Length of the issued SCSI command within the SCSI command data array. */\r
 264                         uint8_t  SCSICommandData[16]; /**< Issued SCSI command in the Command Block. */\r
 265                 } ATTR_PACKED MS_CommandBlockWrapper_t;\r
 266 \r
 267                 /** @brief Mass Storage Class Command Status Wrapper.\r
 268                  *\r
 269                  *  Type define for a Command Status Wrapper, used in the Mass Storage Bulk-Only Transport protocol.\r
 270                  *\r
 271                  *  @note Regardless of CPU architecture, these values should be stored as little endian.\r
 272                  */\r
 273                 typedef ATTR_IAR_PACKED struct\r
 274                 {\r
 275                         uint32_t Signature; /**< Status block signature, must be @ref MS_CSW_SIGNATURE to indicate a valid Command Status. */\r
 276                         uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */\r
 277                         uint32_t DataTransferResidue; /**< Number of bytes of data not processed in the SCSI command. */\r
 278                         uint8_t  Status; /**< Status code of the issued command - a value from the @ref MS_CommandStatusCodes_t enum. */\r
 279                 } ATTR_PACKED MS_CommandStatusWrapper_t;\r
 280 \r
 281                 /** @brief Mass Storage Class SCSI Sense Structure\r
 282                  *\r
 283                  *  Type define for a SCSI Sense structure. Structures of this type are filled out by the\r
 284                  *  device via the @ref MS_Host_RequestSense() function, indicating the current sense data of the\r
 285                  *  device (giving explicit error codes for the last issued command). For details of the\r
 286                  *  structure contents, refer to the SCSI specifications.\r
 287                  */\r
 288                 typedef ATTR_IAR_PACKED struct\r
 289                 {\r
 290                         uint8_t  ResponseCode;\r
 291 \r
 292                         uint8_t  SegmentNumber;\r
 293 \r
 294                         unsigned SenseKey            : 4;\r
 295                         unsigned Reserved            : 1;\r
 296                         unsigned ILI                 : 1;\r
 297                         unsigned EOM                 : 1;\r
 298                         unsigned FileMark            : 1;\r
 299 \r
 300                         uint8_t  Information[4];\r
 301                         uint8_t  AdditionalLength;\r
 302                         uint8_t  CmdSpecificInformation[4];\r
 303                         uint8_t  AdditionalSenseCode;\r
 304                         uint8_t  AdditionalSenseQualifier;\r
 305                         uint8_t  FieldReplaceableUnitCode;\r
 306                         uint8_t  SenseKeySpecific[3];\r
 307                 } ATTR_PACKED SCSI_Request_Sense_Response_t;\r
 308 \r
 309                 /** @brief Mass Storage Class SCSI Inquiry Structure.\r
 310                  *\r
 311                  *  Type define for a SCSI Inquiry structure. Structures of this type are filled out by the\r
 312                  *  device via the @ref MS_Host_GetInquiryData() function, retrieving the attached device's\r
 313                  *  information.\r
 314                  *\r
 315                  *  For details of the structure contents, refer to the SCSI specifications.\r
 316                  */\r
 317                 typedef ATTR_IAR_PACKED struct\r
 318                 {\r
 319                         unsigned DeviceType          : 5;\r
 320                         unsigned PeripheralQualifier : 3;\r
 321 \r
 322                         unsigned Reserved            : 7;\r
 323                         unsigned Removable           : 1;\r
 324 \r
 325                         uint8_t  Version;\r
 326 \r
 327                         unsigned ResponseDataFormat  : 4;\r
 328                         unsigned Reserved2           : 1;\r
 329                         unsigned NormACA             : 1;\r
 330                         unsigned TrmTsk              : 1;\r
 331                         unsigned AERC                : 1;\r
 332 \r
 333                         uint8_t  AdditionalLength;\r
 334                         uint8_t  Reserved3[2];\r
 335 \r
 336                         unsigned SoftReset           : 1;\r
 337                         unsigned CmdQue              : 1;\r
 338                         unsigned Reserved4           : 1;\r
 339                         unsigned Linked              : 1;\r
 340                         unsigned Sync                : 1;\r
 341                         unsigned WideBus16Bit        : 1;\r
 342                         unsigned WideBus32Bit        : 1;\r
 343                         unsigned RelAddr             : 1;\r
 344 \r
 345                         uint8_t  VendorID[8];\r
 346                         uint8_t  ProductID[16];\r
 347                         uint8_t  RevisionID[4];\r
 348                 } ATTR_PACKED SCSI_Inquiry_Response_t;\r
 349 \r
 350         /* Disable C linkage for C++ Compilers: */\r
 351                 #if defined(__cplusplus)\r
 352                         }\r
 353                 #endif\r
 354 \r
 355 #endif\r
 356 \r
 357 /** @} */\r
 358 \r