RTEMS Run-Time Linker. More...

#include <link.h>
#include <rtems.h>
#include <rtems/chain.h>
#include <rtems/rtl/rtl-allocator.h>
#include <rtems/rtl/rtl-fwd.h>
#include <rtems/rtl/rtl-obj.h>
#include <rtems/rtl/rtl-obj-cache.h>
#include <rtems/rtl/rtl-obj-comp.h>
#include <rtems/rtl/rtl-unresolved.h>

Include dependency graph for rtl.h:

Go to the source code of this file.

Data Structures
struct	rtems_rtl_data_s
	The global RTL data. More...

Macros
#define	RTL_XGLUE(a, b) ab
	Macros to glue two tokens.

#define	RTL_GLUE(a, b) RTL_XGLUE(a,b)

#define	RTEMS_RTL_SYMS_GLOBAL_BUCKETS (32)
	The number of buckets in the global symbol table.

#define	RTEMS_RTL_UNRESOLVED_BLOCK_SIZE (64)
	The number of relocation record per block in the unresolved table.

Typedefs
typedef void(*	rtems_rtl_cdtor_t) (void)
	The type of constructor/destructor function.

Functions
void	_rtld_debug_state (void)
	Debugger break function. More...

rtems_rtl_data_t *	rtems_rtl_data (void)
	Get the RTL data with out locking. More...

rtems_rtl_symbols_t *	rtems_rtl_global_symbols (void)
	Get the RTL global symbol table with out locking. More...

rtems_rtl_unresolved_t *	rtems_rtl_unresolved (void)
	Get the RTL resolved table with out locking. More...

void	rtems_rtl_obj_caches (rtems_rtl_obj_cache_t symbols, rtems_rtl_obj_cache_t strings, rtems_rtl_obj_cache_t **relocs)
	Get the RTL symbols, strings, or relocations object file caches. More...

void	rtems_rtl_obj_caches_flush (void)
	Flush all the object file caches.

void	rtems_rtl_obj_comp (rtems_rtl_obj_comp_t *decomp, rtems_rtl_obj_cache_t cache, int fd, int compression, off_t offset)
	Get the RTL decompressor setting the cache and the offset in the file the compressed stream starts. More...

rtems_rtl_data_t *	rtems_rtl_lock (void)
	Lock the Run-time Linker. More...

bool	rtems_rtl_unlock (void)
	Unlock the Run-time Linker. More...

rtems_rtl_obj_t *	rtems_rtl_check_handle (void *handle)
	Check a pointer is a valid object file descriptor returning the pointer as that type. More...

rtems_rtl_obj_t *	rtems_rtl_find_obj (const char *name)
	Find the object given a file name. More...

rtems_rtl_obj_t *	rtems_rtl_load_object (const char *name, int mode)
	Load an object file into memory relocating it. More...

bool	rtems_rtl_unload_object (rtems_rtl_obj_t *obj)
	Unload an object file. More...

void	rtems_rtl_run_ctors (rtems_rtl_obj_t *obj)
	Run any constructor functions the object file may contain. More...

int	rtems_rtl_get_error (char *message, size_t max_message)
	Get the last error message clearing it. More...

bool	rtems_rtl_path_append (const char *path)
	Append the path to the search path. More...

bool	rtems_rtl_path_prepend (const char *path)
	Prepend the path to the search path. More...

void	rtems_rtl_base_sym_global_add (const unsigned char *esyms, unsigned int count)
	Add an exported symbol table to the global symbol table. More...

rtems_rtl_obj_t *	rtems_rtl_baseimage (void)
	Return the object file descriptor for the base image. More...

Variables
struct r_debug	_rtld_debug
	The global debugger interface variable.

Detailed Description

RTEMS Run-Time Linker.

This is the POSIX interface to run-time loading of code into RTEMS.

Function Documentation

◆ _rtld_debug_state()

void _rtld_debug_state ( void )

Debugger break function.

Call when debugging to have it read the _rtld_debug variable.

◆ rtems_rtl_base_sym_global_add()

void rtems_rtl_base_sym_global_add	(	const unsigned char *	esyms,
		unsigned int	count
	)

Add an exported symbol table to the global symbol table.

This call is normally used by an object file when loaded that contains a global symbol table.

