The genalloc/genpool subsystem¶
There are a number of memory-allocation subsystems in the kernel, eachaimed at a specific need. Sometimes, however, a kernel developer needs toimplement a new allocator for a specific range of special-purpose memory;often that memory is located on a device somewhere. The author of thedriver for that device can certainly write a little allocator to get thejob done, but that is the way to fill the kernel with dozens of poorlytested allocators. Back in 2005, Jes Sorensen lifted one of thoseallocators from the sym53c8xx_2 driver andposted it as a generic modulefor the creation of ad hoc memory allocators. This code was mergedfor the 2.6.13 release; it has been modified considerably since then.
Code using this allocator should include <linux/genalloc.h>. The actionbegins with the creation of a pool using one of:
- struct gen_pool *
gen_pool_create(int min_alloc_order, int nid)¶ create a new special memory pool
Parameters
intmin_alloc_order- log base 2 of number of bytes each bitmap bit represents
intnid- node id of the node the pool structure should be allocated on, or -1
Description
Create a new special memory pool that can be used to manage special purposememory not managed by the regular kmalloc/kfree interface.
- struct gen_pool *
devm_gen_pool_create(structdevice * dev, int min_alloc_order, int nid, const char * name)¶ managed gen_pool_create
Parameters
structdevice*dev- device that provides the gen_pool
intmin_alloc_order- log base 2 of number of bytes each bitmap bit represents
intnid- node selector for allocated gen_pool,
NUMA_NO_NODEfor all nodes constchar*name- name of a gen_pool or NULL, identifies a particular gen_pool on device
Description
Create a new special memory pool that can be used to manage special purposememory not managed by the regular kmalloc/kfree interface. The pool will beautomatically destroyed by the device management code.
A call togen_pool_create() will create a pool. The granularity ofallocations is set with min_alloc_order; it is a log-base-2 number likethose used by the page allocator, but it refers to bytes rather than pages.So, if min_alloc_order is passed as 3, then all allocations will be amultiple of eight bytes. Increasing min_alloc_order decreases the memoryrequired to track the memory in the pool. The nid parameter specifieswhich NUMA node should be used for the allocation of the housekeepingstructures; it can be -1 if the caller doesn’t care.
The “managed” interfacedevm_gen_pool_create() ties the pool to aspecific device. Among other things, it will automatically clean up thepool when the given device is destroyed.
A pool is shut down with:
- void
gen_pool_destroy(struct gen_pool * pool)¶ destroy a special memory pool
Parameters
structgen_pool*pool- pool to destroy
Description
Destroy the specified special memory pool. Verifies that there are nooutstanding allocations.
It’s worth noting that, if there are still allocations outstanding from thegiven pool, this function will take the rather extreme step of invokingBUG(), crashing the entire system. You have been warned.
A freshly created pool has no memory to allocate. It is fairly useless inthat state, so one of the first orders of business is usually to add memoryto the pool. That can be done with one of:
- int
gen_pool_add(struct gen_pool * pool, unsigned long addr, size_t size, int nid)¶ add a new chunk of special memory to the pool
Parameters
structgen_pool*pool- pool to add new memory chunk to
unsignedlongaddr- starting address of memory chunk to add to pool
size_tsize- size in bytes of the memory chunk to add to pool
intnid- node id of the node the chunk structure and bitmap should beallocated on, or -1
Description
Add a new chunk of special memory to the specified pool.
Returns 0 on success or a -ve errno on failure.
- int
gen_pool_add_owner(struct gen_pool * pool, unsigned long virt, phys_addr_t phys, size_t size, int nid, void * owner)¶ add a new chunk of special memory to the pool
Parameters
structgen_pool*pool- pool to add new memory chunk to
unsignedlongvirt- virtual starting address of memory chunk to add to pool
phys_addr_tphys- physical starting address of memory chunk to add to pool
size_tsize- size in bytes of the memory chunk to add to pool
intnid- node id of the node the chunk structure and bitmap should beallocated on, or -1
void*owner- private data the publisher would like to recall at alloc time
Description
Add a new chunk of special memory to the specified pool.
Returns 0 on success or a -ve errno on failure.
A call togen_pool_add() will place the size bytes of memorystarting at addr (in the kernel’s virtual address space) into the givenpool, once again using nid as the node ID for ancillary memory allocations.The gen_pool_add_virt() variant associates an explicit physicaladdress with the memory; this is only necessary if the pool will be usedfor DMA allocations.
The functions for allocating memory from the pool (and putting it back)are:
- unsigned long
gen_pool_alloc(struct gen_pool * pool, size_t size)¶ allocate special memory from the pool
Parameters
structgen_pool*pool- pool to allocate from
size_tsize- number of bytes to allocate from the pool
Description
Allocate the requested number of bytes from the specified pool.Uses the pool allocation function (with first-fit algorithm by default).Can not be used in NMI handler on architectures withoutNMI-safe cmpxchg implementation.
- void *
gen_pool_dma_alloc(struct gen_pool * pool, size_t size, dma_addr_t * dma)¶ allocate special memory from the pool for DMA usage
Parameters
structgen_pool*pool- pool to allocate from
size_tsize- number of bytes to allocate from the pool
dma_addr_t*dma- dma-view physical address return value. Use
NULLif unneeded.
Description
Allocate the requested number of bytes from the specified pool.Uses the pool allocation function (with first-fit algorithm by default).Can not be used in NMI handler on architectures withoutNMI-safe cmpxchg implementation.
Return
virtual address of the allocated memory, orNULL on failure
- void
gen_pool_free_owner(struct gen_pool * pool, unsigned long addr, size_t size, void ** owner)¶ free allocated special memory back to the pool
Parameters
structgen_pool*pool- pool to free to
unsignedlongaddr- starting address of memory to free back to pool
size_tsize- size in bytes of memory to free
void**owner- private data stashed at
gen_pool_add()time
Description
Free previously allocated special memory back to the specifiedpool. Can not be used in NMI handler on architectures withoutNMI-safe cmpxchg implementation.
As one would expect,gen_pool_alloc() will allocate size< bytesfrom the given pool. Thegen_pool_dma_alloc() variant allocatesmemory for use with DMA operations, returning the associated physicaladdress in the space pointed to by dma. This will only work if the memorywas added with gen_pool_add_virt(). Note that this functiondeparts from the usual genpool pattern of using unsigned long values torepresent kernel addresses; it returns a void * instead.
That all seems relatively simple; indeed, some developers clearly found itto be too simple. After all, the interface above provides no control overhow the allocation functions choose which specific piece of memory toreturn. If that sort of control is needed, the following functions will beof interest:
- unsigned long
gen_pool_alloc_algo_owner(struct gen_pool * pool, size_t size, genpool_algo_t algo, void * data, void ** owner)¶ allocate special memory from the pool
Parameters
structgen_pool*pool- pool to allocate from
size_tsize- number of bytes to allocate from the pool
genpool_algo_talgo- algorithm passed from caller
void*data- data passed to algorithm
void**owner- optionally retrieve the chunk owner
Description
Allocate the requested number of bytes from the specified pool.Uses the pool allocation function (with first-fit algorithm by default).Can not be used in NMI handler on architectures withoutNMI-safe cmpxchg implementation.
- void
gen_pool_set_algo(struct gen_pool * pool, genpool_algo_t algo, void * data)¶ set the allocation algorithm
Parameters
structgen_pool*pool- pool to change allocation algorithm
genpool_algo_talgo- custom algorithm function
void*data- additional data used byalgo
Description
Callalgo for each memory allocation in the pool.Ifalgo is NULL use gen_pool_first_fit as defaultmemory allocation function.
Allocations with gen_pool_alloc_algo() specify an algorithm to beused to choose the memory to be allocated; the default algorithm can be setwithgen_pool_set_algo(). The data value is passed to thealgorithm; most ignore it, but it is occasionally needed. One can,naturally, write a special-purpose algorithm, but there is a fair setalready available:
- gen_pool_first_fit is a simple first-fit allocator; this is the defaultalgorithm if none other has been specified.
- gen_pool_first_fit_align forces the allocation to have a specificalignment (passed via data in a genpool_data_align structure).
- gen_pool_first_fit_order_align aligns the allocation to the order of thesize. A 60-byte allocation will thus be 64-byte aligned, for example.
- gen_pool_best_fit, as one would expect, is a simple best-fit allocator.
- gen_pool_fixed_alloc allocates at a specific offset (passed in agenpool_data_fixed structure via the data parameter) within the pool.If the indicated memory is not available the allocation fails.
There is a handful of other functions, mostly for purposes like queryingthe space available in the pool or iterating through chunks of memory.Most users, however, should not need much beyond what has been describedabove. With luck, wider awareness of this module will help to prevent thewriting of special-purpose memory allocators in the future.
- phys_addr_t
gen_pool_virt_to_phys(struct gen_pool * pool, unsigned long addr)¶ return the physical address of memory
Parameters
structgen_pool*pool- pool to allocate from
unsignedlongaddr- starting address of memory
Description
Returns the physical address on success, or -1 on error.
- void
gen_pool_for_each_chunk(struct gen_pool * pool, void (*func)(struct gen_pool *pool, struct gen_pool_chunk *chunk, void *data), void * data)¶ call func for every chunk of generic memory pool
Parameters
structgen_pool*pool- the generic memory pool
void(*)(structgen_pool*pool,structgen_pool_chunk*chunk,void*data)func- func to call
void*data- additional data used byfunc
Description
Callfunc for every chunk of generic memory pool. Thefunc iscalled with rcu_read_lock held.
- bool
gen_pool_has_addr(struct gen_pool * pool, unsigned long start, size_t size)¶ checks if an address falls within the range of a pool
Parameters
structgen_pool*pool- the generic memory pool
unsignedlongstart- start address
size_tsize- size of the region
Description
Check if the range of addresses falls within the specified pool. Returnstrue if the entire range is contained in the pool and false otherwise.
- size_t
gen_pool_avail(struct gen_pool * pool)¶ get available free space of the pool
Parameters
structgen_pool*pool- pool to get available free space
Description
Return available free space of the specified pool.
- size_t
gen_pool_size(struct gen_pool * pool)¶ get size in bytes of memory managed by the pool
Parameters
structgen_pool*pool- pool to get size
Description
Return size in bytes of memory managed by the pool.
- struct gen_pool *
gen_pool_get(structdevice * dev, const char * name)¶ Obtain the gen_pool (if any) for a device
Parameters
structdevice*dev- device to retrieve the gen_pool from
constchar*name- name of a gen_pool or NULL, identifies a particular gen_pool on device
Description
Returns the gen_pool for the device if one is present, or NULL.
- struct gen_pool *
of_gen_pool_get(struct device_node * np, const char * propname, int index)¶ find a pool by phandle property
Parameters
structdevice_node*np- device node
constchar*propname- property name containing phandle(s)
intindex- index into the phandle array
Description
Returns the pool that contains the chunk starting at the physicaladdress of the device tree node pointed at by the phandle property,or NULL if not found.