1.. SPDX-License-Identifier: GPL-2.0-only 2 3.. Copyright (C) 2020-21 Intel Corporation 4 5.. _t7xx_driver_doc: 6 7============================================ 8t7xx driver for MTK PCIe based T700 5G modem 9============================================ 10The t7xx driver is a WWAN PCIe host driver developed for linux or Chrome OS platforms 11for data exchange over PCIe interface between Host platform & MediaTek's T700 5G modem. 12The driver exposes an interface conforming to the MBIM protocol [1]. Any front end 13application (e.g. Modem Manager) could easily manage the MBIM interface to enable 14data communication towards WWAN. The driver also provides an interface to interact 15with the MediaTek's modem via AT commands. 16 17Basic usage 18=========== 19MBIM & AT functions are inactive when unmanaged. The t7xx driver provides 20WWAN port userspace interfaces representing MBIM & AT control channels and does 21not play any role in managing their functionality. It is the job of a userspace 22application to detect port enumeration and enable MBIM & AT functionalities. 23 24Examples of few such userspace applications are: 25 26- mbimcli (included with the libmbim [2] library), and 27- Modem Manager [3] 28 29Management Applications to carry out below required actions for establishing 30MBIM IP session: 31 32- open the MBIM control channel 33- configure network connection settings 34- connect to network 35- configure IP network interface 36 37Management Applications to carry out below required actions for send an AT 38command and receive response: 39 40- open the AT control channel using a UART tool or a special user tool 41 42Sysfs 43===== 44The driver provides sysfs interfaces to userspace. 45 46t7xx_mode 47--------- 48The sysfs interface provides userspace with access to the device mode, this interface 49supports read and write operations. 50 51Device mode: 52 53- ``unknown`` represents that device in unknown status 54- ``ready`` represents that device in ready status 55- ``reset`` represents that device in reset status 56- ``fastboot_switching`` represents that device in fastboot switching status 57- ``fastboot_download`` represents that device in fastboot download status 58- ``fastboot_dump`` represents that device in fastboot dump status 59 60Read from userspace to get the current device mode. 61 62:: 63 $ cat /sys/bus/pci/devices/${bdf}/t7xx_mode 64 65Write from userspace to set the device mode. 66 67:: 68 $ echo fastboot_switching > /sys/bus/pci/devices/${bdf}/t7xx_mode 69 70Management application development 71================================== 72The driver and userspace interfaces are described below. The MBIM protocol is 73described in [1] Mobile Broadband Interface Model v1.0 Errata-1. 74 75MBIM control channel userspace ABI 76---------------------------------- 77 78/dev/wwan0mbim0 character device 79~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 80The driver exposes an MBIM interface to the MBIM function by implementing 81MBIM WWAN Port. The userspace end of the control channel pipe is a 82/dev/wwan0mbim0 character device. Application shall use this interface for 83MBIM protocol communication. 84 85Fragmentation 86~~~~~~~~~~~~~ 87The userspace application is responsible for all control message fragmentation 88and defragmentation as per MBIM specification. 89 90/dev/wwan0mbim0 write() 91~~~~~~~~~~~~~~~~~~~~~~~ 92The MBIM control messages from the management application must not exceed the 93negotiated control message size. 94 95/dev/wwan0mbim0 read() 96~~~~~~~~~~~~~~~~~~~~~~ 97The management application must accept control messages of up the negotiated 98control message size. 99 100MBIM data channel userspace ABI 101------------------------------- 102 103wwan0-X network device 104~~~~~~~~~~~~~~~~~~~~~~ 105The t7xx driver exposes IP link interface "wwan0-X" of type "wwan" for IP 106traffic. Iproute network utility is used for creating "wwan0-X" network 107interface and for associating it with MBIM IP session. 108 109The userspace management application is responsible for creating new IP link 110prior to establishing MBIM IP session where the SessionId is greater than 0. 111 112For example, creating new IP link for a MBIM IP session with SessionId 1: 113 114 ip link add dev wwan0-1 parentdev wwan0 type wwan linkid 1 115 116The driver will automatically map the "wwan0-1" network device to MBIM IP 117session 1. 118 119AT port userspace ABI 120---------------------------------- 121 122/dev/wwan0at0 character device 123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 124The driver exposes an AT port by implementing AT WWAN Port. 125The userspace end of the control port is a /dev/wwan0at0 character 126device. Application shall use this interface to issue AT commands. 127 128fastboot port userspace ABI 129--------------------------- 130 131/dev/wwan0fastboot0 character device 132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133The driver exposes a fastboot protocol interface by implementing 134fastboot WWAN Port. The userspace end of the fastboot channel pipe is a 135/dev/wwan0fastboot0 character device. Application shall use this interface for 136fastboot protocol communication. 137 138Please note that driver needs to be reloaded to export /dev/wwan0fastboot0 139port, because device needs a cold reset after enter ``fastboot_switching`` 140mode. 141 142The MediaTek's T700 modem supports the 3GPP TS 27.007 [4] specification. 143 144References 145========== 146[1] *MBIM (Mobile Broadband Interface Model) Errata-1* 147 148- https://www.usb.org/document-library/ 149 150[2] *libmbim "a glib-based library for talking to WWAN modems and devices which 151speak the Mobile Interface Broadband Model (MBIM) protocol"* 152 153- http://www.freedesktop.org/wiki/Software/libmbim/ 154 155[3] *Modem Manager "a DBus-activated daemon which controls mobile broadband 156(2G/3G/4G/5G) devices and connections"* 157 158- http://www.freedesktop.org/wiki/Software/ModemManager/ 159 160[4] *Specification # 27.007 - 3GPP* 161 162- https://www.3gpp.org/DynaReport/27007.htm 163 164[5] *fastboot "a mechanism for communicating with bootloaders"* 165 166- https://android.googlesource.com/platform/system/core/+/refs/heads/main/fastboot/README.md 167