^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) cdc_mbim - Driver for CDC MBIM Mobile Broadband modems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The cdc_mbim driver supports USB devices conforming to the "Universal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Serial Bus Communications Class Subclass Specification for Mobile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) Broadband Interface Model" [1], which is a further development of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) "Universal Serial Bus Communications Class Subclass Specifications for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Network Control Model Devices" [2] optimized for Mobile Broadband
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) devices, aka "3G/LTE modems".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Command Line Parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) The cdc_mbim driver has no parameters of its own. But the probing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) behaviour for NCM 1.0 backwards compatible MBIM functions (an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) "NCM/MBIM function" as defined in section 3.2 of [1]) is affected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) by a cdc_ncm driver parameter:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) prefer_mbim
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) :Type: Boolean
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) :Valid Range: N/Y (0-1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) :Default Value: Y (MBIM is preferred)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) This parameter sets the system policy for NCM/MBIM functions. Such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) functions will be handled by either the cdc_ncm driver or the cdc_mbim
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) driver depending on the prefer_mbim setting. Setting prefer_mbim=N
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) makes the cdc_mbim driver ignore these functions and lets the cdc_ncm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) driver handle them instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) The parameter is writable, and can be changed at any time. A manual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) unbind/bind is required to make the change effective for NCM/MBIM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) functions bound to the "wrong" driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Basic usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) MBIM functions are inactive when unmanaged. The cdc_mbim driver only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) provides a userspace interface to the MBIM control channel, and will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) not participate in the management of the function. This implies that a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) userspace MBIM management application always is required to enable a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) MBIM function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) Such userspace applications includes, but are not limited to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) - mbimcli (included with the libmbim [3] library), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) - ModemManager [4]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Establishing a MBIM IP session reequires at least these actions by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) management application:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) - open the control channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) - configure network connection settings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) - connect to network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) - configure IP interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Management application development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) The driver <-> userspace interfaces are described below. The MBIM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) control channel protocol is described in [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) MBIM control channel userspace ABI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) /dev/cdc-wdmX character device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) The driver creates a two-way pipe to the MBIM function control channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) using the cdc-wdm driver as a subdriver. The userspace end of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) control channel pipe is a /dev/cdc-wdmX character device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) The cdc_mbim driver does not process or police messages on the control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) channel. The channel is fully delegated to the userspace management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) application. It is therefore up to this application to ensure that it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) complies with all the control channel requirements in [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) The cdc-wdmX device is created as a child of the MBIM control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) interface USB device. The character device associated with a specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) MBIM function can be looked up using sysfs. For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) cdc-wdm0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) bjorn@nemi:~$ grep . /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc/cdc-wdm0/dev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) 180:0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) USB configuration descriptors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) The wMaxControlMessage field of the CDC MBIM functional descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) limits the maximum control message size. The managament application is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) responsible for negotiating a control message size complying with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) requirements in section 9.3.1 of [1], taking this descriptor field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) into consideration.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) The userspace application can access the CDC MBIM functional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) descriptor of a MBIM function using either of the two USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) configuration descriptor kernel interfaces described in [6] or [7].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) See also the ioctl documentation below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) Fragmentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) The userspace application is responsible for all control message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) fragmentation and defragmentaion, as described in section 9.5 of [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) /dev/cdc-wdmX write()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) The MBIM control messages from the management application *must not*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) exceed the negotiated control message size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) /dev/cdc-wdmX read()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) The management application *must* accept control messages of up the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) negotiated control message size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) /dev/cdc-wdmX ioctl()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) This ioctl returns the wMaxControlMessage field of the CDC MBIM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) functional descriptor for MBIM devices. This is intended as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) convenience, eliminating the need to parse the USB descriptors from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) #include <stdio.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) #include <fcntl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) #include <sys/ioctl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) #include <linux/types.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) #include <linux/usb/cdc-wdm.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) int main()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) __u16 max;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) int fd = open("/dev/cdc-wdm0", O_RDWR);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) if (!ioctl(fd, IOCTL_WDM_MAX_COMMAND, &max))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) printf("wMaxControlMessage is %d\n", max);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Custom device services
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) The MBIM specification allows vendors to freely define additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) services. This is fully supported by the cdc_mbim driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) Support for new MBIM services, including vendor specified services, is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) implemented entirely in userspace, like the rest of the MBIM control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) New services should be registered in the MBIM Registry [5].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) MBIM data channel userspace ABI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) wwanY network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) The cdc_mbim driver represents the MBIM data channel as a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) network device of the "wwan" type. This network device is initially
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) mapped to MBIM IP session 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Multiplexed IP sessions (IPS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) MBIM allows multiplexing up to 256 IP sessions over a single USB data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) channel. The cdc_mbim driver models such IP sessions as 802.1q VLAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) subdevices of the master wwanY device, mapping MBIM IP session Z to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) VLAN ID Z for all values of Z greater than 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) The device maximum Z is given in the MBIM_DEVICE_CAPS_INFO structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) described in section 10.5.1 of [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) The userspace management application is responsible for adding new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) VLAN links prior to establishing MBIM IP sessions where the SessionId
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) is greater than 0. These links can be added by using the normal VLAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) kernel interfaces, either ioctl or netlink.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) For example, adding a link for a MBIM IP session with SessionId 3::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) ip link add link wwan0 name wwan0.3 type vlan id 3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) The driver will automatically map the "wwan0.3" network device to MBIM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) IP session 3.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Device Service Streams (DSS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) MBIM also allows up to 256 non-IP data streams to be multiplexed over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) the same shared USB data channel. The cdc_mbim driver models these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) sessions as another set of 802.1q VLAN subdevices of the master wwanY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) device, mapping MBIM DSS session A to VLAN ID (256 + A) for all values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) of A.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) The device maximum A is given in the MBIM_DEVICE_SERVICES_INFO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) structure described in section 10.5.29 of [1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) The DSS VLAN subdevices are used as a practical interface between the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) shared MBIM data channel and a MBIM DSS aware userspace application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) It is not intended to be presented as-is to an end user. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) assumption is that a userspace application initiating a DSS session
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) also takes care of the necessary framing of the DSS data, presenting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) the stream to the end user in an appropriate way for the stream type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) The network device ABI requires a dummy ethernet header for every DSS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) data frame being transported. The contents of this header is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) arbitrary, with the following exceptions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) - RX frames will have the protocol field set to ETH_P_802_3 (but will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) not be properly formatted 802.3 frames)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) - RX frames will have the destination address set to the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) address of the master device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) The DSS supporting userspace management application is responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) adding the dummy ethernet header on TX and stripping it on RX.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) This is a simple example using tools commonly available, exporting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) DssSessionId 5 as a pty character device pointed to by a /dev/nmea
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) symlink::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) ip link add link wwan0 name wwan0.dss5 type vlan id 261
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) ip link set dev wwan0.dss5 up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) socat INTERFACE:wwan0.dss5,type=2 PTY:,echo=0,link=/dev/nmea
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) This is only an example, most suitable for testing out a DSS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) service. Userspace applications supporting specific MBIM DSS services
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) are expected to use the tools and programming interfaces required by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) that service.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) Note that adding VLAN links for DSS sessions is entirely optional. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) management application may instead choose to bind a packet socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) directly to the master network device, using the received VLAN tags to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) map frames to the correct DSS session and adding 18 byte VLAN ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) headers with the appropriate tag on TX. In this case using a socket
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) filter is recommended, matching only the DSS VLAN subset. This avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) unnecessary copying of unrelated IP session data to userspace. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) static struct sock_filter dssfilter[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) /* use special negative offsets to get VLAN tag */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) BPF_STMT(BPF_LD|BPF_B|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG_PRESENT),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, 1, 0, 6), /* true */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) /* verify DSS VLAN range */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) BPF_STMT(BPF_LD|BPF_H|BPF_ABS, SKF_AD_OFF + SKF_AD_VLAN_TAG),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 256, 0, 4), /* 256 is first DSS VLAN */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) /* verify ethertype */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) Tagged IP session 0 VLAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) As described above, MBIM IP session 0 is treated as special by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) driver. It is initially mapped to untagged frames on the wwanY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) network device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) This mapping implies a few restrictions on multiplexed IPS and DSS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) sessions, which may not always be practical:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) - no IPS or DSS session can use a frame size greater than the MTU on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) IP session 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) - no IPS or DSS session can be in the up state unless the network
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) device representing IP session 0 also is up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) These problems can be avoided by optionally making the driver map IP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) session 0 to a VLAN subdevice, similar to all other IP sessions. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) behaviour is triggered by adding a VLAN link for the magic VLAN ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) 4094. The driver will then immediately start mapping MBIM IP session
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 0 to this VLAN, and will drop untagged frames on the master wwanY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) Tip: It might be less confusing to the end user to name this VLAN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) subdevice after the MBIM SessionID instead of the VLAN ID. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) ip link add link wwan0 name wwan0.0 type vlan id 4094
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) VLAN mapping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) Summarizing the cdc_mbim driver mapping described above, we have this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) relationship between VLAN tags on the wwanY network device and MBIM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) sessions on the shared USB data channel::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) VLAN ID MBIM type MBIM SessionID Notes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) ---------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) untagged IPS 0 a)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) 1 - 255 IPS 1 - 255 <VLANID>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) 256 - 511 DSS 0 - 255 <VLANID - 256>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) 512 - 4093 b)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) 4094 IPS 0 c)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) a) if no VLAN ID 4094 link exists, else dropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) b) unsupported VLAN range, unconditionally dropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) c) if a VLAN ID 4094 link exists, else dropped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) References
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) 1) USB Implementers Forum, Inc. - "Universal Serial Bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) Communications Class Subclass Specification for Mobile Broadband
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) Interface Model", Revision 1.0 (Errata 1), May 1, 2013
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) - http://www.usb.org/developers/docs/devclass_docs/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) 2) USB Implementers Forum, Inc. - "Universal Serial Bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) Communications Class Subclass Specifications for Network Control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) Model Devices", Revision 1.0 (Errata 1), November 24, 2010
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) - http://www.usb.org/developers/docs/devclass_docs/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) 3) libmbim - "a glib-based library for talking to WWAN modems and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) devices which speak the Mobile Interface Broadband Model (MBIM)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) protocol"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) - http://www.freedesktop.org/wiki/Software/libmbim/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 4) ModemManager - "a DBus-activated daemon which controls mobile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) broadband (2G/3G/4G) devices and connections"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) - http://www.freedesktop.org/wiki/Software/ModemManager/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) 5) "MBIM (Mobile Broadband Interface Model) Registry"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) - http://compliance.usb.org/mbim/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) 6) "/sys/kernel/debug/usb/devices output format"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) - Documentation/driver-api/usb/usb.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) 7) "/sys/bus/usb/devices/.../descriptors"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) - Documentation/ABI/stable/sysfs-bus-usb
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags