On 2024/5/9 8:44, Randy Dunlap wrote: > > > On 5/8/24 6:34 AM, Yunsheng Lin wrote: >> Update documentation about design, implementation and API usages >> for page_frag. >> >> CC: Alexander Duyck <alexander.duyck@xxxxxxxxx> >> Signed-off-by: Yunsheng Lin <linyunsheng@xxxxxxxxxx> >> --- >> Documentation/mm/page_frags.rst | 156 +++++++++++++++++++++++++++++++- >> include/linux/page_frag_cache.h | 96 ++++++++++++++++++++ >> mm/page_frag_cache.c | 65 ++++++++++++- >> 3 files changed, 314 insertions(+), 3 deletions(-) >> >> diff --git a/Documentation/mm/page_frags.rst b/Documentation/mm/page_frags.rst >> index 503ca6cdb804..9c25c0fd81f0 100644 >> --- a/Documentation/mm/page_frags.rst >> +++ b/Documentation/mm/page_frags.rst >> @@ -1,3 +1,5 @@ >> +.. SPDX-License-Identifier: GPL-2.0 >> + >> ============== >> Page fragments >> ============== >> @@ -40,4 +42,156 @@ 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. >> + >> +Architecture overview >> +===================== >> + >> +.. code-block:: none >> + >> + +----------------------+ >> + | page_frag API caller | >> + +----------------------+ >> + ^ >> + | >> + | >> + | >> + v >> + +------------------------------------------------+ >> + | request page fragment | >> + +------------------------------------------------+ >> + ^ ^ ^ >> + | | Cache not enough | >> + | Cache empty v | >> + | +-----------------+ | >> + | | drain old cache | | >> + | +-----------------+ | >> + | ^ | >> + | | | >> + v v | >> + +----------------------------------+ | >> + | refill cache with order 3 page | | >> + +----------------------------------+ | >> + ^ ^ | >> + | | | >> + | | Refill failed | >> + | | | Cache is enough >> + | | | >> + | v | >> + | +----------------------------------+ | >> + | | refill cache with order 0 page | | >> + | +----------------------------------+ | >> + | ^ | >> + | Refill succeed | | >> + | | Refill succeed | >> + | | | >> + v v v >> + +------------------------------------------------+ >> + | allocate fragment from cache | >> + +------------------------------------------------+ >> + >> +API interface >> +============= >> +As the design and implementation of page_frag API implies, the allocation side >> +does not allow concurrent calling. Instead it is assumed that the caller must >> +ensure there is not concurrent alloc calling to the same page_frag_cache >> +instance by using its own lock or rely on some lockless guarantee like NAPI >> +softirq. >> + >> +Depending on different aligning requirement, the page_frag API caller may call >> +page_frag_alloc*_align*() to ensure the returned virtual address or offset of >> +the page is aligned according to the 'align/alignment' parameter. Note the size >> +of the allocated fragment is not aligned, the caller need to provide a aligned > > needs to provide an aligned > >> +fragsz if there is a alignment requirement for the size of the fragment. > > an alignment Will update them accordingly, thanks for the review.
