1 /** @file
2 
3     The definition for USB hub.
4 
5 Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
7 
8 **/
9 
10 #ifndef _USB_HUB_H_
11 #define _USB_HUB_H_
12 
13 #include <IndustryStandard/Usb.h>
14 
15 #define USB_ENDPOINT_ADDR(EpAddr) ((EpAddr) & 0x7F)
16 #define USB_ENDPOINT_TYPE(Desc)   ((Desc)->Attributes & USB_ENDPOINT_TYPE_MASK)
17 
18 
19 #define USB_DESC_TYPE_HUB     0x29
20 
21 #define USB_DESC_TYPE_HUB_SUPER_SPEED  0x2a
22 
23 //
24 // Hub class control transfer target
25 //
26 #define USB_HUB_TARGET_HUB    0
27 #define USB_HUB_TARGET_PORT   3
28 //
29 // HUB class specific contrl transfer request type
30 //
31 #define USB_HUB_REQ_GET_STATUS      0
32 #define USB_HUB_REQ_CLEAR_FEATURE   1
33 #define USB_HUB_REQ_SET_FEATURE     3
34 #define USB_HUB_REQ_GET_DESC        6
35 #define USB_HUB_REQ_SET_DESC        7
36 #define USB_HUB_REQ_CLEAR_TT        8
37 #define USB_HUB_REQ_RESET_TT        9
38 #define USB_HUB_REQ_GET_TT_STATE    10
39 #define USB_HUB_REQ_STOP_TT         11
40 
41 #define USB_HUB_REQ_SET_DEPTH       12
42 
43 //
44 // USB hub class feature selector
45 //
46 #define USB_HUB_C_HUB_LOCAL_POWER   0
47 #define USB_HUB_C_HUB_OVER_CURRENT  1
48 #define USB_HUB_PORT_CONNECTION     0
49 #define USB_HUB_PORT_ENABLE         1
50 #define USB_HUB_PORT_SUSPEND        2
51 #define USB_HUB_PORT_OVER_CURRENT   3
52 #define USB_HUB_PORT_RESET          4
53 
54 #define USB_HUB_PORT_LINK_STATE     5
55 
56 #define USB_HUB_PORT_POWER          8
57 #define USB_HUB_PORT_LOW_SPEED      9
58 #define USB_HUB_C_PORT_CONNECT      16
59 #define USB_HUB_C_PORT_ENABLE       17
60 #define USB_HUB_C_PORT_SUSPEND      18
61 #define USB_HUB_C_PORT_OVER_CURRENT 19
62 #define USB_HUB_C_PORT_RESET        20
63 #define USB_HUB_PORT_TEST           21
64 #define USB_HUB_PORT_INDICATOR      22
65 
66 #define USB_HUB_C_PORT_LINK_STATE     25
67 #define USB_HUB_PORT_REMOTE_WAKE_MASK 27
68 #define USB_HUB_BH_PORT_RESET         28
69 #define USB_HUB_C_BH_PORT_RESET       29
70 
71 //
72 // Constant value for Port Status & Port Change Status of SuperSpeed port
73 //
74 #define USB_SS_PORT_STAT_C_BH_RESET         0x0020
75 #define USB_SS_PORT_STAT_C_PORT_LINK_STATE  0x0040
76 //
77 // USB hub power control method. In gang power control
78 //
79 #define USB_HUB_GANG_POWER_CTRL     0
80 #define USB_HUB_PORT_POWER_CTRL     0x01
81 //
82 // USB hub status bits
83 //
84 #define USB_HUB_STAT_LOCAL_POWER    0x01
85 #define USB_HUB_STAT_OVER_CURRENT   0x02
86 #define USB_HUB_STAT_C_LOCAL_POWER  0x01
87 #define USB_HUB_STAT_C_OVER_CURRENT 0x02
88 
89 #define USB_HUB_CLASS_CODE          0x09
90 #define USB_HUB_SUBCLASS_CODE       0x00
91 
92 //
93 // Host software return timeout if port status doesn't change
94 // after 500ms(LOOP * STALL = 5000 * 0.1ms), set by experience
95 //
96 #define USB_WAIT_PORT_STS_CHANGE_LOOP  5000
97 
98 #pragma pack(1)
99 //
100 // Hub descriptor, the last two fields are of variable lenght.
101 //
102 typedef struct {
103   UINT8           Length;
104   UINT8           DescType;
105   UINT8           NumPorts;
106   UINT16          HubCharacter;
107   UINT8           PwrOn2PwrGood;
108   UINT8           HubContrCurrent;
109   UINT8           Filler[16];
110 } EFI_USB_HUB_DESCRIPTOR;
111 
112 #pragma pack()
113 
114 
115 typedef struct {
116   UINT16                ChangedBit;
117   EFI_USB_PORT_FEATURE  Feature;
118 } USB_CHANGE_FEATURE_MAP;
119 
120 
121 /**
122   Clear the transaction translate buffer if full/low
123   speed control/bulk transfer failed and the transfer
124   uses this hub as translator.Remember to clear the TT
125   buffer of transaction translator, not that of the
126   parent.
127 
128   @param  UsbDev                The Usb device.
129   @param  Port                  The port of the hub.
130   @param  DevAddr               Address of the failed transaction.
131   @param  EpNum                 The endpoint number of the failed transaction.
132   @param  EpType                The type of failed transaction.
133 
134   @retval EFI_SUCCESS           The TT buffer is cleared.
135   @retval Others                Failed to clear the TT buffer.
136 
137 **/
138 EFI_STATUS
139 UsbHubCtrlClearTTBuffer (
140   IN USB_DEVICE           *UsbDev,
141   IN UINT8                Port,
142   IN UINT16               DevAddr,
143   IN UINT16               EpNum,
144   IN UINT16               EpType
145   );
146 
147 
148 /**
149   Test whether the interface is a hub interface.
150 
151   @param  UsbIf                 The interface to test.
152 
153   @retval TRUE                  The interface is a hub interface.
154   @retval FALSE                 The interface isn't a hub interface.
155 
156 **/
157 BOOLEAN
158 UsbIsHubInterface (
159   IN USB_INTERFACE        *UsbIf
160   );
161 
162 
163 /**
164   Ack the hub change bits. If these bits are not ACKed, Hub will
165   always return changed bit map from its interrupt endpoint.
166 
167   @param  UsbDev                The Usb device.
168 
169   @retval EFI_SUCCESS           The hub change status is ACKed.
170   @retval Others                Failed to ACK the hub status.
171 
172 **/
173 EFI_STATUS
174 UsbHubAckHubStatus (
175   IN  USB_DEVICE         *UsbDev
176   );
177 
178 extern USB_HUB_API        mUsbHubApi;
179 extern USB_HUB_API        mUsbRootHubApi;
180 #endif
181 
182