IOSM Driver for Intel M.2 PCIe Modems

Intel M.2 PCIe modem용 IOSM 드라이버

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

Copyright 2020-2021 Intel Corporation.

Intel M.2 PCIe 기반 modem용 IOSM 드라이버

IOSM(IPC over Shared Memory)은 Linux 또는 Chrome platform에서 host와 Intel M.2 modem 사이의 PCIe 데이터 교환을 위해 개발한 WWAN PCIe host 드라이버입니다.

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

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

.. Copyright (C) 2020-21 Intel Corporation

.. _iosm_driver_doc:

===========================================
IOSM Driver for Intel M.2 PCIe based Modems
===========================================
The IOSM (IPC over Shared Memory) driver is a WWAN PCIe host driver developed
for linux or chrome platform for data exchange over PCIe interface between
Host platform & Intel M.2 Modem. The driver exposes interface conforming to the
MBIM protocol [1]. Any front end application ( eg: Modem Manager) could easily
manage the MBIM interface to enable data communication towards WWAN.

IOSM 기본 사용법

기본 사용법

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

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

MBIM IP session을 설정하려면 관리 application이 다음 작업을 수행해야 합니다.

• MBIM control channel 열기
• network connection 설정 구성
• network 연결
• IP network interface 구성

Basic usage
===========
MBIM functions are inactive when unmanaged. The IOSM driver only provides a
userspace interface MBIM "WWAN PORT" representing MBIM control channel and does
not play any role in managing the functionality. It is the job of a userspace
application to detect port enumeration and enable MBIM functionality.

Examples of few such userspace application 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

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은 MBIM specification에 따라 userspace application이 담당합니다.

`/dev/wwan0mbim0`에 쓰는 MBIM control message는 협상된 control message 크기를 넘으면 안 됩니다. 읽을 때는 관리 application이 협상된 크기까지의 control message를 받아들여야 합니다.

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

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

iproute network utility로 `wwan0-X` network interface를 만들고 MBIM IP session과 연결합니다. 드라이버는 동시 IP 통신을 위해 최대 8개 IP session을 지원합니다.

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

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

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

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

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

wwan0-X network device
~~~~~~~~~~~~~~~~~~~~~~
The IOSM 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 Driver supports
up to 8 IP sessions for simultaneous IP communication.

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-name wwan0 type wwan linkid 1

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

IOSM 참고문헌

참고문헌

[1] `MBIM (Mobile Broadband Interface Model) Errata-1`: `https://www.usb.org/document-library/`.

[2] libmbim은 MBIM protocol을 사용하는 WWAN modem·device와 통신하는 glib 기반 library입니다. 원문 주소는 `http://www.freedesktop.org/wiki/Software/libmbim/`입니다.

[3] ModemManager는 mobile broadband 2G/3G/4G device와 connection을 제어하는 D-Bus activated daemon입니다. 원문 주소는 `http://www.freedesktop.org/wiki/Software/ModemManager/`입니다.

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) devices and connections"
      - http://www.freedesktop.org/wiki/Software/ModemManager/