linux-kernel - Re: [PATCH v2 7/7] docs/core-api: mm-api: add section about GFP flags

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 26 Jul 2018 06:01:06 -0700
From:   Matthew Wilcox <willy@...radead.org>
To:     Mike Rapoport <rppt@...ux.vnet.ibm.com>
Cc:     Jonathan Corbet <corbet@....net>,
        Andrew Morton <akpm@...ux-foundation.org>,
        linux-doc@...r.kernel.org, linux-mm@...ck.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 7/7] docs/core-api: mm-api: add section about GFP flags

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?