|
@@ -0,0 +1,339 @@
|
|
|
+ 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 an 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 an 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] "/proc/bus/usb filesystem output"
|
|
|
+ - Documentation/usb/proc_usb_info.txt
|
|
|
+
|
|
|
+[7] "/sys/bus/usb/devices/.../descriptors"
|
|
|
+ - Documentation/ABI/stable/sysfs-bus-usb
|