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

5
Last change on this file since f59d435d was f59d435d, checked in by Chris Johns <chrisj@…>, on 04/12/18 at 07:46:49

libdl: Remove _t from all structures as this is reserved for the standards
  • Property mode set to 100644
File size: 23.2 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
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_REL   (1 << 5)  /**< Section holds relocation records. */
96#define RTEMS_RTL_OBJ_SECT_RELA  (1 << 6)  /**< Section holds relocation addend
97                                            *   records. */
98#define RTEMS_RTL_OBJ_SECT_SYM   (1 << 7)  /**< Section holds symbols. */
99#define RTEMS_RTL_OBJ_SECT_STR   (1 << 8)  /**< Section holds strings. */
100#define RTEMS_RTL_OBJ_SECT_ALLOC (1 << 9)  /**< Section allocates runtime memory. */
101#define RTEMS_RTL_OBJ_SECT_LOAD  (1 << 10) /**< Section is loaded from object file. */
102#define RTEMS_RTL_OBJ_SECT_WRITE (1 << 11) /**< Section is writable, ie data. */
103#define RTEMS_RTL_OBJ_SECT_EXEC  (1 << 12) /**< Section is executable. */
104#define RTEMS_RTL_OBJ_SECT_ZERO  (1 << 13) /**< Section is preset to zero. */
105#define RTEMS_RTL_OBJ_SECT_LINK  (1 << 14) /**< Section is link-ordered. */
106#define RTEMS_RTL_OBJ_SECT_CTOR  (1 << 15) /**< Section contains constructors. */
107#define RTEMS_RTL_OBJ_SECT_DTOR  (1 << 16) /**< Section contains destructors. */
108#define RTEMS_RTL_OBJ_SECT_LOCD  (1 << 17) /**< Section has been located. */
109
110/**
111 * Section types mask.
112 */
113#define RTEMS_RTL_OBJ_SECT_TYPES (RTEMS_RTL_OBJ_SECT_TEXT | \
114                                  RTEMS_RTL_OBJ_SECT_CONST | \
115                                  RTEMS_RTL_OBJ_SECT_DATA | \
116                                  RTEMS_RTL_OBJ_SECT_BSS | \
117                                  RTEMS_RTL_OBJ_SECT_EH)
118
119/**
120 * An object file is made up of sections and the can be more than
121 * one of a specific type of sections. All sections and grouped
122 * together in memory.
123 */
124struct rtems_rtl_obj_sect
125{
126  rtems_chain_node node;        /**< The node's link in the chain. */
127  int              section;     /**< The section number. */
128  const char*      name;        /**< The section's name. */
129  size_t           size;        /**< The size of the section in memory. */
130  off_t            offset;      /**< Offset into the object file. Relative to
131                                 *   the start of the object file. */
132  uint32_t         alignment;   /**< Alignment of this section. */
133  int              link;        /**< Section link field. */
134  int              info;        /**< Secfion info field. */
135  uint32_t         flags;       /**< The section's flags. */
136  void*            base;        /**< The base address of the section in
137                                 *   memory. */
138  int              load_order;  /**< Order we load sections. */
139};
140
141/**
142 * Object file descriptor flags.
143 */
144#define RTEMS_RTL_OBJ_LOCKED     (1 << 0) /**< Lock the object file so it cannot
145                                           *   be unloaded. */
146#define RTEMS_RTL_OBJ_UNRESOLVED (1 << 1) /**< The object file has unresolved
147                                           *   external symbols. */
148
149/**
150 * RTL Object. There is one for each object module loaded plus one for the base
151 * kernel image.
152 */
153struct rtems_rtl_obj
154{
155  rtems_chain_node    link;         /**< The node's link in the chain. */
156  uint32_t            flags;        /**< The status of the object file. */
157  uint32_t            users;        /**< References to the object file. */
158  int                 format;       /**< The format of the object file. */
159  const char*         fname;        /**< The file name for the object. */
160  const char*         oname;        /**< The object file name. Can be
161                                     *   relative. */
162  const char*         aname;        /**< The archive name containing the
163                                     *   object. NULL means the object is not
164                                     *   in a lib */
165  off_t               ooffset;      /**< The object offset in the archive. */
166  size_t              fsize;        /**< Size of the object file. */
167  rtems_chain_control sections;     /**< The sections of interest in the
168                                     *   object file. */
169  rtems_rtl_obj_sym*  local_table;  /**< Local symbol table. */
170  size_t              local_syms;   /**< Local symbol count. */
171  size_t              local_size;   /**< Local symbol memory usage. */
172  rtems_rtl_obj_sym*  global_table; /**< Global symbol table. */
173  size_t              global_syms;  /**< Global symbol count. */
174  size_t              global_size;  /**< Global symbol memory usage. */
175  uint32_t            unresolved;   /**< The number of unresolved relocations. */
176  void*               text_base;    /**< The base address of the text section
177                                     *   in memory. */
178  size_t              text_size;    /**< The size of the text section. */
179  void*               const_base;   /**< The base address of the const section
180                                     *   in memory. */
181  void*               eh_base;      /**< The base address of the eh section
182                                     *   in memory. */
183  size_t              eh_size;      /**< The size of the eh section. */
184  void*               data_base;    /**< The base address of the data section
185                                     *   in memory. */
186  void*               bss_base;     /**< The base address of the bss section
187                                     *   in memory. */
188  size_t              bss_size;     /**< The size of the bss section. */
189  size_t              exec_size;    /**< The amount of executable memory
190                                     *   allocated */
191  void*               entry;        /**< The entry point of the module. */
192  uint32_t            checksum;     /**< The checksum of the text sections. A
193                                     *   zero means do not checksum. */
194  uint32_t*           sec_num;      /**< The sec nums of each obj. */
195  uint32_t            obj_num;      /**< The count of elf files in an rtl obj. */
196  struct link_map*    linkmap;      /**< For GDB. */
197  void*               loader;       /**< The file details specific to a loader. */
198};
199
200/**
201 * A section handler is called once for each section that needs to be
202 * processed by this handler.
203 *
204 * @param obj The object file's descriptor the section belongs too.
205 * @param fd The file descriptor of the object file beling loaded.
206 * @param sect The section the handler is being invoked to handle.
207 * @param data A user supplied data variable.
208 * @retval true The operation was successful.
209 * @retval false The operation failed and the RTL has been set.
210 */
211typedef bool (*rtems_rtl_obj_sect_handler)(rtems_rtl_obj*      obj,
212                                           int                 fd,
213                                           rtems_rtl_obj_sect* sect,
214                                           void*               data);
215
216/**
217 * Get the file name.
218 *
219 * @param obj The object file.
220 * @return const char* The string.
221 */
222static inline const char* rtems_rtl_obj_fname (const rtems_rtl_obj* obj)
223{
224  return obj->fname;
225}
226
227/**
228 * Is the file name valid ?
229 *
230 * @param obj The object file.
231 * @return bool There is a file name
232 */
233static inline bool rtems_rtl_obj_fname_valid (const rtems_rtl_obj* obj)
234{
235  return obj->fname;
236}
237
238/**
239 * Get the object name.
240 *
241 * @param obj The object file.
242 * @return const char* The string.
243 */
244static inline const char* rtems_rtl_obj_oname (const rtems_rtl_obj* obj)
245{
246  return obj->oname;
247}
248
249/**
250 * Is the object name valid ?
251 *
252 * @param obj The object file.
253 * @return bool There is an object name
254 */
255static inline bool rtems_rtl_obj_oname_valid (const rtems_rtl_obj* obj)
256{
257  return obj->oname;
258}
259
260/**
261 * Get the archive name.
262 *
263 * @param obj The object file.
264 * @return const char* The string.
265 */
266static inline const char* rtems_rtl_obj_aname (const rtems_rtl_obj* obj)
267{
268  return obj->aname;
269}
270
271/**
272 * Is the archive name valid ?
273 *
274 * @param obj The object file.
275 * @return bool There is an archive name
276 */
277static inline bool rtems_rtl_obj_aname_valid (const rtems_rtl_obj* obj)
278{
279  return obj->aname;
280}
281
282/**
283 * Is the address inside the text section?
284 *
285 * @param obj The object file.
286 * @return bool There is an archive name
287 */
288static inline bool rtems_rtl_obj_text_inside (const rtems_rtl_obj* obj,
289                                              const void*          address)
290{
291  return
292    (address >= obj->text_base) &&
293    (address < (obj->text_base + obj->text_size));
294}
295
296/**
297 * Allocate an object structure on the heap.
298 *
299 * @retval NULL No memory for the object.
300 */
301rtems_rtl_obj* rtems_rtl_obj_alloc (void);
302
303/**
304 * Free the object structure and related resources.
305 *
306 * @param obj The object file's descriptor to free.
307 * @retval false The object has dependences.
308 * @retval true The object has been freed.
309 */
310bool rtems_rtl_obj_free (rtems_rtl_obj* obj);
311
312/**
313 * Does the object file have unresolved external references ? If it does the
314 * results of executing code is unpredictable.
315 *
316 * @param obj The object file's descriptor.
317 * @retval true The object file has unresolved externals.
318 * @retval false The object file has all external references resolved.
319 */
320bool rtems_rtl_obj_unresolved (rtems_rtl_obj* obj);
321
322/**
323 * Parses a filename and returns newly allocated strings with the archive name,
324 * object name, and the object's offset
325 *
326 * @param name The filename of the object
327 * @param aname Address of a string pointer that holds the archive name
328 * @param oname Address of a string pointer that holds the object name
329 * @param ooffset Address of an int that holds the object offset
330 * @retval true The parsing was successful
331 * @retval false The parsing was unsuccessful
332 */
333bool rtems_rtl_parse_name (const char*  name,
334                           const char** aname,
335                           const char** oname,
336                           off_t*       ooffset);
337
338/**
339 * Check of the name matches the object file's object name.
340 *
341 * @param obj The object file's descriptor.
342 * @param name The name to match.
343 */
344bool rtems_rtl_match_name (rtems_rtl_obj* obj, const char* name);
345
346/**
347 * Find an object file on disk that matches the name. The object descriptor is
348 * fill in with the various parts of a name. A name can have archive, object
349 * file and offset components. The search path in the RTL is searched.
350 *
351 * @param obj The object file's descriptor.
352 * @param name The name to locate on disk.
353 * @retval true The file has been found.
354 * @retval false The file could not be located. The RTL error has been set.
355 */
356bool rtems_rtl_obj_find_file (rtems_rtl_obj* obj, const char* name);
357
358/**
359 * Add a section to the object descriptor.
360 *
361 * @param obj The object file's descriptor.
362 * @param section The section's index number.
363 * @param name The name of the section.
364 * @param size The size of the section in memory.
365 * @param offset The offset of the section in the object file.
366 * @param alignment The alignment of the section in memory.
367 * @param link The section's link field (from the ELF format).
368 * @param info The section's info field (from the ELF format).
369 * @param flags The section's flags.
370 * @retval true The section has been added.
371 * @retval false The section has not been added. See the RTL error.
372 */
373bool rtems_rtl_obj_add_section (rtems_rtl_obj* obj,
374                                int            section,
375                                const char*    name,
376                                size_t         size,
377                                off_t          offset,
378                                uint32_t       alignment,
379                                int            link,
380                                int            info,
381                                uint32_t       flags);
382
383/**
384 * Erase the object file descriptor's sections.
385 *
386 * @param obj The object file's descriptor.
387 */
388void rtems_rtl_obj_erase_sections (rtems_rtl_obj* obj);
389
390/**
391 * Find the section given a name.
392 *
393 * @param obj The object file's descriptor.
394 * @param name The name of the section to find.
395 * @retval NULL The section was not found.
396 * @return rtems_rtl_obj_sect_t* The named section.
397 */
398rtems_rtl_obj_sect* rtems_rtl_obj_find_section (const rtems_rtl_obj* obj,
399                                                const char*          name);
400
401/**
402 * Find a section given a section's index number.
403 *
404 * @param obj The object file's descriptor.
405 * @param index The section's index to find.
406 * @retval NULL The section was not found.
407 * @return rtems_rtl_obj_sect_t* The found section.
408 */
409rtems_rtl_obj_sect* rtems_rtl_obj_find_section_by_index (const rtems_rtl_obj* obj,
410                                                         int                  index);
411
412/**
413 * The text section size. Only use once all the sections has been added. It
414 * includes alignments between sections that are part of the object's text
415 * area. The consts sections are included in this section.
416 *
417 * @param obj The object file's descriptor.
418 * @return size_t The size of the text area of the object file.
419 */
420size_t rtems_rtl_obj_text_size (const rtems_rtl_obj* obj);
421
422/**
423 * The text section alignment for the object file. Only use once all the
424 * sections has been added. The section alignment is the alignment of the first
425 * text type section loaded the text section.
426 *
427 * You can assume the alignment is a positive integral power of 2 if not 0 or
428 * 1. If 0 or 1 then there is no alignment.
429 *
430 * @param obj The object file's descriptor.
431 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
432 */
433uint32_t rtems_rtl_obj_text_alignment (const rtems_rtl_obj* obj);
434
435/**
436 * The const section size. Only use once all the sections has been added. It
437 * includes alignments between sections that are part of the object's const
438 * area. The consts sections are included in this section.
439 *
440 * @param obj The object file's descriptor.
441 * @return size_t The size of the const area of the object file.
442 */
443size_t rtems_rtl_obj_const_size (const rtems_rtl_obj* obj);
444
445/**
446 * The const section alignment for the object file. Only use once all the
447 * sections has been added. The section alignment is the alignment of the first
448 * const type section loaded the const section.
449 *
450 * You can assume the alignment is a positive integral power of 2 if not 0 or
451 * 1. If 0 or 1 then there is no alignment.
452 *
453 * @param obj The object file's descriptor.
454 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
455 */
456uint32_t rtems_rtl_obj_const_alignment (const rtems_rtl_obj* obj);
457
458/**
459 * The eh section size. Only use once all the sections has been added. It
460 * includes alignments between sections that are part of the object's 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_eh_size (const rtems_rtl_obj* obj);
466
467/**
468 * The eh section alignment for the object file. Only use once all the sections
469 * has been added. The section alignment is the alignment of the first bss type
470 * 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_eh_alignment (const rtems_rtl_obj* obj);
479
480/**
481 * The data section size. Only use once all the sections has been added. It
482 * includes alignments between sections that are part of the object's data
483 * area.
484 *
485 * @param obj The object file's descriptor.
486 * @return size_t The size of the data area of the object file.
487 */
488size_t rtems_rtl_obj_data_size (const rtems_rtl_obj* obj);
489
490/**
491 * The data section alignment for the object file. Only use once all the
492 * sections has been added. The section alignment is the alignment of the first
493 * data type section loaded the data section.
494 *
495 * You can assume the alignment is a positive integral power of 2 if not 0 or
496 * 1. If 0 or 1 then there is no alignment.
497 *
498 * @param obj The object file's descriptor.
499 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
500 */
501uint32_t rtems_rtl_obj_data_alignment (const rtems_rtl_obj* obj);
502
503/**
504 * The bss section size. Only use once all the sections has been added. It
505 * includes alignments between sections that are part of the object's bss area.
506 *
507 * @param obj The object file's descriptor.
508 * @return size_t The size of the bss area of the object file.
509 */
510size_t rtems_rtl_obj_bss_size (const rtems_rtl_obj* obj);
511
512/**
513 * The bss section alignment for the object file. Only use once all the
514 * sections has been added. The section alignment is the alignment of the first
515 * bss type section loaded the bss section.
516 *
517 * You can assume the alignment is a positive integral power of 2 if not 0 or
518 * 1. If 0 or 1 then there is no alignment.
519 *
520 * @param obj The object file's descriptor.
521 * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment.
522 */
523uint32_t rtems_rtl_obj_bss_alignment (const rtems_rtl_obj* obj);
524
525/**
526 * Relocate the object file. The object file's section are parsed for any
527 * relocation type sections.
528 *
529 * @param obj The object file's descriptor.
530 * @param fd The object file's file descriptor.
531 * @param handler The object file's format specific relocation handler.
532 * @param data User specific data handle.
533 * @retval true The object file was relocated.
534 * @retval false The relocation failed. The RTL error is set.
535 */
536bool rtems_rtl_obj_relocate (rtems_rtl_obj*             obj,
537                             int                        fd,
538                             rtems_rtl_obj_sect_handler handler,
539                             void*                      data);
540
541/**
542 * Synchronize caches to make code visible to CPU(s)
543 *
544 * @param obj The object file's descriptor.
545 */
546void rtems_rtl_obj_synchronize_cache (rtems_rtl_obj* obj);
547
548/**
549 * Relocate an object file's unresolved reference.
550 *
551 * @param rec The unresolved relocation record.
552 * @param sym The unresolved relocation's referenced symbol.
553 * @retval true The object file record was relocated.
554 * @retval false The relocation failed. The RTL error is set.
555 */
556bool rtems_rtl_obj_relocate_unresolved (rtems_rtl_unresolv_reloc* reloc,
557                                        rtems_rtl_obj_sym*        sym);
558
559/**
560 * Load the symbols from the object file. Only the exported or public symbols
561 * are read into memory and held in the global symbol table.
562 *
563 * @param obj The object file's descriptor.
564 * @param fd The object file's file descriptor.
565 * @param handler The object file's format specific symbol handler.
566 * @param data User specific data handle.
567 * @retval true The object file's symbol where loaded.
568 * @retval false The symbol loading failed. The RTL error is set.
569 */
570bool rtems_rtl_obj_load_symbols (rtems_rtl_obj*             obj,
571                                 int                        fd,
572                                 rtems_rtl_obj_sect_handler handler,
573                                 void*                      data);
574
575/**
576 * Load the sections that have been allocated memory in the target. The bss
577 * type section does not load any data, it is set to 0. The text and data
578 * sections read the detault data from the object file into the target memory.
579 *
580 * @param obj The object file's descriptor.
581 * @param fd The object file's file descriptor.
582 * @param handler The object file's format specific load handler.
583 * @param data User specific data handle.
584 * @retval true The object has been sucessfully loaded.
585 * @retval false The load failed. The RTL error has been set.
586 */
587bool rtems_rtl_obj_load_sections (rtems_rtl_obj*             obj,
588                                  int                        fd,
589                                  rtems_rtl_obj_sect_handler handler,
590                                  void*                      data);
591
592/**
593 * Invoke the constructors the object has. Constructors are a table of pointers
594 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
595 * taken from the section's size. The objet ELF specific code is responisble
596 * for flagging which sections contain constructors.
597 *
598 * @param obj The object file's descriptor.
599 */
600void rtems_rtl_obj_run_ctors (rtems_rtl_obj* obj);
601
602/**
603 * Invoke the destructors the object has. Destructors are a table of pointers
604 * to "void (*)(void);" where NULL pointers are skipped. The table's size is
605 * taken from the section's size. The objet ELF specific code is responisble
606 * for flagging which sections contain destructors.
607 *
608 * @param obj The object file's descriptor.
609 */
610void rtems_rtl_obj_run_dtors (rtems_rtl_obj* obj);
611
612/**
613 * Load the object file, reading all sections into memory, symbols and
614 * performing any relocation fixups.
615 *
616 * @param obj The object file's descriptor.
617 * @retval true The object file has been loaded.
618 * @retval false The load failed. The RTL error has been set.
619 */
620bool rtems_rtl_obj_load (rtems_rtl_obj* obj);
621
622/**
623 * Unload the object file, erasing all symbols and releasing all memory.
624 *
625 * @param obj The object file's descriptor.
626 * @retval true The object file has been unloaded.
627 * @retval false The unload failed. The RTL error has been set.
628 */
629bool rtems_rtl_obj_unload (rtems_rtl_obj* obj);
630
631#ifdef __cplusplus
632}
633#endif /* __cplusplus */
634
635#endif
Note: See TracBrowser for help on using the repository browser.