source: rtems/cpukit/include/rtems/rtl/rtl-unresolved.h @ 194eb403

Last change on this file since 194eb403 was 194eb403, checked in by Chris Johns <chrisj@…>, on Jan 21, 2019 at 9:48:19 PM

libdl: Add support for large memory programs

  • Add trampolines to support relocs that are out of range on support architectures.
  • Support not loading separate text/data sections in an object file if the symbol provided in the section is a duplicate. A base image may have pulled in part of an object and another part needs to be dynamically loaded.
  • Refactor the unresolved handling to scale to hundreds of unresolved symbols when loading large number of files.

Updates #3685

  • Property mode set to 100644
File size: 8.0 KB
Line 
1/*
2 *  COPYRIGHT (c) 2012, 2018 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 File Unresolved Relocations Table.
14 *
15 * The unresolved relocation table holds relocations in a loaded object file
16 * which reference unresolved external symbols. The support is needed to allow
17 * dependent object files to load. In the case of dependent object files one
18 * will have unresolved externals until the dependent object file is also
19 * loaded. There is no load order that resolves this.
20 *
21 * The unresolved relocation table is a single table used by all object files
22 * with unresolved symbols. It made of blocks linked together where blocks are
23 * allocated as requiered. The table is always maintained compacted. That is as
24 * relocations are resolved and removed the table is compacted. The only
25 * pointer in the table is the object file poniter. This is used to identify
26 * which object the relocation belongs to. There are no linking or back
27 * pointers in the unresolved relocations table. The table is scanned for each
28 * object file's relocations. This is not fast but the table should be small
29 * and if it happens to grow large you have other more pressing issues to
30 * resolve in your application.
31 *
32 * The table holds two (2) types of records:
33 *
34 *  # Symbol name strings.
35 *  # Relocations.
36 *
37 * The symbol name a relocation references is held in a specific symbol name
38 * string record in the table the relocation record references. The record
39 * counts the number of references and the string is removed from the table
40 * when the reference count reaches 0. There can be many relocations
41 * referencing the symbol. The strings are referenced by a single 16bit
42 * unsigned integer which is the count of the string in the table.
43 *
44 * The section the relocation is for in the object is the section number. The
45 * relocation data is series of machine word sized fields:
46 *
47 * # Offset in the section.
48 * # Relocation info (format specific)
49 * # Additional format specific data.
50 */
51
52#if !defined (_RTEMS_RTL_UNRESOLVED_H_)
53#define _RTEMS_RTL_UNRESOLVED_H_
54
55#include <rtems.h>
56#include <rtems/chain.h>
57#include "rtl-obj-fwd.h"
58
59#ifdef __cplusplus
60extern "C" {
61#endif /* __cplusplus */
62
63/**
64 * Hack to work around machine size. This needs to be cleaned up
65 * to better support 64bit targets.
66 */
67typedef uint32_t rtems_rtl_word;
68
69/**
70 * The types of records in the blocks.
71 */
72typedef enum rtems_rtl_unresolved_rtype
73{
74  rtems_rtl_unresolved_empty = 0,  /**< The records is empty. Must always be 0 */
75  rtems_rtl_unresolved_symbol = 1, /**< The record is a symbol. */
76  rtems_rtl_unresolved_reloc = 2   /**< The record is a relocation record. */
77} rtems_rtl_unresolved_rtype;
78
79/**
80 * Unresolved external symbol flags.
81 */
82#define RTEMS_RTL_UNRESOLV_SYM_SEARCH_ARCHIVE (1 << 0) /**< Search the archive. */
83#define RTEMS_RTL_UNRESOLV_SYM_HAS_ERROR      (1 << 1) /**< The symbol load
84                                                        *   has an error. */
85
86/**
87 * Unresolved externals symbols. The symbols are reference counted and separate
88 * from the relocation records because a number of records could reference the
89 * same symbol.
90 *
91 * The name is extended in the allocator of the record in the unresolved data
92 * block. The 10 is a minimum that is added to by joining more than one record.
93 */
94typedef struct rtems_rtl_unresolv_symbol
95{
96  uint16_t   refs;     /**< The number of references to this name. */
97  uint16_t   flags;    /**< Flags to manage the symbol. */
98  uint16_t   length;   /**< The length of this name. */
99  const char name[];   /**< The symbol name. */
100} rtems_rtl_unresolv_symbol;
101
102/**
103 * Unresolved externals symbols require the relocation records to be held
104 * and references.
105 */
106typedef struct rtems_rtl_unresolv_reloc
107{
108  rtems_rtl_obj* obj;     /**< The relocation's object file. */
109  uint16_t       flags;   /**< Format specific flags. */
110  uint16_t       name;    /**< The symbol's name. */
111  uint16_t       sect;    /**< The target section. */
112  rtems_rtl_word rel[3];  /**< Relocation record. */
113} rtems_rtl_unresolv_reloc;
114
115/**
116 * Unresolved externals records.
117 */
118typedef struct rtems_rtl_unresolv_rec
119{
120  rtems_rtl_unresolved_rtype type;
121  union
122  {
123    rtems_rtl_unresolv_symbol name;   /**< The symbol, or */
124    rtems_rtl_unresolv_reloc  reloc;  /**< the relocation record. */
125  } rec;
126} rtems_rtl_unresolv_rec;
127
128/**
129 * Unresolved blocks.
130 */
131typedef struct rtems_rtl_unresolv_block
132{
133  rtems_chain_node       link;  /**< Blocks are chained. */
134  uint32_t               recs;  /**< The number of records in the block. */
135  rtems_rtl_unresolv_rec rec[]; /**< The records. More follow. */
136} rtems_rtl_unresolv_block;
137
138/**
139 * Unresolved table holds the names and relocations.
140 */
141typedef struct rtems_rtl_unresolved
142{
143  uint32_t            marker;     /**< Block marker. */
144  size_t              block_recs; /**< The records per blocks allocated. */
145  rtems_chain_control blocks;     /**< List of blocks. */
146} rtems_rtl_unresolved;
147
148/**
149 * The iterator function used to iterate over the unresolved table.
150 *
151 * @param rec The current iterator.
152 * @param data The user data.
153 * @retval true The iterator has finished.
154 * @retval false The iterator has not finished. Keep iterating.
155 */
156typedef bool rtems_rtl_unresolved_iterator (rtems_rtl_unresolv_rec* rec,
157                                            void*                   data);
158
159/**
160 * Open an unresolved relocation table.
161 *
162 * @param unresolv The unresolved table to open.
163 * @param block_records The number of records per block allocated.
164 * @retval true The table is open.
165 * @retval false The unresolved relocation table could not created. The RTL
166 *               error has the error.
167 */
168bool rtems_rtl_unresolved_table_open (rtems_rtl_unresolved* unresolved,
169                                      size_t                block_records);
170
171/**
172 * Close the table and erase the blocks.
173 *
174 * @param unreolved Close the unresolved table.
175 */
176void rtems_rtl_unresolved_table_close (rtems_rtl_unresolved* unresolved);
177
178/**
179 * Iterate over the table of unresolved entries.
180 */
181bool rtems_rtl_unresolved_iterate (rtems_rtl_unresolved_iterator iterator,
182                                   void*                         data);
183
184/**
185 * Add a relocation to the list of unresolved relocations.
186 *
187 * @param unresolved The unresolved symbol table.
188 * @param obj The object table the symbols are for.
189 * @param flags Format specific flags.
190 * @param name The symbol name the relocation references.
191 * @param sect The target section number the relocation references.
192 * @param rel The format specific relocation data.
193 * @retval true The relocation has been added.
194 * @retval false The relocation could not be added.
195 */
196bool rtems_rtl_unresolved_add (rtems_rtl_obj*        obj,
197                               const uint16_t        flags,
198                               const char*           name,
199                               const uint16_t        sect,
200                               const rtems_rtl_word* rel);
201
202/**
203 * Resolve the unresolved symbols.
204 */
205void rtems_rtl_unresolved_resolve (void);
206
207/**
208 * Remove a relocation from the list of unresolved relocations.
209 *
210 * @param unresolved The unresolved symbol table.
211 * @param obj The object table the symbols are for.
212 * @param esyms The exported symbol table.
213 * @param size The size of the table in bytes.
214 */
215bool rtems_rtl_unresolved_remove (rtems_rtl_obj*        obj,
216                                  const char*           name,
217                                  const uint16_t        sect,
218                                  const rtems_rtl_word* rel);
219
220/**
221 * Set all symbols to be archive searchable. This is done when the available
222 * archives have been refreshed and there are new archives to search for.
223 */
224void rtems_rtl_unresolved_set_archive_search (void);
225
226/**
227 * Dump the RTL unresolved data.
228 */
229void rtems_rtl_unresolved_dump (void);
230
231#ifdef __cplusplus
232}
233#endif /* __cplusplus */
234
235#endif
Note: See TracBrowser for help on using the repository browser.