About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / cdc_mbim.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 EST.

1	     cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
2	    ========================================================
3	
4	The cdc_mbim driver supports USB devices conforming to the "Universal
5	Serial Bus Communications Class Subclass Specification for Mobile
6	Broadband Interface Model" [1], which is a further development of
7	"Universal Serial Bus Communications Class Subclass Specifications for
8	Network Control Model Devices" [2] optimized for Mobile Broadband
9	devices, aka "3G/LTE modems".
10	
11	
12	Command Line Parameters
13	=======================
14	
15	The cdc_mbim driver has no parameters of its own.  But the probing
16	behaviour for NCM 1.0 backwards compatible MBIM functions (an
17	"NCM/MBIM function" as defined in section 3.2 of [1]) is affected
18	by a cdc_ncm driver parameter:
19	
20	prefer_mbim
21	-----------
22	Type:          Boolean
23	Valid Range:   N/Y (0-1)
24	Default Value: Y (MBIM is preferred)
25	
26	This parameter sets the system policy for NCM/MBIM functions.  Such
27	functions will be handled by either the cdc_ncm driver or the cdc_mbim
28	driver depending on the prefer_mbim setting.  Setting prefer_mbim=N
29	makes the cdc_mbim driver ignore these functions and lets the cdc_ncm
30	driver handle them instead.
31	
32	The parameter is writable, and can be changed at any time. A manual
33	unbind/bind is required to make the change effective for NCM/MBIM
34	functions bound to the "wrong" driver
35	
36	
37	Basic usage
38	===========
39	
40	MBIM functions are inactive when unmanaged. The cdc_mbim driver only
41	provides an userspace interface to the MBIM control channel, and will
42	not participate in the management of the function. This implies that a
43	userspace MBIM management application always is required to enable a
44	MBIM function.
45	
46	Such userspace applications includes, but are not limited to:
47	 - mbimcli (included with the libmbim [3] library), and
48	 - ModemManager [4]
49	
50	Establishing a MBIM IP session reequires at least these actions by the
51	management application:
52	 - open the control channel
53	 - configure network connection settings
54	 - connect to network
55	 - configure IP interface
56	
57	Management application development
58	----------------------------------
59	The driver <-> userspace interfaces are described below.  The MBIM
60	control channel protocol is described in [1].
61	
62	
63	MBIM control channel userspace ABI
64	==================================
65	
66	/dev/cdc-wdmX character device
67	------------------------------
68	The driver creates a two-way pipe to the MBIM function control channel
69	using the cdc-wdm driver as a subdriver.  The userspace end of the
70	control channel pipe is a /dev/cdc-wdmX character device.
71	
72	The cdc_mbim driver does not process or police messages on the control
73	channel.  The channel is fully delegated to the userspace management
74	application.  It is therefore up to this application to ensure that it
75	complies with all the control channel requirements in [1].
76	
77	The cdc-wdmX device is created as a child of the MBIM control
78	interface USB device.  The character device associated with a specific
79	MBIM 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	
88	USB configuration descriptors
89	-----------------------------
90	The wMaxControlMessage field of the CDC MBIM functional descriptor
91	limits the maximum control message size. The managament application is
92	responsible for negotiating a control message size complying with the
93	requirements in section 9.3.1 of [1], taking this descriptor field
94	into consideration.
95	
96	The userspace application can access the CDC MBIM functional
97	descriptor of a MBIM function using either of the two USB
98	configuration descriptor kernel interfaces described in [6] or [7].
99	
100	See also the ioctl documentation below.
101	
102	
103	Fragmentation
104	-------------
105	The userspace application is responsible for all control message
106	fragmentation and defragmentaion, as described in section 9.5 of [1].
107	
108	
109	/dev/cdc-wdmX write()
110	---------------------
111	The MBIM control messages from the management application *must not*
112	exceed the negotiated control message size.
113	
114	
115	/dev/cdc-wdmX read()
116	--------------------
117	The management application *must* accept control messages of up the
118	negotiated control message size.
119	
120	
121	/dev/cdc-wdmX ioctl()
122	--------------------
123	IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size
124	This ioctl returns the wMaxControlMessage field of the CDC MBIM
125	functional descriptor for MBIM devices.  This is intended as a
126	convenience, eliminating the need to parse the USB descriptors from
127	userspace.
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	
143	Custom device services
144	----------------------
145	The MBIM specification allows vendors to freely define additional
146	services.  This is fully supported by the cdc_mbim driver.
147	
148	Support for new MBIM services, including vendor specified services, is
149	implemented entirely in userspace, like the rest of the MBIM control
150	protocol
151	
152	New services should be registered in the MBIM Registry [5].
153	
154	
155	
156	MBIM data channel userspace ABI
157	===============================
158	
159	wwanY network device
160	--------------------
161	The cdc_mbim driver represents the MBIM data channel as a single
162	network device of the "wwan" type. This network device is initially
163	mapped to MBIM IP session 0.
164	
165	
166	Multiplexed IP sessions (IPS)
167	-----------------------------
168	MBIM allows multiplexing up to 256 IP sessions over a single USB data
169	channel.  The cdc_mbim driver models such IP sessions as 802.1q VLAN
170	subdevices of the master wwanY device, mapping MBIM IP session Z to
171	VLAN ID Z for all values of Z greater than 0.
172	
173	The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure
174	described in section 10.5.1 of [1].
175	
176	The userspace management application is responsible for adding new
177	VLAN links prior to establishing MBIM IP sessions where the SessionId
178	is greater than 0. These links can be added by using the normal VLAN
179	kernel interfaces, either ioctl or netlink.
180	
181	For 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	
185	The driver will automatically map the "wwan0.3" network device to MBIM
186	IP session 3.
187	
188	
189	Device Service Streams (DSS)
190	----------------------------
191	MBIM also allows up to 256 non-IP data streams to be multiplexed over
192	the same shared USB data channel.  The cdc_mbim driver models these
193	sessions as another set of 802.1q VLAN subdevices of the master wwanY
194	device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values
195	of A.
196	
197	The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO
198	structure described in section 10.5.29 of [1].
199	
200	The DSS VLAN subdevices are used as a practical interface between the
201	shared MBIM data channel and a MBIM DSS aware userspace application.
202	It is not intended to be presented as-is to an end user. The
203	assumption is that an userspace application initiating a DSS session
204	also takes care of the necessary framing of the DSS data, presenting
205	the stream to the end user in an appropriate way for the stream type.
206	
207	The network device ABI requires a dummy ethernet header for every DSS
208	data frame being transported.  The contents of this header is
209	arbitrary, 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	
216	The DSS supporting userspace management application is responsible for
217	adding the dummy ethernet header on TX and stripping it on RX.
218	
219	This is a simple example using tools commonly available, exporting
220	DssSessionId 5 as a pty character device pointed to by a /dev/nmea
221	symlink:
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	
227	This is only an example, most suitable for testing out a DSS
228	service. Userspace applications supporting specific MBIM DSS services
229	are expected to use the tools and programming interfaces required by
230	that service.
231	
232	Note that adding VLAN links for DSS sessions is entirely optional.  A
233	management application may instead choose to bind a packet socket
234	directly to the master network device, using the received VLAN tags to
235	map frames to the correct DSS session and adding 18 byte VLAN ethernet
236	headers with the appropriate tag on TX.  In this case using a socket
237	filter is recommended, matching only the DSS VLAN subset. This avoid
238	unnecessary copying of unrelated IP session data to userspace.  For
239	example:
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	
261	Tagged IP session 0 VLAN
262	------------------------
263	As described above, MBIM IP session 0 is treated as special by the
264	driver.  It is initially mapped to untagged frames on the wwanY
265	network device.
266	
267	This mapping implies a few restrictions on multiplexed IPS and DSS
268	sessions, 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	
274	These problems can be avoided by optionally making the driver map IP
275	session 0 to a VLAN subdevice, similar to all other IP sessions.  This
276	behaviour is triggered by adding a VLAN link for the magic VLAN ID
277	4094.  The driver will then immediately start mapping MBIM IP session
278	0 to this VLAN, and will drop untagged frames on the master wwanY
279	device.
280	
281	Tip: It might be less confusing to the end user to name this VLAN
282	subdevice after the MBIM SessionID instead of the VLAN ID.  For
283	example:
284	
285	  ip link add link wwan0 name wwan0.0 type vlan id 4094
286	
287	
288	VLAN mapping
289	------------
290	
291	Summarizing the cdc_mbim driver mapping described above, we have this
292	relationship between VLAN tags on the wwanY network device and MBIM
293	sessions 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	
310	References
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
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.