[linux-2.6-block.git] / Documentation / networking / caif / linux_caif.rst

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

==========
Linux CAIF
==========

Copyright |copy| 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)
	+------+   +-----+   +------+


Implementation
==============


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
da50d57a MCC	1	.. SPDX-License-Identifier: GPL-2.0
	2	.. include:: <isonum.txt>
	3
	4	==========
edc7616c	5	Linux CAIF
da50d57a MCC	6	==========
	7
	8	Copyright \|copy\| ST-Ericsson AB 2010
	9
	10	:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
	11	:License terms: GNU General Public License (GPL) version 2
edc7616c SB	12
	13
	14	Introduction
da50d57a MCC	15	============
da50d57a MCC	16
edc7616c SB	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
da50d57a MCC	26	Architecture
	27	============
	28
edc7616c	29	The implementation of CAIF is divided into:
da50d57a	30
5051c94b	31	* CAIF Socket Layer and GPRS IP Interface.
edc7616c SB	32	* CAIF Core Protocol Implementation
	33	* CAIF Link Layer, implemented as NET devices.
	34
da50d57a	35	::
edc7616c SB	36
	37	RTNL
	38	!
5051c94b SB	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
edc7616c SB	57
edc7616c SB	58
da50d57a MCC	59	Implementation
da50d57a MCC	60	==============
5051c94b	61
edc7616c SB	62
edc7616c SB	63	CAIF Core Protocol Layer
da50d57a	64	------------------------
edc7616c SB	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
da50d57a MCC	72	CAIF structure
	73	^^^^^^^^^^^^^^
	74
edc7616c	75	The Core CAIF implementation contains:
da50d57a	76
edc7616c SB	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.
edc7616c SB	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
5051c94b	86	to the called function (except for framing layers' receive function)
edc7616c SB	87
edc7616c SB	88	Layered Architecture
da50d57a MCC	89	====================
da50d57a MCC	90
edc7616c SB	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
edc7616c SB	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
5051c94b	112	External Interface). This layer encodes/decodes VEI frames.
edc7616c SB	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
25985edc	120	Physical Instances and selects the appropriate instance based
edc7616c SB	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
da50d57a	129	::
edc7616c SB	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	+---------+ +---------+
5051c94b	154	\| \| \| Serial \|
edc7616c SB	155	\| \| \| CFSERL \|
	156	+---------+ +---------+
	157
	158
	159	In this layered approach the following "rules" apply.
da50d57a	160
edc7616c SB	161	- All layers embed the same structure "struct cflayer"
edc7616c SB	162	- A layer does not depend on any other layer's private data.
da50d57a MCC	163	- Layers are stacked by setting the pointers::
da50d57a MCC	164
edc7616c	165	layer->up , layer->dn
da50d57a MCC	166
	167	- In order to send data upwards, each layer should do::
	168
edc7616c	169	layer->up->receive(layer->up, packet);
da50d57a MCC	170
	171	- In order to send data downwards, each layer should do::
	172
edc7616c SB	173	layer->dn->transmit(layer->dn, packet);
	174
	175
5051c94b	176	CAIF Socket and IP interface
da50d57a	177	============================
edc7616c	178
5051c94b SB	179	The IP interface and CAIF socket API are implemented on top of the
5051c94b SB	180	CAIF Core protocol. The IP Interface and CAIF socket have an instance of
edc7616c SB	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
edc7616c SB	187	Configuration of Link Layer
edc7616c SB	188	---------------------------
5051c94b	189	The Link Layer is implemented as Linux network devices (struct net_device).
edc7616c SB	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.