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