diff options
author | sjur.brandeland@stericsson.com <sjur.brandeland@stericsson.com> | 2011-05-22 11:18:53 (GMT) |
---|---|---|
committer | David S. Miller <davem@davemloft.net> | 2011-05-23 00:11:48 (GMT) |
commit | 138eded8ba1227261a297b32b7940664c14d193e (patch) | |
tree | cd723c7eb7309f759c95f5bcebfb7d4b12641ca8 /include/net/caif/caif_layer.h | |
parent | 96796ea8b6b1221c7cacf68ce056d77eff0a793d (diff) | |
download | linux-138eded8ba1227261a297b32b7940664c14d193e.tar.xz |
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>
Diffstat (limited to 'include/net/caif/caif_layer.h')
-rw-r--r-- | include/net/caif/caif_layer.h | 36 |
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) * |