1 files changed, 75 insertions, 0 deletions

diff --git a/Documentation/networking/netdevices.txt b/Documentation/networking/netdevices.txt
new file mode 100644
index 000000000000..1509f3aff968
--- /dev/null
+++ b/Documentation/networking/netdevices.txt
@@ -0,0 +1,75 @@
+
+Network Devices, the Kernel, and You!
+
+
+Introduction
+============
+The following is a random collection of documentation regarding
+network devices.
+
+struct net_device allocation rules
+==================================
+Network device structures need to persist even after module is unloaded and
+must be allocated with kmalloc.  If device has registered successfully,
+it will be freed on last use by free_netdev.  This is required to handle the
+pathologic case cleanly (example: rmmod mydriver </sys/class/net/myeth/mtu )
+
+There are routines in net_init.c to handle the common cases of
+alloc_etherdev, alloc_netdev.  These reserve extra space for driver
+private data which gets freed when the network device is freed. If
+separately allocated data is attached to the network device
+(dev->priv) then it is up to the module exit handler to free that.
+
+
+struct net_device synchronization rules
+=======================================
+dev->open:
+        Synchronization: rtnl_lock() semaphore.
+        Context: process
+
+dev->stop:
+        Synchronization: rtnl_lock() semaphore.
+        Context: process
+        Note1: netif_running() is guaranteed false
+        Note2: dev->poll() is guaranteed to be stopped
+
+dev->do_ioctl:
+        Synchronization: rtnl_lock() semaphore.
+        Context: process
+
+dev->get_stats:
+        Synchronization: dev_base_lock rwlock.
+        Context: nominally process, but don't sleep inside an rwlock
+
+dev->hard_start_xmit:
+        Synchronization: dev->xmit_lock spinlock.
+        When the driver sets NETIF_F_LLTX in dev->features this will be
+        called without holding xmit_lock. In this case the driver 
+        has to lock by itself when needed. It is recommended to use a try lock
+        for this and return -1 when the spin lock fails. 
+        The locking there should also properly protect against 
+        set_multicast_list
+        Context: BHs disabled
+        Notes: netif_queue_stopped() is guaranteed false
+        Return codes: 
+        o NETDEV_TX_OK everything ok. 
+        o NETDEV_TX_BUSY Cannot transmit packet, try later 
+          Usually a bug, means queue start/stop flow control is broken in
+          the driver. Note: the driver must NOT put the skb in its DMA ring.
+        o NETDEV_TX_LOCKED Locking failed, please retry quickly.
+          Only valid when NETIF_F_LLTX is set.
+
+dev->tx_timeout:
+        Synchronization: dev->xmit_lock spinlock.
+        Context: BHs disabled
+        Notes: netif_queue_stopped() is guaranteed true
+
+dev->set_multicast_list:
+        Synchronization: dev->xmit_lock spinlock.
+        Context: BHs disabled
+
+dev->poll:
+        Synchronization: __LINK_STATE_RX_SCHED bit in dev->state.  See
+                dev_close code and comments in net/core/dev.c for more info.
+        Context: softirq
+