rtl-allocator.h File Reference

RTEMS Run-Time Linker Allocator. More...

#include <stdbool.h>
#include "rtl-indirect-ptr.h"

Include dependency graph for rtl-allocator.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	rtems_rtl_alloc_data_s
	The allocator data. More...

Macros
#define	RTEMS_RTL_ALLOC_TAGS   ((size_t) (RTEMS_RTL_ALLOC_READ_EXEC + 1))
	The number of tags.

Typedefs
typedef enum rtems_rtl_alloc_tags_e	rtems_rtl_alloc_tag_t
	The allocator tag type.
typedef void(*	rtems_rtl_allocator_t) (bool allocate, rtems_rtl_alloc_tag_t tag, void **address, size_t size)
	Allocator handler handles all RTL allocations. More...
typedef struct rtems_rtl_alloc_data_s	rtems_rtl_alloc_data_t

Enumerations
enum	rtems_rtl_alloc_tags_e {   RTEMS_RTL_ALLOC_OBJECT, RTEMS_RTL_ALLOC_SYMBOL, RTEMS_RTL_ALLOC_EXTERNAL, RTEMS_RTL_ALLOC_READ,   RTEMS_RTL_ALLOC_READ_WRITE, RTEMS_RTL_ALLOC_READ_EXEC }
	Define the types of allocation the loader requires. More...

Functions
void	rtems_rtl_alloc_initialise (rtems_rtl_alloc_data_t *data)
	Initialise the allocate data. More...
void *	rtems_rtl_alloc_new (rtems_rtl_alloc_tag_t tag, size_t size, bool zero)
	The Runtime Loader allocator new allocates new memory and optionally clear the memory if requested. More...
void	rtems_rtl_alloc_del (rtems_rtl_alloc_tag_t tag, void *address)
	The Runtime Loader allocator delete deletes allocated memory. More...
rtems_rtl_allocator_t	rtems_rtl_alloc_hook (rtems_rtl_allocator_t handler)
	Hook the Runtime Loader allocatior. More...
void	rtems_rtl_alloc_indirect_new (rtems_rtl_alloc_tag_t tag, rtems_rtl_ptr_t *handle, size_t size)
	Allocate memory to an indirect handle. More...
void	rtems_rtl_alloc_indirect_del (rtems_rtl_alloc_tag_t tag, rtems_rtl_ptr_t *handle)
	Free memory from an indirect handle. More...
bool	rtems_rtl_alloc_module_new (void **text_base, size_t text_size, void **const_base, size_t const_size, void **eh_base, size_t eh_size, void **data_base, size_t data_size, void **bss_base, size_t bss_size)
	Allocate the memory for a module given the size of the text, const, data and bss sections. More...
void	rtems_rtl_alloc_module_del (void **text_base, void **const_base, void **eh_base, void **data_base, void **bss_base)
	Free the memory allocated to a module. More...

Detailed Description

RTEMS Run-Time Linker Allocator.

Typedef Documentation

rtems_rtl_allocator_t

typedef void(* rtems_rtl_allocator_t) (bool allocate, rtems_rtl_alloc_tag_t tag, void **address, size_t size)

Allocator handler handles all RTL allocations.

It can be hooked and overridded for customised allocation schemes or memory maps.

Parameters

allocation	If true the request is to allocate memory else free.
tag	The type of allocation request.
address	Pointer to the memory address. If an allocation the value is unspecific on entry and the allocated address or NULL on exit. The NULL value means the allocation failed. If a delete or free request the memory address is the block to free. A free request of NULL is silently ignored.
size	The size of the allocation if an allocation request and not used if deleting or freeing a previous allocation.

Enumeration Type Documentation

rtems_rtl_alloc_tags_e

enum rtems_rtl_alloc_tags_e

Define the types of allocation the loader requires.

Note

It is best to use the object tag for general memory allocation and to leave the tags with specific access properties to the module data

Enumerator
RTEMS_RTL_ALLOC_OBJECT	A generic memory object.
RTEMS_RTL_ALLOC_SYMBOL	Memory used for symbols.
RTEMS_RTL_ALLOC_EXTERNAL	Memory used for external symbols.
RTEMS_RTL_ALLOC_READ	The memory is read only.
RTEMS_RTL_ALLOC_READ_WRITE	The memory is read and write.
RTEMS_RTL_ALLOC_READ_EXEC	The memory is read and executable.

Function Documentation

rtems_rtl_alloc_del()

void rtems_rtl_alloc_del	(	rtems_rtl_alloc_tag_t	tag,
		void *	address
	)

