From 482a4360c56a1ecb5ea54c00db647b0012d787cf Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 30 Apr 2020 18:04:04 +0200 Subject: 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 Signed-off-by: David S. Miller --- Documentation/networking/can.rst | 2 +- Documentation/networking/index.rst | 1 + Documentation/networking/netdevices.rst | 111 ++++++++++++++++++++++++++++++++ Documentation/networking/netdevices.txt | 104 ------------------------------ 4 files changed, 113 insertions(+), 105 deletions(-) create mode 100644 Documentation/networking/netdevices.rst delete mode 100644 Documentation/networking/netdevices.txt (limited to 'Documentation/networking') diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index 2fd0b51a8c52..ff05cbd05e0d 100644 --- 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 4c6aa3db97d4..5a320553ffba 100644 --- 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 index 000000000000..5a85fcc80c76 --- /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 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 index 7fec2061a334..000000000000 --- 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 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. -- cgit v1.2.3-59-g8ed1b