rtl-unresolved.h File Reference

RTEMS Run-Time Linker Object File Unresolved Relocations Table. More...

#include <rtems.h>
#include <rtems/chain.h>
#include "rtl-obj-fwd.h"

Go to the source code of this file.

Data Structures
struct	rtems_rtl_unresolv_symbol
struct	rtems_rtl_unresolv_reloc
struct	rtems_rtl_tramp_reloc
struct	rtems_rtl_unresolv_rec
struct	rtems_rtl_unresolv_block
struct	rtems_rtl_unresolved

Macros
#define	RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE   (1 << 0)
#define	RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR   (1 << 1)

Typedefs
typedef uint32_t	rtems_rtl_word
typedef enum rtems_rtl_unresolved_rtype	rtems_rtl_unresolved_rtype
typedef struct rtems_rtl_unresolv_symbol	rtems_rtl_unresolv_symbol
typedef struct rtems_rtl_unresolv_reloc	rtems_rtl_unresolv_reloc
typedef struct rtems_rtl_tramp_reloc	rtems_rtl_tramp_reloc
typedef struct rtems_rtl_unresolv_rec	rtems_rtl_unresolv_rec
typedef struct rtems_rtl_unresolv_block	rtems_rtl_unresolv_block
typedef struct rtems_rtl_unresolved	rtems_rtl_unresolved
typedef bool	rtems_rtl_unresolved_iterator(rtems_rtl_unresolv_rec *rec, void *data)

Enumerations
enum	rtems_rtl_unresolved_rtype { rtems_rtl_unresolved_empty = 0, rtems_rtl_unresolved_symbol = 1, rtems_rtl_unresolved_reloc = 2, rtems_rtl_trampoline_reloc = 3 }

Functions
bool	rtems_rtl_unresolved_table_open (rtems_rtl_unresolved *unresolved, size_t block_records)
void	rtems_rtl_unresolved_table_close (rtems_rtl_unresolved *unresolved)
bool	rtems_rtl_unresolved_iterate (rtems_rtl_unresolved_iterator iterator, void *data)
bool	rtems_rtl_unresolved_add (rtems_rtl_obj *obj, const uint16_t flags, const char *name, const uint16_t sect, const rtems_rtl_word *rel)
void	rtems_rtl_unresolved_resolve (void)
bool	rtems_rtl_unresolved_remove (rtems_rtl_obj *obj, const char *name, const uint16_t sect, const rtems_rtl_word *rel)
void	rtems_rtl_unresolved_set_archive_search (void)
void	rtems_rtl_unresolved_dump (void)

Detailed Description

RTEMS Run-Time Linker Object File Unresolved Relocations Table.

The unresolved relocation table holds relocations in a loaded object file which reference unresolved external symbols. The support is needed to allow dependent object files to load. In the case of dependent object files one will have unresolved externals until the dependent object file is also loaded. There is no load order that resolves this.

The unresolved relocation table is a single table used by all object files with unresolved symbols. It made of blocks linked together where blocks are allocated as requiered. The table is always maintained compacted. That is as relocations are resolved and removed the table is compacted. The only pointer in the table is the object file poniter. This is used to identify which object the relocation belongs to. There are no linking or back pointers in the unresolved relocations table. The table is scanned for each object file's relocations. This is not fast but the table should be small and if it happens to grow large you have other more pressing issues to resolve in your application.

The table holds two (2) types of records:

Symbol name strings.

Relocations.

The symbol name a relocation references is held in a specific symbol name string record in the table the relocation record references. The record counts the number of references and the string is removed from the table when the reference count reaches 0. There can be many relocations referencing the symbol. The strings are referenced by a single 16bit unsigned integer which is the count of the string in the table.

The section the relocation is for in the object is the section number. The relocation data is series of machine word sized fields:

Offset in the section.

Relocation info (format specific)

Additional format specific data.

Macro Definition Documentation

RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR

#define RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR   (1 << 1)

The symbol load has an error.

RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE

#define RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE   (1 << 0)

Unresolved external symbol flags.Search the archive.

Typedef Documentation

rtems_rtl_tramp_reloc

typedef struct rtems_rtl_tramp_reloc rtems_rtl_tramp_reloc

Trampolines require the relocation records to be held

rtems_rtl_unresolv_block

typedef struct rtems_rtl_unresolv_block rtems_rtl_unresolv_block

