Add more kernel doc's for part of the network device API.
This is only a start, and needs more work.
Applies against net-2.6.24
Signed-off-by: Stephen Hemminger [EMAIL PROTECTED]
--- a/Documentation/DocBook/kernel-api.tmpl 2007-08-21 15:43:37.0
-0700
+++ b/Documentation/DocBook/kernel-api.tmpl 2007-08-22 12:30:33.0
-0700
@@ -240,17 +240,23 @@ X!Ilib/string.c
sect1titleDriver Support/title
!Enet/core/dev.c
!Enet/ethernet/eth.c
+!Enet/sched/sch_generic.c
!Iinclude/linux/etherdevice.h
+!Iinclude/linux/netdevice.h
+ /sect1
+ sect1titlePHY Support/title
!Edrivers/net/phy/phy.c
!Idrivers/net/phy/phy.c
!Edrivers/net/phy/phy_device.c
!Idrivers/net/phy/phy_device.c
!Edrivers/net/phy/mdio_bus.c
!Idrivers/net/phy/mdio_bus.c
+ /sect1
!-- FIXME: Removed for now since no structured comments in source
+ sect1titleWireless/title
X!Enet/core/wireless.c
---
/sect1
+--
sect1titleSynchronous PPP/title
!Edrivers/net/wan/syncppp.c
/sect1
--- a/include/linux/netdevice.h 2007-08-21 15:44:00.0 -0700
+++ b/include/linux/netdevice.h 2007-08-22 12:00:16.0 -0700
@@ -302,17 +302,38 @@ enum
extern void FASTCALL(__napi_schedule(struct napi_struct *n));
+/**
+ * napi_schedule_prep - check if napi can be scheduled
+ * @n: napi context
+ *
+ * Test if NAPI routine is already running, and if not mark
+ * it as running. This is used as a condition variable
+ * insure only one NAPI poll instance runs
+ */
static inline int napi_schedule_prep(struct napi_struct *n)
{
return !test_and_set_bit(NAPI_STATE_SCHED, n-state);
}
+/**
+ * napi_schedule - schedule NAPI poll
+ * @n: napi context
+ *
+ * Schedule NAPI poll routine to be called if it is not already
+ * running.
+ */
static inline void napi_schedule(struct napi_struct *n)
{
if (napi_schedule_prep(n))
__napi_schedule(n);
}
+/**
+ * napi_complete - NAPI processing complete
+ * @n: napi context
+ *
+ * Mark NAPI processing as complete.
+ */
static inline void napi_complete(struct napi_struct *n)
{
BUG_ON(!test_bit(NAPI_STATE_SCHED, n-state));
@@ -320,12 +341,26 @@ static inline void napi_complete(struct
clear_bit(NAPI_STATE_SCHED, n-state);
}
+/**
+ * napi_disable - prevent NAPI from scheduling
+ * @n: napi context
+ *
+ * Stop NAPI from being scheduled on this context.
+ * Waits till any outstanding processing completes.
+ */
static inline void napi_disable(struct napi_struct *n)
{
while (test_and_set_bit(NAPI_STATE_SCHED, n-state))
msleep_interruptible(1);
}
+/**
+ * napi_disable - prevent NAPI from scheduling
+ * @n: napi context
+ *
+ * Resume NAPI from being scheduled on this context.
+ * Must be paired with napi_disable.
+ */
static inline void napi_enable(struct napi_struct *n)
{
BUG_ON(!test_bit(NAPI_STATE_SCHED, n-state));
@@ -636,6 +671,12 @@ struct net_device
#defineNETDEV_ALIGN32
#defineNETDEV_ALIGN_CONST (NETDEV_ALIGN - 1)
+/**
+ * netdev_priv - access network device private data
+ * @dev: network device
+ *
+ * Get network device private data
+ */
static inline void *netdev_priv(const struct net_device *dev)
{
return dev-priv;
@@ -773,11 +814,24 @@ static inline void netif_schedule(struct
__netif_schedule(dev);
}
+/**
+ * netif_start_queue - allow transmit
+ * @dev: network device
+ *
+ * Allow upper layers to call the device hard_start_xmit routine.
+ */
static inline void netif_start_queue(struct net_device *dev)
{
clear_bit(__LINK_STATE_XOFF, dev-state);
}
+/**
+ * netif_wake_queue - restart transmit
+ * @dev: network device
+ *
+ * Allow upper layers to call the device hard_start_xmit routine.
+ * Used for flow control when transmit resources are available.
+ */
static inline void netif_wake_queue(struct net_device *dev)
{
#ifdef CONFIG_NETPOLL_TRAP
@@ -790,16 +844,35 @@ static inline void netif_wake_queue(stru
__netif_schedule(dev);
}
+/**
+ * netif_stop_queue - stop transmitted packets
+ * @dev: network device
+ *
+ * Stop upper layers calling the device hard_start_xmit routine.
+ * Used for flow control when transmit resources are unavailable.
+ */
static inline void netif_stop_queue(struct net_device *dev)
{
set_bit(__LINK_STATE_XOFF, dev-state);
}
+/**
+ * netif_queue_stopped - test if transmit queue is flowblocked
+ * @dev: network device
+ *
+ * Test if transmit queue on device is currently unable to send.
+ */
static inline int netif_queue_stopped(const struct net_device *dev)
{
return test_bit(__LINK_STATE_XOFF, dev-state);
}
+/**
+ * netif_running - test if up
+ * @dev: network device
+ *
+ * Test if the device has been brought up.
+ */
static inline int netif_running(const struct net_device *dev)
{
return
