Re: [PATCH net-next v3 12/13] mm: page_frag: update documentation for page_frag

[Yunsheng Lin <linyunsheng@huawei.com>]

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@gmail.com>
>> Signed-off-by: Yunsheng Lin <linyunsheng@huawei.com>
>> ---
>>  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.