source: rtems/cpukit/include/rtems/rtl/rtl.h @ d9800ac

5
Last change on this file since d9800ac was d9800ac, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 3, 2018 at 5:36:10 AM

libdl: Use self-contained recursive mutex

Update #2843.

  • Property mode set to 100644
File size: 10.3 KB
Line 
1/*
2 *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
3 *
4 *  The license and distribution terms for this file may be
5 *  found in the file LICENSE in this distribution or at
6 *  http://www.rtems.org/license/LICENSE.
7 */
8
9/**
10 * @file
11 *
12 * @ingroup rtems_rtl
13 *
14 * @brief RTEMS Run-Time Linker
15 *
16 * This is the POSIX interface to run-time loading of code into RTEMS.
17 */
18
19#if !defined (_RTEMS_RTL_H_)
20#define _RTEMS_RTL_H_
21
22#include <link.h>
23#include <rtems/chain.h>
24#include <rtems/thread.h>
25
26#include <rtems/rtl/rtl-allocator.h>
27#include <rtems/rtl/rtl-fwd.h>
28#include <rtems/rtl/rtl-obj.h>
29#include <rtems/rtl/rtl-obj-cache.h>
30#include <rtems/rtl/rtl-obj-comp.h>
31#include <rtems/rtl/rtl-unresolved.h>
32
33#ifdef __cplusplus
34extern "C" {
35#endif /* __cplusplus */
36
37/**
38 * @defgroup rtems_rtl RTEMS Runtime Link Editor
39 *
40 * The module implements a runtime link editor with the standard dlopen, and
41 * dlclose family of functions.
42 *
43 * The runtime link editor is different to that found on Unix type systems. The
44 * object modules are compiled for PIC or position indepentent code and
45 * therefore require relocating when loaded.
46 *
47 * The object file format is currently ELF and object files can be separate
48 * files or in an archive. Object files in an archive are referenced by
49 * specifing 'archive:object' format. For example 'libfoo.a:bar.o'.
50 */
51
52/**
53 * Macros to glue two tokens.
54 */
55#ifdef __STDC__
56#define RTL_XGLUE(a,b) a##b
57#else
58#define RTL_XGLUE(a,b) a/**/b
59#endif
60
61#define RTL_GLUE(a,b) RTL_XGLUE(a,b)
62
63/**
64 * The number of buckets in the global symbol table.
65 */
66#define RTEMS_RTL_SYMS_GLOBAL_BUCKETS (32)
67
68/**
69 * The number of relocation record per block in the unresolved table.
70 */
71#define RTEMS_RTL_UNRESOLVED_BLOCK_SIZE (64)
72
73/**
74 * The global debugger interface variable.
75 */
76extern struct r_debug _rtld_debug;
77
78/**
79 * Debugger break function. Call when debugging to have it read the _rtld_debug
80 * variable.
81 */
82extern void _rtld_debug_state (void);
83
84/**
85 * The type of constructor/destructor function.
86 */
87typedef void (*rtems_rtl_cdtor_t)(void);
88
89/**
90 * The global RTL data. This structure is allocated on the heap when the first
91 * call to the RTL is made and never released.
92 *
93 * The global symbol table is a hash table held in this structure and the
94 * actual symbols are part of the object's structure. If this is a problem we
95 * could look at a hash table per object file.
96 */
97struct rtems_rtl_data_s
98{
99  rtems_recursive_mutex  lock;           /**< The RTL lock */
100  rtems_rtl_alloc_data_t allocator;      /**< The allocator data. */
101  rtems_chain_control    objects;        /**< List if loaded object files. */
102  const char*            paths;          /**< Search paths for archives. */
103  rtems_rtl_symbols_t    globals;        /**< Global symbol table. */
104  rtems_rtl_unresolved_t unresolved;     /**< Unresolved symbols. */
105  rtems_rtl_obj_t*       base;           /**< Base object file. */
106  rtems_rtl_obj_cache_t  symbols;        /**< Symbols object file cache. */
107  rtems_rtl_obj_cache_t  strings;        /**< Strings object file cache. */
108  rtems_rtl_obj_cache_t  relocs;         /**< Relocations object file cache. */
109  rtems_rtl_obj_comp_t   decomp;         /**< The decompression compressor. */
110  int                    last_errno;     /**< Last error number. */
111  char                   last_error[64]; /**< Last error string. */
112};
113
114/**
115 * Get the RTL data with out locking. This call assumes the RTL is locked.
116 *
117 * @return rtems_rtl_data_t* The RTL data after being locked.
118 * @retval NULL The RTL data is not initialised.
119 */
120rtems_rtl_data_t* rtems_rtl_data (void);
121
122/**
123 * Get the RTL global symbol table with out locking. This call assmes the RTL
124 * is locked.
125 *
126 * @return rtems_rtl_symbols_t* The RTL global symbols after being locked.
127 * @retval NULL The RTL data is not initialised.
128 */
129rtems_rtl_symbols_t* rtems_rtl_global_symbols (void);
130
131/**
132 * Get the RTL resolved table with out locking. This call assmes the RTL
133 * is locked.
134 *
135 * @return rtems_rtl_unresolv_t* The RTL unresolved symbols and reloc records.
136 * @retval NULL The RTL data is not initialised.
137 */
138rtems_rtl_unresolved_t* rtems_rtl_unresolved (void);
139
140/**
141 * Get the RTL symbols, strings, or relocations object file caches. This call
142 * assmes the RTL is locked.
143 *
144 * @param symbols Pointer to the location to set the cache into. Returns NULL
145 *                is rtl is not initialised. If NULL is passed in no value set.
146 * @param strings Pointer to the location to set the cache into. Returns NULL
147 *                is rtl is not initialised. If NULL is passed in no value set.
148 * @param relocs Pointer to the location to set the cache into. Returns NULL
149 *               is rtl is not initialised. If NULL is passed in no value set.
150 */
151void rtems_rtl_obj_caches (rtems_rtl_obj_cache_t** symbols,
152                           rtems_rtl_obj_cache_t** strings,
153                           rtems_rtl_obj_cache_t** relocs);
154
155/**
156 * Flush all the object file caches.
157 */
158void rtems_rtl_obj_caches_flush (void);
159
160/**
161 * Get the RTL decompressor setting the cache and the offset in the file the
162 * compressed stream starts. This call assmes the RTL is locked.
163 *
164 * @param decomp Pointer to the location to set the compressor into. Returns
165 *               NULL is rtl is not initialised.
166 * @param cache The cache to read the file with. Saves needing an extrs buffer.
167 * @param offset The offset in the file the compressed stream starts.
168 */
169void rtems_rtl_obj_comp (rtems_rtl_obj_comp_t** decomp,
170                         rtems_rtl_obj_cache_t* cache,
171                         int                    fd,
172                         int                    compression,
173                         off_t                  offset);
174
175/**
176 * Lock the Run-time Linker.
177 *
178 * @return rtems_rtl_data_t* The RTL data after being locked.
179 * @retval NULL The RTL data could not be initialised or locked. Typically this
180 *              means the lock could not be created.
181 */
182rtems_rtl_data_t* rtems_rtl_lock (void);
183
184/**
185 * Unlock the Run-time Linker.
186 */
187void rtems_rtl_unlock (void);
188
189/**
190 * Check a pointer is a valid object file descriptor returning the pointer as
191 * that type.
192 *
193 * Assumes the RTL has been locked.
194 *
195 * @param handle Pointer to the object file to be validated.
196 * @return rtl_obj* The object file descriptor. NULL is returned if invalid.
197 */
198rtems_rtl_obj_t* rtems_rtl_check_handle (void* handle);
199
200/**
201 * Find the object given a file name.
202 *
203 * @param name The name of the object file.
204 * @retval NULL No object file with that name found.
205 * @return rtems_rtl_obj_t* The object file descriptor.
206 */
207rtems_rtl_obj_t* rtems_rtl_find_obj (const char* name);
208
209/**
210 * Load an object file into memory relocating it. It will not be resolved
211 * against other symbols in other object files or the base image.
212 *
213 * The name can be a file name for an object file or it can be encoded to
214 * reference an archive of object modules (static library). This encoding is
215 * specific to RTEMS and allows dependences to specify an archive without the
216 * searching overhead normally incurred by linkers locating object files in an
217 * archive. The file name format rules are:
218 *
219 *  1. Absolute file references a specific object file in the architecture
220 *     specific location on the file system.
221 *
222 *  2. Relative file references an object format file in the search path.
223 *
224 *  3. Absolute archive and file reference to a specific location in the file
225 *     system. The archive and file are encoded as 'archive:file [@@offset]'
226 *     where 'archive' is a valid file at the absolute path in the file system,
227 *     and 'file' is a contained in the archive, and optionally an offset to
228 *     the 'file' in the 'archive'. If no offset is provided the archive is
229 *     searched.
230 *
231 *  4. Relative archive and file in the search path. The encoding is the same
232 *     as described in item 3 of this list.
233 *
234 * Assumes the RTL has been locked.
235 *
236 * @param name The name of the object file.
237 * @param mode The mode of the load as defined by the dlopen call.
238 * @return rtl_obj* The object file descriptor. NULL is returned if the load fails.
239 */
240rtems_rtl_obj_t* rtems_rtl_load_object (const char* name, int mode);
241
242/**
243 * Unload an object file. This only happens when the user count is 0.
244 *
245 * Assumes the RTL has been locked.
246 *
247 * @param obj The object file descriptor.
248 * @retval true The object file has been unloaded.
249 * @retval false The object file could not be unloaded.
250 */
251bool rtems_rtl_unload_object (rtems_rtl_obj_t* obj);
252
253/**
254 * Run any constructor functions the object file may contain. This call
255 * assumes the linker is unlocked.
256 *
257 * @param obj The object file.
258 */
259void rtems_rtl_run_ctors (rtems_rtl_obj_t* obj);
260
261/**
262 * Get the last error message clearing it. This operation locks the run time
263 * linker and therefore keeps the RTL thread safe but this call is not thread
264 * safe is multiple threads are loading object files at the same time. This
265 * call is provided to map to the dlopen family of calls.
266 *
267 * @param message Pointer to a buffer to copy the message into.
268 * @param max_message The maximum message that can be copied.
269 * @return int The last error number.
270 */
271int rtems_rtl_get_error (char* message, size_t max_message);
272
273/**
274 * Append the path to the search path.
275 *
276 * @param path The path to append.
277 * @retval false The path could not be appended.
278 * @retval true The path was appended.
279 */
280bool rtems_rtl_path_append (const char* path);
281
282/**
283 * Prepend the path to the search path.
284 *
285 * @param path The path to prepend.
286 * @retval false The path could not be prepended.
287 * @retval true The path was prepended.
288 */
289
290bool rtems_rtl_path_prepend (const char* path);
291
292/**
293 * Add an exported symbol table to the global symbol table. This call is
294 * normally used by an object file when loaded that contains a global symbol
295 * table.
296 *
297 * @param esyms The exported symbol table.
298 * @param count The size of the exported symbol table.
299 */
300void rtems_rtl_base_sym_global_add (const unsigned char* esyms,
301                                    unsigned int         count);
302
303/**
304 * Return the object file descriptor for the base image. The object file
305 * descriptor returned is created when the run time linker is initialised.
306 *
307 * Assumes the RTL has been locked.
308 *
309 * @return rtl_obj* The object file descriptor for the base image. NULL is
310 *                  returned if the load fails.
311 */
312rtems_rtl_obj_t* rtems_rtl_baseimage (void);
313
314#ifdef __cplusplus
315}
316#endif /* __cplusplus */
317
318#endif
Note: See TracBrowser for help on using the repository browser.