3 Usb Bus Driver Binding and Bus IO Protocol.
5 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #ifndef _EFI_USB_BUS_H_
11 #define _EFI_USB_BUS_H_
16 #include <Protocol/Usb2HostController.h>
17 #include <Protocol/UsbHostController.h>
18 #include <Protocol/UsbIo.h>
19 #include <Protocol/DevicePath.h>
21 #include <Library/BaseLib.h>
22 #include <Library/DebugLib.h>
23 #include <Library/BaseMemoryLib.h>
24 #include <Library/UefiDriverEntryPoint.h>
25 #include <Library/UefiBootServicesTableLib.h>
26 #include <Library/UefiLib.h>
27 #include <Library/DevicePathLib.h>
28 #include <Library/MemoryAllocationLib.h>
29 #include <Library/ReportStatusCodeLib.h>
32 #include <IndustryStandard/Usb.h>
34 typedef struct _USB_DEVICE USB_DEVICE
;
35 typedef struct _USB_INTERFACE USB_INTERFACE
;
36 typedef struct _USB_BUS USB_BUS
;
37 typedef struct _USB_HUB_API USB_HUB_API
;
40 #include "UsbUtility.h"
43 #include "UsbEnumer.h"
46 // USB bus timeout experience values
49 #define USB_MAX_LANG_ID 16
50 #define USB_MAX_INTERFACE 16
51 #define USB_MAX_DEVICES 128
53 #define USB_BUS_1_MILLISECOND 1000
56 // Roothub and hub's polling interval, set by experience,
57 // The unit of roothub is 100us, means 100ms as interval, and
58 // the unit of hub is 1ms, means 64ms as interval.
60 #define USB_ROOTHUB_POLL_INTERVAL (100 * 10000U)
61 #define USB_HUB_POLL_INTERVAL 64
64 // Wait for port stable to work, refers to specification
67 #define USB_WAIT_PORT_STABLE_STALL (100 * USB_BUS_1_MILLISECOND)
70 // Wait for port statue reg change, set by experience
72 #define USB_WAIT_PORT_STS_CHANGE_STALL (100)
75 // Wait for set device address, refers to specification
76 // [USB20-9.2.6.3, it says 2ms]
78 #define USB_SET_DEVICE_ADDRESS_STALL (2 * USB_BUS_1_MILLISECOND)
81 // Wait for retry max packet size, set by experience
83 #define USB_RETRY_MAX_PACK_SIZE_STALL (100 * USB_BUS_1_MILLISECOND)
86 // Wait for hub port power-on, refers to specification
89 #define USB_SET_PORT_POWER_STALL (2 * USB_BUS_1_MILLISECOND)
92 // Wait for port reset, refers to specification
93 // [USB20-7.1.7.5, it says 10ms for hub and 50ms for
96 // According to USB2.0, Chapter 11.5.1.5 Resetting,
97 // the worst case for TDRST is 20ms
99 #define USB_SET_PORT_RESET_STALL (20 * USB_BUS_1_MILLISECOND)
100 #define USB_SET_ROOT_PORT_RESET_STALL (50 * USB_BUS_1_MILLISECOND)
103 // Wait for port recovery to accept SetAddress, refers to specification
104 // [USB20-7.1.7.5, it says 10 ms for TRSTRCY]
106 #define USB_SET_PORT_RECOVERY_STALL (10 * USB_BUS_1_MILLISECOND)
109 // Wait for clear roothub port reset, set by experience
111 #define USB_CLR_ROOT_PORT_RESET_STALL (20 * USB_BUS_1_MILLISECOND)
114 // Wait for set roothub port enable, set by experience
116 #define USB_SET_ROOT_PORT_ENABLE_STALL (20 * USB_BUS_1_MILLISECOND)
119 // Send general device request timeout.
121 // The USB Specification 2.0, section 11.24.1 recommends a value of
122 // 50 milliseconds. We use a value of 500 milliseconds to work
123 // around slower hubs and devices.
125 #define USB_GENERAL_DEVICE_REQUEST_TIMEOUT 500
128 // Send clear feature request timeout, set by experience
130 #define USB_CLEAR_FEATURE_REQUEST_TIMEOUT 10
133 // Bus raises TPL to TPL_NOTIFY to serialize all its operations
134 // to protect shared data structures.
136 #define USB_BUS_TPL TPL_NOTIFY
138 #define USB_INTERFACE_SIGNATURE SIGNATURE_32 ('U', 'S', 'B', 'I')
139 #define USB_BUS_SIGNATURE SIGNATURE_32 ('U', 'S', 'B', 'B')
141 #define USB_BIT(a) ((UINTN)(1 << (a)))
142 #define USB_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
144 #define USB_INTERFACE_FROM_USBIO(a) \
145 CR(a, USB_INTERFACE, UsbIo, USB_INTERFACE_SIGNATURE)
147 #define USB_BUS_FROM_THIS(a) \
148 CR(a, USB_BUS, BusId, USB_BUS_SIGNATURE)
151 // Used to locate USB_BUS
152 // UsbBusProtocol is the private protocol.
153 // gEfiCallerIdGuid will be used as its protocol guid.
155 typedef struct _EFI_USB_BUS_PROTOCOL
{
157 } EFI_USB_BUS_PROTOCOL
;
161 // Stands for the real USB device. Each device may
162 // has several separately working interfaces.
168 // Configuration information
175 // The device's descriptors and its configuration
177 USB_DEVICE_DESC
*DevDesc
;
178 USB_CONFIG_DESC
*ActiveConfig
;
180 UINT16 LangId
[USB_MAX_LANG_ID
];
183 UINT8 NumOfInterface
;
184 USB_INTERFACE
*Interfaces
[USB_MAX_INTERFACE
];
187 // Parent child relationship
189 EFI_USB2_HC_TRANSACTION_TRANSLATOR Translator
;
192 USB_INTERFACE
*ParentIf
;
193 UINT8 ParentPort
; // Start at 0
195 BOOLEAN DisconnectFail
;
199 // Stands for different functions of USB device
201 struct _USB_INTERFACE
{
204 USB_INTERFACE_DESC
*IfDesc
;
205 USB_INTERFACE_SETTING
*IfSetting
;
208 // Handles and protocols
211 EFI_USB_IO_PROTOCOL UsbIo
;
212 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
216 // Hub device special data
224 // Data used only by normal hub devices
226 USB_ENDPOINT_DESC
*HubEp
;
230 // Data used only by root hub to hand over device to
231 // companion UHCI driver if low/full speed devices are
232 // connected to EHCI.
238 // Stands for the current USB Bus
242 EFI_USB_BUS_PROTOCOL BusId
;
245 // Managed USB host controller
247 EFI_HANDLE HostHandle
;
248 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
249 EFI_USB2_HC_PROTOCOL
*Usb2Hc
;
250 EFI_USB_HC_PROTOCOL
*UsbHc
;
253 // Recorded the max supported usb devices.
254 // XHCI can support up to 255 devices.
255 // EHCI/UHCI/OHCI supports up to 127 devices.
259 // An array of device that is on the bus. Devices[0] is
260 // for root hub. Device with address i is at Devices[i].
262 USB_DEVICE
*Devices
[256];
265 // USB Bus driver need to control the recursive connect policy of the bus, only those wanted
266 // usb child device will be recursively connected.
268 // WantedUsbIoDPList tracks the Usb child devices which user want to recursively fully connecte,
269 // every wanted child device is stored in a item of the WantedUsbIoDPList, whose structure is
270 // DEVICE_PATH_LIST_ITEM
272 LIST_ENTRY WantedUsbIoDPList
;
281 USB_HUB_GET_PORT_STATUS GetPortStatus
;
282 USB_HUB_CLEAR_PORT_CHANGE ClearPortChange
;
283 USB_HUB_SET_PORT_FEATURE SetPortFeature
;
284 USB_HUB_CLEAR_PORT_FEATURE ClearPortFeature
;
285 USB_HUB_RESET_PORT ResetPort
;
286 USB_HUB_RELEASE Release
;
289 #define USB_US_LAND_ID 0x0409
291 #define DEVICE_PATH_LIST_ITEM_SIGNATURE SIGNATURE_32('d','p','l','i')
292 typedef struct _DEVICE_PATH_LIST_ITEM
{
295 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
296 } DEVICE_PATH_LIST_ITEM
;
299 USB_CLASS_DEVICE_PATH UsbClass
;
300 EFI_DEVICE_PATH_PROTOCOL End
;
301 } USB_CLASS_FORMAT_DEVICE_PATH
;
304 Free a DEVICE_PATH_LIST_ITEM list.
306 @param UsbIoDPList a DEVICE_PATH_LIST_ITEM list pointer.
308 @retval EFI_INVALID_PARAMETER If parameters are invalid, return this value.
309 @retval EFI_SUCCESS If free operation is successful, return this value.
314 UsbBusFreeUsbDPList (
315 IN LIST_ENTRY
*UsbIoDPList
319 Store a wanted usb child device info (its Usb part of device path) which is indicated by
320 RemainingDevicePath in a Usb bus which is indicated by UsbBusId.
322 @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface.
323 @param RemainingDevicePath The remaining device patch.
325 @retval EFI_SUCCESS Add operation is successful.
326 @retval EFI_INVALID_PARAMETER The parameters are invalid.
331 UsbBusAddWantedUsbIoDP (
332 IN EFI_USB_BUS_PROTOCOL
*UsbBusId
,
333 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
337 Check whether a usb child device is the wanted device in a bus.
339 @param Bus The Usb bus's private data pointer.
340 @param UsbIf The usb child device interface.
342 @retval True If a usb child device is the wanted device in a bus.
343 @retval False If a usb child device is *NOT* the wanted device in a bus.
348 UsbBusIsWantedUsbIO (
350 IN USB_INTERFACE
*UsbIf
354 Recursively connect every wanted usb child device to ensure they all fully connected.
355 Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device.
357 @param UsbBusId Point to EFI_USB_BUS_PROTOCOL interface.
359 @retval EFI_SUCCESS Connect is done successfully.
360 @retval EFI_INVALID_PARAMETER The parameter is invalid.
365 UsbBusRecursivelyConnectWantedUsbIo (
366 IN EFI_USB_BUS_PROTOCOL
*UsbBusId
370 USB_IO function to execute a control transfer. This
371 function will execute the USB transfer. If transfer
372 successes, it will sync the internal state of USB bus
375 @param This The USB_IO instance
376 @param Request The control transfer request
377 @param Direction Direction for data stage
378 @param Timeout The time to wait before timeout
379 @param Data The buffer holding the data
380 @param DataLength Then length of the data
381 @param UsbStatus USB result
383 @retval EFI_INVALID_PARAMETER The parameters are invalid
384 @retval EFI_SUCCESS The control transfer succeded.
385 @retval Others Failed to execute the transfer
390 UsbIoControlTransfer (
391 IN EFI_USB_IO_PROTOCOL
*This
,
392 IN EFI_USB_DEVICE_REQUEST
*Request
,
393 IN EFI_USB_DATA_DIRECTION Direction
,
395 IN OUT VOID
*Data OPTIONAL
,
396 IN UINTN DataLength OPTIONAL
,
397 OUT UINT32
*UsbStatus
401 Execute a bulk transfer to the device endpoint.
403 @param This The USB IO instance.
404 @param Endpoint The device endpoint.
405 @param Data The data to transfer.
406 @param DataLength The length of the data to transfer.
407 @param Timeout Time to wait before timeout.
408 @param UsbStatus The result of USB transfer.
410 @retval EFI_SUCCESS The bulk transfer is OK.
411 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
412 @retval Others Failed to execute transfer, reason returned in
419 IN EFI_USB_IO_PROTOCOL
*This
,
422 IN OUT UINTN
*DataLength
,
424 OUT UINT32
*UsbStatus
428 Execute a synchronous interrupt transfer.
430 @param This The USB IO instance.
431 @param Endpoint The device endpoint.
432 @param Data The data to transfer.
433 @param DataLength The length of the data to transfer.
434 @param Timeout Time to wait before timeout.
435 @param UsbStatus The result of USB transfer.
437 @retval EFI_SUCCESS The synchronous interrupt transfer is OK.
438 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
439 @retval Others Failed to execute transfer, reason returned in
445 UsbIoSyncInterruptTransfer (
446 IN EFI_USB_IO_PROTOCOL
*This
,
449 IN OUT UINTN
*DataLength
,
451 OUT UINT32
*UsbStatus
455 Queue a new asynchronous interrupt transfer, or remove the old
456 request if (IsNewTransfer == FALSE).
458 @param This The USB_IO instance.
459 @param Endpoint The device endpoint.
460 @param IsNewTransfer Whether this is a new request, if it's old, remove
462 @param PollInterval The interval to poll the transfer result, (in ms).
463 @param DataLength The length of perodic data transfer.
464 @param Callback The function to call periodically when transfer is
466 @param Context The context to the callback.
468 @retval EFI_SUCCESS New transfer is queued or old request is removed.
469 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
470 @retval Others Failed to queue the new request or remove the old
476 UsbIoAsyncInterruptTransfer (
477 IN EFI_USB_IO_PROTOCOL
*This
,
479 IN BOOLEAN IsNewTransfer
,
480 IN UINTN PollInterval OPTIONAL
,
481 IN UINTN DataLength OPTIONAL
,
482 IN EFI_ASYNC_USB_TRANSFER_CALLBACK Callback OPTIONAL
,
483 IN VOID
*Context OPTIONAL
487 Execute a synchronous isochronous transfer.
489 @param This The USB IO instance.
490 @param DeviceEndpoint The device endpoint.
491 @param Data The data to transfer.
492 @param DataLength The length of the data to transfer.
493 @param UsbStatus The result of USB transfer.
495 @retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported.
500 UsbIoIsochronousTransfer (
501 IN EFI_USB_IO_PROTOCOL
*This
,
502 IN UINT8 DeviceEndpoint
,
509 Queue an asynchronous isochronous transfer.
511 @param This The USB_IO instance.
512 @param DeviceEndpoint The device endpoint.
513 @param Data The data to transfer.
514 @param DataLength The length of perodic data transfer.
515 @param IsochronousCallBack The function to call periodically when transfer is
517 @param Context The context to the callback.
519 @retval EFI_UNSUPPORTED Currently isochronous transfer isn't supported.
524 UsbIoAsyncIsochronousTransfer (
525 IN EFI_USB_IO_PROTOCOL
*This
,
526 IN UINT8 DeviceEndpoint
,
529 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,
530 IN VOID
*Context OPTIONAL
534 Retrieve the device descriptor of the device.
536 @param This The USB IO instance.
537 @param Descriptor The variable to receive the device descriptor.
539 @retval EFI_SUCCESS The device descriptor is returned.
540 @retval EFI_INVALID_PARAMETER The parameter is invalid.
545 UsbIoGetDeviceDescriptor (
546 IN EFI_USB_IO_PROTOCOL
*This
,
547 OUT EFI_USB_DEVICE_DESCRIPTOR
*Descriptor
551 Return the configuration descriptor of the current active configuration.
553 @param This The USB IO instance.
554 @param Descriptor The USB configuration descriptor.
556 @retval EFI_SUCCESS The active configuration descriptor is returned.
557 @retval EFI_INVALID_PARAMETER Some parameter is invalid.
558 @retval EFI_NOT_FOUND Currently no active configuration is selected.
563 UsbIoGetActiveConfigDescriptor (
564 IN EFI_USB_IO_PROTOCOL
*This
,
565 OUT EFI_USB_CONFIG_DESCRIPTOR
*Descriptor
569 Retrieve the active interface setting descriptor for this USB IO instance.
571 @param This The USB IO instance.
572 @param Descriptor The variable to receive active interface setting.
574 @retval EFI_SUCCESS The active interface setting is returned.
575 @retval EFI_INVALID_PARAMETER Some parameter is invalid.
580 UsbIoGetInterfaceDescriptor (
581 IN EFI_USB_IO_PROTOCOL
*This
,
582 OUT EFI_USB_INTERFACE_DESCRIPTOR
*Descriptor
586 Retrieve the endpoint descriptor from this interface setting.
588 @param This The USB IO instance.
589 @param Index The index (start from zero) of the endpoint to
591 @param Descriptor The variable to receive the descriptor.
593 @retval EFI_SUCCESS The endpoint descriptor is returned.
594 @retval EFI_INVALID_PARAMETER Some parameter is invalid.
599 UsbIoGetEndpointDescriptor (
600 IN EFI_USB_IO_PROTOCOL
*This
,
602 OUT EFI_USB_ENDPOINT_DESCRIPTOR
*Descriptor
606 Retrieve the supported language ID table from the device.
608 @param This The USB IO instance.
609 @param LangIDTable The table to return the language IDs.
610 @param TableSize The size, in bytes, of the table LangIDTable.
612 @retval EFI_SUCCESS The language ID is return.
617 UsbIoGetSupportedLanguages (
618 IN EFI_USB_IO_PROTOCOL
*This
,
619 OUT UINT16
**LangIDTable
,
620 OUT UINT16
*TableSize
624 Retrieve an indexed string in the language of LangID.
626 @param This The USB IO instance.
627 @param LangID The language ID of the string to retrieve.
628 @param StringIndex The index of the string.
629 @param String The variable to receive the string.
631 @retval EFI_SUCCESS The string is returned.
632 @retval EFI_NOT_FOUND No such string existed.
637 UsbIoGetStringDescriptor (
638 IN EFI_USB_IO_PROTOCOL
*This
,
640 IN UINT8 StringIndex
,
645 Reset the device, then if that succeeds, reconfigure the
646 device with its address and current active configuration.
648 @param This The USB IO instance.
650 @retval EFI_SUCCESS The device is reset and configured.
651 @retval Others Failed to reset the device.
657 IN EFI_USB_IO_PROTOCOL
*This
661 Install Usb Bus Protocol on host controller, and start the Usb bus.
663 @param This The USB bus driver binding instance.
664 @param Controller The controller to check.
665 @param RemainingDevicePath The remaining device patch.
667 @retval EFI_SUCCESS The controller is controlled by the usb bus.
668 @retval EFI_ALREADY_STARTED The controller is already controlled by the usb bus.
669 @retval EFI_OUT_OF_RESOURCES Failed to allocate resources.
674 UsbBusBuildProtocol (
675 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
676 IN EFI_HANDLE Controller
,
677 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
681 The USB bus driver entry pointer.
683 @param ImageHandle The driver image handle.
684 @param SystemTable The system table.
686 @return EFI_SUCCESS The component name protocol is installed.
687 @return Others Failed to init the usb driver.
692 UsbBusDriverEntryPoint (
693 IN EFI_HANDLE ImageHandle
,
694 IN EFI_SYSTEM_TABLE
*SystemTable
698 Check whether USB bus driver support this device.
700 @param This The USB bus driver binding protocol.
701 @param Controller The controller handle to check.
702 @param RemainingDevicePath The remaining device path.
704 @retval EFI_SUCCESS The bus supports this controller.
705 @retval EFI_UNSUPPORTED This device isn't supported.
710 UsbBusControllerDriverSupported (
711 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
712 IN EFI_HANDLE Controller
,
713 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
717 Start to process the controller.
719 @param This The USB bus driver binding instance.
720 @param Controller The controller to check.
721 @param RemainingDevicePath The remaining device patch.
723 @retval EFI_SUCCESS The controller is controlled by the usb bus.
724 @retval EFI_ALREADY_STARTED The controller is already controlled by the usb
726 @retval EFI_OUT_OF_RESOURCES Failed to allocate resources.
731 UsbBusControllerDriverStart (
732 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
733 IN EFI_HANDLE Controller
,
734 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
738 Stop handle the controller by this USB bus driver.
740 @param This The USB bus driver binding protocol.
741 @param Controller The controller to release.
742 @param NumberOfChildren The child of USB bus that opened controller
744 @param ChildHandleBuffer The array of child handle.
746 @retval EFI_SUCCESS The controller or children are stopped.
747 @retval EFI_DEVICE_ERROR Failed to stop the driver.
752 UsbBusControllerDriverStop (
753 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
754 IN EFI_HANDLE Controller
,
755 IN UINTN NumberOfChildren
,
756 IN EFI_HANDLE
*ChildHandleBuffer
759 extern EFI_USB_IO_PROTOCOL mUsbIoProtocol
;
760 extern EFI_DRIVER_BINDING_PROTOCOL mUsbBusDriverBinding
;
761 extern EFI_COMPONENT_NAME_PROTOCOL mUsbBusComponentName
;
762 extern EFI_COMPONENT_NAME2_PROTOCOL mUsbBusComponentName2
;