MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassBoot.h

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