€•¼G      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ%/translations/zh_CN/networking/netmem”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/zh_TW/networking/netmem”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/it_IT/networking/netmem”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/ja_JP/networking/netmem”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/ko_KR/networking/netmem”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ%/translations/sp_SP/networking/netmem”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒ?/var/lib/git/docbuild/linux/Documentation/networking/netmem.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ"Netmem Support for Network Drivers”h]”hŒ"Netmem Support for Network Drivers”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hX   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.”h]”hX   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.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhÊ)”}”(hŒBenefits of Netmem :”h]”hŒBenefits of Netmem :”…””}”(hhÙhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ¢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.”h]”hÊ)”}”(hŒ¢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.”h]”hŒ¢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.”…””}”(hhòhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khhîubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhhéhžhhŸh³h Nubhí)”}”(hŒZFuture-proof: Drivers with netmem support are ready for upcoming
features that rely on it.”h]”hÊ)”}”(hŒZFuture-proof: Drivers with netmem support are ready for upcoming
features that rely on it.”h]”hŒZFuture-proof: Drivers with netmem support are ready for upcoming
features that rely on it.”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhhéhžhhŸh³h Nubhí)”}”(hŒtSimplified Development: Drivers interact with a consistent API,
regardless of the underlying memory implementation.
”h]”hÊ)”}”(hŒsSimplified Development: Drivers interact with a consistent API,
regardless of the underlying memory implementation.”h]”hŒsSimplified Development: Drivers interact with a consistent API,
regardless of the underlying memory implementation.”…””}”(hj"  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhhéhžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1hçhŸh³h Khh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒDriver Requirements”h]”hŒDriver Requirements”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj>  hžhhŸh³h KubhŒenumerated_list”“”)”}”(hhh]”(hí)”}”(hŒ#The driver must support page_pool.
”h]”hÊ)”}”(hŒ"The driver must support page_pool.”h]”hŒ"The driver must support page_pool.”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KhjT  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸh³h Nubhí)”}”(hŒ;The driver must support the tcp-data-split ethtool option.
”h]”hÊ)”}”(hŒ:The driver must support the tcp-data-split ethtool option.”h]”hŒ:The driver must support the tcp-data-split ethtool option.”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸh³h Nubhí)”}”(hX¤  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.
”h]”(hÊ)”}”(hX  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 * :”h]”hX  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 * :”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khj„  ubhè)”}”(hhh]”(hí)”}”(hŒ)page_pool_alloc -> page_pool_alloc_netmem”h]”hÊ)”}”(hj›  h]”hŒ)page_pool_alloc -> page_pool_alloc_netmem”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K"hj™  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhj–  ubhí)”}”(hŒ7page_pool_get_dma_addr -> page_pool_get_dma_addr_netmem”h]”hÊ)”}”(hj²  h]”hŒ7page_pool_get_dma_addr -> page_pool_get_dma_addr_netmem”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K#hj°  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhj–  ubhí)”}”(hŒ+page_pool_put_page -> page_pool_put_netmem
”h]”hÊ)”}”(hŒ*page_pool_put_page -> page_pool_put_netmem”h]”hŒ*page_pool_put_page -> page_pool_put_netmem”…””}”(hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K$hjÇ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhj–  ubeh}”(h]”h ]”h"]”h$]”h&]”j<  Œ-”uh1hçhŸh³h K"hj„  ubhÊ)”}”(hŒî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.”h]”(hŒ¸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 ”…””}”(hjæ  hžhhŸNh NubhŒ	reference”“”)”}”(hŒalmasrymina@google.com”h]”hŒalmasrymina@google.com”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:almasrymina@google.com”uh1jî  hjæ  ubhŒ  for help adding
the netmem API.”…””}”(hjæ  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K&hj„  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸh³h Nubhí)”}”(hX  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.
”h]”(hÊ)”}”(hŒ+The driver must use the following PP_FLAGS:”h]”hŒ+The driver must use the following PP_FLAGS:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K+hj  ubhè)”}”(hhh]”(hí)”}”(hŒ®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.”h]”hÊ)”}”(hŒ®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.”h]”hŒ®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.”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K-hj%  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhj"  ubhí)”}”(hŒÈ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.”h]”hÊ)”}”(hŒÈ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.”h]”hŒÈ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.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K0hj=  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhj"  ubhí)”}”(hŒbPP_FLAG_ALLOW_UNREADABLE_NETMEM. The driver must specify this flag iff
tcp-data-split is enabled.
”h]”hÊ)”}”(hŒaPP_FLAG_ALLOW_UNREADABLE_NETMEM. The driver must specify this flag iff
tcp-data-split is enabled.”h]”hŒaPP_FLAG_ALLOW_UNREADABLE_NETMEM. The driver must specify this flag iff
tcp-data-split is enabled.”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K3hjU  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhj"  ubeh}”(h]”h ]”h"]”h$]”h&]”j<  jå  uh1hçhŸh³h K-hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸNh Nubhí)”}”(hXl  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).
”h]”(hÊ)”}”(hX/  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.”h]”hX1  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.”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K6hjy  ubhÊ)”}”(hX:  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).”h]”hX:  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).”…””}”(hj‹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K<hjy  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸh³h Nubhí)”}”(hX™  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.
”h]”hÊ)”}”(hX˜  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.”h]”hX˜  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.”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KBhjŸ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸh³h Nubhí)”}”(hXÁ  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.”h]”hÊ)”}”(hXÁ  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.”h]”hXÁ  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.”…””}”(hj»  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KIhj·  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hìhjQ  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jO  hj>  hžhhŸh³h Kubeh}”(h]”Œdriver-requirements”ah ]”h"]”Œdriver requirements”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubeh}”(h]”Œ"netmem-support-for-network-drivers”ah ]”h"]”Œ"netmem support for network drivers”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jç  jä  jß  jÜ  uŒ	nametypes”}”(jç  ‰jß  ‰uh}”(jä  h¶jÜ  j>  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.