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