0001 .. SPDX-License-Identifier: GPL-2.0-only
0002
0003 .. Copyright (C) 2020-21 Intel Corporation
0004
0005 .. _t7xx_driver_doc:
0006
0007 ============================================
0008 t7xx driver for MTK PCIe based T700 5G modem
0009 ============================================
0010 The t7xx driver is a WWAN PCIe host driver developed for linux or Chrome OS platforms
0011 for data exchange over PCIe interface between Host platform & MediaTek's T700 5G modem.
0012 The driver exposes an interface conforming to the MBIM protocol [1]. Any front end
0013 application (e.g. Modem Manager) could easily manage the MBIM interface to enable
0014 data communication towards WWAN. The driver also provides an interface to interact
0015 with the MediaTek's modem via AT commands.
0016
0017 Basic usage
0018 ===========
0019 MBIM & AT functions are inactive when unmanaged. The t7xx driver provides
0020 WWAN port userspace interfaces representing MBIM & AT control channels and does
0021 not play any role in managing their functionality. It is the job of a userspace
0022 application to detect port enumeration and enable MBIM & AT functionalities.
0023
0024 Examples of few such userspace applications are:
0025
0026 - mbimcli (included with the libmbim [2] library), and
0027 - Modem Manager [3]
0028
0029 Management Applications to carry out below required actions for establishing
0030 MBIM IP session:
0031
0032 - open the MBIM control channel
0033 - configure network connection settings
0034 - connect to network
0035 - configure IP network interface
0036
0037 Management Applications to carry out below required actions for send an AT
0038 command and receive response:
0039
0040 - open the AT control channel using a UART tool or a special user tool
0041
0042 Management application development
0043 ==================================
0044 The driver and userspace interfaces are described below. The MBIM protocol is
0045 described in [1] Mobile Broadband Interface Model v1.0 Errata-1.
0046
0047 MBIM control channel userspace ABI
0048 ----------------------------------
0049
0050 /dev/wwan0mbim0 character device
0051 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0052 The driver exposes an MBIM interface to the MBIM function by implementing
0053 MBIM WWAN Port. The userspace end of the control channel pipe is a
0054 /dev/wwan0mbim0 character device. Application shall use this interface for
0055 MBIM protocol communication.
0056
0057 Fragmentation
0058 ~~~~~~~~~~~~~
0059 The userspace application is responsible for all control message fragmentation
0060 and defragmentation as per MBIM specification.
0061
0062 /dev/wwan0mbim0 write()
0063 ~~~~~~~~~~~~~~~~~~~~~~~
0064 The MBIM control messages from the management application must not exceed the
0065 negotiated control message size.
0066
0067 /dev/wwan0mbim0 read()
0068 ~~~~~~~~~~~~~~~~~~~~~~
0069 The management application must accept control messages of up the negotiated
0070 control message size.
0071
0072 MBIM data channel userspace ABI
0073 -------------------------------
0074
0075 wwan0-X network device
0076 ~~~~~~~~~~~~~~~~~~~~~~
0077 The t7xx driver exposes IP link interface "wwan0-X" of type "wwan" for IP
0078 traffic. Iproute network utility is used for creating "wwan0-X" network
0079 interface and for associating it with MBIM IP session.
0080
0081 The userspace management application is responsible for creating new IP link
0082 prior to establishing MBIM IP session where the SessionId is greater than 0.
0083
0084 For example, creating new IP link for a MBIM IP session with SessionId 1:
0085
0086 ip link add dev wwan0-1 parentdev wwan0 type wwan linkid 1
0087
0088 The driver will automatically map the "wwan0-1" network device to MBIM IP
0089 session 1.
0090
0091 AT port userspace ABI
0092 ----------------------------------
0093
0094 /dev/wwan0at0 character device
0095 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0096 The driver exposes an AT port by implementing AT WWAN Port.
0097 The userspace end of the control port is a /dev/wwan0at0 character
0098 device. Application shall use this interface to issue AT commands.
0099
0100 The MediaTek's T700 modem supports the 3GPP TS 27.007 [4] specification.
0101
0102 References
0103 ==========
0104 [1] *MBIM (Mobile Broadband Interface Model) Errata-1*
0105
0106 - https://www.usb.org/document-library/
0107
0108 [2] *libmbim "a glib-based library for talking to WWAN modems and devices which
0109 speak the Mobile Interface Broadband Model (MBIM) protocol"*
0110
0111 - http://www.freedesktop.org/wiki/Software/libmbim/
0112
0113 [3] *Modem Manager "a DBus-activated daemon which controls mobile broadband
0114 (2G/3G/4G/5G) devices and connections"*
0115
0116 - http://www.freedesktop.org/wiki/Software/ModemManager/
0117
0118 [4] *Specification # 27.007 - 3GPP*
0119
0120 - https://www.3gpp.org/DynaReport/27007.htm
