Region of memory dedicated to real-time allocation. More...

Collaboration diagram for Heap management services:

Data Structures
struct	RT_HEAP_INFO
	Heap status descriptor. More...

Macros
#define	H_PRIO 0x1 /* Pend by task priority order. */
	Creation flags. More...

Functions
int	rt_heap_create (RT_HEAP heap, const char name, size_t heapsize, int mode)
	Create a heap. More...

int	rt_heap_delete (RT_HEAP *heap)
	Delete a heap. More...

int	rt_heap_alloc_timed (RT_HEAP heap, size_t size, const struct timespec abs_timeout, void **blockp)
	Allocate a block from a heap. More...

static int	rt_heap_alloc_until (RT_HEAP heap, size_t size, RTIME timeout, void *blockp)
	Allocate a block from a heap (with absolute scalar timeout). More...

static int	rt_heap_alloc (RT_HEAP heap, size_t size, RTIME timeout, void *blockp)
	Allocate a block from a heap (with relative scalar timeout). More...

int	rt_heap_free (RT_HEAP heap, void block)
	Release a block to a heap. More...

int	rt_heap_inquire (RT_HEAP heap, RT_HEAP_INFO info)
	Query heap status. More...

int	rt_heap_bind (RT_HEAP heap, const char name, RTIME timeout)
	Bind to a heap. More...

int	rt_heap_unbind (RT_HEAP *heap)
	Unbind from a heap. More...

Detailed Description

Region of memory dedicated to real-time allocation.

Heaps are regions of memory used for dynamic memory allocation in a time-bounded fashion. Blocks of memory are allocated and freed in an arbitrary order and the pattern of allocation and size of blocks is not known until run time.

Macro Definition Documentation

◆ H_PRIO

#define H_PRIO 0x1 /* Pend by task priority order. */

Creation flags.

Referenced by rt_heap_create().

Function Documentation

◆ rt_heap_alloc()

int rt_heap_alloc	(	RT_HEAP *	heap,
		size_t	size,
		RTIME	timeout,
		void **	blockp
	)

inlinestatic

Allocate a block from a heap (with relative scalar timeout).

This routine is a variant of rt_heap_alloc_timed() accepting a relative timeout specification expressed as a scalar value. Passing TM_INFINITE in timeout causes the caller to block indefinitely until a block is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case a block is not available.

Tags: xthread-nowait, switch-primary

◆ rt_heap_alloc_timed()

int rt_heap_alloc_timed	(	RT_HEAP *	heap,
		size_t	size,
		const struct timespec *	abs_timeout,
		void **	blockp
	)

Allocate a block from a heap.

This service allocates a block from a given heap, or returns the address of the single memory segment if H_SINGLE was mentioned in the creation mode to rt_heap_create(). When not enough memory is available on entry to this service, tasks may be blocked until their allocation request can be fulfilled.

Parameters

heap	The heap descriptor.
size	The requested size (in bytes) of the block. If the heap is managed as a single-block area (H_SINGLE), this value can be either zero, or the same value given to rt_heap_create(). In that case, the same block covering the entire heap space is returned to all callers of this service.
abs_timeout	An absolute date expressed in clock ticks, specifying a time limit to wait for a block of the requested size to be available from the heap (see note). Passing NULL causes the caller to block indefinitely until a block is available. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without blocking in case a block is not available.
blockp	A pointer to a memory location which will be written upon success with the address of the allocated block, or the start address of the single memory segment. In the former case, the block can be freed using rt_heap_free().

Returns: Zero is returned upon success. Otherwise:

-ETIMEDOUT is returned if abs_timeout is reached before a block is available.
-EWOULDBLOCK is returned if abs_timeout is equal to { .tv_sec = 0, .tv_nsec = 0 } and no block is immediately available on entry to fulfill the allocation request.
-EINTR is returned if rt_task_unblock() was called for the current task before a block became available.
-EINVAL is returned if heap is not a valid heap descriptor, or heap is managed as a single-block area (i.e. H_SINGLE mode) and size is non-zero but does not match the original heap size passed to rt_heap_create().
-EIDRM is returned if heap is deleted while the caller was waiting for a block. In such event, heap is no more valid upon return of this service.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: If shared multi-processing is enabled (i.e. –enable-pshared was passed to the configure script), requests for a block size larger than twice the allocation page size are rounded up to the next page size. The allocation page size is currently 512 bytes long (HOBJ_PAGE_SIZE), which means that any request larger than 1k will be rounded up to the next 512 byte boundary.; abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_heap_alloc_until()

