docs: networking: convert netdevices.txt to ReST

- add SPDX header;
- adjust title markup;
- mark lists 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/can.rst b/Documentation/networking/can.rst
index 2fd0b51a8c529da1f6e0f18cfc4da4f9bbd3b40e..ff05cbd05e0dca20477560bc6572fd62a4c0622a 100644 (file)
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -1058,7 +1058,7 @@ drivers you mainly have to deal with:
 - TX: Put the CAN frame from the socket buffer to the CAN controller.
 - RX: Put the CAN frame from the CAN controller to the socket buffer.
 
-See e.g. at Documentation/networking/netdevices.txt . The differences
+See e.g. at Documentation/networking/netdevices.rst . The differences
 for writing CAN network device driver are described below:
 
 

diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 4c6aa3db97d49f1e3bdfb653740985500bda0bae..5a320553ffba037e1bd02620e9f8b6598cd64678 100644 (file)
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -82,6 +82,7 @@ Contents:
    multiqueue
    netconsole
    netdev-features
+   netdevices
 
 .. only::  subproject and html
 

diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst
new file mode 100644 (file)
index 0000000..5a85fcc
--- /dev/null
+++ b/Documentation/networking/netdevices.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================================
+Network Devices, the Kernel, and You!
+=====================================
+
+
+Introduction
+============
+The following is a random collection of documentation regarding
+network devices.
+
+struct net_device allocation rules
+==================================
+Network device structures need to persist even after module is unloaded and
+must be allocated with alloc_netdev_mqs() and friends.
+If device has registered successfully, it will be freed on last use
+by free_netdev(). This is required to handle the pathologic case cleanly
+(example: rmmod mydriver </sys/class/net/myeth/mtu )
+
+alloc_netdev_mqs()/alloc_netdev() reserve extra space for driver
+private data which gets freed when the network device is freed. If
+separately allocated data is attached to the network device
+(netdev_priv(dev)) then it is up to the module exit handler to free that.
+
+MTU
+===
+Each network device has a Maximum Transfer Unit. The MTU does not
+include any link layer protocol overhead. Upper layer protocols must
+not pass a socket buffer (skb) to a device to transmit with more data
+than the mtu. The MTU does not include link layer header overhead, so
+for example on Ethernet if the standard MTU is 1500 bytes used, the
+actual skb will contain up to 1514 bytes because of the Ethernet
+header. Devices should allow for the 4 byte VLAN header as well.
+
+Segmentation Offload (GSO, TSO) is an exception to this rule.  The
+upper layer protocol may pass a large socket buffer to the device
+transmit routine, and the device will break that up into separate
+packets based on the current MTU.
+
+MTU is symmetrical and applies both to receive and transmit. A device
+must be able to receive at least the maximum size packet allowed by
+the MTU. A network device may use the MTU as mechanism to size receive
+buffers, but the device should allow packets with VLAN header. With
+standard Ethernet mtu of 1500 bytes, the device should allow up to
+1518 byte packets (1500 + 14 header + 4 tag).  The device may either:
+drop, truncate, or pass up oversize packets, but dropping oversize
+packets is preferred.
+
+
+struct net_device synchronization rules
+=======================================
+ndo_open:
+       Synchronization: rtnl_lock() semaphore.
+       Context: process
+
+ndo_stop:
+       Synchronization: rtnl_lock() semaphore.
+       Context: process
+       Note: netif_running() is guaranteed false
+
+ndo_do_ioctl:
+       Synchronization: rtnl_lock() semaphore.
+       Context: process
+
+ndo_get_stats:
+       Synchronization: dev_base_lock rwlock.
+       Context: nominally process, but don't sleep inside an rwlock
+
+ndo_start_xmit:
+       Synchronization: __netif_tx_lock spinlock.
+
+       When the driver sets NETIF_F_LLTX in dev->features this will be
+       called without holding netif_tx_lock. In this case the driver
+       has to lock by itself when needed.
+       The locking there should also properly protect against
+       set_rx_mode. WARNING: use of NETIF_F_LLTX is deprecated.
+       Don't use it for new drivers.
+
+       Context: Process with BHs disabled or BH (timer),
+                will be called with interrupts disabled by netconsole.
+
+       Return codes:
+
+       * NETDEV_TX_OK everything ok.
+       * NETDEV_TX_BUSY Cannot transmit packet, try later
+         Usually a bug, means queue start/stop flow control is broken in
+         the driver. Note: the driver must NOT put the skb in its DMA ring.
+
+ndo_tx_timeout:
+       Synchronization: netif_tx_lock spinlock; all TX queues frozen.
+       Context: BHs disabled
+       Notes: netif_queue_stopped() is guaranteed true
+
+ndo_set_rx_mode:
+       Synchronization: netif_addr_lock spinlock.
+       Context: BHs disabled
+
+struct napi_struct synchronization rules
+========================================
+napi->poll:
+       Synchronization:
+               NAPI_STATE_SCHED bit in napi->state.  Device
+               driver's ndo_stop method will invoke napi_disable() on
+               all NAPI instances which will do a sleeping poll on the
+               NAPI_STATE_SCHED napi->state bit, waiting for all pending
+               NAPI activity to cease.
+
+       Context:
+                softirq
+                will be called with interrupts disabled by netconsole.

