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, Kernel API, and  Net Device.
  23 * CAIF Core Protocol Implementation
  24 * CAIF Link Layer, implemented as NET devices.
  25
  26
  27   RTNL
  28    !
  29    !     +------+   +------+   +------+
  30    !    +------+!  +------+!  +------+!
  31    !    ! Sock !!  !Kernel!!  ! Net  !!
  32    !    ! API  !+  ! API  !+  ! Dev  !+   <- CAIF Client APIs
  33    !    +------+   +------!   +------+
  34    !       !          !          !
  35    !       +----------!----------+
  36    !               +------+               <- CAIF Protocol Implementation
  37    +------->       ! CAIF !
  38                    ! Core !
  39                    +------+
  40              +--------!--------+
  41              !                 !
  42           +------+          +-----+
  43           !      !          ! TTY !       <- Link Layer (Net Devices)
  44           +------+          +-----+
  45
  46
  47 Using the Kernel API
  48 ----------------------
  49 The Kernel API is used for accessing CAIF channels from the
  50 kernel.
  51 The user of the API has to implement two callbacks for receive
  52 and control.
  53 The receive callback gives a CAIF packet as a SKB. The control
  54 callback will
  55 notify of channel initialization complete, and flow-on/flow-
  56 off.
  57
  58
  59   struct caif_device caif_dev = {
  60     .caif_config = {
  61      .name = "MYDEV"
  62      .type = CAIF_CHTY_AT
  63     }
  64    .receive_cb = my_receive,
  65    .control_cb = my_control,
  66   };
  67   caif_add_device(&caif_dev);
  68   caif_transmit(&caif_dev, skb);
  69
  70 See the caif_kernel.h for details about the CAIF kernel API.
  71
  72
  73 I M P L E M E N T A T I O N
  74 ===========================
  75 ===========================
  76
  77 CAIF Core Protocol Layer
  78 =========================================
  79
  80 CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
  81 It implements the CAIF protocol stack in a layered approach, where
  82 each layer described in the specification is implemented as a separate layer.
  83 The architecture is inspired by the design patterns "Protocol Layer" and
  84 "Protocol Packet".
  85
  86 == CAIF structure ==
  87 The Core CAIF implementation contains:
  88       - Simple implementation of CAIF.
  89       - Layered architecture (a la Streams), each layer in the CAIF
  90         specification is implemented in a separate c-file.
  91       - Clients must implement PHY layer to access physical HW
  92         with receive and transmit functions.
  93       - Clients must call configuration function to add PHY layer.
  94       - Clients must implement CAIF layer to consume/produce
  95         CAIF payload with receive and transmit functions.
  96       - Clients must call configuration function to add and connect the
  97         Client layer.
  98       - When receiving / transmitting CAIF Packets (cfpkt), ownership is passed
  99         to the called function (except for framing layers' receive functions
 100         or if a transmit function returns an error, in which case the caller
 101         must free the packet).
 102
 103 Layered Architecture
 104 --------------------
 105 The CAIF protocol can be divided into two parts: Support functions and Protocol
 106 Implementation. The support functions include:
 107
 108       - CFPKT CAIF Packet. Implementation of CAIF Protocol Packet. The
 109         CAIF Packet has functions for creating, destroying and adding content
 110         and for adding/extracting header and trailers to protocol packets.
 111
 112       - CFLST CAIF list implementation.
 113
 114       - CFGLUE CAIF Glue. Contains OS Specifics, such as memory
 115         allocation, endianness, etc.
 116
 117 The CAIF Protocol implementation contains:
 118
 119       - CFCNFG CAIF Configuration layer. Configures the CAIF Protocol
 120         Stack and provides a Client interface for adding Link-Layer and
 121         Driver interfaces on top of the CAIF Stack.
 122
 123       - CFCTRL CAIF Control layer. Encodes and Decodes control messages
 124         such as enumeration and channel setup. Also matches request and
 125         response messages.
 126
 127       - CFSERVL General CAIF Service Layer functionality; handles flow
 128         control and remote shutdown requests.
 129
 130       - CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual
 131         External Interface). This layer encodes/decodes VEI frames.
 132
 133       - CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP
 134         traffic), encodes/decodes Datagram frames.
 135
 136       - CFMUX CAIF Mux layer. Handles multiplexing between multiple
 137         physical bearers and multiple channels such as VEI, Datagram, etc.
 138         The MUX keeps track of the existing CAIF Channels and
 139         Physical Instances and selects the appropriate instance based
 140         on Channel-Id and Physical-ID.
 141
 142       - CFFRML CAIF Framing layer. Handles Framing i.e. Frame length
 143         and frame checksum.
 144
 145       - CFSERL CAIF Serial layer. Handles concatenation/split of frames
 146         into CAIF Frames with correct length.
 147
 148
 149
 150                     +---------+
 151                     | Config  |
 152                     | CFCNFG  |
 153                     +---------+
 154                          !
 155     +---------+     +---------+     +---------+
 156     |   AT    |     | Control |     | Datagram|
 157     | CFVEIL  |     | CFCTRL  |     | CFDGML  |
 158     +---------+     +---------+     +---------+
 159            \_____________!______________/
 160                          !
 161                     +---------+
 162                     |   MUX   |
 163                     |         |
 164                     +---------+
 165                     _____!_____
 166                    /           \
 167             +---------+     +---------+
 168             | CFFRML  |     | CFFRML  |
 169             | Framing |     | Framing |
 170             +---------+     +---------+
 171                  !              !
 172             +---------+     +---------+
 173             |         |     | Serial  |
 174             |         |     | CFSERL  |
 175             +---------+     +---------+
 176
 177
 178 In this layered approach the following "rules" apply.
 179       - All layers embed the same structure "struct cflayer"
 180       - A layer does not depend on any other layer's private data.
 181       - Layers are stacked by setting the pointers
 182                   layer->up , layer->dn
 183       - In order to send data upwards, each layer should do
 184                  layer->up->receive(layer->up, packet);
 185       - In order to send data downwards, each layer should do
 186                  layer->dn->transmit(layer->dn, packet);
 187
 188
 189 Linux Driver Implementation
 190 ===========================
 191
 192 Linux GPRS Net Device and CAIF socket are implemented on top of the
 193 CAIF Core protocol. The Net device and CAIF socket have an instance of
 194 'struct cflayer', just like the CAIF Core protocol stack.
 195 Net device and Socket implement the 'receive()' function defined by
 196 'struct cflayer', just like the rest of the CAIF stack. In this way, transmit and
 197 receive of packets is handled as by the rest of the layers: the 'dn->transmit()'
 198 function is called in order to transmit data.
 199
 200 The layer on top of the CAIF Core implementation is
 201 sometimes referred to as the "Client layer".
 202
 203
 204 Configuration of Link Layer
 205 ---------------------------
 206 The Link Layer is implemented as Linux net devices (struct net_device).
 207 Payload handling and registration is done using standard Linux mechanisms.
 208
 209 The CAIF Protocol relies on a loss-less link layer without implementing
 210 retransmission. This implies that packet drops must not happen.
 211 Therefore a flow-control mechanism is implemented where the physical
 212 interface can initiate flow stop for all CAIF Channels.