1*6b818ef5SWang Yaxin.. SPDX-License-Identifier: GPL-2.0 2*6b818ef5SWang Yaxin 3*6b818ef5SWang Yaxin.. include:: ../disclaimer-zh_CN.rst 4*6b818ef5SWang Yaxin 5*6b818ef5SWang Yaxin:Original: Documentation/networking/netmem.rst 6*6b818ef5SWang Yaxin 7*6b818ef5SWang Yaxin:翻译: 8*6b818ef5SWang Yaxin 9*6b818ef5SWang Yaxin 王亚鑫 Wang Yaxin <wang.yaxin@zte.com.cn> 10*6b818ef5SWang Yaxin 11*6b818ef5SWang Yaxin================== 12*6b818ef5SWang Yaxin网络驱动支持Netmem 13*6b818ef5SWang Yaxin================== 14*6b818ef5SWang Yaxin 15*6b818ef5SWang Yaxin本文档概述了网络驱动支持netmem（一种抽象内存类型）的要求，该内存类型 16*6b818ef5SWang Yaxin支持设备内存 TCP 等功能。通过支持netmem，驱动可以灵活适配不同底层内 17*6b818ef5SWang Yaxin存类型（如设备内存TCP），且无需或仅需少量修改。 18*6b818ef5SWang Yaxin 19*6b818ef5SWang YaxinNetmem的优势： 20*6b818ef5SWang Yaxin 21*6b818ef5SWang Yaxin* 灵活性：netmem 可由不同内存类型（如 struct page、DMA-buf）支持， 22*6b818ef5SWang Yaxin 使驱动程序能够支持设备内存 TCP 等各种用例。 23*6b818ef5SWang Yaxin* 前瞻性：支持netmem的驱动可无缝适配未来依赖此功能的新特性。 24*6b818ef5SWang Yaxin* 简化开发：驱动通过统一API与netmem交互，无需关注底层内存的实现差异。 25*6b818ef5SWang Yaxin 26*6b818ef5SWang Yaxin驱动RX要求 27*6b818ef5SWang Yaxin========== 28*6b818ef5SWang Yaxin 29*6b818ef5SWang Yaxin1. 驱动必须支持page_pool。 30*6b818ef5SWang Yaxin 31*6b818ef5SWang Yaxin2. 驱动必须支持tcp-data-split ethtool选项。 32*6b818ef5SWang Yaxin 33*6b818ef5SWang Yaxin3. 驱动必须使用page_pool netmem API处理有效载荷内存。当前netmem API 34*6b818ef5SWang Yaxin 与page API一一对应。转换时需要将page API替换为netmem API，并用驱动 35*6b818ef5SWang Yaxin 中的netmem_refs跟踪内存而非 `struct page *`： 36*6b818ef5SWang Yaxin 37*6b818ef5SWang Yaxin - page_pool_alloc -> page_pool_alloc_netmem 38*6b818ef5SWang Yaxin - page_pool_get_dma_addr -> page_pool_get_dma_addr_netmem 39*6b818ef5SWang Yaxin - page_pool_put_page -> page_pool_put_netmem 40*6b818ef5SWang Yaxin 41*6b818ef5SWang Yaxin 目前并非所有页 pageAPI 都有对应的 netmem 等效接口。如果你的驱动程序 42*6b818ef5SWang Yaxin 依赖某个尚未实现的 netmem API，请直接实现并提交至 netdev@邮件列表， 43*6b818ef5SWang Yaxin 或联系维护者及 almasrymina@google.com 协助添加该 netmem API。 44*6b818ef5SWang Yaxin 45*6b818ef5SWang Yaxin4. 驱动必须设置以下PP_FLAGS： 46*6b818ef5SWang Yaxin 47*6b818ef5SWang Yaxin - PP_FLAG_DMA_MAP：驱动程序无法对 netmem 执行 DMA 映射。此时驱动 48*6b818ef5SWang Yaxin 程序必须将 DMA 映射操作委托给 page_pool，由其判断何时适合（或不适合） 49*6b818ef5SWang Yaxin 进行 DMA 映射。 50*6b818ef5SWang Yaxin - PP_FLAG_DMA_SYNC_DEV：驱动程序无法保证 netmem 的 DMA 地址一定能 51*6b818ef5SWang Yaxin 完成 DMA 同步。此时驱动程序必须将 DMA 同步操作委托给 page_pool，由 52*6b818ef5SWang Yaxin 其判断何时适合（或不适合）进行 DMA 同步。 53*6b818ef5SWang Yaxin - PP_FLAG_ALLOW_UNREADABLE_NETMEM：仅当启用 tcp-data-split 时， 54*6b818ef5SWang Yaxin 驱动程序必须显式设置此标志。 55*6b818ef5SWang Yaxin 56*6b818ef5SWang Yaxin5. 驱动不得假设netmem可读或基于页。当netmem_address()返回NULL时，表示 57*6b818ef5SWang Yaxin内存不可读。驱动需正确处理不可读的netmem，例如，当netmem_address()返回 58*6b818ef5SWang YaxinNULL时，避免访问内容。 59*6b818ef5SWang Yaxin 60*6b818ef5SWang Yaxin 理想情况下，驱动程序不应通过netmem_is_net_iov()等辅助函数检查底层 61*6b818ef5SWang Yaxin netmem 类型，也不应通过netmem_to_page()或netmem_to_net_iov()将 62*6b818ef5SWang Yaxin netmem 转换为其底层类型。在大多数情况下，系统会提供抽象这些复杂性的 63*6b818ef5SWang Yaxin netmem 或 page_pool 辅助函数（并可根据需要添加更多）。 64*6b818ef5SWang Yaxin 65*6b818ef5SWang Yaxin6. 驱动程序必须使用page_pool_dma_sync_netmem_for_cpu()代替dma_sync_single_range_for_cpu()。 66*6b818ef5SWang Yaxin对于某些内存提供者，CPU 的 DMA 同步将由 page_pool 完成；而对于其他提供者 67*6b818ef5SWang Yaxin（特别是 dmabuf 内存提供者），CPU 的 DMA 同步由使用 dmabuf API 的用户空 68*6b818ef5SWang Yaxin间负责。驱动程序必须将整个 DMA 同步操作委托给 page_pool，以确保操作正确执行。 69*6b818ef5SWang Yaxin 70*6b818ef5SWang Yaxin7. 避免在 page_pool 之上实现特定于驱动程序内存回收机制。由于 netmem 可能 71*6b818ef5SWang Yaxin不由struct page支持，驱动程序不能保留struct page来进行自定义回收。不过， 72*6b818ef5SWang Yaxin可为此目的通过page_pool_fragment_netmem()或page_pool_ref_netmem()保留 73*6b818ef5SWang Yaxinpage_pool 引用，但需注意某些 netmem 类型的循环时间可能更长（例如零拷贝场景 74*6b818ef5SWang Yaxin下用户空间持有引用的情况）。 75*6b818ef5SWang Yaxin 76*6b818ef5SWang Yaxin驱动TX要求 77*6b818ef5SWang Yaxin========== 78*6b818ef5SWang Yaxin 79*6b818ef5SWang Yaxin1. 驱动程序绝对不能直接把 netmem 的 dma_addr 传递给任何 dma-mapping API。这 80*6b818ef5SWang Yaxin是由于 netmem 的 dma_addr 可能源自 dma-buf 这类和 dma-mapping API 不兼容的 81*6b818ef5SWang Yaxin源头。 82*6b818ef5SWang Yaxin 83*6b818ef5SWang Yaxin应当使用netmem_dma_unmap_page_attrs()和netmem_dma_unmap_addr_set()等辅助 84*6b818ef5SWang Yaxin函数来替代dma_unmap_page[_attrs]()、dma_unmap_addr_set()。不管 dma_addr 85*6b818ef5SWang Yaxin来源如何，netmem 的这些变体都能正确处理 netmem dma_addr，在合适的时候会委托给 86*6b818ef5SWang Yaxindma-mapping API 去处理。 87*6b818ef5SWang Yaxin 88*6b818ef5SWang Yaxin目前，并非所有的 dma-mapping API 都有对应的 netmem 版本。要是你的驱动程序需要 89*6b818ef5SWang Yaxin使用某个还不存在的 netmem API，你可以自行添加并提交到 netdev@，也可以联系维护 90*6b818ef5SWang Yaxin人员或者发送邮件至 almasrymina@google.com 寻求帮助。 91*6b818ef5SWang Yaxin 92*6b818ef5SWang Yaxin2. 驱动程序应通过设置 netdev->netmem_tx = true 来表明自身支持 netmem 功能。 93