[deliverable/linux.git] / Documentation / networking / caif / Linux-CAIF.txt

Linux CAIF
===========
copyright (C) ST-Ericsson AB 2010
Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
License terms: GNU General Public License (GPL) version 2


Introduction
------------
CAIF is a MUX protocol used by ST-Ericsson cellular modems for
communication between Modem and host. The host processes can open virtual AT
channels, initiate GPRS Data connections, Video channels and Utility Channels.
The Utility Channels are general purpose pipes between modem and host.

ST-Ericsson modems support a number of transports between modem
and host. Currently, UART and Loopback are available for Linux.


Architecture:
------------
The implementation of CAIF is divided into:
* CAIF Socket Layer and GPRS IP Interface.
* CAIF Core Protocol Implementation
* CAIF Link Layer, implemented as NET devices.


  RTNL
   !
   !	      +------+	 +------+
   !	     +------+!	+------+!
   !	     !	IP  !!	!Socket!!
   +-------> !interf!+	! API  !+	<- CAIF Client APIs
   !	     +------+	+------!
   !		!	    !
   !		+-----------+
   !		      !
   !		   +------+		<- CAIF Core Protocol
   !		   ! CAIF !
   !		   ! Core !
   !		   +------+
   !	   +----------!---------+
   !	   !	      !		!
   !	+------+   +-----+   +------+
   +--> ! HSI  !   ! TTY !   ! USB  !	<- Link Layer (Net Devices)
	+------+   +-----+   +------+


I M P L E M E N T A T I O N
===========================


CAIF Core Protocol Layer
=========================================

CAIF Core layer implements the CAIF protocol as defined by ST-Ericsson.
It implements the CAIF protocol stack in a layered approach, where
each layer described in the specification is implemented as a separate layer.
The architecture is inspired by the design patterns "Protocol Layer" and
"Protocol Packet".

== CAIF structure ==
The Core CAIF implementation contains:
      -	Simple implementation of CAIF.
      -	Layered architecture (a la Streams), each layer in the CAIF
	specification is implemented in a separate c-file.
      -	Clients must call configuration function to add PHY layer.
      -	Clients must implement CAIF layer to consume/produce
	CAIF payload with receive and transmit functions.
      -	Clients must call configuration function to add and connect the
	Client layer.
      - When receiving / transmitting CAIF Packets (cfpkt), ownership is passed
	to the called function (except for framing layers' receive function)

Layered Architecture
--------------------
The CAIF protocol can be divided into two parts: Support functions and Protocol
Implementation. The support functions include:

      - CFPKT CAIF Packet. Implementation of CAIF Protocol Packet. The
	CAIF Packet has functions for creating, destroying and adding content
	and for adding/extracting header and trailers to protocol packets.

The CAIF Protocol implementation contains:

      - CFCNFG CAIF Configuration layer. Configures the CAIF Protocol
	Stack and provides a Client interface for adding Link-Layer and
	Driver interfaces on top of the CAIF Stack.

      - CFCTRL CAIF Control layer. Encodes and Decodes control messages
	such as enumeration and channel setup. Also matches request and
	response messages.

      - CFSERVL General CAIF Service Layer functionality; handles flow
	control and remote shutdown requests.

      - CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual
	External Interface). This layer encodes/decodes VEI frames.

      - CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP
	traffic), encodes/decodes Datagram frames.

      - CFMUX CAIF Mux layer. Handles multiplexing between multiple
	physical bearers and multiple channels such as VEI, Datagram, etc.
	The MUX keeps track of the existing CAIF Channels and
	Physical Instances and selects the appropriate instance based
	on Channel-Id and Physical-ID.

      - CFFRML CAIF Framing layer. Handles Framing i.e. Frame length
	and frame checksum.

      - CFSERL CAIF Serial layer. Handles concatenation/split of frames
	into CAIF Frames with correct length.


		    +---------+
		    | Config  |
		    | CFCNFG  |
		    +---------+
			 !
    +---------+	    +---------+	    +---------+
    |	AT    |	    | Control |	    | Datagram|
    | CFVEIL  |	    | CFCTRL  |	    | CFDGML  |
    +---------+	    +---------+	    +---------+
	   \_____________!______________/
			 !
		    +---------+
		    |	MUX   |
		    |	      |
		    +---------+
		    _____!_____
		   /	       \
	    +---------+	    +---------+
	    | CFFRML  |	    | CFFRML  |
	    | Framing |	    | Framing |
	    +---------+	    +---------+
		 !		!
	    +---------+	    +---------+
	    |	      |	    | Serial  |
	    |	      |	    | CFSERL  |
	    +---------+	    +---------+


In this layered approach the following "rules" apply.
      - All layers embed the same structure "struct cflayer"
      - A layer does not depend on any other layer's private data.
      - Layers are stacked by setting the pointers
		  layer->up , layer->dn
      -	In order to send data upwards, each layer should do
		 layer->up->receive(layer->up, packet);
      - In order to send data downwards, each layer should do
		 layer->dn->transmit(layer->dn, packet);


CAIF Socket and IP interface
===========================

The IP interface and CAIF socket API are implemented on top of the
CAIF Core protocol. The IP Interface and CAIF socket have an instance of
'struct cflayer', just like the CAIF Core protocol stack.
Net device and Socket implement the 'receive()' function defined by
'struct cflayer', just like the rest of the CAIF stack. In this way, transmit and
receive of packets is handled as by the rest of the layers: the 'dn->transmit()'
function is called in order to transmit data.

Configuration of Link Layer
---------------------------
The Link Layer is implemented as Linux network devices (struct net_device).
Payload handling and registration is done using standard Linux mechanisms.

The CAIF Protocol relies on a loss-less link layer without implementing
retransmission. This implies that packet drops must not happen.
Therefore a flow-control mechanism is implemented where the physical
interface can initiate flow stop for all CAIF Channels.
Commit	Line	Data
edc7616c SB	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:
5051c94b	22	* CAIF Socket Layer and GPRS IP Interface.
edc7616c SB	23	* CAIF Core Protocol Implementation
	24	* CAIF Link Layer, implemented as NET devices.
	25
	26
	27	RTNL
	28	!
5051c94b SB	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
edc7616c SB	47
	48
	49	I M P L E M E N T A T I O N
	50	===========================
5051c94b	51
edc7616c SB	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.
edc7616c SB	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
5051c94b	73	to the called function (except for framing layers' receive function)
edc7616c SB	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
edc7616c SB	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
5051c94b	98	External Interface). This layer encodes/decodes VEI frames.
edc7616c SB	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
25985edc	106	Physical Instances and selects the appropriate instance based
edc7616c SB	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	+---------+ +---------+
5051c94b	140	\| \| \| Serial \|
edc7616c SB	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
5051c94b	156	CAIF Socket and IP interface
edc7616c SB	157	===========================
edc7616c SB	158
5051c94b SB	159	The IP interface and CAIF socket API are implemented on top of the
5051c94b SB	160	CAIF Core protocol. The IP Interface and CAIF socket have an instance of
edc7616c SB	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
edc7616c SB	167	Configuration of Link Layer
edc7616c SB	168	---------------------------
5051c94b	169	The Link Layer is implemented as Linux network devices (struct net_device).
edc7616c SB	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.