3 Provides some data structure definitions used by the XHCI host controller driver.
5 Copyright (c) 2011 - 2013, 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>
33 #include <Library/ReportStatusCodeLib.h>
35 #include <IndustryStandard/Pci.h>
37 typedef struct _USB_XHCI_INSTANCE USB_XHCI_INSTANCE
;
38 typedef struct _USB_DEV_CONTEXT USB_DEV_CONTEXT
;
41 #include "XhciSched.h"
42 #include "ComponentName.h"
45 // The unit is microsecond, setting it as 1us.
47 #define XHC_1_MICROSECOND (1)
49 // Convert millisecond to microsecond.
51 #define XHC_1_MILLISECOND (1000)
53 // XHC generic timeout experience values.
54 // The unit is microsecond, setting it as 10ms.
56 #define XHC_GENERIC_TIMEOUT (10 * 1000)
58 // XHC reset timeout experience values.
59 // The unit is microsecond, setting it as 1s.
61 #define XHC_RESET_TIMEOUT (1000 * 1000)
63 // XHC delay experience value for polling operation.
64 // The unit is microsecond, set it as 1ms.
66 #define XHC_POLL_DELAY (1000)
68 // XHC async transfer timer interval, set by experience.
69 // The unit is 100us, takes 50ms as interval.
71 #define XHC_ASYNC_TIMER_INTERVAL EFI_TIMER_PERIOD_MILLISECONDS(50)
74 // XHC raises TPL to TPL_NOTIFY to serialize all its operations
75 // to protect shared data structures.
77 #define XHC_TPL TPL_NOTIFY
79 #define CMD_RING_TRB_NUMBER 0x100
80 #define TR_RING_TRB_NUMBER 0x100
81 #define ERST_NUMBER 0x01
82 #define EVENT_RING_TRB_NUMBER 0x200
88 #define INT_INTER_ASYNC 4
91 // Iterate through the doule linked list. This is delete-safe.
92 // Don't touch NextEntry
94 #define EFI_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
95 for (Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
96 Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
98 #define EFI_LIST_CONTAINER(Entry, Type, Field) BASE_CR(Entry, Type, Field)
100 #define XHC_LOW_32BIT(Addr64) ((UINT32)(((UINTN)(Addr64)) & 0xFFFFFFFF))
101 #define XHC_HIGH_32BIT(Addr64) ((UINT32)(RShiftU64((UINT64)(UINTN)(Addr64), 32) & 0xFFFFFFFF))
102 #define XHC_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
104 #define XHC_REG_BIT_IS_SET(Xhc, Offset, Bit) \
105 (XHC_BIT_IS_SET(XhcReadOpReg ((Xhc), (Offset)), (Bit)))
107 #define XHCI_IS_DATAIN(EndpointAddr) XHC_BIT_IS_SET((EndpointAddr), 0x80)
109 #define XHCI_INSTANCE_SIG SIGNATURE_32 ('x', 'h', 'c', 'i')
110 #define XHC_FROM_THIS(a) CR(a, USB_XHCI_INSTANCE, Usb2Hc, XHCI_INSTANCE_SIG)
112 #define USB_DESC_TYPE_HUB 0x29
113 #define USB_DESC_TYPE_HUB_SUPER_SPEED 0x2a
116 // The RequestType in EFI_USB_DEVICE_REQUEST is composed of
117 // three fields: One bit direction, 2 bit type, and 5 bit
120 #define USB_REQUEST_TYPE(Dir, Type, Target) \
121 ((UINT8)((((Dir) == EfiUsbDataIn ? 0x01 : 0) << 7) | (Type) | (Target)))
124 // Xhci Data and Ctrl Structures
139 UINT8 HubContrCurrent
;
141 } EFI_USB_HUB_DESCRIPTOR
;
144 struct _USB_DEV_CONTEXT
{
146 // Whether this entry in UsbDevContext array is used or not.
150 // The slot id assigned to the new device through XHCI's Enable_Slot cmd.
154 // The route string presented an attached usb device.
156 USB_DEV_ROUTE RouteString
;
158 // The route string of parent device if it exists. Otherwise it's zero.
160 USB_DEV_ROUTE ParentRouteString
;
162 // The actual device address assigned by XHCI through Address_Device command.
166 // The requested device address from UsbBus driver through Set_Address standard usb request.
167 // As XHCI spec replaces this request with Address_Device command, we have to record the
168 // requested device address and establish a mapping relationship with the actual device address.
169 // Then UsbBus driver just need to be aware of the requested device address to access usb device
170 // through EFI_USB2_HC_PROTOCOL. Xhci driver would be responsible for translating it to actual
171 // device address and access the actual device.
175 // The pointer to the input device context.
179 // The pointer to the output device context.
183 // The transfer queue for every endpoint.
185 VOID
*EndpointTransferRing
[31];
187 // The device descriptor which is stored to support XHCI's Evaluate_Context cmd.
189 EFI_USB_DEVICE_DESCRIPTOR DevDesc
;
191 // As a usb device may include multiple configuration descriptors, we dynamically allocate an array
193 // Note that every configuration descriptor stored here includes those lower level descriptors,
194 // such as Interface descriptor, Endpoint descriptor, and so on.
195 // These information is used to support XHCI's Config_Endpoint cmd.
197 EFI_USB_CONFIG_DESCRIPTOR
**ConfDesc
;
200 struct _USB_XHCI_INSTANCE
{
202 EFI_PCI_IO_PROTOCOL
*PciIo
;
203 UINT64 OriginalPciAttributes
;
205 EFI_USB2_HC_PROTOCOL Usb2Hc
;
207 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
210 // ExitBootServicesEvent is used to set OS semaphore and
211 // stop the XHC DMA operation after exit boot service.
213 EFI_EVENT ExitBootServiceEvent
;
215 LIST_ENTRY AsyncIntTransfers
;
217 UINT8 CapLength
; ///< Capability Register Length
218 XHC_HCSPARAMS1 HcSParams1
; ///< Structural Parameters 1
219 XHC_HCSPARAMS2 HcSParams2
; ///< Structural Parameters 2
220 XHC_HCCPARAMS HcCParams
; ///< Capability Parameters
221 UINT32 DBOff
; ///< Doorbell Offset
222 UINT32 RTSOff
; ///< Runtime Register Space Offset
226 UINT32 MaxScratchpadBufs
;
227 UINT32 ExtCapRegBase
;
228 UINT32 UsbLegSupOffset
;
234 TRANSFER_RING CmdRing
;
238 EVENT_RING EventRing
;
242 EFI_UNICODE_STRING_TABLE
*ControllerNameTable
;
245 // Store device contexts managed by XHCI instance
246 // The array supports up to 255 devices, entry 0 is reserved and should not be used.
248 USB_DEV_CONTEXT UsbDevContext
[256];
252 extern EFI_DRIVER_BINDING_PROTOCOL gXhciDriverBinding
;
253 extern EFI_COMPONENT_NAME_PROTOCOL gXhciComponentName
;
254 extern EFI_COMPONENT_NAME2_PROTOCOL gXhciComponentName2
;
257 Test to see if this driver supports ControllerHandle. Any
258 ControllerHandle that has Usb2HcProtocol installed will
261 @param This Protocol instance pointer.
262 @param Controller Handle of device to test.
263 @param RemainingDevicePath Not used.
265 @return EFI_SUCCESS This driver supports this device.
266 @return EFI_UNSUPPORTED This driver does not support this device.
271 XhcDriverBindingSupported (
272 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
273 IN EFI_HANDLE Controller
,
274 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
278 Starting the Usb XHCI Driver.
280 @param This Protocol instance pointer.
281 @param Controller Handle of device to test.
282 @param RemainingDevicePath Not used.
284 @return EFI_SUCCESS supports this device.
285 @return EFI_UNSUPPORTED do not support this device.
286 @return EFI_DEVICE_ERROR cannot be started due to device Error.
287 @return EFI_OUT_OF_RESOURCES cannot allocate resources.
292 XhcDriverBindingStart (
293 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
294 IN EFI_HANDLE Controller
,
295 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
299 Stop this driver on ControllerHandle. Support stoping any child handles
300 created by this driver.
302 @param This Protocol instance pointer.
303 @param Controller Handle of device to stop driver on.
304 @param NumberOfChildren Number of Children in the ChildHandleBuffer.
305 @param ChildHandleBuffer List of handles for the children we need to stop.
307 @return EFI_SUCCESS Success.
308 @return EFI_DEVICE_ERROR Fail.
313 XhcDriverBindingStop (
314 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
315 IN EFI_HANDLE Controller
,
316 IN UINTN NumberOfChildren
,
317 IN EFI_HANDLE
*ChildHandleBuffer
321 Retrieves the capability of root hub ports.
323 @param This The EFI_USB2_HC_PROTOCOL instance.
324 @param MaxSpeed Max speed supported by the controller.
325 @param PortNumber Number of the root hub ports.
326 @param Is64BitCapable Whether the controller supports 64-bit memory
329 @retval EFI_SUCCESS Host controller capability were retrieved successfully.
330 @retval EFI_INVALID_PARAMETER Either of the three capability pointer is NULL.
336 IN EFI_USB2_HC_PROTOCOL
*This
,
338 OUT UINT8
*PortNumber
,
339 OUT UINT8
*Is64BitCapable
343 Provides software reset for the USB host controller.
345 @param This This EFI_USB2_HC_PROTOCOL instance.
346 @param Attributes A bit mask of the reset operation to perform.
348 @retval EFI_SUCCESS The reset operation succeeded.
349 @retval EFI_INVALID_PARAMETER Attributes is not valid.
350 @retval EFI_UNSUPPOURTED The type of reset specified by Attributes is
351 not currently supported by the host controller.
352 @retval EFI_DEVICE_ERROR Host controller isn't halted to reset.
358 IN EFI_USB2_HC_PROTOCOL
*This
,
363 Retrieve the current state of the USB host controller.
365 @param This This EFI_USB2_HC_PROTOCOL instance.
366 @param State Variable to return the current host controller
369 @retval EFI_SUCCESS Host controller state was returned in State.
370 @retval EFI_INVALID_PARAMETER State is NULL.
371 @retval EFI_DEVICE_ERROR An error was encountered while attempting to
372 retrieve the host controller's current state.
378 IN EFI_USB2_HC_PROTOCOL
*This
,
379 OUT EFI_USB_HC_STATE
*State
383 Sets the USB host controller to a specific state.
385 @param This This EFI_USB2_HC_PROTOCOL instance.
386 @param State The state of the host controller that will be set.
388 @retval EFI_SUCCESS The USB host controller was successfully placed
389 in the state specified by State.
390 @retval EFI_INVALID_PARAMETER State is invalid.
391 @retval EFI_DEVICE_ERROR Failed to set the state due to device error.
397 IN EFI_USB2_HC_PROTOCOL
*This
,
398 IN EFI_USB_HC_STATE State
402 Retrieves the current status of a USB root hub port.
404 @param This This EFI_USB2_HC_PROTOCOL instance.
405 @param PortNumber The root hub port to retrieve the state from.
406 This value is zero-based.
407 @param PortStatus Variable to receive the port state.
409 @retval EFI_SUCCESS The status of the USB root hub port specified.
410 by PortNumber was returned in PortStatus.
411 @retval EFI_INVALID_PARAMETER PortNumber is invalid.
412 @retval EFI_DEVICE_ERROR Can't read register.
417 XhcGetRootHubPortStatus (
418 IN EFI_USB2_HC_PROTOCOL
*This
,
420 OUT EFI_USB_PORT_STATUS
*PortStatus
424 Sets a feature for the specified root hub port.
426 @param This This EFI_USB2_HC_PROTOCOL instance.
427 @param PortNumber Root hub port to set.
428 @param PortFeature Feature to set.
430 @retval EFI_SUCCESS The feature specified by PortFeature was set.
431 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
432 @retval EFI_DEVICE_ERROR Can't read register.
437 XhcSetRootHubPortFeature (
438 IN EFI_USB2_HC_PROTOCOL
*This
,
440 IN EFI_USB_PORT_FEATURE PortFeature
444 Clears a feature for the specified root hub port.
446 @param This A pointer to the EFI_USB2_HC_PROTOCOL instance.
447 @param PortNumber Specifies the root hub port whose feature is
448 requested to be cleared.
449 @param PortFeature Indicates the feature selector associated with the
450 feature clear request.
452 @retval EFI_SUCCESS The feature specified by PortFeature was cleared
453 for the USB root hub port specified by PortNumber.
454 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
455 @retval EFI_DEVICE_ERROR Can't read register.
460 XhcClearRootHubPortFeature (
461 IN EFI_USB2_HC_PROTOCOL
*This
,
463 IN EFI_USB_PORT_FEATURE PortFeature
467 Submits control transfer to a target USB device.
469 @param This This EFI_USB2_HC_PROTOCOL instance.
470 @param DeviceAddress The target device address.
471 @param DeviceSpeed Target device speed.
472 @param MaximumPacketLength Maximum packet size the default control transfer
473 endpoint is capable of sending or receiving.
474 @param Request USB device request to send.
475 @param TransferDirection Specifies the data direction for the data stage
476 @param Data Data buffer to be transmitted or received from USB
478 @param DataLength The size (in bytes) of the data buffer.
479 @param Timeout Indicates the maximum timeout, in millisecond.
480 @param Translator Transaction translator to be used by this device.
481 @param TransferResult Return the result of this control transfer.
483 @retval EFI_SUCCESS Transfer was completed successfully.
484 @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resources.
485 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
486 @retval EFI_TIMEOUT Transfer failed due to timeout.
487 @retval EFI_DEVICE_ERROR Transfer failed due to host controller or device error.
493 IN EFI_USB2_HC_PROTOCOL
*This
,
494 IN UINT8 DeviceAddress
,
495 IN UINT8 DeviceSpeed
,
496 IN UINTN MaximumPacketLength
,
497 IN EFI_USB_DEVICE_REQUEST
*Request
,
498 IN EFI_USB_DATA_DIRECTION TransferDirection
,
500 IN OUT UINTN
*DataLength
,
502 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
503 OUT UINT32
*TransferResult
507 Submits bulk transfer to a bulk endpoint of a USB device.
509 @param This This EFI_USB2_HC_PROTOCOL instance.
510 @param DeviceAddress Target device address.
511 @param EndPointAddress Endpoint number and its direction in bit 7.
512 @param DeviceSpeed Device speed, Low speed device doesn't support bulk
514 @param MaximumPacketLength Maximum packet size the endpoint is capable of
515 sending or receiving.
516 @param DataBuffersNumber Number of data buffers prepared for the transfer.
517 @param Data Array of pointers to the buffers of data to transmit
518 from or receive into.
519 @param DataLength The lenght of the data buffer.
520 @param DataToggle On input, the initial data toggle for the transfer;
521 On output, it is updated to to next data toggle to
522 use of the subsequent bulk transfer.
523 @param Timeout Indicates the maximum time, in millisecond, which
524 the transfer is allowed to complete.
525 @param Translator A pointr to the transaction translator data.
526 @param TransferResult A pointer to the detailed result information of the
529 @retval EFI_SUCCESS The transfer was completed successfully.
530 @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
531 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
532 @retval EFI_TIMEOUT The transfer failed due to timeout.
533 @retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
539 IN EFI_USB2_HC_PROTOCOL
*This
,
540 IN UINT8 DeviceAddress
,
541 IN UINT8 EndPointAddress
,
542 IN UINT8 DeviceSpeed
,
543 IN UINTN MaximumPacketLength
,
544 IN UINT8 DataBuffersNumber
,
545 IN OUT VOID
*Data
[EFI_USB_MAX_BULK_BUFFER_NUM
],
546 IN OUT UINTN
*DataLength
,
547 IN OUT UINT8
*DataToggle
,
549 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
550 OUT UINT32
*TransferResult
554 Submits an asynchronous interrupt transfer to an
555 interrupt endpoint of a USB device.
557 @param This This EFI_USB2_HC_PROTOCOL instance.
558 @param DeviceAddress Target device address.
559 @param EndPointAddress Endpoint number and its direction encoded in bit 7
560 @param DeviceSpeed Indicates device speed.
561 @param MaximumPacketLength Maximum packet size the target endpoint is capable
562 @param IsNewTransfer If TRUE, to submit an new asynchronous interrupt
563 transfer If FALSE, to remove the specified
564 asynchronous interrupt.
565 @param DataToggle On input, the initial data toggle to use; on output,
566 it is updated to indicate the next data toggle.
567 @param PollingInterval The he interval, in milliseconds, that the transfer
569 @param DataLength The length of data to receive at the rate specified
571 @param Translator Transaction translator to use.
572 @param CallBackFunction Function to call at the rate specified by
574 @param Context Context to CallBackFunction.
576 @retval EFI_SUCCESS The request has been successfully submitted or canceled.
577 @retval EFI_INVALID_PARAMETER Some parameters are invalid.
578 @retval EFI_OUT_OF_RESOURCES The request failed due to a lack of resources.
579 @retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
584 XhcAsyncInterruptTransfer (
585 IN EFI_USB2_HC_PROTOCOL
*This
,
586 IN UINT8 DeviceAddress
,
587 IN UINT8 EndPointAddress
,
588 IN UINT8 DeviceSpeed
,
589 IN UINTN MaximumPacketLength
,
590 IN BOOLEAN IsNewTransfer
,
591 IN OUT UINT8
*DataToggle
,
592 IN UINTN PollingInterval
,
594 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
595 IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction
,
596 IN VOID
*Context OPTIONAL
600 Submits synchronous interrupt transfer to an interrupt endpoint
603 @param This This EFI_USB2_HC_PROTOCOL instance.
604 @param DeviceAddress Target device address.
605 @param EndPointAddress Endpoint number and its direction encoded in bit 7
606 @param DeviceSpeed Indicates device speed.
607 @param MaximumPacketLength Maximum packet size the target endpoint is capable
608 of sending or receiving.
609 @param Data Buffer of data that will be transmitted to USB
610 device or received from USB device.
611 @param DataLength On input, the size, in bytes, of the data buffer; On
612 output, the number of bytes transferred.
613 @param DataToggle On input, the initial data toggle to use; on output,
614 it is updated to indicate the next data toggle.
615 @param Timeout Maximum time, in second, to complete.
616 @param Translator Transaction translator to use.
617 @param TransferResult Variable to receive the transfer result.
619 @return EFI_SUCCESS The transfer was completed successfully.
620 @return EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
621 @return EFI_INVALID_PARAMETER Some parameters are invalid.
622 @return EFI_TIMEOUT The transfer failed due to timeout.
623 @return EFI_DEVICE_ERROR The failed due to host controller or device error
628 XhcSyncInterruptTransfer (
629 IN EFI_USB2_HC_PROTOCOL
*This
,
630 IN UINT8 DeviceAddress
,
631 IN UINT8 EndPointAddress
,
632 IN UINT8 DeviceSpeed
,
633 IN UINTN MaximumPacketLength
,
635 IN OUT UINTN
*DataLength
,
636 IN OUT UINT8
*DataToggle
,
638 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
639 OUT UINT32
*TransferResult
643 Submits isochronous transfer to a target USB device.
645 @param This This EFI_USB2_HC_PROTOCOL instance.
646 @param DeviceAddress Target device address.
647 @param EndPointAddress End point address with its direction.
648 @param DeviceSpeed Device speed, Low speed device doesn't support this
650 @param MaximumPacketLength Maximum packet size that the endpoint is capable of
651 sending or receiving.
652 @param DataBuffersNumber Number of data buffers prepared for the transfer.
653 @param Data Array of pointers to the buffers of data that will
654 be transmitted to USB device or received from USB
656 @param DataLength The size, in bytes, of the data buffer.
657 @param Translator Transaction translator to use.
658 @param TransferResult Variable to receive the transfer result.
660 @return EFI_UNSUPPORTED Isochronous transfer is unsupported.
665 XhcIsochronousTransfer (
666 IN EFI_USB2_HC_PROTOCOL
*This
,
667 IN UINT8 DeviceAddress
,
668 IN UINT8 EndPointAddress
,
669 IN UINT8 DeviceSpeed
,
670 IN UINTN MaximumPacketLength
,
671 IN UINT8 DataBuffersNumber
,
672 IN OUT VOID
*Data
[EFI_USB_MAX_ISO_BUFFER_NUM
],
674 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
675 OUT UINT32
*TransferResult
679 Submits Async isochronous transfer to a target USB device.
681 @param This This EFI_USB2_HC_PROTOCOL instance.
682 @param DeviceAddress Target device address.
683 @param EndPointAddress End point address with its direction.
684 @param DeviceSpeed Device speed, Low speed device doesn't support this
686 @param MaximumPacketLength Maximum packet size that the endpoint is capable of
687 sending or receiving.
688 @param DataBuffersNumber Number of data buffers prepared for the transfer.
689 @param Data Array of pointers to the buffers of data that will
690 be transmitted to USB device or received from USB
692 @param DataLength The size, in bytes, of the data buffer.
693 @param Translator Transaction translator to use.
694 @param IsochronousCallBack Function to be called when the transfer complete.
695 @param Context Context passed to the call back function as
698 @return EFI_UNSUPPORTED Isochronous transfer isn't supported.
703 XhcAsyncIsochronousTransfer (
704 IN EFI_USB2_HC_PROTOCOL
*This
,
705 IN UINT8 DeviceAddress
,
706 IN UINT8 EndPointAddress
,
707 IN UINT8 DeviceSpeed
,
708 IN UINTN MaximumPacketLength
,
709 IN UINT8 DataBuffersNumber
,
710 IN OUT VOID
*Data
[EFI_USB_MAX_ISO_BUFFER_NUM
],
712 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR
*Translator
,
713 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,