3 This file contains the definition for XHCI host controller schedule routines.
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.
16 #ifndef _EFI_XHCI_SCHED_H_
17 #define _EFI_XHCI_SCHED_H_
19 #define XHC_URB_SIG SIGNATURE_32 ('U', 'S', 'B', 'R')
22 // Transfer types, used in URB to identify the transfer type
24 #define XHC_CTRL_TRANSFER 0x01
25 #define XHC_BULK_TRANSFER 0x02
26 #define XHC_INT_TRANSFER_SYNC 0x04
27 #define XHC_INT_TRANSFER_ASYNC 0x08
28 #define XHC_INT_ONLY_TRANSFER_ASYNC 0x10
33 #define TRB_TYPE_NORMAL 1
34 #define TRB_TYPE_SETUP_STAGE 2
35 #define TRB_TYPE_DATA_STAGE 3
36 #define TRB_TYPE_STATUS_STAGE 4
37 #define TRB_TYPE_ISOCH 5
38 #define TRB_TYPE_LINK 6
39 #define TRB_TYPE_EVENT_DATA 7
40 #define TRB_TYPE_NO_OP 8
41 #define TRB_TYPE_EN_SLOT 9
42 #define TRB_TYPE_DIS_SLOT 10
43 #define TRB_TYPE_ADDRESS_DEV 11
44 #define TRB_TYPE_CON_ENDPOINT 12
45 #define TRB_TYPE_EVALU_CONTXT 13
46 #define TRB_TYPE_RESET_ENDPOINT 14
47 #define TRB_TYPE_STOP_ENDPOINT 15
48 #define TRB_TYPE_SET_TR_DEQUE 16
49 #define TRB_TYPE_RESET_DEV 17
50 #define TRB_TYPE_GET_PORT_BANW 21
51 #define TRB_TYPE_FORCE_HEADER 22
52 #define TRB_TYPE_NO_OP_COMMAND 23
53 #define TRB_TYPE_TRANS_EVENT 32
54 #define TRB_TYPE_COMMAND_COMPLT_EVENT 33
55 #define TRB_TYPE_PORT_STATUS_CHANGE_EVENT 34
56 #define TRB_TYPE_HOST_CONTROLLER_EVENT 37
57 #define TRB_TYPE_DEVICE_NOTIFI_EVENT 38
58 #define TRB_TYPE_MFINDEX_WRAP_EVENT 39
61 // Endpoint Type (EP Type).
63 #define ED_NOT_VALID 0
64 #define ED_ISOCH_OUT 1
66 #define ED_INTERRUPT_OUT 3
67 #define ED_CONTROL_BIDIR 4
70 #define ED_INTERRUPT_IN 7
73 // 6.4.5 TRB Completion Codes
75 #define TRB_COMPLETION_INVALID 0
76 #define TRB_COMPLETION_SUCCESS 1
77 #define TRB_COMPLETION_DATA_BUFFER_ERROR 2
78 #define TRB_COMPLETION_BABBLE_ERROR 3
79 #define TRB_COMPLETION_USB_TRANSACTION_ERROR 4
80 #define TRB_COMPLETION_TRB_ERROR 5
81 #define TRB_COMPLETION_STALL_ERROR 6
82 #define TRB_COMPLETION_SHORT_PACKET 13
85 // USB device RouteChart record
87 typedef union _USB_DEV_TOPOLOGY
{
90 UINT32 RouteString
:20; ///< The tier concatenation of down stream port
91 UINT32 RootPortNum
:8; ///< The root port number of the chain
92 UINT32 TierNum
:4; ///< The Tier the device reside
97 // Endpoint address and its capabilities
99 typedef struct _USB_ENDPOINT
{
102 EFI_USB_DATA_DIRECTION Direction
;
111 typedef struct _TRB
{
121 typedef struct _TRANSFER_RING
{
129 typedef struct _EVENT_RING
{
130 UINT32 EventInterrupter
;
134 TRB
*EventRingEnqueue
;
135 TRB
*EventRingDequeue
;
140 // URB (Usb Request Block) contains information for all kinds of
143 typedef struct _URB
{
147 // Usb Device URB related information
150 EFI_USB_DEVICE_REQUEST
*Request
;
153 EFI_ASYNC_USB_TRANSFER_CALLBACK Callback
;
160 // completed data length
164 // Command/Tranfer Ring info
175 // 5.5.2 Interrupter Register Set
177 typedef struct _INTERRUPTER_REGISTER_SET
{
178 UINT32 InterrupterManagement
;
179 UINT32 InterrupterModeration
;
180 UINT32 RingSegTableSize
:16;
187 } INTERRUPTER_REGISTER_SET
;
190 // Host Controller Runtime Registers
192 typedef struct _HC_RUNTIME_REGS
{
193 UINT32 MicroframeIndex
;
198 INTERRUPTER_REGISTER_SET IR
[1];
202 // 6.5 Event Ring Segment Table
203 // The Event Ring Segment Table is used to define multi-segment Event Rings and to enable runtime
204 // expansion and shrinking of the Event Ring. The location of the Event Ring Segment Table is defined by the
205 // Event Ring Segment Table Base Address Register (5.5.2.3.2). The size of the Event Ring Segment Table
206 // is defined by the Event Ring Segment Table Base Size Register (5.5.2.3.1).
208 typedef struct _EVENT_RING_SEG_TABLE_ENTRY
{
211 UINT32 RingTrbSize
:16;
214 } EVENT_RING_SEG_TABLE_ENTRY
;
217 // 6.4.1.1 Normal TRB
218 // A Normal TRB is used in several ways; exclusively on Bulk and Interrupt Transfer Rings for normal and
219 // Scatter/Gather operations, to define additional data buffers for Scatter/Gather operations on Isoch Transfer
220 // Rings, and to define the Data stage information for Control Transfer Rings.
222 typedef struct _TRANSFER_TRB_NORMAL
{
239 } TRANSFER_TRB_NORMAL
;
242 // 6.4.1.2.1 Setup Stage TRB
243 // A Setup Stage TRB is created by system software to initiate a USB Setup packet on a control endpoint.
245 typedef struct _TRANSFER_TRB_CONTROL_SETUP
{
246 UINT32 bmRequestType
:8;
265 } TRANSFER_TRB_CONTROL_SETUP
;
268 // 6.4.1.2.2 Data Stage TRB
269 // A Data Stage TRB is used generate the Data stage transaction of a USB Control transfer.
271 typedef struct _TRANSFER_TRB_CONTROL_DATA
{
288 } TRANSFER_TRB_CONTROL_DATA
;
291 // 6.4.1.2.2 Data Stage TRB
292 // A Data Stage TRB is used generate the Data stage transaction of a USB Control transfer.
294 typedef struct _TRANSFER_TRB_CONTROL_STATUS
{
308 } TRANSFER_TRB_CONTROL_STATUS
;
311 // 6.4.2.1 Transfer Event TRB
312 // A Transfer Event provides the completion status associated with a Transfer TRB. Refer to section 4.11.3.1
313 // for more information on the use and operation of Transfer Events.
315 typedef struct _EVT_TRB_TRANSFER
{
319 UINT32 Completcode
:8;
331 // 6.4.2.2 Command Completion Event TRB
332 // A Command Completion Event TRB shall be generated by the xHC when a command completes on the
333 // Command Ring. Refer to section 4.11.4 for more information on the use of Command Completion Events.
335 typedef struct _EVT_TRB_COMMAND
{
339 UINT32 Completcode
:8;
348 // 6.4.2.3 Port Status Change Event TRB
350 typedef struct _EVT_TRB_PORT
{
355 UINT32 Completcode
:8;
363 // 6.4.3.1 No Op Command TRB
364 // The No Op Command TRB provides a simple means for verifying the operation of the Command Ring
365 // mechanisms offered by the xHCI.
367 typedef struct _CMD_TRB_NO_OP
{
378 // 6.4.3.2 Enable Slot Command TRB
379 // The Enable Slot Command TRB causes the xHC to select an available Device Slot and return the ID of the
380 // selected slot to the host in a Command Completion Event.
382 typedef struct _CMD_TRB_EN_SLOT
{
393 // 6.4.3.3 Disable Slot Command TRB
394 // The Disable Slot Command TRB releases any bandwidth assigned to the disabled slot and frees any
395 // internal xHC resources assigned to the slot.
397 typedef struct _CMD_TRB_DIS_SLOT
{
408 typedef struct _CMD_TRB_RESET_PORT
{
419 } CMD_TRB_RESET_PORT
;
422 // 6.4.3.4 Address Device Command TRB
423 // The Address Device Command TRB transitions the selected Device Context from the Default to the
424 // Addressed state and causes the xHC to select an address for the USB device in the Default State and
425 // issue a SET_ADDRESS request to the USB device.
427 typedef struct _CMD_TRB_ADDR_DEV
{
440 // 6.4.3.5 Configure Endpoint Command TRB
441 // The Configure Endpoint Command TRB evaluates the bandwidth and resource requirements of the
442 // endpoints selected by the command.
444 typedef struct _CMD_CFG_ED
{
457 // 6.4.3.6 Evaluate Context Command TRB
458 // The Evaluate Context Command TRB is used by system software to inform the xHC that the selected
459 // Context data structures in the Device Context have been modified by system software and that the xHC
460 // shall evaluate any changes
462 typedef struct _CMD_TRB_EVALU_CONTX
{
471 } CMD_TRB_EVALU_CONTX
;
474 // 6.4.3.7 Reset Endpoint Command TRB
475 // The Reset Endpoint Command TRB is used by system software to reset a specified Transfer Ring
477 typedef struct _CMD_TRB_RESET_ED
{
491 // 6.4.3.8 Stop Endpoint Command TRB
492 // The Stop Endpoint Command TRB command allows software to stop the xHC execution of the TDs on a
493 // Transfer Ring and temporarily take ownership of TDs that had previously been passed to the xHC.
495 typedef struct _CMD_TRB_STOP_ED
{
509 // 6.4.3.9 Set TR Dequeue Pointer Command TRB
510 // The Set TR Dequeue Pointer Command TRB is used by system software to modify the TR Dequeue
511 // Pointer and DCS fields of an Endpoint or Stream Context.
513 typedef struct _CMD_SET_TR_DEQ
{
527 // A Link TRB provides support for non-contiguous TRB Rings.
529 typedef struct _LNK_TRB
{
533 UINT32 InterTarget
:10;
545 // A Link TRB provides support for non-contiguous TRB Rings.
547 typedef struct _NO_OP_TRB
{
558 // 6.2.2 Slot Context
560 typedef struct _SLOT_CONTEXT
{
566 UINT32 ContextEntries
:5;
568 UINT32 MaxExitLatency
:16;
569 UINT32 RootHubPortNum
:8;
572 UINT32 TTHubSlotId
:8;
576 UINT32 InterTarget
:10;
578 UINT32 DeviceAddress
:8;
589 // 6.2.3 Endpoint Context
591 typedef struct _ENDPOINT_CONTEXT
{
595 UINT32 MaxPStreams
:5;
605 UINT32 MaxBurstSize
:8;
606 UINT32 MaxPacketSize
:16;
612 UINT32 AverageTRBLength
:16;
613 UINT32 MaxESITPayload
:16;
621 // 6.2.5.1 Input Control Context
623 typedef struct _INPUT_CONTRL_CONTEXT
{
632 } INPUT_CONTRL_CONTEXT
;
635 // 6.2.1 Device Context
637 typedef struct _DEVICE_CONTEXT
{
639 ENDPOINT_CONTEXT EP
[31];
643 // 6.2.5 Input Context
645 typedef struct _INPUT_CONTEXT
{
646 INPUT_CONTRL_CONTEXT InputControlContext
;
648 ENDPOINT_CONTEXT EP
[31];
652 Initialize the XHCI host controller for schedule.
654 @param Xhc The XHCI device to be initialized.
663 Free the resouce allocated at initializing schedule.
665 @param Xhc The XHCI device.
674 Ring the door bell to notify XHCI there is a transaction to be executed through URB.
676 @param Xhc The XHCI device.
677 @param Urb The URB to be rung.
679 @retval EFI_SUCCESS Successfully ring the door bell.
683 RingIntTransferDoorBell (
684 IN USB_XHCI_DEV
*Xhc
,
689 Execute the transfer by polling the URB. This is a synchronous operation.
691 @param Xhc The XHCI device.
692 @param CmdTransfer The executed URB is for cmd transfer or not.
693 @param Urb The URB to execute.
694 @param TimeOut The time to wait before abort, in millisecond.
696 @return EFI_DEVICE_ERROR The transfer failed due to transfer error.
697 @return EFI_TIMEOUT The transfer failed due to time out.
698 @return EFI_SUCCESS The transfer finished OK.
703 IN USB_XHCI_DEV
*Xhc
,
704 IN BOOLEAN CmdTransfer
,
710 Delete a single asynchronous interrupt transfer for
711 the device and endpoint.
713 @param Xhc The XHCI device.
714 @param DevAddr The address of the target device.
715 @param EpNum The endpoint of the target.
717 @retval EFI_SUCCESS An asynchronous transfer is removed.
718 @retval EFI_NOT_FOUND No transfer for the device is found.
722 XhciDelAsyncIntTransfer (
723 IN USB_XHCI_DEV
*Xhc
,
729 Remove all the asynchronous interrupt transfers.
731 @param Xhc The XHCI device.
735 XhciDelAllAsyncIntTransfers (
742 @param Xhc The XHCI device.
746 XhcSetBiosOwnership (
753 @param Xhc The XHCI device.
757 XhcClearBiosOwnership (
762 Find out the slot id according to device address assigned by XHCI's Address_Device cmd.
764 @param DevAddr The device address of the target device.
766 @return The slot id used by the device.
775 Find out the slot id according to the device's route string.
777 @param RouteString The route string described the device location.
779 @return The slot id used by the device.
784 XhcRouteStringToSlotId (
785 IN USB_DEV_ROUTE RouteString
789 Calculate the device context index by endpoint address and direction.
791 @param EpAddr The target endpoint number.
792 @param Direction The direction of the target endpoint.
794 @return The device context index of endpoint.
804 Ring the door bell to notify XHCI there is a transaction to be executed.
806 @param Xhc The XHCI device.
807 @param SlotId The slot id of the target device.
808 @param Dci The device context index of the target slot or endpoint.
810 @retval EFI_SUCCESS Successfully ring the door bell.
816 IN USB_XHCI_DEV
*Xhc
,
822 Interrupt transfer periodic check handler.
824 @param Event Interrupt event.
825 @param Context Pointer to USB_XHCI_DEV.
830 XhcMonitorAsyncRequests (
836 Monitor the port status change. Enable/Disable device slot if there is a device attached/detached.
838 @param Xhc The XHCI device.
839 @param ParentRouteChart The route string pointed to the parent device if it exists.
840 @param Port The port to be polled.
841 @param PortState The port state.
843 @retval EFI_SUCCESS Successfully enable/disable device slot according to port state.
844 @retval Others Should not appear.
849 XhcPollPortStatusChange (
850 IN USB_XHCI_DEV
* Xhc
,
851 IN USB_DEV_ROUTE ParentRouteChart
,
853 IN EFI_USB_PORT_STATUS
*PortState
857 Evaluate the slot context for hub device through XHCI's Configure_Endpoint cmd.
859 @param Xhc The XHCI device.
860 @param SlotId The slot id to be configured.
861 @param PortNum The total number of downstream port supported by the hub.
862 @param TTT The TT think time of the hub device.
863 @param MTT The multi-TT of the hub device.
865 @retval EFI_SUCCESS Successfully configure the hub device's slot context.
869 XhcConfigHubContext (
870 IN USB_XHCI_DEV
*Xhc
,
878 Configure all the device endpoints through XHCI's Configure_Endpoint cmd.
880 @param Xhc The XHCI device.
881 @param SlotId The slot id to be configured.
882 @param DeviceSpeed The device's speed.
883 @param ConfigDesc The pointer to the usb device configuration descriptor.
885 @retval EFI_SUCCESS Successfully configure all the device endpoints.
891 IN USB_XHCI_DEV
*Xhc
,
893 IN UINT8 DeviceSpeed
,
894 IN USB_CONFIG_DESCRIPTOR
*ConfigDesc
898 Find out the actual device address according to the requested device address from UsbBus.
900 @param BusDevAddr The requested device address by UsbBus upper driver.
902 @return The actual device address assigned to the device.
907 XhcBusDevAddrToSlotId (
912 Assign and initialize the device slot for a new device.
914 @param Xhc The XHCI device.
915 @param ParentRouteChart The route string pointed to the parent device.
916 @param ParentPort The port at which the device is located.
917 @param RouteChart The route string pointed to the device.
918 @param DeviceSpeed The device speed.
920 @retval EFI_SUCCESS Successfully assign a slot to the device and assign an address to it.
925 XhcInitializeDeviceSlot (
926 IN USB_XHCI_DEV
*Xhc
,
927 IN USB_DEV_ROUTE ParentRouteChart
,
928 IN UINT16 ParentPort
,
929 IN USB_DEV_ROUTE RouteChart
,
934 Evaluate the endpoint 0 context through XHCI's Evaluate_Context cmd.
936 @param Xhc The XHCI device.
937 @param SlotId The slot id to be evaluated.
938 @param MaxPacketSize The max packet size supported by the device control transfer.
940 @retval EFI_SUCCESS Successfully evaluate the device endpoint 0.
946 IN USB_XHCI_DEV
*Xhc
,
948 IN UINT32 MaxPacketSize
952 Disable the specified device slot.
954 @param Xhc The XHCI device.
955 @param SlotId The slot id to be disabled.
957 @retval EFI_SUCCESS Successfully disable the device slot.
963 IN USB_XHCI_DEV
*Xhc
,
968 Synchronize the specified transfer ring to update the enqueue and dequeue pointer.
970 @param Xhc The XHCI device.
971 @param TrsRing The transfer ring to sync.
973 @retval EFI_SUCCESS The transfer ring is synchronized successfully.
979 IN USB_XHCI_DEV
*Xhc
,
980 TRANSFER_RING
*TrsRing
984 Synchronize the specified event ring to update the enqueue and dequeue pointer.
986 @param Xhc The XHCI device.
987 @param EvtRing The event ring to sync.
989 @retval EFI_SUCCESS The event ring is synchronized successfully.
995 IN USB_XHCI_DEV
*Xhc
,
1000 Check if there is a new generated event.
1002 @param Xhc The XHCI device.
1003 @param EvtRing The event ring to check.
1004 @param NewEvtTrb The new event TRB found.
1006 @retval EFI_SUCCESS Found a new event TRB at the event ring.
1007 @retval EFI_NOT_READY The event ring has no new event.
1013 IN USB_XHCI_DEV
*Xhc
,
1014 IN EVENT_RING
*EvtRing
,
1019 Create XHCI transfer ring.
1021 @param Xhc The XHCI device.
1022 @param TrbNum The number of TRB in the ring.
1023 @param TransferRing The created transfer ring.
1027 CreateTransferRing (
1028 IN USB_XHCI_DEV
*Xhc
,
1030 OUT TRANSFER_RING
*TransferRing
1034 Create XHCI event ring.
1036 @param Xhc The XHCI device.
1037 @param EventInterrupter The interrupter of event.
1038 @param EventRing The created event ring.
1043 IN USB_XHCI_DEV
*Xhc
,
1044 IN UINT8 EventInterrupter
,
1045 OUT EVENT_RING
*EventRing
1049 System software shall use a Reset Endpoint Command (section 4.11.4.7) to remove the Halted
1050 condition in the xHC. After the successful completion of the Reset Endpoint Command, the Endpoint
1051 Context is transitioned from the Halted to the Stopped state and the Transfer Ring of the endpoint is
1052 reenabled. The next write to the Doorbell of the Endpoint will transition the Endpoint Context from the
1053 Stopped to the Running state.
1055 @param Xhc The XHCI device.
1056 @param Urb The urb which makes the endpoint halted.
1058 @retval EFI_SUCCESS The recovery is successful.
1059 @retval Others Failed to recovery halted endpoint.
1064 XhcRecoverHaltedEndpoint (
1065 IN USB_XHCI_DEV
*Xhc
,
1070 Create a new URB for a new transaction.
1072 @param Xhc The XHCI device
1073 @param DevAddr The device address
1074 @param EpAddr Endpoint addrress
1075 @param DevSpeed The device speed
1076 @param MaxPacket The max packet length of the endpoint
1077 @param Type The transaction type
1078 @param Request The standard USB request for control transfer
1079 @param Data The user data to transfer
1080 @param DataLen The length of data buffer
1081 @param Callback The function to call when data is transferred
1082 @param Context The context to the callback
1084 @return Created URB or NULL
1089 IN USB_XHCI_DEV
*Xhc
,
1095 IN EFI_USB_DEVICE_REQUEST
*Request
,
1098 IN EFI_ASYNC_USB_TRANSFER_CALLBACK Callback
,
1103 Create a transfer TRB.
1105 @param Xhc The XHCI device
1106 @param Urb The urb used to construct the transfer TRB.
1108 @return Created TRB or NULL
1112 XhcCreateTransferTrb (
1113 IN USB_XHCI_DEV
*Xhc
,