113 lines
4.8 KiB
Plaintext
113 lines
4.8 KiB
Plaintext
mm/README.txt
|
|
=============
|
|
|
|
This directory contains the NuttX memory management logic. This include:
|
|
|
|
1) Standard Memory Management Functions:
|
|
|
|
The standard memory management functions as prototyped in stdlib.h as
|
|
specified in the Base definitions volume of IEEE Std 1003.1-2001. This
|
|
include the files:
|
|
|
|
o Standard Interfaces: mm_malloc.c, mm_calloc.c, mm_realloc.c,
|
|
mm_memalign.c, mm_free.c
|
|
o Less-Standard Interfaces: mm_zalloc.c, mm_mallinfo.c
|
|
o Internal Implementation: mm_initialize.c mm_sem.c mm_addfreechunk.c
|
|
mm_size2ndx.c mm_shrinkchunk.c, mm_internal.h
|
|
o Build and Configuration files: Kconfig, Makefile
|
|
|
|
Memory Models:
|
|
|
|
o Small Memory Model. If the MCU supports only 16-bit data addressing
|
|
then the small memory model is automatically used. The maximum size
|
|
of the heap is then 64K. The small memory model can also be forced
|
|
MCUs with wider addressing by defining CONFIG_SMALL_MEMORY in the
|
|
NuttX configuration file.
|
|
o Large Memory Model. Otherwise, the allocator uses a model that
|
|
supports a heap of up to 4G.
|
|
|
|
This implementation uses a variable length allocator with the following
|
|
properties:
|
|
|
|
o Overhead: Either 8- or 4-bytes per allocation for large and small
|
|
models, respectively.
|
|
o Alignment: All allocations are aligned to 8- or 4-bytes for large
|
|
and small models, respectively.
|
|
|
|
Multiple Heaps:
|
|
|
|
This allocator can be used to manage multiple heaps (albeit with some
|
|
non-standard interfaces). A heap is represented by struct mm_heap_s
|
|
as defined in the file include/nuttx/mm.h. To create another heap
|
|
instance, you would allocate a heap structure, most likely statically
|
|
in memory:
|
|
|
|
include <nuttx/mm.h>
|
|
static struct mm_heap_s g_myheap;
|
|
|
|
Then initialize the heap using:
|
|
|
|
mm_initialize(&g_myheap, myheap_start, myheap_size);
|
|
|
|
Where mm_initialize() and all related interfaces are prototyped in the
|
|
header file include/nuttx/mm.h.
|
|
|
|
After the new heap instance has been initialized, it can then be used
|
|
with these almost familiar interfaces: mm_malloc(), mm_realloc(), mm_free(),
|
|
etc. These are 'almost familiar' because they are analogous of the
|
|
standard malloc(), realloc(), free(), etc. except that they expect a
|
|
reference to the initialized heap structure as the first parameter.
|
|
|
|
In fact, the standard malloc(), realloc(), free() use this same mechanism,
|
|
but with a global heap structure called g_mmheap.
|
|
|
|
2) Granule Allocator.
|
|
|
|
A non-standard granule allocator is also available in this directory The
|
|
granule allocator allocates memory in units of a fixed sized block ("granule").
|
|
Allocations may be aligned to a user-provided address boundary.
|
|
|
|
The granule allocator interfaces are defined in nuttx/include/nuttx/gran.h.
|
|
The granule allocator consists of these files in this directory:
|
|
|
|
mm_gran.h, mm_granalloc.c, mm_grancritical.c, mm_granfree.c
|
|
mm_graninit.c
|
|
|
|
The granule allocator is not used anywhere within the base NuttX code
|
|
as of this writing. The intent of the granule allocator is to provide
|
|
a tool to support platform-specific management of aligned DMA memory.
|
|
|
|
NOTE: Because each granule may be aligned and each allocation is in
|
|
units of the granule size, selection of the granule size is important:
|
|
Larger granules will give better performance and less overhead but more
|
|
losses of memory due to quantization waste. Additional memory waste
|
|
can occur from alignment; Of course, heap alignment should no be
|
|
used unless (a) you are using the granule allocator to manage DMA memory
|
|
and (b) your hardware has specific memory alignment requirements.
|
|
|
|
The current implementation also restricts the maximum allocation size
|
|
to 32 granules. That restriction could be eliminated with some
|
|
additional coding effort, but currently requires larger granule
|
|
sizes for larger allocations.
|
|
|
|
General Usage Example.
|
|
|
|
This is an example using the GCC section attribute to position a DMA
|
|
heap in memory (logic in the linker script would assign the section
|
|
.dmaheap to the DMA memory.
|
|
|
|
FAR uint32_t g_dmaheap[DMAHEAP_SIZE] __attribute__((section(.dmaheap)));
|
|
|
|
The heap is created by calling gran_initialize. Here the granule size
|
|
is set to 64 bytes and the alignment to 16 bytes:
|
|
|
|
GRAN_HANDLE handle = gran_initialize(g_dmaheap, DMAHEAP_SIZE, 6, 4);
|
|
|
|
Then the GRAN_HANDLE can be used to allocate memory (There is no
|
|
GRAN_HANDLE if CONFIG_GRAN_SINGLE=y):
|
|
|
|
FAR uint8_t *dma_memory = (FAR uint8_t *)gran_alloc(handle, 47);
|
|
|
|
The actual memory allocates will be 64 byte (wasting 17 bytes) and
|
|
will be aligned at least to (1 << log2align).
|