Dynamic memory allocation services.
[Xenomai scheduler.]


Detailed Description

Dynamic memory allocation services.

Implements the nanokernel memory allocator based on the algorithm described in "Design of a General Purpose Memory Allocator for the 4.3BSD Unix Kernel" by Marshall K. McKusick and Michael J. Karels.


Files

file  heap.c
 Dynamic memory allocation services.


Functions

int xnheap_init (xnheap_t *heap, void *heapaddr, u_long heapsize, u_long pagesize)
 Initialize a memory heap.

void xnheap_destroy (xnheap_t *heap)
 Destroys a memory heap.

void * xnheap_alloc (xnheap_t *heap, u_long size, xnflags_t flags)
 Allocate a memory block from a memory heap.

int xnheap_free (xnheap_t *heap, void *block)
 Release a memory block to a memory heap.


Function Documentation

void * xnheap_alloc xnheap_t *  heap,
u_long  size,
xnflags_t  flags
 

Allocate a memory block from a memory heap.

Allocates a contiguous region of memory from an active memory heap. Such allocation is guaranteed to be time-bounded if the heap is non-extendable (see xnheap_init()). Otherwise, it might trigger a dynamic extension of the storage area through an internal request to the host operating environment.

Parameters:
heap The descriptor address of the heap to get memory from.
size The size in bytes of the requested block. Sizes lower or equal to the page size are rounded either to the minimum allocation size if lower than this value, or to the minimum alignment size if greater or equal to this value. In the current implementation, with MINALLOC = 8 and MINALIGN = 16, a 7 bytes request will be rounded to 8 bytes, and a 17 bytes request will be rounded to 32.
flags A set of flags affecting the operation. If XNHEAP_NOWAIT is passed, this service will return NULL without attempting to extend the heap dynamically upon memory starvation. This flag is not applicable to non-extendable heaps.
Returns:
The address of the allocated region upon success, or NULL if no memory is available from the specified non-extendable heap, or no memory can be obtained from the host operating environment to extend the heap.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine can always be called on behalf of a thread context. It can also be called on behalf of an IST context if the heap storage area has been statically-defined at initialization time (see xnheap_init()).

void xnheap_destroy xnheap_t *  heap  ) 
 

Destroys a memory heap.

Destroys a memory heap. Dynamically allocated extents are returned to the host operating environment.

Parameters:
heap The descriptor address of the destroyed heap.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread context.

int xnheap_free xnheap_t *  heap,
void *  block
 

Release a memory block to a memory heap.

Releases a memory region to the memory heap it was previously allocated from.

Parameters:
heap The descriptor address of the heap to release memory to.
block The address of the region to release returned by a previous call to xnheap_alloc().
Returns:
XN_OK is returned upon success, or XNERR_PARAM is returned whenever the block is not a valid region of the specified heap.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine can be called on behalf of a thread or IST context

int xnheap_init xnheap_t *  heap,
void *  heapaddr,
u_long  heapsize,
u_long  pagesize
 

Initialize a memory heap.

Initializes a memory heap suitable for dynamic memory allocation requests. The heap manager can operate in two modes, whether time-bounded if the heap storage area and size are statically defined at initialization time, or dynamically extendable at the expense of a less deterministic behaviour.

Parameters:
heap The address of a heap descriptor Xenomai will use to store the allocation data. This descriptor must always be valid while the heap is active therefore it must be allocated in permanent memory.
heapaddr The address of a statically-defined heap storage area. If this parameter is non-zero, all allocations will be made from the given area in fully time-bounded mode. In such a case, the heap is non-extendable. If a null address is passed, the heap manager will attempt to extend the heap each time a memory starvation is encountered. In the latter case, the heap manager will request additional chunks of core memory to the host operating environment when needed, voiding the real-time guarantee for the caller.
heapsize If heapaddr is non-zero, heapsize gives the size in bytes of the statically-defined storage area. Otherwise, heapsize defines the standard length of each extent that will be requested to the host operating environment when a memory starvation is encountered for the heap. heapsize must be a multiple of pagesize and lower than 16 Mbytes. Depending on the host environment, requests for extent memory might be limited in size. For instance, heapsize must be lower than 128Kb for kmalloc()-based allocations used in Linux. In the current implementation, heapsize must be large enough to contain an internal header. The following formula gives the size of this header: hdrsize = (sizeof(xnextent_t) + ((heapsize - sizeof(xnextent_t))) / (pagesize + 1) + 15) & ~15;
pagesize The size in bytes of the fundamental memory page which will be used to subdivide the heap internally. Choosing the right page size is important regarding performance and memory fragmentation issues, so it might be a good idea to take a look at http://docs.FreeBSD.org/44doc/papers/kernmalloc.pdf to pick the best one for your needs. In the current implementation, pagesize must be a power of two in the range [ 8 .. 32768] inclusive.
Returns:
XN_OK is returned upon success, or one of the following error codes:
  • XNERR_PARAM is returned whenever a parameter is invalid.
  • XNERR_NOMEM is returned if no initial extent can be allocated for a dynamically extendable heap (i.e. heapaddr == NULL).
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread context.


Generated on Sat Jul 24 19:36:22 2004 for RTAI API by doxygen 1.3.4