0001 .. _page_frags:
0002
0003 ==============
0004 Page fragments
0005 ==============
0006
0007 A page fragment is an arbitrary-length arbitrary-offset area of memory
0008 which resides within a 0 or higher order compound page. Multiple
0009 fragments within that page are individually refcounted, in the page's
0010 reference counter.
0011
0012 The page_frag functions, page_frag_alloc and page_frag_free, provide a
0013 simple allocation framework for page fragments. This is used by the
0014 network stack and network device drivers to provide a backing region of
0015 memory for use as either an sk_buff->head, or to be used in the "frags"
0016 portion of skb_shared_info.
0017
0018 In order to make use of the page fragment APIs a backing page fragment
0019 cache is needed. This provides a central point for the fragment allocation
0020 and tracks allows multiple calls to make use of a cached page. The
0021 advantage to doing this is that multiple calls to get_page can be avoided
0022 which can be expensive at allocation time. However due to the nature of
0023 this caching it is required that any calls to the cache be protected by
0024 either a per-cpu limitation, or a per-cpu limitation and forcing interrupts
0025 to be disabled when executing the fragment allocation.
0026
0027 The network stack uses two separate caches per CPU to handle fragment
0028 allocation. The netdev_alloc_cache is used by callers making use of the
0029 netdev_alloc_frag and __netdev_alloc_skb calls. The napi_alloc_cache is
0030 used by callers of the __napi_alloc_frag and __napi_alloc_skb calls. The
0031 main difference between these two calls is the context in which they may be
0032 called. The "netdev" prefixed functions are usable in any context as these
0033 functions will disable interrupts, while the "napi" prefixed functions are
0034 only usable within the softirq context.
0035
0036 Many network device drivers use a similar methodology for allocating page
0037 fragments, but the page fragments are cached at the ring or descriptor
0038 level. In order to enable these cases it is necessary to provide a generic
0039 way of tearing down a page cache. For this reason __page_frag_cache_drain
0040 was implemented. It allows for freeing multiple references from a single
0041 page via a single call. The advantage to doing this is that it allows for
0042 cleaning up the multiple references that were added to a page in order to
0043 avoid calling get_page per allocation.
0044
0045 Alexander Duyck, Nov 29, 2016.
