Documentation/core-api/genalloc.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/genalloc.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/genalloc.rst
Extension
.rst
Size
5856 bytes
Lines
145
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

The genalloc/genpool subsystem
==============================

There are a number of memory-allocation subsystems in the kernel, each
aimed at a specific need.  Sometimes, however, a kernel developer needs to
implement a new allocator for a specific range of special-purpose memory;
often that memory is located on a device somewhere.  The author of the
driver for that device can certainly write a little allocator to get the
job done, but that is the way to fill the kernel with dozens of poorly
tested allocators.  Back in 2005, Jes Sorensen lifted one of those
allocators from the sym53c8xx_2 driver and posted_ it as a generic module
for the creation of ad hoc memory allocators.  This code was merged
for the 2.6.13 release; it has been modified considerably since then.

.. _posted: https://lwn.net/Articles/125842/

Code using this allocator should include <linux/genalloc.h>.  The action
begins with the creation of a pool using one of:

.. kernel-doc:: lib/genalloc.c
   :functions: gen_pool_create		

.. kernel-doc:: lib/genalloc.c
   :functions: devm_gen_pool_create

A call to gen_pool_create() will create a pool.  The granularity of
allocations is set with min_alloc_order; it is a log-base-2 number like
those 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 a
multiple of eight bytes.  Increasing min_alloc_order decreases the memory
required to track the memory in the pool.  The nid parameter specifies
which NUMA node should be used for the allocation of the housekeeping
structures; it can be -1 if the caller doesn't care.

The "managed" interface devm_gen_pool_create() ties the pool to a
specific device.  Among other things, it will automatically clean up the
pool when the given device is destroyed.

A pool is shut down with:

.. kernel-doc:: lib/genalloc.c
   :functions: gen_pool_destroy

It's worth noting that, if there are still allocations outstanding from the
given pool, this function will take the rather extreme step of invoking
BUG(), crashing the entire system.  You have been warned.

A freshly created pool has no memory to allocate.  It is fairly useless in
that state, so one of the first orders of business is usually to add memory
to the pool.  That can be done with one of:

.. kernel-doc:: include/linux/genalloc.h
   :functions: gen_pool_add

.. kernel-doc:: lib/genalloc.c
   :functions: gen_pool_add_owner

A call to gen_pool_add() will place the size bytes of memory
starting at addr (in the kernel's virtual address space) into the given
pool, once again using nid as the node ID for ancillary memory allocations.
The gen_pool_add_virt() variant associates an explicit physical
address with the memory; this is only necessary if the pool will be used
for DMA allocations.

The functions for allocating memory from the pool (and putting it back)
are:

.. kernel-doc:: include/linux/genalloc.h
   :functions: gen_pool_alloc

Annotation

Implementation Notes