[PATCH] kmalloc man page before 2.6.17

[PATCH] kmalloc man page before 2.6.17

[Paul Drynoff]

Hello.

Currently I with my colleague dispute about quality of code
Linux vs other. And he fairly point me that linux kernel even
have no manual entry for "kmalloc".

So please consider include this or similar patch before 2.6.17.
With this patch
scripts/kernel-doc -man -function kmalloc mm/slob.c  | nroff -man | less
create man page for "kmalloc"

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,7 +3244,7 @@ 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.
  * @caller: function caller for debug tracking of the caller
Index: linux-2.6.17-rc4/mm/slob.c
===================================================================
--- linux-2.6.17-rc4.orig/mm/slob.c
+++ linux-2.6.17-rc4/mm/slob.c
@@ -158,6 +158,27 @@ static int fastcall find_order(int size)
 	return order;
 }

+/**
+ * kmalloc - allocate memory
+ * @size: how many bytes of memory are required.
+ * @gfp: the type of memory to allocate.
+ *
+ * kmalloc is the normal method of allocating memory
+ * in the kernel.
+ *
+ * The @gfp 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.
+ */
 void *kmalloc(size_t size, gfp_t gfp)
 {
 	slob_t *m;

Re: [PATCH] kmalloc man page before 2.6.17

[Pekka Enberg]

Hi Paul,

On 5/26/06, Paul Drynoff <pauldrynoff@gmail.com> wrote:
> Currently I with my colleague dispute about quality of code
> Linux vs other. And he fairly point me that linux kernel even
> have no manual entry for "kmalloc".
>
> So please consider include this or similar patch before 2.6.17.
> With this patch
> scripts/kernel-doc -man -function kmalloc mm/slob.c  | nroff -man | less
> create man page for "kmalloc"

Duplicating the comment in mm/slob.c seems pointless. I think we could
move the comment to include/linux/slab.h from mm/slab.c assuming the
kerneldoc script picks it up from there.

                                                   Pekka

Re: [PATCH] kmalloc man page before 2.6.17

[Paul Drynoff]

Actually, this is not full duplication:
__do_kmalloc(size_t size, gfp_t flags,
                                          void *caller)
and
void *kmalloc(size_t size, gfp_t gfp)

they have different amount of arguments and different arguments names.

But as I see include/linux/slab.h is better place. See patch.

It will be great to create another entry for flags of "kmalloc* family
functions,
so we can avoid duplication of this in __do_kmalloc and kmalloc
comments, but I don't know is it possible with scripts/kernel-doc.

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,7 +3244,7 @@ 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.
  * @caller: function caller for debug tracking of the caller
Index: linux-2.6.17-rc4/include/linux/slab.h
===================================================================
--- linux-2.6.17-rc4.orig/include/linux/slab.h
+++ linux-2.6.17-rc4/include/linux/slab.h
@@ -87,6 +87,27 @@ extern void *__kmalloc_track_caller(size
     __kmalloc_track_caller(size, flags, __builtin_return_address(0))
 #endif

+/**
+ * kmalloc - allocate memory
+ * @size: how many bytes of memory are required.
+ * @gfp: the type of memory to allocate.
+ *
+ * kmalloc is the normal method of allocating memory
+ * in the kernel.
+ *
+ * The @gfp 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.
+ */
 static inline void *kmalloc(size_t size, gfp_t flags)
 {
 	if (__builtin_constant_p(size)) {

Re: [PATCH] kmalloc man page before 2.6.17

[Pekka J Enberg]

On Fri, 26 May 2006, Paul Drynoff wrote:
> Actually, this is not full duplication:
> __do_kmalloc(size_t size, gfp_t flags,
>                                          void *caller)
> and
> void *kmalloc(size_t size, gfp_t gfp)
> 
> they have different amount of arguments and different arguments names.
> 
> But as I see include/linux/slab.h is better place. See patch.
> 
> It will be great to create another entry for flags of "kmalloc* family
> functions,
> so we can avoid duplication of this in __do_kmalloc and kmalloc
> comments, but I don't know is it possible with scripts/kernel-doc.
> 
> Signed-off-by: Paul Drynoff <pauldrynoff@gmail.com>

Just drop the __do_kmalloc() comment completely.  Did you check that 
kerneldoc picks it up for the generated API docs?  Btw, you should send 
this to Andrew at akpm@osdl.org instead of Linus.

				Pekka

Re: [PATCH] kmalloc man page before 2.6.17

[Paul Drynoff]

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.
  */
 static __always_inline void *__do_kmalloc(size_t size, gfp_t flags,
 					  void *caller)
Index: linux-2.6.17-rc4/include/linux/slab.h
===================================================================
--- linux-2.6.17-rc4.orig/include/linux/slab.h
+++ linux-2.6.17-rc4/include/linux/slab.h
@@ -87,6 +87,27 @@ extern void *__kmalloc_track_caller(size
     __kmalloc_track_caller(size, flags, __builtin_return_address(0))
 #endif

+/**
+ * kmalloc - allocate memory
+ * @size: how many bytes of memory are required.
+ * @gfp: the type of memory to allocate.
+ *
+ * kmalloc is the normal method of allocating memory
+ * in the kernel.
+ *
+ * The @gfp 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.
+ */
 static inline void *kmalloc(size_t size, gfp_t flags)
 {
 	if (__builtin_constant_p(size)) {

Re: [PATCH] kmalloc man page before 2.6.17

[Andrey Panin]

[-- Attachment #1: Type: text/plain, Size: 3639 bytes --]

On 146, 05 26, 2006 at 12:20:56PM +0400, Paul Drynoff wrote:
> Currently kernel-doc doesn't produce the man page for "kmalloc",

Of course it doesn't. You need to add line

!Iinclude/linux/slab.h

into Documentation/DocBook/kernel-api.tmpl. And BTW you can add comment
for kzalloc() too. Something like this:

/**
 * kzalloc - allocate memory. The memory is set to zero.
 * @size: how many bytes of memory are required.
 * @flags: the type of memory to allocate.
 */

> 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.
>  */
> static __always_inline void *__do_kmalloc(size_t size, gfp_t flags,
> 					  void *caller)
> Index: linux-2.6.17-rc4/include/linux/slab.h
> ===================================================================
> --- linux-2.6.17-rc4.orig/include/linux/slab.h
> +++ linux-2.6.17-rc4/include/linux/slab.h
> @@ -87,6 +87,27 @@ extern void *__kmalloc_track_caller(size
>     __kmalloc_track_caller(size, flags, __builtin_return_address(0))
> #endif
> 
> +/**
> + * kmalloc - allocate memory
> + * @size: how many bytes of memory are required.
> + * @gfp: the type of memory to allocate.
> + *
> + * kmalloc is the normal method of allocating memory
> + * in the kernel.
> + *
> + * The @gfp 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.
> + */
> static inline void *kmalloc(size_t size, gfp_t flags)
> {
> 	if (__builtin_constant_p(size)) {
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
> 

-- 
Andrey Panin		| Linux and UNIX system administrator
pazke@donpac.ru		| PGP key: wwwkeys.pgp.net

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] kmalloc man page before 2.6.17

[Jesper Juhl]

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

Re: [PATCH] kmalloc man page before 2.6.17

[Paul Drynoff]

Thanks everyone for comments.
Here is new patch: it make possible creation of kmalloc(9)
and kzalloc(9).

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.
  */
 static __always_inline void *__do_kmalloc(size_t size, gfp_t flags,
 					  void *caller)
Index: linux-2.6.17-rc4/include/linux/slab.h
===================================================================
--- linux-2.6.17-rc4.orig/include/linux/slab.h
+++ linux-2.6.17-rc4/include/linux/slab.h
@@ -87,6 +87,45 @@ extern void *__kmalloc_track_caller(size
     __kmalloc_track_caller(size, flags, __builtin_return_address(0))
 #endif

+/**
+ * kmalloc - allocate memory
+ * @size: how many bytes of memory are required.
+ * @gfp: the type of memory to allocate.
+ *
+ * kmalloc is the normal method of allocating memory
+ * in the kernel.
+ *
+ * The @gfp 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.
+ * %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.
+ *
+ * Also it is possible 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.
+ */
 static inline void *kmalloc(size_t size, gfp_t flags)
 {
 	if (__builtin_constant_p(size)) {
@@ -112,6 +151,11 @@ found:

 extern void *__kzalloc(size_t, gfp_t);

+/**
+ * kzalloc - allocate memory. The memory is set to zero.
+ * @size: how many bytes of memory are required.
+ * @flags: the type of memory to allocate(see kmalloc).
+ */
 static inline void *kzalloc(size_t size, gfp_t flags)
 {
 	if (__builtin_constant_p(size)) {
Index: linux-2.6.17-rc4/Documentation/DocBook/kernel-api.tmpl
===================================================================
--- linux-2.6.17-rc4.orig/Documentation/DocBook/kernel-api.tmpl
+++ linux-2.6.17-rc4/Documentation/DocBook/kernel-api.tmpl
@@ -124,6 +124,7 @@ X!Ilib/string.c
 !Earch/i386/lib/usercopy.c
      </sect1>
      <sect1><title>More Memory Management Functions</title>
+!Iinclude/linux/slab.h
 !Iinclude/linux/rmap.h
 !Emm/readahead.c
 !Emm/filemap.c

Re: [PATCH] kmalloc man page before 2.6.17

[Paul Drynoff]

On 5/26/06, Jesper Juhl <jesper.juhl@gmail.com> wrote:
> Btw: how about vmalloc() do we need to document that one as well
> (didn't check) ?
>

There are vmalloc(9) and vfree(9) on my machine, so I suppose all ok
with this functions.

Re: [PATCH] kmalloc man page before 2.6.17

[Paulo Marques]

Paul Drynoff wrote:
> [...]
> + * %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.

I find this comment to be a little misleading. GFP_ATOMIC should be used 
on _any_ code that can not sleep, including sections protected by a 
spinlock and sections that run with IRQ's disabled, no?

-- 
Paulo Marques - www.grupopie.com

Pointy-Haired Boss: I don't see anything that could stand in our way.
            Dilbert: Sanity? Reality? The laws of physics?

Re: [PATCH] kmalloc man page before 2.6.17

[Christoph Lameter]

On Fri, 26 May 2006, Paul Drynoff wrote:

> Thanks everyone for comments.
> Here is new patch: it make possible creation of kmalloc(9)
> and kzalloc(9).

Documentation of in kernel functions in the manpages <boogle>. You are 
going to do this full time in order to keep all of it up to date?

In that case you should add something to install the manpages 
for each kernel when one does

make install_man

from the top of the kernel tree.

Re: [PATCH] kmalloc man page before 2.6.17

[Paul Drynoff]

On 5/26/06, Christoph Lameter <clameter@sgi.com> wrote:
> Documentation of in kernel functions in the manpages <boogle>.
Why not, this is common practic for big set of Unix lie OS.
You can type something like:
man VFS man vnops and so on.

> You are
> going to do this full time in order to keep all of it up to date?
>
> In that case you should add something to install the manpages
> for each kernel when one does
>
Why? In my Linux OS I should only type something like:
package-manager install vanilla-sources
or
package-manager install git-sources

and I'll get all documentation generated by "make mandocs" in
/usr/share/man/man9

Re: [PATCH] kmalloc man page before 2.6.17

[Christoph Lameter]

On Fri, 26 May 2006, Paul Drynoff wrote:

> Why? In my Linux OS I should only type something like:
> package-manager install vanilla-sources
> or
> package-manager install git-sources
> 
> and I'll get all documentation generated by "make mandocs" in
> /usr/share/man/man9

Many of us are continually installing kernels again and again for testing 
on a variety of platforms. It would be good to have a package manager 
agnostic version.

Also: Usually the packaging scripts use "make installman" or so to trigger 
the manpage installation.

Re: [PATCH] kmalloc man page before 2.6.17

[Luca]

Paul Drynoff <pauldrynoff@gmail.com> ha scritto:
> Thanks everyone for comments.
> Here is new patch: it make possible creation of kmalloc(9)
> and kzalloc(9).
[...]

A few of minor things:

> Index: linux-2.6.17-rc4/include/linux/slab.h
> ===================================================================
> --- linux-2.6.17-rc4.orig/include/linux/slab.h
> +++ linux-2.6.17-rc4/include/linux/slab.h
> @@ -87,6 +87,45 @@ extern void *__kmalloc_track_caller(size
>     __kmalloc_track_caller(size, flags, __builtin_return_address(0))
> #endif
> 
> +/**
> + * kmalloc - allocate memory
> + * @size: how many bytes of memory are required.
> + * @gfp: the type of memory to allocate.
> + *
> + * kmalloc is the normal method of allocating memory
> + * in the kernel.
> + *
> + * The @gfp 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.
> + * %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.
> + *
> + * Also it is possible 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

Missing dot at EOL.

> + * %__GFP_HIGH
> + *  - This allocation is high priority and may use emergency pools.

Not sure about this one, but: is "allocation is high priority" correct?
"This allocation has high priority" sounds better to me.

> + * %__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.

immediately

> + * %__GFP_NOWARN
> + * - If allocation fails, don't issue any warnings.
> + * %__GFP_REPEAT
> + * - If allocation fails initially, try once more before failing.
> + */
> static inline void *kmalloc(size_t size, gfp_t flags)
> {
>        if (__builtin_constant_p(size)) {
> @@ -112,6 +151,11 @@ found:
> 
> extern void *__kzalloc(size_t, gfp_t);
> 
> +/**
> + * kzalloc - allocate memory. The memory is set to zero.
> + * @size: how many bytes of memory are required.
> + * @flags: the type of memory to allocate(see kmalloc).

Space before opening '('?


Luca
-- 
Home: http://kronoz.cjb.net
"La vita potrebbe non avere alcun significato. Oppure, ancora peggio,
 potrebbe averne uno che disapprovo". -- Ashleigh Brilliant

Re: [PATCH] kmalloc man page before 2.6.17

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 1828 bytes --]

hoi :)

thank you for your work!

unfortunately gmail seems to have corrupted your patch slightly
(single spaces on it's own line are stripped).

On Fri, May 26, 2006 at 02:44:08PM +0400, Paul Drynoff wrote:
> +/**
> + * kmalloc - allocate memory
> + * @size: how many bytes of memory are required.
> + * @gfp: the type of memory to allocate.

this should be @flags

> + * kmalloc is the normal method of allocating memory
> + * in the kernel.
> + *
> + * The @gfp 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.
> + * %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.

please add newlines here, too.

> + * Also it is possible 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.

and here, too.

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]