0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ==========
0005 Linux CAIF
0006 ==========
0007
0008 Copyright |copy| ST-Ericsson AB 2010
0009
0010 :Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
0011 :License terms: GNU General Public License (GPL) version 2
0012
0013
0014 Introduction
0015 ============
0016
0017 CAIF is a MUX protocol used by ST-Ericsson cellular modems for
0018 communication between Modem and host. The host processes can open virtual AT
0019 channels, initiate GPRS Data connections, Video channels and Utility Channels.
0020 The Utility Channels are general purpose pipes between modem and host.
0021
0022 ST-Ericsson modems support a number of transports between modem
0023 and host. Currently, UART and Loopback are available for Linux.
0024
0025
0026 Architecture
0027 ============
0028
0029 The implementation of CAIF is divided into:
0030
0031 * CAIF Socket Layer and GPRS IP Interface.
0032 * CAIF Core Protocol Implementation
0033 * CAIF Link Layer, implemented as NET devices.
0034
0035 ::
0036
0037 RTNL
0038 !
0039 ! +------+ +------+
0040 ! +------+! +------+!
0041 ! ! IP !! !Socket!!
0042 +-------> !interf!+ ! API !+ <- CAIF Client APIs
0043 ! +------+ +------!
0044 ! ! !
0045 ! +-----------+
0046 ! !
0047 ! +------+ <- CAIF Core Protocol
0048 ! ! CAIF !
0049 ! ! Core !
0050 ! +------+
0051 ! +----------!---------+
0052 ! ! ! !
0053 ! +------+ +-----+ +------+
0054 +--> ! HSI ! ! TTY ! ! USB ! <- Link Layer (Net Devices)
0055 +------+ +-----+ +------+
0056
0057
0058
0059 Implementation
0060 ==============
0061
0062
0063 CAIF Core Protocol Layer
0064 ------------------------
0065
0066 CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
0067 It implements the CAIF protocol stack in a layered approach, where
0068 each layer described in the specification is implemented as a separate layer.
0069 The architecture is inspired by the design patterns "Protocol Layer" and
0070 "Protocol Packet".
0071
0072 CAIF structure
0073 ^^^^^^^^^^^^^^
0074
0075 The Core CAIF implementation contains:
0076
0077 - Simple implementation of CAIF.
0078 - Layered architecture (a la Streams), each layer in the CAIF
0079 specification is implemented in a separate c-file.
0080 - Clients must call configuration function to add PHY layer.
0081 - Clients must implement CAIF layer to consume/produce
0082 CAIF payload with receive and transmit functions.
0083 - Clients must call configuration function to add and connect the
0084 Client layer.
0085 - When receiving / transmitting CAIF Packets (cfpkt), ownership is passed
0086 to the called function (except for framing layers' receive function)
0087
0088 Layered Architecture
0089 ====================
0090
0091 The CAIF protocol can be divided into two parts: Support functions and Protocol
0092 Implementation. The support functions include:
0093
0094 - CFPKT CAIF Packet. Implementation of CAIF Protocol Packet. The
0095 CAIF Packet has functions for creating, destroying and adding content
0096 and for adding/extracting header and trailers to protocol packets.
0097
0098 The CAIF Protocol implementation contains:
0099
0100 - CFCNFG CAIF Configuration layer. Configures the CAIF Protocol
0101 Stack and provides a Client interface for adding Link-Layer and
0102 Driver interfaces on top of the CAIF Stack.
0103
0104 - CFCTRL CAIF Control layer. Encodes and Decodes control messages
0105 such as enumeration and channel setup. Also matches request and
0106 response messages.
0107
0108 - CFSERVL General CAIF Service Layer functionality; handles flow
0109 control and remote shutdown requests.
0110
0111 - CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual
0112 External Interface). This layer encodes/decodes VEI frames.
0113
0114 - CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP
0115 traffic), encodes/decodes Datagram frames.
0116
0117 - CFMUX CAIF Mux layer. Handles multiplexing between multiple
0118 physical bearers and multiple channels such as VEI, Datagram, etc.
0119 The MUX keeps track of the existing CAIF Channels and
0120 Physical Instances and selects the appropriate instance based
0121 on Channel-Id and Physical-ID.
0122
0123 - CFFRML CAIF Framing layer. Handles Framing i.e. Frame length
0124 and frame checksum.
0125
0126 - CFSERL CAIF Serial layer. Handles concatenation/split of frames
0127 into CAIF Frames with correct length.
0128
0129 ::
0130
0131 +---------+
0132 | Config |
0133 | CFCNFG |
0134 +---------+
0135 !
0136 +---------+ +---------+ +---------+
0137 | AT | | Control | | Datagram|
0138 | CFVEIL | | CFCTRL | | CFDGML |
0139 +---------+ +---------+ +---------+
0140 \_____________!______________/
0141 !
0142 +---------+
0143 | MUX |
0144 | |
0145 +---------+
0146 _____!_____
0147 / \
0148 +---------+ +---------+
0149 | CFFRML | | CFFRML |
0150 | Framing | | Framing |
0151 +---------+ +---------+
0152 ! !
0153 +---------+ +---------+
0154 | | | Serial |
0155 | | | CFSERL |
0156 +---------+ +---------+
0157
0158
0159 In this layered approach the following "rules" apply.
0160
0161 - All layers embed the same structure "struct cflayer"
0162 - A layer does not depend on any other layer's private data.
0163 - Layers are stacked by setting the pointers::
0164
0165 layer->up , layer->dn
0166
0167 - In order to send data upwards, each layer should do::
0168
0169 layer->up->receive(layer->up, packet);
0170
0171 - In order to send data downwards, each layer should do::
0172
0173 layer->dn->transmit(layer->dn, packet);
0174
0175
0176 CAIF Socket and IP interface
0177 ============================
0178
0179 The IP interface and CAIF socket API are implemented on top of the
0180 CAIF Core protocol. The IP Interface and CAIF socket have an instance of
0181 'struct cflayer', just like the CAIF Core protocol stack.
0182 Net device and Socket implement the 'receive()' function defined by
0183 'struct cflayer', just like the rest of the CAIF stack. In this way, transmit and
0184 receive of packets is handled as by the rest of the layers: the 'dn->transmit()'
0185 function is called in order to transmit data.
0186
0187 Configuration of Link Layer
0188 ---------------------------
0189 The Link Layer is implemented as Linux network devices (struct net_device).
0190 Payload handling and registration is done using standard Linux mechanisms.
0191
0192 The CAIF Protocol relies on a loss-less link layer without implementing
0193 retransmission. This implies that packet drops must not happen.
0194 Therefore a flow-control mechanism is implemented where the physical
0195 interface can initiate flow stop for all CAIF Channels.
