NAME
malloc - .TH "malloc" 3 "Thu Aug 12 2010" "Version 1.6.8" "avr-libc"
NAME
malloc - .SH "Introduction"
Many of the devices that are possible targets of avr-libc have a
minimal amount of RAM. The smallest parts supported by the C
environment come with 128 bytes of RAM. This needs to be shared between
initialized and uninitialized variables (sections .data and .bss), the
dynamic memory allocator, and the stack that is used for calling
subroutines and storing local (automatic) variables.
Also, unlike larger architectures, there is no hardware-supported
memory management which could help in separating the mentioned RAM
regions from being overwritten by each other.
The standard RAM layout is to place .data variables first, from the
beginning of the internal RAM, followed by .bss. The stack is started
from the top of internal RAM, growing downwards. The so-called 'heap'
available for the dynamic memory allocator will be placed beyond the
end of .bss. Thus, there's no risk that dynamic memory will ever
collide with the RAM variables (unless there were bugs in the
implementation of the allocator). There is still a risk that the heap
and stack could collide if there are large requirements for either
dynamic memory or stack space. The former can even happen if the
allocations aren't all that large but dynamic memory allocations get
fragmented over time such that new requests don't quite fit into the
'holes' of previously freed regions. Large stack space requirements can
arise in a C function containing large and/or numerous local variables
or when recursively calling function.
Note:
The pictures shown in this document represent typical situations
where the RAM locations refer to an ATmega128. The memory addresses
used are not displayed in a linear scale.
RAM map of a device with internal RAMRAM map of a device with internal
RAM
On a simple device like a microcontroller it is a challenge to
implement a dynamic memory allocator that is simple enough so the code
size requirements will remain low, yet powerful enough to avoid
unnecessary memory fragmentation and to get it all done with reasonably
few CPU cycles. Microcontrollers are often low on space and also run at
much lower speeds than the typical PC these days.
The memory allocator implemented in avr-libc tries to cope with all of
these constraints, and offers some tuning options that can be used if
there are more resources available than in the default configuration.
Internal vs. external RAM
Obviously, the constraints are much harder to satisfy in the default
configuration where only internal RAM is available. Extreme care must
be taken to avoid a stack-heap collision, both by making sure functions
aren't nesting too deeply, and don't require too much stack space for
local variables, as well as by being cautious with allocating too much
dynamic memory.
If external RAM is available, it is strongly recommended to move the
heap into the external RAM, regardless of whether or not the variables
from the .data and .bss sections are also going to be located there.
The stack should always be kept in internal RAM. Some devices even
require this, and in general, internal RAM can be accessed faster since
no extra wait states are required. When using dynamic memory allocation
and stack and heap are separated in distinct memory areas, this is the
safest way to avoid a stack-heap collision.
Tunables for malloc()
There are a number of variables that can be tuned to adapt the behavior
of malloc() to the expected requirements and constraints of the
application. Any changes to these tunables should be made before the
very first call to malloc(). Note that some library functions might
also use dynamic memory (notably those from the <stdio.h>: Standard IO
facilities), so make sure the changes will be done early enough in the
startup sequence.
The variables __malloc_heap_start and __malloc_heap_end can be used to
restrict the malloc() function to a certain memory region. These
variables are statically initialized to point to __heap_start and
__heap_end, respectively, where __heap_start is filled in by the linker
to point just beyond .bss, and __heap_end is set to 0 which makes
malloc() assume the heap is below the stack.
If the heap is going to be moved to external RAM, __malloc_heap_end
must be adjusted accordingly. This can either be done at run-time, by
writing directly to this variable, or it can be done automatically at
link-time, by adjusting the value of the symbol __heap_end.
The following example shows a linker command to relocate the entire
.data and .bss segments, and the heap to location 0x1100 in external
RAM. The heap will extend up to address 0xffff.
avr-gcc ... -Wl,--section-start,.data=0x801100,--defsym=__heap_end=0x80ffff ...
Note:
See explanation for offset 0x800000. See the chapter about using
gcc for the -Wl options.
The ld (linker) user manual states that using -Tdata=<x> is
equivalent to using --section-start,.data=<x>. However, you have to
use --section-start as above because the GCC frontend also sets the
-Tdata option for all MCU types where the SRAM doesn't start at
0x800060. Thus, the linker is being faced with two -Tdata options.
Sarting with binutils 2.16, the linker changed the preference, and
picks the 'wrong' option in this situation.
Internal RAM: stack only, external RAM: variables and heapInternal RAM:
stack only, external RAM: variables and heap
If dynamic memory should be placed in external RAM, while keeping the
variables in internal RAM, something like the following could be used.
Note that for demonstration purposes, the assignment of the various
regions has not been made adjacent in this example, so there are
'holes' below and above the heap in external RAM that remain completely
unaccessible by regular variables or dynamic memory allocations (shown
in light bisque color in the picture below).
avr-gcc ... -Wl,--defsym=__heap_start=0x802000,--defsym=__heap_end=0x803fff ...
Internal RAM: variables and stack, external RAM: heapInternal RAM:
variables and stack, external RAM: heap
If __malloc_heap_end is 0, the allocator attempts to detect the bottom
of stack in order to prevent a stack-heap collision when extending the
actual size of the heap to gain more space for dynamic memory. It will
not try to go beyond the current stack limit, decreased by
__malloc_margin bytes. Thus, all possible stack frames of interrupt
routines that could interrupt the current function, plus all further
nested function calls must not require more stack space, or they will
risk colliding with the data segment.
The default value of __malloc_margin is set to 32.
Implementation details
Dynamic memory allocation requests will be returned with a two-byte
header prepended that records the size of the allocation. This is later
used by free(). The returned address points just beyond that header.
Thus, if the application accidentally writes before the returned memory
region, the internal consistency of the memory allocator is
compromised.
The implementation maintains a simple freelist that accounts for memory
blocks that have been returned in previous calls to free(). Note that
all of this memory is considered to be successfully added to the heap
already, so no further checks against stack-heap collisions are done
when recycling memory from the freelist.
The freelist itself is not maintained as a separate data structure, but
rather by modifying the contents of the freed memory to contain
pointers chaining the pieces together. That way, no additional memory
is reqired to maintain this list except for a variable that keeps track
of the lowest memory segment available for reallocation. Since both, a
chain pointer and the size of the chunk need to be recorded in each
chunk, the minimum chunk size on the freelist is four bytes.
When allocating memory, first the freelist is walked to see if it could
satisfy the request. If there's a chunk available on the freelist that
will fit the request exactly, it will be taken, disconnected from the
freelist, and returned to the caller. If no exact match could be found,
the closest match that would just satisfy the request will be used. The
chunk will normally be split up into one to be returned to the caller,
and another (smaller) one that will remain on the freelist. In case
this chunk was only up to two bytes larger than the request, the
request will simply be altered internally to also account for these
additional bytes since no separate freelist entry could be split off in
that case.
If nothing could be found on the freelist, heap extension is attempted.
This is where __malloc_margin will be considered if the heap is
operating below the stack, or where __malloc_heap_end will be verified
otherwise.
If the remaining memory is insufficient to satisfy the request, NULL
will eventually be returned to the caller.
When calling free(), a new freelist entry will be prepared. An attempt
is then made to aggregate the new entry with possible adjacent entries,
yielding a single larger entry available for further allocations. That
way, the potential for heap fragmentation is hopefully reduced.
A call to realloc() first determines whether the operation is about to
grow or shrink the current allocation. When shrinking, the case is
easy: the existing chunk is split, and the tail of the region that is
no longer to be used is passed to the standard free() function for
insertion into the freelist. Checks are first made whether the tail
chunk is large enough to hold a chunk of its own at all, otherwise
realloc() will simply do nothing, and return the original region.
When growing the region, it is first checked whether the existing
allocation can be extended in-place. If so, this is done, and the
original pointer is returned without copying any data contents. As a
side-effect, this check will also record the size of the largest chunk
on the freelist.
If the region cannot be extended in-place, but the old chunk is at the
top of heap, and the above freelist walk did not reveal a large enough
chunk on the freelist to satisfy the new request, an attempt is made to
quickly extend this topmost chunk (and thus the heap), so no need
arises to copy over the existing data. If there's no more space
available in the heap (same check is done as in malloc()), the entire
request will fail.
Otherwise, malloc() will be called with the new request size, the
existing data will be copied over, and free() will be called on the old
region.