Kyle Swenson | 8d8f654 | 2021-03-15 11:02:55 -0600 | [diff] [blame] | 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 |