Re: [PATCH] kmalloc man page before 2.6.17 v. 2

Re: [PATCH] kmalloc man page before 2.6.17 v. 2

[Paul Drynoff]

On 5/26/06, Paulo Marques <pmarques@grupopie.com> wrote:
> 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?

Is this better?

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,46 @@ 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.
+ *   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 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 +152,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