|
|
|
Linux Utils Application Programming Interface (API)
linuxutils-n02
|
Describes the interface to the contiguous memory allocator.
The cmem user interface library wraps file system calls to an associated kernel module (cmemk.ko), which needs to be loaded in order for calls to this library to succeed.
The CMEM kernel module accepts blocks of physical memory and a pool geometry within those blocks. The blocks and pools can be specified either in the traditional command line method, or with the new DT (Device Tree) method. The DT method is the prefered method due to its control by a system integrator.
The following is an example of installing the cmem kernel module using the traditional command line block and pool parameters (a DT example is shown below):
/sbin/insmod cmemk.ko pools=4x30000,2x500000 phys_start=0x0 phys_end=0x3000000
This particular command creates 2 pools. The first pool is created with 4 buffers of size 30000 bytes and the second pool is created with 2 buffers of size 500000 bytes. The CMEM pool buffers start at 0x0 and end at 0x2FFFFFF (max).
There is also support for a 2nd, 3rd, or 4th contiguous memory block to be specified, with all the same features supported for those blocks as with the 1st. This 2nd block is specified with *_1 parameters (and 3rd block with *_2, 4th block with *_3). The following example expands upon the first example above:
/sbin/insmod cmemk.ko pools=4x30000,2x500000 phys_start=0x0 phys_end=0x3000000 pools_1=4x65536 phys_start_1=0x80000000 phys_end_1=0x80010000
This particular command, in addition to the pools explained above, creates 1 pool (with 4 buffers of size 64KB) in a 2nd memory block which starts at 0x80000000 and ends at 0x8000FFFF (specified as "end + 1" on the insmod command).
In order to access blocks beyond the 1st block, new APIs have been added to CMEM which allow specification of the block ID.
There is another configuration "switch" for the cmemk.ko kernel module, which can be specified on the 'insmod' (or 'modprobe') command lines: useHeapIfPoolUnavailable=[0|1]
'useHeapIfPoolUnavailable', when set to 1, will cause pool-based allocations to fallback to a heap-based allocation if no pool buffer of sufficient size is available (the CMEM heap is described below).
Pool buffers are aligned on a module-dependent boundary, and their sizes are rounded up to this same boundary. This applies to each buffer within a pool. The total space used by an individual pool will therefore be greater than (or equal to) the exact amount requested in the installation of the module.
The poolid used in the driver calls would be 0 for the first pool and 1 for the second pool.
Pool allocations can be requested explicitly by pool number, or more generally by just a size. For size-based allocations, the pool which best fits the requested size is automatically chosen. Some CMEM APIs (newer ones) accept a blockid as a parameter, in order to specify which of the multiple blocks to operate on. For 'legacy' APIs (ones that existed before the support for multiple blocks) where a blockid is still needed, block 0 is assumed.
There is also support for a general purpose heap. In addition to the 2 pools described above, a general purpose heap block is created from which allocations of any size can be requested. Internally, allocation sizes are rounded up to a module-dependent boundary and allocation addresses are aligned either to this same boundary or to the requested alignment (whichever is greater).
The size of the heap block is the amount of CMEM memory remaining after all pool allocations. If more heap space is needed than is available after pool allocations, you must reduce the amount of CMEM memory granted to the pools.
Buffer allocation is tracked at the file descriptor level by way of a 'registration' list. The initial allocator of a buffer (the process that calls CMEM_alloc()) is automatically added to the registration list, and further processes can become registered for the same buffer by way of the CMEM_registerAlloc() API (and unregister with the CMEM_unregister() API). This registration list for each buffer allows for buffer ownership tracking and cleanup on a per-file-descriptor basis, so that when a process exits or dies without having explicitly freed/unregistered its buffers, they get automatically unregistered (and freed when no more registered file descriptors exist). Only when the last registered file descriptor frees a buffer (either explictily, or by auto-cleanup) does a buffer actually get freed back to the kernel module.
The Device Tree can be used to specify physical memory blocks and pool geometry within those blocks, with the same capabilities as the command line specification. DT specification is preferred over command line specification for a number of reasons:
CMEM allows both DT-specified and command line specified blocks. Each block is assigned a number that can be later used for allocations in order to direct the allocation to a particular block. This allows some blocks to be defined in the DT and other blocks to be later defined on the CMEM command line. If a particular block number is assigned in DT and also specified on the CMEM command line then the DT specification takes precedence and the command line specification is ignored.
The following DT example snippet illustrates the syntax...
For every CMEM_alloc*() API, there is a corresponding "Phys" API that returns the physical address of the allocation and does not do the user-space memory mapping (mmap()). There is also a corresponding CMEM_freePhys() to be used for freeing allocations performed by the "Phys" APIs. The user-space memory mapping is performed with the CMEM_map()/CMEM_unmap() APIs. This allows large buffer allocations without the burden of using up a large portion of the application's virtual address space for the duration of the allocation's existence. A mapping performed by CMEM_map() doesn't have to be for the whole of the allocated buffer, it can be for just portions of the buffer (but must not be larger than the allocated buffer).
CMEM_map() can be called multiple times for the same physical allocation. Each invocation of CMEM_map() will allocate a new user virtual address range for the same physical allocation.
On systems with CMA (Contiguous Memory Allocator) support, CMEM can be used to allocate CMA buffers. Both heap and pool allocations are supported. A special block ID, CMEM_CMABLOCKID, is used for these allocations, and therefore the block-based CMEM APIs must be used (the ones ending in "2", such as CMEM_alloc2()), where the 'blockid' parameter is CMEM_CMABLOCKID (instead of 0 or 1).
CMA always contains, at the minimum, a global area that can be accessed by any device driver. CMEM treats this global area as a heap, which means that heap-based allocations can be performed on CMEM_CMABLOCKID. See the Linux CMA documentation for details on specifying this global area. Keep in mind that other Linux kernel entities can (and will) also allocate memory from this global area, so you never really know how much is available for allocations by CMEM.
To achieve pool-based allocations from CMA, a special CMEM stub must be builtin to the kernel, and CMEM must be built with CMEM_KERNEL_STUB=1 for the 'make' command (which turns into -DCMEM_KERNEL_STUB on the compile command). This stub processes a kernel command line parameter named "cmem_cma_pools=..." in the same fashion as the standard CMEM "pools=...". A separate CMA region (area) is created for each of the separate "cmem_cma_pools" (where each pool/region is one element of the comma- separated list).
The CMEM builtin kernel stub is located in .../src/cmem/module/kernel/drivers/cmem/cmemk_stub.c You don't need this stub if you want to allocate only from the CMA global area. Please see comments at the head of the above file for instructions on how to incorporate it into your kernel.
In supporting the pool model of CMEM, a separate CMA region is created for each pool. A pool consists of n buffers of size s, resulting in a region that is sized accordingly. CMA places no restrictions on the size of an allocation from a region, so the buffer size 's' becomes more of a convention than a hard rule. Given enough free space, any pool can be used to allocate a buffer of any size, but it is recommended to partition regions (or, in this case, pools) according to the size of buffers that will be allocated in order to reduce fragmentation and wasted memory due to size-based alignment padding. In other words, if your system will be allocating 10 buffers of size 4096, 8 of size 131072, and 4 of size 1048576, create pools of cmem_cma_pools=10x4096,8x131072,4x1048576 and perform allocations from the respective pool.
An application doesn't need to know the pool IDs that correspond to the respective sizes of that pool's buffers. The CMEM_alloc2() API decides which pool to use according to the requested size of allocation, and will choose the one that fits most efficiently. Unlike non-CMA pool allocations where, when the "best fit" pool has no remaining buffers it will choose a pool with larger available buffers, CMEM_alloc2() won't "promote" a CMA-based pool allocation to a pool with buffers larger than the the best fit.
CMEM supports a kernel command line parameter named "cmem_cma_heapsize". When assigned, a CMA region of size "cmem_cma_heapsize" is created for use by CMEM heap allocations for the CMA "block". This heap is then used for CMEM CMA heap allocations, and the CMA global area is no longer used by CMEM. This allows CMEM to have full usage of the CMEM CMA heap without possible allocations by non-CMEM entities in the kernel.
Go to the source code of this file.
Data Structures | |
| struct | CMEM_AllocParams |
| Parameters for CMEM_alloc(), CMEM_alloc2(), CMEM_allocPool(), CMEM_allocPool2(), CMEM_free(). More... | |
| struct | CMEM_BlockAttrs |
Typedefs | |
| typedef struct CMEM_AllocParams | CMEM_AllocParams |
| Parameters for CMEM_alloc(), CMEM_alloc2(), CMEM_allocPool(), CMEM_allocPool2(), CMEM_free(). More... | |
| typedef struct CMEM_BlockAttrs | CMEM_BlockAttrs |
Functions | |
| int | CMEM_init (void) |
| Initialize the CMEM module. Must be called before other API calls. More... | |
| int | CMEM_getPool (unsigned long long size) |
| Find the pool that best fits a given buffer size and has a buffer available. More... | |
| int | CMEM_getPool2 (int blockid, unsigned long long size) |
| Find the pool in memory block blockid that best fits a given buffer size and has a buffer available. More... | |
| void * | CMEM_allocPool (int poolid, CMEM_AllocParams *params) |
| Allocate memory from a specified pool. More... | |
| void * | CMEM_allocPool2 (int blockid, int poolid, CMEM_AllocParams *params) |
| Allocate memory from a specified pool in a specified memory block. More... | |
| void * | CMEM_alloc (size_t size, CMEM_AllocParams *params) |
| Allocate memory of a specified size. More... | |
| void * | CMEM_alloc2 (int blockid, size_t size, CMEM_AllocParams *params) |
| Allocate memory of a specified size from a specified memory block. More... | |
| off_t | CMEM_allocPoolPhys (int poolid, CMEM_AllocParams *params) |
| Allocate unmapped memory from a specified pool. More... | |
| off_t | CMEM_allocPoolPhys2 (int blockid, int poolid, CMEM_AllocParams *params) |
| Allocate unmapped memory from a specified pool in a specified memory block. More... | |
| off64_t | CMEM_allocPoolPhys64 (int blockid, int poolid, CMEM_AllocParams *params) |
| Allocate unmapped memory from a specified pool in a specified memory block (Android only). More... | |
| off_t | CMEM_allocPhys (size_t size, CMEM_AllocParams *params) |
| Allocate unmapped memory of a specified size. More... | |
| off_t | CMEM_allocPhys2 (int blockid, size_t size, CMEM_AllocParams *params) |
| Allocate unmapped memory of a specified size from a specified memory block. More... | |
| off64_t | CMEM_allocPhys64 (int blockid, size_t size, CMEM_AllocParams *params) |
| Allocate unmapped memory of a specified size from a specified memory block (Android only) More... | |
| void * | CMEM_registerAlloc (off_t physp) |
| Register shared usage of an already-allocated buffer. More... | |
| void * | CMEM_registerAlloc64 (off64_t physp) |
| Register shared usage of an already-allocated buffer using mmap64 (Android only) More... | |
| int | CMEM_free (void *ptr, CMEM_AllocParams *params) |
| Free a buffer previously allocated with CMEM_alloc()/CMEM_allocPool(). More... | |
| int | CMEM_freePhys (off_t physp, CMEM_AllocParams *params) |
| Free an unmapped buffer previously allocated with CMEM_allocPhys()/CMEM_allocPoolPhys(). More... | |
| int | CMEM_freePhys64 (off64_t physp, CMEM_AllocParams *params) |
| Free an unmapped buffer previously allocated with CMEM_allocPhys64()/CMEM_allocPoolPhys64() (Android only). More... | |
| int | CMEM_unregister (void *ptr, CMEM_AllocParams *params) |
| Unregister use of a buffer previously registered with CMEM_registerAlloc(). More... | |
| off_t | CMEM_getPhys (void *ptr) |
| Get the physical address of a contiguous buffer. More... | |
| off64_t | CMEM_getPhys64 (void *ptr) |
| Get the physical address of a contiguous buffer (Android only). More... | |
| int | CMEM_cacheWbInvAll (void) |
| Do a cache writeback/invalidate of the whole cache. More... | |
| int | CMEM_cacheWb (void *ptr, size_t size) |
Do a cache writeback of the block pointed to by ptr/ More... | |
| void * | CMEM_map (off_t physp, size_t size) |
| Map allocated memory. More... | |
| void * | CMEM_map64 (off64_t physp, size_t size) |
| Map allocated memory using mmap64 (Android only) More... | |
| int | CMEM_unmap (void *userp, size_t size) |
| Unmap allocated memory. More... | |
| int | CMEM_cacheInv (void *ptr, size_t size) |
Do a cache invalidate of the block pointed to by ptr/ More... | |
| int | CMEM_cacheWbInv (void *ptr, size_t size) |
Do a cache writeback/invalidate of the block pointed to by ptr/ More... | |
| int | CMEM_getVersion (void) |
| Retrieve version from CMEM driver. More... | |
| int | CMEM_getBlock (off_t *pphys_base, unsigned long long *psize) |
| Retrieve memory block bounds from CMEM driver. More... | |
| int | CMEM_getBlockAttrs (int blockid, CMEM_BlockAttrs *pattrs) |
| Retrieve extended memory block attributes from CMEM driver. More... | |
| int | CMEM_getNumBlocks (int *pnblocks) |
| Retrieve number of blocks configured into CMEM driver. More... | |
| int | CMEM_exit (void) |
| Finalize the CMEM module. More... | |
Variables | |
| CMEM_AllocParams | CMEM_DEFAULTPARAMS |
