annotate 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)
rev   line source
ian@0 1
ian@0 2 Network Devices, the Kernel, and You!
ian@0 3
ian@0 4
ian@0 5 Introduction
ian@0 6 ============
ian@0 7 The following is a random collection of documentation regarding
ian@0 8 network devices.
ian@0 9
ian@0 10 struct net_device allocation rules
ian@0 11 ==================================
ian@0 12 Network device structures need to persist even after module is unloaded and
ian@0 13 must be allocated with kmalloc. If device has registered successfully,
ian@0 14 it will be freed on last use by free_netdev. This is required to handle the
ian@0 15 pathologic case cleanly (example: rmmod mydriver </sys/class/net/myeth/mtu )
ian@0 16
ian@0 17 There are routines in net_init.c to handle the common cases of
ian@0 18 alloc_etherdev, alloc_netdev. These reserve extra space for driver
ian@0 19 private data which gets freed when the network device is freed. If
ian@0 20 separately allocated data is attached to the network device
ian@0 21 (dev->priv) then it is up to the module exit handler to free that.
ian@0 22
ian@0 23
ian@0 24 struct net_device synchronization rules
ian@0 25 =======================================
ian@0 26 dev->open:
ian@0 27 Synchronization: rtnl_lock() semaphore.
ian@0 28 Context: process
ian@0 29
ian@0 30 dev->stop:
ian@0 31 Synchronization: rtnl_lock() semaphore.
ian@0 32 Context: process
ian@0 33 Note1: netif_running() is guaranteed false
ian@0 34 Note2: dev->poll() is guaranteed to be stopped
ian@0 35
ian@0 36 dev->do_ioctl:
ian@0 37 Synchronization: rtnl_lock() semaphore.
ian@0 38 Context: process
ian@0 39
ian@0 40 dev->get_stats:
ian@0 41 Synchronization: dev_base_lock rwlock.
ian@0 42 Context: nominally process, but don't sleep inside an rwlock
ian@0 43
ian@0 44 dev->hard_start_xmit:
ian@0 45 Synchronization: netif_tx_lock spinlock.
ian@0 46 When the driver sets NETIF_F_LLTX in dev->features this will be
ian@0 47 called without holding netif_tx_lock. In this case the driver
ian@0 48 has to lock by itself when needed. It is recommended to use a try lock
ian@0 49 for this and return -1 when the spin lock fails.
ian@0 50 The locking there should also properly protect against
ian@0 51 set_multicast_list
ian@0 52 Context: BHs disabled
ian@0 53 Notes: netif_queue_stopped() is guaranteed false
ian@0 54 Interrupts must be enabled when calling hard_start_xmit.
ian@0 55 (Interrupts must also be enabled when enabling the BH handler.)
ian@0 56 Return codes:
ian@0 57 o NETDEV_TX_OK everything ok.
ian@0 58 o NETDEV_TX_BUSY Cannot transmit packet, try later
ian@0 59 Usually a bug, means queue start/stop flow control is broken in
ian@0 60 the driver. Note: the driver must NOT put the skb in its DMA ring.
ian@0 61 o NETDEV_TX_LOCKED Locking failed, please retry quickly.
ian@0 62 Only valid when NETIF_F_LLTX is set.
ian@0 63
ian@0 64 dev->tx_timeout:
ian@0 65 Synchronization: netif_tx_lock spinlock.
ian@0 66 Context: BHs disabled
ian@0 67 Notes: netif_queue_stopped() is guaranteed true
ian@0 68
ian@0 69 dev->set_multicast_list:
ian@0 70 Synchronization: netif_tx_lock spinlock.
ian@0 71 Context: BHs disabled
ian@0 72
ian@0 73 dev->poll:
ian@0 74 Synchronization: __LINK_STATE_RX_SCHED bit in dev->state. See
ian@0 75 dev_close code and comments in net/core/dev.c for more info.
ian@0 76 Context: softirq
ian@0 77