1.. SPDX-License-Identifier: GPL-2.0-only 2 3.. Copyright (C) 2020-21 Intel Corporation 4 5.. _iosm_driver_doc: 6 7=========================================== 8IOSM Driver for Intel M.2 PCIe based Modems 9=========================================== 10The IOSM (IPC over Shared Memory) driver is a WWAN PCIe host driver developed 11for linux or chrome platform for data exchange over PCIe interface between 12Host platform & Intel M.2 Modem. The driver exposes interface conforming to the 13MBIM protocol [1]. Any front end application ( eg: Modem Manager) could easily 14manage the MBIM interface to enable data communication towards WWAN. 15 16Basic usage 17=========== 18MBIM functions are inactive when unmanaged. The IOSM driver only provides a 19userspace interface MBIM "WWAN PORT" representing MBIM control channel and does 20not play any role in managing the functionality. It is the job of a userspace 21application to detect port enumeration and enable MBIM functionality. 22 23Examples of few such userspace application are: 24- mbimcli (included with the libmbim [2] library), and 25- Modem Manager [3] 26 27Management Applications to carry out below required actions for establishing 28MBIM IP session: 29- open the MBIM control channel 30- configure network connection settings 31- connect to network 32- configure IP network interface 33 34Management application development 35================================== 36The driver and userspace interfaces are described below. The MBIM protocol is 37described in [1] Mobile Broadband Interface Model v1.0 Errata-1. 38 39MBIM control channel userspace ABI 40---------------------------------- 41 42/dev/wwan0mbim0 character device 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44The driver exposes an MBIM interface to the MBIM function by implementing 45MBIM WWAN Port. The userspace end of the control channel pipe is a 46/dev/wwan0mbim0 character device. Application shall use this interface for 47MBIM protocol communication. 48 49Fragmentation 50~~~~~~~~~~~~~ 51The userspace application is responsible for all control message fragmentation 52and defragmentation as per MBIM specification. 53 54/dev/wwan0mbim0 write() 55~~~~~~~~~~~~~~~~~~~~~~~ 56The MBIM control messages from the management application must not exceed the 57negotiated control message size. 58 59/dev/wwan0mbim0 read() 60~~~~~~~~~~~~~~~~~~~~~~ 61The management application must accept control messages of up the negotiated 62control message size. 63 64MBIM data channel userspace ABI 65------------------------------- 66 67wwan0-X network device 68~~~~~~~~~~~~~~~~~~~~~~ 69The IOSM driver exposes IP link interface "wwan0-X" of type "wwan" for IP 70traffic. Iproute network utility is used for creating "wwan0-X" network 71interface and for associating it with MBIM IP session. The Driver supports 72up to 8 IP sessions for simultaneous IP communication. 73 74The userspace management application is responsible for creating new IP link 75prior to establishing MBIM IP session where the SessionId is greater than 0. 76 77For example, creating new IP link for a MBIM IP session with SessionId 1: 78 79 ip link add dev wwan0-1 parentdev-name wwan0 type wwan linkid 1 80 81The driver will automatically map the "wwan0-1" network device to MBIM IP 82session 1. 83 84References 85========== 86[1] "MBIM (Mobile Broadband Interface Model) Errata-1" 87 - https://www.usb.org/document-library/ 88 89[2] libmbim - "a glib-based library for talking to WWAN modems and 90 devices which speak the Mobile Interface Broadband Model (MBIM) 91 protocol" 92 - http://www.freedesktop.org/wiki/Software/libmbim/ 93 94[3] Modem Manager - "a DBus-activated daemon which controls mobile 95 broadband (2G/3G/4G) devices and connections" 96 - http://www.freedesktop.org/wiki/Software/ModemManager/ 97