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/*
201 * wHubCharacteristics (masks)
202 * See USB 2.0 spec Table 11-13, offset 3
203 */
204#define HUB_CHAR_LPSM 0x0003 /* Logical Power Switching Mode mask */
205#define HUB_CHAR_COMMON_LPSM 0x0000 /* All ports power control at once */
206#define HUB_CHAR_INDV_PORT_LPSM 0x0001 /* per-port power control */
207#define HUB_CHAR_NO_LPSM 0x0002 /* no power switching */
208
209#define HUB_CHAR_COMPOUND 0x0004 /* hub is part of a compound device */
210
211#define HUB_CHAR_OCPM 0x0018 /* Over-Current Protection Mode mask */
212#define HUB_CHAR_COMMON_OCPM 0x0000 /* All ports Over-Current reporting */
213#define HUB_CHAR_INDV_PORT_OCPM 0x0008 /* per-port Over-current reporting */
214#define HUB_CHAR_NO_OCPM 0x0010 /* No Over-current Protection support */
215
216#define HUB_CHAR_TTTT 0x0060 /* TT Think Time mask */
217#define HUB_CHAR_PORTIND 0x0080 /* per-port indicators (LEDs) */
218
219struct usb_hub_status {
220 __le16 wHubStatus;
221 __le16 wHubChange;
222} __attribute__ ((packed));
223
224/*
225 * Hub Status & Hub Change bit masks
226 * See USB 2.0 spec Table 11-19 and Table 11-20
227 * Bits 0 and 1 for wHubStatus and wHubChange
228 * Bits 2 to 15 are reserved for both
229 */
230#define HUB_STATUS_LOCAL_POWER 0x0001
231#define HUB_STATUS_OVERCURRENT 0x0002
232#define HUB_CHANGE_LOCAL_POWER 0x0001
233#define HUB_CHANGE_OVERCURRENT 0x0002
234
235
236/*
237 * Hub descriptor
238 * See USB 2.0 spec Table 11-13
239 */
240
241#define USB_DT_HUB (USB_TYPE_CLASS | 0x09)
242#define USB_DT_SS_HUB (USB_TYPE_CLASS | 0x0a)
243#define USB_DT_HUB_NONVAR_SIZE 7
244#define USB_DT_SS_HUB_SIZE 12
245
246/*
247 * Hub Device descriptor
248 * USB Hub class device protocols
249 */
250
251#define USB_HUB_PR_FS 0 /* Full speed hub */
252#define USB_HUB_PR_HS_NO_TT 0 /* Hi-speed hub without TT */
253#define USB_HUB_PR_HS_SINGLE_TT 1 /* Hi-speed hub with single TT */
254#define USB_HUB_PR_HS_MULTI_TT 2 /* Hi-speed hub with multiple TT */
255#define USB_HUB_PR_SS 3 /* Super speed hub */
256
257struct usb_hub_descriptor {
258 __u8 bDescLength;
259 __u8 bDescriptorType;
260 __u8 bNbrPorts;
261 __le16 wHubCharacteristics;
262 __u8 bPwrOn2PwrGood;
263 __u8 bHubContrCurrent;
264
265 /* 2.0 and 3.0 hubs differ here */
266 union {
267 struct {
268 /* add 1 bit for hub status change; round to bytes */
269 __u8 DeviceRemovable[(USB_MAXCHILDREN + 1 + 7) / 8];
270 __u8 PortPwrCtrlMask[(USB_MAXCHILDREN + 1 + 7) / 8];
271 } __attribute__ ((packed)) hs;
272
273 struct {
274 __u8 bHubHdrDecLat;
275 __le16 wHubDelay;
276 __le16 DeviceRemovable;
277 } __attribute__ ((packed)) ss;
278 } u;
279} __attribute__ ((packed));
280
281/* port indicator status selectors, tables 11-7 and 11-25 */
282#define HUB_LED_AUTO 0
283#define HUB_LED_AMBER 1
284#define HUB_LED_GREEN 2
285#define HUB_LED_OFF 3
286
287enum hub_led_mode {
288 INDICATOR_AUTO = 0,
289 INDICATOR_CYCLE,
290 /* software blinks for attention: software, hardware, reserved */
291 INDICATOR_GREEN_BLINK, INDICATOR_GREEN_BLINK_OFF,
292 INDICATOR_AMBER_BLINK, INDICATOR_AMBER_BLINK_OFF,
293 INDICATOR_ALT_BLINK, INDICATOR_ALT_BLINK_OFF
294} __attribute__ ((packed));
295
296/* Transaction Translator Think Times, in bits */
297#define HUB_TTTT_8_BITS 0x00
298#define HUB_TTTT_16_BITS 0x20
299#define HUB_TTTT_24_BITS 0x40
300#define HUB_TTTT_32_BITS 0x60
301
302#endif /* __LINUX_CH11_H */