CAIF: Documentation changes

Change-Id: I3d751b89efb872be5e5f6e1e1a71d089d1ee45ca

5 files changed, 202 insertions, 135 deletions

diff --git a/Documentation/networking/caif/Linux-CAIF.txt b/Documentation/networking/caif/Linux-CAIF.txt
index 88f35c0d91e..7fe7a9a33a4 100644
--- a/Documentation/networking/caif/Linux-CAIF.txt
+++ b/Documentation/networking/caif/Linux-CAIF.txt
@@ -1,14 +1,16 @@
 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.
+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.
@@ -18,11 +20,11 @@ Architecture:
 ------------
 The implementation of CAIF is divided into:
 * CAIF Socket Layer, Kernel API, and  Net Device.
-* CAIF Generic Protocol Implementation
+* CAIF Core Protocol Implementation
 * CAIF Link Layer, implemented as NET devices.
 
 
-  RTNL/IOCTL
+  RTNL
    !
    !	 +------+   +------+   +------+
    !	+------+!  +------+!  +------+!
@@ -33,32 +35,15 @@ The implementation of CAIF is divided into:
    !	   +----------!----------+
    !		   +------+		  <- CAIF Protocol Implementation
    +------->	   ! CAIF !
+		   ! Core !
 		   +------+
 	     +--------!--------+
 	     !		       !
 	  +------+	    +-----+
-	  !Loop	 !	    ! TTY !	  <- Link Layer (Net Devices)
+	  !    	 !	    ! TTY !	  <- Link Layer (Net Devices)
 	  +------+	    +-----+
 
 
-Using CAIF (IP) Net Device
-----------------------
-CAIF Net device can be created by use of Socket IOCTLs,
-or RT Netlink.
-
-  static struct ifcaif_param param = {
-    .ipv4_connid = 1,
-    .loop = 0
-  };
-  static struct ifreq ifr = {
-    .ifr_name = "caif%d",
-    .ifr_ifru.ifru_data = &param
-
-  };
-  s = socket(AF_CAIF,SOCK_SEQPACKET,CAIFPROTO_AT);
-  ioctl(s,SIOCCAIFNETNEW,&ifr);
-
-
 Using the Kernel API
 ----------------------
 The Kernel API is used for accessing CAIF channels from the
@@ -89,32 +74,27 @@ I M P L E M E N T A T I O N
 ===========================
 ===========================
 
-Generic CAIF Protocol Layer
+CAIF Core Protocol Layer
 =========================================
 
-caif/generic is a generic CAIF protocol implementation. It implements the CAIF
-protocol as defined by ST-Ericsson.
+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 goal is to have CAIF as system independent as possible.
-All CAIF code can be found under net/caif/generic and include/net/caif/generic.
-
-The generic CAIF implementation is:
+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 implement PHY layer to access physical HW
 	with receive and transmit functions.
       -	Clients must call configuration function to add PHY layer.
-      -	Clients must implement adaptation layer to consume/produce
+      -	Clients must implement CAIF layer to consume/produce
 	CAIF payload with receive and transmit functions.
-      -	Clients must call configuration function to add adaptation
-	layer.
+      -	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 functions
 	or if a transmit function returns an error, in which case the caller
@@ -137,7 +117,7 @@ Implementation. The support functions include:
 The CAIF Protocol implementation contains:
 
       - CFCNFG CAIF Configuration layer. Configures the CAIF Protocol
-	Stack and has a Client interface for adding Link-Layer and
+	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
@@ -147,10 +127,10 @@ The CAIF Protocol implementation contains:
       - CFSERVL General CAIF Service Layer functionality; handles flow
 	control and remote shutdown requests.
 
-      - CFVEI CAIF VEI layer. Handles CAIF VEI layer (AT-Channel),
-	encodes/decodes VEI frames.
+      - CFVEI CAIF VEI layer. Handles CAIF AT Channels on VEI (Virtual
+        External Interface). This layer encodes/decodes VEI frames.
 
