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