1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================================================
4 cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
5 ======================================================
6
7 The cdc_mbim driver supports USB devices conforming to the "Universal
8 Serial Bus Communications Class Subclass Specification for Mobile
9 Broadband Interface Model" [1], which is a further development of
10 "Universal Serial Bus Communications Class Subclass Specifications for
11 Network Control Model Devices" [2] optimized for Mobile Broadband
12 devices, aka "3G/LTE modems".
13
14
15 Command Line Parameters
16 =======================
17
18 The cdc_mbim driver has no parameters of its own. But the probing
19 behaviour for NCM 1.0 backwards compatible MBIM functions (an
20 "NCM/MBIM function" as defined in section 3.2 of [1]) is affected
21 by a cdc_ncm driver parameter:
22
23 prefer_mbim
24 -----------
25 :Type: Boolean
26 :Valid Range: N/Y (0-1)
27 :Default Value: Y (MBIM is preferred)
28
29 This parameter sets the system policy for NCM/MBIM functions. Such
30 functions will be handled by either the cdc_ncm driver or the cdc_mbim
31 driver depending on the prefer_mbim setting. Setting prefer_mbim=N
32 makes the cdc_mbim driver ignore these functions and lets the cdc_ncm
33 driver handle them instead.
34
35 The parameter is writable, and can be changed at any time. A manual
36 unbind/bind is required to make the change effective for NCM/MBIM
37 functions bound to the "wrong" driver
38
39
40 Basic usage
41 ===========
42
43 MBIM functions are inactive when unmanaged. The cdc_mbim driver only
44 provides a userspace interface to the MBIM control channel, and will
45 not participate in the management of the function. This implies that a
46 userspace MBIM management application always is required to enable a
47 MBIM function.
48
49 Such userspace applications includes, but are not limited to:
50
51 - mbimcli (included with the libmbim [3] library), and
52 - ModemManager [4]
53
54 Establishing a MBIM IP session reequires at least these actions by the
55 management application:
56
57 - open the control channel
58 - configure network connection settings
59 - connect to network
60 - configure IP interface
61
62 Management application development
63 ----------------------------------
64 The driver <-> userspace interfaces are described below. The MBIM
65 control channel protocol is described in [1].
66
67
68 MBIM control channel userspace ABI
69 ==================================
70
71 /dev/cdc-wdmX character device
72 ------------------------------
73 The driver creates a two-way pipe to the MBIM function control channel
74 using the cdc-wdm driver as a subdriver. The userspace end of the
75 control channel pipe is a /dev/cdc-wdmX character device.
76
77 The cdc_mbim driver does not process or police messages on the control
78 channel. The channel is fully delegated to the userspace management
79 application. It is therefore up to this application to ensure that it
80 complies with all the control channel requirements in [1].
81
82 The cdc-wdmX device is created as a child of the MBIM control
83 interface USB device. The character device associated with a specific
84 MBIM function can be looked up using sysfs. For example::
85
86 bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc
87 cdc-wdm0
88
89 bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev
90 180:0
91
92
93 USB configuration descriptors
94 -----------------------------
95 The wMaxControlMessage field of the CDC MBIM functional descriptor
96 limits the maximum control message size. The management application is
97 responsible for negotiating a control message size complying with the
98 requirements in section 9.3.1 of [1], taking this descriptor field
99 into consideration.
100
101 The userspace application can access the CDC MBIM functional
102 descriptor of a MBIM function using either of the two USB
103 configuration descriptor kernel interfaces described in [6] or [7].
104
105 See also the ioctl documentation below.
106
107
108 Fragmentation
109 -------------
110 The userspace application is responsible for all control message
111 fragmentation and defragmentaion, as described in section 9.5 of [1].
112
113
114 /dev/cdc-wdmX write()
115 ---------------------
116 The MBIM control messages from the management application *must not*
117 exceed the negotiated control message size.
118
119
120 /dev/cdc-wdmX read()
121 --------------------
122 The management application *must* accept control messages of up the
123 negotiated control message size.
124
125
126 /dev/cdc-wdmX ioctl()
127 ---------------------
128 IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size
129 This ioctl returns the wMaxControlMessage field of the CDC MBIM
130 functional descriptor for MBIM devices. This is intended as a
131 convenience, eliminating the need to parse the USB descriptors from
132 userspace.
133
134 ::
135
136 #include <stdio.h>
137 #include <fcntl.h>
138 #include <sys/ioctl.h>
139 #include <linux/types.h>
140 #include <linux/usb/cdc-wdm.h>
141 int main()
142 {
143 __u16 max;
144 int fd = open("/dev/cdc-wdm0", O_RDWR);
145 if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max))
146 printf("wMaxControlMessage is %d\n", max);
147 }
148
149
150 Custom device services
151 ----------------------
152 The MBIM specification allows vendors to freely define additional
153 services. This is fully supported by the cdc_mbim driver.
154
155 Support for new MBIM services, including vendor specified services, is
156 implemented entirely in userspace, like the rest of the MBIM control
157 protocol
158
159 New services should be registered in the MBIM Registry [5].
160
161
162
163 MBIM data channel userspace ABI
164 ===============================
165
166 wwanY network device
167 --------------------
168 The cdc_mbim driver represents the MBIM data channel as a single
169 network device of the "wwan" type. This network device is initially
170 mapped to MBIM IP session 0.
171
172
173 Multiplexed IP sessions (IPS)
174 -----------------------------
175 MBIM allows multiplexing up to 256 IP sessions over a single USB data
176 channel. The cdc_mbim driver models such IP sessions as 802.1q VLAN
177 subdevices of the master wwanY device, mapping MBIM IP session Z to
178 VLAN ID Z for all values of Z greater than 0.
179
180 The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure
181 described in section 10.5.1 of [1].
182
183 The userspace management application is responsible for adding new
184 VLAN links prior to establishing MBIM IP sessions where the SessionId
185 is greater than 0. These links can be added by using the normal VLAN
186 kernel interfaces, either ioctl or netlink.
187
188 For example, adding a link for a MBIM IP session with SessionId 3::
189
190 ip link add link wwan0 name wwan0.3 type vlan id 3
191
192 The driver will automatically map the "wwan0.3" network device to MBIM
193 IP session 3.
194
195
196 Device Service Streams (DSS)
197 ----------------------------
198 MBIM also allows up to 256 non-IP data streams to be multiplexed over
199 the same shared USB data channel. The cdc_mbim driver models these
200 sessions as another set of 802.1q VLAN subdevices of the master wwanY
201 device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values
202 of A.
203
204 The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO
205 structure described in section 10.5.29 of [1].
206
207 The DSS VLAN subdevices are used as a practical interface between the
208 shared MBIM data channel and a MBIM DSS aware userspace application.
209 It is not intended to be presented as-is to an end user. The
210 assumption is that a userspace application initiating a DSS session
211 also takes care of the necessary framing of the DSS data, presenting
212 the stream to the end user in an appropriate way for the stream type.
213
214 The network device ABI requires a dummy ethernet header for every DSS
215 data frame being transported. The contents of this header is
216 arbitrary, with the following exceptions:
217
218 - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped
219 - RX frames will have the protocol field set to ETH_P_802_3 (but will
220 not be properly formatted 802.3 frames)
221 - RX frames will have the destination address set to the hardware
222 address of the master device
223
224 The DSS supporting userspace management application is responsible for
225 adding the dummy ethernet header on TX and stripping it on RX.
226
227 This is a simple example using tools commonly available, exporting
228 DssSessionId 5 as a pty character device pointed to by a /dev/nmea
229 symlink::
230
231 ip link add link wwan0 name wwan0.dss5 type vlan id 261
232 ip link set dev wwan0.dss5 up
233 socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea
234
235 This is only an example, most suitable for testing out a DSS
236 service. Userspace applications supporting specific MBIM DSS services
237 are expected to use the tools and programming interfaces required by
238 that service.
239
240 Note that adding VLAN links for DSS sessions is entirely optional. A
241 management application may instead choose to bind a packet socket
242 directly to the master network device, using the received VLAN tags to
243 map frames to the correct DSS session and adding 18 byte VLAN ethernet
244 headers with the appropriate tag on TX. In this case using a socket
245 filter is recommended, matching only the DSS VLAN subset. This avoid
246 unnecessary copying of unrelated IP session data to userspace. For
247 example::
248
249 static struct sock_filter dssfilter[] = {
250 /* use special negative offsets to get VLAN tag */
251 BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT),
252 BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */
253
254 /* verify DSS VLAN range */
255 BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG),
256 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4), /* 256 is first DSS VLAN */
257 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */
258
259 /* verify ethertype */
260 BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN),
261 BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1),
262
263 BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */
264 BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */
265 };
266
267
268
269 Tagged IP session 0 VLAN
270 ------------------------
271 As described above, MBIM IP session 0 is treated as special by the
272 driver. It is initially mapped to untagged frames on the wwanY
273 network device.
274
275 This mapping implies a few restrictions on multiplexed IPS and DSS
276 sessions, which may not always be practical:
277
278 - no IPS or DSS session can use a frame size greater than the MTU on
279 IP session 0
280 - no IPS or DSS session can be in the up state unless the network
281 device representing IP session 0 also is up
282
283 These problems can be avoided by optionally making the driver map IP
284 session 0 to a VLAN subdevice, similar to all other IP sessions. This
285 behaviour is triggered by adding a VLAN link for the magic VLAN ID
286 4094. The driver will then immediately start mapping MBIM IP session
287 0 to this VLAN, and will drop untagged frames on the master wwanY
288 device.
289
290 Tip: It might be less confusing to the end user to name this VLAN
291 subdevice after the MBIM SessionID instead of the VLAN ID. For
292 example::
293
294 ip link add link wwan0 name wwan0.0 type vlan id 4094
295
296
297 VLAN mapping
298 ------------
299
300 Summarizing the cdc_mbim driver mapping described above, we have this
301 relationship between VLAN tags on the wwanY network device and MBIM
302 sessions on the shared USB data channel::
303
304 VLAN ID MBIM type MBIM SessionID Notes
305 ---------------------------------------------------------
306 untagged IPS 0 a)
307 1 - 255 IPS 1 - 255 <VLANID>
308 256 - 511 DSS 0 - 255 <VLANID - 256>
309 512 - 4093 b)
310 4094 IPS 0 c)
311
312 a) if no VLAN ID 4094 link exists, else dropped
313 b) unsupported VLAN range, unconditionally dropped
314 c) if a VLAN ID 4094 link exists, else dropped
315
316
317
318
319 References
320 ==========
321
322 1) USB Implementers Forum, Inc. - "Universal Serial Bus
323 Communications Class Subclass Specification for Mobile Broadband
324 Interface Model", Revision 1.0 (Errata 1), May 1, 2013
325
326 - http://www.usb.org/developers/docs/devclass_docs/
327
328 2) USB Implementers Forum, Inc. - "Universal Serial Bus
329 Communications Class Subclass Specifications for Network Control
330 Model Devices", Revision 1.0 (Errata 1), November 24, 2010
331
332 - http://www.usb.org/developers/docs/devclass_docs/
333
334 3) libmbim - "a glib-based library for talking to WWAN modems and
335 devices which speak the Mobile Interface Broadband Model (MBIM)
336 protocol"
337
338 - http://www.freedesktop.org/wiki/Software/libmbim/
339
340 4) ModemManager - "a DBus-activated daemon which controls mobile
341 broadband (2G/3G/4G) devices and connections"
342
343 - http://www.freedesktop.org/wiki/Software/ModemManager/
344
345 5) "MBIM (Mobile Broadband Interface Model) Registry"
346
347 - http://compliance.usb.org/mbim/
348
349 6) "/sys/kernel/debug/usb/devices output format"
350
351 - Documentation/driver-api/usb/usb.rst
352
353 7) "/sys/bus/usb/devices/.../descriptors"
354
355 - Documentation/ABI/stable/sysfs-bus-usb
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.