1 /** @file 2 Definition of the command set of USB Mass Storage Specification 3 for Bootability, Revision 1.0. 4 5 Copyright (c) 2007 - 2012, 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_NOT_READY 0x04 55 #define USB_BOOT_ASC_NO_MEDIA 0x3A 56 #define USB_BOOT_ASC_MEDIA_CHANGE 0x28 57 58 // 59 // Supported PDT codes, or Peripheral Device Type 60 // 61 #define USB_PDT_DIRECT_ACCESS 0x00 ///< Direct access device 62 #define USB_PDT_CDROM 0x05 ///< CDROM 63 #define USB_PDT_OPTICAL 0x07 ///< Non-CD optical disks 64 #define USB_PDT_SIMPLE_DIRECT 0x0E ///< Simplified direct access device 65 66 // 67 // Other parameters, Max carried size is 512B * 128 = 64KB 68 // 69 #define USB_BOOT_IO_BLOCKS 128 70 71 // 72 // Retry mass command times, set by experience 73 // 74 #define USB_BOOT_COMMAND_RETRY 5 75 76 // 77 // Wait for unit ready command, set by experience 78 // 79 #define USB_BOOT_RETRY_UNIT_READY_STALL (500 * USB_MASS_1_MILLISECOND) 80 81 // 82 // Mass command timeout, refers to specification[USB20-9.2.6.1] 83 // 84 // USB2.0 Spec define the up-limit timeout 5s for all command. USB floppy, 85 // USB CD-Rom and iPod devices are much slower than USB key when reponse 86 // most of commands, So we set 5s as timeout here. 87 // 88 #define USB_BOOT_GENERAL_CMD_TIMEOUT (5 * USB_MASS_1_SECOND) 89 90 // 91 // The required commands are INQUIRY, READ CAPACITY, TEST UNIT READY, 92 // READ10, WRITE10, and REQUEST SENSE. The BLOCK_IO protocol uses LBA 93 // so it isn't necessary to issue MODE SENSE / READ FORMAT CAPACITY 94 // command to retrieve the disk gemotrics. 95 // 96 #pragma pack(1) 97 typedef struct { 98 UINT8 OpCode; 99 UINT8 Lun; ///< Lun (high 3 bits) 100 UINT8 Reserved0[2]; 101 UINT8 AllocLen; 102 UINT8 Reserved1; 103 UINT8 Pad[6]; 104 } USB_BOOT_INQUIRY_CMD; 105 106 typedef struct { 107 UINT8 Pdt; ///< Peripheral Device Type (low 5 bits) 108 UINT8 Removable; ///< Removable Media (highest bit) 109 UINT8 Reserved0[2]; 110 UINT8 AddLen; ///< Additional length 111 UINT8 Reserved1[3]; 112 UINT8 VendorID[8]; 113 UINT8 ProductID[16]; 114 UINT8 ProductRevision[4]; 115 } USB_BOOT_INQUIRY_DATA; 116 117 typedef struct { 118 UINT8 OpCode; 119 UINT8 Lun; 120 UINT8 Reserved0[8]; 121 UINT8 Pad[2]; 122 } USB_BOOT_READ_CAPACITY_CMD; 123 124 typedef struct { 125 UINT8 LastLba[4]; 126 UINT8 BlockLen[4]; 127 } USB_BOOT_READ_CAPACITY_DATA; 128 129 typedef struct { 130 UINT8 OpCode; 131 UINT8 Lun; 132 UINT8 Reserved[4]; 133 UINT8 Pad[6]; 134 } USB_BOOT_TEST_UNIT_READY_CMD; 135 136 typedef struct { 137 UINT8 OpCode; 138 UINT8 Lun; 139 UINT8 PageCode; 140 UINT8 Reserved0[4]; 141 UINT8 ParaListLenMsb; 142 UINT8 ParaListLenLsb; 143 UINT8 Reserved1; 144 UINT8 Pad[2]; 145 } USB_BOOT_MODE_SENSE10_CMD; 146 147 typedef struct { 148 UINT8 ModeDataLenMsb; 149 UINT8 ModeDataLenLsb; 150 UINT8 Reserved0[4]; 151 UINT8 BlkDesLenMsb; 152 UINT8 BlkDesLenLsb; 153 } USB_BOOT_MODE_SENSE10_PARA_HEADER; 154 155 typedef struct { 156 UINT8 OpCode; 157 UINT8 Lun; ///< Lun (High 3 bits) 158 UINT8 Lba[4]; ///< Logical block address 159 UINT8 Reserved0; 160 UINT8 TransferLen[2]; ///< Transfer length 161 UINT8 Reserverd1; 162 UINT8 Pad[2]; 163 } USB_BOOT_READ10_CMD; 164 165 typedef struct { 166 UINT8 OpCode; 167 UINT8 Lun; 168 UINT8 Lba[4]; 169 UINT8 Reserved0; 170 UINT8 TransferLen[2]; 171 UINT8 Reserverd1; 172 UINT8 Pad[2]; 173 } USB_BOOT_WRITE10_CMD; 174 175 typedef struct { 176 UINT8 OpCode; 177 UINT8 Lun; ///< Lun (High 3 bits) 178 UINT8 Reserved0[2]; 179 UINT8 AllocLen; ///< Allocation length 180 UINT8 Reserved1; 181 UINT8 Pad[6]; 182 } USB_BOOT_REQUEST_SENSE_CMD; 183 184 typedef struct { 185 UINT8 ErrorCode; 186 UINT8 Reserved0; 187 UINT8 SenseKey; ///< Sense key (low 4 bits) 188 UINT8 Infor[4]; 189 UINT8 AddLen; ///< Additional Sense length, 10 190 UINT8 Reserved1[4]; 191 UINT8 Asc; ///< Additional Sense Code 192 UINT8 Ascq; ///< Additional Sense Code Qualifier 193 UINT8 Reserverd2[4]; 194 } USB_BOOT_REQUEST_SENSE_DATA; 195 196 typedef struct { 197 UINT8 OpCode; 198 UINT8 Lun; 199 UINT8 PageCode; 200 UINT8 Reserved0; 201 UINT8 AllocateLen; 202 UINT8 Control; 203 } USB_SCSI_MODE_SENSE6_CMD; 204 205 typedef struct { 206 UINT8 ModeDataLen; 207 UINT8 MediumType; 208 UINT8 DevicePara; 209 UINT8 BlkDesLen; 210 } USB_SCSI_MODE_SENSE6_PARA_HEADER; 211 #pragma pack() 212 213 // 214 // Convert a LUN number to that in the command 215 // 216 #define USB_BOOT_LUN(Lun) ((Lun) << 5) 217 218 // 219 // Get the removable, PDT, and sense key bits from the command data 220 // 221 #define USB_BOOT_REMOVABLE(RmbByte) (((RmbByte) & BIT7) != 0) 222 #define USB_BOOT_PDT(Pdt) ((Pdt) & 0x1f) 223 #define USB_BOOT_SENSE_KEY(Key) ((Key) & 0x0f) 224 225 /** 226 Get the parameters for the USB mass storage media. 227 228 This function get the parameters for the USB mass storage media, 229 It is used both to initialize the media during the Start() phase 230 of Driver Binding Protocol and to re-initialize it when the media is 231 changed. Althought the RemoveableMedia is unlikely to change, 232 it is also included here. 233 234 @param UsbMass The device to retrieve disk gemotric. 235 236 @retval EFI_SUCCESS The disk gemotric is successfully retrieved. 237 @retval Other Failed to get the parameters. 238 239 **/ 240 EFI_STATUS 241 UsbBootGetParams ( 242 IN USB_MASS_DEVICE *UsbMass 243 ); 244 245 /** 246 Execute TEST UNIT READY command to check if the device is ready. 247 248 @param UsbMass The device to test 249 250 @retval EFI_SUCCESS The device is ready. 251 @retval Others Device not ready. 252 253 **/ 254 EFI_STATUS 255 UsbBootIsUnitReady ( 256 IN USB_MASS_DEVICE *UsbMass 257 ); 258 259 /** 260 Detect whether the removable media is present and whether it has changed. 261 262 @param UsbMass The device to check. 263 264 @retval EFI_SUCCESS The media status is successfully checked. 265 @retval Other Failed to detect media. 266 267 **/ 268 EFI_STATUS 269 UsbBootDetectMedia ( 270 IN USB_MASS_DEVICE *UsbMass 271 ); 272 273 /** 274 Read some blocks from the device. 275 276 @param UsbMass The USB mass storage device to read from 277 @param Lba The start block number 278 @param TotalBlock Total block number to read 279 @param Buffer The buffer to read to 280 281 @retval EFI_SUCCESS Data are read into the buffer 282 @retval Others Failed to read all the data 283 284 **/ 285 EFI_STATUS 286 UsbBootReadBlocks ( 287 IN USB_MASS_DEVICE *UsbMass, 288 IN UINT32 Lba, 289 IN UINTN TotalBlock, 290 OUT UINT8 *Buffer 291 ); 292 293 /** 294 Write some blocks to the device. 295 296 @param UsbMass The USB mass storage device to write to 297 @param Lba The start block number 298 @param TotalBlock Total block number to write 299 @param Buffer Pointer to the source buffer for the data. 300 301 @retval EFI_SUCCESS Data are written into the buffer 302 @retval Others Failed to write all the data 303 304 **/ 305 EFI_STATUS 306 UsbBootWriteBlocks ( 307 IN USB_MASS_DEVICE *UsbMass, 308 IN UINT32 Lba, 309 IN UINTN TotalBlock, 310 IN UINT8 *Buffer 311 ); 312 313 /** 314 Read some blocks from the device by SCSI 16 byte cmd. 315 316 @param UsbMass The USB mass storage device to read from 317 @param Lba The start block number 318 @param TotalBlock Total block number to read 319 @param Buffer The buffer to read to 320 321 @retval EFI_SUCCESS Data are read into the buffer 322 @retval Others Failed to read all the data 323 324 **/ 325 EFI_STATUS 326 UsbBootReadBlocks16 ( 327 IN USB_MASS_DEVICE *UsbMass, 328 IN UINT64 Lba, 329 IN UINTN TotalBlock, 330 OUT UINT8 *Buffer 331 ); 332 333 /** 334 Write some blocks to the device by SCSI 16 byte cmd. 335 336 @param UsbMass The USB mass storage device to write to 337 @param Lba The start block number 338 @param TotalBlock Total block number to write 339 @param Buffer Pointer to the source buffer for the data. 340 341 @retval EFI_SUCCESS Data are written into the buffer 342 @retval Others Failed to write all the data 343 344 **/ 345 EFI_STATUS 346 UsbBootWriteBlocks16 ( 347 IN USB_MASS_DEVICE *UsbMass, 348 IN UINT64 Lba, 349 IN UINTN TotalBlock, 350 IN UINT8 *Buffer 351 ); 352 353 354 /** 355 Use the USB clear feature control transfer to clear the endpoint stall condition. 356 357 @param UsbIo The USB I/O Protocol instance 358 @param EndpointAddr The endpoint to clear stall for 359 360 @retval EFI_SUCCESS The endpoint stall condition is cleared. 361 @retval Others Failed to clear the endpoint stall condition. 362 363 **/ 364 EFI_STATUS 365 UsbClearEndpointStall ( 366 IN EFI_USB_IO_PROTOCOL *UsbIo, 367 IN UINT8 EndpointAddr 368 ); 369 370 #endif 371 372