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