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