tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork atom

docs: networking: convert cdc_mbim.txt to ReST

- 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>

authored by

Mauro Carvalho Chehab and committed by
David S. Miller 92f06f42 a362032e

+47 -30
+46 -30
Documentation/networking/cdc_mbim.txt Documentation/networking/cdc_mbim.rst
··· 1 - cdc_mbim - Driver for CDC MBIM Mobile Broadband modems 2 - ======================================================== 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ====================================================== 4 + cdc_mbim - Driver for CDC MBIM Mobile Broadband modems 5 + ====================================================== 3 6 4 7 The cdc_mbim driver supports USB devices conforming to the "Universal 5 8 Serial Bus Communications Class Subclass Specification for Mobile ··· 22 19 23 20 prefer_mbim 24 21 ----------- 25 - Type: Boolean 26 - Valid Range: N/Y (0-1) 27 - Default Value: Y (MBIM is preferred) 22 + :Type: Boolean 23 + :Valid Range: N/Y (0-1) 24 + :Default Value: Y (MBIM is preferred) 28 25 29 26 This parameter sets the system policy for NCM/MBIM functions. Such 30 27 functions will be handled by either the cdc_ncm driver or the cdc_mbim ··· 47 44 MBIM function. 48 45 49 46 Such userspace applications includes, but are not limited to: 47 + 50 48 - mbimcli (included with the libmbim [3] library), and 51 49 - ModemManager [4] 52 50 53 51 Establishing a MBIM IP session reequires at least these actions by the 54 52 management application: 53 + 55 54 - open the control channel 56 55 - configure network connection settings 57 56 - connect to network ··· 81 76 82 77 The cdc-wdmX device is created as a child of the MBIM control 83 78 interface USB device. The character device associated with a specific 84 - MBIM function can be looked up using sysfs. For example: 79 + MBIM function can be looked up using sysfs. For example:: 85 80 86 81 bjorn@nemi:~$ ls /sys/bus/usb/drivers/cdc_mbim/2-4:2.12/usbmisc 87 82 cdc-wdm0 ··· 124 119 125 120 126 121 /dev/cdc-wdmX ioctl() 127 - -------------------- 122 + --------------------- 128 123 IOCTL_WDM_MAX_COMMAND: Get Maximum Command Size 129 124 This ioctl returns the wMaxControlMessage field of the CDC MBIM 130 125 functional descriptor for MBIM devices. This is intended as a 131 126 convenience, eliminating the need to parse the USB descriptors from 132 127 userspace. 128 + 129 + :: 133 130 134 131 #include <stdio.h> 135 132 #include <fcntl.h> ··· 185 178 is greater than 0. These links can be added by using the normal VLAN 186 179 kernel interfaces, either ioctl or netlink. 187 180 188 - For example, adding a link for a MBIM IP session with SessionId 3: 181 + For example, adding a link for a MBIM IP session with SessionId 3:: 189 182 190 183 ip link add link wwan0 name wwan0.3 type vlan id 3 191 184 ··· 214 207 The network device ABI requires a dummy ethernet header for every DSS 215 208 data frame being transported. The contents of this header is 216 209 arbitrary, with the following exceptions: 210 + 217 211 - TX frames using an IP protocol (0x0800 or 0x86dd) will be dropped 218 212 - RX frames will have the protocol field set to ETH_P_802_3 (but will 219 213 not be properly formatted 802.3 frames) ··· 226 218 227 219 This is a simple example using tools commonly available, exporting 228 220 DssSessionId 5 as a pty character device pointed to by a /dev/nmea 229 - symlink: 221 + symlink:: 230 222 231 223 ip link add link wwan0 name wwan0.dss5 type vlan id 261 232 224 ip link set dev wwan0.dss5 up ··· 244 236 headers with the appropriate tag on TX. In this case using a socket 245 237 filter is recommended, matching only the DSS VLAN subset. This avoid 246 238 unnecessary copying of unrelated IP session data to userspace. For 247 - example: 239 + example:: 248 240 249 241 static struct sock_filter dssfilter[] = { 250 242 /* use special negative offsets to get VLAN tag */ ··· 257 249 BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 512, 3, 0), /* 511 is last DSS VLAN */ 258 250 259 251 /* verify ethertype */ 260 - BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN), 261 - BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1), 252 + BPF_STMT(BPF_LD|BPF_H|BPF_ABS, 2 * ETH_ALEN), 253 + BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ETH_P_802_3, 0, 1), 262 254 263 - BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */ 264 - BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */ 255 + BPF_STMT(BPF_RET|BPF_K, (u_int)-1), /* accept */ 256 + BPF_STMT(BPF_RET|BPF_K, 0), /* ignore */ 265 257 }; 266 258 267 259 ··· 274 266 275 267 This mapping implies a few restrictions on multiplexed IPS and DSS 276 268 sessions, which may not always be practical: 269 + 277 270 - no IPS or DSS session can use a frame size greater than the MTU on 278 271 IP session 0 279 272 - no IPS or DSS session can be in the up state unless the network ··· 289 280 290 281 Tip: It might be less confusing to the end user to name this VLAN 291 282 subdevice after the MBIM SessionID instead of the VLAN ID. For 292 - example: 283 + example:: 293 284 294 285 ip link add link wwan0 name wwan0.0 type vlan id 4094 295 286 ··· 299 290 300 291 Summarizing the cdc_mbim driver mapping described above, we have this 301 292 relationship between VLAN tags on the wwanY network device and MBIM 302 - sessions on the shared USB data channel: 293 + sessions on the shared USB data channel:: 303 294 304 295 VLAN ID MBIM type MBIM SessionID Notes 305 296 --------------------------------------------------------- ··· 319 310 References 320 311 ========== 321 312 322 - [1] USB Implementers Forum, Inc. - "Universal Serial Bus 323 - Communications Class Subclass Specification for Mobile Broadband 324 - Interface Model", Revision 1.0 (Errata 1), May 1, 2013 313 + 1) USB Implementers Forum, Inc. - "Universal Serial Bus 314 + Communications Class Subclass Specification for Mobile Broadband 315 + Interface Model", Revision 1.0 (Errata 1), May 1, 2013 316 + 325 317 - http://www.usb.org/developers/docs/devclass_docs/ 326 318 327 - [2] USB Implementers Forum, Inc. - "Universal Serial Bus 328 - Communications Class Subclass Specifications for Network Control 329 - Model Devices", Revision 1.0 (Errata 1), November 24, 2010 319 + 2) USB Implementers Forum, Inc. - "Universal Serial Bus 320 + Communications Class Subclass Specifications for Network Control 321 + Model Devices", Revision 1.0 (Errata 1), November 24, 2010 322 + 330 323 - http://www.usb.org/developers/docs/devclass_docs/ 331 324 332 - [3] libmbim - "a glib-based library for talking to WWAN modems and 333 - devices which speak the Mobile Interface Broadband Model (MBIM) 334 - protocol" 325 + 3) libmbim - "a glib-based library for talking to WWAN modems and 326 + devices which speak the Mobile Interface Broadband Model (MBIM) 327 + protocol" 328 + 335 329 - http://www.freedesktop.org/wiki/Software/libmbim/ 336 330 337 - [4] ModemManager - "a DBus-activated daemon which controls mobile 338 - broadband (2G/3G/4G) devices and connections" 331 + 4) ModemManager - "a DBus-activated daemon which controls mobile 332 + broadband (2G/3G/4G) devices and connections" 333 + 339 334 - http://www.freedesktop.org/wiki/Software/ModemManager/ 340 335 341 - [5] "MBIM (Mobile Broadband Interface Model) Registry" 336 + 5) "MBIM (Mobile Broadband Interface Model) Registry" 337 + 342 338 - http://compliance.usb.org/mbim/ 343 339 344 - [6] "/sys/kernel/debug/usb/devices output format" 340 + 6) "/sys/kernel/debug/usb/devices output format" 341 + 345 342 - Documentation/driver-api/usb/usb.rst 346 343 347 - [7] "/sys/bus/usb/devices/.../descriptors" 344 + 7) "/sys/bus/usb/devices/.../descriptors" 345 + 348 346 - Documentation/ABI/stable/sysfs-bus-usb
+1
Documentation/networking/index.rst
··· 45 45 ax25 46 46 baycom 47 47 bonding 48 + cdc_mbim 48 49 49 50 .. only:: subproject and html 50 51