The Runtime Loader allocator delete deletes allocated memory.

Parameters

tag	The type of allocation request.
address	The memory address to delete. A NULL is ignored.

Referenced by rtems_rtl_alloc_module_del(), rtems_rtl_obj_comp_close(), rtems_rtl_obj_erase_sections(), rtems_rtl_symbol_obj_erase_local(), and rtems_rtl_symbol_table_close().

rtems_rtl_alloc_hook()

rtems_rtl_allocator_t rtems_rtl_alloc_hook

(

rtems_rtl_allocator_t

handler

)

Hook the Runtime Loader allocatior.

A handler can call the previous handler in the chain to use it for specific tags. The default handler uses the system heap. Do not unhook your handler if memory it allocates has not been returned.

Parameters

handler

The handler to use as the allocator.

Returns

rtems_rtl_alloc_handler_t The previous handler.

rtems_rtl_alloc_indirect_del()

void rtems_rtl_alloc_indirect_del	(	rtems_rtl_alloc_tag_t	tag,
		rtems_rtl_ptr_t *	handle
	)

Free memory from an indirect handle.

Parameters

tag	The type of allocation request.
handle	The handle to free the memory from.

rtems_rtl_alloc_indirect_new()

void rtems_rtl_alloc_indirect_new	(	rtems_rtl_alloc_tag_t	tag,
		rtems_rtl_ptr_t *	handle,
		size_t	size
	)

Allocate memory to an indirect handle.

Parameters

tag	The type of allocation request.
handle	The handle to allocate the memory to.
size	The size of the allocation.

rtems_rtl_alloc_initialise()

void rtems_rtl_alloc_initialise

(

rtems_rtl_alloc_data_t *

data

)

Initialise the allocate data.

Parameters

data	The data to initialise.

References rtems_rtl_alloc_data_s::allocator, rtems_chain_initialize_empty(), rtems_rtl_alloc_heap(), and RTEMS_RTL_ALLOC_TAGS.

rtems_rtl_alloc_module_del()

void rtems_rtl_alloc_module_del	(	void **	text_base,
		void **	const_base,
		void **	eh_base,
		void **	data_base,
		void **	bss_base
	)

Free the memory allocated to a module.

Parameters

text_base	Pointer to the text base pointer.
const_base	Pointer to the const base pointer.
eh_base	Pointer to the eh base pointer.
data_base	Pointer to the data base pointer.
bss_base	Pointer to the bss base pointer.

References rtems_rtl_alloc_del(), RTEMS_RTL_ALLOC_READ, RTEMS_RTL_ALLOC_READ_EXEC, and RTEMS_RTL_ALLOC_READ_WRITE.

Referenced by rtems_rtl_alloc_module_new(), and rtems_rtl_obj_free().

rtems_rtl_alloc_module_new()

bool rtems_rtl_alloc_module_new	(	void **	text_base,
		size_t	text_size,
		void **	const_base,
		size_t	const_size,
		void **	eh_base,
		size_t	eh_size,
		void **	data_base,
		size_t	data_size,
		void **	bss_base,
		size_t	bss_size
	)

Allocate the memory for a module given the size of the text, const, data and bss sections.

If any part of the allocation fails the no memory is allocated.

Parameters

text_base	Pointer to the text base pointer.
text_size	The size of the read/exec section.
const_base	Pointer to the const base pointer.
const_size	The size of the read only section.
eh_base	Pointer to the eh base pointer.
eh_size	The size of the eh section.
data_base	Pointer to the data base pointer.
data_size	The size of the read/write secton.
bss_base	Pointer to the bss base pointer.
bss_size	The size of the read/write.

Return values

true	The memory has been allocated.
false	The allocation of memory has failed.

References rtems_rtl_alloc_module_del(), rtems_rtl_alloc_new(), RTEMS_RTL_ALLOC_READ, RTEMS_RTL_ALLOC_READ_EXEC, and RTEMS_RTL_ALLOC_READ_WRITE.

Referenced by rtems_rtl_obj_load_sections().

rtems_rtl_alloc_new()

void* rtems_rtl_alloc_new	(	rtems_rtl_alloc_tag_t	tag,
		size_t	size,
		bool	zero
	)

The Runtime Loader allocator new allocates new memory and optionally clear the memory if requested.

Parameters

tag	The type of allocation request.
size	The size of the allocation.
zero	If true the memory is cleared.

Returns

void* The memory address or NULL is not memory available.

Referenced by rtems_rtl_alloc_module_new(), rtems_rtl_obj_alloc(), and rtems_rtl_symbol_table_open().