0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======================================================
0004 cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
0005 ======================================================
0006
0007 The cdc_mbim driver supports USB devices conforming to the "Universal
0008 Serial Bus Communications Class Subclass Specification for Mobile
0009 Broadband Interface Model" [1], which is a further development of
0010 "Universal Serial Bus Communications Class Subclass Specifications for
0011 Network Control Model Devices" [2] optimized for Mobile Broadband
0012 devices, aka "3G/LTE modems".
0013
0014
0015 Command Line Parameters
0016 =======================
0017
0018 The cdc_mbim driver has no parameters of its own. But the probing
0019 behaviour for NCM 1.0 backwards compatible MBIM functions (an
0020 "NCM/MBIM function" as defined in section 3.2 of [1]) is affected
0021 by a cdc_ncm driver parameter:
0022
0023 prefer_mbim
0024 -----------
0025 :Type: Boolean
0026 :Valid Range: N/Y (0-1)
0027 :Default Value: Y (MBIM is preferred)
0028
0029 This parameter sets the system policy for NCM/MBIM functions. Such
0030 functions will be handled by either the cdc_ncm driver or the cdc_mbim
0031 driver depending on the prefer_mbim setting. Setting prefer_mbim=N
0032 makes the cdc_mbim driver ignore these functions and lets the cdc_ncm
0033 driver handle them instead.
0034
0035 The parameter is writable, and can be changed at any time. A manual
0036 unbind/bind is required to make the change effective for NCM/MBIM
0037 functions bound to the "wrong" driver
0038
0039
0040 Basic usage
0041 ===========
0042
0043 MBIM functions are inactive when unmanaged. The cdc_mbim driver only
0044 provides a userspace interface to the MBIM control channel, and will
0045 not participate in the management of the function. This implies that a
0046 userspace MBIM management application always is required to enable a
0047 MBIM function.
0048
0049 Such userspace applications includes, but are not limited to:
0050
0051 - mbimcli (included with the libmbim [3] library), and
0052 - ModemManager [4]
0053
0054 Establishing a MBIM IP session reequires at least these actions by the
0055 management application:
0056
0057 - open the control channel
0058 - configure network connection settings
0059 - connect to network
0060 - configure IP interface
0061
0062 Management application development
0063 ----------------------------------
0064 The driver <-> userspace interfaces are described below. The MBIM
0065 control channel protocol is described in [1].
0066
0067
0068 MBIM control channel userspace ABI
0069 ==================================
0070
0071 /dev/cdc-wdmX character device
0072 ------------------------------
0073 The driver creates a two-way pipe to the MBIM function control channel
0074 using the cdc-wdm driver as a subdriver. The userspace end of the
0075 control channel pipe is a /dev/cdc-wdmX character device.
0076
0077 The cdc_mbim driver does not process or police messages on the control
0078 channel. The channel is fully delegated to the userspace management
0079 application. It is therefore up to this application to ensure that it
0080 complies with all the control channel requirements in [1].
0081
0082 The cdc-wdmX device is created as a child of the MBIM control
0083 interface USB device. The character device associated with a specific
0084 MBIM function can be looked up using sysfs. For example::
0085
0086 bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc
0087 cdc-wdm0
0088
0089 bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev
0090 180:0
0091
0092
0093 USB configuration descriptors
0094 -----------------------------
0095 The wMaxControlMessage field of the CDC MBIM functional descriptor
0096 limits the maximum control message size. The managament application is
0097 responsible for negotiating a control message size complying with the
0098 requirements in section 9.3.1 of [1], taking this descriptor field
0099 into consideration.
0100
0101 The userspace application can access the CDC MBIM functional
0102 descriptor of a MBIM function using either of the two USB
0103 configuration descriptor kernel interfaces described in [6] or [7].
0104
0105 See also the ioctl documentation below.
0106
0107
0108 Fragmentation
0109 -------------
0110 The userspace application is responsible for all control message
0111 fragmentation and defragmentaion, as described in section 9.5 of [1].
0112
0113
0114 /dev/cdc-wdmX write()
0115 ---------------------
0116 The MBIM control messages from the management application *must not*
0117 exceed the negotiated control message size.
0118
0119
0120 /dev/cdc-wdmX read()
0121 --------------------
0122 The management application *must* accept control messages of up the
0123 negotiated control message size.
0124
0125
0126 /dev/cdc-wdmX ioctl()
0127 ---------------------
0128 IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size
0129 This ioctl returns the wMaxControlMessage field of the CDC MBIM
0130 functional descriptor for MBIM devices. This is intended as a
0131 convenience, eliminating the need to parse the USB descriptors from
0132 userspace.
0133
0134 ::
0135
0136 #include <stdio.h>
0137 #include <fcntl.h>
0138 #include <sys/ioctl.h>
0139 #include <linux/types.h>
0140 #include <linux/usb/cdc-wdm.h>
0141 int main()
0142 {
0143 __u16 max;
0144 int fd = open("/dev/cdc-wdm0", O_RDWR);
0145 if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max))
0146 printf("wMaxControlMessage is %d\n", max);
0147 }
0148
0149
0150 Custom device services
0151 ----------------------
0152 The MBIM specification allows vendors to freely define additional
0153 services. This is fully supported by the cdc_mbim driver.
0154
0155 Support for new MBIM services, including vendor specified services, is
0156 implemented entirely in userspace, like the rest of the MBIM control
0157 protocol
0158
0159 New services should be registered in the MBIM Registry [5].
0160
0161
0162
0163 MBIM data channel userspace ABI
0164 ===============================
0165
0166 wwanY network device
0167 --------------------
0168 The cdc_mbim driver represents the MBIM data channel as a single
0169 network device of the "wwan" type. This network device is initially
0170 mapped to MBIM IP session 0.
0171
0172
0173 Multiplexed IP sessions (IPS)
0174 -----------------------------
0175 MBIM allows multiplexing up to 256 IP sessions over a single USB data
0176 channel. The cdc_mbim driver models such IP sessions as 802.1q VLAN
0177 subdevices of the master wwanY device, mapping MBIM IP session Z to
0178 VLAN ID Z for all values of Z greater than 0.
0179
0180 The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure
0181 described in section 10.5.1 of [1].
0182
0183 The userspace management application is responsible for adding new
0184 VLAN links prior to establishing MBIM IP sessions where the SessionId
0185 is greater than 0. These links can be added by using the normal VLAN
0186 kernel interfaces, either ioctl or netlink.
0187
0188 For example, adding a link for a MBIM IP session with SessionId 3::
0189
0190 ip link add link wwan0 name wwan0.3 type vlan id 3
0191
0192 The driver will automatically map the "wwan0.3" network device to MBIM
0193 IP session 3.
0194
0195
0196 Device Service Streams (DSS)
0197 ----------------------------
0198 MBIM also allows up to 256 non-IP data streams to be multiplexed over
0199 the same shared USB data channel. The cdc_mbim driver models these
0200 sessions as another set of 802.1q VLAN subdevices of the master wwanY
0201 device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values
0202 of A.
0203
0204 The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO
0205 structure described in section 10.5.29 of [1].
0206
0207 The DSS VLAN subdevices are used as a practical interface between the
0208 shared MBIM data channel and a MBIM DSS aware userspace application.
0209 It is not intended to be presented as-is to an end user. The
0210 assumption is that a userspace application initiating a DSS session
0211 also takes care of the necessary framing of the DSS data, presenting
0212 the stream to the end user in an appropriate way for the stream type.
0213
0214 The network device ABI requires a dummy ethernet header for every DSS
0215 data frame being transported. The contents of this header is
0216 arbitrary, with the following exceptions:
0217
0218 - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped
0219 - RX frames will have the protocol field set to ETH_P_802_3 (but will
0220 not be properly formatted 802.3 frames)
0221 - RX frames will have the destination address set to the hardware
0222 address of the master device
0223
0224 The DSS supporting userspace management application is responsible for
0225 adding the dummy ethernet header on TX and stripping it on RX.
0226
0227 This is a simple example using tools commonly available, exporting
0228 DssSessionId 5 as a pty character device pointed to by a /dev/nmea
0229 symlink::
0230
0231 ip link add link wwan0 name wwan0.dss5 type vlan id 261
0232 ip link set dev wwan0.dss5 up
0233 socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea
0234
0235 This is only an example, most suitable for testing out a DSS
0236 service. Userspace applications supporting specific MBIM DSS services
0237 are expected to use the tools and programming interfaces required by
0238 that service.
0239
0240 Note that adding VLAN links for DSS sessions is entirely optional. A
0241 management application may instead choose to bind a packet socket
0242 directly to the master network device, using the received VLAN tags to
0243 map frames to the correct DSS session and adding 18 byte VLAN ethernet
0244 headers with the appropriate tag on TX. In this case using a socket
0245 filter is recommended, matching only the DSS VLAN subset. This avoid
0246 unnecessary copying of unrelated IP session data to userspace. For
0247 example::
0248
0249 static struct sock_filter dssfilter[] = {
0250 /* use special negative offsets to get VLAN tag */
0251 BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT),
0252 BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */
0253
0254 /* verify DSS VLAN range */
0255 BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG),
0256 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4), /* 256 is first DSS VLAN */
0257 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */
0258
0259 /* verify ethertype */
0260 BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN),
0261 BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1),
0262
0263 BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */
0264 BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */
0265 };
0266
0267
0268
0269 Tagged IP session 0 VLAN
0270 ------------------------
0271 As described above, MBIM IP session 0 is treated as special by the
0272 driver. It is initially mapped to untagged frames on the wwanY
0273 network device.
0274
0275 This mapping implies a few restrictions on multiplexed IPS and DSS
0276 sessions, which may not always be practical:
0277
0278 - no IPS or DSS session can use a frame size greater than the MTU on
0279 IP session 0
0280 - no IPS or DSS session can be in the up state unless the network
0281 device representing IP session 0 also is up
0282
0283 These problems can be avoided by optionally making the driver map IP
0284 session 0 to a VLAN subdevice, similar to all other IP sessions. This
0285 behaviour is triggered by adding a VLAN link for the magic VLAN ID
0286 4094. The driver will then immediately start mapping MBIM IP session
0287 0 to this VLAN, and will drop untagged frames on the master wwanY
0288 device.
0289
0290 Tip: It might be less confusing to the end user to name this VLAN
0291 subdevice after the MBIM SessionID instead of the VLAN ID. For
0292 example::
0293
0294 ip link add link wwan0 name wwan0.0 type vlan id 4094
0295
0296
0297 VLAN mapping
0298 ------------
0299
0300 Summarizing the cdc_mbim driver mapping described above, we have this
0301 relationship between VLAN tags on the wwanY network device and MBIM
0302 sessions on the shared USB data channel::
0303
0304 VLAN ID MBIM type MBIM SessionID Notes
0305 ---------------------------------------------------------
0306 untagged IPS 0 a)
0307 1 - 255 IPS 1 - 255 <VLANID>
0308 256 - 511 DSS 0 - 255 <VLANID - 256>
0309 512 - 4093 b)
0310 4094 IPS 0 c)
0311
0312 a) if no VLAN ID 4094 link exists, else dropped
0313 b) unsupported VLAN range, unconditionally dropped
0314 c) if a VLAN ID 4094 link exists, else dropped
0315
0316
0317
0318
0319 References
0320 ==========
0321
0322 1) USB Implementers Forum, Inc. - "Universal Serial Bus
0323 Communications Class Subclass Specification for Mobile Broadband
0324 Interface Model", Revision 1.0 (Errata 1), May 1, 2013
0325
0326 - http://www.usb.org/developers/docs/devclass_docs/
0327
0328 2) USB Implementers Forum, Inc. - "Universal Serial Bus
0329 Communications Class Subclass Specifications for Network Control
0330 Model Devices", Revision 1.0 (Errata 1), November 24, 2010
0331
0332 - http://www.usb.org/developers/docs/devclass_docs/
0333
0334 3) libmbim - "a glib-based library for talking to WWAN modems and
0335 devices which speak the Mobile Interface Broadband Model (MBIM)
0336 protocol"
0337
0338 - http://www.freedesktop.org/wiki/Software/libmbim/
0339
0340 4) ModemManager - "a DBus-activated daemon which controls mobile
0341 broadband (2G/3G/4G) devices and connections"
0342
0343 - http://www.freedesktop.org/wiki/Software/ModemManager/
0344
0345 5) "MBIM (Mobile Broadband Interface Model) Registry"
0346
0347 - http://compliance.usb.org/mbim/
0348
0349 6) "/sys/kernel/debug/usb/devices output format"
0350
0351 - Documentation/driver-api/usb/usb.rst
0352
0353 7) "/sys/bus/usb/devices/.../descriptors"
0354
0355 - Documentation/ABI/stable/sysfs-bus-usb
