t7xx Driver for MediaTek T700 5G Modem

MediaTek T700 5G modem용 t7xx 드라이버

이 문서는 `GPL-2.0-only` 라이선스를 따릅니다.

Copyright 2020-2021 Intel Corporation.

MTK PCIe 기반 T700 5G modem용 t7xx 드라이버

t7xx는 Linux 또는 Chrome OS platform에서 host와 MediaTek T700 5G modem 사이의 PCIe 데이터 교환을 위해 개발한 WWAN PCIe host 드라이버입니다.

드라이버는 MBIM protocol을 따르는 interface를 노출하므로 ModemManager 같은 front-end application이 WWAN 데이터 통신을 관리할 수 있습니다.

MediaTek modem과 AT command로 상호 작용하는 interface도 제공합니다.

.. SPDX-License-Identifier: GPL-2.0-only

.. Copyright (C) 2020-21 Intel Corporation

.. _t7xx_driver_doc:

============================================
t7xx driver for MTK PCIe based T700 5G modem
============================================
The t7xx driver is a WWAN PCIe host driver developed for linux or Chrome OS
platforms for data exchange over PCIe interface between Host platform &
MediaTek's T700 5G modem.
The driver exposes an interface conforming to the MBIM protocol [1]. Any front
end application (e.g. Modem Manager) could easily manage the MBIM interface to
enable data communication towards WWAN. The driver also provides an interface
to interact with the MediaTek's modem via AT commands.

t7xx 기본 사용법

기본 사용법

MBIM과 AT function은 관리 application이 없으면 비활성 상태입니다. t7xx 드라이버는 MBIM과 AT control channel을 나타내는 WWAN port userspace interface를 제공하지만 기능을 직접 관리하지 않습니다.

userspace application이 port enumeration을 감지하고 MBIM·AT 기능을 활성화해야 합니다. 예로 libmbim의 `mbimcli`와 ModemManager가 있습니다.

MBIM IP session을 설정하려면 관리 application이 control channel을 열고, network connection을 구성하고, network에 연결하고, IP network interface를 설정해야 합니다.

AT command를 보내고 응답을 받으려면 UART tool 또는 전용 user tool로 AT control channel을 열어야 합니다.

Basic usage
===========
MBIM & AT functions are inactive when unmanaged. The t7xx driver provides
WWAN port userspace interfaces representing MBIM & AT control channels and does
not play any role in managing their functionality. It is the job of a userspace
application to detect port enumeration and enable MBIM & AT functionalities.

Examples of few such userspace applications are:

- mbimcli (included with the libmbim [2] library), and
- Modem Manager [3]

Management Applications to carry out below required actions for establishing
MBIM IP session:

- open the MBIM control channel
- configure network connection settings
- connect to network
- configure IP network interface

Management Applications to carry out below required actions for send an AT
command and receive response:

- open the AT control channel using a UART tool or a special user tool

t7xx sysfs interface

Sysfs

드라이버는 userspace에 sysfs interface를 제공합니다.

`t7xx_mode`

이 read/write sysfs interface로 userspace에서 현재 device mode를 읽거나 device mode를 설정할 수 있습니다.

$ cat /sys/bus/pci/devices/${bdf}/t7xx_mode
$ echo fastboot_switching > /sys/bus/pci/devices/${bdf}/t7xx_mode

첫 명령은 현재 mode를 읽고, 두 번째 명령은 `fastboot_switching` mode를 설정합니다.

`t7xx_debug_ports`

이 read/write sysfs interface는 debug port를 활성화하거나 비활성화합니다. 현재 지원하는 debug port는 ADB와 MIPC입니다.

$ cat /sys/bus/pci/devices/${bdf}/t7xx_debug_ports
$ echo 1 > /sys/bus/pci/devices/${bdf}/t7xx_debug_ports

첫 명령은 현재 debug port 상태를 읽고, 두 번째 명령은 debug port를 활성화합니다.

Sysfs
=====
The driver provides sysfs interfaces to userspace.

t7xx_mode
---------
The sysfs interface provides userspace with access to the device mode, this
interface supports read and write operations.

Device mode:

- ``unknown`` represents that device in unknown status
- ``ready`` represents that device in ready status
- ``reset`` represents that device in reset status
- ``fastboot_switching`` represents that device in fastboot switching status
- ``fastboot_download`` represents that device in fastboot download status
- ``fastboot_dump`` represents that device in fastboot dump status

