1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4==========
5Linux CAIF
6==========
7
8Copyright |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
14Introduction
15============
16
17CAIF is a MUX protocol used by ST-Ericsson cellular modems for
18communication between Modem and host. The host processes can open virtual AT
19channels, initiate GPRS Data connections, Video channels and Utility Channels.
20The Utility Channels are general purpose pipes between modem and host.
21
22ST-Ericsson modems support a number of transports between modem
23and host. Currently, UART and Loopback are available for Linux.
24
25
26Architecture
27============
28
29The 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
59Implementation
60==============
61
62
63CAIF Core Protocol Layer
64------------------------
65
66CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
67It implements the CAIF protocol stack in a layered approach, where
68each layer described in the specification is implemented as a separate layer.
69The architecture is inspired by the design patterns "Protocol Layer" and
70"Protocol Packet".
71
72CAIF structure
73^^^^^^^^^^^^^^
74
75The 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
88Layered Architecture
89====================
90
91The CAIF protocol can be divided into two parts: Support functions and Protocol
92Implementation. 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
98The 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
159In 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
176CAIF Socket and IP interface
177============================
178
179The IP interface and CAIF socket API are implemented on top of the
180CAIF Core protocol. The IP Interface and CAIF socket have an instance of
181'struct cflayer', just like the CAIF Core protocol stack.
182Net 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
184receive of packets is handled as by the rest of the layers: the 'dn->transmit()'
185function is called in order to transmit data.
186
187Configuration of Link Layer
188---------------------------
189The Link Layer is implemented as Linux network devices (struct net_device).
190Payload handling and registration is done using standard Linux mechanisms.
191
192The CAIF Protocol relies on a loss-less link layer without implementing
193retransmission. This implies that packet drops must not happen.
194Therefore a flow-control mechanism is implemented where the physical
195interface can initiate flow stop for all CAIF Channels.
196