Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | |
74d332c1 ED |
13 | must be allocated with alloc_netdev_mqs() and friends. |
14 | If device has registered successfully, it will be freed on last use | |
15 | by free_netdev(). This is required to handle the pathologic case cleanly | |
16 | (example: rmmod mydriver </sys/class/net/myeth/mtu ) | |
1da177e4 | 17 | |
74d332c1 | 18 | alloc_netdev_mqs()/alloc_netdev() reserve extra space for driver |
1da177e4 LT |
19 | private data which gets freed when the network device is freed. If |
20 | separately allocated data is attached to the network device | |
b74ca3a8 | 21 | (netdev_priv(dev)) then it is up to the module exit handler to free that. |
1da177e4 | 22 | |
1c8c7d64 SH |
23 | MTU |
24 | === | |
25 | Each network device has a Maximum Transfer Unit. The MTU does not | |
26 | include any link layer protocol overhead. Upper layer protocols must | |
27 | not pass a socket buffer (skb) to a device to transmit with more data | |
28 | than the mtu. The MTU does not include link layer header overhead, so | |
29 | for example on Ethernet if the standard MTU is 1500 bytes used, the | |
30 | actual skb will contain up to 1514 bytes because of the Ethernet | |
31 | header. Devices should allow for the 4 byte VLAN header as well. | |
32 | ||
33 | Segmentation Offload (GSO, TSO) is an exception to this rule. The | |
34 | upper layer protocol may pass a large socket buffer to the device | |
35 | transmit routine, and the device will break that up into separate | |
36 | packets based on the current MTU. | |
37 | ||
38 | MTU is symmetrical and applies both to receive and transmit. A device | |
39 | must be able to receive at least the maximum size packet allowed by | |
40 | the MTU. A network device may use the MTU as mechanism to size receive | |
41 | buffers, but the device should allow packets with VLAN header. With | |
42 | standard Ethernet mtu of 1500 bytes, the device should allow up to | |
43 | 1518 byte packets (1500 + 14 header + 4 tag). The device may either: | |
44 | drop, truncate, or pass up oversize packets, but dropping oversize | |
45 | packets is preferred. | |
46 | ||
47 | ||
1da177e4 LT |
48 | struct net_device synchronization rules |
49 | ======================================= | |
b3cf6545 | 50 | ndo_open: |
1da177e4 LT |
51 | Synchronization: rtnl_lock() semaphore. |
52 | Context: process | |
53 | ||
b3cf6545 | 54 | ndo_stop: |
1da177e4 LT |
55 | Synchronization: rtnl_lock() semaphore. |
56 | Context: process | |
93b6a3ad | 57 | Note: netif_running() is guaranteed false |
1da177e4 | 58 | |
b3cf6545 | 59 | ndo_do_ioctl: |
1da177e4 LT |
60 | Synchronization: rtnl_lock() semaphore. |
61 | Context: process | |
62 | ||
b3cf6545 | 63 | ndo_get_stats: |
1da177e4 LT |
64 | Synchronization: dev_base_lock rwlock. |
65 | Context: nominally process, but don't sleep inside an rwlock | |
66 | ||
b3cf6545 | 67 | ndo_start_xmit: |
04fd3d35 | 68 | Synchronization: __netif_tx_lock spinlock. |
17229333 | 69 | |
1da177e4 | 70 | When the driver sets NETIF_F_LLTX in dev->features this will be |
932ff279 | 71 | called without holding netif_tx_lock. In this case the driver |
1da177e4 | 72 | has to lock by itself when needed. It is recommended to use a try lock |
17229333 | 73 | for this and return NETDEV_TX_LOCKED when the spin lock fails. |
1da177e4 | 74 | The locking there should also properly protect against |
b81693d9 | 75 | set_rx_mode. Note that the use of NETIF_F_LLTX is deprecated. |
19f59460 | 76 | Don't use it for new drivers. |
17229333 SH |
77 | |
78 | Context: Process with BHs disabled or BH (timer), | |
79 | will be called with interrupts disabled by netconsole. | |
80 | ||
1da177e4 LT |
81 | Return codes: |
82 | o NETDEV_TX_OK everything ok. | |
83 | o NETDEV_TX_BUSY Cannot transmit packet, try later | |
84 | Usually a bug, means queue start/stop flow control is broken in | |
85 | the driver. Note: the driver must NOT put the skb in its DMA ring. | |
86 | o NETDEV_TX_LOCKED Locking failed, please retry quickly. | |
87 | Only valid when NETIF_F_LLTX is set. | |
88 | ||
b3cf6545 | 89 | ndo_tx_timeout: |
04fd3d35 | 90 | Synchronization: netif_tx_lock spinlock; all TX queues frozen. |
1da177e4 LT |
91 | Context: BHs disabled |
92 | Notes: netif_queue_stopped() is guaranteed true | |
93 | ||
b3cf6545 | 94 | ndo_set_rx_mode: |
04fd3d35 | 95 | Synchronization: netif_addr_lock spinlock. |
1da177e4 LT |
96 | Context: BHs disabled |
97 | ||
bea3348e SH |
98 | struct napi_struct synchronization rules |
99 | ======================================== | |
100 | napi->poll: | |
101 | Synchronization: NAPI_STATE_SCHED bit in napi->state. Device | |
b3cf6545 | 102 | driver's ndo_stop method will invoke napi_disable() on |
bea3348e SH |
103 | all NAPI instances which will do a sleeping poll on the |
104 | NAPI_STATE_SCHED napi->state bit, waiting for all pending | |
105 | NAPI activity to cease. | |
1da177e4 | 106 | Context: softirq |
17229333 | 107 | will be called with interrupts disabled by netconsole. |