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 <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>

diff --git a/Documentation/networking/driver.rst b/Documentation/networking/driver.rst
new file mode 100644 (file)
index 0000000..c8f59db
--- /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 (file)
index da59e28..0000000
--- 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 55746038a7e9731799492a881e8742fd0ed1942c..313f66900bce406e5c63472c9caf24fb2b2c4087 100644 (file)
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -53,6 +53,7 @@ Contents:
    decnet
    defza
    dns_resolver
+   driver
 
 .. only::  subproject and html