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