RTEMS Run-Time Linker Object Support. More...

#include <rtems.h>
#include <rtems/chain.h>
#include <rtems/rtl/rtl-sym.h>
#include <rtems/rtl/rtl-unresolved.h>

Data Structures
struct	rtems_rtl_loader_format

struct	rtems_rtl_loader_table

struct	rtems_rtl_obj_sect

struct	rtems_rtl_obj_depends

struct	rtems_rtl_obj

Macros
#define	RTEMS_RTL_FMT_ELF (1 << 0)

#define	RTEMS_RTL_FMT_COMP (1 << 1)

#define	RTEMS_RTL_FMT_PRIVATE (1 << 16)

#define	RTEMS_RTL_OBJ_SECT_TEXT (1 << 0)

#define	RTEMS_RTL_OBJ_SECT_CONST (1 << 1)

#define	RTEMS_RTL_OBJ_SECT_DATA (1 << 2)

#define	RTEMS_RTL_OBJ_SECT_BSS (1 << 3)

#define	RTEMS_RTL_OBJ_SECT_EH (1 << 4)

#define	RTEMS_RTL_OBJ_SECT_TLS (1 << 5)

#define	RTEMS_RTL_OBJ_SECT_REL (1 << 6)

#define	RTEMS_RTL_OBJ_SECT_RELA (1 << 7)

#define	RTEMS_RTL_OBJ_SECT_SYM (1 << 8)

#define	RTEMS_RTL_OBJ_SECT_STR (1 << 9)

#define	RTEMS_RTL_OBJ_SECT_ALLOC (1 << 10

#define	RTEMS_RTL_OBJ_SECT_LOAD (1 << 11)

#define	RTEMS_RTL_OBJ_SECT_WRITE (1 << 12)

#define	RTEMS_RTL_OBJ_SECT_EXEC (1 << 13)

#define	RTEMS_RTL_OBJ_SECT_ZERO (1 << 14)

#define	RTEMS_RTL_OBJ_SECT_LINK (1 << 15)

#define	RTEMS_RTL_OBJ_SECT_CTOR (1 << 16)

#define	RTEMS_RTL_OBJ_SECT_DTOR (1 << 17)

#define	RTEMS_RTL_OBJ_SECT_LOCD (1 << 18)

#define	RTEMS_RTL_OBJ_SECT_ARCH_ALLOC (1 << 19)

#define	RTEMS_RTL_OBJ_SECT_TYPES

#define	RTEMS_RTL_OBJ_LOCKED (1 << 0)

#define	RTEMS_RTL_OBJ_UNRESOLVED (1 << 1)

#define	RTEMS_RTL_OBJ_BASE (1 << 2)

#define	RTEMS_RTL_OBJ_RELOC_TAG (1 << 3)

#define	RTEMS_RTL_OBJ_DEP_VISITED (1 << 4)

#define	RTEMS_RTL_OBJ_CTOR_RUN (1 << 5)

Typedefs
typedef struct rtems_rtl_loader_format	rtems_rtl_loader_format

typedef bool(*	rtems_rtl_loader_check) (rtems_rtl_obj *obj, int fd)

typedef bool(*	rtems_rtl_loader_load) (rtems_rtl_obj *obj, int fd)

typedef bool(*	rtems_rtl_loader_unload) (rtems_rtl_obj *obj)

typedef rtems_rtl_loader_format (	rtems_rtl_loader_sig) (void)

typedef struct rtems_rtl_loader_table	rtems_rtl_loader_table

typedef bool(*	rtems_rtl_obj_depends_iterator) (rtems_rtl_obj obj, rtems_rtl_obj dependent, void *data)

typedef bool(*	rtems_rtl_obj_sect_handler) (rtems_rtl_obj obj, int fd, rtems_rtl_obj_sect sect, void *data)

Functions
rtems_rtl_obj *	rtems_rtl_obj_alloc (void)

