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