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
  59 //
  60 // Supported PDT codes, or Peripheral Device Type
  61 //
  62 #define USB_PDT_DIRECT_ACCESS           0x00       ///< Direct access device
  63 #define USB_PDT_CDROM                   0x05       ///< CDROM
  64 #define USB_PDT_OPTICAL                 0x07       ///< Non-CD optical disks
  65 #define USB_PDT_SIMPLE_DIRECT           0x0E       ///< Simplified direct access device
  66
  67 //
  68 // Other parameters, Max carried size is 64KB.
  69 //
  70 #define USB_BOOT_MAX_CARRY_SIZE         SIZE_64KB
  71
  72 //
  73 // Retry mass command times, set by experience
  74 //
  75 #define USB_BOOT_COMMAND_RETRY          5
  76
  77 //
  78 // Wait for unit ready command, set by experience
  79 //
  80 #define USB_BOOT_RETRY_UNIT_READY_STALL (500 * USB_MASS_1_MILLISECOND)
  81
  82 //
  83 // Mass command timeout, refers to specification[USB20-9.2.6.1]
  84 //
  85 // USB2.0 Spec define the up-limit timeout 5s for all command. USB floppy,
  86 // USB CD-Rom and iPod devices are much slower than USB key when reponse
  87 // most of commands, So we set 5s as timeout here.
  88 //
  89 #define USB_BOOT_GENERAL_CMD_TIMEOUT    (5 * USB_MASS_1_SECOND)
  90
  91 //
  92 // The required commands are INQUIRY, READ CAPACITY, TEST UNIT READY,
  93 // READ10, WRITE10, and REQUEST SENSE. The BLOCK_IO protocol uses LBA
  94 // so it isn't necessary to issue MODE SENSE / READ FORMAT CAPACITY
  95 // command to retrieve the disk gemotrics.
  96 //
  97 #pragma pack(1)
  98 typedef struct {
  99   UINT8             OpCode;
 100   UINT8             Lun;            ///< Lun (high 3 bits)
 101   UINT8             Reserved0[2];
 102   UINT8             AllocLen;
 103   UINT8             Reserved1;
 104   UINT8             Pad[6];
 105 } USB_BOOT_INQUIRY_CMD;
 106
 107 typedef struct {
 108   UINT8             Pdt;            ///< Peripheral Device Type (low 5 bits)
 109   UINT8             Removable;      ///< Removable Media (highest bit)
 110   UINT8             Reserved0[2];
 111   UINT8             AddLen;         ///< Additional length
 112   UINT8             Reserved1[3];
 113   UINT8             VendorID[8];
 114   UINT8             ProductID[16];
 115   UINT8             ProductRevision[4];
 116 } USB_BOOT_INQUIRY_DATA;
 117
 118 typedef struct {
 119   UINT8             OpCode;
 120   UINT8             Lun;
 121   UINT8             Reserved0[8];
 122   UINT8             Pad[2];
 123 } USB_BOOT_READ_CAPACITY_CMD;
 124
 125 typedef struct {
 126   UINT8             LastLba[4];
 127   UINT8             BlockLen[4];
 128 } USB_BOOT_READ_CAPACITY_DATA;
 129
 130 typedef struct {
 131   UINT8             OpCode;
 132   UINT8             Lun;
 133   UINT8             Reserved[4];
 134   UINT8             Pad[6];
 135 } USB_BOOT_TEST_UNIT_READY_CMD;
 136
 137 typedef struct {
 138   UINT8             OpCode;
 139   UINT8             Lun;
 140   UINT8             PageCode;
 141   UINT8             Reserved0[4];
 142   UINT8             ParaListLenMsb;
 143   UINT8             ParaListLenLsb;
 144   UINT8             Reserved1;
 145   UINT8             Pad[2];
 146 } USB_BOOT_MODE_SENSE10_CMD;
 147
 148 typedef struct {
 149   UINT8             ModeDataLenMsb;
 150   UINT8             ModeDataLenLsb;
 151   UINT8             Reserved0[4];
 152   UINT8             BlkDesLenMsb;
 153   UINT8             BlkDesLenLsb;
 154 } USB_BOOT_MODE_SENSE10_PARA_HEADER;
 155
 156 typedef struct {
 157   UINT8             OpCode;
 158   UINT8             Lun;            ///< Lun (High 3 bits)
 159   UINT8             Lba[4];         ///< Logical block address
 160   UINT8             Reserved0;
 161   UINT8             TransferLen[2]; ///< Transfer length
 162   UINT8             Reserverd1;
 163   UINT8             Pad[2];
 164 } USB_BOOT_READ_WRITE_10_CMD;
 165
 166 typedef struct {
 167   UINT8             OpCode;
 168   UINT8             Lun;            ///< Lun (High 3 bits)
 169   UINT8             Reserved0[2];
 170   UINT8             AllocLen;       ///< Allocation length
 171   UINT8             Reserved1;
 172   UINT8             Pad[6];
 173 } USB_BOOT_REQUEST_SENSE_CMD;
 174
 175 typedef struct {
 176   UINT8             ErrorCode;
 177   UINT8             Reserved0;
 178   UINT8             SenseKey;       ///< Sense key (low 4 bits)
 179   UINT8             Infor[4];
 180   UINT8             AddLen;         ///< Additional Sense length, 10
 181   UINT8             Reserved1[4];
 182   UINT8             Asc;            ///< Additional Sense Code
 183   UINT8             Ascq;           ///< Additional Sense Code Qualifier
 184   UINT8             Reserverd2[4];
 185 } USB_BOOT_REQUEST_SENSE_DATA;
 186
 187 typedef struct {
 188   UINT8             OpCode;
 189   UINT8             Lun;
 190   UINT8             PageCode;
 191   UINT8             Reserved0;
 192   UINT8             AllocateLen;
 193   UINT8             Control;
 194 } USB_SCSI_MODE_SENSE6_CMD;
 195
 196 typedef struct {
 197   UINT8             ModeDataLen;
 198   UINT8             MediumType;
 199   UINT8             DevicePara;
 200   UINT8             BlkDesLen;
 201 } USB_SCSI_MODE_SENSE6_PARA_HEADER;
 202 #pragma pack()
 203
 204 //
 205 // Convert a LUN number to that in the command
 206 //
 207 #define USB_BOOT_LUN(Lun) ((Lun) << 5)
 208
 209 //
 210 // Get the removable, PDT, and sense key bits from the command data
 211 //
 212 #define USB_BOOT_REMOVABLE(RmbByte) (((RmbByte) & BIT7) != 0)
 213 #define USB_BOOT_PDT(Pdt)           ((Pdt) & 0x1f)
 214 #define USB_BOOT_SENSE_KEY(Key)     ((Key) & 0x0f)
 215
 216 /**
 217   Get the parameters for the USB mass storage media.
 218
 219   This function get the parameters for the USB mass storage media,
 220   It is used both to initialize the media during the Start() phase
 221   of Driver Binding Protocol and to re-initialize it when the media is
 222   changed. Althought the RemoveableMedia is unlikely to change,
 223   it is also included here.
 224
 225   @param  UsbMass                The device to retrieve disk gemotric.
 226
 227   @retval EFI_SUCCESS            The disk gemotric is successfully retrieved.
 228   @retval Other                  Failed to get the parameters.
 229
 230 **/
 231 EFI_STATUS
 232 UsbBootGetParams (
 233   IN USB_MASS_DEVICE          *UsbMass
 234   );
 235
 236 /**
 237   Execute TEST UNIT READY command to check if the device is ready.
 238
 239   @param  UsbMass                The device to test
 240
 241   @retval EFI_SUCCESS            The device is ready.
 242   @retval Others                 Device not ready.
 243
 244 **/
 245 EFI_STATUS
 246 UsbBootIsUnitReady (
 247   IN USB_MASS_DEVICE          *UsbMass
 248   );
 249
 250 /**
 251   Detect whether the removable media is present and whether it has changed.
 252
 253   @param  UsbMass                The device to check.
 254
 255   @retval EFI_SUCCESS            The media status is successfully checked.
 256   @retval Other                  Failed to detect media.
 257
 258 **/
 259 EFI_STATUS
 260 UsbBootDetectMedia (
 261   IN  USB_MASS_DEVICE       *UsbMass
 262   );
 263
 264 /**
 265   Read some blocks from the device.
 266
 267   @param  UsbMass                The USB mass storage device to read from
 268   @param  Lba                    The start block number
 269   @param  TotalBlock             Total block number to read
 270   @param  Buffer                 The buffer to read to
 271
 272   @retval EFI_SUCCESS            Data are read into the buffer
 273   @retval Others                 Failed to read all the data
 274
 275 **/
 276 EFI_STATUS
 277 UsbBootReadBlocks (
 278   IN  USB_MASS_DEVICE         *UsbMass,
 279   IN  UINT32                  Lba,
 280   IN  UINTN                   TotalBlock,
 281   OUT UINT8                   *Buffer
 282   );
 283
 284 /**
 285   Read or write some blocks from the device.
 286
 287   @param  UsbMass                The USB mass storage device to access
 288   @param  Write                  TRUE for write operation.
 289   @param  Lba                    The start block number
 290   @param  TotalBlock             Total block number to read or write
 291   @param  Buffer                 The buffer to read to or write from
 292
 293   @retval EFI_SUCCESS            Data are read into the buffer or writen into the device.
 294   @retval Others                 Failed to read or write all the data
 295
 296 **/
 297 EFI_STATUS
 298 UsbBootReadWriteBlocks (
 299   IN  USB_MASS_DEVICE       *UsbMass,
 300   IN  BOOLEAN               Write,
 301   IN  UINT32                Lba,
 302   IN  UINTN                 TotalBlock,
 303   IN OUT UINT8              *Buffer
 304   );
 305
 306 /**
 307   Read or write some blocks from the device by SCSI 16 byte cmd.
 308
 309   @param  UsbMass                The USB mass storage device to access
 310   @param  Write                  TRUE for write operation.
 311   @param  Lba                    The start block number
 312   @param  TotalBlock             Total block number to read or write
 313   @param  Buffer                 The buffer to read to or write from
 314
 315   @retval EFI_SUCCESS            Data are read into the buffer or writen into the device.
 316   @retval Others                 Failed to read or write all the data
 317 **/
 318 EFI_STATUS
 319 UsbBootReadWriteBlocks16 (
 320   IN  USB_MASS_DEVICE       *UsbMass,
 321   IN  BOOLEAN               Write,
 322   IN  UINT64                Lba,
 323   IN  UINTN                 TotalBlock,
 324   IN OUT UINT8              *Buffer
 325   );
 326
 327 /**
 328   Use the USB clear feature control transfer to clear the endpoint stall condition.
 329
 330   @param  UsbIo                  The USB I/O Protocol instance
 331   @param  EndpointAddr           The endpoint to clear stall for
 332
 333   @retval EFI_SUCCESS            The endpoint stall condition is cleared.
 334   @retval Others                 Failed to clear the endpoint stall condition.
 335
 336 **/
 337 EFI_STATUS
 338 UsbClearEndpointStall (
 339   IN EFI_USB_IO_PROTOCOL    *UsbIo,
 340   IN UINT8                  EndpointAddr
 341   );
 342
 343 #endif
 344