Parameters

esyms	The exported symbol table.
count	The size of the exported symbol table.

◆ rtems_rtl_baseimage()

rtems_rtl_obj_t* rtems_rtl_baseimage ( void )

Return the object file descriptor for the base image.

The object file descriptor returned is created when the run time linker is initialised.

Assumes the RTL has been locked.

Returns: rtl_obj* The object file descriptor for the base image. NULL is returned if the load fails.

◆ rtems_rtl_check_handle()

rtems_rtl_obj_t* rtems_rtl_check_handle ( void * handle )

Check a pointer is a valid object file descriptor returning the pointer as that type.

Assumes the RTL has been locked.

Parameters

handle Pointer to the object file to be validated.

Returns: rtl_obj* The object file descriptor. NULL is returned if invalid.

References rtems_rtl_data_s::objects, rtems_chain_first(), and rtems_chain_is_tail().

◆ rtems_rtl_data()

rtems_rtl_data_t* rtems_rtl_data ( void )

Get the RTL data with out locking.

This call assumes the RTL is locked.

Returns: rtems_rtl_data_t* The RTL data after being locked.

Return values

NULL	The RTL data is not initialised.

◆ rtems_rtl_find_obj()

rtems_rtl_obj_t* rtems_rtl_find_obj ( const char * name )

Find the object given a file name.

Parameters

name	The name of the object file.

Return values

NULL	No object file with that name found.

Returns: rtems_rtl_obj_t* The object file descriptor.

References rtems_rtl_data_s::objects, rtems_chain_first(), rtems_chain_is_tail(), and rtems_rtl_parse_name().

◆ rtems_rtl_get_error()

int rtems_rtl_get_error	(	char *	message,
		size_t	max_message
	)

Get the last error message clearing it.

This operation locks the run time linker and therefore keeps the RTL thread safe but this call is not thread safe is multiple threads are loading object files at the same time. This call is provided to map to the dlopen family of calls.

Parameters

message	Pointer to a buffer to copy the message into.
max_message	The maximum message that can be copied.

Returns: int The last error number.

◆ rtems_rtl_global_symbols()

rtems_rtl_symbols_t* rtems_rtl_global_symbols ( void )

Get the RTL global symbol table with out locking.

This call assmes the RTL is locked.

Returns: rtems_rtl_symbols_t* The RTL global symbols after being locked.

Return values

NULL	The RTL data is not initialised.

References rtems_rtl_data_s::globals, and rtems_rtl_set_error().

Referenced by rtems_rtl_symbol_global_find().

◆ rtems_rtl_load_object()

rtems_rtl_obj_t* rtems_rtl_load_object	(	const char *	name,
		int	mode
	)

Load an object file into memory relocating it.

It will not be resolved against other symbols in other object files or the base image.

The name can be a file name for an object file or it can be encoded to reference an archive of object modules (static library). This encoding is specific to RTEMS and allows dependences to specify an archive without the searching overhead normally incurred by linkers locating object files in an archive. The file name format rules are:

Absolute file references a specific object file in the architecture specific location on the file system.
Relative file references an object format file in the search path.
Absolute archive and file reference to a specific location in the file system. The archive and file are encoded as 'archive:file [@offset]' where 'archive' is a valid file at the absolute path in the file system, and 'file' is a contained in the archive, and optionally an offset to the 'file' in the 'archive'. If no offset is provided the archive is searched.
Relative archive and file in the search path. The encoding is the same as described in item 3 of this list.

Assumes the RTL has been locked.

Parameters

name	The name of the object file.
mode	The mode of the load as defined by the dlopen call.

Returns: rtl_obj* The object file descriptor. NULL is returned if the load fails.

References rtems_rtl_trace().

◆ rtems_rtl_lock()

rtems_rtl_data_t* rtems_rtl_lock ( void )

Lock the Run-time Linker.

Returns: rtems_rtl_data_t* The RTL data after being locked.

Return values

NULL	The RTL data could not be initialised or locked. Typically this means the lock could not be created.

◆ rtems_rtl_obj_caches()

void rtems_rtl_obj_caches	(	rtems_rtl_obj_cache_t **	symbols,
		rtems_rtl_obj_cache_t **	strings,
		rtems_rtl_obj_cache_t **	relocs
	)