int rt_heap_alloc_until	(	RT_HEAP *	heap,
		size_t	size,
		RTIME	abs_timeout,
		void **	blockp
	)

inlinestatic

Allocate a block from a heap (with absolute scalar timeout).

This routine is a variant of rt_heap_alloc_timed() accepting an absolute timeout specification expressed as a scalar value. Passing TM_INFINITE in timeout causes the caller to block indefinitely until a block is available. Passing TM_NONBLOCK causes the service to return immediately without blocking in case a block is not available.

Tags: xthread-nowait, switch-primary

◆ rt_heap_bind()

int rt_heap_bind	(	RT_HEAP *	heap,
		const char *	name,
		RTIME	timeout
	)

Bind to a heap.

This routine creates a new descriptor to refer to an existing heap identified by its symbolic name. If the object does not exist on entry, the caller may block until a heap of the given name is created.

Parameters

heap	The address of a heap descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the heap to bind to. This string should match the object name argument passed to rt_heap_create().
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns: Zero is returned upon success. Otherwise:

-EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
-ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_heap_create()

int rt_heap_create	(	RT_HEAP *	heap,
		const char *	name,
		size_t	heapsz,
		int	mode
	)

Create a heap.

This routine creates a memory heap suitable for time-bounded allocation requests of RAM chunks. When not enough memory is available, tasks may be blocked until their allocation request can be fulfilled.

By default, heaps support allocation of multiple blocks of memory in an arbitrary order. However, it is possible to ask for single-block management by passing the H_SINGLE flag into the mode parameter, in which case the entire memory space managed by the heap is made available as a unique block. In this mode, all allocation requests made through rt_heap_alloc() will return the same block address, pointing at the beginning of the heap memory.

Parameters

heap	The address of a heap descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the heap. When non-NULL and non-empty, a copy of this string is used for indexing the created heap into the object registry.
heapsz	The size (in bytes) of the memory pool, blocks will be claimed and released to. This area is not extensible, so this value must be compatible with the highest memory pressure that could be expected. The valid range is between 1 byte and 2Gb.
mode	The heap creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new heap:

H_FIFO makes tasks pend in FIFO order on the heap when waiting for available blocks.
H_PRIO makes tasks pend in priority order on the heap when waiting for available blocks.
H_SINGLE causes the entire heap space to be managed as a single memory block.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if mode is invalid, or heapsz is zero or larger than 2Gb.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the heap.
-EEXIST is returned if the name is conflicting with an already registered heap.
-EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.

Tags: xthread-only, mode-unrestricted, switch-secondary

Note: Heaps can be shared by multiple processes which belong to the same Xenomai session.

References H_PRIO.

◆ rt_heap_delete()

int rt_heap_delete ( RT_HEAP * heap )

Delete a heap.

This routine deletes a heap object previously created by a call to rt_heap_create(), releasing all tasks currently blocked on it.

Parameters

heap	The heap descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if heap is not a valid heap descriptor.
-EPERM is returned if this service was called from an asynchronous context.

Tags: mode-unrestricted, switch-secondary

◆ rt_heap_free()

int rt_heap_free	(	RT_HEAP *	heap,
		void *	block
	)

Release a block to a heap.

This service should be used to release a block to the heap it belongs to. An attempt to fulfill the request of every task blocked on rt_heap_alloc() is made once block is returned to the memory pool.

Parameters

heap	The heap descriptor.
block	The address of the block to free.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if heap is not a valid heap descriptor, or block is not a valid block previously allocated by the rt_heap_alloc() service from heap.

Tags: unrestricted, switch-primary

◆ rt_heap_inquire()

int rt_heap_inquire	(	RT_HEAP *	heap,
		RT_HEAP_INFO *	info
	)

Query heap status.

This routine returns the status information about heap.

Parameters

heap	The heap descriptor.
info	A pointer to the return buffer" to copy the information to.

Returns: Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:

-EINVAL is returned if heap is not a valid heap descriptor.

Tags: unrestricted, switch-primary

◆ rt_heap_unbind()

int rt_heap_unbind ( RT_HEAP * heap )

Unbind from a heap.

Parameters

heap	The heap descriptor.

This routine releases a previous binding to a heap. After this call has returned, the descriptor is no more valid for referencing this object.

Tags: thread-unrestricted

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ H_PRIO

Function Documentation

◆ rt_heap_alloc()

◆ rt_heap_alloc_timed()

◆ rt_heap_alloc_until()

◆ rt_heap_bind()

◆ rt_heap_create()

◆ rt_heap_delete()

◆ rt_heap_free()

◆ rt_heap_inquire()

◆ rt_heap_unbind()