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