0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =====================
0004 Softnet Driver Issues
0005 =====================
0006
0007 Transmit path guidelines:
0008
0009 1) The ndo_start_xmit method must not return NETDEV_TX_BUSY under
0010 any normal circumstances. It is considered a hard error unless
0011 there is no way your device can tell ahead of time when its
0012 transmit function will become busy.
0013
0014 Instead it must maintain the queue properly. For example,
0015 for a driver implementing scatter-gather this means::
0016
0017 static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb,
0018 struct net_device *dev)
0019 {
0020 struct drv *dp = netdev_priv(dev);
0021
0022 lock_tx(dp);
0023 ...
0024 /* This is a hard error log it. */
0025 if (TX_BUFFS_AVAIL(dp) <= (skb_shinfo(skb)->nr_frags + 1)) {
0026 netif_stop_queue(dev);
0027 unlock_tx(dp);
0028 printk(KERN_ERR PFX "%s: BUG! Tx Ring full when queue awake!\n",
0029 dev->name);
0030 return NETDEV_TX_BUSY;
0031 }
0032
0033 ... queue packet to card ...
0034 ... update tx consumer index ...
0035
0036 if (TX_BUFFS_AVAIL(dp) <= (MAX_SKB_FRAGS + 1))
0037 netif_stop_queue(dev);
0038
0039 ...
0040 unlock_tx(dp);
0041 ...
0042 return NETDEV_TX_OK;
0043 }
0044
0045 And then at the end of your TX reclamation event handling::
0046
0047 if (netif_queue_stopped(dp->dev) &&
0048 TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1))
0049 netif_wake_queue(dp->dev);
0050
0051 For a non-scatter-gather supporting card, the three tests simply become::
0052
0053 /* This is a hard error log it. */
0054 if (TX_BUFFS_AVAIL(dp) <= 0)
0055
0056 and::
0057
0058 if (TX_BUFFS_AVAIL(dp) == 0)
0059
0060 and::
0061
0062 if (netif_queue_stopped(dp->dev) &&
0063 TX_BUFFS_AVAIL(dp) > 0)
0064 netif_wake_queue(dp->dev);
0065
0066 2) An ndo_start_xmit method must not modify the shared parts of a
0067 cloned SKB.
0068
0069 3) Do not forget that once you return NETDEV_TX_OK from your
0070 ndo_start_xmit method, it is your driver's responsibility to free
0071 up the SKB and in some finite amount of time.
0072
0073 For example, this means that it is not allowed for your TX
0074 mitigation scheme to let TX packets "hang out" in the TX
0075 ring unreclaimed forever if no new TX packets are sent.
0076 This error can deadlock sockets waiting for send buffer room
0077 to be freed up.
0078
0079 If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you
0080 must not keep any reference to that SKB and you must not attempt
0081 to free it up.
0082
0083 Probing guidelines:
0084
0085 1) Any hardware layer address you obtain for your device should
0086 be verified. For example, for ethernet check it with
0087 linux/etherdevice.h:is_valid_ether_addr()
0088
0089 Close/stop guidelines:
0090
0091 1) After the ndo_stop routine has been called, the hardware must
0092 not receive or transmit any data. All in flight packets must
0093 be aborted. If necessary, poll or wait for completion of
0094 any reset commands.
0095
0096 2) The ndo_stop routine will be called by unregister_netdevice
0097 if device is still UP.
