1.. SPDX-License-Identifier: GPL-2.0 2 3===================================== 4Network Devices, the Kernel, and You! 5===================================== 6 7 8Introduction 9============ 10The following is a random collection of documentation regarding 11network devices. 12 13struct net_device lifetime rules 14================================ 15Network device structures need to persist even after module is unloaded and 16must be allocated with alloc_netdev_mqs() and friends. 17If device has registered successfully, it will be freed on last use 18by free_netdev(). This is required to handle the pathological case cleanly 19(example: ``rmmod mydriver </sys/class/net/myeth/mtu``) 20 21alloc_netdev_mqs() / alloc_netdev() reserve extra space for driver 22private data which gets freed when the network device is freed. If 23separately allocated data is attached to the network device 24(netdev_priv()) then it is up to the module exit handler to free that. 25 26There are two groups of APIs for registering struct net_device. 27First group can be used in normal contexts where ``rtnl_lock`` is not already 28held: register_netdev(), unregister_netdev(). 29Second group can be used when ``rtnl_lock`` is already held: 30register_netdevice(), unregister_netdevice(), free_netdevice(). 31 32Simple drivers 33-------------- 34 35Most drivers (especially device drivers) handle lifetime of struct net_device 36in context where ``rtnl_lock`` is not held (e.g. driver probe and remove paths). 37 38In that case the struct net_device registration is done using 39the register_netdev(), and unregister_netdev() functions: 40 41.. code-block:: c 42 43 int probe() 44 { 45 struct my_device_priv *priv; 46 int err; 47 48 dev = alloc_netdev_mqs(...); 49 if (!dev) 50 return -ENOMEM; 51 priv = netdev_priv(dev); 52 53 /* ... do all device setup before calling register_netdev() ... 54 */ 55 56 err = register_netdev(dev); 57 if (err) 58 goto err_undo; 59 60 /* net_device is visible to the user! */ 61 62 err_undo: 63 /* ... undo the device setup ... */ 64 free_netdev(dev); 65 return err; 66 } 67 68 void remove() 69 { 70 unregister_netdev(dev); 71 free_netdev(dev); 72 } 73 74Note that after calling register_netdev() the device is visible in the system. 75Users can open it and start sending / receiving traffic immediately, 76or run any other callback, so all initialization must be done prior to 77registration. 78 79unregister_netdev() closes the device and waits for all users to be done 80with it. The memory of struct net_device itself may still be referenced 81by sysfs but all operations on that device will fail. 82 83free_netdev() can be called after unregister_netdev() returns on when 84register_netdev() failed. 85 86Device management under RTNL 87---------------------------- 88 89Registering struct net_device while in context which already holds 90the ``rtnl_lock`` requires extra care. In those scenarios most drivers 91will want to make use of struct net_device's ``needs_free_netdev`` 92and ``priv_destructor`` members for freeing of state. 93 94Example flow of netdev handling under ``rtnl_lock``: 95 96.. code-block:: c 97 98 static void my_setup(struct net_device *dev) 99 { 100 dev->needs_free_netdev = true; 101 } 102 103 static void my_destructor(struct net_device *dev) 104 { 105 some_obj_destroy(priv->obj); 106 some_uninit(priv); 107 } 108 109 int create_link() 110 { 111 struct my_device_priv *priv; 112 int err; 113 114 ASSERT_RTNL(); 115 116 dev = alloc_netdev(sizeof(*priv), "net%d", NET_NAME_UNKNOWN, my_setup); 117 if (!dev) 118 return -ENOMEM; 119 priv = netdev_priv(dev); 120 121 /* Implicit constructor */ 122 err = some_init(priv); 123 if (err) 124 goto err_free_dev; 125 126 priv->obj = some_obj_create(); 127 if (!priv->obj) { 128 err = -ENOMEM; 129 goto err_some_uninit; 130 } 131 /* End of constructor, set the destructor: */ 132 dev->priv_destructor = my_destructor; 133 134 err = register_netdevice(dev); 135 if (err) 136 /* register_netdevice() calls destructor on failure */ 137 goto err_free_dev; 138 139 /* If anything fails now unregister_netdevice() (or unregister_netdev()) 140 * will take care of calling my_destructor and free_netdev(). 141 */ 142 143 return 0; 144 145 err_some_uninit: 146 some_uninit(priv); 147 err_free_dev: 148 free_netdev(dev); 149 return err; 150 } 151 152If struct net_device.priv_destructor is set it will be called by the core 153some time after unregister_netdevice(), it will also be called if 154register_netdevice() fails. The callback may be invoked with or without 155``rtnl_lock`` held. 156 157There is no explicit constructor callback, driver "constructs" the private 158netdev state after allocating it and before registration. 159 160Setting struct net_device.needs_free_netdev makes core call free_netdevice() 161automatically after unregister_netdevice() when all references to the device 162are gone. It only takes effect after a successful call to register_netdevice() 163so if register_netdevice() fails driver is responsible for calling 164free_netdev(). 165 166free_netdev() is safe to call on error paths right after unregister_netdevice() 167or when register_netdevice() fails. Parts of netdev (de)registration process 168happen after ``rtnl_lock`` is released, therefore in those cases free_netdev() 169will defer some of the processing until ``rtnl_lock`` is released. 170 171Devices spawned from struct rtnl_link_ops should never free the 172struct net_device directly. 173 174.ndo_init and .ndo_uninit 175~~~~~~~~~~~~~~~~~~~~~~~~~ 176 177``.ndo_init`` and ``.ndo_uninit`` callbacks are called during net_device 178registration and de-registration, under ``rtnl_lock``. Drivers can use 179those e.g. when parts of their init process need to run under ``rtnl_lock``. 180 181``.ndo_init`` runs before device is visible in the system, ``.ndo_uninit`` 182runs during de-registering after device is closed but other subsystems 183may still have outstanding references to the netdevice. 184 185MTU 186=== 187Each network device has a Maximum Transfer Unit. The MTU does not 188include any link layer protocol overhead. Upper layer protocols must 189not pass a socket buffer (skb) to a device to transmit with more data 190than the mtu. The MTU does not include link layer header overhead, so 191for example on Ethernet if the standard MTU is 1500 bytes used, the 192actual skb will contain up to 1514 bytes because of the Ethernet 193header. Devices should allow for the 4 byte VLAN header as well. 194 195Segmentation Offload (GSO, TSO) is an exception to this rule. The 196upper layer protocol may pass a large socket buffer to the device 197transmit routine, and the device will break that up into separate 198packets based on the current MTU. 199 200MTU is symmetrical and applies both to receive and transmit. A device 201must be able to receive at least the maximum size packet allowed by 202the MTU. A network device may use the MTU as mechanism to size receive 203buffers, but the device should allow packets with VLAN header. With 204standard Ethernet mtu of 1500 bytes, the device should allow up to 2051518 byte packets (1500 + 14 header + 4 tag). The device may either: 206drop, truncate, or pass up oversize packets, but dropping oversize 207packets is preferred. 208 209 210struct net_device synchronization rules 211======================================= 212ndo_open: 213 Synchronization: rtnl_lock() semaphore. 214 Context: process 215 216ndo_stop: 217 Synchronization: rtnl_lock() semaphore. 218 Context: process 219 Note: netif_running() is guaranteed false 220 221ndo_do_ioctl: 222 Synchronization: rtnl_lock() semaphore. 223 Context: process 224 225ndo_get_stats: 226 Synchronization: rtnl_lock() semaphore, dev_base_lock rwlock, or RCU. 227 Context: atomic (can't sleep under rwlock or RCU) 228 229ndo_start_xmit: 230 Synchronization: __netif_tx_lock spinlock. 231 232 When the driver sets NETIF_F_LLTX in dev->features this will be 233 called without holding netif_tx_lock. In this case the driver 234 has to lock by itself when needed. 235 The locking there should also properly protect against 236 set_rx_mode. WARNING: use of NETIF_F_LLTX is deprecated. 237 Don't use it for new drivers. 238 239 Context: Process with BHs disabled or BH (timer), 240 will be called with interrupts disabled by netconsole. 241 242 Return codes: 243 244 * NETDEV_TX_OK everything ok. 245 * NETDEV_TX_BUSY Cannot transmit packet, try later 246 Usually a bug, means queue start/stop flow control is broken in 247 the driver. Note: the driver must NOT put the skb in its DMA ring. 248 249ndo_tx_timeout: 250 Synchronization: netif_tx_lock spinlock; all TX queues frozen. 251 Context: BHs disabled 252 Notes: netif_queue_stopped() is guaranteed true 253 254ndo_set_rx_mode: 255 Synchronization: netif_addr_lock spinlock. 256 Context: BHs disabled 257 258struct napi_struct synchronization rules 259======================================== 260napi->poll: 261 Synchronization: 262 NAPI_STATE_SCHED bit in napi->state. Device 263 driver's ndo_stop method will invoke napi_disable() on 264 all NAPI instances which will do a sleeping poll on the 265 NAPI_STATE_SCHED napi->state bit, waiting for all pending 266 NAPI activity to cease. 267 268 Context: 269 softirq 270 will be called with interrupts disabled by netconsole. 271