Describes the interface to the contiguous memory allocator.
More...
|
| 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/size. 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/size. More...
|
| |
| int | CMEM_cacheWbInv (void *ptr, size_t size) |
| | Do a cache writeback/invalidate of the block pointed to by ptr/size. 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...
|
| |
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.
Command line block and pool specification
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
- phys_start and phys_end must be specified in hexadecimal format
- phys_start is "inclusive" and phys_end is "exclusive", i.e., phys_end should be "end address + 1".
- pools must be specified using decimal format (for both number and size), since using hexadecimal format would visually clutter the specification due to the use of "x" as a token separator
- it's possible to insmod cmemk.ko without specifying any memory blocks, in which case CMEM_getPhys() and CMEM_cache*() APIs can still be utilized by an application, and CMA-based allocations can still be accomplished (by using blockid as CMEM_CMABLOCKID).
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.
Block and pool specification using Device Tree (DT)
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:
- allows specifying the physical "carveout" with direct linkage to that carveout in the pool specification, thereby eliminating potential errors that could occur when the physical carveout is defined in one place and then needing to be specified on the cmemk.ko command line exactly equivalent to the carveout definition.
- allows a system integrator to define the CMEM specifications without the need to document instructions for the command line, or prepackage the command line in some filesystem-based script.
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...
*
*
*
*
*
* reserved-memory {
* #address-cells = <1>;
* #size-cells = <1>;
* ranges;
* ...
* cmem_block_mem_0: cmem_block_mem@a0000000 {
* reg = <0xa0000000 0x10000000>;
* no-map;
* status = "okay";
* };
*
* cmem_block_mem_1: cmem_block_mem@b0000000 {
* reg = <0xb0000000 0x02000000>;
* no-map;
* status = "okay";
* };
* };
*
*
*
*
*
* cmem {
* compatible = "ti,cmem";
* #address-cells = <1>;
* #size-cells = <0>;
*
* status = "okay";
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* cmem_block_0: cmem_block@0 {
* reg = <0>;
* memory-region = <&cmem_block_mem_0>;
* cmem-buf-pools = <1 0x0c000000>, <4 0x01000000>;
* };
*
* cmem_block_1: cmem_block@1 {
* reg = <1>;
* memory-region = <&cmem_block_mem_1>;
* cmem-buf-pools = <1 0x02000000>;
* };
* };
*
Decoupled allocation & memory mapping
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.
CMA access
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.
| #define CMEM_VERSION 0x04000300U |
| #define CMEM_CMABLOCKID -1 |
| #define CMEM_WB 0x00010000 |
| #define CMEM_INV 0x00020000 |
| #define CMEM_HEAP 0x00040000 |
operation applies to heap
| #define CMEM_POOL 0x00000000 |
operation applies to a pool
| #define CMEM_CACHED 0x00080000 |
allocated buffer is cached
| #define CMEM_NONCACHED 0x00000000 |
allocated buffer is not cached
| #define CMEM_PHYS 0x00100000 |
| #define CMEM_IOCMAGIC 0x0000fe00 |
| #define CMEM_IOCALLOCHEAP 2 |
| #define CMEM_IOCGETPHYS 4 |
| #define CMEM_IOCGETSIZE 5 |
| #define CMEM_IOCGETPOOL 6 |
| #define CMEM_IOCGETVERSION 8 |
| #define CMEM_IOCGETBLOCK 9 |
| #define CMEM_IOCREGUSER 10 |
| #define CMEM_IOCGETNUMBLOCKS 11 |
| #define CMEM_IOCCACHEWBINVALL 12 |
| #define CMEM_IOCCMDMASK 0x000000ff |
Initialize the CMEM module. Must be called before other API calls.
- Returns
- 0 for success or -1 for failure.
- See Also
- CMEM_exit
| int CMEM_getPool |
( |
unsigned long long |
size | ) |
|
| int CMEM_getPool2 |
( |
int |
blockid, |
|
|
unsigned long long |
size |
|
) |
| |
| off_t CMEM_allocPoolPhys2 |
( |
int |
blockid, |
|
|
int |
poolid, |
|
|
CMEM_AllocParams * |
params |
|
) |
| |
| off64_t CMEM_allocPoolPhys64 |
( |
int |
blockid, |
|
|
int |
poolid, |
|
|
CMEM_AllocParams * |
params |
|
) |
| |
| off64_t CMEM_allocPhys64 |
( |
int |
blockid, |
|
|
size_t |
size, |
|
|
CMEM_AllocParams * |
params |
|
) |
| |
| void* CMEM_registerAlloc |
( |
off_t |
physp | ) |
|
| void* CMEM_registerAlloc64 |
( |
off64_t |
physp | ) |
|
Register shared usage of an already-allocated buffer using mmap64 (Android only)
- Parameters
-
| physp | Physical address of the already-allocated buffer. |
- Returns
- A process-specific pointer to the allocated buffer, or NULL for failure.
- Precondition
- Must have called some form of CMEM_alloc*()
- See Also
- CMEM_allocPool()
-
CMEM_allocPool2()
-
CMEM_alloc()
-
CMEM_free()
-
CMEM_unregister()
| off_t CMEM_getPhys |
( |
void * |
ptr | ) |
|
Get the physical address of a contiguous buffer.
- Parameters
-
| ptr | The pointer to the buffer. |
- Returns
- The physical address of the buffer or 0 for failure.
- Precondition
- Must have called CMEM_init()
| off64_t CMEM_getPhys64 |
( |
void * |
ptr | ) |
|
Get the physical address of a contiguous buffer (Android only).
- Parameters
-
| ptr | The pointer to the buffer. |
- Returns
- The physical address of the buffer or 0 for failure.
- Precondition
- Must have called CMEM_init()
| int CMEM_cacheWbInvAll |
( |
void |
| ) |
|
| int CMEM_cacheWb |
( |
void * |
ptr, |
|
|
size_t |
size |
|
) |
| |
| void* CMEM_map |
( |
off_t |
physp, |
|
|
size_t |
size |
|
) |
| |
| void* CMEM_map64 |
( |
off64_t |
physp, |
|
|
size_t |
size |
|
) |
| |
Map allocated memory using mmap64 (Android only)
- Parameters
-
| physp | Physical address of the already-allocated buffer. |
| size | Size in bytes of block to map. |
- Returns
- A pointer to the mapped buffer, or NULL for failure.
- Precondition
- Must have called CMEM_init()
- See Also
- CMEM_allocPhys()
-
CMEM_allocPoolPhys()
-
CMEM_unmap()
| int CMEM_unmap |
( |
void * |
userp, |
|
|
size_t |
size |
|
) |
| |
Unmap allocated memory.
- Parameters
-
| userp | User virtual address of the mapped buffer. |
| size | Size in bytes of block to unmap. |
- Returns
- Success/failure boolean value
- Precondition
- Must have called CMEM_init()
- See Also
- CMEM_freePhys()
-
CMEM_map()
| int CMEM_cacheInv |
( |
void * |
ptr, |
|
|
size_t |
size |
|
) |
| |
| int CMEM_cacheWbInv |
( |
void * |
ptr, |
|
|
size_t |
size |
|
) |
| |
Do a cache writeback/invalidate of the block pointed to by ptr/size.
- Parameters
-
| ptr | Pointer to block to writeback/invalidate |
| size | Size in bytes of block to writeback/invalidate |
- Returns
- Success/failure boolean value
- Precondition
- Must have called CMEM_init()
- See Also
- CMEM_cacheInv()
-
CMEM_cacheWb()
-
CMEM_cacheWbInvAll()
| int CMEM_getVersion |
( |
void |
| ) |
|
Retrieve version from CMEM driver.
- Returns
- Installed CMEM driver's version number.
- Precondition
- Must have called CMEM_init()
| int CMEM_getBlock |
( |
off_t * |
pphys_base, |
|
|
unsigned long long * |
psize |
|
) |
| |
Retrieve memory block bounds from CMEM driver.
- Parameters
-
| pphys_base | Pointer to storage for base physical address of CMEM's memory block |
| psize | Pointer to storage for size of CMEM's memory block |
- Returns
- Success (0) or failure (-1).
- Precondition
- Must have called CMEM_init()
- See Also
- CMEM_getBlockAttrs()
-
CMEM_getNumBlocks()
| int CMEM_getNumBlocks |
( |
int * |
pnblocks | ) |
|
Retrieve number of blocks configured into CMEM driver.
- Parameters
-
| pnblocks | Pointer to storage for holding number of blocks |
- Returns
- Success (0) or failure (-1).
- Precondition
- Must have called CMEM_init()
- See Also
- CMEM_getBlock()
-
CMEM_getBlockAttrs()
Finalize the CMEM module.
- Returns
- 0 for success or -1 for failure.
- Precondition
- Must have called CMEM_init()
- See Also
- CMEM_init()
