Documentation/networking/caif/Linux-CAIF.txt

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