From 138eded8ba1227261a297b32b7940664c14d193e Mon Sep 17 00:00:00 2001
From: "sjur.brandeland@stericsson.com" <sjur.brandeland@stericsson.com>
Date: Sun, 22 May 2011 11:18:53 +0000
Subject: [PATCH] caif: Update documentation of CAIF transmit and receive
functions.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
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>
---
include/net/caif/caif_layer.h | 36 ++++++++++++++++++++---------------
1 file changed, 21 insertions(+), 15 deletions(-)
diff --git a/include/net/caif/caif_layer.h b/include/net/caif/caif_layer.h
index c8b07a904e78..35bc7883cf97 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)
*
--
GitLab