Statistics
| Branch: | Tag: | Revision:

root / LUFA / Drivers / USB / Class / Common / MassStorage.h @ 978b99e5

History | View | Annotate | Download (15.5 KB)

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 "../../Core/StdDescriptors.h"
55

    
56
        /* Enable C linkage for C++ Compilers: */
57
                #if defined(__cplusplus)
58
                        extern "C" {
59
                #endif
60

    
61
        /* Preprocessor Checks: */
62
                #if !defined(__INCLUDE_FROM_MS_DRIVER)
63
                        #error Do not include this file directly. Include LUFA/Drivers/USB.h instead.
64
                #endif
65

    
66
        /* Macros: */
67
                /** Magic signature for a Command Block Wrapper used in the Mass Storage Bulk-Only transport protocol. */
68
                #define MS_CBW_SIGNATURE                               0x43425355UL
69

    
70
                /** Magic signature for a Command Status Wrapper used in the Mass Storage Bulk-Only transport protocol. */
71
                #define MS_CSW_SIGNATURE                               0x53425355UL
72

    
73
                /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from host-to-device. */
74
                #define MS_COMMAND_DIR_DATA_OUT                        (0 << 7)
75

    
76
                /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from device-to-host. */
77
                #define MS_COMMAND_DIR_DATA_IN                         (1 << 7)
78

    
79
                /** \name SCSI Commands*/
80
                //@{
81
                /** SCSI Command Code for an INQUIRY command. */
82
                #define SCSI_CMD_INQUIRY                               0x12
83

    
84
                /** SCSI Command Code for a REQUEST SENSE command. */
85
                #define SCSI_CMD_REQUEST_SENSE                         0x03
86

    
87
                /** SCSI Command Code for a TEST UNIT READY command. */
88
                #define SCSI_CMD_TEST_UNIT_READY                       0x00
89

    
90
                /** SCSI Command Code for a READ CAPACITY (10) command. */
91
                #define SCSI_CMD_READ_CAPACITY_10                      0x25
92

    
93
                /** SCSI Command Code for a SEND DIAGNOSTIC command. */
94
                #define SCSI_CMD_SEND_DIAGNOSTIC                       0x1D
95

    
96
                /** SCSI Command Code for a PREVENT ALLOW MEDIUM REMOVAL command. */
97
                #define SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL          0x1E
98

    
99
                /** SCSI Command Code for a WRITE (10) command. */
100
                #define SCSI_CMD_WRITE_10                              0x2A
101

    
102
                /** SCSI Command Code for a READ (10) command. */
103
                #define SCSI_CMD_READ_10                               0x28
104

    
105
                /** SCSI Command Code for a WRITE (6) command. */
106
                #define SCSI_CMD_WRITE_6                               0x0A
107

    
108
                /** SCSI Command Code for a READ (6) command. */
109
                #define SCSI_CMD_READ_6                                0x08
110

    
111
                /** SCSI Command Code for a VERIFY (10) command. */
112
                #define SCSI_CMD_VERIFY_10                             0x2F
113

    
114
                /** SCSI Command Code for a MODE SENSE (6) command. */
115
                #define SCSI_CMD_MODE_SENSE_6                          0x1A
116

    
117
                /** SCSI Command Code for a MODE SENSE (10) command. */
118
                #define SCSI_CMD_MODE_SENSE_10                         0x5A
119
                //@}
120
                
121
                /** \name SCSI Sense Key Values */
122
                //@{
123
                /** SCSI Sense Code to indicate no error has occurred. */
124
                #define SCSI_SENSE_KEY_GOOD                            0x00
125

    
126
                /** SCSI Sense Code to indicate that the device has recovered from an error. */
127
                #define SCSI_SENSE_KEY_RECOVERED_ERROR                 0x01
128

    
129
                /** SCSI Sense Code to indicate that the device is not ready for a new command. */
130
                #define SCSI_SENSE_KEY_NOT_READY                       0x02
131

    
132
                /** SCSI Sense Code to indicate an error whilst accessing the medium. */
133
                #define SCSI_SENSE_KEY_MEDIUM_ERROR                    0x03
134

    
135
                /** SCSI Sense Code to indicate a hardware error has occurred. */
136
                #define SCSI_SENSE_KEY_HARDWARE_ERROR                  0x04
137

    
138
                /** SCSI Sense Code to indicate that an illegal request has been issued. */
139
                #define SCSI_SENSE_KEY_ILLEGAL_REQUEST                 0x05
140

    
141
                /** SCSI Sense Code to indicate that the unit requires attention from the host to indicate
142
                 *  a reset event, medium removal or other condition.
143
                 */
144
                #define SCSI_SENSE_KEY_UNIT_ATTENTION                  0x06
145

    
146
                /** SCSI Sense Code to indicate that a write attempt on a protected block has been made. */
147
                #define SCSI_SENSE_KEY_DATA_PROTECT                    0x07
148

    
149
                /** SCSI Sense Code to indicate an error while trying to write to a write-once medium. */
150
                #define SCSI_SENSE_KEY_BLANK_CHECK                     0x08
151

    
152
                /** SCSI Sense Code to indicate a vendor specific error has occurred. */
153
                #define SCSI_SENSE_KEY_VENDOR_SPECIFIC                 0x09
154

    
155
                /** SCSI Sense Code to indicate that an EXTENDED COPY command has aborted due to an error. */
156
                #define SCSI_SENSE_KEY_COPY_ABORTED                    0x0A
157

    
158
                /** SCSI Sense Code to indicate that the device has aborted the issued command. */
159
                #define SCSI_SENSE_KEY_ABORTED_COMMAND                 0x0B
160

    
161
                /** SCSI Sense Code to indicate an attempt to write past the end of a partition has been made. */
162
                #define SCSI_SENSE_KEY_VOLUME_OVERFLOW                 0x0D
163

    
164
                /** SCSI Sense Code to indicate that the source data did not match the data read from the medium. */
165
                #define SCSI_SENSE_KEY_MISCOMPARE                      0x0E
166
                //@}
167
                
168
                /** \name SCSI Additional Sense Codes */
169
                //@{
170
                /** SCSI Additional Sense Code to indicate no additional sense information is available. */
171
                #define SCSI_ASENSE_NO_ADDITIONAL_INFORMATION          0x00
172

    
173
                /** SCSI Additional Sense Code to indicate that the logical unit (LUN) addressed is not ready. */
174
                #define SCSI_ASENSE_LOGICAL_UNIT_NOT_READY             0x04
175

    
176
                /** SCSI Additional Sense Code to indicate an invalid field was encountered while processing the issued command. */
177
                #define SCSI_ASENSE_INVALID_FIELD_IN_CDB               0x24
178

    
179
                /** SCSI Additional Sense Code to indicate that a medium that was previously indicated as not ready has now
180
                 *  become ready for use.
181
                 */
182
                #define SCSI_ASENSE_NOT_READY_TO_READY_CHANGE          0x28
183

    
184
                /** SCSI Additional Sense Code to indicate that an attempt to write to a protected area was made. */
185
                #define SCSI_ASENSE_WRITE_PROTECTED                    0x27
186

    
187
                /** SCSI Additional Sense Code to indicate an error whilst formatting the device medium. */
188
                #define SCSI_ASENSE_FORMAT_ERROR                       0x31
189

    
190
                /** SCSI Additional Sense Code to indicate an invalid command was issued. */
191
                #define SCSI_ASENSE_INVALID_COMMAND                    0x20
192

    
193
                /** SCSI Additional Sense Code to indicate a write to a block out outside of the medium's range was issued. */
194
                #define SCSI_ASENSE_LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE 0x21
195

    
196
                /** SCSI Additional Sense Code to indicate that no removable medium is inserted into the device. */
197
                #define SCSI_ASENSE_MEDIUM_NOT_PRESENT                 0x3A
198
                //@}
199
                
200
                /** \name SCSI Additional Sense Key Code Qualifiers */
201
                //@{
202
                /** SCSI Additional Sense Qualifier Code to indicate no additional sense qualifier information is available. */
203
                #define SCSI_ASENSEQ_NO_QUALIFIER                      0x00
204

    
205
                /** SCSI Additional Sense Qualifier Code to indicate that a medium format command failed to complete. */
206
                #define SCSI_ASENSEQ_FORMAT_COMMAND_FAILED             0x01
207

    
208
                /** SCSI Additional Sense Qualifier Code to indicate that an initializing command must be issued before the issued
209
                 *  command can be executed.
210
                 */
211
                #define SCSI_ASENSEQ_INITIALIZING_COMMAND_REQUIRED     0x02
212

    
213
                /** SCSI Additional Sense Qualifier Code to indicate that an operation is currently in progress. */
214
                #define SCSI_ASENSEQ_OPERATION_IN_PROGRESS             0x07
215
                //@}
216
                
217
        /* Enums: */
218
                /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the Mass
219
                 *  Storage device class.
220
                 */
221
                enum MS_Descriptor_ClassSubclassProtocol_t
222
                {
223
                        MS_CSCP_MassStorageClass          = 0x08, /**< Descriptor Class value indicating that the device or interface
224
                                                                   *   belongs to the Mass Storage class.
225
                                                                   */
226
                        MS_CSCP_SCSITransparentSubclass   = 0x06, /**< Descriptor Subclass value indicating that the device or interface
227
                                                                   *   belongs to the SCSI Transparent Command Set subclass of the Mass
228
                                                                   *   storage class.
229
                                                                   */
230
                        MS_CSCP_BulkOnlyTransportProtocol = 0x50, /**< Descriptor Protocol value indicating that the device or interface
231
                                                                   *   belongs to the Bulk Only Transport protocol of the Mass Storage class.
232
                                                                   */
233
                };
234
        
235
                /** Enum for the Mass Storage class specific control requests that can be issued by the USB bus host. */
236
                enum MS_ClassRequests_t
237
                {
238
                        MS_REQ_GetMaxLUN                  = 0xFE, /**< Mass Storage class-specific request to retrieve the total number of Logical
239
                                                                   *   Units (drives) in the SCSI device.
240
                                                                   */
241
                        MS_REQ_MassStorageReset           = 0xFF, /**< Mass Storage class-specific request to reset the Mass Storage interface,
242
                                                                   *   ready for the next command.
243
                                                               */
244
                };
245

    
246
                /** Enum for the possible command status wrapper return status codes. */
247
                enum MS_CommandStatusCodes_t
248
                {
249
                        MS_SCSI_COMMAND_Pass              = 0, /**< Command completed with no error */
250
                        MS_SCSI_COMMAND_Fail              = 1, /**< Command failed to complete - host may check the exact error via a
251
                                                                *   SCSI REQUEST SENSE command.
252
                                                                */
253
                        MS_SCSI_COMMAND_PhaseError        = 2, /**< Command failed due to being invalid in the current phase. */
254
                };
255

    
256
        /* Type Defines: */
257
                /** \brief Mass Storage Class Command Block Wrapper.
258
                 *
259
                 *  Type define for a Command Block Wrapper, used in the Mass Storage Bulk-Only Transport protocol.
260
                 *
261
                 *  \note Regardless of CPU architecture, these values should be stored as little endian.
262
                 */
263
                typedef struct
264
                {
265
                        uint32_t Signature; /**< Command block signature, must be \ref MS_CBW_SIGNATURE to indicate a valid Command Block. */
266
                        uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */
267
                        uint32_t DataTransferLength; /**< Length of the optional data portion of the issued command, in bytes. */
268
                        uint8_t  Flags; /**< Command block flags, indicating command data direction. */
269
                        uint8_t  LUN; /**< Logical Unit number this command is issued to. */
270
                        uint8_t  SCSICommandLength; /**< Length of the issued SCSI command within the SCSI command data array. */
271
                        uint8_t  SCSICommandData[16]; /**< Issued SCSI command in the Command Block. */
272
                } ATTR_PACKED MS_CommandBlockWrapper_t;
273

    
274
                /** \brief Mass Storage Class Command Status Wrapper.
275
                 *
276
                 *  Type define for a Command Status Wrapper, used in the Mass Storage Bulk-Only Transport protocol.
277
                 *
278
                 *  \note Regardless of CPU architecture, these values should be stored as little endian.
279
                 */
280
                typedef struct
281
                {
282
                        uint32_t Signature; /**< Status block signature, must be \ref MS_CSW_SIGNATURE to indicate a valid Command Status. */
283
                        uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */
284
                        uint32_t DataTransferResidue; /**< Number of bytes of data not processed in the SCSI command. */
285
                        uint8_t  Status; /**< Status code of the issued command - a value from the \ref MS_CommandStatusCodes_t enum. */
286
                } ATTR_PACKED MS_CommandStatusWrapper_t;
287

    
288
                /** \brief Mass Storage Class SCSI Sense Structure
289
                 *
290
                 *  Type define for a SCSI Sense structure. Structures of this type are filled out by the
291
                 *  device via the \ref MS_Host_RequestSense() function, indicating the current sense data of the
292
                 *  device (giving explicit error codes for the last issued command). For details of the
293
                 *  structure contents, refer to the SCSI specifications.
294
                 */
295
                typedef struct
296
                {
297
                        uint8_t  ResponseCode;
298

    
299
                        uint8_t  SegmentNumber;
300

    
301
                        unsigned SenseKey            : 4;
302
                        unsigned Reserved            : 1;
303
                        unsigned ILI                 : 1;
304
                        unsigned EOM                 : 1;
305
                        unsigned FileMark            : 1;
306

    
307
                        uint8_t  Information[4];
308
                        uint8_t  AdditionalLength;
309
                        uint8_t  CmdSpecificInformation[4];
310
                        uint8_t  AdditionalSenseCode;
311
                        uint8_t  AdditionalSenseQualifier;
312
                        uint8_t  FieldReplaceableUnitCode;
313
                        uint8_t  SenseKeySpecific[3];
314
                } ATTR_PACKED SCSI_Request_Sense_Response_t;
315

    
316
                /** \brief Mass Storage Class SCSI Inquiry Structure.
317
                 *
318
                 *  Type define for a SCSI Inquiry structure. Structures of this type are filled out by the
319
                 *  device via the \ref MS_Host_GetInquiryData() function, retrieving the attached device's
320
                 *  information.
321
                 *
322
                 *  For details of the structure contents, refer to the SCSI specifications.
323
                 */
324
                typedef struct
325
                {
326
                        unsigned DeviceType          : 5;
327
                        unsigned PeripheralQualifier : 3;
328

    
329
                        unsigned Reserved            : 7;
330
                        unsigned Removable           : 1;
331

    
332
                        uint8_t  Version;
333

    
334
                        unsigned ResponseDataFormat  : 4;
335
                        unsigned Reserved2           : 1;
336
                        unsigned NormACA             : 1;
337
                        unsigned TrmTsk              : 1;
338
                        unsigned AERC                : 1;
339

    
340
                        uint8_t  AdditionalLength;
341
                        uint8_t  Reserved3[2];
342

    
343
                        unsigned SoftReset           : 1;
344
                        unsigned CmdQue              : 1;
345
                        unsigned Reserved4           : 1;
346
                        unsigned Linked              : 1;
347
                        unsigned Sync                : 1;
348
                        unsigned WideBus16Bit        : 1;
349
                        unsigned WideBus32Bit        : 1;
350
                        unsigned RelAddr             : 1;
351

    
352
                        uint8_t  VendorID[8];
353
                        uint8_t  ProductID[16];
354
                        uint8_t  RevisionID[4];
355
                } ATTR_PACKED SCSI_Inquiry_Response_t;
356

    
357
        /* Disable C linkage for C++ Compilers: */
358
                #if defined(__cplusplus)
359
                        }
360
                #endif
361

    
362
#endif
363

    
364
/** @} */
365