xref: /linux/include/uapi/linux/usb/cdc.h (revision 4f2c0a4acffbec01079c28f839422e64ddeff004)
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 */
462