Documentation/networking/driver.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/driver.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/driver.rst
Extension
.rst
Size
4019 bytes
Lines
144
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

if (drv_tx_avail(dr) <= skb_shinfo(skb)->nr_frags + 1) {
			netif_tx_stop_queue(txq);
			netdev_warn(dev, "Tx Ring full when queue awake!\n");
			return NETDEV_TX_BUSY;
		}

		//... queue packet to card ...

		netdev_tx_sent_queue(txq, skb->len);

		//... update tx producer index using WRITE_ONCE() ...

		if (!netif_txq_maybe_stop(txq, drv_tx_avail(dr),
					  MAX_SKB_FRAGS + 1, 2 * MAX_SKB_FRAGS))
			dr->stats.stopped++;

		//...
		return NETDEV_TX_OK;
	}

And then at the end of your TX reclamation event handling:

.. code-block:: c

	//... update tx consumer index using WRITE_ONCE() ...

	netif_txq_completed_wake(txq, cmpl_pkts, cmpl_bytes,
				 drv_tx_avail(dr), 2 * MAX_SKB_FRAGS);

Lockless queue stop / wake helper macros
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: include/net/netdev_queues.h
   :doc: Lockless queue stopping / waking helpers.

The standard macros like netif_txq_maybe_stop(), netif_txq_try_stop() etc.
are well tested, prefer them over local synchronization schemes.

No exclusive ownership
----------------------

An ndo_start_xmit method must not modify the shared parts of a
cloned SKB.

Timely completions
------------------

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.

Error message reporting
=======================

A number of driver configuration interfaces pass a Netlink extended ACK
(``extack``) object to the driver (either directly as an argument or
as a member of a parameter struct). The drivers should try to report
most errors via the ``extack`` object. System level exceptions,
indicating that system or device is misbehaving or is in bad state,
should continue to be reported to system logs.

Annotation

Implementation Notes