LUFA/Drivers/USB/Class/Common/MassStorage.h

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