linux/usb/cdc.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 /*
0003  * USB Communications Device Class (CDC) definitions
0004  *
0005  * CDC says how to talk to lots of different types of network adapters,
0006  * notably ethernet adapters and various modems.  It's used mostly with
0007  * firmware based USB peripherals.
0008  */
0009
0010 #ifndef __UAPI_LINUX_USB_CDC_H
0011 #define __UAPI_LINUX_USB_CDC_H
0012
0013 #include <linux/types.h>
0014
0015 #define USB_CDC_SUBCLASS_ACM            0x02
0016 #define USB_CDC_SUBCLASS_ETHERNET       0x06
0017 #define USB_CDC_SUBCLASS_WHCM           0x08
0018 #define USB_CDC_SUBCLASS_DMM            0x09
0019 #define USB_CDC_SUBCLASS_MDLM           0x0a
0020 #define USB_CDC_SUBCLASS_OBEX           0x0b
0021 #define USB_CDC_SUBCLASS_EEM            0x0c
0022 #define USB_CDC_SUBCLASS_NCM            0x0d
0023 #define USB_CDC_SUBCLASS_MBIM           0x0e
0024
0025 #define USB_CDC_PROTO_NONE          0
0026
0027 #define USB_CDC_ACM_PROTO_AT_V25TER     1
0028 #define USB_CDC_ACM_PROTO_AT_PCCA101        2
0029 #define USB_CDC_ACM_PROTO_AT_PCCA101_WAKE   3
0030 #define USB_CDC_ACM_PROTO_AT_GSM        4
0031 #define USB_CDC_ACM_PROTO_AT_3G         5
0032 #define USB_CDC_ACM_PROTO_AT_CDMA       6
0033 #define USB_CDC_ACM_PROTO_VENDOR        0xff
0034
0035 #define USB_CDC_PROTO_EEM           7
0036
0037 #define USB_CDC_NCM_PROTO_NTB           1
0038 #define USB_CDC_MBIM_PROTO_NTB          2
0039
0040 /*-------------------------------------------------------------------------*/
0041
0042 /*
0043  * Class-Specific descriptors ... there are a couple dozen of them
0044  */
0045
0046 #define USB_CDC_HEADER_TYPE     0x00    /* header_desc */
0047 #define USB_CDC_CALL_MANAGEMENT_TYPE    0x01    /* call_mgmt_descriptor */
0048 #define USB_CDC_ACM_TYPE        0x02    /* acm_descriptor */
0049 #define USB_CDC_UNION_TYPE      0x06    /* union_desc */
0050 #define USB_CDC_COUNTRY_TYPE        0x07
0051 #define USB_CDC_NETWORK_TERMINAL_TYPE   0x0a    /* network_terminal_desc */
0052 #define USB_CDC_ETHERNET_TYPE       0x0f    /* ether_desc */
0053 #define USB_CDC_WHCM_TYPE       0x11
0054 #define USB_CDC_MDLM_TYPE       0x12    /* mdlm_desc */
0055 #define USB_CDC_MDLM_DETAIL_TYPE    0x13    /* mdlm_detail_desc */
0056 #define USB_CDC_DMM_TYPE        0x14
0057 #define USB_CDC_OBEX_TYPE       0x15
0058 #define USB_CDC_NCM_TYPE        0x1a
0059 #define USB_CDC_MBIM_TYPE       0x1b
0060 #define USB_CDC_MBIM_EXTENDED_TYPE  0x1c
0061
0062 /* "Header Functional Descriptor" from CDC spec  5.2.3.1 */
0063 struct usb_cdc_header_desc {
0064     __u8    bLength;
0065     __u8    bDescriptorType;
0066     __u8    bDescriptorSubType;
0067
0068     __le16  bcdCDC;
0069 } __attribute__ ((packed));
0070
0071 /* "Call Management Descriptor" from CDC spec  5.2.3.2 */
0072 struct usb_cdc_call_mgmt_descriptor {
0073     __u8    bLength;
0074     __u8    bDescriptorType;
0075     __u8    bDescriptorSubType;
0076
0077     __u8    bmCapabilities;
0078 #define USB_CDC_CALL_MGMT_CAP_CALL_MGMT     0x01
0079 #define USB_CDC_CALL_MGMT_CAP_DATA_INTF     0x02
0080
0081     __u8    bDataInterface;
0082 } __attribute__ ((packed));
0083
0084 /* "Abstract Control Management Descriptor" from CDC spec  5.2.3.3 */
0085 struct usb_cdc_acm_descriptor {
0086     __u8    bLength;
0087     __u8    bDescriptorType;
0088     __u8    bDescriptorSubType;
0089
0090     __u8    bmCapabilities;
0091 } __attribute__ ((packed));
0092
0093 /* capabilities from 5.2.3.3 */
0094
0095 #define USB_CDC_COMM_FEATURE    0x01
0096 #define USB_CDC_CAP_LINE    0x02
0097 #define USB_CDC_CAP_BRK     0x04
0098 #define USB_CDC_CAP_NOTIFY  0x08
0099
0100 /* "Union Functional Descriptor" from CDC spec 5.2.3.8 */
0101 struct usb_cdc_union_desc {
0102     __u8    bLength;
0103     __u8    bDescriptorType;
0104     __u8    bDescriptorSubType;
0105
0106     __u8    bMasterInterface0;
0107     __u8    bSlaveInterface0;
0108     /* ... and there could be other slave interfaces */
0109 } __attribute__ ((packed));
0110
0111 /* "Country Selection Functional Descriptor" from CDC spec 5.2.3.9 */
0112 struct usb_cdc_country_functional_desc {
0113     __u8    bLength;
0114     __u8    bDescriptorType;
0115     __u8    bDescriptorSubType;
0116
0117     __u8    iCountryCodeRelDate;
0118     __le16  wCountyCode0;
0119     /* ... and there can be a lot of country codes */
0120 } __attribute__ ((packed));
0121
0122 /* "Network Channel Terminal Functional Descriptor" from CDC spec 5.2.3.11 */
0123 struct usb_cdc_network_terminal_desc {
0124     __u8    bLength;
0125     __u8    bDescriptorType;
0126     __u8    bDescriptorSubType;
0127
0128     __u8    bEntityId;
0129     __u8    iName;
0130     __u8    bChannelIndex;
0131     __u8    bPhysicalInterface;
0132 } __attribute__ ((packed));
0133
0134 /* "Ethernet Networking Functional Descriptor" from CDC spec 5.2.3.16 */
0135 struct usb_cdc_ether_desc {
0136     __u8    bLength;
0137     __u8    bDescriptorType;
0138     __u8    bDescriptorSubType;
0139
0140     __u8    iMACAddress;
0141     __le32  bmEthernetStatistics;
0142     __le16  wMaxSegmentSize;
0143     __le16  wNumberMCFilters;
0144     __u8    bNumberPowerFilters;
0145 } __attribute__ ((packed));
0146
0147 /* "Telephone Control Model Functional Descriptor" from CDC WMC spec 6.3..3 */
0148 struct usb_cdc_dmm_desc {
0149     __u8    bFunctionLength;
0150     __u8    bDescriptorType;
0151     __u8    bDescriptorSubtype;
0152     __u16   bcdVersion;
0153     __le16  wMaxCommand;
0154 } __attribute__ ((packed));
0155
0156 /* "MDLM Functional Descriptor" from CDC WMC spec 6.7.2.3 */
0157 struct usb_cdc_mdlm_desc {
0158     __u8    bLength;
0159     __u8    bDescriptorType;
0160     __u8    bDescriptorSubType;
0161
0162     __le16  bcdVersion;
0163     __u8    bGUID[16];
0164 } __attribute__ ((packed));
0165
0166 /* "MDLM Detail Functional Descriptor" from CDC WMC spec 6.7.2.4 */
0167 struct usb_cdc_mdlm_detail_desc {
0168     __u8    bLength;
0169     __u8    bDescriptorType;
0170     __u8    bDescriptorSubType;
0171
0172     /* type is associated with mdlm_desc.bGUID */
0173     __u8    bGuidDescriptorType;
0174     __u8    bDetailData[];
0175 } __attribute__ ((packed));
0176
0177 /* "OBEX Control Model Functional Descriptor" */
0178 struct usb_cdc_obex_desc {
0179     __u8    bLength;
0180     __u8    bDescriptorType;
0181     __u8    bDescriptorSubType;
0182
0183     __le16  bcdVersion;
0184 } __attribute__ ((packed));
0185
0186 /* "NCM Control Model Functional Descriptor" */
0187 struct usb_cdc_ncm_desc {
0188     __u8    bLength;
0189     __u8    bDescriptorType;
0190     __u8    bDescriptorSubType;
0191
0192     __le16  bcdNcmVersion;
0193     __u8    bmNetworkCapabilities;
0194 } __attribute__ ((packed));
0195
0196 /* "MBIM Control Model Functional Descriptor" */
0197 struct usb_cdc_mbim_desc {
0198     __u8    bLength;
0199     __u8    bDescriptorType;
0200     __u8    bDescriptorSubType;
0201
0202     __le16  bcdMBIMVersion;
0203     __le16  wMaxControlMessage;
0204     __u8    bNumberFilters;
0205     __u8    bMaxFilterSize;
0206     __le16  wMaxSegmentSize;
0207     __u8    bmNetworkCapabilities;
0208 } __attribute__ ((packed));
0209
0210 /* "MBIM Extended Functional Descriptor" from CDC MBIM spec 1.0 errata-1 */
0211 struct usb_cdc_mbim_extended_desc {
0212     __u8    bLength;
0213     __u8    bDescriptorType;
0214     __u8    bDescriptorSubType;
0215
0216     __le16  bcdMBIMExtendedVersion;
0217     __u8    bMaxOutstandingCommandMessages;
0218     __le16  wMTU;
0219 } __attribute__ ((packed));
0220
0221 /*-------------------------------------------------------------------------*/
0222
0223 /*
0224  * Class-Specific Control Requests (6.2)
0225  *
0226  * section 3.6.2.1 table 4 has the ACM profile, for modems.
0227  * section 3.8.2 table 10 has the ethernet profile.
0228  *
0229  * Microsoft's RNDIS stack for Ethernet is a vendor-specific CDC ACM variant,
0230  * heavily dependent on the encapsulated (proprietary) command mechanism.
0231  */
0232
0233 #define USB_CDC_SEND_ENCAPSULATED_COMMAND   0x00
0234 #define USB_CDC_GET_ENCAPSULATED_RESPONSE   0x01
0235 #define USB_CDC_REQ_SET_LINE_CODING     0x20
0236 #define USB_CDC_REQ_GET_LINE_CODING     0x21
0237 #define USB_CDC_REQ_SET_CONTROL_LINE_STATE  0x22
0238 #define USB_CDC_REQ_SEND_BREAK          0x23
0239 #define USB_CDC_SET_ETHERNET_MULTICAST_FILTERS  0x40
0240 #define USB_CDC_SET_ETHERNET_PM_PATTERN_FILTER  0x41
0241 #define USB_CDC_GET_ETHERNET_PM_PATTERN_FILTER  0x42
0242 #define USB_CDC_SET_ETHERNET_PACKET_FILTER  0x43
0243 #define USB_CDC_GET_ETHERNET_STATISTIC      0x44
0244 #define USB_CDC_GET_NTB_PARAMETERS      0x80
0245 #define USB_CDC_GET_NET_ADDRESS         0x81
0246 #define USB_CDC_SET_NET_ADDRESS         0x82
0247 #define USB_CDC_GET_NTB_FORMAT          0x83
0248 #define USB_CDC_SET_NTB_FORMAT          0x84
0249 #define USB_CDC_GET_NTB_INPUT_SIZE      0x85
0250 #define USB_CDC_SET_NTB_INPUT_SIZE      0x86
0251 #define USB_CDC_GET_MAX_DATAGRAM_SIZE       0x87
0252 #define USB_CDC_SET_MAX_DATAGRAM_SIZE       0x88
0253 #define USB_CDC_GET_CRC_MODE            0x89
0254 #define USB_CDC_SET_CRC_MODE            0x8a
0255
0256 /* Line Coding Structure from CDC spec 6.2.13 */
0257 struct usb_cdc_line_coding {
0258     __le32  dwDTERate;
0259     __u8    bCharFormat;
0260 #define USB_CDC_1_STOP_BITS         0
0261 #define USB_CDC_1_5_STOP_BITS           1
0262 #define USB_CDC_2_STOP_BITS         2
0263
0264     __u8    bParityType;
0265 #define USB_CDC_NO_PARITY           0
0266 #define USB_CDC_ODD_PARITY          1
0267 #define USB_CDC_EVEN_PARITY         2
0268 #define USB_CDC_MARK_PARITY         3
0269 #define USB_CDC_SPACE_PARITY            4
0270
0271     __u8    bDataBits;
0272 } __attribute__ ((packed));
0273
0274 /* Control Signal Bitmap Values from 6.2.14 SetControlLineState */
0275 #define USB_CDC_CTRL_DTR            (1 << 0)
0276 #define USB_CDC_CTRL_RTS            (1 << 1)
0277
0278 /* table 62; bits in multicast filter */
0279 #define USB_CDC_PACKET_TYPE_PROMISCUOUS     (1 << 0)
0280 #define USB_CDC_PACKET_TYPE_ALL_MULTICAST   (1 << 1) /* no filter */
0281 #define USB_CDC_PACKET_TYPE_DIRECTED        (1 << 2)
0282 #define USB_CDC_PACKET_TYPE_BROADCAST       (1 << 3)
0283 #define USB_CDC_PACKET_TYPE_MULTICAST       (1 << 4) /* filtered */
0284
0285
0286 /*-------------------------------------------------------------------------*/
0287
0288 /*
0289  * Class-Specific Notifications (6.3) sent by interrupt transfers
0290  *
0291  * section 3.8.2 table 11 of the CDC spec lists Ethernet notifications
0292  * section 3.6.2.1 table 5 specifies ACM notifications, accepted by RNDIS
0293  * RNDIS also defines its own bit-incompatible notifications
0294  */
0295
0296 #define USB_CDC_NOTIFY_NETWORK_CONNECTION   0x00
0297 #define USB_CDC_NOTIFY_RESPONSE_AVAILABLE   0x01
0298 #define USB_CDC_NOTIFY_SERIAL_STATE     0x20
0299 #define USB_CDC_NOTIFY_SPEED_CHANGE     0x2a
0300
0301 struct usb_cdc_notification {
0302     __u8    bmRequestType;
0303     __u8    bNotificationType;
0304     __le16  wValue;
0305     __le16  wIndex;
0306     __le16  wLength;
0307 } __attribute__ ((packed));
0308
0309 /* UART State Bitmap Values from 6.3.5 SerialState */
0310 #define USB_CDC_SERIAL_STATE_DCD        (1 << 0)
0311 #define USB_CDC_SERIAL_STATE_DSR        (1 << 1)
0312 #define USB_CDC_SERIAL_STATE_BREAK      (1 << 2)
0313 #define USB_CDC_SERIAL_STATE_RING_SIGNAL    (1 << 3)
0314 #define USB_CDC_SERIAL_STATE_FRAMING        (1 << 4)
0315 #define USB_CDC_SERIAL_STATE_PARITY     (1 << 5)
0316 #define USB_CDC_SERIAL_STATE_OVERRUN        (1 << 6)
0317
0318 struct usb_cdc_speed_change {
0319     __le32  DLBitRRate; /* contains the downlink bit rate (IN pipe) */
0320     __le32  ULBitRate;  /* contains the uplink bit rate (OUT pipe) */
0321 } __attribute__ ((packed));
0322
0323 /*-------------------------------------------------------------------------*/
0324
0325 /*
0326  * Class Specific structures and constants
0327  *
0328  * CDC NCM NTB parameters structure, CDC NCM subclass 6.2.1
0329  *
0330  */
0331
0332 struct usb_cdc_ncm_ntb_parameters {
0333     __le16  wLength;
0334     __le16  bmNtbFormatsSupported;
0335     __le32  dwNtbInMaxSize;
0336     __le16  wNdpInDivisor;
0337     __le16  wNdpInPayloadRemainder;
0338     __le16  wNdpInAlignment;
0339     __le16  wPadding1;
0340     __le32  dwNtbOutMaxSize;
0341     __le16  wNdpOutDivisor;
0342     __le16  wNdpOutPayloadRemainder;
0343     __le16  wNdpOutAlignment;
0344     __le16  wNtbOutMaxDatagrams;
0345 } __attribute__ ((packed));
0346
0347 /*
0348  * CDC NCM transfer headers, CDC NCM subclass 3.2
0349  */
0350
0351 #define USB_CDC_NCM_NTH16_SIGN      0x484D434E /* NCMH */
0352 #define USB_CDC_NCM_NTH32_SIGN      0x686D636E /* ncmh */
0353
0354 struct usb_cdc_ncm_nth16 {
0355     __le32  dwSignature;
0356     __le16  wHeaderLength;
0357     __le16  wSequence;
0358     __le16  wBlockLength;
0359     __le16  wNdpIndex;
0360 } __attribute__ ((packed));
0361
0362 struct usb_cdc_ncm_nth32 {
0363     __le32  dwSignature;
0364     __le16  wHeaderLength;
0365     __le16  wSequence;
0366     __le32  dwBlockLength;
0367     __le32  dwNdpIndex;
0368 } __attribute__ ((packed));
0369
0370 /*
0371  * CDC NCM datagram pointers, CDC NCM subclass 3.3
0372  */
0373
0374 #define USB_CDC_NCM_NDP16_CRC_SIGN  0x314D434E /* NCM1 */
0375 #define USB_CDC_NCM_NDP16_NOCRC_SIGN    0x304D434E /* NCM0 */
0376 #define USB_CDC_NCM_NDP32_CRC_SIGN  0x316D636E /* ncm1 */
0377 #define USB_CDC_NCM_NDP32_NOCRC_SIGN    0x306D636E /* ncm0 */
0378
0379 #define USB_CDC_MBIM_NDP16_IPS_SIGN     0x00535049 /* IPS<sessionID> : IPS0 for now */
0380 #define USB_CDC_MBIM_NDP32_IPS_SIGN     0x00737069 /* ips<sessionID> : ips0 for now */
0381 #define USB_CDC_MBIM_NDP16_DSS_SIGN     0x00535344 /* DSS<sessionID> */
0382 #define USB_CDC_MBIM_NDP32_DSS_SIGN     0x00737364 /* dss<sessionID> */
0383
0384 /* 16-bit NCM Datagram Pointer Entry */
0385 struct usb_cdc_ncm_dpe16 {
0386     __le16  wDatagramIndex;
0387     __le16  wDatagramLength;
0388 } __attribute__((__packed__));
0389
0390 /* 16-bit NCM Datagram Pointer Table */
0391 struct usb_cdc_ncm_ndp16 {
0392     __le32  dwSignature;
0393     __le16  wLength;
0394     __le16  wNextNdpIndex;
0395     struct  usb_cdc_ncm_dpe16 dpe16[];
0396 } __attribute__ ((packed));
0397
0398 /* 32-bit NCM Datagram Pointer Entry */
0399 struct usb_cdc_ncm_dpe32 {
0400     __le32  dwDatagramIndex;
0401     __le32  dwDatagramLength;
0402 } __attribute__((__packed__));
0403
0404 /* 32-bit NCM Datagram Pointer Table */
0405 struct usb_cdc_ncm_ndp32 {
0406     __le32  dwSignature;
0407     __le16  wLength;
0408     __le16  wReserved6;
0409     __le32  dwNextNdpIndex;
0410     __le32  dwReserved12;
0411     struct  usb_cdc_ncm_dpe32 dpe32[];
0412 } __attribute__ ((packed));
0413
0414 /* CDC NCM subclass 3.2.1 and 3.2.2 */
0415 #define USB_CDC_NCM_NDP16_INDEX_MIN         0x000C
0416 #define USB_CDC_NCM_NDP32_INDEX_MIN         0x0010
0417
0418 /* CDC NCM subclass 3.3.3 Datagram Formatting */
0419 #define USB_CDC_NCM_DATAGRAM_FORMAT_CRC         0x30
0420 #define USB_CDC_NCM_DATAGRAM_FORMAT_NOCRC       0X31
0421
0422 /* CDC NCM subclass 4.2 NCM Communications Interface Protocol Code */
0423 #define USB_CDC_NCM_PROTO_CODE_NO_ENCAP_COMMANDS    0x00
0424 #define USB_CDC_NCM_PROTO_CODE_EXTERN_PROTO     0xFE
0425
0426 /* CDC NCM subclass 5.2.1 NCM Functional Descriptor, bmNetworkCapabilities */
0427 #define USB_CDC_NCM_NCAP_ETH_FILTER         (1 << 0)
0428 #define USB_CDC_NCM_NCAP_NET_ADDRESS            (1 << 1)
0429 #define USB_CDC_NCM_NCAP_ENCAP_COMMAND          (1 << 2)
0430 #define USB_CDC_NCM_NCAP_MAX_DATAGRAM_SIZE      (1 << 3)
0431 #define USB_CDC_NCM_NCAP_CRC_MODE           (1 << 4)
0432 #define USB_CDC_NCM_NCAP_NTB_INPUT_SIZE         (1 << 5)
0433
0434 /* CDC NCM subclass Table 6-3: NTB Parameter Structure */
0435 #define USB_CDC_NCM_NTB16_SUPPORTED         (1 << 0)
0436 #define USB_CDC_NCM_NTB32_SUPPORTED         (1 << 1)
0437
0438 /* CDC NCM subclass Table 6-3: NTB Parameter Structure */
0439 #define USB_CDC_NCM_NDP_ALIGN_MIN_SIZE          0x04
0440 #define USB_CDC_NCM_NTB_MAX_LENGTH          0x1C
0441
0442 /* CDC NCM subclass 6.2.5 SetNtbFormat */
0443 #define USB_CDC_NCM_NTB16_FORMAT            0x00
0444 #define USB_CDC_NCM_NTB32_FORMAT            0x01
0445
0446 /* CDC NCM subclass 6.2.7 SetNtbInputSize */
0447 #define USB_CDC_NCM_NTB_MIN_IN_SIZE         2048
0448 #define USB_CDC_NCM_NTB_MIN_OUT_SIZE            2048
0449
0450 /* NTB Input Size Structure */
0451 struct usb_cdc_ncm_ndp_input_size {
0452     __le32  dwNtbInMaxSize;
0453     __le16  wNtbInMaxDatagrams;
0454     __le16  wReserved;
0455 } __attribute__ ((packed));
0456
0457 /* CDC NCM subclass 6.2.11 SetCrcMode */
0458 #define USB_CDC_NCM_CRC_NOT_APPENDED            0x00
0459 #define USB_CDC_NCM_CRC_APPENDED            0x01
0460
0461 #endif /* __UAPI_LINUX_USB_CDC_H */