source: rtems/cpukit/include/rtems/rtl/rtl-obj.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: 32.4 KB
Line 
1/*
2 *  COPYRIGHT (c) 2012,2019 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
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;
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* obj, int fd);
57
58/**
59 * The type of the format loader load handler. This handler loads the specific
60 * format.
61 */
62typedef bool (*rtems_rtl_loader_load) (rtems_rtl_obj* obj, int fd);
63
64/**
65 * The type of the format loader unload handler. This handler unloads the
66 * specific format.
67 */
68typedef bool (*rtems_rtl_loader_unload) (rtems_rtl_obj* obj);
69
70/**
71 * The type of the format loader signature handler. This handler checks the
72 * format signature.
73 */
74typedef rtems_rtl_loader_format* (*rtems_rtl_loader_sig) (void);
75
76/**
77 * Table for supported loadable formats.
78 */
79typedef struct rtems_rtl_loader_table
80{
81  rtems_rtl_loader_check  check;     /**< The check handler. */
82  rtems_rtl_loader_load   load;      /**< The loader. */
83  rtems_rtl_loader_unload unload;    /**< The unloader. */
84  rtems_rtl_loader_sig    signature; /**< The loader's signature. */
85} rtems_rtl_loader_table;
86
87/**
88 * Flags for the various section types.
89 */
90#define RTEMS_RTL_OBJ_SECT_TEXT       (1 << 0)  /**< Section holds program text. */
91#define RTEMS_RTL_OBJ_SECT_CONST      (1 << 1)  /**< Section holds program text. */
92#define RTEMS_RTL_OBJ_SECT_DATA       (1 << 2)  /**< Section holds program data. */
93#define RTEMS_RTL_OBJ_SECT_BSS        (1 << 3)  /**< Section holds program bss. */
94#define RTEMS_RTL_OBJ_SECT_EH         (1 << 4)  /**< Section holds exception data. */
95#define RTEMS_RTL_OBJ_SECT_TLS        (1 << 5)  /**< Section holds TLS data. */
96#define RTEMS_RTL_OBJ_SECT_REL        (1 << 6)  /**< Section holds relocation recs. */
97#define RTEMS_RTL_OBJ_SECT_RELA       (1 << 7)  /**< Section holds reloc addend recs. */
98#define RTEMS_RTL_OBJ_SECT_SYM        (1 << 8)  /**< Section holds symbols. */
99#define RTEMS_RTL_OBJ_SECT_STR        (1 << 9)  /**< Section holds strings. */
100#define RTEMS_RTL_OBJ_SECT_ALLOC      (1 << 10  /**< Section allocates runtime memory. */
101#define RTEMS_RTL_OBJ_SECT_LOAD       (1 << 11) /**< Section is loaded from object file. */
102#define RTEMS_RTL_OBJ_SECT_WRITE      (1 << 12) /**< Section is writable, ie data. */
103#define RTEMS_RTL_OBJ_SECT_EXEC       (1 << 13) /**< Section is executable. */
104#define RTEMS_RTL_OBJ_SECT_ZERO       (1 << 14) /**< Section is preset to zero. */
105#define RTEMS_RTL_OBJ_SECT_LINK       (1 << 15) /**< Section is link-ordered. */
106#define RTEMS_RTL_OBJ_SECT_CTOR       (1 << 16) /**< Section contains constructors. */
107#define RTEMS_RTL_OBJ_SECT_DTOR       (1 << 17) /**< Section contains destructors. */
108#define RTEMS_RTL_OBJ_SECT_LOCD       (1 << 18) /**< Section has been located. */
109#define RTEMS_RTL_OBJ_SECT_ARCH_ALLOC (1 << 19) /**< Section use arch allocator. */
110
111/**
112 * Section types mask.
113 */
114#define RTEMS_RTL_OBJ_SECT_TYPES (RTEMS_RTL_OBJ_SECT_TEXT | \
115                                  RTEMS_RTL_OBJ_SECT_CONST | \
116                                  RTEMS_RTL_OBJ_SECT_DATA | \
117                                  RTEMS_RTL_OBJ_SECT_BSS | \
118                                  RTEMS_RTL_OBJ_SECT_TLS | \
119                                  RTEMS_RTL_OBJ_SECT_EH)
120
121/**
122 * An object file is made up of sections and the can be more than
123 * one of a specific type of sections. All sections and grouped
124 * together in memory.
125 */
126struct rtems_rtl_obj_sect
127{
128  rtems_chain_node node;        /**< The node's link in the chain. */
129  int              section;     /**< The section number. */
130  const char*      name;        /**< The section's name. */
131  size_t           size;        /**< The size of the section in memory. */
132  off_t            offset;      /**< Offset into the object file. Relative to
133                                 *   the start of the object file. */
134  uint32_t         alignment;   /**< Alignment of this section. */
135  int              link;        /**< Section link field. */
136  int              info;        /**< Secfion info field. */
137  uint32_t         flags;       /**< The section's flags. */
138  void*            base;        /**< The base address of the section in
139                                 *   memory. */
140  int              load_order;  /**< Order we load sections. */
141};
142
143/**
144 * Object file dependents. This is a list of tables of pointers to the object
145 * modules the object file depends on. The table is a list of tables because
146 * unresolved externals can exist when an object file is loaded and resolved
147 * later when the dependent object file is loaded.
148 */
149struct rtems_rtl_obj_depends
150{
151  rtems_chain_node node;        /**< The node's link in the chain. */
152  size_t           dependents;  /**< The number of dependent object pointers. */
153  rtems_rtl_obj*   depends[];   /**< Dependtent objects. More follow. */
154};
155
156/**
157 * Dependency iterator.
158 */
159typedef bool (*rtems_rtl_obj_depends_iterator) (rtems_rtl_obj* obj,
160                                                rtems_rtl_obj* dependent,
161                                                void*          data);
162
163/**
164 * Object file descriptor flags.
165 */
166#define RTEMS_RTL_OBJ_LOCKED       (1 << 0) /**< Lock the object file so it cannot
167                                             *   be unloaded. */
168#define RTEMS_RTL_OBJ_UNRESOLVED   (1 << 1) /**< The object file has unresolved
169                                             *   external symbols. */
170#define RTEMS_RTL_OBJ_BASE         (1 << 2) /**< The base image. */
171#define RTEMS_RTL_OBJ_RELOC_TAG    (1 << 3) /**< Tag the object as visited when reloc
172                                             *   parsing. */
173#define RTEMS_RTL_OBJ_DEP_VISITED  (1 << 4) /**< Dependency loop detection. */
174#define RTEMS_RTL_OBJ_CTOR_RUN     (1 << 5) /**< Constructors have been called. */
175
176/**
177 * RTL Object. There is one for each object module loaded plus one for the base
178 * kernel image.
179 */
180struct rtems_rtl_obj
181{
182  rtems_chain_node    link;         /**< The node's link in the chain. */
183  uint32_t            flags;        /**< The status of the object file. */
184  size_t              users;        /**< Users of this object file, number of loads. */
185  size_t              refs;         /**< References to the object file. */
186  int                 format;       /**< The format of the object file. */
187  const char*         fname;        /**< The file name for the object. */
188  const char*         oname;        /**< The object file name. Can be
189                                     *   relative. */
190  const char*         aname;        /**< The archive name containing the
191                                     *   object. NULL means the object is not
192                                     *   in a lib */
193  off_t               ooffset;      /**< The object offset in the archive. */
194  size_t              fsize;        /**< Size of the object file. */
195  rtems_chain_control sections;     /**< The sections of interest in the object
196                                     *   file. */
197  rtems_chain_control dependents;   /**< The dependent object files. */
198  rtems_rtl_obj_sym*  local_table;  /**< Local symbol table. */
199  size_t              local_syms;   /**< Local symbol count. */
200  size_t              local_size;   /**< Local symbol memory usage. */
201  rtems_rtl_obj_sym*  global_table; /**< Global symbol table. */
202  size_t              global_syms;  /**< Global symbol count. */
203  size_t              global_size;  /**< Global symbol memory usage. */
204  size_t              unresolved;   /**< The number of unresolved relocations. */
205  void*               text_base;    /**< The base address of the text section
206                                     *   in memory. */
207  size_t              text_size;    /**< The size of the text section. */
208  void*               const_base;   /**< The base address of the const section
209                                     *   in memory. */
210  size_t              const_size;   /**< The size of the const section. */
211  void*               eh_base;      /**< The base address of the eh section in
212                                     *   memory. */
213  size_t              eh_size;      /**< The size of the eh section. */
214  void*               data_base;    /**< The base address of the data section
215                                     *   in memory. */
216  size_t              data_size;    /**< The size of the data section. */
217  void*               bss_base;     /**< The base address of the bss section in
218                                     *   memory. */
219  size_t              bss_size;     /**< The size of the bss section. */
220  size_t              exec_size;    /**< The amount of executable memory
221                                     *   allocated */
222  void*               entry;        /**< The entry point of the module. */
223  uint32_t            checksum;     /**< The checksum of the text sections. A
224                                     *   zero means do not checksum. */
225  uint32_t*           sec_num;      /**< The sec nums of each obj. */
226  uint32_t            obj_num;      /**< The count of elf files in an rtl
227                                     *   obj. */
228  void*               trampoline;   /**< Trampoline memory. Used for fixups or
229                                     *   veneers */
230  size_t              tramp_size;   /**< Size of a tramopline slot. */
231  size_t              tramps_size;  /**< Size of the trampoline memory. */
232  void*               tramp_brk;    /**< Trampoline memory allocator. MD
233                                     *   relocators can take memory from the
234                                     *   break upto the size. */
235  size_t              tramp_relocs; /**< Number of slots reserved for
236                                     *   relocs. The remainder are for
237                                     *   unresolved symbols. */
238  struct link_map*    linkmap;      /**< For GDB. */
239  void*               loader;       /**< The file details specific to a
240                                     *   loader. */
241};
242
243/**
244 * A section handler is called once for each section that needs to be
245 * processed by this handler. The handler is specific to a task.
246 *
247 * @param obj The object file's descriptor the section belongs too.
248 * @param fd The file descriptor of the object file beling loaded.
249 * @param sect The section the handler is being invoked to handle.
250 * @param data A user supplied data variable.
251 * @retval true The operation was successful.
252 * @retval false The operation failed and the RTL has been set.
253 */
254typedef bool (*rtems_rtl_obj_sect_handler)(rtems_rtl_obj*      obj,
255                                           int                 fd,
256                                           rtems_rtl_obj_sect* sect,
257                                           void*               data);
258
259/**
260 * Get the file name.
261 *
262 * @param obj The object file.
263 * @return const char* The string.
264 */
265static inline const char* rtems_rtl_obj_fname (const rtems_rtl_obj* obj)
266{
267  return obj->fname;
268}
269
270/**
271 * Is the file name valid ?
272 *
273 * @param obj The object file.
274 * @return bool There is a file name
275 */
276static inline bool rtems_rtl_obj_fname_valid (const rtems_rtl_obj* obj)
277{
278  return obj->fname;
279}
280
281/**
282 * Get the object name.
283 *
284 * @param obj The object file.
285 * @return const char* The string.
286 */
287static inline const char* rtems_rtl_obj_oname (const rtems_rtl_obj* obj)
288{
289  return obj->oname;
290}
291
292/**
293 * Is the object name valid ?
294 *
295 * @param obj The object file.
296 * @return bool There is an object name
297 */
298static inline bool rtems_rtl_obj_oname_valid (const rtems_rtl_obj* obj)
299{
300  return obj->oname;
301}
302
303/**
304 * Get the archive name.
305 *
306 * @param obj The object file.
307 * @return const char* The string.
308 */
309static inline const char* rtems_rtl_obj_aname (const rtems_rtl_obj* obj)
310{
311  return obj->aname;
312}
313
314/**
315 * Is the archive name valid ?
316 *
317 * @param obj The object file.
318 * @return bool There is an archive name
319 */
320static inline bool rtems_rtl_obj_aname_valid (const rtems_rtl_obj* obj)
321{
322  return obj->aname;
323}
324
325/**
326 * Is the address inside the text section?
327 *
328 * @param obj The object file.
329 * @return bool There is an archive name
330 */
331static inline bool rtems_rtl_obj_text_inside (const rtems_rtl_obj* obj,
332                                              const void*          address)
333{
334  return
335    (address >= obj->text_base) &&
336    (address < (obj->text_base + obj->text_size));
337}
338
339/**
340 * Align the size to the next alignment point. Assume the alignment is a
341 * positive integral power of 2 if not 0 or 1. If 0 or 1 then there is no
342 * alignment.
343 *
344 * @param offset Offset to align up from.
345 * @param alignment The alignment.
346 * @return size_t Aligned offset.
347 */
348static inline size_t rtems_rtl_obj_align (size_t   offset,
349                                          uint32_t alignment)
350{
351  if ((alignment > 1) && ((offset & (alignment - 1)) != 0))
352    offset = (offset + alignment) & ~(alignment - 1);
353  return offset;
354}
355
356/**
357 * Is the symbol in this object's files globa symbol table?
358 *
359 * @param obj The object file's descriptor to search.
360 * @param sym The symbol to check.
361 * @retval bool Returns @true if present else @false is returned.
362 */
363static inline bool rtems_rtl_obj_has_symbol (const rtems_rtl_obj*     obj,
364                                             const rtems_rtl_obj_sym* sym)
365{
366  return (sym >= obj->global_table &&
367          sym < (obj->global_table + obj->global_syms));
368}
369
370/**
371 * Is there space in the trampoline memory for a trapoline.
372 *
373 * @param obj The object file's descriptor to check for available space.
374 * @param size The size to be allocated.
375 * @retval bool Returns @true if the space is available.
376 */
377static inline bool rtems_rtl_obj_has_tramp_space (const rtems_rtl_obj* obj,
378                                                  const size_t         size)
379{
380  return (obj->trampoline != NULL &&
381          ((obj->tramp_brk - obj->trampoline) + size) <= obj->tramps_size);
382}
383
384/**
385 * Trampoline slots.
386 *
387 * @param obj The object file's descriptor.
388 * @retval size_t The number of trampoline slots.
389 */
390static inline size_t rtems_rtl_obj_trampoline_slots (const rtems_rtl_obj* obj)
391{
392  return obj->trampoline == NULL || obj->tramp_size == 0 ?
393    0 : obj->tramps_size / obj->tramp_size;
394}
395
396/**
397 * Number of trampolines.
398 *
399 * @param obj The object file's descriptor.
400 * @retval size_t The number of trampolines.
401 */
402static inline size_t rtems_rtl_obj_trampolines (const rtems_rtl_obj* obj)
403{
404  return obj->trampoline == NULL || obj->tramp_size == 0 ?
405    0 : (obj->tramp_brk - obj->trampoline) / obj->tramp_size;
406}
407
408/**
409 * Does the section require architecture specific allocations?
410 *
411 * @param sect The section.
412 * @retval bool Returns @true if the section requires arch allocation.
413 */
414static inline bool rtems_rtl_obj_sect_is_arch_alloc (rtems_rtl_obj_sect* sect)
415{
416  return (sect->flags & RTEMS_RTL_OBJ_SECT_ARCH_ALLOC) != 0;
417}
418
419/**
420 * Allocate an object structure on the heap.
421 *
422 * @retval NULL No memory for the object.
423 */
424rtems_rtl_obj* rtems_rtl_obj_alloc (void);
425
426/**
427 * Free the object structure and related resources.
428 *
429 * @param obj The object file's descriptor to free.
430 * @retval false The object has dependences.
431 * @retval true The object has been freed.
432 */
433bool rtems_rtl_obj_free (rtems_rtl_obj* obj);
434
435/**
436 * Does the object file have unresolved external references ? If it does the
437 * results of executing code is unpredictable.
438 *
439 * @param obj The object file's descriptor.
440 * @retval true The object file has unresolved externals.
441 * @retval false The object file has all external references resolved.
442 */
443bool rtems_rtl_obj_unresolved (rtems_rtl_obj* obj);
444
445/**
446 * Parses a filename and returns newly allocated strings with the archive name,
447 * object name, and the object's offset
448 *
449 * @param name The filename of the object
450 * @param aname Address of a string pointer that holds the archive name
451 * @param oname Address of a string pointer that holds the object name
452 * @param ooffset Address of an int that holds the object offset
453 * @retval true The parsing was successful
454 * @retval false The parsing was unsuccessful
455 */
456bool rtems_rtl_parse_name (const char*  name,
457                           const char** aname,
458                           const char** oname,
459                           off_t*       ooffset);
460
461/**
462 * Find an object file on disk that matches the name. The object descriptor is
463 * fill in with the various parts of a name. A name can have archive, object
464 * file and offset components. The search path in the RTL is searched.
465 *
466 * @param obj The object file's descriptor.
467 * @param name The name to locate on disk.
468 * @retval true The file has been found.
469 * @retval false The file could not be located. The RTL error has been set.
470 */
471bool rtems_rtl_obj_find_file (rtems_rtl_obj* obj, const char* name);
472
473/**
474 * Add a section to the object descriptor.
475 *
476 * @param obj The object file's descriptor.
477 * @param section The section's index number.
478 * @param name The name of the section.
479 * @param size The size of the section in memory.
480 * @param offset The offset of the section in the object file.
481 * @param alignment The alignment of the section in memory.
482 * @param link The section's link field (from the ELF format).
483 * @param info The section's info field (from the ELF format).
484 * @param flags The section's flags.
485 * @retval true The section has been added.
486 * @retval false The section has not been added. See the RTL error.
487 */
488bool rtems_rtl_obj_add_section (rtems_rtl_obj* obj,
489                                int            section,
490                                const char*    name,
491                                size_t         size,
492                                off_t          offset,
493                                uint32_t       alignment,
494                                int            link,
495                                int            info,
496                                uint32_t       flags);
497
498/**
499 * Erase the object file descriptor's sections.
500 *
501 * @param obj The object file's descriptor.
502 */
503void rtems_rtl_obj_erase_sections (rtems_rtl_obj* obj);
504
505/**
506 * Find the section given a name.
507 *
508 * @param obj The object file's descriptor.
509 * @param name The name of the section to find.
510 * @retval NULL The section was not found.
511 * @return rtems_rtl_obj_sect_t* The named section.
512 */
513rtems_rtl_obj_sect* rtems_rtl_obj_find_section (const rtems_rtl_obj* obj,
514                                                const char*          name);
515
516/**
517 * Find a section given a section's index number.
518 *
519 * @param obj The object file's descriptor.
520 * @param index The section's index to find.
521 * @retval NULL The section was not found.
522 * @return rtems_rtl_obj_sect_t* The found section.
523 */
524rtems_rtl_obj_sect* rtems_rtl_obj_find_section_by_index (const rtems_rtl_obj* obj,
525                                                         int                  index);
526
527/**
528 * Find a section given a section's mask. The index is the section after which
529 * the mask is matched. An index of -1 starts the search from the beginning of
530 * the section list. You can find multiple matches for a mask by passing the
531 * index of the last section that matched the mask on a subsequent call.
532 *
533 * @param obj The object file's descriptor.
534 * @param index The section's index to start searching from, -1 for the start.
535 * @param mask The section's mask to match against the section's flags.
536 * @retval NULL The section was not found.
537 * @return rtems_rtl_obj_sect_t* The found section.
538 */
539rtems_rtl_obj_sect* rtems_rtl_obj_find_section_by_mask (const rtems_rtl_obj* obj,
540                                                        int                  index,
541                                                        uint32_t             mask);
542
543/**
544 * Allocate a table for trampoline fixup calls.
545 *
546 * @param obj The object file's descriptor.
547 * @retval true The table was allocated.
548 * @retval false The alloction failed.
549 */
550bool rtems_rtl_obj_alloc_trampoline (rtems_rtl_obj* obj);
551
552/**
553 * Erase the object file descriptor's trampoline table..
554 *
555 * @param obj The object file's descriptor.
556 */
557void rtems_rtl_obj_erase_trampoline (rtems_rtl_obj* obj);
558
559/**
560 * Allocate a table for dependent objects.
561 *
562 * @param obj The object file's descriptor.
563 * @param dependents The size of the table.
564 * @retval true The table was allocated.
565 * @retval false The alloction failed.
566 */
567bool rtems_rtl_obj_alloc_dependents (rtems_rtl_obj* obj, size_t dependents);
568
569/**
570 * Erase the object file descriptor's dependents.
571 *
572 * @param obj The object file's descriptor.
573 */
574void rtems_rtl_obj_erase_dependents (rtems_rtl_obj* obj);
575
576/**
577 * Add an object file to the dependents table.
578 *
579 * @param obj The object file's descriptor.
580 * @param dependent The dependent object file to add.
581 * @retval true The dependent has been added to the table.
582 * @retval false There is no space in the table.
583 */
584bool rtems_rtl_obj_add_dependent (rtems_rtl_obj* obj, rtems_rtl_obj* dependent);
585
586/**
587 * Remove dependencies. This decrements the dependent object file references.
588 *
589 * @param obj The object file's descriptor.
590 * @retval true The dependencies have been removed.
591 * @retval false There is no space in the table.
592 */
593bool rtems_rtl_obj_remove_dependencies (rtems_rtl_obj* obj);
594
595/**
596 * Iterate over the module dependenices.
597 *
598 * @param obj The object file's descriptor.
599 * @param handler The iterator handler. Returns true to end.
600 * @param data User data passed to the iterator.
601 * @retval true The iterator handler returned true.
602 * @retval false The iterator handler returned false.
603 */
604bool rtems_rtl_obj_iterate_dependents (rtems_rtl_obj*                 obj,
605                                       rtems_rtl_obj_depends_iterator iterator,
606                                       void*                          data);
607
608/**
609 * The text section size. Only use once all the sections has been added. It
610 * includes alignments between sections that are part of the object's text
611 * area. The consts sections are included in this section.
612 *
613 * @param obj The object file's descriptor.
614 * @return size_t The size of the text area of the object file.
615 */
616size_t rtems_rtl_obj_text_size (const rtems_rtl_obj* obj);
617
618/**
619 * The text section alignment for the object file. Only use once all the
620 * sections has been added. The section alignment is the alignment of the first
621 * text type section loaded the text section.
622 *
623 * You can assume the alignment is a positive integral power of 2 if not 0 or
624 * 1. If 0 or 1 then there is no alignment.
625 *
626 * @param obj The object file's descriptor.
627 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
628 */
629uint32_t rtems_rtl_obj_text_alignment (const rtems_rtl_obj* obj);
630
631/**
632 * The const section size. Only use once all the sections has been added. It
633 * includes alignments between sections that are part of the object's const
634 * area. The consts sections are included in this section.
635 *
636 * @param obj The object file's descriptor.
637 * @return size_t The size of the const area of the object file.
638 */
639size_t rtems_rtl_obj_const_size (const rtems_rtl_obj* obj);
640
641/**
642 * The const section alignment for the object file. Only use once all the
643 * sections has been added. The section alignment is the alignment of the first
644 * const type section loaded the const section.
645 *
646 * You can assume the alignment is a positive integral power of 2 if not 0 or
647 * 1. If 0 or 1 then there is no alignment.
648 *
649 * @param obj The object file's descriptor.
650 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
651 */
652uint32_t rtems_rtl_obj_const_alignment (const rtems_rtl_obj* obj);
653
654/**
655 * The eh section size. Only use once all the sections has been added. It
656 * includes alignments between sections that are part of the object's bss area.
657 *
658 * @param obj The object file's descriptor.
659 * @return size_t The size of the bss area of the object file.
660 */
661size_t rtems_rtl_obj_eh_size (const rtems_rtl_obj* obj);
662
663/**
664 * The eh section alignment for the object file. Only use once all the sections
665 * has been added. The section alignment is the alignment of the first bss type
666 * section loaded the bss section.
667 *
668 * You can assume the alignment is a positive integral power of 2 if not 0 or
669 * 1. If 0 or 1 then there is no alignment.
670 *
671 * @param obj The object file's descriptor.
672 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
673 */
674uint32_t rtems_rtl_obj_eh_alignment (const rtems_rtl_obj* obj);
675
676/**
677 * The data section size. Only use once all the sections has been added. It
678 * includes alignments between sections that are part of the object's data
679 * area.
680 *
681 * @param obj The object file's descriptor.
682 * @return size_t The size of the data area of the object file.
683 */
684size_t rtems_rtl_obj_data_size (const rtems_rtl_obj* obj);
685
686/**
687 * The data section alignment for the object file. Only use once all the
688 * sections has been added. The section alignment is the alignment of the first
689 * data type section loaded the data section.
690 *
691 * You can assume the alignment is a positive integral power of 2 if not 0 or
692 * 1. If 0 or 1 then there is no alignment.
693 *
694 * @param obj The object file's descriptor.
695 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
696 */
697uint32_t rtems_rtl_obj_data_alignment (const rtems_rtl_obj* obj);
698
699/**
700 * The bss section size. Only use once all the sections has been added. It
701 * includes alignments between sections that are part of the object's bss area.
702 *
703 * @param obj The object file's descriptor.
704 * @return size_t The size of the bss area of the object file.
705 */
706size_t rtems_rtl_obj_bss_size (const rtems_rtl_obj* obj);
707
708/**
709 * The bss section alignment for the object file. Only use once all the
710 * sections has been added. The section alignment is the alignment of the first
711 * bss type section loaded the bss section.
712 *
713 * You can assume the alignment is a positive integral power of 2 if not 0 or
714 * 1. If 0 or 1 then there is no alignment.
715 *
716 * @param obj The object file's descriptor.
717 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
718 */
719uint32_t rtems_rtl_obj_bss_alignment (const rtems_rtl_obj* obj);
720
721/**
722 * Relocate the object file. The object file's section are parsed for any
723 * relocation type sections.
724 *
725 * @param obj The object file's descriptor.
726 * @param fd The object file's file descriptor.
727 * @param handler The object file's format specific relocation handler.
728 * @param data User specific data handle.
729 * @retval true The object file was relocated.
730 * @retval false The relocation failed. The RTL error is set.
731 */
732bool rtems_rtl_obj_relocate (rtems_rtl_obj*             obj,
733                             int                        fd,
734                             rtems_rtl_obj_sect_handler handler,
735                             void*                      data);
736
737/**
738 * Synchronize caches to make code visible to CPU(s)
739 *
740 * @param obj The object file's descriptor.
741 */
742void rtems_rtl_obj_synchronize_cache (rtems_rtl_obj* obj);
743
744/**
745 * Relocate an object file's unresolved reference.
746 *
747 * @param rec The unresolved relocation record.
748 * @param sym The unresolved relocation's referenced symbol.
749 * @retval true The object file record was relocated.
750 * @retval false The relocation failed. The RTL error is set.
751 */
752bool rtems_rtl_obj_relocate_unresolved (rtems_rtl_unresolv_reloc* reloc,
753                                        rtems_rtl_obj_sym*        sym);
754
755/**
756 * Load the symbols from the object file. Only the exported or public symbols
757 * are read into memory and held in the global symbol table.
758 *
759 * @param obj The object file's descriptor.
760 * @param fd The object file's file descriptor.
761 * @param handler The object file's format specific symbol handler.
762 * @param data User specific data handle.
763 * @retval true The object file's symbol where loaded.
764 * @retval false The symbol loading failed. The RTL error is set.
765 */
766bool rtems_rtl_obj_load_symbols (rtems_rtl_obj*             obj,
767                                 int                        fd,
768                                 rtems_rtl_obj_sect_handler handler,
769                                 void*                      data);
770
771/**
772 * Allocate the sections. If a handler is provided (not NULL) it is called for
773 * all section.
774 *
775 * @param obj The object file's descriptor.
776 * @param fd The object file's file descriptor.
777 * @param handler The object file's format specific allocation handler.
778 * @param data User specific data handle.
779 * @retval true The object has been sucessfully loaded.
780 * @retval false The load failed. The RTL error has been set.
781 */
782bool
783rtems_rtl_obj_alloc_sections (rtems_rtl_obj*             obj,
784                              int                        fd,
785                              rtems_rtl_obj_sect_handler handler,
786                              void*                      data);
787
788/**
789 * Load the sections that have been allocated memory in the target. The bss
790 * type section does not load any data, it is set to 0. The text and data
791 * sections read the detault data from the object file into the target memory.
792 *
793 * @param obj The object file's descriptor.
794 * @param fd The object file's file descriptor.
795 * @param handler The object file's format specific load handler.
796 * @param data User specific data handle.
797 * @retval true The object has been sucessfully loaded.
798 * @retval false The load failed. The RTL error has been set.
799 */
800bool rtems_rtl_obj_load_sections (rtems_rtl_obj*             obj,
801                                  int                        fd,
802                                  rtems_rtl_obj_sect_handler handler,
803                                  void*                      data);
804
805/**
806 * Does the object have constructors to run?
807 *
808 * @return bool True if there are constructors to run.
809 */
810bool rtems_rtl_obj_ctors_to_run (rtems_rtl_obj* obj);
811
812/**
813 * Invoke the constructors the object has. Constructors are a table of pointers
814 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
815 * taken from the section's size. The objet ELF specific code is responisble
816 * for flagging which sections contain constructors.
817 *
818 * @param obj The object file's descriptor.
819 */
820void rtems_rtl_obj_run_ctors (rtems_rtl_obj* obj);
821
822/**
823 * Does the object have destructors to run?
824 *
825 * @return bool True if there are destructors to run.
826 */
827bool rtems_rtl_obj_dtors_to_run (rtems_rtl_obj* obj);
828
829/**
830 * Invoke the destructors the object has. Destructors are a table of pointers
831 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
832 * taken from the section's size. The objet ELF specific code is responisble
833 * for flagging which sections contain destructors.
834 *
835 * @param obj The object file's descriptor.
836 */
837void rtems_rtl_obj_run_dtors (rtems_rtl_obj* obj);
838
839/**
840 * Get the object file reference count.
841 *
842 * @retval int The object file's reference count.
843 */
844size_t rtems_rtl_obj_get_reference (rtems_rtl_obj* obj);
845
846/**
847 * Increment the object file reference count.
848 *
849 * @param obj The object file's descriptor.
850 */
851void rtems_rtl_obj_inc_reference (rtems_rtl_obj* obj);
852
853/**
854 * Decrement the object file reference count.
855 *
856 * @param obj The object file's descriptor.
857 */
858void rtems_rtl_obj_dec_reference (rtems_rtl_obj* obj);
859
860/**
861 * Is the object file orphaned? An orphaned object file is not locked, has no
862 * users and it not being referenced.
863 *
864 * @param obj The object file's descriptor.
865 */
866bool rtems_rtl_obj_orphaned (rtems_rtl_obj* obj);
867
868/**
869 * Load the object file, reading all sections into memory, symbols and
870 * performing any relocation fixups.
871 *
872 * @param obj The object file's descriptor.
873 * @retval true The object file has been loaded.
874 * @retval false The load failed. The RTL error has been set.
875 */
876bool rtems_rtl_obj_load (rtems_rtl_obj* obj);
877
878/**
879 * Unload the object file, erasing all symbols and releasing all memory.
880 *
881 * @param obj The object file's descriptor.
882 * @retval true The object file has been unloaded.
883 * @retval false The unload failed. The RTL error has been set.
884 */
885bool rtems_rtl_obj_unload (rtems_rtl_obj* obj);
886
887#ifdef __cplusplus
888}
889#endif /* __cplusplus */
890
891#endif
Note: See TracBrowser for help on using the repository browser.