xref: /linux/Documentation/networking/device_drivers/wwan/t7xx.rst (revision f7f52738637f4361c108cad36e23ee98959a9006)
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