Commit | Line | Data |
---|---|---|
28d23311 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ===================== | |
4 | Softnet Driver Issues | |
5 | ===================== | |
1da177e4 LT |
6 | |
7 | Transmit path guidelines: | |
8 | ||
e34fac1c BH |
9 | 1) The ndo_start_xmit method must not return NETDEV_TX_BUSY under |
10 | any normal circumstances. It is considered a hard error unless | |
1da177e4 LT |
11 | there is no way your device can tell ahead of time when it's |
12 | transmit function will become busy. | |
13 | ||
14 | Instead it must maintain the queue properly. For example, | |
28d23311 | 15 | for a driver implementing scatter-gather this means:: |
1da177e4 | 16 | |
e34fac1c BH |
17 | static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb, |
18 | struct net_device *dev) | |
1da177e4 | 19 | { |
b74ca3a8 | 20 | struct drv *dp = netdev_priv(dev); |
1da177e4 LT |
21 | |
22 | lock_tx(dp); | |
23 | ... | |
24 | /* This is a hard error log it. */ | |
25 | if (TX_BUFFS_AVAIL(dp) <= (skb_shinfo(skb)->nr_frags + 1)) { | |
26 | netif_stop_queue(dev); | |
27 | unlock_tx(dp); | |
28 | printk(KERN_ERR PFX "%s: BUG! Tx Ring full when queue awake!\n", | |
29 | dev->name); | |
e34fac1c | 30 | return NETDEV_TX_BUSY; |
1da177e4 LT |
31 | } |
32 | ||
33 | ... queue packet to card ... | |
34 | ... update tx consumer index ... | |
35 | ||
36 | if (TX_BUFFS_AVAIL(dp) <= (MAX_SKB_FRAGS + 1)) | |
37 | netif_stop_queue(dev); | |
38 | ||
39 | ... | |
40 | unlock_tx(dp); | |
41 | ... | |
e34fac1c | 42 | return NETDEV_TX_OK; |
1da177e4 LT |
43 | } |
44 | ||
28d23311 | 45 | And then at the end of your TX reclamation event handling:: |
1da177e4 LT |
46 | |
47 | if (netif_queue_stopped(dp->dev) && | |
28d23311 | 48 | TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1)) |
1da177e4 LT |
49 | netif_wake_queue(dp->dev); |
50 | ||
28d23311 | 51 | For a non-scatter-gather supporting card, the three tests simply become:: |
1da177e4 LT |
52 | |
53 | /* This is a hard error log it. */ | |
54 | if (TX_BUFFS_AVAIL(dp) <= 0) | |
55 | ||
28d23311 | 56 | and:: |
1da177e4 LT |
57 | |
58 | if (TX_BUFFS_AVAIL(dp) == 0) | |
59 | ||
28d23311 | 60 | and:: |
1da177e4 LT |
61 | |
62 | if (netif_queue_stopped(dp->dev) && | |
28d23311 | 63 | TX_BUFFS_AVAIL(dp) > 0) |
1da177e4 LT |
64 | netif_wake_queue(dp->dev); |
65 | ||
de7aca16 | 66 | 2) An ndo_start_xmit method must not modify the shared parts of a |
ce3ba139 ML |
67 | cloned SKB. |
68 | ||
e34fac1c BH |
69 | 3) Do not forget that once you return NETDEV_TX_OK from your |
70 | ndo_start_xmit method, it is your driver's responsibility to free | |
71 | up the SKB and in some finite amount of time. | |
1da177e4 LT |
72 | |
73 | For example, this means that it is not allowed for your TX | |
74 | mitigation scheme to let TX packets "hang out" in the TX | |
75 | ring unreclaimed forever if no new TX packets are sent. | |
76 | This error can deadlock sockets waiting for send buffer room | |
77 | to be freed up. | |
78 | ||
e34fac1c BH |
79 | If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you |
80 | must not keep any reference to that SKB and you must not attempt | |
81 | to free it up. | |
1da177e4 LT |
82 | |
83 | Probing guidelines: | |
84 | ||
85 | 1) Any hardware layer address you obtain for your device should | |
86 | be verified. For example, for ethernet check it with | |
87 | linux/etherdevice.h:is_valid_ether_addr() | |
88 | ||
89 | Close/stop guidelines: | |
90 | ||
b3cf6545 | 91 | 1) After the ndo_stop routine has been called, the hardware must |
1da177e4 | 92 | not receive or transmit any data. All in flight packets must |
28d23311 | 93 | be aborted. If necessary, poll or wait for completion of |
1da177e4 LT |
94 | any reset commands. |
95 | ||
b3cf6545 | 96 | 2) The ndo_stop routine will be called by unregister_netdevice |
1da177e4 | 97 | if device is still UP. |