RTEMS  5.0.0
Data Structures | Macros | Typedefs | Enumerations | Functions
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

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

Symbol search and loading results.

◆ rtems_rtl_archive_symbol

RTL Archive symbols.

◆ rtems_rtl_archive_symbols

RTL Archive symbols.

◆ rtems_rtl_archives

RTL Archive data.

Enumeration Type Documentation

◆ 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
archivesThe archives data to search.
nameThe archive to load.
Return values
trueThe 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
archivesThe archives data to search.
symbolThe symbol name to search for.
loadIf 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
archivesThe 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
archivesThe archives data to open.
configThe 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
archivesThe archives data to refresh.
Return values
falseThe 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
fdOpen file handle for the archive.
fsizeSize of the archive. name Pointer to the name string.
offsetThe offset of the file in the archive.
sizeThe size of the file in the archive.
extended_namesThe offset in the archive for the extended names.
errorThe error handler called on an error.
Return values
trueThe file was found in the archive.
falseThe file was not found.