diff --git a/Documentation/networking/netdevices.txt b/Documentation/networking/netdevices.txt
deleted file mode 100644 (file)
index 7fec206..0000000
--- a/Documentation/networking/netdevices.txt
+++ /dev/null
@@ -1,104 +0,0 @@
-
-Network Devices, the Kernel, and You!
-
-
-Introduction
-============
-The following is a random collection of documentation regarding
-network devices.
-
-struct net_device allocation rules
-==================================
-Network device structures need to persist even after module is unloaded and
-must be allocated with alloc_netdev_mqs() and friends.
-If device has registered successfully, it will be freed on last use
-by free_netdev(). This is required to handle the pathologic case cleanly
-(example: rmmod mydriver </sys/class/net/myeth/mtu )
-
-alloc_netdev_mqs()/alloc_netdev() reserve extra space for driver
-private data which gets freed when the network device is freed. If
-separately allocated data is attached to the network device
-(netdev_priv(dev)) then it is up to the module exit handler to free that.
-
-MTU
-===
-Each network device has a Maximum Transfer Unit. The MTU does not
-include any link layer protocol overhead. Upper layer protocols must
-not pass a socket buffer (skb) to a device to transmit with more data
-than the mtu. The MTU does not include link layer header overhead, so
-for example on Ethernet if the standard MTU is 1500 bytes used, the
-actual skb will contain up to 1514 bytes because of the Ethernet
-header. Devices should allow for the 4 byte VLAN header as well.
-
-Segmentation Offload (GSO, TSO) is an exception to this rule.  The
-upper layer protocol may pass a large socket buffer to the device
-transmit routine, and the device will break that up into separate
-packets based on the current MTU.
-
-MTU is symmetrical and applies both to receive and transmit. A device
-must be able to receive at least the maximum size packet allowed by
-the MTU. A network device may use the MTU as mechanism to size receive
-buffers, but the device should allow packets with VLAN header. With
-standard Ethernet mtu of 1500 bytes, the device should allow up to
-1518 byte packets (1500 + 14 header + 4 tag).  The device may either:
-drop, truncate, or pass up oversize packets, but dropping oversize
-packets is preferred.
-
-
-struct net_device synchronization rules
-=======================================
-ndo_open:
-       Synchronization: rtnl_lock() semaphore.
-       Context: process
-
-ndo_stop:
-       Synchronization: rtnl_lock() semaphore.
-       Context: process
-       Note: netif_running() is guaranteed false
-
-ndo_do_ioctl:
-       Synchronization: rtnl_lock() semaphore.
-       Context: process
-
-ndo_get_stats:
-       Synchronization: dev_base_lock rwlock.
-       Context: nominally process, but don't sleep inside an rwlock
-
-ndo_start_xmit:
-       Synchronization: __netif_tx_lock spinlock.
-
-       When the driver sets NETIF_F_LLTX in dev->features this will be
-       called without holding netif_tx_lock. In this case the driver
-       has to lock by itself when needed.
-       The locking there should also properly protect against
-       set_rx_mode. WARNING: use of NETIF_F_LLTX is deprecated.
-       Don't use it for new drivers.
-
-       Context: Process with BHs disabled or BH (timer),
-                will be called with interrupts disabled by netconsole.
-
-       Return codes: 
-       o NETDEV_TX_OK everything ok. 
-       o NETDEV_TX_BUSY Cannot transmit packet, try later 
-         Usually a bug, means queue start/stop flow control is broken in
-         the driver. Note: the driver must NOT put the skb in its DMA ring.
-
-ndo_tx_timeout:
-       Synchronization: netif_tx_lock spinlock; all TX queues frozen.
-       Context: BHs disabled
-       Notes: netif_queue_stopped() is guaranteed true
-
-ndo_set_rx_mode:
-       Synchronization: netif_addr_lock spinlock.
-       Context: BHs disabled
-
-struct napi_struct synchronization rules
-========================================
-napi->poll:
-       Synchronization: NAPI_STATE_SCHED bit in napi->state.  Device
-               driver's ndo_stop method will invoke napi_disable() on
-               all NAPI instances which will do a sleeping poll on the
-               NAPI_STATE_SCHED napi->state bit, waiting for all pending
-               NAPI activity to cease.
-       Context: softirq
-                will be called with interrupts disabled by netconsole.