rtl-archive.h File Reference

RTEMS Run-Time Linker Archive. More...

#include <rtems.h>
#include <rtems/chain.h>
#include <rtems/printer.h>

Go to the source code of this file.

Data Structures
struct	rtems_rtl_archive_symbol
struct	rtems_rtl_archive_symbols
struct	rtems_rtl_archive
struct	rtems_rtl_archives

Macros
#define	RTEMS_RTL_ARCHIVE_USER_LOAD   (1 << 0)
#define	RTEMS_RTL_ARCHIVE_REMOVE   (1 << 1)
#define	RTEMS_RTL_ARCHIVE_LOAD   (1 << 2)

Typedefs
typedef enum rtems_rtl_archive_search	rtems_rtl_archive_search
typedef struct rtems_rtl_archive_symbol	rtems_rtl_archive_symbol
typedef struct rtems_rtl_archive_symbols	rtems_rtl_archive_symbols
typedef struct rtems_rtl_archive	rtems_rtl_archive
typedef struct rtems_rtl_archives	rtems_rtl_archives
typedef void(*	rtems_rtl_archive_error) (int num, const char *text)

Enumerations
enum	rtems_rtl_archive_search {   rtems_rtl_archive_search_not_found = 0, rtems_rtl_archive_search_found = 1, rtems_rtl_archive_search_loaded = 2, rtems_rtl_archive_search_error = 3,   rtems_rtl_archive_search_no_config = 4 }

Functions
void	rtems_rtl_archives_open (rtems_rtl_archives *archives, const char *config)
void	rtems_rtl_archives_close (rtems_rtl_archives *archives)
bool	rtems_rtl_archives_refresh (rtems_rtl_archives *archives)
bool	rtems_rtl_archive_load (rtems_rtl_archives *archives, const char *name)
rtems_rtl_archive_search	rtems_rtl_archive_obj_load (rtems_rtl_archives *archives, const char *symbol, bool load)
bool	rtems_rtl_obj_archive_find_obj (int fd, size_t fsize, const char **name, off_t *offset, size_t *size, off_t *extended_names, rtems_rtl_archive_error error)

Detailed Description

RTEMS Run-Time Linker Archive.

The RTL Archive module manages dependent loading of object files from archives. The archives need to have a ranlib generated symbol table.

This module reads a configuration file called rtl-libs.conf from a default directory of /etc. The file is a line per glob'ed path to archives to search for symbols.

The archive symbols are held in a per archive cache for searching.

Note

Errors in the reading of a config file, locating archives, reading symbol tables and loading object files are not considered RTL error reported to a user. The user error is undefined symbols.

Macro Definition Documentation

RTEMS_RTL_ARCHIVE_LOAD

#define RTEMS_RTL_ARCHIVE_LOAD   (1 << 2)

Load the achive.

RTEMS_RTL_ARCHIVE_REMOVE

#define RTEMS_RTL_ARCHIVE_REMOVE   (1 << 1)

The achive is not found.

RTEMS_RTL_ARCHIVE_USER_LOAD

#define RTEMS_RTL_ARCHIVE_USER_LOAD   (1 << 0)

Flags for archives.User forced load.

Typedef Documentation

rtems_rtl_archive

typedef struct rtems_rtl_archive rtems_rtl_archive

RTL Archive data.

rtems_rtl_archive_error

typedef void(* rtems_rtl_archive_error) (int num, const char *text)

Error handler call when finding an archive.

rtems_rtl_archive_search

typedef enum rtems_rtl_archive_search rtems_rtl_archive_search

Symbol search and loading results.

rtems_rtl_archive_symbol

typedef struct rtems_rtl_archive_symbol rtems_rtl_archive_symbol

RTL Archive symbols.

rtems_rtl_archive_symbols

typedef struct rtems_rtl_archive_symbols rtems_rtl_archive_symbols

RTL Archive symbols.

rtems_rtl_archives

typedef struct rtems_rtl_archives rtems_rtl_archives

RTL Archive data.

Enumeration Type Documentation

rtems_rtl_archive_search

enum rtems_rtl_archive_search

Symbol search and loading results.

Enumerator
rtems_rtl_archive_search_not_found	The search failed to find the symbol.
rtems_rtl_archive_search_found	The symbols was found.
rtems_rtl_archive_search_loaded	The symbol was found and the object file has been loaded
rtems_rtl_archive_search_error	There was an error searching or loading.
rtems_rtl_archive_search_no_config	There is no config or it is invalid.

Function Documentation

rtems_rtl_archive_load()

bool rtems_rtl_archive_load	(	rtems_rtl_archives *	archives,
		const char *	name
	)

Load an archive.

Parameters

archives	The archives data to search.
name	The archive to load.

Return values

true	The archive is loaded.

rtems_rtl_archive_obj_load()

rtems_rtl_archive_search rtems_rtl_archive_obj_load	(	rtems_rtl_archives *	archives,
		const char *	symbol,
		bool	load
	)

Search for a symbol and load the first object file that has the symbol.

Parameters

archives	The archives data to search.
symbol	The symbol name to search for.
load	If load the object file the symbol is found in else return the found not found status.

rtems_rtl_archives_close()

void rtems_rtl_archives_close

(

rtems_rtl_archives *

archives

)

Close the RTL archives support.

Parameters

archives

The archives data to close.

rtems_rtl_archives_open()

void rtems_rtl_archives_open	(	rtems_rtl_archives *	archives,
		const char *	config
	)

Open the RTL archives support with the specified configration file.

Parameters

archives	The archives data to open.
config	The path to the configuration file.

Returns

bool Returns is the archives are open.

rtems_rtl_archives_refresh()

bool rtems_rtl_archives_refresh

(

rtems_rtl_archives *

archives

)

Refresh the archives data. Check if the configuration has changes and if it has reload it. Check each path in the configuration and creates archive instances for new archives and remove archives not present any more.

Refreshing is a development aid so reboots can be avoided as users trial configurations that work.

Parameters

archives

The archives data to refresh.

Return values

false

The refresh failed, an error will have been set.

rtems_rtl_obj_archive_find_obj()

bool rtems_rtl_obj_archive_find_obj	(	int	fd,
		size_t	fsize,
		const char **	name,
		off_t *	offset,
		size_t *	size,
		off_t *	extended_names,
		rtems_rtl_archive_error	error
	)

Find a module in an archive returning the offset in the archive and the size. If the name field is pointing to a string pointer and that poniter is NULL and the offset is valid the name is extracted from the archive and filled in. This is used when loading a file from the archive after a symbol is found. The file name is not know and could be extended which requires searching the extended string table in the archive.

Parameters

fd	Open file handle for the archive.
fsize	Size of the archive. name Pointer to the name string.
offset	The offset of the file in the archive.
size	The size of the file in the archive.
extended_names	The offset in the archive for the extended names.
error	The error handler called on an error.

Return values

true	The file was found in the archive.
false	The file was not found.