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_READ10_CMD;
 165
 166 typedef struct {
 167   UINT8             OpCode;
 168   UINT8             Lun;
 169   UINT8             Lba[4];
 170   UINT8             Reserved0;
 171   UINT8             TransferLen[2];
 172   UINT8             Reserverd1;
 173   UINT8             Pad[2];
 174 } USB_BOOT_WRITE10_CMD;
 175
 176 typedef struct {
 177   UINT8             OpCode;
 178   UINT8             Lun;            ///< Lun (High 3 bits)
 179   UINT8             Reserved0[2];
 180   UINT8             AllocLen;       ///< Allocation length
 181   UINT8             Reserved1;
 182   UINT8             Pad[6];
 183 } USB_BOOT_REQUEST_SENSE_CMD;
 184
 185 typedef struct {
 186   UINT8             ErrorCode;
 187   UINT8             Reserved0;
 188   UINT8             SenseKey;       ///< Sense key (low 4 bits)
 189   UINT8             Infor[4];
 190   UINT8             AddLen;         ///< Additional Sense length, 10
 191   UINT8             Reserved1[4];
 192   UINT8             Asc;            ///< Additional Sense Code
 193   UINT8             Ascq;           ///< Additional Sense Code Qualifier
 194   UINT8             Reserverd2[4];
 195 } USB_BOOT_REQUEST_SENSE_DATA;
 196
 197 typedef struct {
 198   UINT8             OpCode;
 199   UINT8             Lun;
 200   UINT8             PageCode;
 201   UINT8             Reserved0;
 202   UINT8             AllocateLen;
 203   UINT8             Control;
 204 } USB_SCSI_MODE_SENSE6_CMD;
 205
 206 typedef struct {
 207   UINT8             ModeDataLen;
 208   UINT8             MediumType;
 209   UINT8             DevicePara;
 210   UINT8             BlkDesLen;
 211 } USB_SCSI_MODE_SENSE6_PARA_HEADER;
 212 #pragma pack()
 213
 214 //
 215 // Convert a LUN number to that in the command
 216 //
 217 #define USB_BOOT_LUN(Lun) ((Lun) << 5)
 218
 219 //
 220 // Get the removable, PDT, and sense key bits from the command data
 221 //
 222 #define USB_BOOT_REMOVABLE(RmbByte) (((RmbByte) & BIT7) != 0)
 223 #define USB_BOOT_PDT(Pdt)           ((Pdt) & 0x1f)
 224 #define USB_BOOT_SENSE_KEY(Key)     ((Key) & 0x0f)
 225
 226 /**
 227   Get the parameters for the USB mass storage media.
 228
 229   This function get the parameters for the USB mass storage media,
 230   It is used both to initialize the media during the Start() phase
 231   of Driver Binding Protocol and to re-initialize it when the media is
 232   changed. Althought the RemoveableMedia is unlikely to change,
 233   it is also included here.
 234
 235   @param  UsbMass                The device to retrieve disk gemotric.
 236
 237   @retval EFI_SUCCESS            The disk gemotric is successfully retrieved.
 238   @retval Other                  Failed to get the parameters.
 239
 240 **/
 241 EFI_STATUS
 242 UsbBootGetParams (
 243   IN USB_MASS_DEVICE          *UsbMass
 244   );
 245
 246 /**
 247   Execute TEST UNIT READY command to check if the device is ready.
 248
 249   @param  UsbMass                The device to test
 250
 251   @retval EFI_SUCCESS            The device is ready.
 252   @retval Others                 Device not ready.
 253
 254 **/
 255 EFI_STATUS
 256 UsbBootIsUnitReady (
 257   IN USB_MASS_DEVICE          *UsbMass
 258   );
 259
 260 /**
 261   Detect whether the removable media is present and whether it has changed.
 262
 263   @param  UsbMass                The device to check.
 264
 265   @retval EFI_SUCCESS            The media status is successfully checked.
 266   @retval Other                  Failed to detect media.
 267
 268 **/
 269 EFI_STATUS
 270 UsbBootDetectMedia (
 271   IN  USB_MASS_DEVICE       *UsbMass
 272   );
 273
 274 /**
 275   Read some blocks from the device.
 276
 277   @param  UsbMass                The USB mass storage device to read from
 278   @param  Lba                    The start block number
 279   @param  TotalBlock             Total block number to read
 280   @param  Buffer                 The buffer to read to
 281
 282   @retval EFI_SUCCESS            Data are read into the buffer
 283   @retval Others                 Failed to read all the data
 284
 285 **/
 286 EFI_STATUS
 287 UsbBootReadBlocks (
 288   IN  USB_MASS_DEVICE         *UsbMass,
 289   IN  UINT32                  Lba,
 290   IN  UINTN                   TotalBlock,
 291   OUT UINT8                   *Buffer
 292   );
 293
 294 /**
 295   Write some blocks to the device.
 296
 297   @param  UsbMass                The USB mass storage device to write to
 298   @param  Lba                    The start block number
 299   @param  TotalBlock             Total block number to write
 300   @param  Buffer                 Pointer to the source buffer for the data.
 301
 302   @retval EFI_SUCCESS            Data are written into the buffer
 303   @retval Others                 Failed to write all the data
 304
 305 **/
 306 EFI_STATUS
 307 UsbBootWriteBlocks (
 308   IN  USB_MASS_DEVICE         *UsbMass,
 309   IN  UINT32                  Lba,
 310   IN  UINTN                   TotalBlock,
 311   IN  UINT8                   *Buffer
 312   );
 313
 314 /**
 315   Read some blocks from the device by SCSI 16 byte cmd.
 316
 317   @param  UsbMass                The USB mass storage device to read from
 318   @param  Lba                    The start block number
 319   @param  TotalBlock             Total block number to read
 320   @param  Buffer                 The buffer to read to
 321
 322   @retval EFI_SUCCESS            Data are read into the buffer
 323   @retval Others                 Failed to read all the data
 324
 325 **/
 326 EFI_STATUS
 327 UsbBootReadBlocks16 (
 328   IN  USB_MASS_DEVICE       *UsbMass,
 329   IN  UINT64                Lba,
 330   IN  UINTN                 TotalBlock,
 331   OUT UINT8                 *Buffer
 332   );
 333
 334 /**
 335   Write some blocks to the device by SCSI 16 byte cmd.
 336
 337   @param  UsbMass                The USB mass storage device to write to
 338   @param  Lba                    The start block number
 339   @param  TotalBlock             Total block number to write
 340   @param  Buffer                 Pointer to the source buffer for the data.
 341
 342   @retval EFI_SUCCESS            Data are written into the buffer
 343   @retval Others                 Failed to write all the data
 344
 345 **/
 346 EFI_STATUS
 347 UsbBootWriteBlocks16 (
 348   IN  USB_MASS_DEVICE         *UsbMass,
 349   IN  UINT64                  Lba,
 350   IN  UINTN                   TotalBlock,
 351   IN  UINT8                   *Buffer
 352   );
 353
 354
 355 /**
 356   Use the USB clear feature control transfer to clear the endpoint stall condition.
 357
 358   @param  UsbIo                  The USB I/O Protocol instance
 359   @param  EndpointAddr           The endpoint to clear stall for
 360
 361   @retval EFI_SUCCESS            The endpoint stall condition is cleared.
 362   @retval Others                 Failed to clear the endpoint stall condition.
 363
 364 **/
 365 EFI_STATUS
 366 UsbClearEndpointStall (
 367   IN EFI_USB_IO_PROTOCOL    *UsbIo,
 368   IN UINT8                  EndpointAddr
 369   );
 370
 371 #endif
 372