1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2 /*
3  * This file holds Hub protocol constants and data structures that are
4  * defined in chapter 11 (Hub Specification) of the USB 2.0 specification.
5  *
6  * It is used/shared between the USB core, the HCDs and couple of other USB
7  * drivers.
8  */
9 
10 #ifndef __LINUX_CH11_H
11 #define __LINUX_CH11_H
12 
13 #include <linux/types.h>	/* __u8 etc */
14 
15 /* This is arbitrary.
16  * From USB 2.0 spec Table 11-13, offset 7, a hub can
17  * have up to 255 ports. The most yet reported is 10.
18  * Upcoming hardware might raise that limit.
19  * Because the arrays need to add a bit for hub status data, we
20  * use 31, so plus one evens out to four bytes.
21  */
22 #define USB_MAXCHILDREN		31
23 
24 /* See USB 3.1 spec Table 10-5 */
25 #define USB_SS_MAXPORTS		15
26 
27 /*
28  * Hub request types
29  */
30 
31 #define USB_RT_HUB	(USB_TYPE_CLASS | USB_RECIP_DEVICE)
32 #define USB_RT_PORT	(USB_TYPE_CLASS | USB_RECIP_OTHER)
33 
34 /*
35  * Port status type for GetPortStatus requests added in USB 3.1
36  * See USB 3.1 spec Table 10-12
37  */
38 #define HUB_PORT_STATUS		0
39 #define HUB_PORT_PD_STATUS	1
40 #define HUB_EXT_PORT_STATUS	2
41 
42 /*
43  * Hub class requests
44  * See USB 2.0 spec Table 11-16
45  */
46 #define HUB_CLEAR_TT_BUFFER	8
47 #define HUB_RESET_TT		9
48 #define HUB_GET_TT_STATE	10
49 #define HUB_STOP_TT		11
50 
51 /*
52  * Hub class additional requests defined by USB 3.0 spec
53  * See USB 3.0 spec Table 10-6
54  */
55 #define HUB_SET_DEPTH		12
56 #define HUB_GET_PORT_ERR_COUNT	13
57 
58 /*
59  * Hub Class feature numbers
60  * See USB 2.0 spec Table 11-17
61  */
62 #define C_HUB_LOCAL_POWER	0
63 #define C_HUB_OVER_CURRENT	1
64 
65 /*
66  * Port feature numbers
67  * See USB 2.0 spec Table 11-17
68  */
69 #define USB_PORT_FEAT_CONNECTION	0
70 #define USB_PORT_FEAT_ENABLE		1
71 #define USB_PORT_FEAT_SUSPEND		2	/* L2 suspend */
72 #define USB_PORT_FEAT_OVER_CURRENT	3
73 #define USB_PORT_FEAT_RESET		4
74 #define USB_PORT_FEAT_L1		5	/* L1 suspend */
75 #define USB_PORT_FEAT_POWER		8
76 #define USB_PORT_FEAT_LOWSPEED		9	/* Should never be used */
77 #define USB_PORT_FEAT_C_CONNECTION	16
78 #define USB_PORT_FEAT_C_ENABLE		17
79 #define USB_PORT_FEAT_C_SUSPEND		18
80 #define USB_PORT_FEAT_C_OVER_CURRENT	19
81 #define USB_PORT_FEAT_C_RESET		20
82 #define USB_PORT_FEAT_TEST              21
83 #define USB_PORT_FEAT_INDICATOR         22
84 #define USB_PORT_FEAT_C_PORT_L1         23
85 
86 /*
87  * Port feature selectors added by USB 3.0 spec.
88  * See USB 3.0 spec Table 10-7
89  */
90 #define USB_PORT_FEAT_LINK_STATE		5
91 #define USB_PORT_FEAT_U1_TIMEOUT		23
92 #define USB_PORT_FEAT_U2_TIMEOUT		24
93 #define USB_PORT_FEAT_C_PORT_LINK_STATE		25
94 #define USB_PORT_FEAT_C_PORT_CONFIG_ERROR	26
95 #define USB_PORT_FEAT_REMOTE_WAKE_MASK		27
96 #define USB_PORT_FEAT_BH_PORT_RESET		28
97 #define USB_PORT_FEAT_C_BH_PORT_RESET		29
98 #define USB_PORT_FEAT_FORCE_LINKPM_ACCEPT	30
99 
100 #define USB_PORT_LPM_TIMEOUT(p)			(((p) & 0xff) << 8)
101 
102 /* USB 3.0 hub remote wake mask bits, see table 10-14 */
103 #define USB_PORT_FEAT_REMOTE_WAKE_CONNECT	(1 << 8)
104 #define USB_PORT_FEAT_REMOTE_WAKE_DISCONNECT	(1 << 9)
105 #define USB_PORT_FEAT_REMOTE_WAKE_OVER_CURRENT	(1 << 10)
106 
107 /*
108  * Hub Status and Hub Change results
109  * See USB 2.0 spec Table 11-19 and Table 11-20
110  * USB 3.1 extends the port status request and may return 4 additional bytes.
111  * See USB 3.1 spec section 10.16.2.6 Table 10-12 and 10-15
112  */
113 struct usb_port_status {
114 	__le16 wPortStatus;
115 	__le16 wPortChange;
116 	__le32 dwExtPortStatus;
117 } __attribute__ ((packed));
118 
119 /*
120  * wPortStatus bit field
121  * See USB 2.0 spec Table 11-21
122  */
123 #define USB_PORT_STAT_CONNECTION	0x0001
124 #define USB_PORT_STAT_ENABLE		0x0002
125 #define USB_PORT_STAT_SUSPEND		0x0004
126 #define USB_PORT_STAT_OVERCURRENT	0x0008
127 #define USB_PORT_STAT_RESET		0x0010
128 #define USB_PORT_STAT_L1		0x0020
129 /* bits 6 to 7 are reserved */
130 #define USB_PORT_STAT_POWER		0x0100
131 #define USB_PORT_STAT_LOW_SPEED		0x0200
132 #define USB_PORT_STAT_HIGH_SPEED        0x0400
133 #define USB_PORT_STAT_TEST              0x0800
134 #define USB_PORT_STAT_INDICATOR         0x1000
135 /* bits 13 to 15 are reserved */
136 
137 /*
138  * Additions to wPortStatus bit field from USB 3.0
139  * See USB 3.0 spec Table 10-10
140  */
141 #define USB_PORT_STAT_LINK_STATE	0x01e0
142 #define USB_SS_PORT_STAT_POWER		0x0200
143 #define USB_SS_PORT_STAT_SPEED		0x1c00
144 #define USB_PORT_STAT_SPEED_5GBPS	0x0000
145 /* Valid only if port is enabled */
146 /* Bits that are the same from USB 2.0 */
147 #define USB_SS_PORT_STAT_MASK (USB_PORT_STAT_CONNECTION |	    \
148 				USB_PORT_STAT_ENABLE |	    \
149 				USB_PORT_STAT_OVERCURRENT | \
150 				USB_PORT_STAT_RESET)
151 
152 /*
153  * Definitions for PORT_LINK_STATE values
154  * (bits 5-8) in wPortStatus
155  */
156 #define USB_SS_PORT_LS_U0		0x0000
157 #define USB_SS_PORT_LS_U1		0x0020
158 #define USB_SS_PORT_LS_U2		0x0040
159 #define USB_SS_PORT_LS_U3		0x0060
160 #define USB_SS_PORT_LS_SS_DISABLED	0x0080
161 #define USB_SS_PORT_LS_RX_DETECT	0x00a0
162 #define USB_SS_PORT_LS_SS_INACTIVE	0x00c0
163 #define USB_SS_PORT_LS_POLLING		0x00e0
164 #define USB_SS_PORT_LS_RECOVERY		0x0100
165 #define USB_SS_PORT_LS_HOT_RESET	0x0120
166 #define USB_SS_PORT_LS_COMP_MOD		0x0140
167 #define USB_SS_PORT_LS_LOOPBACK		0x0160
168 
169 /*
170  * wPortChange bit field
171  * See USB 2.0 spec Table 11-22 and USB 2.0 LPM ECN Table-4.10
172  * Bits 0 to 5 shown, bits 6 to 15 are reserved
173  */
174 #define USB_PORT_STAT_C_CONNECTION	0x0001
175 #define USB_PORT_STAT_C_ENABLE		0x0002
176 #define USB_PORT_STAT_C_SUSPEND		0x0004
177 #define USB_PORT_STAT_C_OVERCURRENT	0x0008
178 #define USB_PORT_STAT_C_RESET		0x0010
179 #define USB_PORT_STAT_C_L1		0x0020
180 /*
181  * USB 3.0 wPortChange bit fields
182  * See USB 3.0 spec Table 10-11
183  */
184 #define USB_PORT_STAT_C_BH_RESET	0x0020
185 #define USB_PORT_STAT_C_LINK_STATE	0x0040
186 #define USB_PORT_STAT_C_CONFIG_ERROR	0x0080
187 
188 /*
189  * USB 3.1 dwExtPortStatus field masks
190  * See USB 3.1 spec 10.16.2.6.3 Table 10-15
191  */
192 
193 #define USB_EXT_PORT_STAT_RX_SPEED_ID	0x0000000f
194 #define USB_EXT_PORT_STAT_TX_SPEED_ID	0x000000f0
195 #define USB_EXT_PORT_STAT_RX_LANES	0x00000f00
196 #define USB_EXT_PORT_STAT_TX_LANES	0x0000f000
197 
198 #define USB_EXT_PORT_RX_LANES(p) \
199 			(((p) & USB_EXT_PORT_STAT_RX_LANES) >> 8)
200 #define USB_EXT_PORT_TX_LANES(p) \
201 			(((p) & USB_EXT_PORT_STAT_TX_LANES) >> 12)
202 
203 /*
204  * wHubCharacteristics (masks)
205  * See USB 2.0 spec Table 11-13, offset 3
206  */
207 #define HUB_CHAR_LPSM		0x0003 /* Logical Power Switching Mode mask */
208 #define HUB_CHAR_COMMON_LPSM	0x0000 /* All ports power control at once */
209 #define HUB_CHAR_INDV_PORT_LPSM	0x0001 /* per-port power control */
210 #define HUB_CHAR_NO_LPSM	0x0002 /* no power switching */
211 
212 #define HUB_CHAR_COMPOUND	0x0004 /* hub is part of a compound device */
213 
214 #define HUB_CHAR_OCPM		0x0018 /* Over-Current Protection Mode mask */
215 #define HUB_CHAR_COMMON_OCPM	0x0000 /* All ports Over-Current reporting */
216 #define HUB_CHAR_INDV_PORT_OCPM	0x0008 /* per-port Over-current reporting */
217 #define HUB_CHAR_NO_OCPM	0x0010 /* No Over-current Protection support */
218 
219 #define HUB_CHAR_TTTT		0x0060 /* TT Think Time mask */
220 #define HUB_CHAR_PORTIND	0x0080 /* per-port indicators (LEDs) */
221 
222 struct usb_hub_status {
223 	__le16 wHubStatus;
224 	__le16 wHubChange;
225 } __attribute__ ((packed));
226 
227 /*
228  * Hub Status & Hub Change bit masks
229  * See USB 2.0 spec Table 11-19 and Table 11-20
230  * Bits 0 and 1 for wHubStatus and wHubChange
231  * Bits 2 to 15 are reserved for both
232  */
233 #define HUB_STATUS_LOCAL_POWER	0x0001
234 #define HUB_STATUS_OVERCURRENT	0x0002
235 #define HUB_CHANGE_LOCAL_POWER	0x0001
236 #define HUB_CHANGE_OVERCURRENT	0x0002
237 
238 
239 /*
240  * Hub descriptor
241  * See USB 2.0 spec Table 11-13
242  */
243 
244 #define USB_DT_HUB			(USB_TYPE_CLASS | 0x09)
245 #define USB_DT_SS_HUB			(USB_TYPE_CLASS | 0x0a)
246 #define USB_DT_HUB_NONVAR_SIZE		7
247 #define USB_DT_SS_HUB_SIZE              12
248 
249 /*
250  * Hub Device descriptor
251  * USB Hub class device protocols
252  */
253 
254 #define USB_HUB_PR_FS		0 /* Full speed hub */
255 #define USB_HUB_PR_HS_NO_TT	0 /* Hi-speed hub without TT */
256 #define USB_HUB_PR_HS_SINGLE_TT	1 /* Hi-speed hub with single TT */
257 #define USB_HUB_PR_HS_MULTI_TT	2 /* Hi-speed hub with multiple TT */
258 #define USB_HUB_PR_SS		3 /* Super speed hub */
259 
260 struct usb_hub_descriptor {
261 	__u8  bDescLength;
262 	__u8  bDescriptorType;
263 	__u8  bNbrPorts;
264 	__le16 wHubCharacteristics;
265 	__u8  bPwrOn2PwrGood;
266 	__u8  bHubContrCurrent;
267 
268 	/* 2.0 and 3.0 hubs differ here */
269 	union {
270 		struct {
271 			/* add 1 bit for hub status change; round to bytes */
272 			__u8  DeviceRemovable[(USB_MAXCHILDREN + 1 + 7) / 8];
273 			__u8  PortPwrCtrlMask[(USB_MAXCHILDREN + 1 + 7) / 8];
274 		}  __attribute__ ((packed)) hs;
275 
276 		struct {
277 			__u8 bHubHdrDecLat;
278 			__le16 wHubDelay;
279 			__le16 DeviceRemovable;
280 		}  __attribute__ ((packed)) ss;
281 	} u;
282 } __attribute__ ((packed));
283 
284 /* port indicator status selectors, tables 11-7 and 11-25 */
285 #define HUB_LED_AUTO	0
286 #define HUB_LED_AMBER	1
287 #define HUB_LED_GREEN	2
288 #define HUB_LED_OFF	3
289 
290 enum hub_led_mode {
291 	INDICATOR_AUTO = 0,
292 	INDICATOR_CYCLE,
293 	/* software blinks for attention:  software, hardware, reserved */
294 	INDICATOR_GREEN_BLINK, INDICATOR_GREEN_BLINK_OFF,
295 	INDICATOR_AMBER_BLINK, INDICATOR_AMBER_BLINK_OFF,
296 	INDICATOR_ALT_BLINK, INDICATOR_ALT_BLINK_OFF
297 } __attribute__ ((packed));
298 
299 /* Transaction Translator Think Times, in bits */
300 #define HUB_TTTT_8_BITS		0x00
301 #define HUB_TTTT_16_BITS	0x20
302 #define HUB_TTTT_24_BITS	0x40
303 #define HUB_TTTT_32_BITS	0x60
304 
305 #endif /* __LINUX_CH11_H */
306