1 /** @file 2 EFI Usb I/O Protocol as defined in UEFI specification. 3 This protocol is used by code, typically drivers, running in the EFI 4 boot services environment to access USB devices like USB keyboards, 5 mice and mass storage devices. In particular, functions for managing devices 6 on USB buses are defined here. 7 8 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> 9 This program and the accompanying materials 10 are licensed and made available under the terms and conditions of the BSD License 11 which accompanies this distribution. The full text of the license may be found at 12 http://opensource.org/licenses/bsd-license.php 13 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 16 17 **/ 18 19 #ifndef __USB_IO_H__ 20 #define __USB_IO_H__ 21 22 FILE_LICENCE ( BSD3 ); 23 24 #include <ipxe/efi/IndustryStandard/Usb.h> 25 26 // 27 // Global ID for the USB I/O Protocol 28 // 29 #define EFI_USB_IO_PROTOCOL_GUID \ 30 { \ 31 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \ 32 } 33 34 typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL; 35 36 // 37 // Related Definition for EFI USB I/O protocol 38 // 39 40 // 41 // USB standard descriptors and reqeust 42 // 43 typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST; 44 typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR; 45 typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR; 46 typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR; 47 typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR; 48 49 /// 50 /// USB data transfer direction 51 /// 52 typedef enum { 53 EfiUsbDataIn, 54 EfiUsbDataOut, 55 EfiUsbNoData 56 } EFI_USB_DATA_DIRECTION; 57 58 // 59 // USB Transfer Results 60 // 61 #define EFI_USB_NOERROR 0x00 62 #define EFI_USB_ERR_NOTEXECUTE 0x01 63 #define EFI_USB_ERR_STALL 0x02 64 #define EFI_USB_ERR_BUFFER 0x04 65 #define EFI_USB_ERR_BABBLE 0x08 66 #define EFI_USB_ERR_NAK 0x10 67 #define EFI_USB_ERR_CRC 0x20 68 #define EFI_USB_ERR_TIMEOUT 0x40 69 #define EFI_USB_ERR_BITSTUFF 0x80 70 #define EFI_USB_ERR_SYSTEM 0x100 71 72 /** 73 Async USB transfer callback routine. 74 75 @param Data Data received or sent via the USB Asynchronous Transfer, if the 76 transfer completed successfully. 77 @param DataLength The length of Data received or sent via the Asynchronous 78 Transfer, if transfer successfully completes. 79 @param Context Data passed from UsbAsyncInterruptTransfer() request. 80 @param Status Indicates the result of the asynchronous transfer. 81 82 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed. 83 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. 84 85 **/ 86 typedef 87 EFI_STATUS 88 (EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK)( 89 IN VOID *Data, 90 IN UINTN DataLength, 91 IN VOID *Context, 92 IN UINT32 Status 93 ); 94 95 // 96 // Prototype for EFI USB I/O protocol 97 // 98 99 100 /** 101 This function is used to manage a USB device with a control transfer pipe. A control transfer is 102 typically used to perform device initialization and configuration. 103 104 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 105 @param Request A pointer to the USB device request that will be sent to the USB 106 device. 107 @param Direction Indicates the data direction. 108 @param Timeout Indicating the transfer should be completed within this time frame. 109 The units are in milliseconds. 110 @param Data A pointer to the buffer of data that will be transmitted to USB 111 device or received from USB device. 112 @param DataLength The size, in bytes, of the data buffer specified by Data. 113 @param Status A pointer to the result of the USB transfer. 114 115 @retval EFI_SUCCESS The control transfer has been successfully executed. 116 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status. 117 @retval EFI_INVALID_PARAMETE One or more parameters are invalid. 118 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 119 @retval EFI_TIMEOUT The control transfer fails due to timeout. 120 121 **/ 122 typedef 123 EFI_STATUS 124 (EFIAPI *EFI_USB_IO_CONTROL_TRANSFER)( 125 IN EFI_USB_IO_PROTOCOL *This, 126 IN EFI_USB_DEVICE_REQUEST *Request, 127 IN EFI_USB_DATA_DIRECTION Direction, 128 IN UINT32 Timeout, 129 IN OUT VOID *Data OPTIONAL, 130 IN UINTN DataLength OPTIONAL, 131 OUT UINT32 *Status 132 ); 133 134 /** 135 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are 136 typically used to transfer large amounts of data to/from USB devices. 137 138 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 139 @param DeviceEndpoint The destination USB device endpoint to which the 140 device request is being sent. DeviceEndpoint must 141 be between 0x01 and 0x0F or between 0x81 and 0x8F, 142 otherwise EFI_INVALID_PARAMETER is returned. If 143 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 144 is returned. The MSB of this parameter indicates 145 the endpoint direction. The number "1" stands for 146 an IN endpoint, and "0" stands for an OUT endpoint. 147 @param Data A pointer to the buffer of data that will be transmitted to USB 148 device or received from USB device. 149 @param DataLength The size, in bytes, of the data buffer specified by Data. 150 On input, the size, in bytes, of the data buffer specified by Data. 151 On output, the number of bytes that were actually transferred. 152 @param Timeout Indicating the transfer should be completed within this time frame. 153 The units are in milliseconds. If Timeout is 0, then the 154 caller must wait for the function to be completed until 155 EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 156 @param Status This parameter indicates the USB transfer status. 157 158 @retval EFI_SUCCESS The bulk transfer has been successfully executed. 159 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status. 160 @retval EFI_INVALID_PARAMETE One or more parameters are invalid. 161 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. 162 @retval EFI_TIMEOUT The control transfer fails due to timeout. 163 164 **/ 165 typedef 166 EFI_STATUS 167 (EFIAPI *EFI_USB_IO_BULK_TRANSFER)( 168 IN EFI_USB_IO_PROTOCOL *This, 169 IN UINT8 DeviceEndpoint, 170 IN OUT VOID *Data, 171 IN OUT UINTN *DataLength, 172 IN UINTN Timeout, 173 OUT UINT32 *Status 174 ); 175 176 /** 177 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous 178 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example, 179 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at 180 a fixed rate. 181 182 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 183 @param DeviceEndpoint The destination USB device endpoint to which the 184 device request is being sent. DeviceEndpoint must 185 be between 0x01 and 0x0F or between 0x81 and 0x8F, 186 otherwise EFI_INVALID_PARAMETER is returned. If 187 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 188 is returned. The MSB of this parameter indicates 189 the endpoint direction. The number "1" stands for 190 an IN endpoint, and "0" stands for an OUT endpoint. 191 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If 192 FALSE, the interrupt transfer is deleted from the device's interrupt 193 transfer queue. 194 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be 195 executed.This parameter is required when IsNewTransfer is TRUE. The 196 value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned. 197 The units are in milliseconds. 198 @param DataLength Specifies the length, in bytes, of the data to be received from the 199 USB device. This parameter is only required when IsNewTransfer is TRUE. 200 @param InterruptCallback The Callback function. This function is called if the asynchronous 201 interrupt transfer is completed. This parameter is required 202 when IsNewTransfer is TRUE. 203 @param Context Data passed to the InterruptCallback function. This is an optional 204 parameter and may be NULL. 205 206 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed. 207 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. 208 209 **/ 210 typedef 211 EFI_STATUS 212 (EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER)( 213 IN EFI_USB_IO_PROTOCOL *This, 214 IN UINT8 DeviceEndpoint, 215 IN BOOLEAN IsNewTransfer, 216 IN UINTN PollingInterval OPTIONAL, 217 IN UINTN DataLength OPTIONAL, 218 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL, 219 IN VOID *Context OPTIONAL 220 ); 221 222 /** 223 This function is used to manage a USB device with an interrupt transfer pipe. 224 225 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 226 @param DeviceEndpoint The destination USB device endpoint to which the 227 device request is being sent. DeviceEndpoint must 228 be between 0x01 and 0x0F or between 0x81 and 0x8F, 229 otherwise EFI_INVALID_PARAMETER is returned. If 230 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 231 is returned. The MSB of this parameter indicates 232 the endpoint direction. The number "1" stands for 233 an IN endpoint, and "0" stands for an OUT endpoint. 234 @param Data A pointer to the buffer of data that will be transmitted to USB 235 device or received from USB device. 236 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the 237 amount of data actually transferred. 238 @param Timeout The time out, in seconds, for this transfer. If Timeout is 0, 239 then the caller must wait for the function to be completed 240 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the 241 transfer is not completed in this time frame, then EFI_TIMEOUT is returned. 242 @param Status This parameter indicates the USB transfer status. 243 244 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed. 245 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 246 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed. 247 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. 248 @retval EFI_TIMEOUT The transfer fails due to timeout. 249 **/ 250 typedef 251 EFI_STATUS 252 (EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER)( 253 IN EFI_USB_IO_PROTOCOL *This, 254 IN UINT8 DeviceEndpoint, 255 IN OUT VOID *Data, 256 IN OUT UINTN *DataLength, 257 IN UINTN Timeout, 258 OUT UINT32 *Status 259 ); 260 261 /** 262 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous 263 transfer is typically used to transfer streaming data. 264 265 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 266 @param DeviceEndpoint The destination USB device endpoint to which the 267 device request is being sent. DeviceEndpoint must 268 be between 0x01 and 0x0F or between 0x81 and 0x8F, 269 otherwise EFI_INVALID_PARAMETER is returned. If 270 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 271 is returned. The MSB of this parameter indicates 272 the endpoint direction. The number "1" stands for 273 an IN endpoint, and "0" stands for an OUT endpoint. 274 @param Data A pointer to the buffer of data that will be transmitted to USB 275 device or received from USB device. 276 @param DataLength The size, in bytes, of the data buffer specified by Data. 277 @param Status This parameter indicates the USB transfer status. 278 279 @retval EFI_SUCCESS The isochronous transfer has been successfully executed. 280 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid. 281 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status 282 is returned in Status. 283 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. 284 @retval EFI_TIMEOUT The transfer fails due to timeout. 285 **/ 286 typedef 287 EFI_STATUS 288 (EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER)( 289 IN EFI_USB_IO_PROTOCOL *This, 290 IN UINT8 DeviceEndpoint, 291 IN OUT VOID *Data, 292 IN UINTN DataLength, 293 OUT UINT32 *Status 294 ); 295 296 /** 297 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous 298 transfer is typically used to transfer streaming data. 299 300 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 301 @param DeviceEndpoint The destination USB device endpoint to which the 302 device request is being sent. DeviceEndpoint must 303 be between 0x01 and 0x0F or between 0x81 and 0x8F, 304 otherwise EFI_INVALID_PARAMETER is returned. If 305 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER 306 is returned. The MSB of this parameter indicates 307 the endpoint direction. The number "1" stands for 308 an IN endpoint, and "0" stands for an OUT endpoint. 309 @param Data A pointer to the buffer of data that will be transmitted to USB 310 device or received from USB device. 311 @param DataLength The size, in bytes, of the data buffer specified by Data. 312 This is an optional parameter and may be NULL. 313 @param IsochronousCallback The IsochronousCallback() function.This function is 314 called if the requested isochronous transfer is completed. 315 @param Context Data passed to the IsochronousCallback() function. 316 317 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted 318 to the system. 319 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid. 320 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources. 321 322 **/ 323 typedef 324 EFI_STATUS 325 (EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER)( 326 IN EFI_USB_IO_PROTOCOL *This, 327 IN UINT8 DeviceEndpoint, 328 IN OUT VOID *Data, 329 IN UINTN DataLength, 330 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, 331 IN VOID *Context OPTIONAL 332 ); 333 334 /** 335 Resets and reconfigures the USB controller. This function will work for all USB devices except 336 USB Hub Controllers. 337 338 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 339 340 @retval EFI_SUCCESS The USB controller was reset. 341 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub. 342 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process. 343 344 **/ 345 typedef 346 EFI_STATUS 347 (EFIAPI *EFI_USB_IO_PORT_RESET)( 348 IN EFI_USB_IO_PROTOCOL *This 349 ); 350 351 /** 352 Retrieves the USB Device Descriptor. 353 354 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 355 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor. 356 357 @retval EFI_SUCCESS The device descriptor was retrieved successfully. 358 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL. 359 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured. 360 361 **/ 362 typedef 363 EFI_STATUS 364 (EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR)( 365 IN EFI_USB_IO_PROTOCOL *This, 366 OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor 367 ); 368 369 /** 370 Retrieves the USB Device Descriptor. 371 372 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 373 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration 374 Descriptor. 375 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully. 376 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL. 377 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not 378 be configured. 379 380 **/ 381 typedef 382 EFI_STATUS 383 (EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR)( 384 IN EFI_USB_IO_PROTOCOL *This, 385 OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor 386 ); 387 388 /** 389 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface 390 within a USB device is equivalently to a USB Controller within the current configuration. 391 392 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 393 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within 394 the configuration setting. 395 @retval EFI_SUCCESS The interface descriptor retrieved successfully. 396 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL. 397 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be 398 correctly configured. 399 400 **/ 401 typedef 402 EFI_STATUS 403 (EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR)( 404 IN EFI_USB_IO_PROTOCOL *This, 405 OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor 406 ); 407 408 /** 409 Retrieves an Endpoint Descriptor within a USB Controller. 410 411 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 412 @param EndpointIndex Indicates which endpoint descriptor to retrieve. 413 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of 414 a USB controller. 415 416 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully. 417 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 418 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be 419 correctly configured. 420 421 **/ 422 typedef 423 EFI_STATUS 424 (EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR)( 425 IN EFI_USB_IO_PROTOCOL *This, 426 IN UINT8 EndpointIndex, 427 OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor 428 ); 429 430 /** 431 Retrieves a string stored in a USB Device. 432 433 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 434 @param LangID The Language ID for the string being retrieved. 435 @param StringID The ID of the string being retrieved. 436 @param String A pointer to a buffer allocated by this function with 437 AllocatePool() to store the string.If this function 438 returns EFI_SUCCESS, it stores the string the caller 439 wants to get. The caller should release the string 440 buffer with FreePool() after the string is not used any more. 441 442 @retval EFI_SUCCESS The string was retrieved successfully. 443 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found. 444 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String. 445 446 **/ 447 typedef 448 EFI_STATUS 449 (EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR)( 450 IN EFI_USB_IO_PROTOCOL *This, 451 IN UINT16 LangID, 452 IN UINT8 StringID, 453 OUT CHAR16 **String 454 ); 455 456 /** 457 Retrieves all the language ID codes that the USB device supports. 458 459 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. 460 @param LangIDTable Language ID for the string the caller wants to get. 461 This is a 16-bit ID defined by Microsoft. This 462 buffer pointer is allocated and maintained by 463 the USB Bus Driver, the caller should not modify 464 its contents. 465 @param TableSize The size, in bytes, of the table LangIDTable. 466 467 @retval EFI_SUCCESS The support languages were retrieved successfully. 468 469 **/ 470 typedef 471 EFI_STATUS 472 (EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE)( 473 IN EFI_USB_IO_PROTOCOL *This, 474 OUT UINT16 **LangIDTable, 475 OUT UINT16 *TableSize 476 ); 477 478 /// 479 /// The EFI_USB_IO_PROTOCOL provides four basic transfers types described 480 /// in the USB 1.1 Specification. These include control transfer, interrupt 481 /// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL 482 /// also provides some basic USB device/controller management and configuration 483 /// interfaces. A USB device driver uses the services of this protocol to manage USB devices. 484 /// 485 struct _EFI_USB_IO_PROTOCOL { 486 // 487 // IO transfer 488 // 489 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer; 490 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer; 491 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer; 492 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer; 493 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer; 494 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer; 495 496 // 497 // Common device request 498 // 499 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor; 500 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor; 501 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor; 502 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor; 503 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor; 504 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages; 505 506 // 507 // Reset controller's parent port 508 // 509 EFI_USB_IO_PORT_RESET UsbPortReset; 510 }; 511 512 extern EFI_GUID gEfiUsbIoProtocolGuid; 513 514 #endif 515