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 |
f0cdf76c FW |
72 | has to lock by itself when needed. |
73 | The locking there should also properly protect against | |
74 | set_rx_mode. WARNING: use of NETIF_F_LLTX is deprecated. | |
19f59460 | 75 | Don't use it for new drivers. |
17229333 SH |
76 | |
77 | Context: Process with BHs disabled or BH (timer), | |
78 | will be called with interrupts disabled by netconsole. | |
79 | ||
1da177e4 LT |
80 | Return codes: |
81 | o NETDEV_TX_OK everything ok. | |
82 | o NETDEV_TX_BUSY Cannot transmit packet, try later | |
83 | Usually a bug, means queue start/stop flow control is broken in | |
84 | the driver. Note: the driver must NOT put the skb in its DMA ring. | |
1da177e4 | 85 | |
b3cf6545 | 86 | ndo_tx_timeout: |
04fd3d35 | 87 | Synchronization: netif_tx_lock spinlock; all TX queues frozen. |
1da177e4 LT |
88 | Context: BHs disabled |
89 | Notes: netif_queue_stopped() is guaranteed true | |
90 | ||
b3cf6545 | 91 | ndo_set_rx_mode: |
04fd3d35 | 92 | Synchronization: netif_addr_lock spinlock. |
1da177e4 LT |
93 | Context: BHs disabled |
94 | ||
bea3348e SH |
95 | struct napi_struct synchronization rules |
96 | ======================================== | |
97 | napi->poll: | |
98 | Synchronization: NAPI_STATE_SCHED bit in napi->state. Device | |
b3cf6545 | 99 | driver's ndo_stop method will invoke napi_disable() on |
bea3348e SH |
100 | all NAPI instances which will do a sleeping poll on the |
101 | NAPI_STATE_SCHED napi->state bit, waiting for all pending | |
102 | NAPI activity to cease. | |
1da177e4 | 103 | Context: softirq |
17229333 | 104 | will be called with interrupts disabled by netconsole. |