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