fsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget)/translations/zh_CN/networking/netdevicesmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/zh_TW/networking/netdevicesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/it_IT/networking/netdevicesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ja_JP/networking/netdevicesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/ko_KR/networking/netdevicesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget)/translations/sp_SP/networking/netdevicesmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhC/var/lib/git/docbuild/linux/Documentation/networking/netdevices.rsthKubhsection)}(hhh](htitle)}(h%Network Devices, the Kernel, and You!h]h%Network Devices, the Kernel, and You!}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh paragraph)}(hPThe following is a random collection of documentation regarding network devices.h]hPThe following is a random collection of documentation regarding network devices.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(h struct net_device lifetime rulesh]h struct net_device lifetime rules}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hXINetwork device structures need to persist even after module is unloaded and must be allocated with alloc_netdev_mqs() and friends. If device has registered successfully, it will be freed on last use by free_netdev(). This is required to handle the pathological case cleanly (example: ``rmmod mydriver needs_free_netdev = true; } static void my_destructor(struct net_device *dev) { some_obj_destroy(priv->obj); some_uninit(priv); } int create_link() { struct my_device_priv *priv; int err; ASSERT_RTNL(); dev = alloc_netdev(sizeof(*priv), "net%d", NET_NAME_UNKNOWN, my_setup); if (!dev) return -ENOMEM; priv = netdev_priv(dev); /* Implicit constructor */ err = some_init(priv); if (err) goto err_free_dev; priv->obj = some_obj_create(); if (!priv->obj) { err = -ENOMEM; goto err_some_uninit; } /* End of constructor, set the destructor: */ dev->priv_destructor = my_destructor; err = register_netdevice(dev); if (err) /* register_netdevice() calls destructor on failure */ goto err_free_dev; /* If anything fails now unregister_netdevice() (or unregister_netdev()) * will take care of calling my_destructor and free_netdev(). */ return 0; err_some_uninit: some_uninit(priv); err_free_dev: free_netdev(dev); return err; }h]hX"static void my_setup(struct net_device *dev) { dev->needs_free_netdev = true; } static void my_destructor(struct net_device *dev) { some_obj_destroy(priv->obj); some_uninit(priv); } int create_link() { struct my_device_priv *priv; int err; ASSERT_RTNL(); dev = alloc_netdev(sizeof(*priv), "net%d", NET_NAME_UNKNOWN, my_setup); if (!dev) return -ENOMEM; priv = netdev_priv(dev); /* Implicit constructor */ err = some_init(priv); if (err) goto err_free_dev; priv->obj = some_obj_create(); if (!priv->obj) { err = -ENOMEM; goto err_some_uninit; } /* End of constructor, set the destructor: */ dev->priv_destructor = my_destructor; err = register_netdevice(dev); if (err) /* register_netdevice() calls destructor on failure */ goto err_free_dev; /* If anything fails now unregister_netdevice() (or unregister_netdev()) * will take care of calling my_destructor and free_netdev(). */ return 0; err_some_uninit: some_uninit(priv); err_free_dev: free_netdev(dev); return err; }}hj`sbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhK`hjhhubh)}(hIf struct net_device.priv_destructor is set it will be called by the core some time after unregister_netdevice(), it will also be called if register_netdevice() fails. The callback may be invoked with or without ``rtnl_lock`` held.h](hIf struct net_device.priv_destructor is set it will be called by the core some time after unregister_netdevice(), it will also be called if register_netdevice() fails. The callback may be invoked with or without }(hjohhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjoubh held.}(hjohhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThere is no explicit constructor callback, driver "constructs" the private netdev state after allocating it and before registration.h]hThere is no explicit constructor callback, driver “constructs” the private netdev state after allocating it and before registration.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX:Setting struct net_device.needs_free_netdev makes core call free_netdevice() automatically after unregister_netdevice() when all references to the device are gone. It only takes effect after a successful call to register_netdevice() so if register_netdevice() fails driver is responsible for calling free_netdev().h]hX:Setting struct net_device.needs_free_netdev makes core call free_netdevice() automatically after unregister_netdevice() when all references to the device are gone. It only takes effect after a successful call to register_netdevice() so if register_netdevice() fails driver is responsible for calling free_netdev().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX.free_netdev() is safe to call on error paths right after unregister_netdevice() or when register_netdevice() fails. Parts of netdev (de)registration process happen after ``rtnl_lock`` is released, therefore in those cases free_netdev() will defer some of the processing until ``rtnl_lock`` is released.h](hfree_netdev() is safe to call on error paths right after unregister_netdevice() or when register_netdevice() fails. Parts of netdev (de)registration process happen after }(hjhhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh] is released, therefore in those cases free_netdev() will defer some of the processing until }(hjhhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh is released.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h[Devices spawned from struct rtnl_link_ops should never free the struct net_device directly.h]h[Devices spawned from struct rtnl_link_ops should never free the struct net_device directly.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(h.ndo_init and .ndo_uninith]h.ndo_init and .ndo_uninit}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h``.ndo_init`` and ``.ndo_uninit`` callbacks are called during net_device registration and de-registration, under ``rtnl_lock``. Drivers can use those e.g. when parts of their init process need to run under ``rtnl_lock``.h](j )}(h ``.ndo_init``h]h .ndo_init}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh and }(hjhhhNhNubj )}(h``.ndo_uninit``h]h .ndo_uninit}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubhP callbacks are called during net_device registration and de-registration, under }(hjhhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubhP. Drivers can use those e.g. when parts of their init process need to run under }(hjhhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h``.ndo_init`` runs before device is visible in the system, ``.ndo_uninit`` runs during de-registering after device is closed but other subsystems may still have outstanding references to the netdevice.h](j )}(h ``.ndo_init``h]h .ndo_init}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjNubh. runs before device is visible in the system, }(hjNhhhNhNubj )}(h``.ndo_uninit``h]h .ndo_uninit}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjNubh runs during de-registering after device is closed but other subsystems may still have outstanding references to the netdevice.}(hjNhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]ndo-init-and-ndo-uninitah ]h"].ndo_init and .ndo_uninitah$]h&]uh1hhjhhhhhKubeh}(h]device-management-under-rtnlah ]h"]device management under rtnlah$]h&]uh1hhhhhhhhKWubeh}(h] struct-net-device-lifetime-rulesah ]h"] struct net_device lifetime rulesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hMTUh]hMTU}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXEach network device has a Maximum Transfer Unit. The MTU does not include any link layer protocol overhead. Upper layer protocols must not pass a socket buffer (skb) to a device to transmit with more data than the mtu. The MTU does not include link layer header overhead, so for example on Ethernet if the standard MTU is 1500 bytes used, the actual skb will contain up to 1514 bytes because of the Ethernet header. Devices should allow for the 4 byte VLAN header as well.h]hXEach network device has a Maximum Transfer Unit. The MTU does not include any link layer protocol overhead. Upper layer protocols must not pass a socket buffer (skb) to a device to transmit with more data than the mtu. The MTU does not include link layer header overhead, so for example on Ethernet if the standard MTU is 1500 bytes used, the actual skb will contain up to 1514 bytes because of the Ethernet header. Devices should allow for the 4 byte VLAN header as well.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hSegmentation Offload (GSO, TSO) is an exception to this rule. The upper layer protocol may pass a large socket buffer to the device transmit routine, and the device will break that up into separate packets based on the current MTU.h]hSegmentation Offload (GSO, TSO) is an exception to this rule. The upper layer protocol may pass a large socket buffer to the device transmit routine, and the device will break that up into separate packets based on the current MTU.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXMTU is symmetrical and applies both to receive and transmit. A device must be able to receive at least the maximum size packet allowed by the MTU. A network device may use the MTU as mechanism to size receive buffers, but the device should allow packets with VLAN header. With standard Ethernet mtu of 1500 bytes, the device should allow up to 1518 byte packets (1500 + 14 header + 4 tag). The device may either: drop, truncate, or pass up oversize packets, but dropping oversize packets is preferred.h]hXMTU is symmetrical and applies both to receive and transmit. A device must be able to receive at least the maximum size packet allowed by the MTU. A network device may use the MTU as mechanism to size receive buffers, but the device should allow packets with VLAN header. With standard Ethernet mtu of 1500 bytes, the device should allow up to 1518 byte packets (1500 + 14 header + 4 tag). The device may either: drop, truncate, or pass up oversize packets, but dropping oversize packets is preferred.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]mtuah ]h"]mtuah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h'struct net_device synchronization rulesh]h'struct net_device synchronization rules}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubhdefinition_list)}(hhh](hdefinition_list_item)}(hndo_open: Synchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process h](hterm)}(h ndo_open:h]h ndo_open:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubh definition)}(hhh]h)}(hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: processh]hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hndo_stop: Synchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process Note: netif_running() is guaranteed false h](j)}(h ndo_stop:h]h ndo_stop:}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj"ubj)}(hhh]h)}(hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process Note: netif_running() is guaranteed falseh]hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process Note: netif_running() is guaranteed false}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj4ubah}(h]h ]h"]h$]h&]uh1jhj"ubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hndo_do_ioctl: Synchronization: rtnl_lock() semaphore. This is only called by network subsystems internally, not by user space calling ioctl as it was in before linux-5.14. h](j)}(h ndo_do_ioctl:h]h ndo_do_ioctl:}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjQubj)}(hhh](h)}(h'Synchronization: rtnl_lock() semaphore.h]h'Synchronization: rtnl_lock() semaphore.}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjcubh)}(huThis is only called by network subsystems internally, not by user space calling ioctl as it was in before linux-5.14.h]huThis is only called by network subsystems internally, not by user space calling ioctl as it was in before linux-5.14.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjcubeh}(h]h ]h"]h$]h&]uh1jhjQubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hndo_siocbond: Synchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process Used by the bonding driver for the SIOCBOND family of ioctl commands. h](j)}(h ndo_siocbond:h]h ndo_siocbond:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh](h)}(hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: processh]hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hEUsed by the bonding driver for the SIOCBOND family of ioctl commands.h]hEUsed by the bonding driver for the SIOCBOND family of ioctl commands.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hX ndo_siocwandev: Synchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process Used by the drivers/net/wan framework to handle the SIOCWANDEV ioctl with the if_settings structure. h](j)}(hndo_siocwandev:h]hndo_siocwandev:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh](h)}(hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: processh]hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hdUsed by the drivers/net/wan framework to handle the SIOCWANDEV ioctl with the if_settings structure.h]hdUsed by the drivers/net/wan framework to handle the SIOCWANDEV ioctl with the if_settings structure.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hXndo_siocdevprivate: Synchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process This is used to implement SIOCDEVPRIVATE ioctl helpers. These should not be added to new drivers, so don't use. h](j)}(hndo_siocdevprivate:h]hndo_siocdevprivate:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh](h)}(hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: processh]hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hoThis is used to implement SIOCDEVPRIVATE ioctl helpers. These should not be added to new drivers, so don't use.h]hqThis is used to implement SIOCDEVPRIVATE ioctl helpers. These should not be added to new drivers, so don’t use.}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hndo_eth_ioctl: Synchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process h](j)}(hndo_eth_ioctl:h]hndo_eth_ioctl:}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjEubj)}(hhh]h)}(hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: processh]hSynchronization: rtnl_lock() semaphore. In addition, netdev instance lock if the driver implements queue management or shaper API. Context: process}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWubah}(h]h ]h"]h$]h&]uh1jhjEubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hndo_get_stats: Synchronization: RCU (can be called concurrently with the stats update path). Context: atomic (can't sleep under RCU) h](j)}(hndo_get_stats:h]hndo_get_stats:}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjtubj)}(hhh]h)}(huSynchronization: RCU (can be called concurrently with the stats update path). Context: atomic (can't sleep under RCU)h]hwSynchronization: RCU (can be called concurrently with the stats update path). Context: atomic (can’t sleep under RCU)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjtubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hXndo_start_xmit: Synchronization: __netif_tx_lock spinlock. When the driver sets dev->lltx this will be called without holding netif_tx_lock. In this case the driver has to lock by itself when needed. The locking there should also properly protect against set_rx_mode. WARNING: use of dev->lltx is deprecated. Don't use it for new drivers. Context: Process with BHs disabled or BH (timer), will be called with interrupts disabled by netconsole. Return codes: * NETDEV_TX_OK everything ok. * NETDEV_TX_BUSY Cannot transmit packet, try later Usually a bug, means queue start/stop flow control is broken in the driver. Note: the driver must NOT put the skb in its DMA ring. h](j)}(hndo_start_xmit:h]hndo_start_xmit:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hhh](h)}(h*Synchronization: __netif_tx_lock spinlock.h]h*Synchronization: __netif_tx_lock spinlock.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubh)}(hXWhen the driver sets dev->lltx this will be called without holding netif_tx_lock. In this case the driver has to lock by itself when needed. The locking there should also properly protect against set_rx_mode. WARNING: use of dev->lltx is deprecated. Don't use it for new drivers.h]hXWhen the driver sets dev->lltx this will be called without holding netif_tx_lock. In this case the driver has to lock by itself when needed. The locking there should also properly protect against set_rx_mode. WARNING: use of dev->lltx is deprecated. Don’t use it for new drivers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubj)}(hhh]j)}(hiContext: Process with BHs disabled or BH (timer), will be called with interrupts disabled by netconsole. h](j)}(h1Context: Process with BHs disabled or BH (timer),h]h1Context: Process with BHs disabled or BH (timer),}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hhh]h)}(h6will be called with interrupts disabled by netconsole.h]h6will be called with interrupts disabled by netconsole.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubh)}(h Return codes:h]h Return codes:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh bullet_list)}(hhh](h list_item)}(hNETDEV_TX_OK everything ok.h]h)}(hj#h]hNETDEV_TX_OK everything ok.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj!ubah}(h]h ]h"]h$]h&]uh1jhjubj )}(hNETDEV_TX_BUSY Cannot transmit packet, try later Usually a bug, means queue start/stop flow control is broken in the driver. Note: the driver must NOT put the skb in its DMA ring. h]h)}(hNETDEV_TX_BUSY Cannot transmit packet, try later Usually a bug, means queue start/stop flow control is broken in the driver. Note: the driver must NOT put the skb in its DMA ring.h]hNETDEV_TX_BUSY Cannot transmit packet, try later Usually a bug, means queue start/stop flow control is broken in the driver. Note: the driver must NOT put the skb in its DMA ring.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj8ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet*uh1jhhhMhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hndo_tx_timeout: Synchronization: netif_tx_lock spinlock; all TX queues frozen. Context: BHs disabled Notes: netif_queue_stopped() is guaranteed true h](j)}(hndo_tx_timeout:h]hndo_tx_timeout:}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjdubj)}(hhh]h)}(hSynchronization: netif_tx_lock spinlock; all TX queues frozen. Context: BHs disabled Notes: netif_queue_stopped() is guaranteed trueh]hSynchronization: netif_tx_lock spinlock; all TX queues frozen. Context: BHs disabled Notes: netif_queue_stopped() is guaranteed true}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjvubah}(h]h ]h"]h$]h&]uh1jhjdubeh}(h]h ]h"]h$]h&]uh1jhhhMhjhhubj)}(hRndo_set_rx_mode: Synchronization: netif_addr_lock spinlock. Context: BHs disabled h](j)}(hndo_set_rx_mode:h]hndo_set_rx_mode:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM#hjubj)}(hhh]h)}(h@Synchronization: netif_addr_lock spinlock. Context: BHs disabledh]h@Synchronization: netif_addr_lock spinlock. Context: BHs disabled}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM#hjhhubj)}(hXndo_setup_tc: ``TC_SETUP_BLOCK`` and ``TC_SETUP_FT`` are running under NFT locks (i.e. no ``rtnl_lock`` and no device instance lock). The rest of ``tc_setup_type`` types run under netdev instance lock if the driver implements queue management or shaper API. h](j)}(h ndo_setup_tc:h]h ndo_setup_tc:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM)hjubj)}(hhh]h)}(h``TC_SETUP_BLOCK`` and ``TC_SETUP_FT`` are running under NFT locks (i.e. no ``rtnl_lock`` and no device instance lock). The rest of ``tc_setup_type`` types run under netdev instance lock if the driver implements queue management or shaper API.h](j )}(h``TC_SETUP_BLOCK``h]hTC_SETUP_BLOCK}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh and }(hjhhhNhNubj )}(h``TC_SETUP_FT``h]h TC_SETUP_FT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh& are running under NFT locks (i.e. no }(hjhhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh+ and no device instance lock). The rest of }(hjhhhNhNubj )}(h``tc_setup_type``h]h tc_setup_type}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh^ types run under netdev instance lock if the driver implements queue management or shaper API.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM&hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM)hjhhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubh)}(hMost ndo callbacks not specified in the list above are running under ``rtnl_lock``. In addition, netdev instance lock is taken as well if the driver implements queue management or shaper API.h](hEMost ndo callbacks not specified in the list above are running under }(hj;hhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1j hj;ubhm. In addition, netdev instance lock is taken as well if the driver implements queue management or shaper API.}(hj;hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM+hjhhubeh}(h]'struct-net-device-synchronization-rulesah ]h"]'struct net_device synchronization rulesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h(struct napi_struct synchronization rulesh]h(struct napi_struct synchronization rules}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjchhhhhM0ubj)}(hhh]j)}(hXnapi->poll: Synchronization: NAPI_STATE_SCHED bit in napi->state. Device driver's ndo_stop method will invoke napi_disable() on all NAPI instances which will do a sleeping poll on the NAPI_STATE_SCHED napi->state bit, waiting for all pending NAPI activity to cease. Context: softirq will be called with interrupts disabled by netconsole. h](j)}(h napi->poll:h]h napi->poll:}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM;hjwubj)}(hhh]j)}(hhh](j)}(hSynchronization: NAPI_STATE_SCHED bit in napi->state. Device driver's ndo_stop method will invoke napi_disable() on all NAPI instances which will do a sleeping poll on the NAPI_STATE_SCHED napi->state bit, waiting for all pending NAPI activity to cease. h](j)}(hSynchronization:h]hSynchronization:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM7hjubj)}(hhh]h)}(hNAPI_STATE_SCHED bit in napi->state. Device driver's ndo_stop method will invoke napi_disable() on all NAPI instances which will do a sleeping poll on the NAPI_STATE_SCHED napi->state bit, waiting for all pending NAPI activity to cease.h]hNAPI_STATE_SCHED bit in napi->state. Device driver’s ndo_stop method will invoke napi_disable() on all NAPI instances which will do a sleeping poll on the NAPI_STATE_SCHED napi->state bit, waiting for all pending NAPI activity to cease.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM7hjubj)}(hHContext: softirq will be called with interrupts disabled by netconsole. h](j)}(hContext:h]hContext:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM;hjubj)}(hhh]h)}(h>softirq will be called with interrupts disabled by netconsole.h]h>softirq will be called with interrupts disabled by netconsole.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM;hjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjwubeh}(h]h ]h"]h$]h&]uh1jhhhM;hjtubah}(h]h ]h"]h$]h&]uh1jhjchhhNhNubeh}(h](struct-napi-struct-synchronization-rulesah ]h"](struct napi_struct synchronization rulesah$]h&]uh1hhhhhhhhM0ubh)}(hhh](h)}(h2struct netdev_queue_mgmt_ops synchronization rulesh]h2struct netdev_queue_mgmt_ops synchronization rules}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM>ubh)}(hDAll queue management ndo callbacks are holding netdev instance lock.h]hDAll queue management ndo callbacks are holding netdev instance lock.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hj hhubeh}(h]2struct-netdev-queue-mgmt-ops-synchronization-rulesah ]h"]2struct netdev_queue_mgmt_ops synchronization rulesah$]h&]uh1hhhhhhhhM>ubh)}(hhh](h)}(hRTNL and netdev instance lockh]hRTNL and netdev instance lock}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj4hhhhhMCubh)}(hX3Historically, all networking control operations were protected by a single global lock known as ``rtnl_lock``. There is an ongoing effort to replace this global lock with separate locks for each network namespace. Additionally, properties of individual netdev are increasingly protected by per-netdev locks.h](h`Historically, all networking control operations were protected by a single global lock known as }(hjEhhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjEubh. There is an ongoing effort to replace this global lock with separate locks for each network namespace. Additionally, properties of individual netdev are increasingly protected by per-netdev locks.}(hjEhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMEhj4hhubh)}(hXFor device drivers that implement shaping or queue management APIs, all control operations will be performed under the netdev instance lock. Currently, this instance lock is acquired within the context of ``rtnl_lock``. The drivers can also explicitly request instance lock to be acquired via ``request_ops_lock``. In the future, there will be an option for individual drivers to opt out of using ``rtnl_lock`` and instead perform their control operations directly under the netdev instance lock.h](hFor device drivers that implement shaping or queue management APIs, all control operations will be performed under the netdev instance lock. Currently, this instance lock is acquired within the context of }(hjehhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjeubhK. The drivers can also explicitly request instance lock to be acquired via }(hjehhhNhNubj )}(h``request_ops_lock``h]hrequest_ops_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjeubhT. In the future, there will be an option for individual drivers to opt out of using }(hjehhhNhNubj )}(h ``rtnl_lock``h]h rtnl_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjeubhV and instead perform their control operations directly under the netdev instance lock.}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMJhj4hhubh)}(hKDevices drivers are encouraged to rely on the instance lock where possible.h]hKDevices drivers are encouraged to rely on the instance lock where possible.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhj4hhubh)}(hXFor the (mostly software) drivers that need to interact with the core stack, there are two sets of interfaces: ``dev_xxx``/``netdev_xxx`` and ``netif_xxx`` (e.g., ``dev_set_mtu`` and ``netif_set_mtu``). The ``dev_xxx``/``netdev_xxx`` functions handle acquiring the instance lock themselves, while the ``netif_xxx`` functions assume that the driver has already acquired the instance lock.h](hoFor the (mostly software) drivers that need to interact with the core stack, there are two sets of interfaces: }(hjhhhNhNubj )}(h ``dev_xxx``h]hdev_xxx}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh/}(hjhhhNhNubj )}(h``netdev_xxx``h]h netdev_xxx}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh and }(hjhhhNhNubj )}(h ``netif_xxx``h]h netif_xxx}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh (e.g., }(hjhhhNhNubj )}(h``dev_set_mtu``h]h dev_set_mtu}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh and }hjsbj )}(h``netif_set_mtu``h]h netif_set_mtu}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh). The }(hjhhhNhNubj )}(h ``dev_xxx``h]hdev_xxx}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh/}hjsbj )}(h``netdev_xxx``h]h netdev_xxx}(hj+ hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubhD functions handle acquiring the instance lock themselves, while the }(hjhhhNhNubj )}(h ``netif_xxx``h]h netif_xxx}(hj= hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubhI functions assume that the driver has already acquired the instance lock.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMThj4hhubeh}(h]rtnl-and-netdev-instance-lockah ]h"]rtnl and netdev instance lockah$]h&]uh1hhhhhhhhMCubh)}(hhh](h)}(h"Notifiers and netdev instance lockh]h"Notifiers and netdev instance lock}(hj` hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj] hhhhhM\ubh)}(hFor device drivers that implement shaping or queue management APIs, some of the notifiers (``enum netdev_cmd``) are running under the netdev instance lock.h](h[For device drivers that implement shaping or queue management APIs, some of the notifiers (}(hjn hhhNhNubj )}(h``enum netdev_cmd``h]henum netdev_cmd}(hjv hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjn ubh-) are running under the netdev instance lock.}(hjn hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM^hj] hhubh)}(hFor devices with locked ops, currently only the following notifiers are running under the lock: * ``NETDEV_REGISTER`` * ``NETDEV_UP`` * ``NETDEV_CHANGE``h](hbFor devices with locked ops, currently only the following notifiers are running under the lock: * }(hj hhhNhNubj )}(h``NETDEV_REGISTER``h]hNETDEV_REGISTER}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh * }(hj hhhNhNubj )}(h ``NETDEV_UP``h]h NETDEV_UP}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh * }hj sbj )}(h``NETDEV_CHANGE``h]h NETDEV_CHANGE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1hhhhMbhj] hhubh)}(hMThe following notifiers are running without the lock: * ``NETDEV_UNREGISTER``h](h8The following notifiers are running without the lock: * }(hj hhhNhNubj )}(h``NETDEV_UNREGISTER``h]hNETDEV_UNREGISTER}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1hhhhMhhj] hhubh)}(hXThere are no clear expectations for the remaining notifiers. Notifiers not on the list may run with or without the instance lock, potentially even invoking the same notifier type with and without the lock from different code paths. The goal is to eventually ensure that all (or most, with a few documented exceptions) notifiers run under the instance lock. Please extend this documentation whenever you make explicit assumption about lock being held from a notifier.h]hXThere are no clear expectations for the remaining notifiers. Notifiers not on the list may run with or without the instance lock, potentially even invoking the same notifier type with and without the lock from different code paths. The goal is to eventually ensure that all (or most, with a few documented exceptions) notifiers run under the instance lock. Please extend this documentation whenever you make explicit assumption about lock being held from a notifier.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMkhj] hhubeh}(h]"notifiers-and-netdev-instance-lockah ]h"]"notifiers and netdev instance lockah$]h&]uh1hhhhhhhhM\ubh)}(hhh](h)}(h NETDEV_INTERNAL symbol namespaceh]h NETDEV_INTERNAL symbol namespace}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMtubh)}(hXSymbols exported as NETDEV_INTERNAL can only be used in networking core and drivers which exclusively flow via the main networking list and trees. Note that the inverse is not true, most symbols outside of NETDEV_INTERNAL are not expected to be used by random code outside netdev either. Symbols may lack the designation because they predate the namespaces, or simply due to an oversight.h]hXSymbols exported as NETDEV_INTERNAL can only be used in networking core and drivers which exclusively flow via the main networking list and trees. Note that the inverse is not true, most symbols outside of NETDEV_INTERNAL are not expected to be used by random code outside netdev either. Symbols may lack the designation because they predate the namespaces, or simply due to an oversight.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMvhj hhubeh}(h] netdev-internal-symbol-namespaceah ]h"] netdev_internal symbol namespaceah$]h&]uh1hhhhhhhhMtubeh}(h]"network-devices-the-kernel-and-youah ]h"]%network devices, the kernel, and you!ah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjR error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j, j) hhjjjjjjjj~jjj`j]j jj1j.jZ jW j j j$ j! u nametypes}(j, hjjjjjj`j j1jZ j j$ uh}(j) hhhjhjjejjj~jjjj]jjjcj.j jW j4j j] j! j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.