Documentation/networking/device_drivers/wwan/iosm.rst

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