caif: Update documentation of CAIF transmit and receive functions.

Trivial patch updating documentation in header files only.
Error handling of CAIF transmit errors was changed by commit:
      caif: Don't resend if dev_queue_xmit fails.
This patch updates the documentation accordingly.

Signed-off-by: Sjur Brændeland <sjur.brandeland@stericsson.com>
Signed-off-by: David S. Miller <davem@davemloft.net>

1 files changed, 21 insertions, 15 deletions

diff --git a/include/net/caif/caif_layer.h b/include/net/caif/caif_layer.h
index c8b07a9..35bc788 100644
--- a/include/net/caif/caif_layer.h
+++ b/include/net/caif/caif_layer.h
@@ -15,7 +15,6 @@ struct cfpktq;
 struct caif_payload_info;
 struct caif_packet_funcs;
 
-
 #define CAIF_LAYER_NAME_SZ 16
 
 /**
@@ -33,7 +32,6 @@ do {								\
 	}							\
 } while (0)
 
-
 /**
  * enum caif_ctrlcmd - CAIF Stack Control Signaling sent in layer.ctrlcmd().
  *
@@ -141,7 +139,7 @@ enum caif_direction {
  *    - All layers must use this structure. If embedding it, then place this
  *	structure first in the layer specific structure.
  *
- *    - Each layer should not depend on any others layer private data.
+ *    - Each layer should not depend on any others layer's private data.
  *
  *    - In order to send data upwards do
  *	layer->up->receive(layer->up, packet);
@@ -155,16 +153,23 @@ struct cflayer {
 	struct list_head node;
 
 	/*
-	 *  receive() - Receive Function.
+	 *  receive() - Receive Function (non-blocking).
 	 *  Contract: Each layer must implement a receive function passing the
 	 *  CAIF packets upwards in the stack.
 	 *	Packet handling rules:
-	 *	      - The CAIF packet (cfpkt) cannot be accessed after
-	 *		     passing it to the next layer using up->receive().
+	 *	      - The CAIF packet (cfpkt) ownership is passed to the
+	 *		called receive function. This means that the the
+	 *		packet cannot be accessed after passing it to the
+	 *		above layer using up->receive().
+	 *
 	 *	      - If parsing of the packet fails, the packet must be
-	 *		     destroyed and -1 returned from the function.
+	 *		destroyed and negative error code returned
+	 *		from the function.
+	 *		EXCEPTION: If the framing layer (cffrml) returns
+	 *			-EILSEQ, the packet is not freed.
+	 *
 	 *	      - If parsing succeeds (and above layers return OK) then
-	 *		      the function must return a value > 0.
+	 *		      the function must return a value >= 0.
 	 *
 	 *  Returns result < 0 indicates an error, 0 or positive value
 	 *	     indicates success.
@@ -176,7 +181,7 @@ struct cflayer {
 	int (*receive)(struct cflayer *layr, struct cfpkt *cfpkt);
 
 	/*
-	 *  transmit() - Transmit Function.
+	 *  transmit() - Transmit Function (non-blocking).
 	 *  Contract: Each layer must implement a transmit function passing the
 	 *	CAIF packet downwards in the stack.
 	 *	Packet handling rules:
@@ -185,15 +190,16 @@ struct cflayer {
 	 *		cannot be accessed after passing it to the below
 	 *		layer using dn->transmit().
 	 *
-	 *	      - If transmit fails, however, the ownership is returned
-	 *		to thecaller. The caller of "dn->transmit()" must
-	 *		destroy or resend packet.
+	 *	      - Upon error the packet ownership is still passed on,
+	 *		so the packet shall be freed where error is detected.
+	 *		Callers of the transmit function shall not free packets,
+	 *		but errors shall be returned.
 	 *
 	 *	      - Return value less than zero means error, zero or
 	 *		greater than zero means OK.
 	 *
-	 *	 result < 0 indicates an error, 0 or positive value
-	 *	 indicate success.
+	 *  Returns result < 0 indicates an error, 0 or positive value
+	 *		indicates success.
 	 *
 	 *  @layr:	Pointer to the current layer the receive function
 	 *		isimplemented for (this pointer).
@@ -202,7 +208,7 @@ struct cflayer {
 	int (*transmit) (struct cflayer *layr, struct cfpkt *cfpkt);
 
 	/*
-	 *  cttrlcmd() - Control Function upwards in CAIF Stack.
+	 *  cttrlcmd() - Control Function upwards in CAIF Stack  (non-blocking).
 	 *  Used for signaling responses (CAIF_CTRLCMD_*_RSP)
 	 *  and asynchronous events from the modem  (CAIF_CTRLCMD_*_IND)
 	 *