Netmem Support for Network Drivers

추상 메모리형의 목적

Netmem은 device memory TCP 같은 기능을 가능하게 하는 추상 메모리형입니다. 드라이버가 netmem API를 사용하면 `struct page`, DMA-buf 등 서로 다른 기반 메모리를 큰 수정 없이 처리할 수 있습니다.

장점은 세 가지입니다. 여러 메모리 backend를 지원하는 유연성, 앞으로 netmem에 의존할 기능을 수용하는 미래 대비, 실제 메모리 구현과 무관한 일관된 API로 개발을 단순화하는 것입니다.

.. SPDX-License-Identifier: GPL-2.0

==================================
Netmem Support for Network Drivers
==================================

This document outlines the requirements for network drivers to support netmem,
an abstract memory type that enables features like device memory TCP. By
supporting netmem, drivers can work with various underlying memory types
with little to no modification.

Benefits of Netmem :

* Flexibility: Netmem can be backed by different memory types (e.g., struct
  page, DMA-buf), allowing drivers to support various use cases such as device
  memory TCP.
* Future-proof: Drivers with netmem support are ready for upcoming
  features that rely on it.
* Simplified Development: Drivers interact with a consistent API,
  regardless of the underlying memory implementation.

Driver RX Requirements

드라이버 RX 요구 사항

RX 드라이버는 먼저 `page_pool`과 ethtool의 `tcp-data-split` 옵션을 지원해야 합니다. payload memory에는 page_pool netmem API를 사용하고 `struct page *` 대신 `netmem_ref`로 메모리를 추적합니다. 현재 API는 page API와 일대일로 대응하므로 `page_pool_alloc`은 `page_pool_alloc_netmem`, `page_pool_get_dma_addr`는 `page_pool_get_dma_addr_netmem`, `page_pool_put_page`는 `page_pool_put_netmem`으로 바꿀 수 있습니다.

아직 모든 page API에 netmem 대응 함수가 있는 것은 아닙니다. 필요한 함수가 없다면 직접 추가해 netdev mailing list에 제안하거나 maintainer 및 `almasrymina@google.com`에 도움을 요청할 수 있습니다.

page_pool에는 `PP_FLAG_DMA_MAP`과 `PP_FLAG_DMA_SYNC_DEV`를 설정해야 합니다. 드라이버가 netmem을 직접 DMA map하거나 sync할 수 있다고 가정할 수 없으므로 적절성을 아는 page_pool에 두 작업을 위임합니다. `PP_FLAG_ALLOW_UNREADABLE_NETMEM`은 `tcp-data-split`이 활성화된 경우에만, 그리고 반드시 설정해야 합니다.

드라이버는 netmem이 읽을 수 있거나 page 기반이라고 가정하면 안 됩니다. 읽을 수 없는 netmem에서는 `netmem_address()`가 `NULL`을 반환하므로 내용을 건드리지 말아야 합니다. 가능하면 `netmem_is_net_iov()`로 실제 종류를 검사하거나 `netmem_to_page()`·`netmem_to_net_iov()`로 변환하지 말고, 복잡성을 감춘 netmem/page_pool helper를 사용해야 합니다. 필요한 helper는 추가할 수 있습니다.

CPU용 DMA 동기화에는 `dma_sync_single_range_for_cpu()` 대신 `page_pool_dma_sync_netmem_for_cpu()`를 사용합니다. 어떤 provider는 page_pool이 동기화하지만 DMA-buf provider처럼 userspace가 DMA-buf API로 책임지는 경우도 있으므로, 드라이버는 전체 결정을 page_pool에 넘겨야 합니다.

page_pool 위에 드라이버 고유 recycling을 구현하지 않는 것이 좋습니다. netmem이 `struct page` 기반이 아닐 수 있으므로 page를 붙잡아 재활용할 수 없습니다. 필요하면 `page_pool_fragment_netmem()` 또는 `page_pool_ref_netmem()`으로 page_pool 참조를 유지할 수 있지만, zerocopy에서 userspace가 참조를 오래 보유하는 유형은 순환 시간이 길 수 있음을 고려해야 합니다.

======================

1. The driver must support page_pool.

2. The driver must support the tcp-data-split ethtool option.

