Commit | Line | Data |
---|---|---|
28d23311 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ===================== | |
4 | Softnet Driver Issues | |
5 | ===================== | |
1da177e4 | 6 | |
da4f0f82 JK |
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 | ||
d2f5c68e JK |
34 | Transmit path guidelines |
35 | ======================== | |
1da177e4 | 36 | |
d2f5c68e JK |
37 | Stop queues in advance |
38 | ---------------------- | |
1da177e4 | 39 | |
d2f5c68e JK |
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, | |
83364625 JK |
46 | for a driver implementing scatter-gather this means: |
47 | ||
48 | .. code-block:: c | |
1da177e4 | 49 | |
50762d9a JK |
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 & bp->tx_ring_mask); | |
55 | } | |
56 | ||
e34fac1c BH |
57 | static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb, |
58 | struct net_device *dev) | |
1da177e4 | 59 | { |
b74ca3a8 | 60 | struct drv *dp = netdev_priv(dev); |
50762d9a JK |
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); | |
1da177e4 | 68 | |
83364625 | 69 | //... |
50762d9a JK |
70 | /* This should be a very rare race - log it. */ |
71 | if (drv_tx_avail(dr) <= skb_shinfo(skb)->nr_frags + 1) { | |
1da177e4 | 72 | netif_stop_queue(dev); |
50762d9a | 73 | netdev_warn(dev, "Tx Ring full when queue awake!\n"); |
e34fac1c | 74 | return NETDEV_TX_BUSY; |
1da177e4 LT |
75 | } |
76 | ||
83364625 | 77 | //... queue packet to card ... |
1da177e4 | 78 | |
50762d9a JK |
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++; | |
1da177e4 | 86 | |
83364625 | 87 | //... |
e34fac1c | 88 | return NETDEV_TX_OK; |
1da177e4 LT |
89 | } |
90 | ||
83364625 JK |
91 | And then at the end of your TX reclamation event handling: |
92 | ||
93 | .. code-block:: c | |
1da177e4 | 94 | |
50762d9a | 95 | //... update tx consumer index using WRITE_ONCE() ... |
1da177e4 | 96 | |
50762d9a JK |
97 | netif_txq_completed_wake(txq, cmpl_pkts, cmpl_bytes, |
98 | drv_tx_avail(dr), 2 * MAX_SKB_FRAGS); | |
1da177e4 | 99 | |
c91c46de JK |
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 | ||
d2f5c68e JK |
106 | No exclusive ownership |
107 | ---------------------- | |
108 | ||
109 | An ndo_start_xmit method must not modify the shared parts of a | |
110 | cloned SKB. | |
111 | ||
112 | Timely completions | |
113 | ------------------ | |
114 | ||
115 | Do not forget that once you return NETDEV_TX_OK from your | |
116 | ndo_start_xmit method, it is your driver's responsibility to free | |
117 | up the SKB and in some finite amount of time. | |
ce3ba139 | 118 | |
d2f5c68e JK |
119 | For example, this means that it is not allowed for your TX |
120 | mitigation scheme to let TX packets "hang out" in the TX | |
121 | ring unreclaimed forever if no new TX packets are sent. | |
122 | This error can deadlock sockets waiting for send buffer room | |
123 | to be freed up. | |
1da177e4 | 124 | |
d2f5c68e JK |
125 | If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you |
126 | must not keep any reference to that SKB and you must not attempt | |
127 | to free it up. |