[PATCH net-next-2.6 V2] net: enhance the documentation for rx_handler.

["Nicolas de Pesloüan" <nicolas.2p.debian@free.fr>]

Signed-off-by: Nicolas de Pesloüan <nicolas.2p.debian@free.fr>
Reviewed-by: Jiri Pirko <jpirko@redhat.com>
---
This apply on top of Jiri's last patch serie, including the last one that
commented the RX_HANDLER_* values.

 include/linux/netdevice.h |   53 ++++++++++++++++++++++++++++++++++++++------
 net/core/dev.c            |    2 +
 2 files changed, 47 insertions(+), 8 deletions(-)

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 26e03f9..0c9dc93 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -390,15 +390,52 @@ enum gro_result {
 };
 typedef enum gro_result gro_result_t;
 
+/**
+ * enum rx_handler_result - Possible return values for rx_handlers.
+ * @RX_HANDLER_CONSUMED: skb was consumed by rx_handler, do not process it
+ * further.
+ * @RX_HANDLER_ANOTHER: Do another round in receive path. This is indicated in
+ * case skb->dev was changed by rx_handler.
+ * @RX_HANDLER_EXACT: Force exact delivery, no wildcard.
+ * @RX_HANDLER_PASS: Do nothing, process the skb as if no rx_handler was called.
+ *
+ * rx_handlers are functions called from inside __netif_receive_skb(), to do
+ * special processing of the skb, prior to delivery to protocol handlers.
+ *
+ * Currently, a net_device can only have a single rx_handler registered. Trying
+ * to register a second rx_handler will return -EBUSY.
+ *
+ * To register a rx_handler on a net_device, use netdev_rx_handler_register().
+ * To unregister a rx_handler on a net_device, use
+ * netdev_rx_handler_unregister().
+ *
+ * Upon return, rx_handler is expected to tell __netif_receive_skb() what to
+ * do with the skb.
+ *
+ * If the rx_handler consumed to skb in some way, it should return
+ * RX_HANDLER_CONSUMED. This is appropriate when the rx_handler arranged for
+ * the skb to be delivered in some other ways.
+ *
+ * If the rx_handler changed skb->dev, to divert the skb to another
+ * net_device, it should return RX_HANDLER_ANOTHER. The rx_handler for the
+ * new device will be called if it exists.
+ *
+ * If the rx_handler consider the skb should be ignored, it should return
+ * RX_HANDLER_EXACT. The skb will only be delivered to protocol handlers that
+ * are registred on exact device (ptype->dev == skb->dev).
+ *
+ * If the rx_handler didn't changed skb->dev, but want the skb to be normally 
+ * delivered, it should return RX_HANDLER_PASS.
+ * 
+ * A device without a registered rx_handler will behave as if rx_handler
+ * returned RX_HANDLER_PASS.
+ */
+
 enum rx_handler_result {
-	RX_HANDLER_CONSUMED,	/* skb was consumed by rx_handler,
-				   do not process it further. */
-	RX_HANDLER_ANOTHER,	/* Do another round in receive path.
-				   This is indicated in case skb->dev
-				   was changed by rx_handler */
-	RX_HANDLER_EXACT,	/* Force exact delivery, no wildcard */
-	RX_HANDLER_PASS,	/* Do nothing, pass the skb as if
-				   no rx_handler was called */
+	RX_HANDLER_CONSUMED,
+	RX_HANDLER_ANOTHER,	
+	RX_HANDLER_EXACT,
+	RX_HANDLER_PASS,
 };
 typedef enum rx_handler_result rx_handler_result_t;
 typedef rx_handler_result_t rx_handler_func_t(struct sk_buff **pskb);
diff --git a/net/core/dev.c b/net/core/dev.c
index a368223..3630722 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -3060,6 +3060,8 @@ out:
  *	on a failure.
  *
  *	The caller must hold the rtnl_mutex.
+ *
+ *	For a general description of rx_handler, see enum rx_handler_result.
  */
 int netdev_rx_handler_register(struct net_device *dev,
 			       rx_handler_func_t *rx_handler,
-- 
1.7.2.3