Read from userspace to get the current device mode.

::
  $ cat /sys/bus/pci/devices/${bdf}/t7xx_mode

Write from userspace to set the device mode.

::
  $ echo fastboot_switching > /sys/bus/pci/devices/${bdf}/t7xx_mode

t7xx_debug_ports
----------------
The sysfs interface provides userspace with access to enable/disable the debug
ports, this interface supports read and write operations.

Debug port status:

- ``1`` represents enable debug ports
- ``0`` represents disable debug ports

Currently supported debug ports (ADB/MIPC).

Read from userspace to get the current debug ports status.

::
  $ cat /sys/bus/pci/devices/${bdf}/t7xx_debug_ports

Write from userspace to set the debug ports status.

::
  $ echo 1 > /sys/bus/pci/devices/${bdf}/t7xx_debug_ports

MBIM control channel userspace ABI

관리 application 개발

아래에서 드라이버와 userspace interface를 설명합니다. MBIM protocol은 참고문헌 [1] `Mobile Broadband Interface Model v1.0 Errata-1`에 정의되어 있습니다.

MBIM control channel userspace ABI

드라이버는 MBIM WWAN Port를 구현해 MBIM function interface를 노출합니다. control channel pipe의 userspace endpoint는 `/dev/wwan0mbim0` character device입니다.

application은 이 interface로 MBIM protocol 통신을 수행해야 합니다.

모든 control message fragmentation과 defragmentation은 userspace application이 담당합니다. 쓰는 message는 협상된 크기를 넘으면 안 되고, 읽는 application은 그 크기까지 받아들여야 합니다.

Management application development
==================================
The driver and userspace interfaces are described below. The MBIM protocol is
described in [1] Mobile Broadband Interface Model v1.0 Errata-1.

MBIM control channel userspace ABI
----------------------------------

/dev/wwan0mbim0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes an MBIM interface to the MBIM function by implementing
MBIM WWAN Port. The userspace end of the control channel pipe is a
/dev/wwan0mbim0 character device. Application shall use this interface for
MBIM protocol communication.

Fragmentation
~~~~~~~~~~~~~
The userspace application is responsible for all control message fragmentation
and defragmentation as per MBIM specification.

/dev/wwan0mbim0 write()
~~~~~~~~~~~~~~~~~~~~~~~
The MBIM control messages from the management application must not exceed the
negotiated control message size.

/dev/wwan0mbim0 read()
~~~~~~~~~~~~~~~~~~~~~~
The management application must accept control messages of up the negotiated
control message size.

MBIM data channel userspace ABI

MBIM data channel userspace ABI

t7xx 드라이버는 IP traffic용 `wwan` type IP link interface `wwan0-X`를 노출합니다.

iproute network utility로 `wwan0-X`를 만들고 MBIM IP session과 연결합니다.

`SessionId`가 0보다 큰 MBIM IP session을 설정하기 전에 userspace 관리 application이 새 IP link를 만들어야 합니다.

`SessionId 1`용 link 생성 예는 다음과 같습니다.

ip link add dev wwan0-1 parentdev wwan0 type wwan linkid 1

드라이버는 `wwan0-1` network device를 MBIM IP session 1에 자동으로 mapping합니다.

MBIM data channel userspace ABI
-------------------------------

wwan0-X network device
~~~~~~~~~~~~~~~~~~~~~~
The t7xx driver exposes IP link interface "wwan0-X" of type "wwan" for IP
traffic. Iproute network utility is used for creating "wwan0-X" network
interface and for associating it with MBIM IP session.

The userspace management application is responsible for creating new IP link
prior to establishing MBIM IP session where the SessionId is greater than 0.

For example, creating new IP link for a MBIM IP session with SessionId 1:

  ip link add dev wwan0-1 parentdev wwan0 type wwan linkid 1

The driver will automatically map the "wwan0-1" network device to MBIM IP
session 1.

AT·fastboot·ADB·MIPC userspace ABI

AT port userspace ABI

드라이버는 AT WWAN Port를 구현해 `/dev/wwan0at0` character device를 노출합니다. application은 이 interface로 AT command를 실행합니다.

fastboot port userspace ABI

