include/uapi/linux/usb/ch11.h

   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 */