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 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
  42   USB_BOOT_MODE_SENSE10_OPCODE    = 0x5A,
  43   USB_BOOT_READ_CAPACITY_OPCODE   = 0x25,
  44   USB_BOOT_TEST_UNIT_READY_OPCODE = 0x00,
  45   USB_BOOT_READ10_OPCODE          = 0x28,
  46   USB_BOOT_WRITE10_OPCODE         = 0x2A,
  47
  48   USB_SCSI_MODE_SENSE6_OPCODE     = 0x1A,
  49
  50   //
  51   // The Sense Key part of the sense data. Sense data has three levels:
  52   // Sense key, Additional Sense Code and Additional Sense Code Qualifier
  53   //
  54   USB_BOOT_SENSE_NO_SENSE         = 0x00, // No sense key
  55   USB_BOOT_SENSE_RECOVERED        = 0x01, // Last command succeed with recovery actions
  56   USB_BOOT_SENSE_NOT_READY        = 0x02, // Device not ready
  57   USB_BOOT_SNESE_MEDIUM_ERROR     = 0X03, // Failed probably because flaw in the media
  58   USB_BOOT_SENSE_HARDWARE_ERROR   = 0X04, // Non-recoverable hardware failure
  59   USB_BOOT_SENSE_ILLEGAL_REQUEST  = 0X05, // Illegal parameters in the request
  60   USB_BOOT_SENSE_UNIT_ATTENTION   = 0X06, // Removable medium may have been changed
  61   USB_BOOT_SNESE_DATA_PROTECT     = 0X07, // Write protected
  62   USB_BOOT_SENSE_BLANK_CHECK      = 0X08, // Blank/non-blank medium while reading/writing
  63   USB_BOOT_SENSE_VENDOR           = 0X09, // Vendor specific sense key
  64   USB_BOOT_SENSE_ABORTED          = 0X0B, // Command aborted by the device
  65   USB_BOOT_SENSE_VOLUME_OVERFLOW  = 0x0D, // Partition overflow
  66   USB_BOOT_SENSE_MISCOMPARE       = 0x0E, // Source data mis-match while verfying.
  67
  68   USB_BOOT_ASC_NOT_READY          = 0x04,
  69   USB_BOOT_ASC_NO_MEDIA           = 0x3A,
  70   USB_BOOT_ASC_MEDIA_CHANGE       = 0x28,
  71
  72   //
  73   // Other parameters
  74   //
  75   USB_BOOT_IO_BLOCKS              = 64,
  76
  77   //
  78   // Boot Retry times
  79   //
  80   USB_BOOT_COMMAND_RETRY          = 5,
  81   USB_BOOT_WAIT_RETRY             = 5,
  82
  83   //
  84   // Boot Stall time
  85   //
  86   USB_BOOT_UNIT_READY_STALL       = 50 * USB_MASS_STALL_1_MS,
  87
  88   //
  89   // Boot Transfer timeout
  90   //
  91   // USB2.0 Spec define the up-limit timeout 5s for all command. USB floppy,
  92   // USB CD-Rom and iPod devices are much slower than USB key when reponse
  93   // most of commands, So we set 5s as timeout here.
  94   //
  95   //
  96   USB_BOOT_GENERAL_CMD_TIMEOUT    = 5 * USB_MASS_STALL_1_S,
  97
  98   //
  99   // Supported PDT codes, or Peripheral Device Type
 100   //
 101   USB_PDT_DIRECT_ACCESS           = 0x00,       // Direct access device
 102   USB_PDT_CDROM                   = 0x05,       // CDROM
 103   USB_PDT_OPTICAL                 = 0x07,       // Non-CD optical disks
 104   USB_PDT_SIMPLE_DIRECT           = 0x0E        // Simplified direct access device
 105 };
 106
 107 //
 108 // The required commands are INQUIRY, READ CAPACITY, TEST UNIT READY,
 109 // READ10, WRITE10, and REQUEST SENSE. The BLOCK_IO protocol uses LBA
 110 // so it isn't necessary to issue MODE SENSE / READ FORMAT CAPACITY
 111 // command to retrieve the disk gemotrics.
 112 //
 113 #pragma pack(1)
 114 typedef struct {
 115   UINT8             OpCode;
 116   UINT8             Lun;            // Lun (high 3 bits)
 117   UINT8             Reserved0[2];
 118   UINT8             AllocLen;
 119   UINT8             Reserved1;
 120   UINT8             Pad[6];
 121 } USB_BOOT_INQUIRY_CMD;
 122
 123 typedef struct {
 124   UINT8             Pdt;            // Peripheral Device Type (low 5 bits)
 125   UINT8             Removable;      // Removable Media (highest bit)
 126   UINT8             Reserved0[2];
 127   UINT8             AddLen;         // Additional length
 128   UINT8             Reserved1[3];
 129   UINT8             VendorID[8];
 130   UINT8             ProductID[16];
 131   UINT8             ProductRevision[4];
 132 } USB_BOOT_INQUIRY_DATA;
 133
 134 typedef struct {
 135   UINT8             OpCode;
 136   UINT8             Lun;
 137   UINT8             Reserved0[8];
 138   UINT8             Pad[2];
 139 } USB_BOOT_READ_CAPACITY_CMD;
 140
 141 typedef struct {
 142   UINT8             LastLba[4];
 143   UINT8             BlockLen[4];
 144 } USB_BOOT_READ_CAPACITY_DATA;
 145
 146 typedef struct {
 147   UINT8             OpCode;
 148   UINT8             Lun;
 149   UINT8             Reserved[4];
 150   UINT8             Pad[6];
 151 } USB_BOOT_TEST_UNIT_READY_CMD;
 152
 153 typedef struct {
 154   UINT8             OpCode;
 155   UINT8             Lun;
 156   UINT8             PageCode;
 157   UINT8             Reserved0[4];
 158   UINT8             ParaListLenMsb;
 159   UINT8             ParaListLenLsb;
 160   UINT8             Reserved1;
 161   UINT8             Pad[2];
 162 } USB_BOOT_MODE_SENSE10_CMD;
 163
 164 typedef struct {
 165   UINT8             ModeDataLenMsb;
 166   UINT8             ModeDataLenLsb;
 167   UINT8             Reserved0[4];
 168   UINT8             BlkDesLenMsb;
 169   UINT8             BlkDesLenLsb;
 170 } USB_BOOT_MODE_SENSE10_PARA_HEADER;
 171
 172 typedef struct {
 173   UINT8             OpCode;
 174   UINT8             Lun;            // Lun (High 3 bits)
 175   UINT8             Lba[4];         // Logical block address
 176   UINT8             Reserved0;
 177   UINT8             TransferLen[2]; // Transfer length
 178   UINT8             Reserverd1;
 179   UINT8             Pad[2];
 180 } USB_BOOT_READ10_CMD;
 181
 182 typedef struct {
 183   UINT8             OpCode;
 184   UINT8             Lun;
 185   UINT8             Lba[4];
 186   UINT8             Reserved0;
 187   UINT8             TransferLen[2];
 188   UINT8             Reserverd1;
 189   UINT8             Pad[2];
 190 } USB_BOOT_WRITE10_CMD;
 191
 192 typedef struct {
 193   UINT8             OpCode;
 194   UINT8             Lun;            // Lun (High 3 bits)
 195   UINT8             Reserved0[2];
 196   UINT8             AllocLen;       // Allocation length
 197   UINT8             Reserved1;
 198   UINT8             Pad[6];
 199 } USB_BOOT_REQUEST_SENSE_CMD;
 200
 201 typedef struct {
 202   UINT8             ErrorCode;
 203   UINT8             Reserved0;
 204   UINT8             SenseKey;       // Sense key (low 4 bits)
 205   UINT8             Infor[4];
 206   UINT8             AddLen;         // Additional Sense length, 10
 207   UINT8             Reserved1[4];
 208   UINT8             ASC;            // Additional Sense Code
 209   UINT8             ASCQ;           // Additional Sense Code Qualifier
 210   UINT8             Reserverd2[4];
 211 } USB_BOOT_REQUEST_SENSE_DATA;
 212
 213 typedef struct {
 214   UINT8             OpCode;
 215   UINT8             Lun;
 216   UINT8             PageCode;
 217   UINT8             Reserved0;
 218   UINT8             AllocateLen;
 219   UINT8             Control;
 220 } USB_SCSI_MODE_SENSE6_CMD;
 221
 222 typedef struct {
 223   UINT8             ModeDataLen;
 224  UINT8             MediumType;
 225   UINT8             DevicePara;
 226   UINT8             BlkDesLen;
 227 } USB_SCSI_MODE_SENSE6_PARA_HEADER;
 228 #pragma pack()
 229
 230 //
 231 // Convert a LUN number to that in the command
 232 //
 233 #define USB_BOOT_LUN(Lun) ((Lun) << 5)
 234
 235 //
 236 // Get the removable, PDT, and sense key bits from the command data
 237 //
 238 #define USB_BOOT_REMOVABLE(RmbByte) (((RmbByte) & 0x80) != 0)
 239 #define USB_BOOT_PDT(Pdt)           ((Pdt) & 0x1f)
 240 #define USB_BOOT_SENSE_KEY(Key)     ((Key) & 0x0f)
 241
 242 //
 243 // Swap the byte sequence of a UINT32. Intel CPU uses little endian
 244 // in UEFI environment, but USB boot uses big endian.
 245 //
 246 #define USB_BOOT_SWAP32(Data32) \
 247                 ((((Data32) & 0x000000ff) << 24) | (((Data32) & 0xff000000) >> 24) | \
 248                  (((Data32) & 0x0000ff00) << 8)  | (((Data32) & 0x00ff0000) >> 8))
 249
 250 #define USB_BOOT_SWAP16(Data16) \
 251                 ((((Data16) & 0x00ff) << 8) | (((Data16) & 0xff00) >> 8))
 252
 253 EFI_STATUS
 254 UsbBootGetParams (
 255   IN USB_MASS_DEVICE          *UsbMass
 256   );
 257
 258 EFI_STATUS
 259 UsbBootIsUnitReady (
 260   IN USB_MASS_DEVICE          *UsbMass
 261   );
 262
 263 EFI_STATUS
 264 UsbBootDetectMedia (
 265   IN  USB_MASS_DEVICE       *UsbMass
 266   );
 267
 268 EFI_STATUS
 269 UsbBootReadBlocks (
 270   IN  USB_MASS_DEVICE         *UsbMass,
 271   IN  UINT32                  Lba,
 272   IN  UINTN                   TotalBlock,
 273   OUT UINT8                   *Buffer
 274   );
 275
 276 EFI_STATUS
 277 UsbBootWriteBlocks (
 278   IN  USB_MASS_DEVICE         *UsbMass,
 279   IN  UINT32                  Lba,
 280   IN  UINTN                   TotalBlock,
 281   OUT UINT8                   *Buffer
 282   );
 283 #endif
 284