| 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/ [email protected] |
| 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. |