From 28d23311ff35ac97ff20608f47c84c95d6389c33 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 28 Apr 2020 00:01:33 +0200 Subject: docs: networking: convert driver.txt to ReST - add SPDX header; - add a document title; - mark code blocks and literals as such; - adjust identation, whitespaces and blank lines; - add to networking/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: David S. Miller --- Documentation/networking/driver.rst | 97 +++++++++++++++++++++++++++++++++++++ Documentation/networking/driver.txt | 93 ----------------------------------- Documentation/networking/index.rst | 1 + 3 files changed, 98 insertions(+), 93 deletions(-) create mode 100644 Documentation/networking/driver.rst delete mode 100644 Documentation/networking/driver.txt diff --git a/Documentation/networking/driver.rst b/Documentation/networking/driver.rst new file mode 100644 index 000000000000..c8f59dbda46f --- /dev/null +++ b/Documentation/networking/driver.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Softnet Driver Issues +===================== + +Transmit path guidelines: + +1) The ndo_start_xmit method must not return NETDEV_TX_BUSY under + any normal circumstances. It is considered a hard error unless + there is no way your device can tell ahead of time when it's + transmit function will become busy. + + Instead it must maintain the queue properly. For example, + for a driver implementing scatter-gather this means:: + + static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb, + struct net_device *dev) + { + struct drv *dp = netdev_priv(dev); + + lock_tx(dp); + ... + /* This is a hard error log it. */ + if (TX_BUFFS_AVAIL(dp) <= (skb_shinfo(skb)->nr_frags + 1)) { + netif_stop_queue(dev); + unlock_tx(dp); + printk(KERN_ERR PFX "%s: BUG! Tx Ring full when queue awake!\n", + dev->name); + return NETDEV_TX_BUSY; + } + + ... queue packet to card ... + ... update tx consumer index ... + + if (TX_BUFFS_AVAIL(dp) <= (MAX_SKB_FRAGS + 1)) + netif_stop_queue(dev); + + ... + unlock_tx(dp); + ... + return NETDEV_TX_OK; + } + + And then at the end of your TX reclamation event handling:: + + if (netif_queue_stopped(dp->dev) && + TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1)) + netif_wake_queue(dp->dev); + + For a non-scatter-gather supporting card, the three tests simply become:: + + /* This is a hard error log it. */ + if (TX_BUFFS_AVAIL(dp) <= 0) + + and:: + + if (TX_BUFFS_AVAIL(dp) == 0) + + and:: + + if (netif_queue_stopped(dp->dev) && + TX_BUFFS_AVAIL(dp) > 0) + netif_wake_queue(dp->dev); + +2) An ndo_start_xmit method must not modify the shared parts of a + cloned SKB. + +3) Do not forget that once you return NETDEV_TX_OK from your + ndo_start_xmit method, it is your driver's responsibility to free + up the SKB and in some finite amount of time. + + For example, this means that it is not allowed for your TX + mitigation scheme to let TX packets "hang out" in the TX + ring unreclaimed forever if no new TX packets are sent. + This error can deadlock sockets waiting for send buffer room + to be freed up. + + If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you + must not keep any reference to that SKB and you must not attempt + to free it up. + +Probing guidelines: + +1) Any hardware layer address you obtain for your device should + be verified. For example, for ethernet check it with + linux/etherdevice.h:is_valid_ether_addr() + +Close/stop guidelines: + +1) After the ndo_stop routine has been called, the hardware must + not receive or transmit any data. All in flight packets must + be aborted. If necessary, poll or wait for completion of + any reset commands. + +2) The ndo_stop routine will be called by unregister_netdevice + if device is still UP. diff --git a/Documentation/networking/driver.txt b/Documentation/networking/driver.txt deleted file mode 100644 index da59e2884130..000000000000 --- a/Documentation/networking/driver.txt +++ /dev/null @@ -1,93 +0,0 @@ -Document about softnet driver issues - -Transmit path guidelines: - -1) The ndo_start_xmit method must not return NETDEV_TX_BUSY under - any normal circumstances. It is considered a hard error unless - there is no way your device can tell ahead of time when it's - transmit function will become busy. - - Instead it must maintain the queue properly. For example, - for a driver implementing scatter-gather this means: - - static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb, - struct net_device *dev) - { - struct drv *dp = netdev_priv(dev); - - lock_tx(dp); - ... - /* This is a hard error log it. */ - if (TX_BUFFS_AVAIL(dp) <= (skb_shinfo(skb)->nr_frags + 1)) { - netif_stop_queue(dev); - unlock_tx(dp); - printk(KERN_ERR PFX "%s: BUG! Tx Ring full when queue awake!\n", - dev->name); - return NETDEV_TX_BUSY; - } - - ... queue packet to card ... - ... update tx consumer index ... - - if (TX_BUFFS_AVAIL(dp) <= (MAX_SKB_FRAGS + 1)) - netif_stop_queue(dev); - - ... - unlock_tx(dp); - ... - return NETDEV_TX_OK; - } - - And then at the end of your TX reclamation event handling: - - if (netif_queue_stopped(dp->dev) && - TX_BUFFS_AVAIL(dp) > (MAX_SKB_FRAGS + 1)) - netif_wake_queue(dp->dev); - - For a non-scatter-gather supporting card, the three tests simply become: - - /* This is a hard error log it. */ - if (TX_BUFFS_AVAIL(dp) <= 0) - - and: - - if (TX_BUFFS_AVAIL(dp) == 0) - - and: - - if (netif_queue_stopped(dp->dev) && - TX_BUFFS_AVAIL(dp) > 0) - netif_wake_queue(dp->dev); - -2) An ndo_start_xmit method must not modify the shared parts of a - cloned SKB. - -3) Do not forget that once you return NETDEV_TX_OK from your - ndo_start_xmit method, it is your driver's responsibility to free - up the SKB and in some finite amount of time. - - For example, this means that it is not allowed for your TX - mitigation scheme to let TX packets "hang out" in the TX - ring unreclaimed forever if no new TX packets are sent. - This error can deadlock sockets waiting for send buffer room - to be freed up. - - If you return NETDEV_TX_BUSY from the ndo_start_xmit method, you - must not keep any reference to that SKB and you must not attempt - to free it up. - -Probing guidelines: - -1) Any hardware layer address you obtain for your device should - be verified. For example, for ethernet check it with - linux/etherdevice.h:is_valid_ether_addr() - -Close/stop guidelines: - -1) After the ndo_stop routine has been called, the hardware must - not receive or transmit any data. All in flight packets must - be aborted. If necessary, poll or wait for completion of - any reset commands. - -2) The ndo_stop routine will be called by unregister_netdevice - if device is still UP. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index 55746038a7e9..313f66900bce 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -53,6 +53,7 @@ Contents: decnet defza dns_resolver + driver .. only:: subproject and html -- cgit