Skip to contentSkip to conversation

mm/comments: kmalloc man page before 2.6.17 (the third attempt)

PATCH In review Paul Drynoff 4 participants 7 messages May 28, 2006 – May 30, 2006

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 mm/comments: kmalloc man page before 2.6.17 (the third attempt)

This bugfix patch is added comments to right places and give possibility generate man pages for kmalloc(9) and kzalloc(9).

---

mm/slab.c +2 -18
Index: 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)
include/linux/slab.h +47 -0

59 lines not on this page · raw message

Documentation/DocBook/kernel-api.tmpl +1 -0
Index: 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
#1 lore raw

On 28/05/06, Paul Drynoff <[email protected]> wrote:
[snip]

Quoted 1 line

+ * Also it is possible set different flags by OR'ing

"possible to set different"

Signature · 3 lines
Jesper Juhl <[email protected]>
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
#2 lore raw

PATCH 1/1 mm/comments: kmalloc man page before 2.6.17 (the fourth attempt)

This bugfix patch is added comments to right places and give possibility generate man pages for kmalloc(9) and kzalloc(9).

Changes:
* minor gramatical corrections

---

mm/slab.c +2 -18
Index: 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)
include/linux/slab.h +47 -0

59 lines not on this page · raw message

Documentation/DocBook/kernel-api.tmpl +1 -0
Index: 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
#3 lore raw
In reply to Paul Drynoff

Since no one else seems to have complained about this...

Quoted 11 lines · Paul Drynoff

+/**
+ * kmalloc - allocate memory
+ * @size: how many bytes of memory are required.
+ * @flags: the type of memory to allocate.
+ *
+ * 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.

Quoted 8 lines

+ *
+ * %GFP_KERNEL - Allocate normal kernel ram. May sleep.
+ *
+ * %GFP_ATOMIC - Allocation will not sleep.
+ * For example: 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.

Why are the last four formatted differently from the first two? That is, a newline seems to be missing.

Quoted 13 lines

+ *
+ *
+ * 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 has high priority and may use emergency pools.
+ * %__GFP_HIGHMEM
+ * - Allocated memory may be from highmem.
+ * %__GFP_NOFAIL

Quoted 8 lines

+ * - Indicate that this allocation is in no way allowed to fail
+ * (think twice before using).
+ * %__GFP_NORETRY
+ * - If memory is not immediately 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 why do these have completely different formatting? Please pick one and use that consistently.

Pekka

#4 lore raw

PATCH 1/1 mm/comments: kmalloc man page before 2.6.17 (the fifth attempt)

This bugfix patch is added comments to right places and give possibility generate man pages for kmalloc(9) and kzalloc(9).

Changelog:
* fix formatting issue

---

mm/slab.c +2 -18
Index: 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)
include/linux/slab.h +38 -0
Index: linux-2.6.17-rc4/include/linux/slab.h
===================================================================
@@ -87,6 +87,39 @@ 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.
+ * @flags: the type of memory to allocate.
+ *
+ * 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.
+ *   For example: 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 to 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 has 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 immediately 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 +145,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)) {
Documentation/DocBook/kernel-api.tmpl +1 -0
Index: 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
#5 lore raw

Re: [PATCH] mm/comments: kmalloc man page before 2.6.17 (the fifth attempt)

Quoted 2 lines · On Mon, 29 May 2006 18:33:25 +0400 Paul Drynoff wrote:

This bugfix patch is added comments to right places and give possibility generate man pages for kmalloc(9) and kzalloc(9).

Thanks for doing this. You are right IMO, it was really needed. There are more that are needed if you are up to it.

Quoted 2 lines

Changelog:
* fix formatting issue

You tested this, right? I'm still seeing some formatting issues. Maybe it's my tools. (?)

Quoted 16 lines

Index: linux-2.6.17-rc4/mm/slab.c
===================================================================

mm/slab.c +2 -4
@@ -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

mm/slab.c EXPORT_SYMBOL(kmalloc_node); · line 3262

Quoted 10 lines
mm/slab.c +0 -10
- * 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.
- *

These (almost) blank lines were here for better list-like formatting. Otherwise the lines are run together -- ugly.
I have a patch below to add blank lines back in here plus a few more fixes.

Quoted 59 lines
mm/slab.c +0 -4
- * 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
===================================================================

include/linux/slab.h +33 -0
@@ -87,6 +87,39 @@ 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.
+ * @flags: the type of memory to allocate.
+ *
+ * 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.
+ *   For example: 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 to 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 has 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 immediately 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 +145,11 @@ found:
 
 extern void *__kzalloc(size_t, gfp_t);

Index: linux-2.6.17-rc4/Documentation/DocBook/kernel-api.tmpl
===================================================================

Documentation/DocBook/kernel-api.tmpl X!Ilib/string.c · line 130

Quoted 7 lines
Documentation/DocBook/kernel-api.tmpl +1 -0
@@ -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

Wrong place for that include/ IMO. See patch below.

---
From: Randy Dunlap <[email protected]>

Additional kmalloc kernel-doc formatting cleanups.
Put kmalloc/kzalloc/kcalloc in the slab cache doc section. Only use colon (":") for description/section headings.
Skip a line between "list" elements for better (not run-on) formatting.

---
 Documentation/DocBook/kernel-api.tmpl |    2 +-
 include/linux/slab.h                  |   16 ++++++++++++++--
 2 files changed, 15 insertions(+), 3 deletions(-)
include/linux/slab.h +14 -2
@@ -98,26 +98,38 @@ extern void *__kmalloc_track_caller(size
  * 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.
- *   For example: use inside interrupt handlers.
+ *   For example, use this 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 to set different flags by OR'ing
- * in one or more of the following:
+ * in one or more of the following additional @flags:
  *
  * %__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 has 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 immediately 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)
Documentation/DocBook/kernel-api.tmpl +1 -1
@@ -117,6 +117,7 @@ X!Ilib/string.c
   <chapter id="mm">
      <title>Memory Management in Linux</title>
      <sect1><title>The Slab Cache</title>
+!Iinclude/linux/slab.h
 !Emm/slab.c
      </sect1>
      <sect1><title>User Space Memory Access</title>
@@ -124,7 +125,6 @@ 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
#6 lore raw

Re: [PATCH] mm/comments: kmalloc man page before 2.6.17 (the fifth attempt)

Hi,

Quoted 2 lines · On Mon, 29 May 2006 18:33:25 +0400 Paul Drynoff wrote:
Quoted 2 lines

This bugfix patch is added comments to right places and give possibility generate man pages for kmalloc(9) and kzalloc(9).

Quoted 2 lines · Randy.Dunlap

Thanks for doing this. You are right IMO, it was really needed. There are more that are needed if you are up to it.

Looks good. Thanks.