cdc_mbim.rst 12 KB

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