source: rtems/cpukit/include/rtems/rtl/rtl.h @ 2afb22b

5
Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on 12/23/17 at 07:18:56

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 10.4 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.h>
24#include <rtems/chain.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_id               lock;           /**< The RTL lock id */
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 *
187 * @return True The RTL is unlocked.
188 * @return False The RTL could not be unlocked. Not much you can do.
189 */
190bool rtems_rtl_unlock (void);
191
192/**
193 * Check a pointer is a valid object file descriptor returning the pointer as
194 * that type.
195 *
196 * Assumes the RTL has been locked.
197 *
198 * @param handle Pointer to the object file to be validated.
199 * @return rtl_obj* The object file descriptor. NULL is returned if invalid.
200 */
201rtems_rtl_obj_t* rtems_rtl_check_handle (void* handle);
202
203/**
204 * Find the object given a file name.
205 *
206 * @param name The name of the object file.
207 * @retval NULL No object file with that name found.
208 * @return rtems_rtl_obj_t* The object file descriptor.
209 */
210rtems_rtl_obj_t* rtems_rtl_find_obj (const char* name);
211
212/**
213 * Load an object file into memory relocating it. It will not be resolved
214 * against other symbols in other object files or the base image.
215 *
216 * The name can be a file name for an object file or it can be encoded to
217 * reference an archive of object modules (static library). This encoding is
218 * specific to RTEMS and allows dependences to specify an archive without the
219 * searching overhead normally incurred by linkers locating object files in an
220 * archive. The file name format rules are:
221 *
222 *  1. Absolute file references a specific object file in the architecture
223 *     specific location on the file system.
224 *
225 *  2. Relative file references an object format file in the search path.
226 *
227 *  3. Absolute archive and file reference to a specific location in the file
228 *     system. The archive and file are encoded as 'archive:file [@@offset]'
229 *     where 'archive' is a valid file at the absolute path in the file system,
230 *     and 'file' is a contained in the archive, and optionally an offset to
231 *     the 'file' in the 'archive'. If no offset is provided the archive is
232 *     searched.
233 *
234 *  4. Relative archive and file in the search path. The encoding is the same
235 *     as described in item 3 of this list.
236 *
237 * Assumes the RTL has been locked.
238 *
239 * @param name The name of the object file.
240 * @param mode The mode of the load as defined by the dlopen call.
241 * @return rtl_obj* The object file descriptor. NULL is returned if the load fails.
242 */
243rtems_rtl_obj_t* rtems_rtl_load_object (const char* name, int mode);
244
245/**
246 * Unload an object file. This only happens when the user count is 0.
247 *
248 * Assumes the RTL has been locked.
249 *
250 * @param obj The object file descriptor.
251 * @retval true The object file has been unloaded.
252 * @retval false The object file could not be unloaded.
253 */
254bool rtems_rtl_unload_object (rtems_rtl_obj_t* obj);
255
256/**
257 * Run any constructor functions the object file may contain. This call
258 * assumes the linker is unlocked.
259 *
260 * @param obj The object file.
261 */
262void rtems_rtl_run_ctors (rtems_rtl_obj_t* obj);
263
264/**
265 * Get the last error message clearing it. This operation locks the run time
266 * linker and therefore keeps the RTL thread safe but this call is not thread
267 * safe is multiple threads are loading object files at the same time. This
268 * call is provided to map to the dlopen family of calls.
269 *
270 * @param message Pointer to a buffer to copy the message into.
271 * @param max_message The maximum message that can be copied.
272 * @return int The last error number.
273 */
274int rtems_rtl_get_error (char* message, size_t max_message);
275
276/**
277 * Append the path to the search path.
278 *
279 * @param path The path to append.
280 * @retval false The path could not be appended.
281 * @retval true The path was appended.
282 */
283bool rtems_rtl_path_append (const char* path);
284
285/**
286 * Prepend the path to the search path.
287 *
288 * @param path The path to prepend.
289 * @retval false The path could not be prepended.
290 * @retval true The path was prepended.
291 */
292
293bool rtems_rtl_path_prepend (const char* path);
294
295/**
296 * Add an exported symbol table to the global symbol table. This call is
297 * normally used by an object file when loaded that contains a global symbol
298 * table.
299 *
300 * @param esyms The exported symbol table.
301 * @param count The size of the exported symbol table.
302 */
303void rtems_rtl_base_sym_global_add (const unsigned char* esyms,
304                                    unsigned int         count);
305
306/**
307 * Return the object file descriptor for the base image. The object file
308 * descriptor returned is created when the run time linker is initialised.
309 *
310 * Assumes the RTL has been locked.
311 *
312 * @return rtl_obj* The object file descriptor for the base image. NULL is
313 *                  returned if the load fails.
314 */
315rtems_rtl_obj_t* rtems_rtl_baseimage (void);
316
317#ifdef __cplusplus
318}
319#endif /* __cplusplus */
320
321#endif
Note: See TracBrowser for help on using the repository browser.