Re: [PATCH] kmalloc man page before 2.6.17

["Jesper Juhl" <jesper.juhl@gmail.com>]

On 26/05/06, Paul Drynoff <pauldrynoff@gmail.com> wrote:
> Currently kernel-doc doesn't produce the man page for "kmalloc",
> I think that is a big lack of documentation. This patch should help.
> Now
> scripts/kernel-doc -man -function kmalloc include/linux/slab.h  |
> nroff -man | less
> creates suitable "man page".
>
> Signed-off-by: Paul Drynoff <pauldrynoff@gmail.com>
>
> ---
>
> Index: linux-2.6.17-rc4/mm/slab.c
> ===================================================================
> --- linux-2.6.17-rc4.orig/mm/slab.c
> +++ linux-2.6.17-rc4/mm/slab.c
> @@ -3244,26 +3244,10 @@ EXPORT_SYMBOL(kmalloc_node);
>  #endif
>
>  /**
> - * kmalloc - allocate memory
> + * __do_kmalloc - allocate memory
>   * @size: how many bytes of memory are required.
> - * @flags: the type of memory to allocate.
> + * @flags: the type of memory to allocate(see kmalloc).
>   * @caller: function caller for debug tracking of the caller
> - *
> - * kmalloc is the normal method of allocating memory
> - * in the kernel.
> - *
> - * The @flags argument may be one of:
> - *
> - * %GFP_USER - Allocate memory on behalf of user.  May sleep.
> - *
> - * %GFP_KERNEL - Allocate normal kernel ram.  May sleep.
> - *
> - * %GFP_ATOMIC - Allocation will not sleep.  Use inside interrupt handlers.
> - *
> - * Additionally, the %GFP_DMA flag may be set to indicate the memory
> - * must be suitable for DMA.  This can mean different things on different
> - * platforms.  For example, on i386, it means that the memory must come
> - * from the first 16MB.

You seem to be missing :

   GFP_HIGHUSER
      - Allocate pages from high memory.
   GFP_NOIO
      - Do not do any I/O at all while trying to get memory.
   GFP_NOFS
      - Do not make any fs calls while trying to get memory.

It might also make sense to document the fact that you can set
different flags by OR'ing in one or more of the following :

   __GFP_COLD
      - Request cache-cold pages instead of trying to return cache-warm pages.
   __GFP_DMA
      - Request memory from the DMA-capable zone
   __GFP_HIGH
      - This allocation is high priority and may use emergency pools.
   __GFP_HIGHMEM
      - Allocated memory may be from highmem.
   __GFP_NOFAIL
      - Indicate that this allocation is in no way allowed to fail
(think twice before using).
   __GFP_NORETRY
      - If memory is not imidiately available, then give up at once.
   __GFP_NOWARN
      - If allocation fails, don't issue any warnings.
   __GFP_REPEAT
      - If allocation fails initially, try once more before failing.


Btw: how about vmalloc() do we need to document that one as well
(didn't check) ?


-- 
Jesper Juhl <jesper.juhl@gmail.com>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html