Document the new mbuf pools with external pinned buffers. Signed-off-by: Viacheslav Ovsiienko <viachesl...@mellanox.com> --- doc/guides/prog_guide/mbuf_lib.rst | 34 ++++++++++++++++++++++++++++++++++ doc/guides/rel_notes/release_20_02.rst | 5 +++++ 2 files changed, 39 insertions(+)
diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index 0d3223b..d7be5dd 100644 --- a/doc/guides/prog_guide/mbuf_lib.rst +++ b/doc/guides/prog_guide/mbuf_lib.rst @@ -240,6 +240,40 @@ the memory pool for indirect buffers should be configured to indicate the reduce Examples of the initialization of a memory pool for indirect buffers (as well as use case examples for indirect buffers) can be found in several of the sample applications, for example, the IPv4 Multicast sample application. +.. _external_pinned_buffer: + +External Pinned Buffers +----------------------- + +The regular pktmbuf pools contain only mbufs with no external buffers. +This means data buffer for the mbuf should be placed right after the +mbuf structure (and the private data if any). + +On some cases, the application would want to have the buffers allocated +from a different device in the platform. This is in order to do zero +copy for the packet directly to the device memory. Examples for such +devices can be GPU or storage device. For such cases the regular pktmbuf +pool does not fit since each mbuf would need to point to external +buffer. + +To support above, the new type of pktmbuf pool is introduced - the pktmbuf +pool with pinned external memory. The pool of such type is populated with +mbufs pointing to the device buffers using the mbuf external buffer feature. +The PMD populates its receive queues with those buffers, so that +every packet received will be scattered directly to the device memory. +On the other direction, embedding the buffer pointer to the transmit +queues of the NIC, will make the DMA to fetch device memory +using peer to peer communication. + +Such mbuf with external buffer should be handled with care when mbuf is +freed. Mainly the external buffer should not be detached, so that it can +be reused for the next packet receive. To support this pool feature the PMDs +should be aware that pool mbuf allocator might return the buffers with +EXT_ATTACHED_MBUF flag set. + +To create the pktmbuf pool with the pinned external memory the dedicated +routine rte_pktmbuf_pool_create_extbuf() is provided. + Debug ----- diff --git a/doc/guides/rel_notes/release_20_02.rst b/doc/guides/rel_notes/release_20_02.rst index dfebc46..a0e6734 100644 --- a/doc/guides/rel_notes/release_20_02.rst +++ b/doc/guides/rel_notes/release_20_02.rst @@ -65,6 +65,10 @@ New Features New APIs have been added to support rings with custom element size. +* **Added rte_mbuf pool with Pinned External Memory.** + + Added support for new type of pktsmbuf pool. + * **Updated rte_flow api to support L2TPv3 over IP flows.** Added support for new flow item to handle L2TPv3 over IP rte_flow patterns. @@ -132,6 +136,7 @@ New Features * Added support for RSS using L3/L4 source/destination only. * Added support for matching on GTP tunnel header item. + * Added support for the mbufs with external pinned buffers. * Removed limitation of matching on tagged/untagged packets (when using DV flow engine). * Added BlueField-2 integrated ConnectX-6 Dx device support. -- 1.8.3.1
