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