Commit | Line | Data |
---|---|---|
92f06f42 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ====================================================== | |
4 | cdc_mbim - Driver for CDC MBIM Mobile Broadband modems | |
5 | ====================================================== | |
a563babe BM |
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 | ----------- | |
92f06f42 MCC |
25 | :Type: Boolean |
26 | :Valid Range: N/Y (0-1) | |
27 | :Default Value: Y (MBIM is preferred) | |
a563babe BM |
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 | |
9332ef9d | 44 | provides a userspace interface to the MBIM control channel, and will |
a563babe BM |
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: | |
92f06f42 | 50 | |
a563babe BM |
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: | |
92f06f42 | 56 | |
a563babe BM |
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 | |
92f06f42 | 84 | MBIM function can be looked up using sysfs. For example:: |
a563babe BM |
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 managament 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() | |
92f06f42 | 127 | --------------------- |
a563babe BM |
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 | ||
92f06f42 MCC |
134 | :: |
135 | ||
a563babe BM |
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 | ||
92f06f42 | 188 | For example, adding a link for a MBIM IP session with SessionId 3:: |
a563babe BM |
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 | |
9332ef9d | 210 | assumption is that a userspace application initiating a DSS session |
a563babe BM |
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: | |
92f06f42 | 217 | |
a563babe BM |
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 | |
92f06f42 | 229 | symlink:: |
a563babe BM |
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 | |
92f06f42 | 247 | example:: |
a563babe BM |
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 */ | |
92f06f42 MCC |
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), | |
a563babe | 262 | |
92f06f42 MCC |
263 | BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */ |
264 | BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */ | |
a563babe BM |
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: | |
92f06f42 | 277 | |
a563babe BM |
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 | |
92f06f42 | 292 | example:: |
a563babe BM |
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 | |
92f06f42 | 302 | sessions on the shared USB data channel:: |
a563babe BM |
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 | ||
92f06f42 MCC |
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 | ||
a563babe BM |
326 | - http://www.usb.org/developers/docs/devclass_docs/ |
327 | ||
92f06f42 MCC |
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 | ||
a563babe BM |
332 | - http://www.usb.org/developers/docs/devclass_docs/ |
333 | ||
92f06f42 MCC |
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 | ||
a563babe BM |
338 | - http://www.freedesktop.org/wiki/Software/libmbim/ |
339 | ||
92f06f42 MCC |
340 | 4) ModemManager - "a DBus-activated daemon which controls mobile |
341 | broadband (2G/3G/4G) devices and connections" | |
342 | ||
a563babe BM |
343 | - http://www.freedesktop.org/wiki/Software/ModemManager/ |
344 | ||
92f06f42 MCC |
345 | 5) "MBIM (Mobile Broadband Interface Model) Registry" |
346 | ||
a563babe BM |
347 | - http://compliance.usb.org/mbim/ |
348 | ||
92f06f42 MCC |
349 | 6) "/sys/kernel/debug/usb/devices output format" |
350 | ||
4269a691 | 351 | - Documentation/driver-api/usb/usb.rst |
a563babe | 352 | |
92f06f42 MCC |
353 | 7) "/sys/bus/usb/devices/.../descriptors" |
354 | ||
a563babe | 355 | - Documentation/ABI/stable/sysfs-bus-usb |