page_pool: update document about fragment API

.. kernel-doc:: include/net/page_pool/helpers.h

   :identifiers: page_pool_put_page page_pool_put_full_page

		 page_pool_recycle_direct page_pool_dev_alloc_pages

		 page_pool_recycle_direct page_pool_free_va

		 page_pool_dev_alloc_pages page_pool_dev_alloc_frag

		 page_pool_dev_alloc page_pool_dev_alloc_va

		 page_pool_get_dma_addr page_pool_get_dma_dir

.. kernel-doc:: net/core/page_pool.c

/**

 * DOC: page_pool allocator

 *

 * The page_pool allocator is optimized for the XDP mode that

 * uses one frame per-page, but it can fallback on the

 * regular page allocator APIs.

 * The page_pool allocator is optimized for recycling page or page fragment used

 * by skb packet and xdp frame.

 *

 * Basic use involves replacing alloc_pages() calls with the

 * page_pool_alloc_pages() call.  Drivers should use

 * page_pool_dev_alloc_pages() replacing dev_alloc_pages().

 * Basic use involves replacing and alloc_pages() calls with page_pool_alloc(),

 * which allocate memory with or without page splitting depending on the

 * requested memory size.

 *

 * The API keeps track of in-flight pages, in order to let API users know

 * when it is safe to free a page_pool object.  Thus, API users

 * must call page_pool_put_page() to free the page, or attach

 * the page to a page_pool-aware object like skbs marked with

 * If the driver knows that it always requires full pages or its allocations are

 * always smaller than half a page, it can use one of the more specific API

 * calls:

 *

 * 1. page_pool_alloc_pages(): allocate memory without page splitting when

 * driver knows that the memory it need is always bigger than half of the page

 * allocated from page pool. There is no cache line dirtying for 'struct page'

 * when a page is recycled back to the page pool.

 *

 * 2. page_pool_alloc_frag(): allocate memory with page splitting when driver

 * knows that the memory it need is always smaller than or equal to half of the

 * page allocated from page pool. Page splitting enables memory saving and thus

 * avoids TLB/cache miss for data access, but there also is some cost to

 * implement page splitting, mainly some cache line dirtying/bouncing for

 * 'struct page' and atomic operation for page->pp_frag_count.

 *

 * The API keeps track of in-flight pages, in order to let API users know when

 * it is safe to free a page_pool object, the API users must call

 * page_pool_put_page() or page_pool_free_va() to free the page_pool object, or

 * attach the page_pool object to a page_pool-aware object like skbs marked with

 * skb_mark_for_recycle().

 *

 * API users must call page_pool_put_page() once on a page, as it

 * will either recycle the page, or in case of refcnt > 1, it will

 * release the DMA mapping and in-flight state accounting.

 * page_pool_put_page() may be called multi times on the same page if a page is

 * split into multi fragments. For the last fragment, it will either recycle the

 * page, or in case of page->_refcount > 1, it will release the DMA mapping and

 * in-flight state accounting.

 *

 * dma_sync_single_range_for_device() is only called for the last fragment when

 * page_pool is created with PP_FLAG_DMA_SYNC_DEV flag, so it depends on the

 * last freed fragment to do the sync_for_device operation for all fragments in

 * the same page when a page is split, the API user must setup pool->p.max_len

 * and pool->p.offset correctly and ensure that page_pool_put_page() is called

 * with dma_sync_size being -1 for fragment API.

 */

#ifndef _NET_PAGE_POOL_HELPERS_H

#define _NET_PAGE_POOL_HELPERS_H

	return page_pool_alloc_pages(pool, gfp);

}

/**

 * page_pool_dev_alloc_frag() - allocate a page fragment.

 * @pool: pool from which to allocate

 * @offset: offset to the allocated page

 * @size: requested size

 *

 * Get a page fragment from the page allocator or page_pool caches.

 *

 * Return:

 * Return allocated page fragment, otherwise return NULL.

 */

static inline struct page *page_pool_dev_alloc_frag(struct page_pool *pool,

						    unsigned int *offset,

						    unsigned int size)

	return page;

}

/**

 * page_pool_dev_alloc() - allocate a page or a page fragment.

 * @pool: pool from which to allocate

 * @offset: offset to the allocated page

 * @size: in as the requested size, out as the allocated size

 *

 * Get a page or a page fragment from the page allocator or page_pool caches

 * depending on the requested size in order to allocate memory with least memory

 * utilization and performance penalty.

 *

 * Return:

 * Return allocated page or page fragment, otherwise return NULL.

 */

static inline struct page *page_pool_dev_alloc(struct page_pool *pool,

					       unsigned int *offset,

					       unsigned int *size)

	return page_address(page) + offset;

}

/**

 * page_pool_dev_alloc_va() - allocate a page or a page fragment and return its

 *			      va.

 * @pool: pool from which to allocate

 * @size: in as the requested size, out as the allocated size

 *

 * This is just a thin wrapper around the page_pool_alloc() API, and

 * it returns va of the allocated page or page fragment.

 *

 * Return:

 * Return the va for the allocated page or page fragment, otherwise return NULL.

 */

static inline void *page_pool_dev_alloc_va(struct page_pool *pool,

					   unsigned int *size)

{

#define PAGE_POOL_32BIT_ARCH_WITH_64BIT_DMA	\

		(sizeof(dma_addr_t) > sizeof(unsigned long))

/**

 * page_pool_free_va() - free a va into the page_pool

 * @pool: pool from which va was allocated

 * @va: va to be freed

 * @allow_direct: freed by the consumer, allow lockless caching

 *

 * Free a va allocated from page_pool_allo_va().

 */

static inline void page_pool_free_va(struct page_pool *pool, void *va,

				     bool allow_direct)

{