3. The driver must use the page_pool netmem APIs for payload memory. The netmem
   APIs currently 1-to-1 correspond with page APIs. Conversion to netmem should
   be achievable by switching the page APIs to netmem APIs and tracking memory
   via netmem_refs in the driver rather than struct page * :

   - page_pool_alloc -> page_pool_alloc_netmem
   - page_pool_get_dma_addr -> page_pool_get_dma_addr_netmem
   - page_pool_put_page -> page_pool_put_netmem

   Not all page APIs have netmem equivalents at the moment. If your driver
   relies on a missing netmem API, feel free to add and propose to netdev@, or
   reach out to the maintainers and/or almasrymina@google.com for help adding
   the netmem API.

4. The driver must use the following PP_FLAGS:

   - PP_FLAG_DMA_MAP: netmem is not dma-mappable by the driver. The driver
     must delegate the dma mapping to the page_pool, which knows when
     dma-mapping is (or is not) appropriate.
   - PP_FLAG_DMA_SYNC_DEV: netmem dma addr is not necessarily dma-syncable
     by the driver. The driver must delegate the dma syncing to the page_pool,
     which knows when dma-syncing is (or is not) appropriate.
   - PP_FLAG_ALLOW_UNREADABLE_NETMEM. The driver must specify this flag iff
     tcp-data-split is enabled.

5. The driver must not assume the netmem is readable and/or backed by pages.
   The netmem returned by the page_pool may be unreadable, in which case
   netmem_address() will return NULL. The driver must correctly handle
   unreadable netmem, i.e. don't attempt to handle its contents when
   netmem_address() is NULL.

   Ideally, drivers should not have to check the underlying netmem type via
   helpers like netmem_is_net_iov() or convert the netmem to any of its
   underlying types via netmem_to_page() or netmem_to_net_iov(). In most cases,
   netmem or page_pool helpers that abstract this complexity are provided
   (and more can be added).

6. The driver must use page_pool_dma_sync_netmem_for_cpu() in lieu of
   dma_sync_single_range_for_cpu(). For some memory providers, dma_syncing for
   CPU will be done by the page_pool, for others (particularly dmabuf memory
   provider), dma syncing for CPU is the responsibility of the userspace using
   dmabuf APIs. The driver must delegate the entire dma-syncing operation to
   the page_pool which will do it correctly.

7. Avoid implementing driver-specific recycling on top of the page_pool. Drivers
   cannot hold onto a struct page to do their own recycling as the netmem may
   not be backed by a struct page. However, you may hold onto a page_pool
   reference with page_pool_fragment_netmem() or page_pool_ref_netmem() for
   that purpose, but be mindful that some netmem types might have longer
   circulation times, such as when userspace holds a reference in zerocopy
   scenarios.

Driver TX Requirements

드라이버 TX 요구 사항

TX 드라이버는 netmem의 `dma_addr`를 DMA mapping API에 직접 넘기면 안 됩니다. 주소가 일반 DMA API와 호환되지 않는 DMA-buf 같은 공급원에서 왔을 수 있기 때문입니다.

`dma_unmap_page[_attrs]()`와 `dma_unmap_addr_set()` 대신 `netmem_dma_unmap_page_attrs()`와 `netmem_dma_unmap_addr_set()` 같은 helper를 사용해야 합니다. 이 함수들은 주소 출처와 무관하게 올바르게 처리하고 적절할 때만 일반 DMA mapping API로 위임합니다. 대응 API가 없다면 RX와 마찬가지로 netdev에 제안하거나 maintainer에게 도움을 요청할 수 있습니다.

마지막으로 드라이버는 `netdev->netmem_tx = true`를 설정하여 netmem TX 지원을 선언해야 합니다.

======================

1. The Driver must not pass the netmem dma_addr to any of the dma-mapping APIs
   directly. This is because netmem dma_addrs may come from a source like
   dma-buf that is not compatible with the dma-mapping APIs.

   Helpers like netmem_dma_unmap_page_attrs() & netmem_dma_unmap_addr_set()
   should be used in lieu of dma_unmap_page[_attrs](), dma_unmap_addr_set().
   The netmem variants will handle netmem dma_addrs correctly regardless of the
   source, delegating to the dma-mapping APIs when appropriate.

   Not all dma-mapping APIs have netmem equivalents at the moment. If your
   driver relies on a missing netmem API, feel free to add and propose to
   netdev@, or reach out to the maintainers and/or almasrymina@google.com for
   help adding the netmem API.

2. Driver should declare support by setting `netdev->netmem_tx = true`