linux/usb/ch11.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 /*
0003  * This file holds Hub protocol constants and data structures that are
0004  * defined in chapter 11 (Hub Specification) of the USB 2.0 specification.
0005  *
0006  * It is used/shared between the USB core, the HCDs and couple of other USB
0007  * drivers.
0008  */
0009
0010 #ifndef __LINUX_CH11_H
0011 #define __LINUX_CH11_H
0012
0013 #include <linux/types.h>    /* __u8 etc */
0014
0015 /* This is arbitrary.
0016  * From USB 2.0 spec Table 11-13, offset 7, a hub can
0017  * have up to 255 ports. The most yet reported is 10.
0018  *
0019  * Current Wireless USB host hardware (Intel i1480 for example) allows
0020  * up to 22 devices to connect. Upcoming hardware might raise that
0021  * limit. Because the arrays need to add a bit for hub status data, we
0022  * use 31, so plus one evens out to four bytes.
0023  */
0024 #define USB_MAXCHILDREN     31
0025
0026 /* See USB 3.1 spec Table 10-5 */
0027 #define USB_SS_MAXPORTS     15
0028
0029 /*
0030  * Hub request types
0031  */
0032
0033 #define USB_RT_HUB  (USB_TYPE_CLASS | USB_RECIP_DEVICE)
0034 #define USB_RT_PORT (USB_TYPE_CLASS | USB_RECIP_OTHER)
0035
0036 /*
0037  * Port status type for GetPortStatus requests added in USB 3.1
0038  * See USB 3.1 spec Table 10-12
0039  */
0040 #define HUB_PORT_STATUS     0
0041 #define HUB_PORT_PD_STATUS  1
0042 #define HUB_EXT_PORT_STATUS 2
0043
0044 /*
0045  * Hub class requests
0046  * See USB 2.0 spec Table 11-16
0047  */
0048 #define HUB_CLEAR_TT_BUFFER 8
0049 #define HUB_RESET_TT        9
0050 #define HUB_GET_TT_STATE    10
0051 #define HUB_STOP_TT     11
0052
0053 /*
0054  * Hub class additional requests defined by USB 3.0 spec
0055  * See USB 3.0 spec Table 10-6
0056  */
0057 #define HUB_SET_DEPTH       12
0058 #define HUB_GET_PORT_ERR_COUNT  13
0059
0060 /*
0061  * Hub Class feature numbers
0062  * See USB 2.0 spec Table 11-17
0063  */
0064 #define C_HUB_LOCAL_POWER   0
0065 #define C_HUB_OVER_CURRENT  1
0066
0067 /*
0068  * Port feature numbers
0069  * See USB 2.0 spec Table 11-17
0070  */
0071 #define USB_PORT_FEAT_CONNECTION    0
0072 #define USB_PORT_FEAT_ENABLE        1
0073 #define USB_PORT_FEAT_SUSPEND       2   /* L2 suspend */
0074 #define USB_PORT_FEAT_OVER_CURRENT  3
0075 #define USB_PORT_FEAT_RESET     4
0076 #define USB_PORT_FEAT_L1        5   /* L1 suspend */
0077 #define USB_PORT_FEAT_POWER     8
0078 #define USB_PORT_FEAT_LOWSPEED      9   /* Should never be used */
0079 #define USB_PORT_FEAT_C_CONNECTION  16
0080 #define USB_PORT_FEAT_C_ENABLE      17
0081 #define USB_PORT_FEAT_C_SUSPEND     18
0082 #define USB_PORT_FEAT_C_OVER_CURRENT    19
0083 #define USB_PORT_FEAT_C_RESET       20
0084 #define USB_PORT_FEAT_TEST              21
0085 #define USB_PORT_FEAT_INDICATOR         22
0086 #define USB_PORT_FEAT_C_PORT_L1         23
0087
0088 /*
0089  * Port feature selectors added by USB 3.0 spec.
0090  * See USB 3.0 spec Table 10-7
0091  */
0092 #define USB_PORT_FEAT_LINK_STATE        5
0093 #define USB_PORT_FEAT_U1_TIMEOUT        23
0094 #define USB_PORT_FEAT_U2_TIMEOUT        24
0095 #define USB_PORT_FEAT_C_PORT_LINK_STATE     25
0096 #define USB_PORT_FEAT_C_PORT_CONFIG_ERROR   26
0097 #define USB_PORT_FEAT_REMOTE_WAKE_MASK      27
0098 #define USB_PORT_FEAT_BH_PORT_RESET     28
0099 #define USB_PORT_FEAT_C_BH_PORT_RESET       29
0100 #define USB_PORT_FEAT_FORCE_LINKPM_ACCEPT   30
0101
0102 #define USB_PORT_LPM_TIMEOUT(p)         (((p) & 0xff) << 8)
0103
0104 /* USB 3.0 hub remote wake mask bits, see table 10-14 */
0105 #define USB_PORT_FEAT_REMOTE_WAKE_CONNECT   (1 << 8)
0106 #define USB_PORT_FEAT_REMOTE_WAKE_DISCONNECT    (1 << 9)
0107 #define USB_PORT_FEAT_REMOTE_WAKE_OVER_CURRENT  (1 << 10)
0108
0109 /*
0110  * Hub Status and Hub Change results
0111  * See USB 2.0 spec Table 11-19 and Table 11-20
0112  * USB 3.1 extends the port status request and may return 4 additional bytes.
0113  * See USB 3.1 spec section 10.16.2.6 Table 10-12 and 10-15
0114  */
0115 struct usb_port_status {
0116     __le16 wPortStatus;
0117     __le16 wPortChange;
0118     __le32 dwExtPortStatus;
0119 } __attribute__ ((packed));
0120
0121 /*
0122  * wPortStatus bit field
0123  * See USB 2.0 spec Table 11-21
0124  */
0125 #define USB_PORT_STAT_CONNECTION    0x0001
0126 #define USB_PORT_STAT_ENABLE        0x0002
0127 #define USB_PORT_STAT_SUSPEND       0x0004
0128 #define USB_PORT_STAT_OVERCURRENT   0x0008
0129 #define USB_PORT_STAT_RESET     0x0010
0130 #define USB_PORT_STAT_L1        0x0020
0131 /* bits 6 to 7 are reserved */
0132 #define USB_PORT_STAT_POWER     0x0100
0133 #define USB_PORT_STAT_LOW_SPEED     0x0200
0134 #define USB_PORT_STAT_HIGH_SPEED        0x0400
0135 #define USB_PORT_STAT_TEST              0x0800
0136 #define USB_PORT_STAT_INDICATOR         0x1000
0137 /* bits 13 to 15 are reserved */
0138
0139 /*
0140  * Additions to wPortStatus bit field from USB 3.0
0141  * See USB 3.0 spec Table 10-10
0142  */
0143 #define USB_PORT_STAT_LINK_STATE    0x01e0
0144 #define USB_SS_PORT_STAT_POWER      0x0200
0145 #define USB_SS_PORT_STAT_SPEED      0x1c00
0146 #define USB_PORT_STAT_SPEED_5GBPS   0x0000
0147 /* Valid only if port is enabled */
0148 /* Bits that are the same from USB 2.0 */
0149 #define USB_SS_PORT_STAT_MASK (USB_PORT_STAT_CONNECTION |       \
0150                 USB_PORT_STAT_ENABLE |      \
0151                 USB_PORT_STAT_OVERCURRENT | \
0152                 USB_PORT_STAT_RESET)
0153
0154 /*
0155  * Definitions for PORT_LINK_STATE values
0156  * (bits 5-8) in wPortStatus
0157  */
0158 #define USB_SS_PORT_LS_U0       0x0000
0159 #define USB_SS_PORT_LS_U1       0x0020
0160 #define USB_SS_PORT_LS_U2       0x0040
0161 #define USB_SS_PORT_LS_U3       0x0060
0162 #define USB_SS_PORT_LS_SS_DISABLED  0x0080
0163 #define USB_SS_PORT_LS_RX_DETECT    0x00a0
0164 #define USB_SS_PORT_LS_SS_INACTIVE  0x00c0
0165 #define USB_SS_PORT_LS_POLLING      0x00e0
0166 #define USB_SS_PORT_LS_RECOVERY     0x0100
0167 #define USB_SS_PORT_LS_HOT_RESET    0x0120
0168 #define USB_SS_PORT_LS_COMP_MOD     0x0140
0169 #define USB_SS_PORT_LS_LOOPBACK     0x0160
0170
0171 /*
0172  * wPortChange bit field
0173  * See USB 2.0 spec Table 11-22 and USB 2.0 LPM ECN Table-4.10
0174  * Bits 0 to 5 shown, bits 6 to 15 are reserved
0175  */
0176 #define USB_PORT_STAT_C_CONNECTION  0x0001
0177 #define USB_PORT_STAT_C_ENABLE      0x0002
0178 #define USB_PORT_STAT_C_SUSPEND     0x0004
0179 #define USB_PORT_STAT_C_OVERCURRENT 0x0008
0180 #define USB_PORT_STAT_C_RESET       0x0010
0181 #define USB_PORT_STAT_C_L1      0x0020
0182 /*
0183  * USB 3.0 wPortChange bit fields
0184  * See USB 3.0 spec Table 10-11
0185  */
0186 #define USB_PORT_STAT_C_BH_RESET    0x0020
0187 #define USB_PORT_STAT_C_LINK_STATE  0x0040
0188 #define USB_PORT_STAT_C_CONFIG_ERROR    0x0080
0189
0190 /*
0191  * USB 3.1 dwExtPortStatus field masks
0192  * See USB 3.1 spec 10.16.2.6.3 Table 10-15
0193  */
0194
0195 #define USB_EXT_PORT_STAT_RX_SPEED_ID   0x0000000f
0196 #define USB_EXT_PORT_STAT_TX_SPEED_ID   0x000000f0
0197 #define USB_EXT_PORT_STAT_RX_LANES  0x00000f00
0198 #define USB_EXT_PORT_STAT_TX_LANES  0x0000f000
0199
0200 #define USB_EXT_PORT_RX_LANES(p) \
0201             (((p) & USB_EXT_PORT_STAT_RX_LANES) >> 8)
0202 #define USB_EXT_PORT_TX_LANES(p) \
0203             (((p) & USB_EXT_PORT_STAT_TX_LANES) >> 12)
0204
0205 /*
0206  * wHubCharacteristics (masks)
0207  * See USB 2.0 spec Table 11-13, offset 3
0208  */
0209 #define HUB_CHAR_LPSM       0x0003 /* Logical Power Switching Mode mask */
0210 #define HUB_CHAR_COMMON_LPSM    0x0000 /* All ports power control at once */
0211 #define HUB_CHAR_INDV_PORT_LPSM 0x0001 /* per-port power control */
0212 #define HUB_CHAR_NO_LPSM    0x0002 /* no power switching */
0213
0214 #define HUB_CHAR_COMPOUND   0x0004 /* hub is part of a compound device */
0215
0216 #define HUB_CHAR_OCPM       0x0018 /* Over-Current Protection Mode mask */
0217 #define HUB_CHAR_COMMON_OCPM    0x0000 /* All ports Over-Current reporting */
0218 #define HUB_CHAR_INDV_PORT_OCPM 0x0008 /* per-port Over-current reporting */
0219 #define HUB_CHAR_NO_OCPM    0x0010 /* No Over-current Protection support */
0220
0221 #define HUB_CHAR_TTTT       0x0060 /* TT Think Time mask */
0222 #define HUB_CHAR_PORTIND    0x0080 /* per-port indicators (LEDs) */
0223
0224 struct usb_hub_status {
0225     __le16 wHubStatus;
0226     __le16 wHubChange;
0227 } __attribute__ ((packed));
0228
0229 /*
0230  * Hub Status & Hub Change bit masks
0231  * See USB 2.0 spec Table 11-19 and Table 11-20
0232  * Bits 0 and 1 for wHubStatus and wHubChange
0233  * Bits 2 to 15 are reserved for both
0234  */
0235 #define HUB_STATUS_LOCAL_POWER  0x0001
0236 #define HUB_STATUS_OVERCURRENT  0x0002
0237 #define HUB_CHANGE_LOCAL_POWER  0x0001
0238 #define HUB_CHANGE_OVERCURRENT  0x0002
0239
0240
0241 /*
0242  * Hub descriptor
0243  * See USB 2.0 spec Table 11-13
0244  */
0245
0246 #define USB_DT_HUB          (USB_TYPE_CLASS | 0x09)
0247 #define USB_DT_SS_HUB           (USB_TYPE_CLASS | 0x0a)
0248 #define USB_DT_HUB_NONVAR_SIZE      7
0249 #define USB_DT_SS_HUB_SIZE              12
0250
0251 /*
0252  * Hub Device descriptor
0253  * USB Hub class device protocols
0254  */
0255
0256 #define USB_HUB_PR_FS       0 /* Full speed hub */
0257 #define USB_HUB_PR_HS_NO_TT 0 /* Hi-speed hub without TT */
0258 #define USB_HUB_PR_HS_SINGLE_TT 1 /* Hi-speed hub with single TT */
0259 #define USB_HUB_PR_HS_MULTI_TT  2 /* Hi-speed hub with multiple TT */
0260 #define USB_HUB_PR_SS       3 /* Super speed hub */
0261
0262 struct usb_hub_descriptor {
0263     __u8  bDescLength;
0264     __u8  bDescriptorType;
0265     __u8  bNbrPorts;
0266     __le16 wHubCharacteristics;
0267     __u8  bPwrOn2PwrGood;
0268     __u8  bHubContrCurrent;
0269
0270     /* 2.0 and 3.0 hubs differ here */
0271     union {
0272         struct {
0273             /* add 1 bit for hub status change; round to bytes */
0274             __u8  DeviceRemovable[(USB_MAXCHILDREN + 1 + 7) / 8];
0275             __u8  PortPwrCtrlMask[(USB_MAXCHILDREN + 1 + 7) / 8];
0276         }  __attribute__ ((packed)) hs;
0277
0278         struct {
0279             __u8 bHubHdrDecLat;
0280             __le16 wHubDelay;
0281             __le16 DeviceRemovable;
0282         }  __attribute__ ((packed)) ss;
0283     } u;
0284 } __attribute__ ((packed));
0285
0286 /* port indicator status selectors, tables 11-7 and 11-25 */
0287 #define HUB_LED_AUTO    0
0288 #define HUB_LED_AMBER   1
0289 #define HUB_LED_GREEN   2
0290 #define HUB_LED_OFF 3
0291
0292 enum hub_led_mode {
0293     INDICATOR_AUTO = 0,
0294     INDICATOR_CYCLE,
0295     /* software blinks for attention:  software, hardware, reserved */
0296     INDICATOR_GREEN_BLINK, INDICATOR_GREEN_BLINK_OFF,
0297     INDICATOR_AMBER_BLINK, INDICATOR_AMBER_BLINK_OFF,
0298     INDICATOR_ALT_BLINK, INDICATOR_ALT_BLINK_OFF
0299 } __attribute__ ((packed));
0300
0301 /* Transaction Translator Think Times, in bits */
0302 #define HUB_TTTT_8_BITS     0x00
0303 #define HUB_TTTT_16_BITS    0x20
0304 #define HUB_TTTT_24_BITS    0x40
0305 #define HUB_TTTT_32_BITS    0x60
0306
0307 #endif /* __LINUX_CH11_H */