source: rtems/cpukit/libdl/rtl-obj.h @ d4edbdbc

4.115
Last change on this file since d4edbdbc was d4edbdbc, checked in by Sebastian Huber <sebastian.huber@…>, on Mar 20, 2015 at 1:09:26 PM

Replace www.rtems.com with www.rtems.org

  • Property mode set to 100644
File size: 21.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 * @file
10 *
11 * @ingroup rtems_rtl
12 *
13 * @brief RTEMS Run-Time Linker Object Support.
14 */
15
16#if !defined (_RTEMS_RTL_OBJ_H_)
17#define _RTEMS_RTL_OBJ_H_
18
19#include <rtems.h>
20#include <rtems/chain.h>
21#include <rtems/rtl/rtl-sym.h>
22#include <rtems/rtl/rtl-unresolved.h>
23
24#ifdef __cplusplus
25extern "C" {
26#endif /* __cplusplus */
27
28/**
29 * Loader format flags.
30 */
31#define RTEMS_RTL_FMT_ELF     (1 << 0)
32#define RTEMS_RTL_FMT_COMP    (1 << 1)
33#define RTEMS_RTL_FMT_PRIVATE (1 << 16)
34
35/**
36 * Loader format definition.
37 */
38typedef struct rtems_rtl_loader_format_s
39{
40  /**
41   * The format label. This can be used to determine and manage
42   * specific formats.
43   */
44  const char* label;
45
46  /**
47   * The format flags.
48   */
49  uint32_t flags;
50} rtems_rtl_loader_format_t;
51
52/**
53 * The type of the format loader check handler. This handler checks the format
54 * and if it is detected as suitable it returns true.
55 */
56typedef bool (*rtems_rtl_loader_check) (rtems_rtl_obj_t* obj, int fd);
57
58/**
59 * The type of the format loader handler. This handler loads the specific
60 * format.
61 */
62typedef bool (*rtems_rtl_loader_load) (rtems_rtl_obj_t* obj, int fd);
63
64/**
65 * The type of the format loader handler. This handler loads the specific
66 * format.
67 */
68typedef rtems_rtl_loader_format_t* (*rtems_rtl_loader_sig) (void);
69
70/**
71 * Table for supported loadable formats.
72 */
73typedef struct rtems_rtl_loader_table_s
74{
75  rtems_rtl_loader_check check;     /**< The check handler. */
76  rtems_rtl_loader_load  load;      /**< The loader. */
77  rtems_rtl_loader_sig   signature; /**< The loader's signature. */
78} rtems_rtl_loader_table_t;
79
80/**
81 * Flags for the various section types.
82 */
83#define RTEMS_RTL_OBJ_SECT_TEXT  (1 << 0)  /**< Section holds program text. */
84#define RTEMS_RTL_OBJ_SECT_CONST (1 << 1)  /**< Section holds program text. */
85#define RTEMS_RTL_OBJ_SECT_DATA  (1 << 2)  /**< Section holds program data. */
86#define RTEMS_RTL_OBJ_SECT_BSS   (1 << 3)  /**< Section holds program bss. */
87#define RTEMS_RTL_OBJ_SECT_REL   (1 << 4)  /**< Section holds relocation records. */
88#define RTEMS_RTL_OBJ_SECT_RELA  (1 << 5)  /**< Section holds relocation addend
89                                            *   records. */
90#define RTEMS_RTL_OBJ_SECT_SYM   (1 << 6)  /**< Section holds symbols. */
91#define RTEMS_RTL_OBJ_SECT_STR   (1 << 7)  /**< Section holds strings. */
92#define RTEMS_RTL_OBJ_SECT_ALLOC (1 << 8)  /**< Section allocates runtime memory. */
93#define RTEMS_RTL_OBJ_SECT_LOAD  (1 << 9)  /**< Section is loaded from object file. */
94#define RTEMS_RTL_OBJ_SECT_WRITE (1 << 10) /**< Section is writable, ie data. */
95#define RTEMS_RTL_OBJ_SECT_EXEC  (1 << 11) /**< Section is executable. */
96#define RTEMS_RTL_OBJ_SECT_ZERO  (1 << 12) /**< Section is preset to zero. */
97#define RTEMS_RTL_OBJ_SECT_CTOR  (1 << 13) /**< Section contains constructors. */
98#define RTEMS_RTL_OBJ_SECT_DTOR  (1 << 14) /**< Section contains destructors. */
99
100/**
101 * An object file is made up of sections and the can be more than
102 * one of a specific type of sections. All sections and grouped
103 * together in memory.
104 */
105struct rtems_rtl_obj_sect_s
106{
107  rtems_chain_node node;        /**< The node's link in the chain. */
108  int              section;     /**< The section number. */
109  const char*      name;        /**< The section's name. */
110  size_t           size;        /**< The size of the section in memory. */
111  off_t            offset;      /**< Offset into the object file. Relative to
112                                 * the start of the object file. */
113  uint32_t         alignment;   /**< Alignment of this section. */
114  int              link;        /**< Section link field. */
115  int              info;        /**< Secfion info field. */
116  uint32_t         flags;       /**< The section's flags. */
117  void*            base;        /**< The base address of the section in
118                                 *   memory. */
119};
120
121/**
122 * Object file descriptor flags.
123 */
124#define RTEMS_RTL_OBJ_LOCKED     (1 << 0) /**< Lock the object file so it cannot
125                                           *   be unloaded. */
126#define RTEMS_RTL_OBJ_UNRESOLVED (1 << 1) /**< The object file has unresolved
127                                           *   external symbols. */
128
129/**
130 * RTL Object. There is one for each object module loaded plus one for the base
131 * kernel image.
132 */
133struct rtems_rtl_obj_s
134{
135  rtems_chain_node     link;         /**< The node's link in the chain. */
136  uint32_t             flags;        /**< The status of the object file. */
137  uint32_t             users;        /**< References to the object file. */
138  const char*          fname;        /**< The file name for the object. */
139  const char*          oname;        /**< The object file name. Can be
140                                      *   relative. */
141  const char*          aname;        /**< The archive name containing the
142                                      *   object. NULL means the object is not
143                                      *   in a lib */
144  off_t                ooffset;      /**< The object offset in the archive. */
145  size_t               fsize;        /**< Size of the object file. */
146  rtems_chain_control  sections;     /**< The sections of interest in the
147                                      *   object file. */
148  rtems_rtl_obj_sym_t* local_table;  /**< Local symbol table. */
149  size_t               local_syms;   /**< Local symbol count. */
150  size_t               local_size;   /**< Local symbol memory usage. */
151  rtems_rtl_obj_sym_t* global_table; /**< Global symbol table. */
152  size_t               global_syms;  /**< Global symbol count. */
153  size_t               global_size;  /**< Global symbol memory usage. */
154  uint32_t             unresolved;   /**< The number of unresolved relocations. */
155  void*                text_base;    /**< The base address of the text section
156                                      * in memory. */
157  void*                const_base;   /**< The base address of the const section
158                                      * in memory. */
159  void*                data_base;    /**< The base address of the data section
160                                      * in memory. */
161  void*                bss_base;     /**< The base address of the bss section
162                                      * in memory. */
163  size_t               bss_size;     /**< The size of the bss section. */
164  size_t               exec_size;    /**< The amount of executable memory
165                                      * allocated */
166  void*                entry;        /**< The entry point of the module. */
167  uint32_t             checksum;     /**< The checksum of the text sections. A
168                                      * zero means do not checksum. */
169  void*                detail;       /**< The file details. It contains the elf file
170                                      * detail, mainly including elf file name,
171                                      * section offset, section size, which
172                                      * elf this section belongs to.*/
173  uint32_t*            sec_num;      /**< The sec nums of each obj. */
174  uint32_t             obj_num;      /**< The count of elf files in an rtl obj. */
175  struct link_map*     linkmap;      /**< For GDB. */
176};
177
178/**
179 * A section handler is called once for each section that needs to be
180 * processed by this handler.
181 *
182 * @param obj The object file's descriptor the section belongs too.
183 * @param fd The file descriptor of the object file beling loaded.
184 * @param sect The section the handler is being invoked to handle.
185 * @param data A user supplied data variable.
186 * @retval true The operation was successful.
187 * @retval false The operation failed and the RTL has been set.
188 */
189typedef bool (*rtems_rtl_obj_sect_handler_t)(rtems_rtl_obj_t*      obj,
190                                             int                   fd,
191                                             rtems_rtl_obj_sect_t* sect,
192                                             void*                 data);
193
194/**
195 * Get the file name.
196 *
197 * @param obj The object file.
198 * @return const char* The string.
199 */
200static inline const char* rtems_rtl_obj_fname (const rtems_rtl_obj_t* obj)
201{
202  return obj->fname;
203}
204
205/**
206 * Is the file name valid ?
207 *
208 * @param obj The object file.
209 * @return bool There is a file name
210 */
211static inline bool rtems_rtl_obj_fname_valid (const rtems_rtl_obj_t* obj)
212{
213  return obj->fname;
214}
215
216/**
217 * Get the object name.
218 *
219 * @param obj The object file.
220 * @return const char* The string.
221 */
222static inline const char* rtems_rtl_obj_oname (const rtems_rtl_obj_t* obj)
223{
224  return obj->oname;
225}
226
227/**
228 * Is the object name valid ?
229 *
230 * @param obj The object file.
231 * @return bool There is an object name
232 */
233static inline bool rtems_rtl_obj_oname_valid (const rtems_rtl_obj_t* obj)
234{
235  return obj->oname;
236}
237
238/**
239 * Get the archive name.
240 *
241 * @param obj The object file.
242 * @return const char* The string.
243 */
244static inline const char* rtems_rtl_obj_aname (const rtems_rtl_obj_t* obj)
245{
246  return obj->aname;
247}
248
249/**
250 * Is the archive name valid ?
251 *
252 * @param obj The object file.
253 * @return bool There is an archive name
254 */
255static inline bool rtems_rtl_obj_aname_valid (const rtems_rtl_obj_t* obj)
256{
257  return obj->aname;
258}
259
260/**
261 * Allocate an object structure on the heap.
262 *
263 * @retval NULL No memory for the object.
264 */
265rtems_rtl_obj_t* rtems_rtl_obj_alloc (void);
266
267/**
268 * Free the object structure and related resources.
269 *
270 * @param obj The object file's descriptor to free.
271 * @retval false The object has dependences.
272 * @retval true The object has been freed.
273 */
274bool rtems_rtl_obj_free (rtems_rtl_obj_t* obj);
275
276/**
277 * Does the object file have unresolved external references ? If it does the
278 * results of executing code is unpredictable.
279 *
280 * @param obj The object file's descriptor.
281 * @retval true The object file has unresolved externals.
282 * @retval false The object file has all external references resolved.
283 */
284bool rtems_rtl_obj_unresolved (rtems_rtl_obj_t* obj);
285
286/**
287 * Parses a filename and returns newly allocated strings with the archive name,
288 * object name, and the object's offset
289 *
290 * @param name The filename of the object
291 * @param aname Address of a string pointer that holds the archive name
292 * @param oname Address of a string pointer that holds the object name
293 * @param ooffset Address of an int that holds the object offset
294 * @retval true The parsing was successful
295 * @retval false The parsing was unsuccessful
296 */
297bool rtems_rtl_parse_name (const char*  name,
298                           const char** aname,
299                           const char** oname,
300                           off_t*       ooffset);
301
302/**
303 * Load the object file.
304 *
305 * @param obj The object file's descriptor.
306 * @param fd The file descriptor.
307 * @param load_syms Load symbols.
308 * @param load_dep Load dependent object files.
309 * @retval true The load was successful.
310 * @retval false The load failed. The RTL error has been set.
311 */
312bool rtems_rtl_obj_file_load (rtems_rtl_obj_t* obj, int fd);
313
314/**
315 * Check of the name matches the object file's object name.
316 *
317 * @param obj The object file's descriptor.
318 * @param name The name to match.
319 */
320bool rtems_rtl_match_name (rtems_rtl_obj_t* obj, const char* name);
321
322/**
323 * Find an object file on disk that matches the name. The object descriptor is
324 * fill in with the various parts of a name. A name can have archive, object
325 * file and offset components. The search path in the RTL is searched.
326 *
327 * @param obj The object file's descriptor.
328 * @param name The name to locate on disk.
329 * @retval true The file has been found.
330 * @retval false The file could not be located. The RTL error has been set.
331 */
332bool rtems_rtl_obj_find_file (rtems_rtl_obj_t* obj, const char* name);
333
334/**
335 * Add a section to the object descriptor.
336 *
337 * @param obj The object file's descriptor.
338 * @param section The section's index number.
339 * @param name The name of the section.
340 * @param size The size of the section in memory.
341 * @param offset The offset of the section in the object file.
342 * @param alignment The alignment of the section in memory.
343 * @param link The section's link field (from the ELF format).
344 * @param info The section's info field (from the ELF format).
345 * @param flags The section's flags.
346 * @retval true The section has been added.
347 * @retval false The section has not been added. See the RTL error.
348 */
349bool rtems_rtl_obj_add_section (rtems_rtl_obj_t* obj,
350                                int              section,
351                                const char*      name,
352                                size_t           size,
353                                off_t            offset,
354                                uint32_t         alignment,
355                                int              link,
356                                int              info,
357                                uint32_t         flags);
358
359/**
360 * Erase the object file descriptor's sections.
361 *
362 * @param obj The object file's descriptor.
363 */
364void rtems_rtl_obj_erase_sections (rtems_rtl_obj_t* obj);
365
366/**
367 * Find the section given a name.
368 *
369 * @param obj The object file's descriptor.
370 * @param name The name of the section to find.
371 * @retval NULL The section was not found.
372 * @return rtems_rtl_obj_sect_t* The named section.
373 */
374rtems_rtl_obj_sect_t* rtems_rtl_obj_find_section (rtems_rtl_obj_t* obj,
375                                                  const char*      name);
376
377/**
378 * Find a section given a section's index number.
379 *
380 * @param obj The object file's descriptor.
381 * @param index The section's index to find.
382 * @retval NULL The section was not found.
383 * @return rtems_rtl_obj_sect_t* The found section.
384 */
385rtems_rtl_obj_sect_t* rtems_rtl_obj_find_section_by_index (rtems_rtl_obj_t* obj,
386                                                           int              index);
387
388/**
389 * The text size of the object file. Only use once all the sections has been
390 * added. It includes alignments between sections that are part of the object's
391 * text area. The consts sections are included in this section.
392 *
393 * @param obj The object file's descriptor.
394 * @return size_t The size of the text area of the object file.
395 */
396size_t rtems_rtl_obj_text_size (rtems_rtl_obj_t* obj);
397
398/**
399 * The text section alignment of the object file. Only use once all the
400 * sections has been added. The section alignment is the alignment of the first
401 * text type section loaded the text section.
402 *
403 * You can assume the alignment is a positive integral power of 2 if not 0 or
404 * 1. If 0 or 1 then there is no alignment.
405 *
406 * @param obj The object file's descriptor.
407 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
408 */
409uint32_t rtems_rtl_obj_text_alignment (rtems_rtl_obj_t* obj);
410
411/**
412 * The const size of the object file. Only use once all the sections has been
413 * added. It includes alignments between sections that are part of the object's
414 * const area. The consts sections are included in this section.
415 *
416 * @param obj The object file's descriptor.
417 * @return size_t The size of the const area of the object file.
418 */
419size_t rtems_rtl_obj_const_size (rtems_rtl_obj_t* obj);
420
421/**
422 * The const section alignment of the object file. Only use once all the
423 * sections has been added. The section alignment is the alignment of the first
424 * const type section loaded the const section.
425 *
426 * You can assume the alignment is a positive integral power of 2 if not 0 or
427 * 1. If 0 or 1 then there is no alignment.
428 *
429 * @param obj The object file's descriptor.
430 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
431 */
432uint32_t rtems_rtl_obj_const_alignment (rtems_rtl_obj_t* obj);
433
434/**
435 * The data size of the object file. Only use once all the sections has been
436 * added. It includes alignments between sections that are part of the object's
437 * data area.
438 *
439 * @param obj The object file's descriptor.
440 * @return size_t The size of the data area of the object file.
441 */
442size_t rtems_rtl_obj_data_size (rtems_rtl_obj_t* obj);
443
444/**
445 * The data section alignment of the object file. Only use once all the
446 * sections has been added. The section alignment is the alignment of the first
447 * data type section loaded the data section.
448 *
449 * You can assume the alignment is a positive integral power of 2 if not 0 or
450 * 1. If 0 or 1 then there is no alignment.
451 *
452 * @param obj The object file's descriptor.
453 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
454 */
455uint32_t rtems_rtl_obj_data_alignment (rtems_rtl_obj_t* obj);
456
457/**
458 * The bss size of the object file. Only use once all the sections has been
459 * added. It includes alignments between sections that are part of the object's
460 * bss area.
461 *
462 * @param obj The object file's descriptor.
463 * @return size_t The size of the bss area of the object file.
464 */
465size_t rtems_rtl_obj_bss_size (rtems_rtl_obj_t* obj);
466
467/**
468 * The bss section alignment of the object file. Only use once all the
469 * sections has been added. The section alignment is the alignment of the first
470 * bss type section loaded the bss section.
471 *
472 * You can assume the alignment is a positive integral power of 2 if not 0 or
473 * 1. If 0 or 1 then there is no alignment.
474 *
475 * @param obj The object file's descriptor.
476 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
477 */
478uint32_t rtems_rtl_obj_bss_alignment (rtems_rtl_obj_t* obj);
479
480/**
481 * Relocate the object file. The object file's section are parsed for any
482 * relocation type sections.
483 *
484 * @param obj The object file's descriptor.
485 * @param fd The object file's file descriptor.
486 * @param handler The object file's format specific relocation handler.
487 * @param data User specific data handle.
488 * @retval true The object file was relocated.
489 * @retval false The relocation failed. The RTL error is set.
490 */
491bool rtems_rtl_obj_relocate (rtems_rtl_obj_t*             obj,
492                             int                          fd,
493                             rtems_rtl_obj_sect_handler_t handler,
494                             void*                        data);
495
496/**
497 * Relocate an object file's unresolved reference.
498 *
499 * @param rec The unresolved relocation record.
500 * @param sym The unresolved relocation's referenced symbol.
501 * @retval true The object file record was relocated.
502 * @retval false The relocation failed. The RTL error is set.
503 */
504bool rtems_rtl_obj_relocate_unresolved (rtems_rtl_unresolv_reloc_t* reloc,
505                                        rtems_rtl_obj_sym_t*        sym);
506
507/**
508 * Load the symbols from the object file. Only the exported or public symbols
509 * are read into memory and held in the global symbol table.
510 *
511 * @param obj The object file's descriptor.
512 * @param fd The object file's file descriptor.
513 * @param handler The object file's format specific symbol handler.
514 * @param data User specific data handle.
515 * @retval true The object file's symbol where loaded.
516 * @retval false The symbol loading failed. The RTL error is set.
517 */
518bool rtems_rtl_obj_load_symbols (rtems_rtl_obj_t*             obj,
519                                 int                          fd,
520                                 rtems_rtl_obj_sect_handler_t handler,
521                                 void*                        data);
522
523/**
524 * Load the sections that have been allocated memory in the target. The bss
525 * type section does not load any data, it is set to 0. The text and data
526 * sections read the detault data from the object file into the target memory.
527 *
528 * @param obj The object file's descriptor.
529 * @param fd The object file's file descriptor.
530 * @param handler The object file's format specific load handler.
531 * @param data User specific data handle.
532 * @retval true The object has been sucessfully loaded.
533 * @retval false The load failed. The RTL error has been set.
534 */
535bool rtems_rtl_obj_load_sections (rtems_rtl_obj_t*             obj,
536                                  int                          fd,
537                                  rtems_rtl_obj_sect_handler_t handler,
538                                  void*                        data);
539
540/**
541 * Invoke the constructors the object has. Constructors are a table of pointers
542 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
543 * taken from the section's size. The objet ELF specific code is responisble
544 * for flagging which sections contain constructors.
545 *
546 * @param obj The object file's descriptor.
547 */
548void rtems_rtl_obj_run_ctors (rtems_rtl_obj_t* obj);
549
550/**
551 * Invoke the destructors the object has. Destructors are a table of pointers
552 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
553 * taken from the section's size. The objet ELF specific code is responisble
554 * for flagging which sections contain destructors.
555 *
556 * @param obj The object file's descriptor.
557 */
558void rtems_rtl_obj_run_dtors (rtems_rtl_obj_t* obj);
559
560/**
561 * Load the object file, reading all sections into memory, symbols and
562 * performing any relocation fixups.
563 *
564 * @param obj The object file's descriptor.
565 * @retval true The object file has been loaded.
566 * @retval false The load failed. The RTL error has been set.
567 */
568bool rtems_rtl_obj_load (rtems_rtl_obj_t* obj);
569
570/**
571 * Unload the object file, erasing all symbols and releasing all memory.
572 *
573 * @param obj The object file's descriptor.
574 * @retval true The object file has been unloaded.
575 * @retval false The unload failed. The RTL error has been set.
576 */
577bool rtems_rtl_obj_unload (rtems_rtl_obj_t* obj);
578
579#ifdef __cplusplus
580}
581#endif /* __cplusplus */
582
583#endif
Note: See TracBrowser for help on using the repository browser.