[PATCH] net: docbook fixes for netif_ functions

[PATCH] net: docbook fixes for netif_ functions

[Stephen Hemminger]

Documentation updates for network interfaces.

1. Add doc for netif_napi_add
2. Remove doc for unused returns from netif_rx
3. Add doc for netif_receive_skb

Signed-off-by: Stephen Hemminger <shemminger@linux-foundation.org>

--- a/include/linux/netdevice.h	2007-10-31 09:16:09.000000000 -0700
+++ b/include/linux/netdevice.h	2007-10-31 10:02:15.000000000 -0700
@@ -739,6 +739,16 @@ static inline void *netdev_priv(const st
  */
 #define SET_NETDEV_DEV(net, pdev)	((net)->dev.parent = (pdev))
 
+/**
+ *	netif_napi_add - initialize a napi context
+ *	@dev:  network device
+ *	@napi: napi context
+ *	@poll: polling function
+ *	@weight: default weight
+ *
+ * netif_napi_add() must be used to initialize a napi context prior to calling
+ * *any* of the other napi related functions.
+ */
 static inline void netif_napi_add(struct net_device *dev,
 				  struct napi_struct *napi,
 				  int (*poll)(struct napi_struct *, int),
--- a/net/core/dev.c	2007-10-31 09:16:09.000000000 -0700
+++ b/net/core/dev.c	2007-10-31 10:00:39.000000000 -0700
@@ -1751,9 +1751,6 @@ DEFINE_PER_CPU(struct netif_rx_stats, ne
  *
  *	return values:
  *	NET_RX_SUCCESS	(no congestion)
- *	NET_RX_CN_LOW   (low congestion)
- *	NET_RX_CN_MOD   (moderate congestion)
- *	NET_RX_CN_HIGH  (high congestion)
  *	NET_RX_DROP     (packet was dropped)
  *
  */
@@ -2001,6 +1998,21 @@ out:
 }
 #endif
 
+/**
+ *	netif_receive_skb - process receive buffer from network
+ *	@skb: buffer to process
+ *
+ *	netif_receive_skb() is the main receive data processing function.
+ *	It always succeeds. The buffer may be dropped during processing
+ *	for congestion control or by the protocol layers.
+ *
+ *	This function may only be called from softirq context and interrupts
+ *	should be enabled.
+ *
+ *	return values (usually ignored).
+ *	NET_RX_SUCCESS	(no congestion)
+ *	NET_RX_DROP     (packet was dropped)
+ */
 int netif_receive_skb(struct sk_buff *skb)
 {
 	struct packet_type *ptype, *pt_prev;

Re: [PATCH] net: docbook fixes for netif_ functions

[Randy Dunlap]

On Wed, 31 Oct 2007 14:08:48 -0700 Stephen Hemminger wrote:

> Documentation updates for network interfaces.
> 
> 1. Add doc for netif_napi_add
> 2. Remove doc for unused returns from netif_rx
> 3. Add doc for netif_receive_skb
> 
> Signed-off-by: Stephen Hemminger <shemminger@linux-foundation.org>
> 

> --- a/net/core/dev.c	2007-10-31 09:16:09.000000000 -0700
> +++ b/net/core/dev.c	2007-10-31 10:00:39.000000000 -0700

> @@ -2001,6 +1998,21 @@ out:
>  }
>  #endif
>  
> +/**
> + *	netif_receive_skb - process receive buffer from network
> + *	@skb: buffer to process
> + *
> + *	netif_receive_skb() is the main receive data processing function.
> + *	It always succeeds. The buffer may be dropped during processing
> + *	for congestion control or by the protocol layers.
> + *
> + *	This function may only be called from softirq context and interrupts
> + *	should be enabled.
> + *
> + *	return values (usually ignored).
> + *	NET_RX_SUCCESS	(no congestion)
> + *	NET_RX_DROP     (packet was dropped)

For the 3 lines above, how about:

 *	Return values (usually ignored):
 *	NET_RX_SUCCESS: no congestion
 *	NET_RX_DROP: packet was dropped


only because they come out of kernel-doc badly, munged together like so:

       return  values  (usually  ignored).    NET_RX_SUCCESS (no   congestion)
       NET_RX_DROP     (packet was dropped)


> + */
>  int netif_receive_skb(struct sk_buff *skb)
>  {
>  	struct packet_type *ptype, *pt_prev;
> 

Thanks for doing this patch.
---
~Randy

Re: [PATCH] net: docbook fixes for netif_ functions

[David Miller]

From: Randy Dunlap <rdunlap@xenotime.net>
Date: Wed, 31 Oct 2007 15:36:20 -0700

> > + *	return values (usually ignored).
> > + *	NET_RX_SUCCESS	(no congestion)
> > + *	NET_RX_DROP     (packet was dropped)
> 
> For the 3 lines above, how about:
> 
>  *	Return values (usually ignored):
>  *	NET_RX_SUCCESS: no congestion
>  *	NET_RX_DROP: packet was dropped
> 
> 
> only because they come out of kernel-doc badly, munged together like so:
> 
>        return  values  (usually  ignored).    NET_RX_SUCCESS (no   congestion)
>        NET_RX_DROP     (packet was dropped)

I've applied Stephen's patch with this minor correction
added.