Documentation/networking/cdc_mbim.txt

   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 a 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 a 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] "/sys/kernel/debug/usb/devices output format"
 336        - Documentation/driver-api/usb/usb.rst
 337
 338 [7] "/sys/bus/usb/devices/.../descriptors"
 339        - Documentation/ABI/stable/sysfs-bus-usb