드라이버는 fastboot WWAN Port를 구현해 `/dev/wwan0fastboot0` character device를 노출합니다. application은 이 interface로 fastboot protocol 통신을 수행합니다.

`fastboot_switching` mode에 들어가면 device cold reset이 필요하므로 `/dev/wwan0fastboot0` port를 내보내려면 드라이버를 다시 적재해야 합니다.

ADB port userspace ABI

드라이버는 ADB WWAN Port를 구현해 `/dev/wwan0adb0` character device를 노출합니다. application은 이 interface로 ADB protocol 통신을 수행합니다.

MIPC port userspace ABI

드라이버는 MIPC(Modem Information Process Center) WWAN Port를 구현해 `/dev/wwan0mipc0` character device를 노출합니다.

application은 이 interface로 MediaTek modem 진단 통신을 수행합니다.

AT port userspace ABI
----------------------------------

/dev/wwan0at0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes an AT port by implementing AT WWAN Port.
The userspace end of the control port is a /dev/wwan0at0 character
device. Application shall use this interface to issue AT commands.

fastboot port userspace ABI
---------------------------

/dev/wwan0fastboot0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes a fastboot protocol interface by implementing
fastboot WWAN Port. The userspace end of the fastboot channel pipe is a
/dev/wwan0fastboot0 character device. Application shall use this interface for
fastboot protocol communication.

Please note that driver needs to be reloaded to export /dev/wwan0fastboot0
port, because device needs a cold reset after enter ``fastboot_switching``
mode.

ADB port userspace ABI
----------------------

/dev/wwan0adb0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes a ADB protocol interface by implementing ADB WWAN Port.
The userspace end of the ADB channel pipe is a /dev/wwan0adb0 character device.
Application shall use this interface for ADB protocol communication.

MIPC port userspace ABI
-----------------------

/dev/wwan0mipc0 character device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The driver exposes a diagnostic interface by implementing MIPC (Modem
Information Process Center) WWAN Port. The userspace end of the MIPC channel
pipe is a /dev/wwan0mipc0 character device.
Application shall use this interface for MTK modem diagnostic communication.

t7xx 규격과 참고문헌

MediaTek T700 modem은 3GPP TS 27.007 specification을 지원합니다.

참고문헌

• [1] MBIM Errata-1: `https://www.usb.org/document-library/`
• [2] libmbim: `http://www.freedesktop.org/wiki/Software/libmbim/`
• [3] ModemManager: `http://www.freedesktop.org/wiki/Software/ModemManager/`
• [4] 3GPP Specification 27.007: `https://www.3gpp.org/DynaReport/27007.htm`
• [5] fastboot README: `https://android.googlesource.com/platform/system/core/+/refs/heads/main/fastboot/README.md`
• [6] ADB README: `https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/README.md`

libmbim은 MBIM WWAN modem과 통신하는 glib 기반 library입니다. ModemManager는 2G/3G/4G/5G mobile broadband 장치와 연결을 제어하는 D-Bus activated daemon입니다.

fastboot는 bootloader와 통신하는 mechanism이고, ADB는 host 개발 시스템에 연결되거나 실행 중인 Android device와 emulator instance를 추적하는 protocol입니다.

The MediaTek's T700 modem supports the 3GPP TS 27.007 [4] specification.

References
==========
[1] *MBIM (Mobile Broadband Interface Model) Errata-1*

- https://www.usb.org/document-library/

[2] *libmbim "a glib-based library for talking to WWAN modems and devices which
speak the Mobile Interface Broadband Model (MBIM) protocol"*

- http://www.freedesktop.org/wiki/Software/libmbim/

[3] *Modem Manager "a DBus-activated daemon which controls mobile broadband
(2G/3G/4G/5G) devices and connections"*

- http://www.freedesktop.org/wiki/Software/ModemManager/

[4] *Specification # 27.007 - 3GPP*

- https://www.3gpp.org/DynaReport/27007.htm

[5] *fastboot "a mechanism for communicating with bootloaders"*

- https://android.googlesource.com/platform/system/core/+/refs/heads/main/fastboot/README.md

[6] *ADB (Android Debug Bridge) "a mechanism to keep track of Android devices
and emulators instances connected to or running on a given host developer
machine with ADB protocol"*

- https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/README.md