KMALLOC(9)

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_KERNEL, 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 available.
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 kmalloc 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 mistakenly allocated pages will be freed. This function 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 allocated. 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 memory 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 memory 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