Documentation/networking/device_drivers/wwan/t7xx.rst

   1 .. SPDX-License-Identifier: GPL-2.0-only
   2
   3 .. Copyright (C) 2020-21 Intel Corporation
   4
   5 .. _t7xx_driver_doc:
   6
   7 ============================================
   8 t7xx driver for MTK PCIe based T700 5G modem
   9 ============================================
  10 The t7xx driver is a WWAN PCIe host driver developed for linux or Chrome OS platforms
  11 for data exchange over PCIe interface between Host platform & MediaTek's T700 5G modem.
  12 The driver exposes an interface conforming to the MBIM protocol [1]. Any front end
  13 application (e.g. Modem Manager) could easily manage the MBIM interface to enable
  14 data communication towards WWAN. The driver also provides an interface to interact
  15 with the MediaTek's modem via AT commands.
  16
  17 Basic usage
  18 ===========
  19 MBIM & AT functions are inactive when unmanaged. The t7xx driver provides
  20 WWAN port userspace interfaces representing MBIM & AT control channels and does
  21 not play any role in managing their functionality. It is the job of a userspace
  22 application to detect port enumeration and enable MBIM & AT functionalities.
  23
  24 Examples of few such userspace applications are:
  25
  26 - mbimcli (included with the libmbim [2] library), and
  27 - Modem Manager [3]
  28
  29 Management Applications to carry out below required actions for establishing
  30 MBIM IP session:
  31
  32 - open the MBIM control channel
  33 - configure network connection settings
  34 - connect to network
  35 - configure IP network interface
  36
  37 Management Applications to carry out below required actions for send an AT
  38 command and receive response:
  39
  40 - open the AT control channel using a UART tool or a special user tool
  41
  42 Management application development
  43 ==================================
  44 The driver and userspace interfaces are described below. The MBIM protocol is
  45 described in [1] Mobile Broadband Interface Model v1.0 Errata-1.
  46
  47 MBIM control channel userspace ABI
  48 ----------------------------------
  49
  50 /dev/wwan0mbim0 character device
  51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52 The driver exposes an MBIM interface to the MBIM function by implementing
  53 MBIM WWAN Port. The userspace end of the control channel pipe is a
  54 /dev/wwan0mbim0 character device. Application shall use this interface for
  55 MBIM protocol communication.
  56
  57 Fragmentation
  58 ~~~~~~~~~~~~~
  59 The userspace application is responsible for all control message fragmentation
  60 and defragmentation as per MBIM specification.
  61
  62 /dev/wwan0mbim0 write()
  63 ~~~~~~~~~~~~~~~~~~~~~~~
  64 The MBIM control messages from the management application must not exceed the
  65 negotiated control message size.
  66
  67 /dev/wwan0mbim0 read()
  68 ~~~~~~~~~~~~~~~~~~~~~~
  69 The management application must accept control messages of up the negotiated
  70 control message size.
  71
  72 MBIM data channel userspace ABI
  73 -------------------------------
  74
  75 wwan0-X network device
  76 ~~~~~~~~~~~~~~~~~~~~~~
  77 The t7xx driver exposes IP link interface "wwan0-X" of type "wwan" for IP
  78 traffic. Iproute network utility is used for creating "wwan0-X" network
  79 interface and for associating it with MBIM IP session.
  80
  81 The userspace management application is responsible for creating new IP link
  82 prior to establishing MBIM IP session where the SessionId is greater than 0.
  83
  84 For example, creating new IP link for a MBIM IP session with SessionId 1:
  85
  86   ip link add dev wwan0-1 parentdev wwan0 type wwan linkid 1
  87
  88 The driver will automatically map the "wwan0-1" network device to MBIM IP
  89 session 1.
  90
  91 AT port userspace ABI
  92 ----------------------------------
  93
  94 /dev/wwan0at0 character device
  95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96 The driver exposes an AT port by implementing AT WWAN Port.
  97 The userspace end of the control port is a /dev/wwan0at0 character
  98 device. Application shall use this interface to issue AT commands.
  99
 100 The MediaTek's T700 modem supports the 3GPP TS 27.007 [4] specification.
 101
 102 References
 103 ==========
 104 [1] *MBIM (Mobile Broadband Interface Model) Errata-1*
 105
 106 - https://www.usb.org/document-library/
 107
 108 [2] *libmbim "a glib-based library for talking to WWAN modems and devices which
 109 speak the Mobile Interface Broadband Model (MBIM) protocol"*
 110
 111 - http://www.freedesktop.org/wiki/Software/libmbim/
 112
 113 [3] *Modem Manager "a DBus-activated daemon which controls mobile broadband
 114 (2G/3G/4G/5G) devices and connections"*
 115
 116 - http://www.freedesktop.org/wiki/Software/ModemManager/
 117
 118 [4] *Specification # 27.007 - 3GPP*
 119
 120 - https://www.3gpp.org/DynaReport/27007.htm