Commit | Line | Data |
---|---|---|
a563babe BM |
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 |