forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
355 lines
12 KiB
355 lines
12 KiB
.. SPDX-License-Identifier: GPL-2.0 |
|
|
|
====================================================== |
|
cdc_mbim - Driver for CDC MBIM Mobile Broadband modems |
|
====================================================== |
|
|
|
The cdc_mbim driver supports USB devices conforming to the "Universal |
|
Serial Bus Communications Class Subclass Specification for Mobile |
|
Broadband Interface Model" [1], which is a further development of |
|
"Universal Serial Bus Communications Class Subclass Specifications for |
|
Network Control Model Devices" [2] optimized for Mobile Broadband |
|
devices, aka "3G/LTE modems". |
|
|
|
|
|
Command Line Parameters |
|
======================= |
|
|
|
The cdc_mbim driver has no parameters of its own. But the probing |
|
behaviour for NCM 1.0 backwards compatible MBIM functions (an |
|
"NCM/MBIM function" as defined in section 3.2 of [1]) is affected |
|
by a cdc_ncm driver parameter: |
|
|
|
prefer_mbim |
|
----------- |
|
:Type: Boolean |
|
:Valid Range: N/Y (0-1) |
|
:Default Value: Y (MBIM is preferred) |
|
|
|
This parameter sets the system policy for NCM/MBIM functions. Such |
|
functions will be handled by either the cdc_ncm driver or the cdc_mbim |
|
driver depending on the prefer_mbim setting. Setting prefer_mbim=N |
|
makes the cdc_mbim driver ignore these functions and lets the cdc_ncm |
|
driver handle them instead. |
|
|
|
The parameter is writable, and can be changed at any time. A manual |
|
unbind/bind is required to make the change effective for NCM/MBIM |
|
functions bound to the "wrong" driver |
|
|
|
|
|
Basic usage |
|
=========== |
|
|
|
MBIM functions are inactive when unmanaged. The cdc_mbim driver only |
|
provides a userspace interface to the MBIM control channel, and will |
|
not participate in the management of the function. This implies that a |
|
userspace MBIM management application always is required to enable a |
|
MBIM function. |
|
|
|
Such userspace applications includes, but are not limited to: |
|
|
|
- mbimcli (included with the libmbim [3] library), and |
|
- ModemManager [4] |
|
|
|
Establishing a MBIM IP session reequires at least these actions by the |
|
management application: |
|
|
|
- open the control channel |
|
- configure network connection settings |
|
- connect to network |
|
- configure IP interface |
|
|
|
Management application development |
|
---------------------------------- |
|
The driver <-> userspace interfaces are described below. The MBIM |
|
control channel protocol is described in [1]. |
|
|
|
|
|
MBIM control channel userspace ABI |
|
================================== |
|
|
|
/dev/cdc-wdmX character device |
|
------------------------------ |
|
The driver creates a two-way pipe to the MBIM function control channel |
|
using the cdc-wdm driver as a subdriver. The userspace end of the |
|
control channel pipe is a /dev/cdc-wdmX character device. |
|
|
|
The cdc_mbim driver does not process or police messages on the control |
|
channel. The channel is fully delegated to the userspace management |
|
application. It is therefore up to this application to ensure that it |
|
complies with all the control channel requirements in [1]. |
|
|
|
The cdc-wdmX device is created as a child of the MBIM control |
|
interface USB device. The character device associated with a specific |
|
MBIM function can be looked up using sysfs. For example:: |
|
|
|
bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc |
|
cdc-wdm0 |
|
|
|
bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev |
|
180:0 |
|
|
|
|
|
USB configuration descriptors |
|
----------------------------- |
|
The wMaxControlMessage field of the CDC MBIM functional descriptor |
|
limits the maximum control message size. The managament application is |
|
responsible for negotiating a control message size complying with the |
|
requirements in section 9.3.1 of [1], taking this descriptor field |
|
into consideration. |
|
|
|
The userspace application can access the CDC MBIM functional |
|
descriptor of a MBIM function using either of the two USB |
|
configuration descriptor kernel interfaces described in [6] or [7]. |
|
|
|
See also the ioctl documentation below. |
|
|
|
|
|
Fragmentation |
|
------------- |
|
The userspace application is responsible for all control message |
|
fragmentation and defragmentaion, as described in section 9.5 of [1]. |
|
|
|
|
|
/dev/cdc-wdmX write() |
|
--------------------- |
|
The MBIM control messages from the management application *must not* |
|
exceed the negotiated control message size. |
|
|
|
|
|
/dev/cdc-wdmX read() |
|
-------------------- |
|
The management application *must* accept control messages of up the |
|
negotiated control message size. |
|
|
|
|
|
/dev/cdc-wdmX ioctl() |
|
--------------------- |
|
IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size |
|
This ioctl returns the wMaxControlMessage field of the CDC MBIM |
|
functional descriptor for MBIM devices. This is intended as a |
|
convenience, eliminating the need to parse the USB descriptors from |
|
userspace. |
|
|
|
:: |
|
|
|
#include <stdio.h> |
|
#include <fcntl.h> |
|
#include <sys/ioctl.h> |
|
#include <linux/types.h> |
|
#include <linux/usb/cdc-wdm.h> |
|
int main() |
|
{ |
|
__u16 max; |
|
int fd = open("/dev/cdc-wdm0", O_RDWR); |
|
if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max)) |
|
printf("wMaxControlMessage is %d\n", max); |
|
} |
|
|
|
|
|
Custom device services |
|
---------------------- |
|
The MBIM specification allows vendors to freely define additional |
|
services. This is fully supported by the cdc_mbim driver. |
|
|
|
Support for new MBIM services, including vendor specified services, is |
|
implemented entirely in userspace, like the rest of the MBIM control |
|
protocol |
|
|
|
New services should be registered in the MBIM Registry [5]. |
|
|
|
|
|
|
|
MBIM data channel userspace ABI |
|
=============================== |
|
|
|
wwanY network device |
|
-------------------- |
|
The cdc_mbim driver represents the MBIM data channel as a single |
|
network device of the "wwan" type. This network device is initially |
|
mapped to MBIM IP session 0. |
|
|
|
|
|
Multiplexed IP sessions (IPS) |
|
----------------------------- |
|
MBIM allows multiplexing up to 256 IP sessions over a single USB data |
|
channel. The cdc_mbim driver models such IP sessions as 802.1q VLAN |
|
subdevices of the master wwanY device, mapping MBIM IP session Z to |
|
VLAN ID Z for all values of Z greater than 0. |
|
|
|
The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure |
|
described in section 10.5.1 of [1]. |
|
|
|
The userspace management application is responsible for adding new |
|
VLAN links prior to establishing MBIM IP sessions where the SessionId |
|
is greater than 0. These links can be added by using the normal VLAN |
|
kernel interfaces, either ioctl or netlink. |
|
|
|
For example, adding a link for a MBIM IP session with SessionId 3:: |
|
|
|
ip link add link wwan0 name wwan0.3 type vlan id 3 |
|
|
|
The driver will automatically map the "wwan0.3" network device to MBIM |
|
IP session 3. |
|
|
|
|
|
Device Service Streams (DSS) |
|
---------------------------- |
|
MBIM also allows up to 256 non-IP data streams to be multiplexed over |
|
the same shared USB data channel. The cdc_mbim driver models these |
|
sessions as another set of 802.1q VLAN subdevices of the master wwanY |
|
device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values |
|
of A. |
|
|
|
The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO |
|
structure described in section 10.5.29 of [1]. |
|
|
|
The DSS VLAN subdevices are used as a practical interface between the |
|
shared MBIM data channel and a MBIM DSS aware userspace application. |
|
It is not intended to be presented as-is to an end user. The |
|
assumption is that a userspace application initiating a DSS session |
|
also takes care of the necessary framing of the DSS data, presenting |
|
the stream to the end user in an appropriate way for the stream type. |
|
|
|
The network device ABI requires a dummy ethernet header for every DSS |
|
data frame being transported. The contents of this header is |
|
arbitrary, with the following exceptions: |
|
|
|
- TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped |
|
- RX frames will have the protocol field set to ETH_P_802_3 (but will |
|
not be properly formatted 802.3 frames) |
|
- RX frames will have the destination address set to the hardware |
|
address of the master device |
|
|
|
The DSS supporting userspace management application is responsible for |
|
adding the dummy ethernet header on TX and stripping it on RX. |
|
|
|
This is a simple example using tools commonly available, exporting |
|
DssSessionId 5 as a pty character device pointed to by a /dev/nmea |
|
symlink:: |
|
|
|
ip link add link wwan0 name wwan0.dss5 type vlan id 261 |
|
ip link set dev wwan0.dss5 up |
|
socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea |
|
|
|
This is only an example, most suitable for testing out a DSS |
|
service. Userspace applications supporting specific MBIM DSS services |
|
are expected to use the tools and programming interfaces required by |
|
that service. |
|
|
|
Note that adding VLAN links for DSS sessions is entirely optional. A |
|
management application may instead choose to bind a packet socket |
|
directly to the master network device, using the received VLAN tags to |
|
map frames to the correct DSS session and adding 18 byte VLAN ethernet |
|
headers with the appropriate tag on TX. In this case using a socket |
|
filter is recommended, matching only the DSS VLAN subset. This avoid |
|
unnecessary copying of unrelated IP session data to userspace. For |
|
example:: |
|
|
|
static struct sock_filter dssfilter[] = { |
|
/* use special negative offsets to get VLAN tag */ |
|
BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT), |
|
BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */ |
|
|
|
/* verify DSS VLAN range */ |
|
BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG), |
|
BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4), /* 256 is first DSS VLAN */ |
|
BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */ |
|
|
|
/* verify ethertype */ |
|
BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN), |
|
BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1), |
|
|
|
BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */ |
|
BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */ |
|
}; |
|
|
|
|
|
|
|
Tagged IP session 0 VLAN |
|
------------------------ |
|
As described above, MBIM IP session 0 is treated as special by the |
|
driver. It is initially mapped to untagged frames on the wwanY |
|
network device. |
|
|
|
This mapping implies a few restrictions on multiplexed IPS and DSS |
|
sessions, which may not always be practical: |
|
|
|
- no IPS or DSS session can use a frame size greater than the MTU on |
|
IP session 0 |
|
- no IPS or DSS session can be in the up state unless the network |
|
device representing IP session 0 also is up |
|
|
|
These problems can be avoided by optionally making the driver map IP |
|
session 0 to a VLAN subdevice, similar to all other IP sessions. This |
|
behaviour is triggered by adding a VLAN link for the magic VLAN ID |
|
4094. The driver will then immediately start mapping MBIM IP session |
|
0 to this VLAN, and will drop untagged frames on the master wwanY |
|
device. |
|
|
|
Tip: It might be less confusing to the end user to name this VLAN |
|
subdevice after the MBIM SessionID instead of the VLAN ID. For |
|
example:: |
|
|
|
ip link add link wwan0 name wwan0.0 type vlan id 4094 |
|
|
|
|
|
VLAN mapping |
|
------------ |
|
|
|
Summarizing the cdc_mbim driver mapping described above, we have this |
|
relationship between VLAN tags on the wwanY network device and MBIM |
|
sessions on the shared USB data channel:: |
|
|
|
VLAN ID MBIM type MBIM SessionID Notes |
|
--------------------------------------------------------- |
|
untagged IPS 0 a) |
|
1 - 255 IPS 1 - 255 <VLANID> |
|
256 - 511 DSS 0 - 255 <VLANID - 256> |
|
512 - 4093 b) |
|
4094 IPS 0 c) |
|
|
|
a) if no VLAN ID 4094 link exists, else dropped |
|
b) unsupported VLAN range, unconditionally dropped |
|
c) if a VLAN ID 4094 link exists, else dropped |
|
|
|
|
|
|
|
|
|
References |
|
========== |
|
|
|
1) USB Implementers Forum, Inc. - "Universal Serial Bus |
|
Communications Class Subclass Specification for Mobile Broadband |
|
Interface Model", Revision 1.0 (Errata 1), May 1, 2013 |
|
|
|
- http://www.usb.org/developers/docs/devclass_docs/ |
|
|
|
2) USB Implementers Forum, Inc. - "Universal Serial Bus |
|
Communications Class Subclass Specifications for Network Control |
|
Model Devices", Revision 1.0 (Errata 1), November 24, 2010 |
|
|
|
- http://www.usb.org/developers/docs/devclass_docs/ |
|
|
|
3) libmbim - "a glib-based library for talking to WWAN modems and |
|
devices which speak the Mobile Interface Broadband Model (MBIM) |
|
protocol" |
|
|
|
- http://www.freedesktop.org/wiki/Software/libmbim/ |
|
|
|
4) ModemManager - "a DBus-activated daemon which controls mobile |
|
broadband (2G/3G/4G) devices and connections" |
|
|
|
- http://www.freedesktop.org/wiki/Software/ModemManager/ |
|
|
|
5) "MBIM (Mobile Broadband Interface Model) Registry" |
|
|
|
- http://compliance.usb.org/mbim/ |
|
|
|
6) "/sys/kernel/debug/usb/devices output format" |
|
|
|
- Documentation/driver-api/usb/usb.rst |
|
|
|
7) "/sys/bus/usb/devices/.../descriptors" |
|
|
|
- Documentation/ABI/stable/sysfs-bus-usb
|
|
|