docs: networking: convert cdc_mbim.txt to ReST
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Mon, 27 Apr 2020 22:01:25 +0000 (00:01 +0200)
committerDavid S. Miller <davem@davemloft.net>
Tue, 28 Apr 2020 21:38:39 +0000 (14:38 -0700)
- add SPDX header;
- mark code blocks and literals as such;
- use :field: markup;
- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Documentation/networking/cdc_mbim.rst [new file with mode: 0644]
Documentation/networking/cdc_mbim.txt [deleted file]
Documentation/networking/index.rst

diff --git a/Documentation/networking/cdc_mbim.rst b/Documentation/networking/cdc_mbim.rst
new file mode 100644 (file)
index 0000000..0048409
--- /dev/null
@@ -0,0 +1,355 @@
+.. 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
diff --git a/Documentation/networking/cdc_mbim.txt b/Documentation/networking/cdc_mbim.txt
deleted file mode 100644 (file)
index 4e68f0b..0000000
+++ /dev/null
@@ -1,339 +0,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
index 22b872834ef0e484c54c6f796cce2eb08bb0b02a..55802abd65a077eb11afcdc7acb19d7b8469d52a 100644 (file)
@@ -45,6 +45,7 @@ Contents:
    ax25
    baycom
    bonding
+   cdc_mbim
 
 .. only::  subproject and html