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