Softnet Driver Issues

Softnet 드라이버 구현 지침

이 문서는 `GPL-2.0` 라이선스를 따릅니다.

Softnet 드라이버의 탐색, 종료, 송신 경로에서 지켜야 할 핵심 구현 규칙을 설명합니다.

.. SPDX-License-Identifier: GPL-2.0

=====================
Softnet Driver Issues
=====================

장치 주소 검증

탐색 지침

주소 검증

장치에서 얻은 하드웨어 계층 주소는 반드시 검증해야 합니다. 예를 들어 이더넷 주소는 `linux/etherdevice.h`의 `is_valid_ether_addr()`로 확인합니다.

Probing guidelines
==================

Address validation
------------------

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()

ndo_stop 이후 정지 상태 보장

닫기 및 정지 지침

정지 상태

`ndo_stop` 루틴이 호출된 뒤에는 하드웨어가 어떤 데이터도 송수신해서는 안 됩니다. 처리 중인 모든 패킷을 중단해야 하며, 필요하면 재설정 명령이 끝날 때까지 폴링하거나 기다립니다.

자동 닫기

장치가 여전히 `UP` 상태라면 `unregister_netdevice`가 `ndo_stop` 루틴을 호출합니다.

Close/stop guidelines
=====================

Quiescence
----------

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.

Auto-close
----------

The ndo_stop routine will be called by unregister_netdevice
if device is still UP.

송신 큐를 미리 멈추고 안전하게 깨우기

송신 경로 지침

큐를 미리 정지

정상적인 상황에서 `ndo_start_xmit` 메서드는 `NETDEV_TX_BUSY`를 반환해서는 안 됩니다. 장치의 송신 기능이 언제 바빠질지 미리 알 방법이 전혀 없는 경우가 아니라면 이는 심각한 오류로 간주됩니다.

대신 드라이버가 큐를 올바르게 관리해야 합니다. 다음 scatter-gather 드라이버 예제에서 `drv_tx_avail()`은 생산자·소비자 인덱스를 `READ_ONCE()`로 읽어 사용 가능한 송신 링 엔트리 수를 계산합니다.

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 & bp->tx_ring_mask);
}

`drv_hard_start_xmit()`은 SKB의 큐 매핑으로 송신 링과 `netdev_queue`를 선택합니다. 큐가 깨어 있는데도 필요한 엔트리가 부족한 드문 경쟁 조건에서는 큐를 멈추고 경고를 기록한 다음 `NETDEV_TX_BUSY`를 반환합니다.

패킷을 카드에 넣은 뒤 `netdev_tx_sent_queue()`로 전송 바이트를 회계 처리하고, 생산자 인덱스를 `WRITE_ONCE()`로 갱신합니다. 이어 `netif_txq_maybe_stop()`으로 현재 여유 공간과 정지·재개 임계값을 검사하여 필요하면 큐를 멈추고 통계를 증가시킵니다.

송신 완료 회수 처리의 끝에서는 소비자 인덱스를 `WRITE_ONCE()`로 갱신한 후 `netif_txq_completed_wake()`에 완료 패킷 수, 완료 바이트 수, 현재 링 여유량, 재개 임계값을 전달해 큐를 깨웁니다.

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

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

Transmit path guidelines
========================

Stop queues in advance
----------------------

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 its
transmit function will become busy.

Instead it must maintain the queue properly.  For example,
for a driver implementing scatter-gather this means:

.. 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 & bp->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);

                //...
                /* This should be a very rare race - log it. */
                if (drv_tx_avail(dr) <= skb_shinfo(skb)->nr_frags + 1) {
                        netif_stop_queue(dev);
                        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);

잠금 없는 큐 정지·재개 도우미

잠금 없는 큐 정지 및 깨우기 도우미 매크로

잠금 없는 큐 정지·재개 도우미의 커널 문서는 `include/net/netdev_queues.h`에서 가져옵니다.

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

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

복제 SKB의 공유 영역 보호

배타적 소유권 없음

`ndo_start_xmit` 메서드는 복제된 SKB의 공유 영역을 수정해서는 안 됩니다.

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

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

유한 시간 안에 송신 완료 처리

적시 완료

`ndo_start_xmit` 메서드에서 `NETDEV_TX_OK`를 반환한 뒤에는 드라이버가 SKB를 해제할 책임이 있으며, 반드시 유한한 시간 안에 처리해야 합니다.

예를 들어 새 송신 패킷이 들어오지 않는다는 이유로 송신 완화 기법이 기존 패킷을 송신 링에 영원히 미회수 상태로 남겨서는 안 됩니다. 이런 오류는 송신 버퍼 공간이 해제되기를 기다리는 소켓을 교착 상태에 빠뜨릴 수 있습니다.

`ndo_start_xmit`에서 `NETDEV_TX_BUSY`를 반환했다면 해당 SKB의 참조를 보관해서도, 그 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.