| Message ID | 1532607722-17079-8-git-send-email-rppt@linux.vnet.ibm.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | memory management documentation updates | expand |
On Thu, Jul 26, 2018 at 03:22:02PM +0300, Mike Rapoport wrote: > +Memory Allocation Controls > +========================== Perhaps call this section "Memory Allocation Flags" instead? > +Linux provides a variety of APIs for memory allocation from direct > +calls to page allocator through slab caches and vmalloc to allocators > +of compressed memory. Although these allocators have different > +semantics and are used in different circumstances, they all share the > +GFP (get free page) flags that control behavior of each allocation > +request. While this isn't /wrong/, I think it might not be the most useful way of explaining what the GFP flags are to someone who's just come across them in some remote part of the kernel. How about this paragraph instead? Functions which need to allocate memory often use GFP flags to express how that memory should be allocated. The GFP acronym stands for "get free pages", the underlying memory allocation function. Not every GFP flag is allowed to every function which may allocate memory. Most users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. > +.. kernel-doc:: include/linux/gfp.h > + :doc: Page mobility and placement hints > + > +.. kernel-doc:: include/linux/gfp.h > + :doc: Watermark modifiers > + > +.. kernel-doc:: include/linux/gfp.h > + :doc: Reclaim modifiers > + > +.. kernel-doc:: include/linux/gfp.h > + :doc: Common combinations Would it make more sense to put 'common combinations' first?
On Thu 26-07-18 06:01:06, Matthew Wilcox wrote: > On Thu, Jul 26, 2018 at 03:22:02PM +0300, Mike Rapoport wrote: > > +Memory Allocation Controls > > +========================== > > Perhaps call this section "Memory Allocation Flags" instead? > > > +Linux provides a variety of APIs for memory allocation from direct > > +calls to page allocator through slab caches and vmalloc to allocators > > +of compressed memory. Although these allocators have different > > +semantics and are used in different circumstances, they all share the > > +GFP (get free page) flags that control behavior of each allocation > > +request. > > While this isn't /wrong/, I think it might not be the most useful way > of explaining what the GFP flags are to someone who's just come across > them in some remote part of the kernel. How about this paragraph instead? > > Functions which need to allocate memory often use GFP flags to express > how that memory should be allocated. The GFP acronym stands for "get > free pages", the underlying memory allocation function. OK. > Not every GFP > flag is allowed to every function which may allocate memory. Most > users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. Or rather than mentioning the two just use "Useful GFP flag combinations" comment segment from gfp.h
On Thu, Jul 26, 2018 at 04:20:39PM +0200, Michal Hocko wrote: > On Thu 26-07-18 06:01:06, Matthew Wilcox wrote: > > On Thu, Jul 26, 2018 at 03:22:02PM +0300, Mike Rapoport wrote: > > > +Memory Allocation Controls > > > +========================== > > > > Perhaps call this section "Memory Allocation Flags" instead? > > > > > +Linux provides a variety of APIs for memory allocation from direct > > > +calls to page allocator through slab caches and vmalloc to allocators > > > +of compressed memory. Although these allocators have different > > > +semantics and are used in different circumstances, they all share the > > > +GFP (get free page) flags that control behavior of each allocation > > > +request. > > > > While this isn't /wrong/, I think it might not be the most useful way > > of explaining what the GFP flags are to someone who's just come across > > them in some remote part of the kernel. How about this paragraph instead? > > > > Functions which need to allocate memory often use GFP flags to express > > how that memory should be allocated. The GFP acronym stands for "get > > free pages", the underlying memory allocation function. > > OK. > > > Not every GFP > > flag is allowed to every function which may allocate memory. Most > > users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. > > Or rather than mentioning the two just use "Useful GFP flag > combinations" comment segment from gfp.h The comment there includes GFP_DMA, GFP_NOIO etc so I'd prefer Matthew's version and maybe even omit GFP_ATOMIC from it. Some grepping shows that roughly 80% of allocations are GFP_KERNEL, 12% are GFP_ATOMIC and ... I didn't count the usage of other flags ;-) > -- > Michal Hocko > SUSE Labs >
On Thu, Jul 26, 2018 at 06:01:06AM -0700, Matthew Wilcox wrote: > On Thu, Jul 26, 2018 at 03:22:02PM +0300, Mike Rapoport wrote: > > +Memory Allocation Controls > > +========================== > > Perhaps call this section "Memory Allocation Flags" instead? > > > +Linux provides a variety of APIs for memory allocation from direct > > +calls to page allocator through slab caches and vmalloc to allocators > > +of compressed memory. Although these allocators have different > > +semantics and are used in different circumstances, they all share the > > +GFP (get free page) flags that control behavior of each allocation > > +request. > > While this isn't /wrong/, I think it might not be the most useful way > of explaining what the GFP flags are to someone who's just come across > them in some remote part of the kernel. How about this paragraph instead? > > Functions which need to allocate memory often use GFP flags to express > how that memory should be allocated. The GFP acronym stands for "get > free pages", the underlying memory allocation function. Not every GFP > flag is allowed to every function which may allocate memory. Most > users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. > > > +.. kernel-doc:: include/linux/gfp.h > > + :doc: Page mobility and placement hints > > + > > +.. kernel-doc:: include/linux/gfp.h > > + :doc: Watermark modifiers > > + > > +.. kernel-doc:: include/linux/gfp.h > > + :doc: Reclaim modifiers > > + > > +.. kernel-doc:: include/linux/gfp.h > > + :doc: Common combinations > > Would it make more sense to put 'common combinations' first? Now I feel that "common combinations" is not really good name since not all of them are that common. The original "Useful ... combination" also does not seem right because use of some of these combinations is discouraged. That said, I think I'm going to change "common combinations" to "GPF flag combinations" (as the comments cover all the defined combinations) and leave it the last.
On Thu, Jul 26, 2018 at 06:18:53PM +0300, Mike Rapoport wrote: > On Thu, Jul 26, 2018 at 04:20:39PM +0200, Michal Hocko wrote: > > > Functions which need to allocate memory often use GFP flags to express > > > how that memory should be allocated. The GFP acronym stands for "get > > > free pages", the underlying memory allocation function. > > > > OK. > > > > > Not every GFP > > > flag is allowed to every function which may allocate memory. Most > > > users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. > > > > Or rather than mentioning the two just use "Useful GFP flag > > combinations" comment segment from gfp.h > > The comment there includes GFP_DMA, GFP_NOIO etc so I'd prefer Matthew's > version and maybe even omit GFP_ATOMIC from it. I'm totally OK with that. > Some grepping shows that roughly 80% of allocations are GFP_KERNEL, 12% are > GFP_ATOMIC and ... I didn't count the usage of other flags ;-) ;-) You'll find a lot of GFP_NOFS and GFP_NOIO in the filesystem/block code ...
On Thu 26-07-18 18:18:53, Mike Rapoport wrote: > On Thu, Jul 26, 2018 at 04:20:39PM +0200, Michal Hocko wrote: > > On Thu 26-07-18 06:01:06, Matthew Wilcox wrote: > > > On Thu, Jul 26, 2018 at 03:22:02PM +0300, Mike Rapoport wrote: > > > > +Memory Allocation Controls > > > > +========================== > > > > > > Perhaps call this section "Memory Allocation Flags" instead? > > > > > > > +Linux provides a variety of APIs for memory allocation from direct > > > > +calls to page allocator through slab caches and vmalloc to allocators > > > > +of compressed memory. Although these allocators have different > > > > +semantics and are used in different circumstances, they all share the > > > > +GFP (get free page) flags that control behavior of each allocation > > > > +request. > > > > > > While this isn't /wrong/, I think it might not be the most useful way > > > of explaining what the GFP flags are to someone who's just come across > > > them in some remote part of the kernel. How about this paragraph instead? > > > > > > Functions which need to allocate memory often use GFP flags to express > > > how that memory should be allocated. The GFP acronym stands for "get > > > free pages", the underlying memory allocation function. > > > > OK. > > > > > Not every GFP > > > flag is allowed to every function which may allocate memory. Most > > > users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. > > > > Or rather than mentioning the two just use "Useful GFP flag > > combinations" comment segment from gfp.h > > The comment there includes GFP_DMA, GFP_NOIO etc so I'd prefer Matthew's > version and maybe even omit GFP_ATOMIC from it. > > Some grepping shows that roughly 80% of allocations are GFP_KERNEL, 12% are > GFP_ATOMIC and ... I didn't count the usage of other flags ;-) Well, I will certainly not insist... I don't know who is the expected audience of this documentation. That section was meant for kernel developers to know which of the high level flags to use.
On Thu, Jul 26, 2018 at 06:41:50PM +0200, Michal Hocko wrote: > On Thu 26-07-18 18:18:53, Mike Rapoport wrote: > > On Thu, Jul 26, 2018 at 04:20:39PM +0200, Michal Hocko wrote: > > > On Thu 26-07-18 06:01:06, Matthew Wilcox wrote: > > > > On Thu, Jul 26, 2018 at 03:22:02PM +0300, Mike Rapoport wrote: > > > > > +Memory Allocation Controls > > > > > +========================== > > > > > > > > Perhaps call this section "Memory Allocation Flags" instead? > > > > > > > > > +Linux provides a variety of APIs for memory allocation from direct > > > > > +calls to page allocator through slab caches and vmalloc to allocators > > > > > +of compressed memory. Although these allocators have different > > > > > +semantics and are used in different circumstances, they all share the > > > > > +GFP (get free page) flags that control behavior of each allocation > > > > > +request. > > > > > > > > While this isn't /wrong/, I think it might not be the most useful way > > > > of explaining what the GFP flags are to someone who's just come across > > > > them in some remote part of the kernel. How about this paragraph instead? > > > > > > > > Functions which need to allocate memory often use GFP flags to express > > > > how that memory should be allocated. The GFP acronym stands for "get > > > > free pages", the underlying memory allocation function. > > > > > > OK. > > > > > > > Not every GFP > > > > flag is allowed to every function which may allocate memory. Most > > > > users will want to use a plain ``GFP_KERNEL`` or ``GFP_ATOMIC``. > > > > > > Or rather than mentioning the two just use "Useful GFP flag > > > combinations" comment segment from gfp.h > > > > The comment there includes GFP_DMA, GFP_NOIO etc so I'd prefer Matthew's > > version and maybe even omit GFP_ATOMIC from it. > > > > Some grepping shows that roughly 80% of allocations are GFP_KERNEL, 12% are > > GFP_ATOMIC and ... I didn't count the usage of other flags ;-) > > Well, I will certainly not insist... I don't know who is the expected > audience of this documentation. That section was meant for kernel > developers to know which of the high level flags to use. Well, as this is kernel api documentation I presume the audience is the same. All the descriptions from include/linux/gfp.h are converted by by kernel-doc and would be included here. This was actually the point of this patch :) > -- > Michal Hocko > SUSE Labs >
diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index b5913aa..3d2a7ec 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -14,6 +14,28 @@ User Space Memory Access .. kernel-doc:: mm/util.c :functions: get_user_pages_fast +Memory Allocation Controls +========================== + +Linux provides a variety of APIs for memory allocation from direct +calls to page allocator through slab caches and vmalloc to allocators +of compressed memory. Although these allocators have different +semantics and are used in different circumstances, they all share the +GFP (get free page) flags that control behavior of each allocation +request. + +.. kernel-doc:: include/linux/gfp.h + :doc: Page mobility and placement hints + +.. kernel-doc:: include/linux/gfp.h + :doc: Watermark modifiers + +.. kernel-doc:: include/linux/gfp.h + :doc: Reclaim modifiers + +.. kernel-doc:: include/linux/gfp.h + :doc: Common combinations + The Slab Cache ==============
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> --- Documentation/core-api/mm-api.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+)