0001 .. SPDX-License-Identifier: GPL-2.0-only
0002
0003 .. Copyright (C) 2020-21 Intel Corporation
0004
0005 .. _iosm_driver_doc:
0006
0007 ===========================================
0008 IOSM Driver for Intel M.2 PCIe based Modems
0009 ===========================================
0010 The IOSM (IPC over Shared Memory) driver is a WWAN PCIe host driver developed
0011 for linux or chrome platform for data exchange over PCIe interface between
0012 Host platform & Intel M.2 Modem. The driver exposes interface conforming to the
0013 MBIM protocol [1]. Any front end application ( eg: Modem Manager) could easily
0014 manage the MBIM interface to enable data communication towards WWAN.
0015
0016 Basic usage
0017 ===========
0018 MBIM functions are inactive when unmanaged. The IOSM driver only provides a
0019 userspace interface MBIM "WWAN PORT" representing MBIM control channel and does
0020 not play any role in managing the functionality. It is the job of a userspace
0021 application to detect port enumeration and enable MBIM functionality.
0022
0023 Examples of few such userspace application are:
0024 - mbimcli (included with the libmbim [2] library), and
0025 - Modem Manager [3]
0026
0027 Management Applications to carry out below required actions for establishing
0028 MBIM IP session:
0029 - open the MBIM control channel
0030 - configure network connection settings
0031 - connect to network
0032 - configure IP network interface
0033
0034 Management application development
0035 ==================================
0036 The driver and userspace interfaces are described below. The MBIM protocol is
0037 described in [1] Mobile Broadband Interface Model v1.0 Errata-1.
0038
0039 MBIM control channel userspace ABI
0040 ----------------------------------
0041
0042 /dev/wwan0mbim0 character device
0043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0044 The driver exposes an MBIM interface to the MBIM function by implementing
0045 MBIM WWAN Port. The userspace end of the control channel pipe is a
0046 /dev/wwan0mbim0 character device. Application shall use this interface for
0047 MBIM protocol communication.
0048
0049 Fragmentation
0050 ~~~~~~~~~~~~~
0051 The userspace application is responsible for all control message fragmentation
0052 and defragmentation as per MBIM specification.
0053
0054 /dev/wwan0mbim0 write()
0055 ~~~~~~~~~~~~~~~~~~~~~~~
0056 The MBIM control messages from the management application must not exceed the
0057 negotiated control message size.
0058
0059 /dev/wwan0mbim0 read()
0060 ~~~~~~~~~~~~~~~~~~~~~~
0061 The management application must accept control messages of up the negotiated
0062 control message size.
0063
0064 MBIM data channel userspace ABI
0065 -------------------------------
0066
0067 wwan0-X network device
0068 ~~~~~~~~~~~~~~~~~~~~~~
0069 The IOSM driver exposes IP link interface "wwan0-X" of type "wwan" for IP
0070 traffic. Iproute network utility is used for creating "wwan0-X" network
0071 interface and for associating it with MBIM IP session. The Driver supports
0072 upto 8 IP sessions for simultaneous IP communication.
0073
0074 The userspace management application is responsible for creating new IP link
0075 prior to establishing MBIM IP session where the SessionId is greater than 0.
0076
0077 For example, creating new IP link for a MBIM IP session with SessionId 1:
0078
0079 ip link add dev wwan0-1 parentdev-name wwan0 type wwan linkid 1
0080
0081 The driver will automatically map the "wwan0-1" network device to MBIM IP
0082 session 1.
0083
0084 References
0085 ==========
0086 [1] "MBIM (Mobile Broadband Interface Model) Errata-1"
0087 - https://www.usb.org/document-library/
0088
0089 [2] libmbim - "a glib-based library for talking to WWAN modems and
0090 devices which speak the Mobile Interface Broadband Model (MBIM)
0091 protocol"
0092 - http://www.freedesktop.org/wiki/Software/libmbim/
0093
0094 [3] Modem Manager - "a DBus-activated daemon which controls mobile
0095 broadband (2G/3G/4G) devices and connections"
0096 - http://www.freedesktop.org/wiki/Software/ModemManager/
