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