kmalloc

NAME

       __get_free_pages,      get_free_page,     __get_free_page,
       __get_dma_pages, free_pages,  free_page,  kmalloc,  kfree,
       kfree_s, vmalloc, vfree - Allocate and free dynamic kernel
       memory

SYNOPSIS

       #include <linux/malloc.h>
       #include <linux/mm.h>

       unsigned long __get_free_pages(int priority, unsigned long gfporder);
       unsigned long __get_free_page(int priority);
       unsigned long get_free_page(int priority);
       void free_pages(unsigned long addr, unsigned long order);
       void free_page(addr);
       void *kmalloc (size_t size, int priority)
       void kfree_s(void * obj, int size);
       void kfree(void *obj);
       void * vmalloc(unsigned long size);
       void vfree(void * addr);

DESCRIPTION

       __get_free_pages()
              allocates 2^gfporder consecutive  pages  in  kernel
              space.

              priority is one of GFP_BUFFER, GFP_ATOMIC, GFP_KER-
              NEL, GFP_USER, GFP_NOBUFFER, GFP_NFS or GFP_DMA.

       GFP_BUFFER
              has the lowest priority, and doesn't  try  to  free
              other  pages  if  the requested memory isn't avail-
              able.

       GFP_ATOMIC
              tries to allocate the memory immediately.  The task
              will  not  sleep  if  the  memory  isn't available.
              There is a number of reserved pages for GFP_ATOMIC.
              For  allocating  memory on interrupt this has to be
              used.

       GFP_KERNEL
              is the normal way to allocate memory in the  kernel
              space.  The reserved pages will not be used, and if
              the   memory   is   not   available    immediately,
              try_to_free_page() will be called.

       GFP_USER
              is currently the same as GFP_KERNEL.

       GFP_NOBUFFER
              doesn't  try  to shrink the buffer cache for memory
              allocation. This is used  in kernel for  allocating
              pages for the buffer cache.

       GFP_NFS
              is  the  same  as GFP_KERNEL, but the number of the
              reserved pages  is  lower,  so  this  will  succeed
              faster.

       GFP_DMA
              Has  no  effect in __get_free_pages(). This flag is
              only for use with kmalloc().  For DMA memory  kmal-
              loc or __get_dma_pages should be used.  Description
              of effect see __get_dma_pages().

       __get_dma_pages()
              calls repeatedly  __get_free_pages()  until   pages
              suitable for dma are found.  After success the mis-
              takenly allocated pages will be freed.  This  func-
              tion  is  necessary  because  PC DMA controlles are
              limited to 16MB.   DMA  Pages  may  not  cross  64k
              boundaries.  This  is  guaranteed by the allocation
              algorithm of __get_free_pages(). This function

       __get_free_page()
              allocates one  page.  It's  a   macro  which  calls
              __get_free_pages() with gfporder 0.

       get_free_page()
              Same  as  __get_free_page(),  except  the allocated
              memory is set to zero.

       free_pages()
              frees  the  memory space starting  at  addr,  which
              must  have  been  returned  by a previous  call  to
              __get_free_pages().   order  has  to  be  the  same
              __get_free_pages() was called with.  Note that addr
              is unsigned long.

       free_page()
              frees the memory page starting at addr, which  must
              have   been   returned   by   a  previous  call  to
              __get_free_page() or  get_free_page().   Note  that
              addr is unsigned long.

       kmalloc()
              allocates  size bytes, and returns a pointer to the
              allocated memory.  On  i386  the  following  bucket
              sizes  are  possible:  24, 56, 120, 244, 500, 1012,
              2032, 4072, 8168, 16360, 32744,  65512  and  131048
              bytes.  ( See linux/mm/kmalloc.c ) If an other size
              is kmalloc'ed  the the next  bigger  one  is  allo-
              cated. For priority see __get_free_pages.

       kfree_s()
              frees  the  memory  object pointed to by obj.  size
              should be the size of the memory  object  or  zero.
              kfree_s()  determines  the  size of the object from
              the block header. If size is not zero  it  will  be
              checked for being correct.

       kfree()
              frees the memory object pointed to by obj.  It is a
              macro which calls kfree_s() with size zero.

       vmalloc()
              allocates size bytes, and returns a pointer to  the
              allocated  memory.  size  becomes  page  aligned by
              vmalloc(), so the smallest allocated amount is 4kB.
              The  allocated pages are mapped to the virtual mem-
              ory space behind the 1:1 mapped physical memory  in
              the  kernel  space.  Behind  every  vmalloc'ed area
              there is at least one  unmapped  page.  So  writing
              behind the end of a vmalloc'ed area will not result
              in a system crash, but in a segmentation  violation
              in  the kernel space.  Because memory fragmentation
              isn't a big problem for vmalloc(), vmalloc() should
              be used for huge amounts of memory.

       vfree()
              frees  the  virtual memory area pointed to by addr,
              which must have been allocated by a  previous  call
              to vmalloc().

RETURN VALUES

       __get_free_pages(),  __get_free_page()  and  get_free_page
       return on success an unsigned long which is the address of
       the start of the allocated memory, and  should normally be
       cast to a pointer. On failure zero is returned.

       kmalloc and vmalloc return a pointer to the allocated mem-
       ory on success and NULL on failure.

ERRORS

       If    one    of    the    functions    __get_free_pages(),
       __get_free_page(), get_free_page(), or kmalloc() is called
       from  interrupt,  and  priority  is not GFP_ATOMIC, syslog
       will give a warning.

SOURCES

       linux/mm/kmalloc.c
       linux/mm/vmalloc.c
       linux/mm/swap.c
       linux/include/linux/mm.h
       linux/include/linux/malloc.h

BUGS/LIMITAIONS

       Because of memory fragmentation  it's  still  insecure  to
       allocate  areas  of many pages with kmalloc. So for  areas
       bigger than one page vmalloc() should be  used.  Only  for
       DMA kmalloc or __get_dma_pages() has to be used.

AUTHOR

       Linus Torvalds