Get the RTL symbols, strings, or relocations object file caches.

This call assmes the RTL is locked.

Parameters

symbols	Pointer to the location to set the cache into. Returns NULL is rtl is not initialised. If NULL is passed in no value set.
strings	Pointer to the location to set the cache into. Returns NULL is rtl is not initialised. If NULL is passed in no value set.
relocs	Pointer to the location to set the cache into. Returns NULL is rtl is not initialised. If NULL is passed in no value set.

References rtems_rtl_data_s::relocs, rtems_rtl_data_s::strings, and rtems_rtl_data_s::symbols.

Referenced by rtems_rtl_elf_file_check(), rtems_rtl_elf_file_load(), and rtems_rtl_rap_file_load().

◆ rtems_rtl_obj_comp()

void rtems_rtl_obj_comp	(	rtems_rtl_obj_comp_t **	decomp,
		rtems_rtl_obj_cache_t *	cache,
		int	fd,
		int	compression,
		off_t	offset
	)

Get the RTL decompressor setting the cache and the offset in the file the compressed stream starts.

This call assmes the RTL is locked.

Parameters

decomp	Pointer to the location to set the compressor into. Returns NULL is rtl is not initialised.
cache	The cache to read the file with. Saves needing an extrs buffer.
offset	The offset in the file the compressed stream starts.

References rtems_rtl_data_s::decomp, and rtems_rtl_obj_comp_set().

◆ rtems_rtl_path_append()

bool rtems_rtl_path_append ( const char * path )

Append the path to the search path.

Parameters

path	The path to append.

Return values

false	The path could not be appended.
true	The path was appended.

◆ rtems_rtl_path_prepend()

bool rtems_rtl_path_prepend ( const char * path )

Prepend the path to the search path.

Parameters

path	The path to prepend.

Return values

false	The path could not be prepended.
true	The path was prepended.

◆ rtems_rtl_run_ctors()

void rtems_rtl_run_ctors ( rtems_rtl_obj_t * obj )

Run any constructor functions the object file may contain.

This call assumes the linker is unlocked.

Parameters

obj	The object file.

References rtems_rtl_obj_run_ctors().

◆ rtems_rtl_unload_object()

bool rtems_rtl_unload_object ( rtems_rtl_obj_t * obj )

Unload an object file.

This only happens when the user count is 0.

Assumes the RTL has been locked.

Parameters

obj	The object file descriptor.

Return values

true	The object file has been unloaded.
false	The object file could not be unloaded.

References rtems_rtl_trace().

◆ rtems_rtl_unlock()

bool rtems_rtl_unlock ( void )

Unlock the Run-time Linker.

Returns: True The RTL is unlocked.; False The RTL could not be unlocked. Not much you can do.

References rtems_rtl_data_s::lock, rtems_semaphore_release(), and RTEMS_SUCCESSFUL.

◆ rtems_rtl_unresolved()

rtems_rtl_unresolved_t* rtems_rtl_unresolved ( void )

Get the RTL resolved table with out locking.

This call assmes the RTL is locked.

Returns: rtems_rtl_unresolv_t* The RTL unresolved symbols and reloc records.

Return values

NULL	The RTL data is not initialised.

References rtems_rtl_set_error(), and rtems_rtl_data_s::unresolved.

Referenced by rtems_rtl_unresolved_interate(), and rtems_rtl_unresolved_remove().

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Function Documentation

◆ _rtld_debug_state()

◆ rtems_rtl_base_sym_global_add()

◆ rtems_rtl_baseimage()

◆ rtems_rtl_check_handle()

◆ rtems_rtl_data()

◆ rtems_rtl_find_obj()

◆ rtems_rtl_get_error()

◆ rtems_rtl_global_symbols()

◆ rtems_rtl_load_object()

◆ rtems_rtl_lock()

◆ rtems_rtl_obj_caches()

◆ rtems_rtl_obj_comp()

◆ rtems_rtl_path_append()

◆ rtems_rtl_path_prepend()

◆ rtems_rtl_run_ctors()

◆ rtems_rtl_unload_object()

◆ rtems_rtl_unlock()

◆ rtems_rtl_unresolved()