Documentation/networking/cdc_mbim.rst

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