source: rtems/cpukit/include/rtems/rtl/rtl-obj.h @ 6c9f017

Last change on this file since 6c9f017 was 6c9f017, checked in by Chris Johns <chrisj@…>, on Feb 2, 2019 at 4:09:53 AM

libdl: Add powerpc large memory and small data support.

  • Add support for architecure sections that can be handled by the architecture back end.
  • Add trampoline/fixup support for PowerPC. This means the PowerPC now supports large memory loading of applications.
  • Add a bit allocator to manage small block based regions of memory.
  • Add small data (sdata/sbss) support for the PowerPC. The support makes the linker allocated small data region of memory a global resource available to libdl loaded object files.

Updates #3687
Updates #3685

  • Property mode set to 100644
File size: 31.5 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 the tramopline memory. */
231  void*               tramp_brk;    /**< Trampoline memory allocator. MD
232                                     *   relocators can take memory from the
233                                     *   break upto the size. */
234  struct link_map*    linkmap;      /**< For GDB. */
235  void*               loader;       /**< The file details specific to a
236                                     *   loader. */
237};
238
239/**
240 * A section handler is called once for each section that needs to be
241 * processed by this handler. The handler is specific to a task.
242 *
243 * @param obj The object file's descriptor the section belongs too.
244 * @param fd The file descriptor of the object file beling loaded.
245 * @param sect The section the handler is being invoked to handle.
246 * @param data A user supplied data variable.
247 * @retval true The operation was successful.
248 * @retval false The operation failed and the RTL has been set.
249 */
250typedef bool (*rtems_rtl_obj_sect_handler)(rtems_rtl_obj*      obj,
251                                           int                 fd,
252                                           rtems_rtl_obj_sect* sect,
253                                           void*               data);
254
255/**
256 * Get the file name.
257 *
258 * @param obj The object file.
259 * @return const char* The string.
260 */
261static inline const char* rtems_rtl_obj_fname (const rtems_rtl_obj* obj)
262{
263  return obj->fname;
264}
265
266/**
267 * Is the file name valid ?
268 *
269 * @param obj The object file.
270 * @return bool There is a file name
271 */
272static inline bool rtems_rtl_obj_fname_valid (const rtems_rtl_obj* obj)
273{
274  return obj->fname;
275}
276
277/**
278 * Get the object name.
279 *
280 * @param obj The object file.
281 * @return const char* The string.
282 */
283static inline const char* rtems_rtl_obj_oname (const rtems_rtl_obj* obj)
284{
285  return obj->oname;
286}
287
288/**
289 * Is the object name valid ?
290 *
291 * @param obj The object file.
292 * @return bool There is an object name
293 */
294static inline bool rtems_rtl_obj_oname_valid (const rtems_rtl_obj* obj)
295{
296  return obj->oname;
297}
298
299/**
300 * Get the archive name.
301 *
302 * @param obj The object file.
303 * @return const char* The string.
304 */
305static inline const char* rtems_rtl_obj_aname (const rtems_rtl_obj* obj)
306{
307  return obj->aname;
308}
309
310/**
311 * Is the archive name valid ?
312 *
313 * @param obj The object file.
314 * @return bool There is an archive name
315 */
316static inline bool rtems_rtl_obj_aname_valid (const rtems_rtl_obj* obj)
317{
318  return obj->aname;
319}
320
321/**
322 * Is the address inside the text section?
323 *
324 * @param obj The object file.
325 * @return bool There is an archive name
326 */
327static inline bool rtems_rtl_obj_text_inside (const rtems_rtl_obj* obj,
328                                              const void*          address)
329{
330  return
331    (address >= obj->text_base) &&
332    (address < (obj->text_base + obj->text_size));
333}
334
335/**
336 * Align the size to the next alignment point. Assume the alignment is a
337 * positive integral power of 2 if not 0 or 1. If 0 or 1 then there is no
338 * alignment.
339 *
340 * @param offset Offset to align up from.
341 * @param alignment The alignment.
342 * @return size_t Aligned offset.
343 */
344static inline size_t rtems_rtl_obj_align (size_t   offset,
345                                          uint32_t alignment)
346{
347  if ((alignment > 1) && ((offset & (alignment - 1)) != 0))
348    offset = (offset + alignment) & ~(alignment - 1);
349  return offset;
350}
351
352/**
353 * Is the symbol in this object's files globa symbol table?
354 *
355 * @param obj The object file's descriptor to search.
356 * @param sym The symbol to check.
357 * @retval bool Returns @true if present else @false is returned.
358 */
359static inline bool rtems_rtl_obj_has_symbol (const rtems_rtl_obj*     obj,
360                                             const rtems_rtl_obj_sym* sym)
361{
362  return (sym >= obj->global_table &&
363          sym < (obj->global_table + obj->global_syms));
364}
365
366/**
367 * Is there space in the trampoline memory for a trapoline.
368 *
369 * @param obj The object file's descriptor to check for available space.
370 * @param size The size to be allocated.
371 * @retval bool Returns @true if the space is available.
372 */
373static inline bool rtems_rtl_obj_has_ramp_space (const rtems_rtl_obj* obj,
374                                                 const size_t         size)
375{
376  return (obj->trampoline != NULL &&
377          ((obj->tramp_brk - obj->trampoline) + size) <= obj->tramp_size);
378}
379
380/**
381 * Does the section require architecture specific allocations?
382 *
383 * @param sect The section.
384 * @retval bool Returns @true if the section requires arch allocation.
385 */
386static inline bool rtems_rtl_obj_sect_is_arch_alloc (rtems_rtl_obj_sect* sect)
387{
388  return (sect->flags & RTEMS_RTL_OBJ_SECT_ARCH_ALLOC) != 0;
389}
390
391/**
392 * Allocate an object structure on the heap.
393 *
394 * @retval NULL No memory for the object.
395 */
396rtems_rtl_obj* rtems_rtl_obj_alloc (void);
397
398/**
399 * Free the object structure and related resources.
400 *
401 * @param obj The object file's descriptor to free.
402 * @retval false The object has dependences.
403 * @retval true The object has been freed.
404 */
405bool rtems_rtl_obj_free (rtems_rtl_obj* obj);
406
407/**
408 * Does the object file have unresolved external references ? If it does the
409 * results of executing code is unpredictable.
410 *
411 * @param obj The object file's descriptor.
412 * @retval true The object file has unresolved externals.
413 * @retval false The object file has all external references resolved.
414 */
415bool rtems_rtl_obj_unresolved (rtems_rtl_obj* obj);
416
417/**
418 * Parses a filename and returns newly allocated strings with the archive name,
419 * object name, and the object's offset
420 *
421 * @param name The filename of the object
422 * @param aname Address of a string pointer that holds the archive name
423 * @param oname Address of a string pointer that holds the object name
424 * @param ooffset Address of an int that holds the object offset
425 * @retval true The parsing was successful
426 * @retval false The parsing was unsuccessful
427 */
428bool rtems_rtl_parse_name (const char*  name,
429                           const char** aname,
430                           const char** oname,
431                           off_t*       ooffset);
432
433/**
434 * Find an object file on disk that matches the name. The object descriptor is
435 * fill in with the various parts of a name. A name can have archive, object
436 * file and offset components. The search path in the RTL is searched.
437 *
438 * @param obj The object file's descriptor.
439 * @param name The name to locate on disk.
440 * @retval true The file has been found.
441 * @retval false The file could not be located. The RTL error has been set.
442 */
443bool rtems_rtl_obj_find_file (rtems_rtl_obj* obj, const char* name);
444
445/**
446 * Add a section to the object descriptor.
447 *
448 * @param obj The object file's descriptor.
449 * @param section The section's index number.
450 * @param name The name of the section.
451 * @param size The size of the section in memory.
452 * @param offset The offset of the section in the object file.
453 * @param alignment The alignment of the section in memory.
454 * @param link The section's link field (from the ELF format).
455 * @param info The section's info field (from the ELF format).
456 * @param flags The section's flags.
457 * @retval true The section has been added.
458 * @retval false The section has not been added. See the RTL error.
459 */
460bool rtems_rtl_obj_add_section (rtems_rtl_obj* obj,
461                                int            section,
462                                const char*    name,
463                                size_t         size,
464                                off_t          offset,
465                                uint32_t       alignment,
466                                int            link,
467                                int            info,
468                                uint32_t       flags);
469
470/**
471 * Erase the object file descriptor's sections.
472 *
473 * @param obj The object file's descriptor.
474 */
475void rtems_rtl_obj_erase_sections (rtems_rtl_obj* obj);
476
477/**
478 * Find the section given a name.
479 *
480 * @param obj The object file's descriptor.
481 * @param name The name of the section to find.
482 * @retval NULL The section was not found.
483 * @return rtems_rtl_obj_sect_t* The named section.
484 */
485rtems_rtl_obj_sect* rtems_rtl_obj_find_section (const rtems_rtl_obj* obj,
486                                                const char*          name);
487
488/**
489 * Find a section given a section's index number.
490 *
491 * @param obj The object file's descriptor.
492 * @param index The section's index to find.
493 * @retval NULL The section was not found.
494 * @return rtems_rtl_obj_sect_t* The found section.
495 */
496rtems_rtl_obj_sect* rtems_rtl_obj_find_section_by_index (const rtems_rtl_obj* obj,
497                                                         int                  index);
498
499/**
500 * Find a section given a section's mask. The index is the section after which
501 * the mask is matched. An index of -1 starts the search from the beginning of
502 * the section list. You can find multiple matches for a mask by passing the
503 * index of the last section that matched the mask on a subsequent call.
504 *
505 * @param obj The object file's descriptor.
506 * @param index The section's index to start searching from, -1 for the start.
507 * @param mask The section's mask to match against the section's flags.
508 * @retval NULL The section was not found.
509 * @return rtems_rtl_obj_sect_t* The found section.
510 */
511rtems_rtl_obj_sect* rtems_rtl_obj_find_section_by_mask (const rtems_rtl_obj* obj,
512                                                        int                  index,
513                                                        uint32_t             mask);
514
515/**
516 * Allocate a table for trampoline fixup calls.
517 *
518 * @param obj The object file's descriptor.
519 * @retval true The table was allocated.
520 * @retval false The alloction failed.
521 */
522bool rtems_rtl_obj_alloc_trampoline (rtems_rtl_obj* obj);
523
524/**
525 * Erase the object file descriptor's trampoline table..
526 *
527 * @param obj The object file's descriptor.
528 */
529void rtems_rtl_obj_erase_trampoline (rtems_rtl_obj* obj);
530
531/**
532 * Allocate a table for dependent objects.
533 *
534 * @param obj The object file's descriptor.
535 * @param dependents The size of the table.
536 * @retval true The table was allocated.
537 * @retval false The alloction failed.
538 */
539bool rtems_rtl_obj_alloc_dependents (rtems_rtl_obj* obj, size_t dependents);
540
541/**
542 * Erase the object file descriptor's dependents.
543 *
544 * @param obj The object file's descriptor.
545 */
546void rtems_rtl_obj_erase_dependents (rtems_rtl_obj* obj);
547
548/**
549 * Add an object file to the dependents table.
550 *
551 * @param obj The object file's descriptor.
552 * @param dependent The dependent object file to add.
553 * @retval true The dependent has been added to the table.
554 * @retval false There is no space in the table.
555 */
556bool rtems_rtl_obj_add_dependent (rtems_rtl_obj* obj, rtems_rtl_obj* dependent);
557
558/**
559 * Remove dependencies. This decrements the dependent object file references.
560 *
561 * @param obj The object file's descriptor.
562 * @retval true The dependencies have been removed.
563 * @retval false There is no space in the table.
564 */
565bool rtems_rtl_obj_remove_dependencies (rtems_rtl_obj* obj);
566
567/**
568 * Iterate over the module dependenices.
569 *
570 * @param obj The object file's descriptor.
571 * @param handler The iterator handler. Returns true to end.
572 * @param data User data passed to the iterator.
573 * @retval true The iterator handler returned true.
574 * @retval false The iterator handler returned false.
575 */
576bool rtems_rtl_obj_iterate_dependents (rtems_rtl_obj*                 obj,
577                                       rtems_rtl_obj_depends_iterator iterator,
578                                       void*                          data);
579
580/**
581 * The text section size. Only use once all the sections has been added. It
582 * includes alignments between sections that are part of the object's text
583 * area. The consts sections are included in this section.
584 *
585 * @param obj The object file's descriptor.
586 * @return size_t The size of the text area of the object file.
587 */
588size_t rtems_rtl_obj_text_size (const rtems_rtl_obj* obj);
589
590/**
591 * The text section alignment for the object file. Only use once all the
592 * sections has been added. The section alignment is the alignment of the first
593 * text type section loaded the text section.
594 *
595 * You can assume the alignment is a positive integral power of 2 if not 0 or
596 * 1. If 0 or 1 then there is no alignment.
597 *
598 * @param obj The object file's descriptor.
599 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
600 */
601uint32_t rtems_rtl_obj_text_alignment (const rtems_rtl_obj* obj);
602
603/**
604 * The const section size. Only use once all the sections has been added. It
605 * includes alignments between sections that are part of the object's const
606 * area. The consts sections are included in this section.
607 *
608 * @param obj The object file's descriptor.
609 * @return size_t The size of the const area of the object file.
610 */
611size_t rtems_rtl_obj_const_size (const rtems_rtl_obj* obj);
612
613/**
614 * The const section alignment for the object file. Only use once all the
615 * sections has been added. The section alignment is the alignment of the first
616 * const type section loaded the const section.
617 *
618 * You can assume the alignment is a positive integral power of 2 if not 0 or
619 * 1. If 0 or 1 then there is no alignment.
620 *
621 * @param obj The object file's descriptor.
622 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
623 */
624uint32_t rtems_rtl_obj_const_alignment (const rtems_rtl_obj* obj);
625
626/**
627 * The eh section size. Only use once all the sections has been added. It
628 * includes alignments between sections that are part of the object's bss area.
629 *
630 * @param obj The object file's descriptor.
631 * @return size_t The size of the bss area of the object file.
632 */
633size_t rtems_rtl_obj_eh_size (const rtems_rtl_obj* obj);
634
635/**
636 * The eh section alignment for the object file. Only use once all the sections
637 * has been added. The section alignment is the alignment of the first bss type
638 * section loaded the bss section.
639 *
640 * You can assume the alignment is a positive integral power of 2 if not 0 or
641 * 1. If 0 or 1 then there is no alignment.
642 *
643 * @param obj The object file's descriptor.
644 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
645 */
646uint32_t rtems_rtl_obj_eh_alignment (const rtems_rtl_obj* obj);
647
648/**
649 * The data section size. Only use once all the sections has been added. It
650 * includes alignments between sections that are part of the object's data
651 * area.
652 *
653 * @param obj The object file's descriptor.
654 * @return size_t The size of the data area of the object file.
655 */
656size_t rtems_rtl_obj_data_size (const rtems_rtl_obj* obj);
657
658/**
659 * The data section alignment for the object file. Only use once all the
660 * sections has been added. The section alignment is the alignment of the first
661 * data type section loaded the data section.
662 *
663 * You can assume the alignment is a positive integral power of 2 if not 0 or
664 * 1. If 0 or 1 then there is no alignment.
665 *
666 * @param obj The object file's descriptor.
667 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
668 */
669uint32_t rtems_rtl_obj_data_alignment (const rtems_rtl_obj* obj);
670
671/**
672 * The bss section size. Only use once all the sections has been added. It
673 * includes alignments between sections that are part of the object's bss area.
674 *
675 * @param obj The object file's descriptor.
676 * @return size_t The size of the bss area of the object file.
677 */
678size_t rtems_rtl_obj_bss_size (const rtems_rtl_obj* obj);
679
680/**
681 * The bss section alignment for the object file. Only use once all the
682 * sections has been added. The section alignment is the alignment of the first
683 * bss type section loaded the bss section.
684 *
685 * You can assume the alignment is a positive integral power of 2 if not 0 or
686 * 1. If 0 or 1 then there is no alignment.
687 *
688 * @param obj The object file's descriptor.
689 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
690 */
691uint32_t rtems_rtl_obj_bss_alignment (const rtems_rtl_obj* obj);
692
693/**
694 * Relocate the object file. The object file's section are parsed for any
695 * relocation type sections.
696 *
697 * @param obj The object file's descriptor.
698 * @param fd The object file's file descriptor.
699 * @param handler The object file's format specific relocation handler.
700 * @param data User specific data handle.
701 * @retval true The object file was relocated.
702 * @retval false The relocation failed. The RTL error is set.
703 */
704bool rtems_rtl_obj_relocate (rtems_rtl_obj*             obj,
705                             int                        fd,
706                             rtems_rtl_obj_sect_handler handler,
707                             void*                      data);
708
709/**
710 * Synchronize caches to make code visible to CPU(s)
711 *
712 * @param obj The object file's descriptor.
713 */
714void rtems_rtl_obj_synchronize_cache (rtems_rtl_obj* obj);
715
716/**
717 * Relocate an object file's unresolved reference.
718 *
719 * @param rec The unresolved relocation record.
720 * @param sym The unresolved relocation's referenced symbol.
721 * @retval true The object file record was relocated.
722 * @retval false The relocation failed. The RTL error is set.
723 */
724bool rtems_rtl_obj_relocate_unresolved (rtems_rtl_unresolv_reloc* reloc,
725                                        rtems_rtl_obj_sym*        sym);
726
727/**
728 * Load the symbols from the object file. Only the exported or public symbols
729 * are read into memory and held in the global symbol table.
730 *
731 * @param obj The object file's descriptor.
732 * @param fd The object file's file descriptor.
733 * @param handler The object file's format specific symbol handler.
734 * @param data User specific data handle.
735 * @retval true The object file's symbol where loaded.
736 * @retval false The symbol loading failed. The RTL error is set.
737 */
738bool rtems_rtl_obj_load_symbols (rtems_rtl_obj*             obj,
739                                 int                        fd,
740                                 rtems_rtl_obj_sect_handler handler,
741                                 void*                      data);
742
743/**
744 * Allocate the sections. If a handler is provided (not NULL) it is called for
745 * all section.
746 *
747 * @param obj The object file's descriptor.
748 * @param fd The object file's file descriptor.
749 * @param handler The object file's format specific allocation handler.
750 * @param data User specific data handle.
751 * @retval true The object has been sucessfully loaded.
752 * @retval false The load failed. The RTL error has been set.
753 */
754bool
755rtems_rtl_obj_alloc_sections (rtems_rtl_obj*             obj,
756                              int                        fd,
757                              rtems_rtl_obj_sect_handler handler,
758                              void*                      data);
759
760/**
761 * Load the sections that have been allocated memory in the target. The bss
762 * type section does not load any data, it is set to 0. The text and data
763 * sections read the detault data from the object file into the target memory.
764 *
765 * @param obj The object file's descriptor.
766 * @param fd The object file's file descriptor.
767 * @param handler The object file's format specific load handler.
768 * @param data User specific data handle.
769 * @retval true The object has been sucessfully loaded.
770 * @retval false The load failed. The RTL error has been set.
771 */
772bool rtems_rtl_obj_load_sections (rtems_rtl_obj*             obj,
773                                  int                        fd,
774                                  rtems_rtl_obj_sect_handler handler,
775                                  void*                      data);
776
777/**
778 * Does the object have constructors to run?
779 *
780 * @return bool True if there are constructors to run.
781 */
782bool rtems_rtl_obj_ctors_to_run (rtems_rtl_obj* obj);
783
784/**
785 * Invoke the constructors the object has. Constructors are a table of pointers
786 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
787 * taken from the section's size. The objet ELF specific code is responisble
788 * for flagging which sections contain constructors.
789 *
790 * @param obj The object file's descriptor.
791 */
792void rtems_rtl_obj_run_ctors (rtems_rtl_obj* obj);
793
794/**
795 * Does the object have destructors to run?
796 *
797 * @return bool True if there are destructors to run.
798 */
799bool rtems_rtl_obj_dtors_to_run (rtems_rtl_obj* obj);
800
801/**
802 * Invoke the destructors the object has. Destructors are a table of pointers
803 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
804 * taken from the section's size. The objet ELF specific code is responisble
805 * for flagging which sections contain destructors.
806 *
807 * @param obj The object file's descriptor.
808 */
809void rtems_rtl_obj_run_dtors (rtems_rtl_obj* obj);
810
811/**
812 * Get the object file reference count.
813 *
814 * @retval int The object file's reference count.
815 */
816size_t rtems_rtl_obj_get_reference (rtems_rtl_obj* obj);
817
818/**
819 * Increment the object file reference count.
820 *
821 * @param obj The object file's descriptor.
822 */
823void rtems_rtl_obj_inc_reference (rtems_rtl_obj* obj);
824
825/**
826 * Decrement the object file reference count.
827 *
828 * @param obj The object file's descriptor.
829 */
830void rtems_rtl_obj_dec_reference (rtems_rtl_obj* obj);
831
832/**
833 * Is the object file orphaned? An orphaned object file is not locked, has no
834 * users and it not being referenced.
835 *
836 * @param obj The object file's descriptor.
837 */
838bool rtems_rtl_obj_orphaned (rtems_rtl_obj* obj);
839
840/**
841 * Load the object file, reading all sections into memory, symbols and
842 * performing any relocation fixups.
843 *
844 * @param obj The object file's descriptor.
845 * @retval true The object file has been loaded.
846 * @retval false The load failed. The RTL error has been set.
847 */
848bool rtems_rtl_obj_load (rtems_rtl_obj* obj);
849
850/**
851 * Unload the object file, erasing all symbols and releasing all memory.
852 *
853 * @param obj The object file's descriptor.
854 * @retval true The object file has been unloaded.
855 * @retval false The unload failed. The RTL error has been set.
856 */
857bool rtems_rtl_obj_unload (rtems_rtl_obj* obj);
858
859#ifdef __cplusplus
860}
861#endif /* __cplusplus */
862
863#endif
Note: See TracBrowser for help on using the repository browser.