Commit da50d57a authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by David S. Miller
Browse files

docs: networking: convert caif files to ReST 



There are two text files for caif, plus one already converted
file.

Convert the two remaining ones to ReST, create a new index.rst
file for CAIF, adding it to the main networking documentation
index.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent 790ab249

Documentation/networking/caif/caif.rst

+0 −2
Original line number Diff line number Diff line 
:orphan:



.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

Documentation/networking/caif/index.rst

0 → 100644
+13 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



CAIF

====



Contents:



.. toctree::

   :maxdepth: 2



   linux_caif

   caif

   spi_porting

Documentation/networking/caif/Linux-CAIF.txt→Documentation/networking/caif/linux_caif.rst

+37 −17
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.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

==========



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.
@@ -16,13 +23,16 @@ ST-Ericsson modems support a number of transports between modem 
and host. Currently, UART and Loopback are available for Linux.





Architecture:

------------

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

   !
@@ -46,12 +56,12 @@ The implementation of CAIF is divided into: 






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

===========================

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
@@ -59,8 +69,11 @@ 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 ==

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.
@@ -73,7 +86,8 @@ The Core CAIF implementation contains: 
	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:
@@ -112,7 +126,7 @@ The CAIF Protocol implementation contains: 
      - CFSERL CAIF Serial layer. Handles concatenation/split of frames

	into CAIF Frames with correct length.





::



		    +---------+

		    | Config  |
@@ -143,18 +157,24 @@ The CAIF Protocol implementation contains: 




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

      - Layers are stacked by setting the pointers::



		  layer->up , layer->dn

      -	In order to send data upwards, each layer should do



      -	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



      - 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

Documentation/networking/caif/spi_porting.txt→Documentation/networking/caif/spi_porting.rst

+229 −0
Original line number Diff line number Diff line 
- CAIF SPI porting -

.. SPDX-License-Identifier: GPL-2.0



- CAIF SPI basics:

================

CAIF SPI porting

================



CAIF SPI basics

===============



Running CAIF over SPI needs some extra setup, owing to the nature of SPI.

Two extra GPIOs have been added in order to negotiate the transfers
@@ -9,7 +14,8 @@ CAIF over SPI is a SPI slave chip and two GPIOs (more details below). 
Please note that running as a slave implies that you need to keep up

with the master clock. An overrun or underrun event is fatal.



- CAIF SPI framework:

CAIF SPI framework

==================



To make porting as easy as possible, the CAIF SPI has been divided in

two parts. The first part (called the interface part) deals with all
@@ -27,6 +33,8 @@ the physical hardware, both with regard to SPI and to GPIOs. 
	need to implement the following

	functions:



	::



	    int (*init_xfer) (struct cfspi_xfer * xfer, struct cfspi_dev *dev):



	This function is called by the CAIF SPI interface to give
@@ -36,6 +44,8 @@ the physical hardware, both with regard to SPI and to GPIOs. 
	of the transfer in both directions.The dev parameter can be used

	to map to different CAIF SPI slave devices.



	::



	    void (*sig_xfer) (bool xfer, struct cfspi_dev *dev):



	This function is called by the CAIF SPI interface when the output
@@ -46,6 +56,8 @@ the physical hardware, both with regard to SPI and to GPIOs. 


	- Functionality provided by the CAIF SPI interface:



	::



	    void (*ss_cb) (bool assert, struct cfspi_ifc *ifc);



	This function is called by the CAIF SPI slave device in order to
@@ -55,6 +67,8 @@ the physical hardware, both with regard to SPI and to GPIOs. 
	not to introduce latency). The ifc parameter should be the pointer

	returned from the platform probe function in the SPI device structure.



	::



	    void (*xfer_done_cb) (struct cfspi_ifc *ifc);



	This function is called by the CAIF SPI slave device in order to
@@ -69,16 +83,23 @@ the physical hardware, both with regard to SPI and to GPIOs. 
		- Filling in the SPI slave device structure:



		  Connect the necessary callback functions.



		  Indicate clock speed (used to calculate toggle delays).



		  Chose a suitable name (helps debugging if you use several CAIF

		  SPI slave devices).

		Assign your private data (can be used to map to your structure).



		  Assign your private data (can be used to map to your

		  structure).



		- Filling in the SPI slave platform device structure:



		  Add name of driver to connect to ("cfspi_sspi").



		  Assign the SPI slave device structure as platform data.



- Padding:

Padding

=======



In order to optimize throughput, a number of SPI padding options are provided.

Padding can be enabled independently for uplink and downlink transfers.
@@ -87,7 +108,7 @@ The padding needs to be correctly configured on both sides of the link. 
The padding can be changed via module parameters in cfspi_sspi.c or via

the sysfs directory of the cfspi_sspi driver (before device registration).



- CAIF SPI device template:

- CAIF SPI device template::



    /*

    *	Copyright (C) ST-Ericsson AB 2010

Documentation/networking/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -15,6 +15,7 @@ Contents: 
   device_drivers/index

   dsa/index

   devlink/index

   caif/index

   ethtool-netlink

   ieee802154

   j1939