-      - CFDGML CAIF Data-gram layer. Handles CAIF Data-gram layer(IP
+      - CFDGML CAIF Datagram layer. Handles CAIF Datagram layer (IP
 	traffic), encodes/decodes Datagram frames.
 
       - CFMUX CAIF Mux layer. Handles multiplexing between multiple
@@ -190,13 +170,13 @@ The CAIF Protocol implementation contains:
 	    +---------+	    +---------+
 		 !		!
 	    +---------+	    +---------+
-	    | Loopback|	    | Serial  |
+	    |         |	    | Serial  |
 	    |	      |	    | CFSERL  |
 	    +---------+	    +---------+
 
 
-In this layered approach the following "rules" applies.
-      - All layers embedd the same structure "struct layer"
+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
@@ -210,23 +190,23 @@ Linux Driver Implementation
 ===========================
 
 Linux GPRS Net Device and CAIF socket are implemented on top of the
-Generic CAIF protocol. The Net device and CAIF socket have an instance of
-'struct layer', just like the generic CAIF protocol stack.
+CAIF Core protocol. The Net device 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 layer', just like the rest of the CAIF stack. In this way, transmit and
+'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.
 
-The layer on top of the generic CAIF implementation is
-sometimes refered to as the "adaptation layer".
+The layer on top of the CAIF Core implementation is
+sometimes referred to as the "Client layer".
 
 
 Configuration of Link Layer
 ---------------------------
 The Link Layer is implemented as Linux net devices (struct net_device).
-Payload handling and registration is done using standard Linux mecanisms.
+Payload handling and registration is done using standard Linux mechanisms.
 
-The CAIF Protocol relies on a lossless link layer without implementing
+The CAIF Protocol relies on a loss-less link layer without implementing
 retransmission. This implies that packet drops must not happen.
-Therefor a flow-control mecanism is implemented where the physical
+Therefore a flow-control mechanism is implemented where the physical
 interface can initiate flow stop for all CAIF Channels.
diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/README
index ef1d51f40d4..7df7ae0d056 100644
--- a/Documentation/networking/caif/README
+++ b/Documentation/networking/caif/README
@@ -1,33 +1,109 @@
-copyright (C) ST-Ericsson AB 2009
+Copyright (C) ST-Ericsson AB 2010
 Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-        Kim Lilliestierna Kim.xx.Lilliestierna@ericsson.com
 License terms: GNU General Public License (GPL) version 2
+---------------------------------------------------------
 
 === Start ===
-Copy the .ko files onto the board, and do insmod:
+If you have compiled CAIF for modules do:
 
-insmod caif.ko
-insmod caif_loop.ko
-insmod chnl_net.ko
-ifconfig caif0 <your-home-address> up
+$modprobe crc_ccitt
+$modprobe caif
+$modprobe caif_socket
+$modprobe chnl_net
 
 
-=== Test Loopback on net device ===
-insmod chnl_net.ko loop=yes
-ifconfig caif0 192.168.0.1 up
-ping -c 10 -s 1000 192.168.0.2
+=== Preparing the setup with a STE modem ===
 
-=== Preparing the setup.===
+If you are working on integration of CAIF you should make sure
+that the kernel is built with module support.
 
-Make sure that the kernel is built with module support.
-
-There are some things that need to be tweaked to get the host TTY
-correctly set up to talk to the modem.
+There are some things that need to be tweaked to get the host TTY correctly
+set up to talk to the modem.
 Since the CAIF stack is running in the kernel and we want to use the existing
 TTY, we are installing our physical serial driver as a line discipline above
-the TTY device. The TTY device used to communicate to modem must be specified
-as a module parameter to caif_ser.
-If the modem is using Start-of-frame-extension (STX) this must also be set as
-module parameter.
+the TTY device.
+
+To achieve this we need to install the N_CAIF ldisc from user space.
+The benefit is that we can hook up to any TTY.
+
+The use of Start-of-frame-extension (STX) must also be set as
+module parameter "ser_use_stx".
+
+Normally Frame Checksum is always used on UART, but this is also provided as a
+module parameter "ser_use_fcs".
+
+$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+$ ifconfig caif_ttyS0 up
+
+PLEASE NOTE: 	There is a limitation in Android shell.
+		It only accepts one argument to insmod/modprobe!
+
+=== Trouble shooting ===
+
+There are debugfs parameters provided for serial communication.
+/sys/kernel/debug/caif_serial/<tty-name>/
+
+* ser_state:   Prints the bit-mask status where
+  - 0x02 means SENDING, this is a transient state.
+  - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
+	and is blocking further send operation. Flow OFF has been propagated
+	to all CAIF Channels using this TTY.
+
+* tty_status: Prints the bit-mask tty status information
+  - 0x01 - tty->warned is on.
+  - 0x02 - tty->low_latency is on.
+  - 0x04 - tty->packed is on.
+  - 0x08 - tty->flow_stopped is on.
+  - 0x10 - tty->hw_stopped is on.
+  - 0x20 - tty->stopped is on.
+
+* last_tx_msg: Binary blob Prints the last transmitted frame.
+	This can be printed with
+	$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
+	The first two tx messages sent look like this. Note: The initial
+	byte 02 is start of frame extension (STX) used for re-syncing
+	upon errors.
+
+  - Enumeration:
+        0000000  02 05 00 00 03 01 d2 02
+                 |  |     |  |  |  |
+                 STX(1)   |  |  |  |
+                    Length(2)|  |  |
+                          Control Channel(1)
+                             Command:Enumeration(1)
+                                Link-ID(1)
+                                    Checksum(2)
+  - Channel Setup:
+        0000000  02 07 00 00 00 21 a1 00 48 df
+                 |  |     |  |  |  |  |  |
+                 STX(1)   |  |  |  |  |  |
+                    Length(2)|  |  |  |  |
+                          Control Channel(1)
+                             Command:Channel Setup(1)
+                                Channel Type(1)
+                                    Priority and Link-ID(1)
+				      Endpoint(1)
+					  Checksum(2)
+
+* last_rx_msg: Prints the last transmitted frame.
+	The RX messages for LinkSetup look almost identical but they have the
+	bit 0x20 set in the command bit, and Channel Setup has added one byte
+	before Checksum containing Channel ID.
+	NOTE: Several CAIF Messages might be concatenated. The maximum debug
+	buffer size is 128 bytes.
+
+== Error Scenarios:
+- last_tx_msg contains channel setup message and last_rx_msg is empty ->
+  The host seems to be able to send over the UART, at least the CAIF ldisc get
+  notified that sending is completed.
+
+- last_tx_msg contains enumeration message and last_rx_msg is empty ->
+  The host is not able to send the message from UART, the tty has not been
+  able to complete the transmit operation.
 
-$ insmod caif_ser.ko ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
+  might be problems transmitting over UART.
+  E.g. host and modem wiring is not correct you will typically see
+  tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+  You will probably see the enumeration message in last_tx_message
+  and empty last_rx_message.
\ No newline at end of file
diff --git a/Documentation/networking/caif/caif.man b/Documentation/networking/caif/caif.man
index ece19574277..74d12f49839 100644
--- a/Documentation/networking/caif/caif.man
+++ b/Documentation/networking/caif/caif.man
@@ -55,8 +55,6 @@ is returned by the functions
 .BR read (2), recv (2),
 .BR recvmsg (2)
 if the provided buffer is too small to hold the received CAIF message.
-The length can be retrieved by using socket option
-.BR CAIFSO_PACKET_LEN .
 
 .B EMSGSIZE
 is returned for
@@ -91,7 +89,7 @@ After a successful connect, information about the CAIF connection
 can be read using
 .BR getsockopt (2).
 Relevant options for getsockopt are
-.B CAIFSO_CONN_ID
+.B CAIFSO_CHANNEL_ID
 to read the unique CAIF channel ID.
 For a CAIF utility link
 .RB ( CAIFPROTO_UTIL )
@@ -203,7 +201,60 @@ must be one of the supported protocols defined by the
 enum.
 
 .TP
-.B CAIFSO_CHANNEL_CONFIG
+.B CAIFSO_LINK_SELECT
+When muliple CAIF Link layers are available the CAIF socket will
+default use the high bandwidth link. But the link selection can
+be set explicitly with the socket option
+.B CAIFSO_LINK_SELECT.
+Either a high bandwidth link can be selected by using
+.B CAIF_LINK_HIGH_BANDW
+as argument or a low latency link can be selected with argument
+.B CAIF_LINK_LOW_LATENCY
+This option is of type u_int32_t.
+Alternativly to this option SO_BINDTODEVICE can be used.
+.TP
+.B SO_BINDTODEVICE
+can be used to bind a CAIF socket to an named
+.I struct ifreq
+with element name set to the desired CAIF interface.
+.TP
+.B SO_PRIORITY
+can be used to specify the CAIF Channel priority.
+The is used as argument of type int.
+The priority must be a between 0 and 31 where 0 is
+the lowest priority of the channel.
+.TP
+.B CAIFSO_REQ_PARAM
+For connections of type
+.B CAIFPROTO_UTIL
+additional request parameters may be supplied with this socket option.
+The actual parameters are send using
+the struct
+.I caif_param.
+
+.nf
+struct caif_param {
+        u_int16_t size;
+        u_int8_t  data[256];
+};
+.fi
+.I size
+and
+.I data
+specifies the request parameter length and value.
+.TP
+.B CAIFSO_RSP_PARAM
+For connections of type
+.B CAIFPROTO_UTIL
+the modem may supply extra response parameters in the connect response.
+.TP
+.B CAIFSO_CHANNEL_ID
+Every open connection has a unique CAIF connection ID.
+This is assigned by the modem and is unique for every CAIF connection in the system.
+This socket option allows connection ID (u_int32_t) to be read after a successful connect.
+
+.TP
+.B CAIFSO_CHANNEL_CONFIG - DEPREPECATED
 When connecting a CAIF socket, the address given in sockaddr_caif is not
 the only parameters in the
 actual CAIF connect message. It also contains priority on the connection
@@ -235,50 +286,6 @@ should be set to
 for low latency connections and
 .B CAIF_LINK_HIGH_BANDW
 for high bandwidth connections.
-.TP
-.B CAIFSO_REQ_PARAM
-For connections of type
-.B CAIFPROTO_UTIL
-additional request parameters may be supplied with this socket option.
-The actual parameters are send using
-the struct
-.I caif_param.
-
-.nf
-struct caif_param {
-        u_int16_t size;
-        u_int8_t  data[256];
-};
-.fi
-.I size
-and
-.I data
-specifies the request parameter length and value.
-.TP
-.B CAIFSO_RSP_PARAM
-For connections of type
-.B CAIFPROTO_UTIL
-the modem may supply extra response parameters in the connect response.
-The response is returned in struct
-.IR caif_param .
-If no response parameters are supplied,
-.I size
-will be set to zero.
-.TP
-.B CAIFSO_CONN_ID
-Every open connection has a unique CAIF connection ID.
-This is assigned by the modem and is unique for every CAIF connection in the system.
-This socket option allows connection ID (u_int32_t) to be read after a successful connect.
-.TP
-.B CAIFSO_NEXT_PACKET_LEN
-The length of the next packet in the socket's receive queue can be read using
-this socket option. If no packet is available, zero is returned.
-The type is u_int32_t.
-.TP
-.B CAIFSO_MAX_PACKET_LEN
-The maximum transfer and receive packet size can be read using this
-socket option.
-The type is u_int32_t.
 
 .SH ERROR CODES
 .TP
@@ -384,13 +391,13 @@ but may be caused by transient congestion.
   len = sizeof(rsp);
   getsockopt(s, SOL_CAIF, CAIFSO_RSP_PARAM, &rsp, &len);
   len = sizeof(connid);
-  getsockopt(s, SOL_CAIF, CAIFSO_CONN_ID, &connid, &len);
+  getsockopt(s, SOL_CAIF, CAIFSO_CHANNEL_ID, &connid, &len);
 .fi
 .PP
 .SH AUTHOR
 Sjur Brandeland <sjur.brandeland@stericsson.com>
 .SH COPYRIGHT
-Copyright (C) ST-Ericsson AB 2009
+Copyright (C) ST-Ericsson AB 2010
 .SH SEE ALSO
 .BR socket (2),
 .BR connect (2),
diff --git a/Documentation/networking/caif/caifioc/caifioc.c b/Documentation/networking/caif/caifioc/caifioc.c
index aa50da046fd..e4185fe0c6d 100644
--- a/Documentation/networking/caif/caifioc/caifioc.c
+++ b/Documentation/networking/caif/caifioc/caifioc.c
@@ -1,8 +1,8 @@
 /*
  * Example program creating and configuring CAIF IP Interface
  * by use of IOCTLs.
- * Copyright (C) ST-Ericsson AB 2009
- * Author:	Sjur Brandeland / sjur.brandeland@stericsson.com
+ * Copyright (C) ST-Ericsson AB 2010
+ * Author:	Sjur Brendeland / sjur.brandeland@stericsson.com
  * License terms: GNU General Public License (GPL) version 2
  */
 #include <linux/types.h>
diff --git a/Documentation/networking/caif/spi_porting.txt b/Documentation/networking/caif/spi_porting.txt
index 45744ce4a9c..69f801e85f4 100644
--- a/Documentation/networking/caif/spi_porting.txt
+++ b/Documentation/networking/caif/spi_porting.txt
@@ -67,7 +67,7 @@ This part takes care of the physical hardware, both with regard to SPI and to GP
 		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 ("phyif_sspi").
+		Add name of driver to connect to ("cfspi_sspi").
 		Assign the SPI slave device structure as platform data.
 
 - Padding:
@@ -75,16 +75,14 @@ This part takes care of the physical hardware, both with regard to SPI and to GP
 In order to optimize throughput, a number of SPI padding options are provided. Padding can be
 enabled independently for uplink and downlink transfers. Padding can be enabled for the head, the
 tail and for the total frame size. The padding needs to be correctly configured on both sides of
-the link. The padding can be changed via module parameters in phyif_sspi.c or via the sysfs
-directory of the phyif_sspi driver (before device registration).
+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:
 
 /*
- *      Copyright (C) ST-Ericsson AB 2009
- *
+ *      Copyright (C) ST-Ericsson AB 2010
  *      Author: Daniel Martensson / Daniel.Martensson@stericsson.com
- *
  *      License terms: GNU General Public License (GPL), version 2.
  *
  */
@@ -95,9 +93,7 @@ directory of the phyif_sspi driver (before device registration).
 #include <linux/wait.h>
 #include <linux/interrupt.h>
 #include <linux/dma-mapping.h>
-
-#include "caif_chr.h"
-#include "phyif_spi.h"
+#include <net/caif/caif_spi.h>
 
 MODULE_LICENSE("GPL");
 
@@ -153,6 +149,13 @@ void sspi_sig_xfer(bool xfer, struct cfspi_dev *dev)
 	struct sspi_struct *sspi = (struct sspi_struct *)dev->priv;
 }
 
+static void sspi_release(struct device *dev)
+{
+	/*
+	 * Here you should release your SPI device resources.
+	 */
+}
+
 static int __init sspi_init(void)
 {
 	/* Here you should initialize your SPI device by providing the
@@ -171,9 +174,10 @@ static int __init sspi_init(void)
 	slave.sdev.clk_mhz = 13;
 	slave.sdev.priv = &slave;
 	slave.sdev.name = "spi_sspi";
+	slave_device.dev.release = sspi_release;
 
 	/* Initialize platform device. */
-	slave_device.name = "phyif_sspi";
+	slave_device.name = "cfspi_sspi";
 	slave_device.dev.platform_data = &slave.sdev;
 
 	/* Register platform device. */
@@ -188,7 +192,7 @@ static int __init sspi_init(void)
 
 static void __exit sspi_exit(void)
 {
-	platform_device_unregister(&slave_device);
+	platform_device_del(&slave_device);
 }
 
 module_init(sspi_init);