| Randy Dunlap | 98766fb | 2005-11-21 21:32:31 -0800 | [diff] [blame] | 1 | Document about softnet driver issues |
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 2 | |
| 3 | Transmit path guidelines: |
| 4 | |
| 5 | 1) The hard_start_xmit method must never return '1' under any |
| 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 | { |
| 16 | struct drv *dp = dev->priv; |
| 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 | |
| 40 | And then at the end of your TX reclaimation event handling: |
| 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 | |
| 61 | 2) Do not forget to update netdev->trans_start to jiffies after |
| 62 | each new tx packet is given to the hardware. |
| 63 | |
| 64 | 3) Do not forget that once you return 0 from your hard_start_xmit |
| 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 | |
| 74 | If you return 1 from the hard_start_xmit method, you must not keep |
| 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 | |
| 85 | 1) After the dev->stop routine has been called, the hardware must |
| 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 | |
| 90 | 2) The dev->stop routine will be called by unregister_netdevice |
| 91 | if device is still UP. |