Documentation/networking/caif/linux_caif.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ==========
   5 Linux CAIF
   6 ==========
   7
   8 Copyright |copy| ST-Ericsson AB 2010
   9
  10 :Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
  11 :License terms: GNU General Public License (GPL) version 2
  12
  13
  14 Introduction
  15 ============
  16
  17 CAIF is a MUX protocol used by ST-Ericsson cellular modems for
  18 communication between Modem and host. The host processes can open virtual AT
  19 channels, initiate GPRS Data connections, Video channels and Utility Channels.
  20 The Utility Channels are general purpose pipes between modem and host.
  21
  22 ST-Ericsson modems support a number of transports between modem
  23 and host. Currently, UART and Loopback are available for Linux.
  24
  25
  26 Architecture
  27 ============
  28
  29 The implementation of CAIF is divided into:
  30
  31 * CAIF Socket Layer and GPRS IP Interface.
  32 * CAIF Core Protocol Implementation
  33 * CAIF Link Layer, implemented as NET devices.
  34
  35 ::
  36
  37   RTNL
  38    !
  39    !          +------+   +------+
  40    !         +------+!  +------+!
  41    !         !  IP  !!  !Socket!!
  42    +-------> !interf!+  ! API  !+       <- CAIF Client APIs
  43    !         +------+   +------!
  44    !            !           !
  45    !            +-----------+
  46    !                  !
  47    !               +------+             <- CAIF Core Protocol
  48    !               ! CAIF !
  49    !               ! Core !
  50    !               +------+
  51    !       +----------!---------+
  52    !       !          !         !
  53    !    +------+   +-----+   +------+
  54    +--> ! HSI  !   ! TTY !   ! USB  !   <- Link Layer (Net Devices)
  55         +------+   +-----+   +------+
  56
  57
  58
  59 Implementation
  60 ==============
  61
  62
  63 CAIF Core Protocol Layer
  64 ------------------------
  65
  66 CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
  67 It implements the CAIF protocol stack in a layered approach, where
  68 each layer described in the specification is implemented as a separate layer.
  69 The architecture is inspired by the design patterns "Protocol Layer" and
  70 "Protocol Packet".
  71
  72 CAIF structure
  73 ^^^^^^^^^^^^^^
  74
  75 The Core CAIF implementation contains:
  76
  77       - Simple implementation of CAIF.
  78       - Layered architecture (a la Streams), each layer in the CAIF
  79         specification is implemented in a separate c-file.
  80       - Clients must call configuration function to add PHY layer.
  81       - Clients must implement CAIF layer to consume/produce
  82         CAIF payload with receive and transmit functions.
  83       - Clients must call configuration function to add and connect the
  84         Client layer.
  85       - When receiving / transmitting CAIF Packets (cfpkt), ownership is passed
  86         to the called function (except for framing layers' receive function)
  87
  88 Layered Architecture
  89 ====================
  90
  91 The CAIF protocol can be divided into two parts: Support functions and Protocol
  92 Implementation. The support functions include:
  93
  94       - CFPKT CAIF Packet. Implementation of CAIF Protocol Packet. The
  95         CAIF Packet has functions for creating, destroying and adding content
  96         and for adding/extracting header and trailers to protocol packets.
  97
  98 The CAIF Protocol implementation contains:
  99
 100       - CFCNFG CAIF Configuration layer. Configures the CAIF Protocol
 101         Stack and provides a Client interface for adding Link-Layer and
 102         Driver interfaces on top of the CAIF Stack.
 103
 104       - CFCTRL CAIF Control layer. Encodes and Decodes control messages
 105         such as enumeration and channel setup. Also matches request and
 106         response messages.
 107
 108       - CFSERVL General CAIF Service Layer functionality; handles flow
 109         control and remote shutdown requests.
 110
 111       - CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual
 112         External Interface). This layer encodes/decodes VEI frames.
 113
 114       - CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP
 115         traffic), encodes/decodes Datagram frames.
 116
 117       - CFMUX CAIF Mux layer. Handles multiplexing between multiple
 118         physical bearers and multiple channels such as VEI, Datagram, etc.
 119         The MUX keeps track of the existing CAIF Channels and
 120         Physical Instances and selects the appropriate instance based
 121         on Channel-Id and Physical-ID.
 122
 123       - CFFRML CAIF Framing layer. Handles Framing i.e. Frame length
 124         and frame checksum.
 125
 126       - CFSERL CAIF Serial layer. Handles concatenation/split of frames
 127         into CAIF Frames with correct length.
 128
 129 ::
 130
 131                     +---------+
 132                     | Config  |
 133                     | CFCNFG  |
 134                     +---------+
 135                          !
 136     +---------+     +---------+     +---------+
 137     |   AT    |     | Control |     | Datagram|
 138     | CFVEIL  |     | CFCTRL  |     | CFDGML  |
 139     +---------+     +---------+     +---------+
 140            \_____________!______________/
 141                          !
 142                     +---------+
 143                     |   MUX   |
 144                     |         |
 145                     +---------+
 146                     _____!_____
 147                    /           \
 148             +---------+     +---------+
 149             | CFFRML  |     | CFFRML  |
 150             | Framing |     | Framing |
 151             +---------+     +---------+
 152                  !              !
 153             +---------+     +---------+
 154             |         |     | Serial  |
 155             |         |     | CFSERL  |
 156             +---------+     +---------+
 157
 158
 159 In this layered approach the following "rules" apply.
 160
 161       - All layers embed the same structure "struct cflayer"
 162       - A layer does not depend on any other layer's private data.
 163       - Layers are stacked by setting the pointers::
 164
 165                   layer->up , layer->dn
 166
 167       - In order to send data upwards, each layer should do::
 168
 169                  layer->up->receive(layer->up, packet);
 170
 171       - In order to send data downwards, each layer should do::
 172
 173                  layer->dn->transmit(layer->dn, packet);
 174
 175
 176 CAIF Socket and IP interface
 177 ============================
 178
 179 The IP interface and CAIF socket API are implemented on top of the
 180 CAIF Core protocol. The IP Interface and CAIF socket have an instance of
 181 'struct cflayer', just like the CAIF Core protocol stack.
 182 Net device and Socket implement the 'receive()' function defined by
 183 'struct cflayer', just like the rest of the CAIF stack. In this way, transmit and
 184 receive of packets is handled as by the rest of the layers: the 'dn->transmit()'
 185 function is called in order to transmit data.
 186
 187 Configuration of Link Layer
 188 ---------------------------
 189 The Link Layer is implemented as Linux network devices (struct net_device).
 190 Payload handling and registration is done using standard Linux mechanisms.
 191
 192 The CAIF Protocol relies on a loss-less link layer without implementing
 193 retransmission. This implies that packet drops must not happen.
 194 Therefore a flow-control mechanism is implemented where the physical
 195 interface can initiate flow stop for all CAIF Channels.