ia64/linux-2.6.18-xen.hg

diff Documentation/networking/netdevices.txt @ 0:831230e53067

Import 2.6.18 from kernel.org tarball.
author Ian Campbell <ian.campbell@xensource.com>
date Wed Apr 11 14:15:44 2007 +0100 (2007-04-11)
parents
children
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/Documentation/networking/netdevices.txt	Wed Apr 11 14:15:44 2007 +0100
     1.3 @@ -0,0 +1,77 @@
     1.4 +
     1.5 +Network Devices, the Kernel, and You!
     1.6 +
     1.7 +
     1.8 +Introduction
     1.9 +============
    1.10 +The following is a random collection of documentation regarding
    1.11 +network devices.
    1.12 +
    1.13 +struct net_device allocation rules
    1.14 +==================================
    1.15 +Network device structures need to persist even after module is unloaded and
    1.16 +must be allocated with kmalloc.  If device has registered successfully,
    1.17 +it will be freed on last use by free_netdev.  This is required to handle the
    1.18 +pathologic case cleanly (example: rmmod mydriver </sys/class/net/myeth/mtu )
    1.19 +
    1.20 +There are routines in net_init.c to handle the common cases of
    1.21 +alloc_etherdev, alloc_netdev.  These reserve extra space for driver
    1.22 +private data which gets freed when the network device is freed. If
    1.23 +separately allocated data is attached to the network device
    1.24 +(dev->priv) then it is up to the module exit handler to free that.
    1.25 +
    1.26 +
    1.27 +struct net_device synchronization rules
    1.28 +=======================================
    1.29 +dev->open:
    1.30 +	Synchronization: rtnl_lock() semaphore.
    1.31 +	Context: process
    1.32 +
    1.33 +dev->stop:
    1.34 +	Synchronization: rtnl_lock() semaphore.
    1.35 +	Context: process
    1.36 +	Note1: netif_running() is guaranteed false
    1.37 +	Note2: dev->poll() is guaranteed to be stopped
    1.38 +
    1.39 +dev->do_ioctl:
    1.40 +	Synchronization: rtnl_lock() semaphore.
    1.41 +	Context: process
    1.42 +
    1.43 +dev->get_stats:
    1.44 +	Synchronization: dev_base_lock rwlock.
    1.45 +	Context: nominally process, but don't sleep inside an rwlock
    1.46 +
    1.47 +dev->hard_start_xmit:
    1.48 +	Synchronization: netif_tx_lock spinlock.
    1.49 +	When the driver sets NETIF_F_LLTX in dev->features this will be
    1.50 +	called without holding netif_tx_lock. In this case the driver
    1.51 +	has to lock by itself when needed. It is recommended to use a try lock
    1.52 +	for this and return -1 when the spin lock fails. 
    1.53 +	The locking there should also properly protect against 
    1.54 +	set_multicast_list
    1.55 +	Context: BHs disabled
    1.56 +	Notes: netif_queue_stopped() is guaranteed false
    1.57 +               Interrupts must be enabled when calling hard_start_xmit.
    1.58 +                (Interrupts must also be enabled when enabling the BH handler.)
    1.59 +	Return codes: 
    1.60 +	o NETDEV_TX_OK everything ok. 
    1.61 +	o NETDEV_TX_BUSY Cannot transmit packet, try later 
    1.62 +	  Usually a bug, means queue start/stop flow control is broken in
    1.63 +	  the driver. Note: the driver must NOT put the skb in its DMA ring.
    1.64 +	o NETDEV_TX_LOCKED Locking failed, please retry quickly.
    1.65 +	  Only valid when NETIF_F_LLTX is set.
    1.66 +
    1.67 +dev->tx_timeout:
    1.68 +	Synchronization: netif_tx_lock spinlock.
    1.69 +	Context: BHs disabled
    1.70 +	Notes: netif_queue_stopped() is guaranteed true
    1.71 +
    1.72 +dev->set_multicast_list:
    1.73 +	Synchronization: netif_tx_lock spinlock.
    1.74 +	Context: BHs disabled
    1.75 +
    1.76 +dev->poll:
    1.77 +	Synchronization: __LINK_STATE_RX_SCHED bit in dev->state.  See
    1.78 +		dev_close code and comments in net/core/dev.c for more info.
    1.79 +	Context: softirq
    1.80 +