MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h

   1 /** @file
   2   Definition of the command set of USB Mass Storage Specification
   3   for Bootability, Revision 1.0.
   4
   5 Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _EFI_USB_MASS_BOOT_H_
  17 #define _EFI_USB_MASS_BOOT_H_
  18
  19 //
  20 // The opcodes of various USB boot commands:
  21 // INQUIRY/REQUEST_SENSE are "No Timeout Commands" as specified
  22 // by Multi-Media Commands (MMC) set.
  23 // Others are "Group 1 Timeout Commands". That is,
  24 // they should be retried if driver is ready.
  25 //
  26 #define USB_BOOT_INQUIRY_OPCODE         0x12
  27 #define USB_BOOT_REQUEST_SENSE_OPCODE   0x03
  28 #define USB_BOOT_MODE_SENSE10_OPCODE    0x5A
  29 #define USB_BOOT_READ_CAPACITY_OPCODE   0x25
  30 #define USB_BOOT_TEST_UNIT_READY_OPCODE 0x00
  31 #define USB_BOOT_READ10_OPCODE          0x28
  32 #define USB_BOOT_WRITE10_OPCODE         0x2A
  33
  34 #define USB_SCSI_MODE_SENSE6_OPCODE     0x1A
  35
  36 //
  37 // The Sense Key part of the sense data. Sense data has three levels:
  38 // Sense key, Additional Sense Code and Additional Sense Code Qualifier
  39 //
  40 #define USB_BOOT_SENSE_NO_SENSE         0x00 ///< No sense key
  41 #define USB_BOOT_SENSE_RECOVERED        0x01 ///< Last command succeed with recovery actions
  42 #define USB_BOOT_SENSE_NOT_READY        0x02 ///< Device not ready
  43 #define USB_BOOT_SNESE_MEDIUM_ERROR     0X03 ///< Failed probably because flaw in the media
  44 #define USB_BOOT_SENSE_HARDWARE_ERROR   0X04 ///< Non-recoverable hardware failure
  45 #define USB_BOOT_SENSE_ILLEGAL_REQUEST  0X05 ///< Illegal parameters in the request
  46 #define USB_BOOT_SENSE_UNIT_ATTENTION   0X06 ///< Removable medium may have been changed
  47 #define USB_BOOT_SENSE_DATA_PROTECT     0X07 ///< Write protected
  48 #define USB_BOOT_SENSE_BLANK_CHECK      0X08 ///< Blank/non-blank medium while reading/writing
  49 #define USB_BOOT_SENSE_VENDOR           0X09 ///< Vendor specific sense key
  50 #define USB_BOOT_SENSE_ABORTED          0X0B ///< Command aborted by the device
  51 #define USB_BOOT_SENSE_VOLUME_OVERFLOW  0x0D ///< Partition overflow
  52 #define USB_BOOT_SENSE_MISCOMPARE       0x0E ///< Source data mis-match while verfying.
  53
  54 #define USB_BOOT_ASC_NO_ADDITIONAL_SENSE_INFORMATION  0x00
  55 #define USB_BOOT_ASC_NOT_READY                        0x04
  56 #define USB_BOOT_ASC_NO_MEDIA                         0x3A
  57 #define USB_BOOT_ASC_MEDIA_CHANGE                     0x28
  58 #define USB_BOOT_ASC_POWER_ON                         0x29
  59
  60 //
  61 // Supported PDT codes, or Peripheral Device Type
  62 //
  63 #define USB_PDT_DIRECT_ACCESS           0x00       ///< Direct access device
  64 #define USB_PDT_CDROM                   0x05       ///< CDROM
  65 #define USB_PDT_OPTICAL                 0x07       ///< Non-CD optical disks
  66 #define USB_PDT_SIMPLE_DIRECT           0x0E       ///< Simplified direct access device
  67
  68 //
  69 // Other parameters, Max carried size is 512B * 128 = 64KB
  70 //
  71 #define USB_BOOT_IO_BLOCKS              128
  72
  73 //
  74 // Retry mass command times, set by experience
  75 //
  76 #define USB_BOOT_COMMAND_RETRY          5
  77
  78 //
  79 // Wait for unit ready command, set by experience
  80 //
  81 #define USB_BOOT_RETRY_UNIT_READY_STALL (500 * USB_MASS_1_MILLISECOND)
  82
  83 //
  84 // Mass command timeout, refers to specification[USB20-9.2.6.1]
  85 //
  86 // USB2.0 Spec define the up-limit timeout 5s for all command. USB floppy,
  87 // USB CD-Rom and iPod devices are much slower than USB key when reponse
  88 // most of commands, So we set 5s as timeout here.
  89 //
  90 #define USB_BOOT_GENERAL_CMD_TIMEOUT    (5 * USB_MASS_1_SECOND)
  91
  92 //
  93 // The required commands are INQUIRY, READ CAPACITY, TEST UNIT READY,
  94 // READ10, WRITE10, and REQUEST SENSE. The BLOCK_IO protocol uses LBA
  95 // so it isn't necessary to issue MODE SENSE / READ FORMAT CAPACITY
  96 // command to retrieve the disk gemotrics.
  97 //
  98 #pragma pack(1)
  99 typedef struct {
 100   UINT8             OpCode;
 101   UINT8             Lun;            ///< Lun (high 3 bits)
 102   UINT8             Reserved0[2];
 103   UINT8             AllocLen;
 104   UINT8             Reserved1;
 105   UINT8             Pad[6];
 106 } USB_BOOT_INQUIRY_CMD;
 107
 108 typedef struct {
 109   UINT8             Pdt;            ///< Peripheral Device Type (low 5 bits)
 110   UINT8             Removable;      ///< Removable Media (highest bit)
 111   UINT8             Reserved0[2];
 112   UINT8             AddLen;         ///< Additional length
 113   UINT8             Reserved1[3];
 114   UINT8             VendorID[8];
 115   UINT8             ProductID[16];
 116   UINT8             ProductRevision[4];
 117 } USB_BOOT_INQUIRY_DATA;
 118
 119 typedef struct {
 120   UINT8             OpCode;
 121   UINT8             Lun;
 122   UINT8             Reserved0[8];
 123   UINT8             Pad[2];
 124 } USB_BOOT_READ_CAPACITY_CMD;
 125
 126 typedef struct {
 127   UINT8             LastLba[4];
 128   UINT8             BlockLen[4];
 129 } USB_BOOT_READ_CAPACITY_DATA;
 130
 131 typedef struct {
 132   UINT8             OpCode;
 133   UINT8             Lun;
 134   UINT8             Reserved[4];
 135   UINT8             Pad[6];
 136 } USB_BOOT_TEST_UNIT_READY_CMD;
 137
 138 typedef struct {
 139   UINT8             OpCode;
 140   UINT8             Lun;
 141   UINT8             PageCode;
 142   UINT8             Reserved0[4];
 143   UINT8             ParaListLenMsb;
 144   UINT8             ParaListLenLsb;
 145   UINT8             Reserved1;
 146   UINT8             Pad[2];
 147 } USB_BOOT_MODE_SENSE10_CMD;
 148
 149 typedef struct {
 150   UINT8             ModeDataLenMsb;
 151   UINT8             ModeDataLenLsb;
 152   UINT8             Reserved0[4];
 153   UINT8             BlkDesLenMsb;
 154   UINT8             BlkDesLenLsb;
 155 } USB_BOOT_MODE_SENSE10_PARA_HEADER;
 156
 157 typedef struct {
 158   UINT8             OpCode;
 159   UINT8             Lun;            ///< Lun (High 3 bits)
 160   UINT8             Lba[4];         ///< Logical block address
 161   UINT8             Reserved0;
 162   UINT8             TransferLen[2]; ///< Transfer length
 163   UINT8             Reserverd1;
 164   UINT8             Pad[2];
 165 } USB_BOOT_READ10_CMD;
 166
 167 typedef struct {
 168   UINT8             OpCode;
 169   UINT8             Lun;
 170   UINT8             Lba[4];
 171   UINT8             Reserved0;
 172   UINT8             TransferLen[2];
 173   UINT8             Reserverd1;
 174   UINT8             Pad[2];
 175 } USB_BOOT_WRITE10_CMD;
 176
 177 typedef struct {
 178   UINT8             OpCode;
 179   UINT8             Lun;            ///< Lun (High 3 bits)
 180   UINT8             Reserved0[2];
 181   UINT8             AllocLen;       ///< Allocation length
 182   UINT8             Reserved1;
 183   UINT8             Pad[6];
 184 } USB_BOOT_REQUEST_SENSE_CMD;
 185
 186 typedef struct {
 187   UINT8             ErrorCode;
 188   UINT8             Reserved0;
 189   UINT8             SenseKey;       ///< Sense key (low 4 bits)
 190   UINT8             Infor[4];
 191   UINT8             AddLen;         ///< Additional Sense length, 10
 192   UINT8             Reserved1[4];
 193   UINT8             Asc;            ///< Additional Sense Code
 194   UINT8             Ascq;           ///< Additional Sense Code Qualifier
 195   UINT8             Reserverd2[4];
 196 } USB_BOOT_REQUEST_SENSE_DATA;
 197
 198 typedef struct {
 199   UINT8             OpCode;
 200   UINT8             Lun;
 201   UINT8             PageCode;
 202   UINT8             Reserved0;
 203   UINT8             AllocateLen;
 204   UINT8             Control;
 205 } USB_SCSI_MODE_SENSE6_CMD;
 206
 207 typedef struct {
 208   UINT8             ModeDataLen;
 209   UINT8             MediumType;
 210   UINT8             DevicePara;
 211   UINT8             BlkDesLen;
 212 } USB_SCSI_MODE_SENSE6_PARA_HEADER;
 213 #pragma pack()
 214
 215 //
 216 // Convert a LUN number to that in the command
 217 //
 218 #define USB_BOOT_LUN(Lun) ((Lun) << 5)
 219
 220 //
 221 // Get the removable, PDT, and sense key bits from the command data
 222 //
 223 #define USB_BOOT_REMOVABLE(RmbByte) (((RmbByte) & BIT7) != 0)
 224 #define USB_BOOT_PDT(Pdt)           ((Pdt) & 0x1f)
 225 #define USB_BOOT_SENSE_KEY(Key)     ((Key) & 0x0f)
 226
 227 /**
 228   Get the parameters for the USB mass storage media.
 229
 230   This function get the parameters for the USB mass storage media,
 231   It is used both to initialize the media during the Start() phase
 232   of Driver Binding Protocol and to re-initialize it when the media is
 233   changed. Althought the RemoveableMedia is unlikely to change,
 234   it is also included here.
 235
 236   @param  UsbMass                The device to retrieve disk gemotric.
 237
 238   @retval EFI_SUCCESS            The disk gemotric is successfully retrieved.
 239   @retval Other                  Failed to get the parameters.
 240
 241 **/
 242 EFI_STATUS
 243 UsbBootGetParams (
 244   IN USB_MASS_DEVICE          *UsbMass
 245   );
 246
 247 /**
 248   Execute TEST UNIT READY command to check if the device is ready.
 249
 250   @param  UsbMass                The device to test
 251
 252   @retval EFI_SUCCESS            The device is ready.
 253   @retval Others                 Device not ready.
 254
 255 **/
 256 EFI_STATUS
 257 UsbBootIsUnitReady (
 258   IN USB_MASS_DEVICE          *UsbMass
 259   );
 260
 261 /**
 262   Detect whether the removable media is present and whether it has changed.
 263
 264   @param  UsbMass                The device to check.
 265
 266   @retval EFI_SUCCESS            The media status is successfully checked.
 267   @retval Other                  Failed to detect media.
 268
 269 **/
 270 EFI_STATUS
 271 UsbBootDetectMedia (
 272   IN  USB_MASS_DEVICE       *UsbMass
 273   );
 274
 275 /**
 276   Read some blocks from the device.
 277
 278   @param  UsbMass                The USB mass storage device to read from
 279   @param  Lba                    The start block number
 280   @param  TotalBlock             Total block number to read
 281   @param  Buffer                 The buffer to read to
 282
 283   @retval EFI_SUCCESS            Data are read into the buffer
 284   @retval Others                 Failed to read all the data
 285
 286 **/
 287 EFI_STATUS
 288 UsbBootReadBlocks (
 289   IN  USB_MASS_DEVICE         *UsbMass,
 290   IN  UINT32                  Lba,
 291   IN  UINTN                   TotalBlock,
 292   OUT UINT8                   *Buffer
 293   );
 294
 295 /**
 296   Write some blocks to the device.
 297
 298   @param  UsbMass                The USB mass storage device to write to
 299   @param  Lba                    The start block number
 300   @param  TotalBlock             Total block number to write
 301   @param  Buffer                 Pointer to the source buffer for the data.
 302
 303   @retval EFI_SUCCESS            Data are written into the buffer
 304   @retval Others                 Failed to write all the data
 305
 306 **/
 307 EFI_STATUS
 308 UsbBootWriteBlocks (
 309   IN  USB_MASS_DEVICE         *UsbMass,
 310   IN  UINT32                  Lba,
 311   IN  UINTN                   TotalBlock,
 312   IN  UINT8                   *Buffer
 313   );
 314
 315 /**
 316   Read some blocks from the device by SCSI 16 byte cmd.
 317
 318   @param  UsbMass                The USB mass storage device to read from
 319   @param  Lba                    The start block number
 320   @param  TotalBlock             Total block number to read
 321   @param  Buffer                 The buffer to read to
 322
 323   @retval EFI_SUCCESS            Data are read into the buffer
 324   @retval Others                 Failed to read all the data
 325
 326 **/
 327 EFI_STATUS
 328 UsbBootReadBlocks16 (
 329   IN  USB_MASS_DEVICE       *UsbMass,
 330   IN  UINT64                Lba,
 331   IN  UINTN                 TotalBlock,
 332   OUT UINT8                 *Buffer
 333   );
 334
 335 /**
 336   Write some blocks to the device by SCSI 16 byte cmd.
 337
 338   @param  UsbMass                The USB mass storage device to write to
 339   @param  Lba                    The start block number
 340   @param  TotalBlock             Total block number to write
 341   @param  Buffer                 Pointer to the source buffer for the data.
 342
 343   @retval EFI_SUCCESS            Data are written into the buffer
 344   @retval Others                 Failed to write all the data
 345
 346 **/
 347 EFI_STATUS
 348 UsbBootWriteBlocks16 (
 349   IN  USB_MASS_DEVICE         *UsbMass,
 350   IN  UINT64                  Lba,
 351   IN  UINTN                   TotalBlock,
 352   IN  UINT8                   *Buffer
 353   );
 354
 355
 356 /**
 357   Use the USB clear feature control transfer to clear the endpoint stall condition.
 358
 359   @param  UsbIo                  The USB I/O Protocol instance
 360   @param  EndpointAddr           The endpoint to clear stall for
 361
 362   @retval EFI_SUCCESS            The endpoint stall condition is cleared.
 363   @retval Others                 Failed to clear the endpoint stall condition.
 364
 365 **/
 366 EFI_STATUS
 367 UsbClearEndpointStall (
 368   IN EFI_USB_IO_PROTOCOL    *UsbIo,
 369   IN UINT8                  EndpointAddr
 370   );
 371
 372 #endif
 373