| 1 | |
| 2 |
|
| 3 | =====================
|
| 4 | Softnet Driver Issues
|
| 5 | =====================
|
| 6 |
|
| 7 | Probing guidelines
|
| 8 | ==================
|
| 9 |
|
| 10 | Address validation
|
| 11 | ------------------
|
| 12 |
|
| 13 | Any hardware layer address you obtain for your device should
|
| 14 | be verified. For example, for ethernet check it with
|
| 15 | linux/etherdevice.h:is_valid_ether_addr()
|
| 16 |
|
| 17 | Close/stop guidelines
|
| 18 | =====================
|
| 19 |
|
| 20 | Quiescence
|
| 21 | ----------
|
| 22 |
|
| 23 | After the ndo_stop routine has been called, the hardware must
|
| 24 | not receive or transmit any data. All in flight packets must
|
| 25 | be aborted. If necessary, poll or wait for completion of
|
| 26 | any reset commands.
|
| 27 |
|
| 28 | Auto-close
|
| 29 | ----------
|
| 30 |
|
| 31 | The ndo_stop routine will be called by unregister_netdevice
|
| 32 | if device is still UP.
|
| 33 |
|
| 34 | Transmit path guidelines
|
| 35 | ========================
|
| 36 |
|
| 37 | Stop queues in advance
|
| 38 | ----------------------
|
| 39 |
|
| 40 | The ndo_start_xmit method must not return NETDEV_TX_BUSY under
|
| 41 | any normal circumstances. It is considered a hard error unless
|
| 42 | there is no way your device can tell ahead of time when its
|
| 43 | transmit function will become busy.
|
| 44 |
|
| 45 | Instead it must maintain the queue properly. For example,
|
| 46 | for a driver implementing scatter-gather this means:
|
| 47 |
|
| 48 | .. code-block:: c
|
| 49 |
|
| 50 | static u32 drv_tx_avail(struct drv_ring *dr)
|
| 51 | {
|
| 52 | u32 used = READ_ONCE(dr->prod) - READ_ONCE(dr->cons);
|
| 53 |
|
| 54 | return dr->tx_ring_size - (used & dr->tx_ring_mask);
|
| 55 | }
|
| 56 |
|
| 57 | static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb,
|
| 58 | struct net_device *dev)
|
| 59 | {
|
| 60 | struct drv *dp = netdev_priv(dev);
|
| 61 | struct netdev_queue *txq;
|
| 62 | struct drv_ring *dr;
|
| 63 | int idx;
|
| 64 |
|
| 65 | idx = skb_get_queue_mapping(skb);
|
| 66 | dr = dp->tx_rings[idx];
|
| 67 | txq = netdev_get_tx_queue(dev, idx);
|
| 68 |
|
| 69 | //...
|
| 70 | /* This should be a very rare race - log it. */
|
| 71 | if (drv_tx_avail(dr) <= skb_shinfo(skb)->nr_frags + 1) {
|
| 72 | netif_tx_stop_queue(txq);
|
| 73 | netdev_warn(dev, "Tx Ring full when queue awake!\n");
|
| 74 | return NETDEV_TX_BUSY;
|
| 75 | }
|
| 76 |
|
| 77 | //... queue packet to card ...
|
| 78 |
|
| 79 | netdev_tx_sent_queue(txq, skb->len);
|
| 80 |
|
| 81 | //... update tx producer index using WRITE_ONCE() ...
|
| 82 |
|
| 83 | if (!netif_txq_maybe_stop(txq, drv_tx_avail(dr),
|
| 84 | MAX_SKB_FRAGS + 1, 2 * MAX_SKB_FRAGS))
|
| 85 | dr->stats.stopped++;
|
| 86 |
|
| 87 | //...
|
| 88 | return NETDEV_TX_OK;
|
| 89 | }
|
| 90 |
|
| 91 | And then at the end of your TX reclamation event handling:
|
| 92 |
|
| 93 | .. code-block:: c
|
| 94 |
|
| 95 | //... update tx consumer index using WRITE_ONCE() ...
|
| 96 |
|
| 97 | netif_txq_completed_wake(txq, cmpl_pkts, cmpl_bytes,
|
| 98 | drv_tx_avail(dr), 2 * MAX_SKB_FRAGS);
|
| 99 |
|
| 100 | Lockless queue stop / wake helper macros
|
| 101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 102 |
|
| 103 | .. kernel-doc:: include/net/netdev_queues.h
|
| 104 | :doc: Lockless queue stopping / waking helpers.
|
| 105 |
|
| 106 | The standard macros like netif_txq_maybe_stop(), netif_txq_try_stop() etc.
|
| 107 | are well tested, prefer them over local synchronization schemes.
|
| 108 |
|
| 109 | No exclusive ownership
|
| 110 | ----------------------
|
| 111 |
|
| 112 | An ndo_start_xmit method must not modify the shared parts of a
|
| 113 | cloned SKB.
|
| 114 |
|
| 115 | Timely completions
|
| 116 | ------------------
|
| 117 |
|
| 118 | Do not forget that once you return NETDEV_TX_OK from your
|
| 119 | ndo_start_xmit method, it is your driver's responsibility to free
|
| 120 | up the SKB and in some finite amount of time.
|
| 121 |
|
| 122 | For example, this means that it is not allowed for your TX
|
| 123 | mitigation scheme to let TX packets "hang out" in the TX
|
| 124 | ring unreclaimed forever if no new TX packets are sent.
|
| 125 | This error can deadlock sockets waiting for send buffer room
|
| 126 | to be freed up.
|
| 127 |
|
| 128 | If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you
|
| 129 | must not keep any reference to that SKB and you must not attempt
|
| 130 | to free it up.
|
| 131 |
|
| 132 | Error message reporting
|
| 133 | =======================
|
| 134 |
|
| 135 | A number of driver configuration interfaces pass a Netlink extended ACK
|
| 136 | (``extack``) object to the driver (either directly as an argument or
|
| 137 | as a member of a parameter struct). The drivers should try to report
|
| 138 | most errors via the ``extack`` object. System level exceptions,
|
| 139 | indicating that system or device is misbehaving or is in bad state,
|
| 140 | should continue to be reported to system logs.
|
| 141 |
|
| 142 | Messages should be passed **either** via ``extack`` **or** to system logs.
|
| 143 | Drivers should not try to report the same information to both.
|