bool	rtems_rtl_obj_free (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_unresolved (rtems_rtl_obj *obj)

bool	rtems_rtl_parse_name (const char name, const char aname, const char oname, off_t ooffset)

bool	rtems_rtl_obj_find_file (rtems_rtl_obj obj, const char name)

bool	rtems_rtl_obj_add_section (rtems_rtl_obj obj, int section, const char name, size_t size, off_t offset, uint32_t alignment, int link, int info, uint32_t flags)

void	rtems_rtl_obj_erase_sections (rtems_rtl_obj *obj)

rtems_rtl_obj_sect *	rtems_rtl_obj_find_section (const rtems_rtl_obj obj, const char name)

rtems_rtl_obj_sect *	rtems_rtl_obj_find_section_by_index (const rtems_rtl_obj *obj, int index)

rtems_rtl_obj_sect *	rtems_rtl_obj_find_section_by_mask (const rtems_rtl_obj *obj, int index, uint32_t mask)

bool	rtems_rtl_obj_alloc_dependents (rtems_rtl_obj *obj, size_t dependents)

void	rtems_rtl_obj_erase_dependents (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_add_dependent (rtems_rtl_obj obj, rtems_rtl_obj dependent)

bool	rtems_rtl_obj_remove_dependencies (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_iterate_dependents (rtems_rtl_obj obj, rtems_rtl_obj_depends_iterator iterator, void data)

size_t	rtems_rtl_obj_text_size (const rtems_rtl_obj *obj)

uint32_t	rtems_rtl_obj_text_alignment (const rtems_rtl_obj *obj)

size_t	rtems_rtl_obj_const_size (const rtems_rtl_obj *obj)

uint32_t	rtems_rtl_obj_const_alignment (const rtems_rtl_obj *obj)

size_t	rtems_rtl_obj_eh_size (const rtems_rtl_obj *obj)

uint32_t	rtems_rtl_obj_eh_alignment (const rtems_rtl_obj *obj)

size_t	rtems_rtl_obj_data_size (const rtems_rtl_obj *obj)

uint32_t	rtems_rtl_obj_data_alignment (const rtems_rtl_obj *obj)

size_t	rtems_rtl_obj_bss_size (const rtems_rtl_obj *obj)

uint32_t	rtems_rtl_obj_bss_alignment (const rtems_rtl_obj *obj)

size_t	rtems_rtl_obj_tramp_size (const rtems_rtl_obj *obj)

uint32_t	rtems_rtl_obj_tramp_alignment (const rtems_rtl_obj *obj)

bool	rtems_rtl_obj_relocate (rtems_rtl_obj obj, int fd, rtems_rtl_obj_sect_handler handler, void data)

void	rtems_rtl_obj_synchronize_cache (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_relocate_unresolved (rtems_rtl_unresolv_reloc reloc, rtems_rtl_obj_sym sym)

bool	rtems_rtl_obj_load_symbols (rtems_rtl_obj obj, int fd, rtems_rtl_obj_sect_handler handler, void data)

bool	rtems_rtl_obj_alloc_sections (rtems_rtl_obj obj, int fd, rtems_rtl_obj_sect_handler handler, void data)

bool	rtems_rtl_obj_resize_sections (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_load_sections (rtems_rtl_obj obj, int fd, rtems_rtl_obj_sect_handler handler, void data)

bool	rtems_rtl_obj_ctors_to_run (rtems_rtl_obj *obj)

void	rtems_rtl_obj_run_ctors (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_dtors_to_run (rtems_rtl_obj *obj)

void	rtems_rtl_obj_run_dtors (rtems_rtl_obj *obj)

size_t	rtems_rtl_obj_get_reference (rtems_rtl_obj *obj)

void	rtems_rtl_obj_inc_reference (rtems_rtl_obj *obj)

void	rtems_rtl_obj_dec_reference (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_orphaned (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_load (rtems_rtl_obj *obj)

bool	rtems_rtl_obj_unload (rtems_rtl_obj *obj)

Detailed Description

RTEMS Run-Time Linker Object Support.

Macro Definition Documentation

◆ RTEMS_RTL_FMT_ELF

#define RTEMS_RTL_FMT_ELF (1 << 0)

Loader format flags.

◆ RTEMS_RTL_OBJ_BASE

#define RTEMS_RTL_OBJ_BASE (1 << 2)

The base image.

◆ RTEMS_RTL_OBJ_CTOR_RUN

#define RTEMS_RTL_OBJ_CTOR_RUN (1 << 5)

Constructors have been called.

◆ RTEMS_RTL_OBJ_DEP_VISITED

#define RTEMS_RTL_OBJ_DEP_VISITED (1 << 4)

Dependency loop detection.

◆ RTEMS_RTL_OBJ_LOCKED

#define RTEMS_RTL_OBJ_LOCKED (1 << 0)

Object file descriptor flags. Lock the object file so it cannot be unloaded.

◆ RTEMS_RTL_OBJ_RELOC_TAG

#define RTEMS_RTL_OBJ_RELOC_TAG (1 << 3)

Tag the object as visited when reloc parsing.

◆ RTEMS_RTL_OBJ_SECT_ALLOC

#define RTEMS_RTL_OBJ_SECT_ALLOC (1 << 10

Section allocates runtime memory.

◆ RTEMS_RTL_OBJ_SECT_ARCH_ALLOC

#define RTEMS_RTL_OBJ_SECT_ARCH_ALLOC (1 << 19)

Section use arch allocator.

◆ RTEMS_RTL_OBJ_SECT_BSS

#define RTEMS_RTL_OBJ_SECT_BSS (1 << 3)

Section holds program bss.

◆ RTEMS_RTL_OBJ_SECT_CONST

#define RTEMS_RTL_OBJ_SECT_CONST (1 << 1)

Section holds program text.

◆ RTEMS_RTL_OBJ_SECT_CTOR

#define RTEMS_RTL_OBJ_SECT_CTOR (1 << 16)

Section contains constructors.

◆ RTEMS_RTL_OBJ_SECT_DATA

#define RTEMS_RTL_OBJ_SECT_DATA (1 << 2)

Section holds program data.

◆ RTEMS_RTL_OBJ_SECT_DTOR

#define RTEMS_RTL_OBJ_SECT_DTOR (1 << 17)

Section contains destructors.

◆ RTEMS_RTL_OBJ_SECT_EH

#define RTEMS_RTL_OBJ_SECT_EH (1 << 4)

Section holds exception data.

◆ RTEMS_RTL_OBJ_SECT_EXEC

#define RTEMS_RTL_OBJ_SECT_EXEC (1 << 13)

Section is executable.

◆ RTEMS_RTL_OBJ_SECT_LINK

#define RTEMS_RTL_OBJ_SECT_LINK (1 << 15)

Section is link-ordered.

◆ RTEMS_RTL_OBJ_SECT_LOAD

#define RTEMS_RTL_OBJ_SECT_LOAD (1 << 11)

Section is loaded from object file.

◆ RTEMS_RTL_OBJ_SECT_LOCD

#define RTEMS_RTL_OBJ_SECT_LOCD (1 << 18)

Section has been located.

◆ RTEMS_RTL_OBJ_SECT_REL

#define RTEMS_RTL_OBJ_SECT_REL (1 << 6)

Section holds relocation recs.

◆ RTEMS_RTL_OBJ_SECT_RELA

#define RTEMS_RTL_OBJ_SECT_RELA (1 << 7)

Section holds reloc addend recs.

◆ RTEMS_RTL_OBJ_SECT_STR

#define RTEMS_RTL_OBJ_SECT_STR (1 << 9)

Section holds strings.

◆ RTEMS_RTL_OBJ_SECT_SYM

#define RTEMS_RTL_OBJ_SECT_SYM (1 << 8)

Section holds symbols.

◆ RTEMS_RTL_OBJ_SECT_TEXT

#define RTEMS_RTL_OBJ_SECT_TEXT (1 << 0)

Flags for the various section types. Section holds program text.

◆ RTEMS_RTL_OBJ_SECT_TLS

#define RTEMS_RTL_OBJ_SECT_TLS (1 << 5)

Section holds TLS data.

◆ RTEMS_RTL_OBJ_SECT_TYPES

#define RTEMS_RTL_OBJ_SECT_TYPES

Value:

                                  (RTEMS_RTL_OBJ_SECT_TEXT | \
                                  RTEMS_RTL_OBJ_SECT_CONST | \
                                  RTEMS_RTL_OBJ_SECT_DATA | \
                                  RTEMS_RTL_OBJ_SECT_BSS | \
                                  RTEMS_RTL_OBJ_SECT_TLS | \
                                  RTEMS_RTL_OBJ_SECT_EH)

Section types mask.

◆ RTEMS_RTL_OBJ_SECT_WRITE

#define RTEMS_RTL_OBJ_SECT_WRITE (1 << 12)

Section is writable, ie data.

◆ RTEMS_RTL_OBJ_SECT_ZERO

#define RTEMS_RTL_OBJ_SECT_ZERO (1 << 14)

Section is preset to zero.

◆ RTEMS_RTL_OBJ_UNRESOLVED

#define RTEMS_RTL_OBJ_UNRESOLVED (1 << 1)

The object file has unresolved external symbols.

Typedef Documentation

◆ rtems_rtl_loader_check

typedef bool(* rtems_rtl_loader_check) (rtems_rtl_obj *obj, int fd)

The type of the format loader check handler. This handler checks the format and if it is detected as suitable it returns true.

◆ rtems_rtl_loader_format

typedef struct rtems_rtl_loader_format rtems_rtl_loader_format

Loader format definition.

◆ rtems_rtl_loader_load

typedef bool(* rtems_rtl_loader_load) (rtems_rtl_obj *obj, int fd)

The type of the format loader load handler. This handler loads the specific format.

◆ rtems_rtl_loader_sig

typedef rtems_rtl_loader_format *(* rtems_rtl_loader_sig) (void)

The type of the format loader signature handler. This handler checks the format signature.

◆ rtems_rtl_loader_table

typedef struct rtems_rtl_loader_table rtems_rtl_loader_table

Table for supported loadable formats.

◆ rtems_rtl_loader_unload

typedef bool(* rtems_rtl_loader_unload) (rtems_rtl_obj *obj)

The type of the format loader unload handler. This handler unloads the specific format.

◆ rtems_rtl_obj_depends_iterator

typedef bool(* rtems_rtl_obj_depends_iterator) (rtems_rtl_obj *obj, rtems_rtl_obj *dependent, void *data)

Dependency iterator.

◆ rtems_rtl_obj_sect_handler

typedef bool(* rtems_rtl_obj_sect_handler) (rtems_rtl_obj *obj, int fd, rtems_rtl_obj_sect *sect, void *data)

A section handler is called once for each section that needs to be processed by this handler. The handler is specific to a task.

Parameters

obj	The object file's descriptor the section belongs too.
fd	The file descriptor of the object file beling loaded.
sect	The section the handler is being invoked to handle.
data	A user supplied data variable.

Return values

true	The operation was successful.
false	The operation failed and the RTL has been set.

Function Documentation

◆ rtems_rtl_obj_add_dependent()

bool rtems_rtl_obj_add_dependent	(	rtems_rtl_obj *	obj,
		rtems_rtl_obj *	dependent
	)

Add an object file to the dependents table.

Parameters

obj	The object file's descriptor.
dependent	The dependent object file to add.

Return values

true	The dependent has been added to the table.
false	There is no space in the table.

◆ rtems_rtl_obj_add_section()

bool rtems_rtl_obj_add_section	(	rtems_rtl_obj *	obj,
		int	section,
		const char *	name,
		size_t	size,
		off_t	offset,
		uint32_t	alignment,
		int	link,
		int	info,
		uint32_t	flags
	)

Add a section to the object descriptor.

Parameters

obj	The object file's descriptor.
section	The section's index number.
name	The name of the section.
size	The size of the section in memory.
offset	The offset of the section in the object file.
alignment	The alignment of the section in memory.
link	The section's link field (from the ELF format).
info	The section's info field (from the ELF format).
flags	The section's flags.

Return values

true	The section has been added.
false	The section has not been added. See the RTL error.

◆ rtems_rtl_obj_alloc()

rtems_rtl_obj * rtems_rtl_obj_alloc ( void )

Allocate an object structure on the heap.

Return values

NULL	No memory for the object.

◆ rtems_rtl_obj_alloc_dependents()

bool rtems_rtl_obj_alloc_dependents	(	rtems_rtl_obj *	obj,
		size_t	dependents
	)

Allocate a table for dependent objects.

Parameters

obj	The object file's descriptor.
dependents	The size of the table.

Return values

true	The table was allocated.
false	The alloction failed.

◆ rtems_rtl_obj_alloc_sections()

bool rtems_rtl_obj_alloc_sections	(	rtems_rtl_obj *	obj,
		int	fd,
		rtems_rtl_obj_sect_handler	handler,
		void *	data
	)

Allocate the sections. If a handler is provided (not NULL) it is called for all section.

Parameters

obj	The object file's descriptor.
fd	The object file's file descriptor.
handler	The object file's format specific allocation handler.
data	User specific data handle.

Return values

true	The object has been sucessfully loaded.
false	The load failed. The RTL error has been set.

◆ rtems_rtl_obj_bss_alignment()

uint32_t rtems_rtl_obj_bss_alignment ( const rtems_rtl_obj * obj )

The bss section alignment for the object file. Only use once all the sections has been added. The section alignment is the alignment of the first bss type section loaded the bss section.

You can assume the alignment is a positive integral power of 2 if not 0 or

If 0 or 1 then there is no alignment.

Parameters

obj	The object file's descriptor.

Returns: uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.

◆ rtems_rtl_obj_bss_size()

size_t rtems_rtl_obj_bss_size ( const rtems_rtl_obj * obj )

The bss section size. Only use once all the sections has been added. It includes alignments between sections that are part of the object's bss area.

Parameters

obj	The object file's descriptor.

Returns: size_t The size of the bss area of the object file.

◆ rtems_rtl_obj_const_alignment()

uint32_t rtems_rtl_obj_const_alignment ( const rtems_rtl_obj * obj )

The const section alignment for the object file. Only use once all the sections has been added. The section alignment is the alignment of the first const type section loaded the const section.

You can assume the alignment is a positive integral power of 2 if not 0 or

If 0 or 1 then there is no alignment.

Parameters

obj	The object file's descriptor.

Returns: uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.

◆ rtems_rtl_obj_const_size()

size_t rtems_rtl_obj_const_size ( const rtems_rtl_obj * obj )

The const section size. Only use once all the sections has been added. It includes alignments between sections that are part of the object's const area. The consts sections are included in this section.

Parameters

obj	The object file's descriptor.

Returns: size_t The size of the const area of the object file.

◆ rtems_rtl_obj_ctors_to_run()

bool rtems_rtl_obj_ctors_to_run ( rtems_rtl_obj * obj )

Does the object have constructors to run?

Returns: bool True if there are constructors to run.

◆ rtems_rtl_obj_data_alignment()

uint32_t rtems_rtl_obj_data_alignment ( const rtems_rtl_obj * obj )

The data section alignment for the object file. Only use once all the sections has been added. The section alignment is the alignment of the first data type section loaded the data section.

You can assume the alignment is a positive integral power of 2 if not 0 or

If 0 or 1 then there is no alignment.

Parameters

obj	The object file's descriptor.

Returns: uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.

◆ rtems_rtl_obj_data_size()

size_t rtems_rtl_obj_data_size ( const rtems_rtl_obj * obj )

The data section size. Only use once all the sections has been added. It includes alignments between sections that are part of the object's data area.

Parameters

obj	The object file's descriptor.

Returns: size_t The size of the data area of the object file.

◆ rtems_rtl_obj_dec_reference()

void rtems_rtl_obj_dec_reference ( rtems_rtl_obj * obj )

Decrement the object file reference count.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_dtors_to_run()

bool rtems_rtl_obj_dtors_to_run ( rtems_rtl_obj * obj )

Does the object have destructors to run?

Returns: bool True if there are destructors to run.

◆ rtems_rtl_obj_eh_alignment()

uint32_t rtems_rtl_obj_eh_alignment ( const rtems_rtl_obj * obj )

The eh section alignment for the object file. Only use once all the sections has been added. The section alignment is the alignment of the first bss type section loaded the bss section.

You can assume the alignment is a positive integral power of 2 if not 0 or

If 0 or 1 then there is no alignment.

Parameters

obj	The object file's descriptor.

Returns: uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.

◆ rtems_rtl_obj_eh_size()

size_t rtems_rtl_obj_eh_size ( const rtems_rtl_obj * obj )

The eh section size. Only use once all the sections has been added. It includes alignments between sections that are part of the object's bss area.

Parameters

obj	The object file's descriptor.

Returns: size_t The size of the bss area of the object file.

◆ rtems_rtl_obj_erase_dependents()

void rtems_rtl_obj_erase_dependents ( rtems_rtl_obj * obj )

Erase the object file descriptor's dependents.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_erase_sections()

void rtems_rtl_obj_erase_sections ( rtems_rtl_obj * obj )

Erase the object file descriptor's sections.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_find_file()

bool rtems_rtl_obj_find_file	(	rtems_rtl_obj *	obj,
		const char *	name
	)

Find an object file on disk that matches the name. The object descriptor is fill in with the various parts of a name. A name can have archive, object file and offset components. The search path in the RTL is searched.

Parameters

obj	The object file's descriptor.
name	The name to locate on disk.

Return values

true	The file has been found.
false	The file could not be located. The RTL error has been set.

◆ rtems_rtl_obj_find_section()

rtems_rtl_obj_sect * rtems_rtl_obj_find_section	(	const rtems_rtl_obj *	obj,
		const char *	name
	)

Find the section given a name.

Parameters

obj	The object file's descriptor.
name	The name of the section to find.

Return values

NULL	The section was not found.

Returns: rtems_rtl_obj_sect_t* The named section.

◆ rtems_rtl_obj_find_section_by_index()

rtems_rtl_obj_sect * rtems_rtl_obj_find_section_by_index	(	const rtems_rtl_obj *	obj,
		int	index
	)

Find a section given a section's index number.

Parameters

obj	The object file's descriptor.
index	The section's index to find.

Return values

NULL	The section was not found.

Returns: rtems_rtl_obj_sect_t* The found section.

◆ rtems_rtl_obj_find_section_by_mask()

rtems_rtl_obj_sect * rtems_rtl_obj_find_section_by_mask	(	const rtems_rtl_obj *	obj,
		int	index,
		uint32_t	mask
	)

Find a section given a section's mask. The index is the section after which the mask is matched. An index of -1 starts the search from the beginning of the section list. You can find multiple matches for a mask by passing the index of the last section that matched the mask on a subsequent call.

Parameters

obj	The object file's descriptor.
index	The section's index to start searching from, -1 for the start.
mask	The section's mask to match against the section's flags.

Return values

NULL	The section was not found.

Returns: rtems_rtl_obj_sect_t* The found section.

◆ rtems_rtl_obj_free()

bool rtems_rtl_obj_free ( rtems_rtl_obj * obj )

Free the object structure and related resources.

Parameters

obj	The object file's descriptor to free.

Return values

false	The object has dependences.
true	The object has been freed.

◆ rtems_rtl_obj_get_reference()

size_t rtems_rtl_obj_get_reference ( rtems_rtl_obj * obj )

Get the object file reference count.

Return values

int	The object file's reference count.

◆ rtems_rtl_obj_inc_reference()

void rtems_rtl_obj_inc_reference ( rtems_rtl_obj * obj )

Increment the object file reference count.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_iterate_dependents()

bool rtems_rtl_obj_iterate_dependents	(	rtems_rtl_obj *	obj,
		rtems_rtl_obj_depends_iterator	iterator,
		void *	data
	)

Iterate over the module dependenices.

Parameters

obj	The object file's descriptor.
handler	The iterator handler. Returns true to end.
data	User data passed to the iterator.

Return values

true	The iterator handler returned true.
false	The iterator handler returned false.

◆ rtems_rtl_obj_load()

bool rtems_rtl_obj_load ( rtems_rtl_obj * obj )

Load the object file, reading all sections into memory, symbols and performing any relocation fixups.

Parameters

obj	The object file's descriptor.

Return values

true	The object file has been loaded.
false	The load failed. The RTL error has been set.

◆ rtems_rtl_obj_load_sections()

bool rtems_rtl_obj_load_sections	(	rtems_rtl_obj *	obj,
		int	fd,
		rtems_rtl_obj_sect_handler	handler,
		void *	data
	)

Load the sections that have been allocated memory in the target. The bss type section does not load any data, it is set to 0. The text and data sections read the detault data from the object file into the target memory.

Parameters

obj	The object file's descriptor.
fd	The object file's file descriptor.
handler	The object file's format specific load handler.
data	User specific data handle.

Return values

true	The object has been sucessfully loaded.
false	The load failed. The RTL error has been set.

◆ rtems_rtl_obj_load_symbols()

bool rtems_rtl_obj_load_symbols	(	rtems_rtl_obj *	obj,
		int	fd,
		rtems_rtl_obj_sect_handler	handler,
		void *	data
	)

Load the symbols from the object file. Only the exported or public symbols are read into memory and held in the global symbol table.

Parameters

obj	The object file's descriptor.
fd	The object file's file descriptor.
handler	The object file's format specific symbol handler.
data	User specific data handle.

Return values

true	The object file's symbol where loaded.
false	The symbol loading failed. The RTL error is set.

◆ rtems_rtl_obj_orphaned()

bool rtems_rtl_obj_orphaned ( rtems_rtl_obj * obj )

Is the object file orphaned? An orphaned object file is not locked, has no users and it not being referenced.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_relocate()

bool rtems_rtl_obj_relocate	(	rtems_rtl_obj *	obj,
		int	fd,
		rtems_rtl_obj_sect_handler	handler,
		void *	data
	)

Relocate the object file. The object file's section are parsed for any relocation type sections.

Parameters

obj	The object file's descriptor.
fd	The object file's file descriptor.
handler	The object file's format specific relocation handler.
data	User specific data handle.

Return values

true	The object file was relocated.
false	The relocation failed. The RTL error is set.

◆ rtems_rtl_obj_relocate_unresolved()

bool rtems_rtl_obj_relocate_unresolved	(	rtems_rtl_unresolv_reloc *	reloc,
		rtems_rtl_obj_sym *	sym
	)

Relocate an object file's unresolved reference.

Parameters

rec	The unresolved relocation record.
sym	The unresolved relocation's referenced symbol.

Return values

true	The object file record was relocated.
false	The relocation failed. The RTL error is set.

◆ rtems_rtl_obj_remove_dependencies()

bool rtems_rtl_obj_remove_dependencies ( rtems_rtl_obj * obj )

Remove dependencies. This decrements the dependent object file references.

Parameters

obj	The object file's descriptor.

Return values

true	The dependencies have been removed.
false	There is no space in the table.

◆ rtems_rtl_obj_resize_sections()

bool rtems_rtl_obj_resize_sections ( rtems_rtl_obj * obj )

Resize the sections.

Parameters

obj	The object file's descriptor.

Return values

true	The object has been sucessfully loaded.
false	The load failed. The RTL error has been set.

◆ rtems_rtl_obj_run_ctors()

void rtems_rtl_obj_run_ctors ( rtems_rtl_obj * obj )

Invoke the constructors the object has. Constructors are a table of pointers to "void (*)(void);" where NULL pointers are skipped. The table's size is taken from the section's size. The objet ELF specific code is responisble for flagging which sections contain constructors.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_run_dtors()

void rtems_rtl_obj_run_dtors ( rtems_rtl_obj * obj )

Invoke the destructors the object has. Destructors are a table of pointers to "void (*)(void);" where NULL pointers are skipped. The table's size is taken from the section's size. The objet ELF specific code is responisble for flagging which sections contain destructors.

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_synchronize_cache()

void rtems_rtl_obj_synchronize_cache ( rtems_rtl_obj * obj )

Synchronize caches to make code visible to CPU(s)

Parameters

obj	The object file's descriptor.

◆ rtems_rtl_obj_text_alignment()

uint32_t rtems_rtl_obj_text_alignment ( const rtems_rtl_obj * obj )

The text section alignment for the object file. Only use once all the sections has been added. The section alignment is the alignment of the first text type section loaded the text section.

You can assume the alignment is a positive integral power of 2 if not 0 or

If 0 or 1 then there is no alignment.

Parameters

obj	The object file's descriptor.

Returns: uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.

◆ rtems_rtl_obj_text_size()

size_t rtems_rtl_obj_text_size ( const rtems_rtl_obj * obj )

The text section size. Only use once all the sections has been added. It includes alignments between sections that are part of the object's text area. The consts sections are included in this section.

Parameters

obj	The object file's descriptor.

Returns: size_t The size of the text area of the object file.

◆ rtems_rtl_obj_tramp_alignment()

uint32_t rtems_rtl_obj_tramp_alignment ( const rtems_rtl_obj * obj )

The trampolinme alignment for the architecture.

This is implemented and set in the architecture backend.

Parameters

obj	The object file's descriptor.

Returns: uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.

◆ rtems_rtl_obj_tramp_size()

size_t rtems_rtl_obj_tramp_size ( const rtems_rtl_obj * obj )

The trampoline size.

Parameters

obj	The object file's descriptor.

Returns: size_t The size of the trampoline memory of the object file.

◆ rtems_rtl_obj_unload()

bool rtems_rtl_obj_unload ( rtems_rtl_obj * obj )

Unload the object file, erasing all symbols and releasing all memory.

Parameters

obj	The object file's descriptor.

Return values

true	The object file has been unloaded.
false	The unload failed. The RTL error has been set.

◆ rtems_rtl_obj_unresolved()

bool rtems_rtl_obj_unresolved ( rtems_rtl_obj * obj )

Does the object file have unresolved external references ? If it does the results of executing code is unpredictable.

Parameters

obj	The object file's descriptor.

Return values

true	The object file has unresolved externals.
false	The object file has all external references resolved.

◆ rtems_rtl_parse_name()

bool rtems_rtl_parse_name	(	const char *	name,
		const char **	aname,
		const char **	oname,
		off_t *	ooffset
	)

Parses a filename and returns newly allocated strings with the archive name, object name, and the object's offset

Parameters

name	The filename of the object
aname	Address of a string pointer that holds the archive name
oname	Address of a string pointer that holds the object name
ooffset	Address of an int that holds the object offset

Return values

true	The parsing was successful
false	The parsing was unsuccessful

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ RTEMS_RTL_FMT_ELF

◆ RTEMS_RTL_OBJ_BASE

◆ RTEMS_RTL_OBJ_CTOR_RUN

◆ RTEMS_RTL_OBJ_DEP_VISITED

◆ RTEMS_RTL_OBJ_LOCKED

◆ RTEMS_RTL_OBJ_RELOC_TAG

◆ RTEMS_RTL_OBJ_SECT_ALLOC

◆ RTEMS_RTL_OBJ_SECT_ARCH_ALLOC

◆ RTEMS_RTL_OBJ_SECT_BSS

◆ RTEMS_RTL_OBJ_SECT_CONST

◆ RTEMS_RTL_OBJ_SECT_CTOR

◆ RTEMS_RTL_OBJ_SECT_DATA

◆ RTEMS_RTL_OBJ_SECT_DTOR

◆ RTEMS_RTL_OBJ_SECT_EH

◆ RTEMS_RTL_OBJ_SECT_EXEC

◆ RTEMS_RTL_OBJ_SECT_LINK

◆ RTEMS_RTL_OBJ_SECT_LOAD

◆ RTEMS_RTL_OBJ_SECT_LOCD

◆ RTEMS_RTL_OBJ_SECT_REL

◆ RTEMS_RTL_OBJ_SECT_RELA

◆ RTEMS_RTL_OBJ_SECT_STR

◆ RTEMS_RTL_OBJ_SECT_SYM

◆ RTEMS_RTL_OBJ_SECT_TEXT

◆ RTEMS_RTL_OBJ_SECT_TLS

◆ RTEMS_RTL_OBJ_SECT_TYPES

◆ RTEMS_RTL_OBJ_SECT_WRITE

◆ RTEMS_RTL_OBJ_SECT_ZERO

◆ RTEMS_RTL_OBJ_UNRESOLVED

Typedef Documentation

◆ rtems_rtl_loader_check

◆ rtems_rtl_loader_format

◆ rtems_rtl_loader_load

◆ rtems_rtl_loader_sig

◆ rtems_rtl_loader_table

◆ rtems_rtl_loader_unload

◆ rtems_rtl_obj_depends_iterator

◆ rtems_rtl_obj_sect_handler

Function Documentation

◆ rtems_rtl_obj_add_dependent()

◆ rtems_rtl_obj_add_section()

◆ rtems_rtl_obj_alloc()

◆ rtems_rtl_obj_alloc_dependents()

◆ rtems_rtl_obj_alloc_sections()

◆ rtems_rtl_obj_bss_alignment()

◆ rtems_rtl_obj_bss_size()

◆ rtems_rtl_obj_const_alignment()

◆ rtems_rtl_obj_const_size()

◆ rtems_rtl_obj_ctors_to_run()

◆ rtems_rtl_obj_data_alignment()

◆ rtems_rtl_obj_data_size()

◆ rtems_rtl_obj_dec_reference()

◆ rtems_rtl_obj_dtors_to_run()

◆ rtems_rtl_obj_eh_alignment()

◆ rtems_rtl_obj_eh_size()

◆ rtems_rtl_obj_erase_dependents()

◆ rtems_rtl_obj_erase_sections()

◆ rtems_rtl_obj_find_file()

◆ rtems_rtl_obj_find_section()

◆ rtems_rtl_obj_find_section_by_index()

◆ rtems_rtl_obj_find_section_by_mask()

◆ rtems_rtl_obj_free()

◆ rtems_rtl_obj_get_reference()

◆ rtems_rtl_obj_inc_reference()

◆ rtems_rtl_obj_iterate_dependents()

◆ rtems_rtl_obj_load()

◆ rtems_rtl_obj_load_sections()

◆ rtems_rtl_obj_load_symbols()

◆ rtems_rtl_obj_orphaned()

◆ rtems_rtl_obj_relocate()

◆ rtems_rtl_obj_relocate_unresolved()

◆ rtems_rtl_obj_remove_dependencies()

◆ rtems_rtl_obj_resize_sections()

◆ rtems_rtl_obj_run_ctors()

◆ rtems_rtl_obj_run_dtors()