.. SPDX-License-Identifier: GPL-2.0

.. include:: ../disclaimer-zh_CN.rst

:Original: Documentation/networking/driver.rst

:翻译:

	陈思为 Siwei Chen <businiaoanka@anka1.top>

================
Softnet 驱动问题
================

探测指南
========

地址校验
--------

为设备获取的任何硬件层地址都应进行校验。例如，以太网地址应使用
linux/etherdevice.h 中的 is_valid_ether_addr() 进行检查。

关闭/停止指南
=============

静默
----

ndo_stop 例程被调用后，硬件不得再收发任何数据。所有在途报文都必须中止。
如有必要，应轮询或等待任何复位命令完成。

自动关闭
--------

若设备仍处于 UP 状态，ndo_stop 例程将由 unregister_netdevice 调用。

发送路径指南
============

提前停止队列
------------

ndo_start_xmit 方法在任何正常情况下都不得返回 NETDEV_TX_BUSY。
除非设备确实无法预先判断其发送功能何时会繁忙，否则返回该值被视为严重错误。

相反，驱动必须正确地维护队列。例如，对于实现分散-聚集
（scatter-gather）的驱动，这意味着：

.. code-block:: c

	static u32 drv_tx_avail(struct drv_ring *dr)
	{
		u32 used = READ_ONCE(dr->prod) - READ_ONCE(dr->cons);

		return dr->tx_ring_size - (used & dr->tx_ring_mask);
	}

	static netdev_tx_t drv_hard_start_xmit(struct sk_buff *skb,
					       struct net_device *dev)
	{
		struct drv *dp = netdev_priv(dev);
		struct netdev_queue *txq;
		struct drv_ring *dr;
		int idx;

		idx = skb_get_queue_mapping(skb);
		dr = dp->tx_rings[idx];
		txq = netdev_get_tx_queue(dev, idx);

		//...
		/* 这应当是极为罕见的竞争——记录下来。 */
		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;
		}

		//... 将报文排队到网卡 ...

		netdev_tx_sent_queue(txq, skb->len);

		//... 使用 WRITE_ONCE() 更新 tx 生产者索引 ...

		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;
	}

然后在 TX 回收事件处理的末尾：

.. code-block:: c

	//... 使用 WRITE_ONCE() 更新 tx 消费者索引 ...

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

无锁队列停止/唤醒辅助宏
~~~~~~~~~~~~~~~~~~~~~~~

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

netif_txq_maybe_stop()、netif_txq_try_stop() 等标准宏已经过充分测试，
请优先使用它们，而非本地同步方案。

无独占所有权
------------

ndo_start_xmit 方法不得修改被克隆 SKB 的共享部分。

及时完成
--------

请谨记：一旦 ndo_start_xmit 方法返回 NETDEV_TX_OK，
驱动就有责任在有限的时间内释放该 SKB。

例如，这意味着不允许你的 TX 缓解方案在没有新 TX 报文发送时，
让 TX 报文永远“滞留”在 TX 环中而不被回收。
这种错误会使等待发送缓冲区空间释放的套接字发生死锁。

若 ndo_start_xmit 方法返回 NETDEV_TX_BUSY，
则不得保留对该 SKB 的任何引用，也不得尝试释放它。

错误消息报告
============

许多驱动配置接口会向驱动传递一个 Netlink 扩展 ACK（``extack``）对象
（直接作为参数，或作为参数结构体的成员）。驱动应尽量通过 ``extack`` 对象
报告大多数错误。表示系统或设备行为异常、处于不良状态的系统级异常，则应继续
报告到系统日志。

消息应 **要么** 通过 ``extack`` 传递， **要么** 写入系统日志。驱动不应
试图将同一信息同时报告到两处。