forked from Imagelibrary/rtems
321 lines
10 KiB
C
321 lines
10 KiB
C
/*
|
|
* COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
|
|
*
|
|
* The license and distribution terms for this file may be
|
|
* found in the file LICENSE in this distribution or at
|
|
* http://www.rtems.com/license/LICENSE.
|
|
*/
|
|
/**
|
|
* @file
|
|
*
|
|
* @ingroup rtems_rtl
|
|
*
|
|
* @brief RTEMS Run-Time Linker
|
|
*
|
|
* This is the POSIX interface to run-time loading of code into RTEMS.
|
|
*/
|
|
|
|
#if !defined (_RTEMS_RTL_H_)
|
|
#define _RTEMS_RTL_H_
|
|
|
|
#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>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/**
|
|
* @defgroup rtems_rtl RTEMS Runtime Link Editor
|
|
*
|
|
* The module implements a runtime link editor with the standard dlopen, and
|
|
* dlclose family of functions.
|
|
*
|
|
* The runtime link editor is different to that found on Unix type systems. The
|
|
* object modules are compiled for PIC or position indepentent code and
|
|
* therefore require relocating when loaded.
|
|
*
|
|
* The object file format is currently ELF and object files can be separate
|
|
* files or in an archive. Object files in an archive are referenced by
|
|
* specifing 'archive:object' format. For example 'libfoo.a:bar.o'.
|
|
*/
|
|
|
|
/**
|
|
* Macros to glue two tokens.
|
|
*/
|
|
#ifdef __STDC__
|
|
#define RTL_XGLUE(a,b) a##b
|
|
#else
|
|
#define RTL_XGLUE(a,b) a/**/b
|
|
#endif
|
|
|
|
#define RTL_GLUE(a,b) RTL_XGLUE(a,b)
|
|
|
|
/**
|
|
* The number of buckets in the global symbol table.
|
|
*/
|
|
#define RTEMS_RTL_SYMS_GLOBAL_BUCKETS (32)
|
|
|
|
/**
|
|
* The number of relocation record per block in the unresolved table.
|
|
*/
|
|
#define RTEMS_RTL_UNRESOLVED_BLOCK_SIZE (64)
|
|
|
|
/**
|
|
* The global debugger interface variable.
|
|
*/
|
|
extern struct r_debug _rtld_debug;
|
|
|
|
/**
|
|
* Debugger break function. Call when debugging to have it read the _rtld_debug
|
|
* variable.
|
|
*/
|
|
extern void _rtld_debug_state (void);
|
|
|
|
/**
|
|
* The type of constructor/destructor function.
|
|
*/
|
|
typedef void (*rtems_rtl_cdtor_t)(void);
|
|
|
|
/**
|
|
* The global RTL data. This structure is allocated on the heap when the first
|
|
* call to the RTL is made and never released.
|
|
*
|
|
* The global symbol table is a hash table held in this structure and the
|
|
* actual symbols are part of the object's structure. If this is a problem we
|
|
* could look at a hash table per object file.
|
|
*/
|
|
struct rtems_rtl_data_s
|
|
{
|
|
rtems_id lock; /**< The RTL lock id */
|
|
rtems_rtl_alloc_data_t allocator; /**< The allocator data. */
|
|
rtems_chain_control objects; /**< List if loaded object files. */
|
|
const char* paths; /**< Search paths for archives. */
|
|
rtems_rtl_symbols_t globals; /**< Global symbol table. */
|
|
rtems_rtl_unresolved_t unresolved; /**< Unresolved symbols. */
|
|
rtems_rtl_obj_t* base; /**< Base object file. */
|
|
rtems_rtl_obj_cache_t symbols; /**< Symbols object file cache. */
|
|
rtems_rtl_obj_cache_t strings; /**< Strings object file cache. */
|
|
rtems_rtl_obj_cache_t relocs; /**< Relocations object file cache. */
|
|
rtems_rtl_obj_comp_t decomp; /**< The decompression compressor. */
|
|
int last_errno; /**< Last error number. */
|
|
char last_error[64]; /**< Last error string. */
|
|
};
|
|
|
|
/**
|
|
* Get the RTL data with out locking. This call assmes the RTL is locked.
|
|
*
|
|
* @return rtems_rtl_data_t* The RTL data after being locked.
|
|
* @retval NULL The RTL data is not initialised.
|
|
*/
|
|
rtems_rtl_data_t* rtems_rtl_data (void);
|
|
|
|
/**
|
|
* Get the RTL global symbol table with out locking. This call assmes the RTL
|
|
* is locked.
|
|
*
|
|
* @return rtems_rtl_symbols_t* The RTL global symbols after being locked.
|
|
* @retval NULL The RTL data is not initialised.
|
|
*/
|
|
rtems_rtl_symbols_t* rtems_rtl_global_symbols (void);
|
|
|
|
/**
|
|
* Get the RTL resolved table with out locking. This call assmes the RTL
|
|
* is locked.
|
|
*
|
|
* @return rtems_rtl_unresolv_t* The RTL unresolved symbols and reloc records.
|
|
* @retval NULL The RTL data is not initialised.
|
|
*/
|
|
rtems_rtl_unresolved_t* rtems_rtl_unresolved (void);
|
|
|
|
/**
|
|
* Get the RTL symbols, strings, or relocations object file caches. This call
|
|
* assmes the RTL is locked.
|
|
*
|
|
* @param 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.
|
|
* @param 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.
|
|
* @param 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.
|
|
*/
|
|
void rtems_rtl_obj_caches (rtems_rtl_obj_cache_t** symbols,
|
|
rtems_rtl_obj_cache_t** strings,
|
|
rtems_rtl_obj_cache_t** relocs);
|
|
|
|
/**
|
|
* Flush all the object file caches.
|
|
*/
|
|
void rtems_rtl_obj_caches_flush (void);
|
|
|
|
/**
|
|
* Get the RTL decompressor setting the cache and the offset in the file the
|
|
* compressed stream starts. This call assmes the RTL is locked.
|
|
*
|
|
* @param decomp Pointer to the location to set the compressor into. Returns
|
|
* NULL is rtl is not initialised.
|
|
* @param cache The cache to read the file with. Saves needing an extrs buffer.
|
|
* @param offset The offset in the file the compressed stream starts.
|
|
*/
|
|
void rtems_rtl_obj_comp (rtems_rtl_obj_comp_t** decomp,
|
|
rtems_rtl_obj_cache_t* cache,
|
|
int fd,
|
|
int compression,
|
|
off_t offset);
|
|
|
|
/**
|
|
* Lock the Run-time Linker.
|
|
*
|
|
* @return rtems_rtl_data_t* The RTL data after being locked.
|
|
* @retval NULL The RTL data could not be initialised or locked. Typically this
|
|
* means the lock could not be created.
|
|
*/
|
|
rtems_rtl_data_t* rtems_rtl_lock (void);
|
|
|
|
/**
|
|
* Unlock the Run-time Linker.
|
|
*
|
|
* @return True The RTL is unlocked.
|
|
* @return False The RTL could not be unlocked. Not much you can do.
|
|
*/
|
|
bool rtems_rtl_unlock (void);
|
|
|
|
/**
|
|
* Check a pointer is a valid object file descriptor returning the pointer as
|
|
* that type.
|
|
*
|
|
* Assumes the RTL has been locked.
|
|
*
|
|
* @param handle Pointer to the object file to be validated.
|
|
* @return rtl_obj* The object file descriptor. NULL is returned if invalid.
|
|
*/
|
|
rtems_rtl_obj_t* rtems_rtl_check_handle (void* handle);
|
|
|
|
/**
|
|
* Find the object given a file name.
|
|
*
|
|
* @param name The name of the object file.
|
|
* @retval NULL No object file with that name found.
|
|
* @return rtems_rtl_obj_t* The object file descriptor.
|
|
*/
|
|
rtems_rtl_obj_t* rtems_rtl_find_obj (const char* name);
|
|
|
|
/**
|
|
* 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:
|
|
*
|
|
* 1. Absolute file references a specific object file in the architecture
|
|
* specific location on the file system.
|
|
*
|
|
* 2. Relative file references an object format file in the search path.
|
|
*
|
|
* 3. 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.
|
|
*
|
|
* 4. 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.
|
|
*
|
|
* @param name The name of the object file.
|
|
* @param mode The mode of the load as defined by the dlopen call.
|
|
* @return rtl_obj* The object file descriptor. NULL is returned if the load fails.
|
|
*/
|
|
rtems_rtl_obj_t* rtems_rtl_load_object (const char* name, int mode);
|
|
|
|
/**
|
|
* Unload an object file. This only happens when the user count is 0.
|
|
*
|
|
* Assumes the RTL has been locked.
|
|
*
|
|
* @param obj The object file descriptor.
|
|
* @retval true The object file has been unloaded.
|
|
* @retval false The object file could not be unloaded.
|
|
*/
|
|
bool rtems_rtl_unload_object (rtems_rtl_obj_t* obj);
|
|
|
|
/**
|
|
* Run any constructor functions the object file may contain. This call
|
|
* assumes the linker is unlocked.
|
|
*
|
|
* @param obj The object file.
|
|
*/
|
|
void rtems_rtl_run_ctors (rtems_rtl_obj_t* obj);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param message Pointer to a buffer to copy the message into.
|
|
* @param max_message The maximum message that can be copied.
|
|
* @return int The last error number.
|
|
*/
|
|
int rtems_rtl_get_error (char* message, size_t max_message);
|
|
|
|
/**
|
|
* Append the path to the search path.
|
|
*
|
|
* @path The path to append.
|
|
* @retval false The path could not be appended.
|
|
* @retval true The path was appended.
|
|
*/
|
|
bool rtems_rtl_path_append (const char* path);
|
|
|
|
/**
|
|
* Prepend the path to the search path.
|
|
*
|
|
* @path The path to prepend.
|
|
* @retval false The path could not be prepended.
|
|
* @retval true The path was prepended.
|
|
*/
|
|
|
|
bool rtems_rtl_path_prepend (const char* path);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param esyms The exported symbol table.
|
|
* @param count The size of the exported symbol table.
|
|
*/
|
|
void rtems_rtl_base_sym_global_add (const unsigned char* esyms,
|
|
unsigned int count);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @return rtl_obj* The object file descriptor for the base image. NULL is
|
|
* returned if the load fails.
|
|
*/
|
|
rtems_rtl_obj_t* rtems_rtl_baseimage (void);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
#endif
|