^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Network Devices, the Kernel, and You!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) The following is a random collection of documentation regarding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) network devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) struct net_device allocation rules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Network device structures need to persist even after module is unloaded and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) must be allocated with alloc_netdev_mqs() and friends.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) If device has registered successfully, it will be freed on last use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) by free_netdev(). This is required to handle the pathologic case cleanly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) (example: rmmod mydriver </sys/class/net/myeth/mtu )
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) alloc_netdev_mqs()/alloc_netdev() reserve extra space for driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) private data which gets freed when the network device is freed. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) separately allocated data is attached to the network device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) (netdev_priv(dev)) then it is up to the module exit handler to free that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) MTU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) ===
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Each network device has a Maximum Transfer Unit. The MTU does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) include any link layer protocol overhead. Upper layer protocols must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) not pass a socket buffer (skb) to a device to transmit with more data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) than the mtu. The MTU does not include link layer header overhead, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) for example on Ethernet if the standard MTU is 1500 bytes used, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) actual skb will contain up to 1514 bytes because of the Ethernet
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) header. Devices should allow for the 4 byte VLAN header as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Segmentation Offload (GSO, TSO) is an exception to this rule. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) upper layer protocol may pass a large socket buffer to the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) transmit routine, and the device will break that up into separate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) packets based on the current MTU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) MTU is symmetrical and applies both to receive and transmit. A device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) must be able to receive at least the maximum size packet allowed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) the MTU. A network device may use the MTU as mechanism to size receive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) buffers, but the device should allow packets with VLAN header. With
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) standard Ethernet mtu of 1500 bytes, the device should allow up to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 1518 byte packets (1500 + 14 header + 4 tag). The device may either:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) drop, truncate, or pass up oversize packets, but dropping oversize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) packets is preferred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) struct net_device synchronization rules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) ndo_open:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Synchronization: rtnl_lock() semaphore.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Context: process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ndo_stop:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Synchronization: rtnl_lock() semaphore.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Context: process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) Note: netif_running() is guaranteed false
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) ndo_do_ioctl:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) Synchronization: rtnl_lock() semaphore.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Context: process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ndo_get_stats:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) Synchronization: dev_base_lock rwlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Context: nominally process, but don't sleep inside an rwlock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) ndo_start_xmit:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) Synchronization: __netif_tx_lock spinlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) When the driver sets NETIF_F_LLTX in dev->features this will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) called without holding netif_tx_lock. In this case the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) has to lock by itself when needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) The locking there should also properly protect against
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) set_rx_mode. WARNING: use of NETIF_F_LLTX is deprecated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Don't use it for new drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) Context: Process with BHs disabled or BH (timer),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) will be called with interrupts disabled by netconsole.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Return codes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) * NETDEV_TX_OK everything ok.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) * NETDEV_TX_BUSY Cannot transmit packet, try later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Usually a bug, means queue start/stop flow control is broken in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) the driver. Note: the driver must NOT put the skb in its DMA ring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) ndo_tx_timeout:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) Synchronization: netif_tx_lock spinlock; all TX queues frozen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) Context: BHs disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Notes: netif_queue_stopped() is guaranteed true
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) ndo_set_rx_mode:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) Synchronization: netif_addr_lock spinlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Context: BHs disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) struct napi_struct synchronization rules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) napi->poll:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) Synchronization:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) NAPI_STATE_SCHED bit in napi->state. Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) driver's ndo_stop method will invoke napi_disable() on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) all NAPI instances which will do a sleeping poll on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) NAPI_STATE_SCHED napi->state bit, waiting for all pending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) NAPI activity to cease.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Context:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) softirq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) will be called with interrupts disabled by netconsole.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags
| Donate