Debian Codegraph @

Documentation/networking/device_drivers/wwan/t7xx.rst

raw
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