Unresolved blocks.

rtems_rtl_unresolv_rec

typedef struct rtems_rtl_unresolv_rec rtems_rtl_unresolv_rec

Unresolved externals records.

rtems_rtl_unresolv_reloc

typedef struct rtems_rtl_unresolv_reloc rtems_rtl_unresolv_reloc

Unresolved externals symbols require the relocation records to be held and referenced.

rtems_rtl_unresolv_symbol

typedef struct rtems_rtl_unresolv_symbol rtems_rtl_unresolv_symbol

Unresolved externals symbols. The symbols are reference counted and separate from the relocation records because a number of records could reference the same symbol.

The name is extended in the allocator of the record in the unresolved data block. The 10 is a minimum that is added to by joining more than one record.

rtems_rtl_unresolved

typedef struct rtems_rtl_unresolved rtems_rtl_unresolved

Unresolved table holds the names and relocations.

rtems_rtl_unresolved_iterator

typedef bool rtems_rtl_unresolved_iterator(rtems_rtl_unresolv_rec *rec, void *data)

The iterator function used to iterate over the unresolved table.

Parameters

rec	The current iterator.
data	The user data.

Return values

true	The iterator has finished.
false	The iterator has not finished. Keep iterating.

rtems_rtl_unresolved_rtype

typedef enum rtems_rtl_unresolved_rtype rtems_rtl_unresolved_rtype

The types of records in the blocks.

rtems_rtl_word

typedef uint32_t rtems_rtl_word

Hack to work around machine size. This needs to be cleaned up to better support 64bit targets.

Enumeration Type Documentation

rtems_rtl_unresolved_rtype

enum rtems_rtl_unresolved_rtype

The types of records in the blocks.

Enumerator
rtems_rtl_unresolved_empty	The records is empty. Must always be 0
rtems_rtl_unresolved_symbol	The record is a symbol.
rtems_rtl_unresolved_reloc	The record is a relocation record.
rtems_rtl_trampoline_reloc	The record is a trampoline relocation record.

Function Documentation

rtems_rtl_unresolved_add()

bool rtems_rtl_unresolved_add	(	rtems_rtl_obj *	obj,
		const uint16_t	flags,
		const char *	name,
		const uint16_t	sect,
		const rtems_rtl_word *	rel
	)

Add a relocation to the list of unresolved relocations.

Parameters

unresolved	The unresolved symbol table.
obj	The object table the symbols are for.
flags	Format specific flags.
name	The symbol name the relocation references.
sect	The target section number the relocation references.
rel	The format specific relocation data.

Return values

true	The relocation has been added.
false	The relocation could not be added.

rtems_rtl_unresolved_dump()

void rtems_rtl_unresolved_dump

(

void

)

Dump the RTL unresolved data.

rtems_rtl_unresolved_iterate()

bool rtems_rtl_unresolved_iterate	(	rtems_rtl_unresolved_iterator	iterator,
		void *	data
	)

Iterate over the table of unresolved entries.

rtems_rtl_unresolved_remove()

bool rtems_rtl_unresolved_remove	(	rtems_rtl_obj *	obj,
		const char *	name,
		const uint16_t	sect,
		const rtems_rtl_word *	rel
	)

Remove a relocation from the list of unresolved relocations.

Parameters

unresolved	The unresolved symbol table.
obj	The object table the symbols are for.
esyms	The exported symbol table.
size	The size of the table in bytes.

rtems_rtl_unresolved_resolve()

void rtems_rtl_unresolved_resolve

(

void

)

Resolve the unresolved symbols.

rtems_rtl_unresolved_set_archive_search()

void rtems_rtl_unresolved_set_archive_search

(

void

)

Set all symbols to be archive searchable. This is done when the available archives have been refreshed and there are new archives to search for.

rtems_rtl_unresolved_table_close()

void rtems_rtl_unresolved_table_close

(

rtems_rtl_unresolved *

unresolved

)

Close the table and erase the blocks.

Parameters

unreolved

Close the unresolved table.

rtems_rtl_unresolved_table_open()

bool rtems_rtl_unresolved_table_open	(	rtems_rtl_unresolved *	unresolved,
		size_t	block_records
	)

Open an unresolved relocation table.

Parameters

unresolv	The unresolved table to open.
block_records	The number of records per block allocated.

Return values

true	The table is open.
false	The unresolved relocation table could not created. The RTL error has the error.