3 Provides some data structure definitions used by the XHCI host controller driver.
5 Copyright (c) 2011, 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
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.
21 #include <Protocol/Usb2HostController.h>
22 #include <Protocol/PciIo.h>
24 #include <Guid/EventGroup.h>
26 #include <Library/BaseLib.h>
27 #include <Library/BaseMemoryLib.h>
28 #include <Library/UefiDriverEntryPoint.h>
29 #include <Library/UefiBootServicesTableLib.h>
30 #include <Library/MemoryAllocationLib.h>
31 #include <Library/UefiLib.h>
32 #include <Library/DebugLib.h>
34 #include <IndustryStandard/Pci.h>
36 typedef struct _USB_XHCI_INSTANCE USB_XHCI_INSTANCE
;
37 typedef struct _USB_DEV_CONTEXT USB_DEV_CONTEXT
;
40 #include "XhciSched.h"
41 #include "ComponentName.h"
44 // Convert millisecond to microsecond.
46 #define XHC_1_MILLISECOND (1000)
48 // XHC generic timeout experience values.
49 // The unit is microsecond, setting it as 10ms.
51 #define XHC_GENERIC_TIMEOUT (10 * 1000)
53 // XHC reset timeout experience values.
54 // The unit is microsecond, setting it as 1s.
56 #define XHC_RESET_TIMEOUT (1000 * 1000)
58 // XHC delay experience value for polling operation.
59 // The unit is microsecond, set it as 1ms.
61 #define XHC_POLL_DELAY (1000)
63 // XHC async transfer timer interval, set by experience.
64 // The unit is 100us, takes 50ms as interval.
66 #define XHC_ASYNC_TIMER_INTERVAL EFI_TIMER_PERIOD_MILLISECONDS(50)
69 // XHC raises TPL to TPL_NOTIFY to serialize all its operations
70 // to protect shared data structures.
72 #define XHC_TPL TPL_NOTIFY
74 #define CMD_RING_TRB_NUMBER 0x40
75 #define TR_RING_TRB_NUMBER 0x40
76 #define ERST_NUMBER 0x01
77 #define EVENT_RING_TRB_NUMBER 0x80
83 #define INT_INTER_ASYNC 4
86 // Iterate through the doule linked list. This is delete-safe.
87 // Don't touch NextEntry
89 #define EFI_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
90 for (Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
91 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
93 #define EFI_LIST_CONTAINER(Entry, Type, Field) BASE_CR(Entry, Type, Field)
95 #define XHC_LOW_32BIT(Addr64) ((UINT32)(((UINTN)(Addr64)) & 0xFFFFFFFF))
96 #define XHC_HIGH_32BIT(Addr64) ((UINT32)(RShiftU64((UINTN)(Addr64), 32) & 0xFFFFFFFF))
97 #define XHC_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
99 #define XHC_REG_BIT_IS_SET(Xhc, Offset, Bit) \
100 (XHC_BIT_IS_SET(XhcReadOpReg ((Xhc), (Offset)), (Bit)))
102 #define XHCI_IS_DATAIN(EndpointAddr) XHC_BIT_IS_SET((EndpointAddr), 0x80)
104 #define XHCI_INSTANCE_SIG SIGNATURE_32 ('x', 'h', 'c', 'i')
105 #define XHC_FROM_THIS(a) CR(a, USB_XHCI_INSTANCE, Usb2Hc, XHCI_INSTANCE_SIG)
107 #define USB_DESC_TYPE_HUB 0x29
108 #define USB_DESC_TYPE_HUB_SUPER_SPEED 0x2a
111 // The RequestType in EFI_USB_DEVICE_REQUEST is composed of
112 // three fields: One bit direction, 2 bit type, and 5 bit
115 #define USB_REQUEST_TYPE(Dir, Type, Target) \
116 ((UINT8)((((Dir) == EfiUsbDataIn ? 0x01 : 0) << 7) | (Type) | (Target)))
119 // Xhci Data and Ctrl Structures
134 UINT8 HubContrCurrent
;
136 } EFI_USB_HUB_DESCRIPTOR
;
139 struct _USB_DEV_CONTEXT
{
141 // Whether this entry in UsbDevContext array is used or not.
145 // The slot id assigned to the new device through XHCI's Enable_Slot cmd.
149 // The route string presented an attached usb device.
151 USB_DEV_ROUTE RouteString
;
153 // The route string of parent device if it exists. Otherwise it's zero.
155 USB_DEV_ROUTE ParentRouteString
;
157 // The actual device address assigned by XHCI through Address_Device command.
161 // The requested device address from UsbBus driver through Set_Address standard usb request.
162 // As XHCI spec replaces this request with Address_Device command, we have to record the
163 // requested device address and establish a mapping relationship with the actual device address.
164 // Then UsbBus driver just need to be aware of the requested device address to access usb device
165 // through EFI_USB2_HC_PROTOCOL. Xhci driver would be responsible for translating it to actual
166 // device address and access the actual device.
170 // The pointer to the input device context.
174 // The pointer to the output device context.
178 // The transfer queue for every endpoint.
180 VOID
*EndpointTransferRing
[31];
182 // The device descriptor which is stored to support XHCI's Evaluate_Context cmd.
184 EFI_USB_DEVICE_DESCRIPTOR DevDesc
;
186 // As a usb device may include multiple configuration descriptors, we dynamically allocate an array
188 // Note that every configuration descriptor stored here includes those lower level descriptors,
189 // such as Interface descriptor, Endpoint descriptor, and so on.
190 // These information is used to support XHCI's Config_Endpoint cmd.
192 EFI_USB_CONFIG_DESCRIPTOR
**ConfDesc
;
195 struct _USB_XHCI_INSTANCE
{
197 EFI_PCI_IO_PROTOCOL
*PciIo
;
198 UINT64 OriginalPciAttributes
;
200 EFI_USB2_HC_PROTOCOL Usb2Hc
;
202 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
205 // ExitBootServicesEvent is used to set OS semaphore and
206 // stop the XHC DMA operation after exit boot service.
208 EFI_EVENT ExitBootServiceEvent
;
210 LIST_ENTRY AsyncIntTransfers
;
212 UINT8 CapLength
; ///< Capability Register Length
213 XHC_HCSPARAMS1 HcSParams1
; ///< Structural Parameters 1
214 XHC_HCSPARAMS2 HcSParams2
; ///< Structural Parameters 2
215 XHC_HCCPARAMS HcCParams
; ///< Capability Parameters
216 UINT32 DBOff
; ///< Doorbell Offset
217 UINT32 RTSOff
; ///< Runtime Register Space Offset
221 UINT32 MaxScratchpadBufs
;
222 UINT32 ExtCapRegBase
;
223 UINT32 UsbLegSupOffset
;
229 TRANSFER_RING CmdRing
;
233 EVENT_RING CmdEventRing
;
235 // ControlTREventRing
237 EVENT_RING CtrlTrEventRing
;
241 EVENT_RING BulkTrEventRing
;
245 EVENT_RING IntTrEventRing
;
247 // AsyncIntTREventRing
249 EVENT_RING AsynIntTrEventRing
;
253 EFI_UNICODE_STRING_TABLE
*ControllerNameTable
;
256 // Store device contexts managed by XHCI instance
257 // The array supports up to 255 devices, entry 0 is reserved and should not be used.
259 USB_DEV_CONTEXT UsbDevContext
[256];
263 extern EFI_DRIVER_BINDING_PROTOCOL gXhciDriverBinding
;
264 extern EFI_COMPONENT_NAME_PROTOCOL gXhciComponentName
;
265 extern EFI_COMPONENT_NAME2_PROTOCOL gXhciComponentName2
;
268 Test to see if this driver supports ControllerHandle. Any
269 ControllerHandle that has Usb2HcProtocol installed will
272 @param This Protocol instance pointer.
273 @param Controller Handle of device to test.
274 @param RemainingDevicePath Not used.
276 @return EFI_SUCCESS This driver supports this device.
277 @return EFI_UNSUPPORTED This driver does not support this device.
282 XhcDriverBindingSupported (
283 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
284 IN EFI_HANDLE Controller
,
285 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
289 Starting the Usb XHCI Driver.
291 @param This Protocol instance pointer.
292 @param Controller Handle of device to test.
293 @param RemainingDevicePath Not used.
295 @return EFI_SUCCESS supports this device.
296 @return EFI_UNSUPPORTED do not support this device.
297 @return EFI_DEVICE_ERROR cannot be started due to device Error.
298 @return EFI_OUT_OF_RESOURCES cannot allocate resources.
303 XhcDriverBindingStart (
304 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
305 IN EFI_HANDLE Controller
,
306 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
310 Stop this driver on ControllerHandle. Support stoping any child handles
311 created by this driver.
313 @param This Protocol instance pointer.
314 @param Controller Handle of device to stop driver on.
315 @param NumberOfChildren Number of Children in the ChildHandleBuffer.
316 @param ChildHandleBuffer List of handles for the children we need to stop.
318 @return EFI_SUCCESS Success.
319 @return EFI_DEVICE_ERROR Fail.
324 XhcDriverBindingStop (
325 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
326 IN EFI_HANDLE Controller
,
327 IN UINTN NumberOfChildren
,
328 IN EFI_HANDLE
*ChildHandleBuffer
332 Retrieves the capability of root hub ports.
334 @param This The EFI_USB2_HC_PROTOCOL instance.
335 @param MaxSpeed Max speed supported by the controller.
336 @param PortNumber Number of the root hub ports.
337 @param Is64BitCapable Whether the controller supports 64-bit memory
340 @retval EFI_SUCCESS Host controller capability were retrieved successfully.
341 @retval EFI_INVALID_PARAMETER Either of the three capability pointer is NULL.
347 IN EFI_USB2_HC_PROTOCOL
*This
,
349 OUT UINT8
*PortNumber
,
350 OUT UINT8
*Is64BitCapable
354 Provides software reset for the USB host controller.
356 @param This This EFI_USB2_HC_PROTOCOL instance.
357 @param Attributes A bit mask of the reset operation to perform.
359 @retval EFI_SUCCESS The reset operation succeeded.
360 @retval EFI_INVALID_PARAMETER Attributes is not valid.
361 @retval EFI_UNSUPPOURTED The type of reset specified by Attributes is
362 not currently supported by the host controller.
363 @retval EFI_DEVICE_ERROR Host controller isn't halted to reset.
369 IN EFI_USB2_HC_PROTOCOL
*This
,
374 Retrieve the current state of the USB host controller.
376 @param This This EFI_USB2_HC_PROTOCOL instance.
377 @param State Variable to return the current host controller
380 @retval EFI_SUCCESS Host controller state was returned in State.
381 @retval EFI_INVALID_PARAMETER State is NULL.
382 @retval EFI_DEVICE_ERROR An error was encountered while attempting to
383 retrieve the host controller's current state.
389 IN EFI_USB2_HC_PROTOCOL
*This
,
390 OUT EFI_USB_HC_STATE
*State
394 Sets the USB host controller to a specific state.
396 @param This This EFI_USB2_HC_PROTOCOL instance.
397 @param State The state of the host controller that will be set.
399 @retval EFI_SUCCESS The USB host controller was successfully placed
400 in the state specified by State.
401 @retval EFI_INVALID_PARAMETER State is invalid.
402 @retval EFI_DEVICE_ERROR Failed to set the state due to device error.
408 IN EFI_USB2_HC_PROTOCOL
*This
,
409 IN EFI_USB_HC_STATE State
413 Retrieves the current status of a USB root hub port.
415 @param This This EFI_USB2_HC_PROTOCOL instance.
416 @param PortNumber The root hub port to retrieve the state from.
417 This value is zero-based.
418 @param PortStatus Variable to receive the port state.
420 @retval EFI_SUCCESS The status of the USB root hub port specified.
421 by PortNumber was returned in PortStatus.
422 @retval EFI_INVALID_PARAMETER PortNumber is invalid.
423 @retval EFI_DEVICE_ERROR Can't read register.
428 XhcGetRootHubPortStatus (
429 IN EFI_USB2_HC_PROTOCOL
*This
,
431 OUT EFI_USB_PORT_STATUS
*PortStatus
435 Sets a feature for the specified root hub port.
437 @param This This EFI_USB2_HC_PROTOCOL instance.
438 @param PortNumber Root hub port to set.
439 @param PortFeature Feature to set.
441 @retval EFI_SUCCESS The feature specified by PortFeature was set.
442 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
443 @retval EFI_DEVICE_ERROR Can't read register.
448 XhcSetRootHubPortFeature (
449 IN EFI_USB2_HC_PROTOCOL
*This
,
451 IN EFI_USB_PORT_FEATURE PortFeature
455 Clears a feature for the specified root hub port.
457 @param This A pointer to the EFI_USB2_HC_PROTOCOL instance.
458 @param PortNumber Specifies the root hub port whose feature is
459 requested to be cleared.
460 @param PortFeature Indicates the feature selector associated with the
461 feature clear request.
463 @retval EFI_SUCCESS The feature specified by PortFeature was cleared
464 for the USB root hub port specified by PortNumber.
465 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
466 @retval EFI_DEVICE_ERROR Can't read register.
471 XhcClearRootHubPortFeature (
472 IN EFI_USB2_HC_PROTOCOL
*This
,
474 IN EFI_USB_PORT_FEATURE PortFeature
478 Submits control transfer to a target USB device.
480 @param This This EFI_USB2_HC_PROTOCOL instance.
481 @param DeviceAddress The target device address.
482 @param DeviceSpeed Target device speed.
483 @param MaximumPacketLength Maximum packet size the default control transfer
484 endpoint is capable of sending or receiving.
485 @param Request USB device request to send.
486 @param TransferDirection Specifies the data direction for the data stage
487 @param Data Data buffer to be transmitted or received from USB
489 @param DataLength The size (in bytes) of the data buffer.
490 @param Timeout Indicates the maximum timeout, in millisecond.
491 @param Translator Transaction translator to be used by this device.
492 @param TransferResult Return the result of this control transfer.
494 @retval EFI_SUCCESS Transfer was completed successfully.
495 @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resources.
496 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
497 @retval EFI_TIMEOUT Transfer failed due to timeout.
498 @retval EFI_DEVICE_ERROR Transfer failed due to host controller or device error.
504 IN EFI_USB2_HC_PROTOCOL
*This
,
505 IN UINT8 DeviceAddress
,
506 IN UINT8 DeviceSpeed
,
507 IN UINTN MaximumPacketLength
,
508 IN EFI_USB_DEVICE_REQUEST
*Request
,
509 IN EFI_USB_DATA_DIRECTION TransferDirection
,
511 IN OUT UINTN
*DataLength
,
513 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
514 OUT UINT32
*TransferResult
518 Submits bulk transfer to a bulk endpoint of a USB device.
520 @param This This EFI_USB2_HC_PROTOCOL instance.
521 @param DeviceAddress Target device address.
522 @param EndPointAddress Endpoint number and its direction in bit 7.
523 @param DeviceSpeed Device speed, Low speed device doesn't support bulk
525 @param MaximumPacketLength Maximum packet size the endpoint is capable of
526 sending or receiving.
527 @param DataBuffersNumber Number of data buffers prepared for the transfer.
528 @param Data Array of pointers to the buffers of data to transmit
529 from or receive into.
530 @param DataLength The lenght of the data buffer.
531 @param DataToggle On input, the initial data toggle for the transfer;
532 On output, it is updated to to next data toggle to
533 use of the subsequent bulk transfer.
534 @param Timeout Indicates the maximum time, in millisecond, which
535 the transfer is allowed to complete.
536 @param Translator A pointr to the transaction translator data.
537 @param TransferResult A pointer to the detailed result information of the
540 @retval EFI_SUCCESS The transfer was completed successfully.
541 @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
542 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
543 @retval EFI_TIMEOUT The transfer failed due to timeout.
544 @retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
550 IN EFI_USB2_HC_PROTOCOL
*This
,
551 IN UINT8 DeviceAddress
,
552 IN UINT8 EndPointAddress
,
553 IN UINT8 DeviceSpeed
,
554 IN UINTN MaximumPacketLength
,
555 IN UINT8 DataBuffersNumber
,
556 IN OUT VOID
*Data
[EFI_USB_MAX_BULK_BUFFER_NUM
],
557 IN OUT UINTN
*DataLength
,
558 IN OUT UINT8
*DataToggle
,
560 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
561 OUT UINT32
*TransferResult
565 Submits an asynchronous interrupt transfer to an
566 interrupt endpoint of a USB device.
568 @param This This EFI_USB2_HC_PROTOCOL instance.
569 @param DeviceAddress Target device address.
570 @param EndPointAddress Endpoint number and its direction encoded in bit 7
571 @param DeviceSpeed Indicates device speed.
572 @param MaximumPacketLength Maximum packet size the target endpoint is capable
573 @param IsNewTransfer If TRUE, to submit an new asynchronous interrupt
574 transfer If FALSE, to remove the specified
575 asynchronous interrupt.
576 @param DataToggle On input, the initial data toggle to use; on output,
577 it is updated to indicate the next data toggle.
578 @param PollingInterval The he interval, in milliseconds, that the transfer
580 @param DataLength The length of data to receive at the rate specified
582 @param Translator Transaction translator to use.
583 @param CallBackFunction Function to call at the rate specified by
585 @param Context Context to CallBackFunction.
587 @retval EFI_SUCCESS The request has been successfully submitted or canceled.
588 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
589 @retval EFI_OUT_OF_RESOURCES The request failed due to a lack of resources.
590 @retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
595 XhcAsyncInterruptTransfer (
596 IN EFI_USB2_HC_PROTOCOL
*This
,
597 IN UINT8 DeviceAddress
,
598 IN UINT8 EndPointAddress
,
599 IN UINT8 DeviceSpeed
,
600 IN UINTN MaximumPacketLength
,
601 IN BOOLEAN IsNewTransfer
,
602 IN OUT UINT8
*DataToggle
,
603 IN UINTN PollingInterval
,
605 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
606 IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction
,
607 IN VOID
*Context OPTIONAL
611 Submits synchronous interrupt transfer to an interrupt endpoint
614 @param This This EFI_USB2_HC_PROTOCOL instance.
615 @param DeviceAddress Target device address.
616 @param EndPointAddress Endpoint number and its direction encoded in bit 7
617 @param DeviceSpeed Indicates device speed.
618 @param MaximumPacketLength Maximum packet size the target endpoint is capable
619 of sending or receiving.
620 @param Data Buffer of data that will be transmitted to USB
621 device or received from USB device.
622 @param DataLength On input, the size, in bytes, of the data buffer; On
623 output, the number of bytes transferred.
624 @param DataToggle On input, the initial data toggle to use; on output,
625 it is updated to indicate the next data toggle.
626 @param Timeout Maximum time, in second, to complete.
627 @param Translator Transaction translator to use.
628 @param TransferResult Variable to receive the transfer result.
630 @return EFI_SUCCESS The transfer was completed successfully.
631 @return EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
632 @return EFI_INVALID_PARAMETER Some parameters are invalid.
633 @return EFI_TIMEOUT The transfer failed due to timeout.
634 @return EFI_DEVICE_ERROR The failed due to host controller or device error
639 XhcSyncInterruptTransfer (
640 IN EFI_USB2_HC_PROTOCOL
*This
,
641 IN UINT8 DeviceAddress
,
642 IN UINT8 EndPointAddress
,
643 IN UINT8 DeviceSpeed
,
644 IN UINTN MaximumPacketLength
,
646 IN OUT UINTN
*DataLength
,
647 IN OUT UINT8
*DataToggle
,
649 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
650 OUT UINT32
*TransferResult
654 Submits isochronous transfer to a target USB device.
656 @param This This EFI_USB2_HC_PROTOCOL instance.
657 @param DeviceAddress Target device address.
658 @param EndPointAddress End point address with its direction.
659 @param DeviceSpeed Device speed, Low speed device doesn't support this
661 @param MaximumPacketLength Maximum packet size that the endpoint is capable of
662 sending or receiving.
663 @param DataBuffersNumber Number of data buffers prepared for the transfer.
664 @param Data Array of pointers to the buffers of data that will
665 be transmitted to USB device or received from USB
667 @param DataLength The size, in bytes, of the data buffer.
668 @param Translator Transaction translator to use.
669 @param TransferResult Variable to receive the transfer result.
671 @return EFI_UNSUPPORTED Isochronous transfer is unsupported.
676 XhcIsochronousTransfer (
677 IN EFI_USB2_HC_PROTOCOL
*This
,
678 IN UINT8 DeviceAddress
,
679 IN UINT8 EndPointAddress
,
680 IN UINT8 DeviceSpeed
,
681 IN UINTN MaximumPacketLength
,
682 IN UINT8 DataBuffersNumber
,
683 IN OUT VOID
*Data
[EFI_USB_MAX_ISO_BUFFER_NUM
],
685 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
686 OUT UINT32
*TransferResult
690 Submits Async isochronous transfer to a target USB device.
692 @param This This EFI_USB2_HC_PROTOCOL instance.
693 @param DeviceAddress Target device address.
694 @param EndPointAddress End point address with its direction.
695 @param DeviceSpeed Device speed, Low speed device doesn't support this
697 @param MaximumPacketLength Maximum packet size that the endpoint is capable of
698 sending or receiving.
699 @param DataBuffersNumber Number of data buffers prepared for the transfer.
700 @param Data Array of pointers to the buffers of data that will
701 be transmitted to USB device or received from USB
703 @param DataLength The size, in bytes, of the data buffer.
704 @param Translator Transaction translator to use.
705 @param IsochronousCallBack Function to be called when the transfer complete.
706 @param Context Context passed to the call back function as
709 @return EFI_UNSUPPORTED Isochronous transfer isn't supported.
714 XhcAsyncIsochronousTransfer (
715 IN EFI_USB2_HC_PROTOCOL
*This
,
716 IN UINT8 DeviceAddress
,
717 IN UINT8 EndPointAddress
,
718 IN UINT8 DeviceSpeed
,
719 IN UINTN MaximumPacketLength
,
720 IN UINT8 DataBuffersNumber
,
721 IN OUT VOID
*Data
[EFI_USB_MAX_ISO_BUFFER_NUM
],
723 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
724 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,