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