include/uapi/linux/usb/cdc.h

   1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
   2 /*
   3  * USB Communications Device Class (CDC) definitions
   4  *
   5  * CDC says how to talk to lots of different types of network adapters,
   6  * notably ethernet adapters and various modems.  It's used mostly with
   7  * firmware based USB peripherals.
   8  */
   9
  10 #ifndef __UAPI_LINUX_USB_CDC_H
  11 #define __UAPI_LINUX_USB_CDC_H
  12
  13 #include <linux/types.h>
  14
  15 #define USB_CDC_SUBCLASS_ACM                    0x02
  16 #define USB_CDC_SUBCLASS_ETHERNET               0x06
  17 #define USB_CDC_SUBCLASS_WHCM                   0x08
  18 #define USB_CDC_SUBCLASS_DMM                    0x09
  19 #define USB_CDC_SUBCLASS_MDLM                   0x0a
  20 #define USB_CDC_SUBCLASS_OBEX                   0x0b
  21 #define USB_CDC_SUBCLASS_EEM                    0x0c
  22 #define USB_CDC_SUBCLASS_NCM                    0x0d
  23 #define USB_CDC_SUBCLASS_MBIM                   0x0e
  24
  25 #define USB_CDC_PROTO_NONE                      0
  26
  27 #define USB_CDC_ACM_PROTO_AT_V25TER             1
  28 #define USB_CDC_ACM_PROTO_AT_PCCA101            2
  29 #define USB_CDC_ACM_PROTO_AT_PCCA101_WAKE       3
  30 #define USB_CDC_ACM_PROTO_AT_GSM                4
  31 #define USB_CDC_ACM_PROTO_AT_3G                 5
  32 #define USB_CDC_ACM_PROTO_AT_CDMA               6
  33 #define USB_CDC_ACM_PROTO_VENDOR                0xff
  34
  35 #define USB_CDC_PROTO_EEM                       7
  36
  37 #define USB_CDC_NCM_PROTO_NTB                   1
  38 #define USB_CDC_MBIM_PROTO_NTB                  2
  39
  40 /*-------------------------------------------------------------------------*/
  41
  42 /*
  43  * Class-Specific descriptors ... there are a couple dozen of them
  44  */
  45
  46 #define USB_CDC_HEADER_TYPE             0x00    /* header_desc */
  47 #define USB_CDC_CALL_MANAGEMENT_TYPE    0x01    /* call_mgmt_descriptor */
  48 #define USB_CDC_ACM_TYPE                0x02    /* acm_descriptor */
  49 #define USB_CDC_UNION_TYPE              0x06    /* union_desc */
  50 #define USB_CDC_COUNTRY_TYPE            0x07
  51 #define USB_CDC_NETWORK_TERMINAL_TYPE   0x0a    /* network_terminal_desc */
  52 #define USB_CDC_ETHERNET_TYPE           0x0f    /* ether_desc */
  53 #define USB_CDC_WHCM_TYPE               0x11
  54 #define USB_CDC_MDLM_TYPE               0x12    /* mdlm_desc */
  55 #define USB_CDC_MDLM_DETAIL_TYPE        0x13    /* mdlm_detail_desc */
  56 #define USB_CDC_DMM_TYPE                0x14
  57 #define USB_CDC_OBEX_TYPE               0x15
  58 #define USB_CDC_NCM_TYPE                0x1a
  59 #define USB_CDC_MBIM_TYPE               0x1b
  60 #define USB_CDC_MBIM_EXTENDED_TYPE      0x1c
  61
  62 /* "Header Functional Descriptor" from CDC spec  5.2.3.1 */
  63 struct usb_cdc_header_desc {
  64         __u8    bLength;
  65         __u8    bDescriptorType;
  66         __u8    bDescriptorSubType;
  67
  68         __le16  bcdCDC;
  69 } __attribute__ ((packed));
  70
  71 /* "Call Management Descriptor" from CDC spec  5.2.3.2 */
  72 struct usb_cdc_call_mgmt_descriptor {
  73         __u8    bLength;
  74         __u8    bDescriptorType;
  75         __u8    bDescriptorSubType;
  76
  77         __u8    bmCapabilities;
  78 #define USB_CDC_CALL_MGMT_CAP_CALL_MGMT         0x01
  79 #define USB_CDC_CALL_MGMT_CAP_DATA_INTF         0x02
  80
  81         __u8    bDataInterface;
  82 } __attribute__ ((packed));
  83
  84 /* "Abstract Control Management Descriptor" from CDC spec  5.2.3.3 */
  85 struct usb_cdc_acm_descriptor {
  86         __u8    bLength;
  87         __u8    bDescriptorType;
  88         __u8    bDescriptorSubType;
  89
  90         __u8    bmCapabilities;
  91 } __attribute__ ((packed));
  92
  93 /* capabilities from 5.2.3.3 */
  94
  95 #define USB_CDC_COMM_FEATURE    0x01
  96 #define USB_CDC_CAP_LINE        0x02
  97 #define USB_CDC_CAP_BRK         0x04
  98 #define USB_CDC_CAP_NOTIFY      0x08
  99
 100 /* "Union Functional Descriptor" from CDC spec 5.2.3.8 */
 101 struct usb_cdc_union_desc {
 102         __u8    bLength;
 103         __u8    bDescriptorType;
 104         __u8    bDescriptorSubType;
 105
 106         __u8    bMasterInterface0;
 107         __u8    bSlaveInterface0;
 108         /* ... and there could be other slave interfaces */
 109 } __attribute__ ((packed));
 110
 111 /* "Country Selection Functional Descriptor" from CDC spec 5.2.3.9 */
 112 struct usb_cdc_country_functional_desc {
 113         __u8    bLength;
 114         __u8    bDescriptorType;
 115         __u8    bDescriptorSubType;
 116
 117         __u8    iCountryCodeRelDate;
 118         __le16  wCountyCode0;
 119         /* ... and there can be a lot of country codes */
 120 } __attribute__ ((packed));
 121
 122 /* "Network Channel Terminal Functional Descriptor" from CDC spec 5.2.3.11 */
 123 struct usb_cdc_network_terminal_desc {
 124         __u8    bLength;
 125         __u8    bDescriptorType;
 126         __u8    bDescriptorSubType;
 127
 128         __u8    bEntityId;
 129         __u8    iName;
 130         __u8    bChannelIndex;
 131         __u8    bPhysicalInterface;
 132 } __attribute__ ((packed));
 133
 134 /* "Ethernet Networking Functional Descriptor" from CDC spec 5.2.3.16 */
 135 struct usb_cdc_ether_desc {
 136         __u8    bLength;
 137         __u8    bDescriptorType;
 138         __u8    bDescriptorSubType;
 139
 140         __u8    iMACAddress;
 141         __le32  bmEthernetStatistics;
 142         __le16  wMaxSegmentSize;
 143         __le16  wNumberMCFilters;
 144         __u8    bNumberPowerFilters;
 145 } __attribute__ ((packed));
 146
 147 /* "Telephone Control Model Functional Descriptor" from CDC WMC spec 6.3..3 */
 148 struct usb_cdc_dmm_desc {
 149         __u8    bFunctionLength;
 150         __u8    bDescriptorType;
 151         __u8    bDescriptorSubtype;
 152         __u16   bcdVersion;
 153         __le16  wMaxCommand;
 154 } __attribute__ ((packed));
 155
 156 /* "MDLM Functional Descriptor" from CDC WMC spec 6.7.2.3 */
 157 struct usb_cdc_mdlm_desc {
 158         __u8    bLength;
 159         __u8    bDescriptorType;
 160         __u8    bDescriptorSubType;
 161
 162         __le16  bcdVersion;
 163         __u8    bGUID[16];
 164 } __attribute__ ((packed));
 165
 166 /* "MDLM Detail Functional Descriptor" from CDC WMC spec 6.7.2.4 */
 167 struct usb_cdc_mdlm_detail_desc {
 168         __u8    bLength;
 169         __u8    bDescriptorType;
 170         __u8    bDescriptorSubType;
 171
 172         /* type is associated with mdlm_desc.bGUID */
 173         __u8    bGuidDescriptorType;
 174         __u8    bDetailData[];
 175 } __attribute__ ((packed));
 176
 177 /* "OBEX Control Model Functional Descriptor" */
 178 struct usb_cdc_obex_desc {
 179         __u8    bLength;
 180         __u8    bDescriptorType;
 181         __u8    bDescriptorSubType;
 182
 183         __le16  bcdVersion;
 184 } __attribute__ ((packed));
 185
 186 /* "NCM Control Model Functional Descriptor" */
 187 struct usb_cdc_ncm_desc {
 188         __u8    bLength;
 189         __u8    bDescriptorType;
 190         __u8    bDescriptorSubType;
 191
 192         __le16  bcdNcmVersion;
 193         __u8    bmNetworkCapabilities;
 194 } __attribute__ ((packed));
 195
 196 /* "MBIM Control Model Functional Descriptor" */
 197 struct usb_cdc_mbim_desc {
 198         __u8    bLength;
 199         __u8    bDescriptorType;
 200         __u8    bDescriptorSubType;
 201
 202         __le16  bcdMBIMVersion;
 203         __le16  wMaxControlMessage;
 204         __u8    bNumberFilters;
 205         __u8    bMaxFilterSize;
 206         __le16  wMaxSegmentSize;
 207         __u8    bmNetworkCapabilities;
 208 } __attribute__ ((packed));
 209
 210 /* "MBIM Extended Functional Descriptor" from CDC MBIM spec 1.0 errata-1 */
 211 struct usb_cdc_mbim_extended_desc {
 212         __u8    bLength;
 213         __u8    bDescriptorType;
 214         __u8    bDescriptorSubType;
 215
 216         __le16  bcdMBIMExtendedVersion;
 217         __u8    bMaxOutstandingCommandMessages;
 218         __le16  wMTU;
 219 } __attribute__ ((packed));
 220
 221 /*-------------------------------------------------------------------------*/
 222
 223 /*
 224  * Class-Specific Control Requests (6.2)
 225  *
 226  * section 3.6.2.1 table 4 has the ACM profile, for modems.
 227  * section 3.8.2 table 10 has the ethernet profile.
 228  *
 229  * Microsoft's RNDIS stack for Ethernet is a vendor-specific CDC ACM variant,
 230  * heavily dependent on the encapsulated (proprietary) command mechanism.
 231  */
 232
 233 #define USB_CDC_SEND_ENCAPSULATED_COMMAND       0x00
 234 #define USB_CDC_GET_ENCAPSULATED_RESPONSE       0x01
 235 #define USB_CDC_REQ_SET_LINE_CODING             0x20
 236 #define USB_CDC_REQ_GET_LINE_CODING             0x21
 237 #define USB_CDC_REQ_SET_CONTROL_LINE_STATE      0x22
 238 #define USB_CDC_REQ_SEND_BREAK                  0x23
 239 #define USB_CDC_SET_ETHERNET_MULTICAST_FILTERS  0x40
 240 #define USB_CDC_SET_ETHERNET_PM_PATTERN_FILTER  0x41
 241 #define USB_CDC_GET_ETHERNET_PM_PATTERN_FILTER  0x42
 242 #define USB_CDC_SET_ETHERNET_PACKET_FILTER      0x43
 243 #define USB_CDC_GET_ETHERNET_STATISTIC          0x44
 244 #define USB_CDC_GET_NTB_PARAMETERS              0x80
 245 #define USB_CDC_GET_NET_ADDRESS                 0x81
 246 #define USB_CDC_SET_NET_ADDRESS                 0x82
 247 #define USB_CDC_GET_NTB_FORMAT                  0x83
 248 #define USB_CDC_SET_NTB_FORMAT                  0x84
 249 #define USB_CDC_GET_NTB_INPUT_SIZE              0x85
 250 #define USB_CDC_SET_NTB_INPUT_SIZE              0x86
 251 #define USB_CDC_GET_MAX_DATAGRAM_SIZE           0x87
 252 #define USB_CDC_SET_MAX_DATAGRAM_SIZE           0x88
 253 #define USB_CDC_GET_CRC_MODE                    0x89
 254 #define USB_CDC_SET_CRC_MODE                    0x8a
 255
 256 /* Line Coding Structure from CDC spec 6.2.13 */
 257 struct usb_cdc_line_coding {
 258         __le32  dwDTERate;
 259         __u8    bCharFormat;
 260 #define USB_CDC_1_STOP_BITS                     0
 261 #define USB_CDC_1_5_STOP_BITS                   1
 262 #define USB_CDC_2_STOP_BITS                     2
 263
 264         __u8    bParityType;
 265 #define USB_CDC_NO_PARITY                       0
 266 #define USB_CDC_ODD_PARITY                      1
 267 #define USB_CDC_EVEN_PARITY                     2
 268 #define USB_CDC_MARK_PARITY                     3
 269 #define USB_CDC_SPACE_PARITY                    4
 270
 271         __u8    bDataBits;
 272 } __attribute__ ((packed));
 273
 274 /* Control Signal Bitmap Values from 6.2.14 SetControlLineState */
 275 #define USB_CDC_CTRL_DTR                        (1 << 0)
 276 #define USB_CDC_CTRL_RTS                        (1 << 1)
 277
 278 /* table 62; bits in multicast filter */
 279 #define USB_CDC_PACKET_TYPE_PROMISCUOUS         (1 << 0)
 280 #define USB_CDC_PACKET_TYPE_ALL_MULTICAST       (1 << 1) /* no filter */
 281 #define USB_CDC_PACKET_TYPE_DIRECTED            (1 << 2)
 282 #define USB_CDC_PACKET_TYPE_BROADCAST           (1 << 3)
 283 #define USB_CDC_PACKET_TYPE_MULTICAST           (1 << 4) /* filtered */
 284
 285
 286 /*-------------------------------------------------------------------------*/
 287
 288 /*
 289  * Class-Specific Notifications (6.3) sent by interrupt transfers
 290  *
 291  * section 3.8.2 table 11 of the CDC spec lists Ethernet notifications
 292  * section 3.6.2.1 table 5 specifies ACM notifications, accepted by RNDIS
 293  * RNDIS also defines its own bit-incompatible notifications
 294  */
 295
 296 #define USB_CDC_NOTIFY_NETWORK_CONNECTION       0x00
 297 #define USB_CDC_NOTIFY_RESPONSE_AVAILABLE       0x01
 298 #define USB_CDC_NOTIFY_SERIAL_STATE             0x20
 299 #define USB_CDC_NOTIFY_SPEED_CHANGE             0x2a
 300
 301 struct usb_cdc_notification {
 302         __u8    bmRequestType;
 303         __u8    bNotificationType;
 304         __le16  wValue;
 305         __le16  wIndex;
 306         __le16  wLength;
 307 } __attribute__ ((packed));
 308
 309 /* UART State Bitmap Values from 6.3.5 SerialState */
 310 #define USB_CDC_SERIAL_STATE_DCD                (1 << 0)
 311 #define USB_CDC_SERIAL_STATE_DSR                (1 << 1)
 312 #define USB_CDC_SERIAL_STATE_BREAK              (1 << 2)
 313 #define USB_CDC_SERIAL_STATE_RING_SIGNAL        (1 << 3)
 314 #define USB_CDC_SERIAL_STATE_FRAMING            (1 << 4)
 315 #define USB_CDC_SERIAL_STATE_PARITY             (1 << 5)
 316 #define USB_CDC_SERIAL_STATE_OVERRUN            (1 << 6)
 317
 318 struct usb_cdc_speed_change {
 319         __le32  DLBitRRate;     /* contains the downlink bit rate (IN pipe) */
 320         __le32  ULBitRate;      /* contains the uplink bit rate (OUT pipe) */
 321 } __attribute__ ((packed));
 322
 323 /*-------------------------------------------------------------------------*/
 324
 325 /*
 326  * Class Specific structures and constants
 327  *
 328  * CDC NCM NTB parameters structure, CDC NCM subclass 6.2.1
 329  *
 330  */
 331
 332 struct usb_cdc_ncm_ntb_parameters {
 333         __le16  wLength;
 334         __le16  bmNtbFormatsSupported;
 335         __le32  dwNtbInMaxSize;
 336         __le16  wNdpInDivisor;
 337         __le16  wNdpInPayloadRemainder;
 338         __le16  wNdpInAlignment;
 339         __le16  wPadding1;
 340         __le32  dwNtbOutMaxSize;
 341         __le16  wNdpOutDivisor;
 342         __le16  wNdpOutPayloadRemainder;
 343         __le16  wNdpOutAlignment;
 344         __le16  wNtbOutMaxDatagrams;
 345 } __attribute__ ((packed));
 346
 347 /*
 348  * CDC NCM transfer headers, CDC NCM subclass 3.2
 349  */
 350
 351 #define USB_CDC_NCM_NTH16_SIGN          0x484D434E /* NCMH */
 352 #define USB_CDC_NCM_NTH32_SIGN          0x686D636E /* ncmh */
 353
 354 struct usb_cdc_ncm_nth16 {
 355         __le32  dwSignature;
 356         __le16  wHeaderLength;
 357         __le16  wSequence;
 358         __le16  wBlockLength;
 359         __le16  wNdpIndex;
 360 } __attribute__ ((packed));
 361
 362 struct usb_cdc_ncm_nth32 {
 363         __le32  dwSignature;
 364         __le16  wHeaderLength;
 365         __le16  wSequence;
 366         __le32  dwBlockLength;
 367         __le32  dwNdpIndex;
 368 } __attribute__ ((packed));
 369
 370 /*
 371  * CDC NCM datagram pointers, CDC NCM subclass 3.3
 372  */
 373
 374 #define USB_CDC_NCM_NDP16_CRC_SIGN      0x314D434E /* NCM1 */
 375 #define USB_CDC_NCM_NDP16_NOCRC_SIGN    0x304D434E /* NCM0 */
 376 #define USB_CDC_NCM_NDP32_CRC_SIGN      0x316D636E /* ncm1 */
 377 #define USB_CDC_NCM_NDP32_NOCRC_SIGN    0x306D636E /* ncm0 */
 378
 379 #define USB_CDC_MBIM_NDP16_IPS_SIGN     0x00535049 /* IPS<sessionID> : IPS0 for now */
 380 #define USB_CDC_MBIM_NDP32_IPS_SIGN     0x00737069 /* ips<sessionID> : ips0 for now */
 381 #define USB_CDC_MBIM_NDP16_DSS_SIGN     0x00535344 /* DSS<sessionID> */
 382 #define USB_CDC_MBIM_NDP32_DSS_SIGN     0x00737364 /* dss<sessionID> */
 383
 384 /* 16-bit NCM Datagram Pointer Entry */
 385 struct usb_cdc_ncm_dpe16 {
 386         __le16  wDatagramIndex;
 387         __le16  wDatagramLength;
 388 } __attribute__((__packed__));
 389
 390 /* 16-bit NCM Datagram Pointer Table */
 391 struct usb_cdc_ncm_ndp16 {
 392         __le32  dwSignature;
 393         __le16  wLength;
 394         __le16  wNextNdpIndex;
 395         struct  usb_cdc_ncm_dpe16 dpe16[];
 396 } __attribute__ ((packed));
 397
 398 /* 32-bit NCM Datagram Pointer Entry */
 399 struct usb_cdc_ncm_dpe32 {
 400         __le32  dwDatagramIndex;
 401         __le32  dwDatagramLength;
 402 } __attribute__((__packed__));
 403
 404 /* 32-bit NCM Datagram Pointer Table */
 405 struct usb_cdc_ncm_ndp32 {
 406         __le32  dwSignature;
 407         __le16  wLength;
 408         __le16  wReserved6;
 409         __le32  dwNextNdpIndex;
 410         __le32  dwReserved12;
 411         struct  usb_cdc_ncm_dpe32 dpe32[];
 412 } __attribute__ ((packed));
 413
 414 /* CDC NCM subclass 3.2.1 and 3.2.2 */
 415 #define USB_CDC_NCM_NDP16_INDEX_MIN                     0x000C
 416 #define USB_CDC_NCM_NDP32_INDEX_MIN                     0x0010
 417
 418 /* CDC NCM subclass 3.3.3 Datagram Formatting */
 419 #define USB_CDC_NCM_DATAGRAM_FORMAT_CRC                 0x30
 420 #define USB_CDC_NCM_DATAGRAM_FORMAT_NOCRC               0X31
 421
 422 /* CDC NCM subclass 4.2 NCM Communications Interface Protocol Code */
 423 #define USB_CDC_NCM_PROTO_CODE_NO_ENCAP_COMMANDS        0x00
 424 #define USB_CDC_NCM_PROTO_CODE_EXTERN_PROTO             0xFE
 425
 426 /* CDC NCM subclass 5.2.1 NCM Functional Descriptor, bmNetworkCapabilities */
 427 #define USB_CDC_NCM_NCAP_ETH_FILTER                     (1 << 0)
 428 #define USB_CDC_NCM_NCAP_NET_ADDRESS                    (1 << 1)
 429 #define USB_CDC_NCM_NCAP_ENCAP_COMMAND                  (1 << 2)
 430 #define USB_CDC_NCM_NCAP_MAX_DATAGRAM_SIZE              (1 << 3)
 431 #define USB_CDC_NCM_NCAP_CRC_MODE                       (1 << 4)
 432 #define USB_CDC_NCM_NCAP_NTB_INPUT_SIZE                 (1 << 5)
 433
 434 /* CDC NCM subclass Table 6-3: NTB Parameter Structure */
 435 #define USB_CDC_NCM_NTB16_SUPPORTED                     (1 << 0)
 436 #define USB_CDC_NCM_NTB32_SUPPORTED                     (1 << 1)
 437
 438 /* CDC NCM subclass Table 6-3: NTB Parameter Structure */
 439 #define USB_CDC_NCM_NDP_ALIGN_MIN_SIZE                  0x04
 440 #define USB_CDC_NCM_NTB_MAX_LENGTH                      0x1C
 441
 442 /* CDC NCM subclass 6.2.5 SetNtbFormat */
 443 #define USB_CDC_NCM_NTB16_FORMAT                        0x00
 444 #define USB_CDC_NCM_NTB32_FORMAT                        0x01
 445
 446 /* CDC NCM subclass 6.2.7 SetNtbInputSize */
 447 #define USB_CDC_NCM_NTB_MIN_IN_SIZE                     2048
 448 #define USB_CDC_NCM_NTB_MIN_OUT_SIZE                    2048
 449
 450 /* NTB Input Size Structure */
 451 struct usb_cdc_ncm_ndp_input_size {
 452         __le32  dwNtbInMaxSize;
 453         __le16  wNtbInMaxDatagrams;
 454         __le16  wReserved;
 455 } __attribute__ ((packed));
 456
 457 /* CDC NCM subclass 6.2.11 SetCrcMode */
 458 #define USB_CDC_NCM_CRC_NOT_APPENDED                    0x00
 459 #define USB_CDC_NCM_CRC_APPENDED                        0x01
 460
 461 #endif /* __UAPI_LINUX_USB_CDC_H */