[linux-2.6-block.git] / Documentation / vm / page_frags.rst

.. _page_frags:

==============
Page fragments
==============

A page fragment is an arbitrary-length arbitrary-offset area of memory
which resides within a 0 or higher order compound page.  Multiple
fragments within that page are individually refcounted, in the page's
reference counter.

The page_frag functions, page_frag_alloc and page_frag_free, provide a
simple allocation framework for page fragments.  This is used by the
network stack and network device drivers to provide a backing region of
memory for use as either an sk_buff->head, or to be used in the "frags"
portion of skb_shared_info.

In order to make use of the page fragment APIs a backing page fragment
cache is needed.  This provides a central point for the fragment allocation
and tracks allows multiple calls to make use of a cached page.  The
advantage to doing this is that multiple calls to get_page can be avoided
which can be expensive at allocation time.  However due to the nature of
this caching it is required that any calls to the cache be protected by
either a per-cpu limitation, or a per-cpu limitation and forcing interrupts
to be disabled when executing the fragment allocation.

The network stack uses two separate caches per CPU to handle fragment
allocation.  The netdev_alloc_cache is used by callers making use of the
__netdev_alloc_frag and __netdev_alloc_skb calls.  The napi_alloc_cache is
used by callers of the __napi_alloc_frag and __napi_alloc_skb calls.  The
main difference between these two calls is the context in which they may be
called.  The "netdev" prefixed functions are usable in any context as these
functions will disable interrupts, while the "napi" prefixed functions are
only usable within the softirq context.

Many network device drivers use a similar methodology for allocating page
fragments, but the page fragments are cached at the ring or descriptor
level.  In order to enable these cases it is necessary to provide a generic
way of tearing down a page cache.  For this reason __page_frag_cache_drain
was implemented.  It allows for freeing multiple references from a single
page via a single call.  The advantage to doing this is that it allows for
cleaning up the multiple references that were added to a page in order to
avoid calling get_page per allocation.

Alexander Duyck, Nov 29, 2016.
Commit	Line	Data
4a832588 MR	1	.. _page_frags:
	2
	3	==============
4d09d0f4	4	Page fragments
4a832588	5	==============
4d09d0f4 AD	6
	7	A page fragment is an arbitrary-length arbitrary-offset area of memory
	8	which resides within a 0 or higher order compound page. Multiple
	9	fragments within that page are individually refcounted, in the page's
	10	reference counter.
	11
	12	The page_frag functions, page_frag_alloc and page_frag_free, provide a
	13	simple allocation framework for page fragments. This is used by the
	14	network stack and network device drivers to provide a backing region of
	15	memory for use as either an sk_buff->head, or to be used in the "frags"
	16	portion of skb_shared_info.
	17
	18	In order to make use of the page fragment APIs a backing page fragment
	19	cache is needed. This provides a central point for the fragment allocation
	20	and tracks allows multiple calls to make use of a cached page. The
	21	advantage to doing this is that multiple calls to get_page can be avoided
	22	which can be expensive at allocation time. However due to the nature of
	23	this caching it is required that any calls to the cache be protected by
	24	either a per-cpu limitation, or a per-cpu limitation and forcing interrupts
	25	to be disabled when executing the fragment allocation.
	26
	27	The network stack uses two separate caches per CPU to handle fragment
	28	allocation. The netdev_alloc_cache is used by callers making use of the
	29	__netdev_alloc_frag and __netdev_alloc_skb calls. The napi_alloc_cache is
	30	used by callers of the __napi_alloc_frag and __napi_alloc_skb calls. The
	31	main difference between these two calls is the context in which they may be
	32	called. The "netdev" prefixed functions are usable in any context as these
	33	functions will disable interrupts, while the "napi" prefixed functions are
	34	only usable within the softirq context.
	35
	36	Many network device drivers use a similar methodology for allocating page
	37	fragments, but the page fragments are cached at the ring or descriptor
	38	level. In order to enable these cases it is necessary to provide a generic
	39	way of tearing down a page cache. For this reason __page_frag_cache_drain
	40	was implemented. It allows for freeing multiple references from a single
	41	page via a single call. The advantage to doing this is that it allows for
	42	cleaning up the multiple references that were added to a page in order to
	43	avoid calling get_page per allocation.
	44
	45	Alexander Duyck, Nov 29, 2016.