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

Last change on this file since b36c5209 was b36c5209, checked in by Chris Johns <chrisj@…>, on May 3, 2019 at 12:15:20 AM

libdl: Do not access the ELF file while the allocator is locked.

  • Load symbols before allocation.
  • Parse reloc records and place any reloc recs in a cache to use while the allocator is locked.
  • Relocate symbols after section allocation.
  • Split section loading into allocation/locating and loading.
  • Update all arch back-ends with a new reloc interface to control tramp handling.
  • Add -a and -t to the object list shell command.

Closes #3741

  • Property mode set to 100644
File size: 12.9 KB
Line 
1/*
2 *  COPYRIGHT (c) 2012, 2018 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-archive.h>
28#include <rtems/rtl/rtl-fwd.h>
29#include <rtems/rtl/rtl-obj.h>
30#include <rtems/rtl/rtl-obj-cache.h>
31#include <rtems/rtl/rtl-obj-comp.h>
32#include <rtems/rtl/rtl-sym.h>
33#include <rtems/rtl/rtl-unresolved.h>
34
35#ifdef __cplusplus
36extern "C" {
37#endif /* __cplusplus */
38
39/**
40 * @defgroup rtems_rtl RTEMS Runtime Link Editor
41 *
42 * @ingroup RTEMSAPI
43 *
44 * The module implements a runtime link editor with the standard dlopen, and
45 * dlclose family of functions.
46 *
47 * The runtime link editor is different to that found on Unix type systems. The
48 * object modules are compiled for PIC or position independent code and
49 * therefore require relocating when loaded.
50 *
51 * The object file format is currently ELF and object files can be separate
52 * files or in an archive. Object files in an archive are referenced by
53 * specifying 'archive:object' format. For example 'libfoo.a:bar.o'.
54 */
55
56/**
57 * Macros to glue two tokens.
58 */
59#ifdef __STDC__
60#define RTL_XGLUE(a,b) a##b
61#else
62#define RTL_XGLUE(a,b) a/**/b
63#endif
64
65#define RTL_GLUE(a,b) RTL_XGLUE(a,b)
66
67/**
68 * The number of buckets in the global symbol table.
69 */
70#define RTEMS_RTL_SYMS_GLOBAL_BUCKETS (32)
71
72/**
73 * The number of relocation record per block in the unresolved table.
74 */
75#define RTEMS_RTL_UNRESOLVED_BLOCK_SIZE (256)
76
77/**
78 * The number of dependency record per block in the dependency table.
79 */
80#define RTEMS_RTL_DEPENDENCY_BLOCK_SIZE (16)
81
82/**
83 * The global debugger interface variable.
84 */
85extern struct r_debug _rtld_debug;
86
87/**
88 * Debugger break function. Call when debugging to have it read the _rtld_debug
89 * variable.
90 */
91extern void _rtld_debug_state (void);
92
93/**
94 * The type of constructor/destructor function.
95 */
96typedef void (*rtems_rtl_cdtor)(void);
97
98/**
99 * The global RTL data. This structure is allocated on the heap when the first
100 * call to the RTL is made and never released.
101 *
102 * The global symbol table is a hash table held in this structure and the
103 * actual symbols are part of the object's structure. If this is a problem we
104 * could look at a hash table per object file.
105 */
106struct rtems_rtl_data
107{
108  rtems_recursive_mutex lock;           /**< The RTL lock */
109  rtems_rtl_alloc_data  allocator;      /**< The allocator data. */
110  rtems_chain_control   objects;        /**< List if loaded object files. */
111  rtems_chain_control   pending;        /**< Listof object files needing work. */
112  const char*           paths;          /**< Search paths for archives. */
113  rtems_rtl_symbols     globals;        /**< Global symbol table. */
114  rtems_rtl_archives    archives;       /**< Archive search and loader. */
115  rtems_rtl_unresolved  unresolved;     /**< Unresolved symbols. */
116  rtems_rtl_obj*        base;           /**< Base object file. */
117  rtems_rtl_obj_cache   symbols;        /**< Symbols object file cache. */
118  rtems_rtl_obj_cache   strings;        /**< Strings object file cache. */
119  rtems_rtl_obj_cache   relocs;         /**< Relocations object file cache. */
120  rtems_rtl_obj_comp    decomp;         /**< The decompression compressor. */
121  int                   last_errno;     /**< Last error number. */
122  char                  last_error[64]; /**< Last error string. */
123};
124
125/**
126 * Get the RTL data with out locking. This call assumes the RTL is locked.
127 *
128 * @return rtems_rtl_data* The RTL data after being locked.
129 * @retval NULL The RTL data is not initialised.
130 */
131rtems_rtl_data* rtems_rtl_data_unprotected (void);
132
133/**
134 * Get the RTL global symbol table with out locking. This call assumes
135 * the RTL is locked.
136 *
137 * @return rtems_rtl_symbols* The RTL global symbols after being locked.
138 * @retval NULL The RTL data is not initialised.
139 */
140rtems_rtl_symbols* rtems_rtl_global_symbols (void);
141
142/**
143 * Get the RTL last error string with out locking. This call assumes the RTL is
144 * locked.
145 *
146 * @return const char* The RTL's laste error.
147 * @retval NULL The RTL data is not initialised.
148 */
149const char* rtems_rtl_last_error_unprotected (void);
150
151/**
152 * Get the RTL objects table with out locking. This call assumes the RTL
153 * is locked.
154 *
155 * @return rtems_chain_control* The RTL objects chain.
156 * @retval NULL The RTL data is not initialised.
157 */
158rtems_chain_control* rtems_rtl_objects_unprotected (void);
159
160/**
161 * Get the RTL pending with out locking. This call assumes the RTL is locked.
162 *
163 * @return rtems_chain_control* The RTL pending list control.
164 * @retval NULL The RTL data is not initialised.
165 */
166rtems_chain_control* rtems_rtl_pending_unprotected (void);
167
168/**
169 * Get the RTL unresolved table with out locking. This call assumes the RTL
170 * is locked.
171 *
172 * @return rtems_rtl_unresolv* The RTL unresolved symbols and reloc records.
173 * @retval NULL The RTL data is not initialised.
174 */
175rtems_rtl_unresolved* rtems_rtl_unresolved_unprotected (void);
176
177/**
178 * Get the RTL archives with out locking. This call assumes the RTL is locked.
179 *
180 * @return rtems_rtl_archives* The RTL acrhives.
181 * @retval NULL The RTL data is not initialised.
182 */
183rtems_rtl_archives* rtems_rtl_archives_unprotected (void);
184
185/**
186 * Get the RTL symbols, strings, or relocations object file caches. This call
187 * assmes the RTL is locked.
188 *
189 * @param symbols Pointer to the location to set the cache into. Returns NULL
190 *                is rtl is not initialised. If NULL is passed in no value set.
191 * @param strings Pointer to the location to set the cache into. Returns NULL
192 *                is rtl is not initialised. If NULL is passed in no value set.
193 * @param relocs Pointer to the location to set the cache into. Returns NULL
194 *               is rtl is not initialised. If NULL is passed in no value set.
195 */
196void rtems_rtl_obj_caches (rtems_rtl_obj_cache** symbols,
197                           rtems_rtl_obj_cache** strings,
198                           rtems_rtl_obj_cache** relocs);
199
200/**
201 * Flush all the object file caches.
202 */
203void rtems_rtl_obj_caches_flush (void);
204
205/**
206 * Get the RTL decompressor setting for the cache and the offset in the file
207 * the compressed stream starts. This call assumes the RTL is locked.
208 *
209 * @param decomp Pointer to the location to set the compressor into. Returns
210 *               NULL is rtl is not initialised.
211 * @param cache The cache to read the file with. Saves needing an extrs buffer.
212 * @param offset The offset in the file the compressed stream starts.
213 */
214void rtems_rtl_obj_decompress (rtems_rtl_obj_comp** decomp,
215                               rtems_rtl_obj_cache* cache,
216                               int                  fd,
217                               int                  compression,
218                               off_t                offset);
219
220/**
221 * Update the mask in the object files. You can clear flags and then set
222 * flags. A zero (0) does not clear or set the flags. This is global to all
223 * object files that are laoded.
224 *
225 * @param clear The flag's clear mask, a 0 does not clear any flags.
226 * @param set The flag's set mask, a 0 does not set any flags.
227 */
228void rtems_rtl_obj_update_flags (uint32_t clear, uint32_t set);
229
230/**
231 * Lock the Run-time Linker.
232 *
233 * @return rtems_rtl_data* The RTL data after being locked.
234 * @retval NULL The RTL data could not be initialised or locked. Typically this
235 *              means the lock could not be created.
236 */
237rtems_rtl_data* rtems_rtl_lock (void);
238
239/**
240 * Unlock the Run-time Linker.
241 */
242void rtems_rtl_unlock (void);
243
244/**
245 * Check a pointer is a valid object file descriptor returning the pointer as
246 * that type.
247 *
248 * Assumes the RTL has been locked.
249 *
250 * @param handle Pointer to the object file to be validated.
251 * @return rtl_obj* The object file descriptor. NULL is returned if invalid.
252 */
253rtems_rtl_obj* rtems_rtl_check_handle (void* handle);
254
255/**
256 * Find the object given a file name.
257 *
258 * @param name The name of the object file.
259 * @retval NULL No object file with that name found.
260 * @return rtems_rtl_obj* The object file descriptor.
261 */
262rtems_rtl_obj* rtems_rtl_find_obj (const char* name);
263
264/**
265 * Find the object file a symbol is exported from.
266 *
267 * @param sym The symbol to search with.
268 * @retval NULL No object file found.
269 * @return rtems_rtl_obj* Reference to the symbol.
270 */
271rtems_rtl_obj* rtems_rtl_find_obj_with_symbol (const rtems_rtl_obj_sym* sym);
272
273/**
274 * Load an object file into memory relocating it. It will not be resolved
275 * against other symbols in other object files or the base image.
276 *
277 * The name can be a file name for an object file or it can be encoded to
278 * reference an archive of object modules (static library). This encoding is
279 * specific to RTEMS and allows dependences to specify an archive without the
280 * searching overhead normally incurred by linkers locating object files in an
281 * archive. The file name format rules are:
282 *
283 *  1. Absolute file references a specific object file in the architecture
284 *     specific location on the file system.
285 *
286 *  2. Relative file references an object format file in the search path.
287 *
288 *  3. Absolute archive and file reference to a specific location in the file
289 *     system. The archive and file are encoded as 'archive:file [@@offset]'
290 *     where 'archive' is a valid file at the absolute path in the file system,
291 *     and 'file' is a contained in the archive, and optionally an offset to
292 *     the 'file' in the 'archive'. If no offset is provided the archive is
293 *     searched.
294 *
295 *  4. Relative archive and file in the search path. The encoding is the same
296 *     as described in item 3 of this list.
297 *
298 * Assumes the RTL has been locked.
299 *
300 * @param name The name of the object file.
301 * @param mode The mode of the load as defined by the dlopen call.
302 * @return rtl_obj* The object file descriptor. NULL is returned if the load fails.
303 */
304rtems_rtl_obj* rtems_rtl_load_object (const char* name, int mode);
305
306/**
307 * Unload an object file. This only happens when the user count is 0.
308 *
309 * Assumes the RTL has been locked.
310 *
311 * @param obj The object file descriptor.
312 * @retval true The object file has been unloaded.
313 * @retval false The object file could not be unloaded.
314 */
315bool rtems_rtl_unload_object (rtems_rtl_obj* obj);
316
317/**
318 * Load an object file.  This is the user accessable interface to unloading an
319 * object file. See @rtems_rtl_load_object.
320 *
321 * @param name The name of the object file.
322 * @param mode The mode of the load as defined by the dlopen call.
323 * @return rtl_obj* The object file descriptor. NULL is returned if the load fails.
324 */
325rtems_rtl_obj* rtems_rtl_load (const char* name, int mode);
326
327/**
328 * Unload an object file. This is the user accessable interface to unloading an
329 * object file. See @rtems_rtl_unload_object.
330 *
331 * Assumes the RTL has been locked.
332 *
333 * @param obj The object file descriptor.
334 * @retval true The object file has been unloaded.
335 * @retval false The object file could not be unloaded.
336 */
337bool rtems_rtl_unload (rtems_rtl_obj* obj);
338
339/**
340 * Get the last error message clearing it. This operation locks the run time
341 * linker and therefore keeps the RTL thread safe but this call is not thread
342 * safe is multiple threads are loading object files at the same time. This
343 * call is provided to map to the dlopen family of calls.
344 *
345 * @param message Pointer to a buffer to copy the message into.
346 * @param max_message The maximum message that can be copied.
347 * @return int The last error number.
348 */
349int rtems_rtl_get_error (char* message, size_t max_message);
350
351/**
352 * Append the path to the search path.
353 *
354 * @param path The path to append.
355 * @retval false The path could not be appended.
356 * @retval true The path was appended.
357 */
358bool rtems_rtl_path_append (const char* path);
359
360/**
361 * Prepend the path to the search path.
362 *
363 * @param path The path to prepend.
364 * @retval false The path could not be prepended.
365 * @retval true The path was prepended.
366 */
367
368bool rtems_rtl_path_prepend (const char* path);
369
370/**
371 * Add an exported symbol table to the global symbol table. This call is
372 * normally used by an object file when loaded that contains a global symbol
373 * table.
374 *
375 * @param esyms The exported symbol table.
376 * @param count The size of the exported symbol table.
377 */
378void rtems_rtl_base_sym_global_add (const unsigned char* esyms,
379                                    unsigned int         count);
380
381/**
382 * Return the object file descriptor for the base image. The object file
383 * descriptor returned is created when the run time linker is initialised.
384 *
385 * Assumes the RTL has been locked.
386 *
387 * @return rtl_obj* The object file descriptor for the base image. NULL is
388 *                  returned if the load fails.
389 */
390rtems_rtl_obj* rtems_rtl_baseimage (void);
391
392#ifdef __cplusplus
393}
394#endif /* __cplusplus */
395
396#endif
Note: See TracBrowser for help on using the repository browser.