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