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