Merge branch 'vendor/GCC44'
[dragonfly.git] / contrib / binutils-2.22 / include / plugin-api.h
1 /* plugin-api.h -- External linker plugin API.  */
2
3 /* Copyright 2009, 2010 Free Software Foundation, Inc.
4    Written by Cary Coutant <ccoutant@google.com>.
5
6    This file is part of binutils.
7
8    This program is free software; you can redistribute it and/or modify
9    it under the terms of the GNU General Public License as published by
10    the Free Software Foundation; either version 3 of the License, or
11    (at your option) any later version.
12
13    This program is distributed in the hope that it will be useful,
14    but WITHOUT ANY WARRANTY; without even the implied warranty of
15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16    GNU General Public License for more details.
17
18    You should have received a copy of the GNU General Public License
19    along with this program; if not, write to the Free Software
20    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
21    MA 02110-1301, USA.  */
22
23 /* This file defines the interface for writing a linker plugin, which is
24    described at < http://gcc.gnu.org/wiki/whopr/driver >.  */
25
26 #ifndef PLUGIN_API_H
27 #define PLUGIN_API_H
28
29 #ifdef HAVE_STDINT_H
30 #include <stdint.h>
31 #elif defined(HAVE_INTTYPES_H)
32 #include <inttypes.h>
33 #endif
34 #include <sys/types.h>
35 #if !defined(HAVE_STDINT_H) && !defined(HAVE_INTTYPES_H) && \
36     !defined(UINT64_MAX) && !defined(uint64_t)
37 #error can not find uint64_t type
38 #endif
39
40 #ifdef __cplusplus
41 extern "C"
42 {
43 #endif
44
45 /* Status code returned by most API routines.  */
46
47 enum ld_plugin_status
48 {
49   LDPS_OK = 0,
50   LDPS_NO_SYMS,         /* Attempt to get symbols that haven't been added. */
51   LDPS_BAD_HANDLE,      /* No claimed object associated with given handle. */
52   LDPS_ERR
53   /* Additional Error codes TBD.  */
54 };
55
56 /* The version of the API specification.  */
57
58 enum ld_plugin_api_version
59 {
60   LD_PLUGIN_API_VERSION = 1
61 };
62
63 /* The type of output file being generated by the linker.  */
64
65 enum ld_plugin_output_file_type
66 {
67   LDPO_REL,
68   LDPO_EXEC,
69   LDPO_DYN
70 };
71
72 /* An input file managed by the plugin library.  */
73
74 struct ld_plugin_input_file
75 {
76   const char *name;
77   int fd;
78   off_t offset;
79   off_t filesize;
80   void *handle;
81 };
82
83 /* A symbol belonging to an input file managed by the plugin library.  */
84
85 struct ld_plugin_symbol
86 {
87   char *name;
88   char *version;
89   int def;
90   int visibility;
91   uint64_t size;
92   char *comdat_key;
93   int resolution;
94 };
95
96 /* An object's section.  */
97
98 struct ld_plugin_section
99 {
100   const void* handle;
101   unsigned int shndx;
102 };
103
104 /* Whether the symbol is a definition, reference, or common, weak or not.  */
105
106 enum ld_plugin_symbol_kind
107 {
108   LDPK_DEF,
109   LDPK_WEAKDEF,
110   LDPK_UNDEF,
111   LDPK_WEAKUNDEF,
112   LDPK_COMMON
113 };
114
115 /* The visibility of the symbol.  */
116
117 enum ld_plugin_symbol_visibility
118 {
119   LDPV_DEFAULT,
120   LDPV_PROTECTED,
121   LDPV_INTERNAL,
122   LDPV_HIDDEN
123 };
124
125 /* How a symbol is resolved.  */
126
127 enum ld_plugin_symbol_resolution
128 {
129   LDPR_UNKNOWN = 0,
130
131   /* Symbol is still undefined at this point.  */
132   LDPR_UNDEF,
133
134   /* This is the prevailing definition of the symbol, with references from
135      regular object code.  */
136   LDPR_PREVAILING_DEF,
137
138   /* This is the prevailing definition of the symbol, with no
139      references from regular objects.  It is only referenced from IR
140      code.  */
141   LDPR_PREVAILING_DEF_IRONLY,
142
143   /* This definition was pre-empted by a definition in a regular
144      object file.  */
145   LDPR_PREEMPTED_REG,
146
147   /* This definition was pre-empted by a definition in another IR file.  */
148   LDPR_PREEMPTED_IR,
149
150   /* This symbol was resolved by a definition in another IR file.  */
151   LDPR_RESOLVED_IR,
152
153   /* This symbol was resolved by a definition in a regular object
154      linked into the main executable.  */
155   LDPR_RESOLVED_EXEC,
156
157   /* This symbol was resolved by a definition in a shared object.  */
158   LDPR_RESOLVED_DYN,
159
160   /* This is the prevailing definition of the symbol, with no
161      references from regular objects.  It is only referenced from IR
162      code, but the symbol is exported and may be referenced from
163      a dynamic object (not seen at link time).  */
164   LDPR_PREVAILING_DEF_IRONLY_EXP
165 };
166
167 /* The plugin library's "claim file" handler.  */
168
169 typedef
170 enum ld_plugin_status
171 (*ld_plugin_claim_file_handler) (
172   const struct ld_plugin_input_file *file, int *claimed);
173
174 /* The plugin library's "all symbols read" handler.  */
175
176 typedef
177 enum ld_plugin_status
178 (*ld_plugin_all_symbols_read_handler) (void);
179
180 /* The plugin library's cleanup handler.  */
181
182 typedef
183 enum ld_plugin_status
184 (*ld_plugin_cleanup_handler) (void);
185
186 /* The linker's interface for registering the "claim file" handler.  */
187
188 typedef
189 enum ld_plugin_status
190 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
191
192 /* The linker's interface for registering the "all symbols read" handler.  */
193
194 typedef
195 enum ld_plugin_status
196 (*ld_plugin_register_all_symbols_read) (
197   ld_plugin_all_symbols_read_handler handler);
198
199 /* The linker's interface for registering the cleanup handler.  */
200
201 typedef
202 enum ld_plugin_status
203 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
204
205 /* The linker's interface for adding symbols from a claimed input file.  */
206
207 typedef
208 enum ld_plugin_status
209 (*ld_plugin_add_symbols) (void *handle, int nsyms,
210                           const struct ld_plugin_symbol *syms);
211
212 /* The linker's interface for getting the input file information with
213    an open (possibly re-opened) file descriptor.  */
214
215 typedef
216 enum ld_plugin_status
217 (*ld_plugin_get_input_file) (const void *handle,
218                              struct ld_plugin_input_file *file);
219
220 typedef
221 enum ld_plugin_status
222 (*ld_plugin_get_view) (const void *handle, const void **viewp);
223
224 /* The linker's interface for releasing the input file.  */
225
226 typedef
227 enum ld_plugin_status
228 (*ld_plugin_release_input_file) (const void *handle);
229
230 /* The linker's interface for retrieving symbol resolution information.  */
231
232 typedef
233 enum ld_plugin_status
234 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
235                           struct ld_plugin_symbol *syms);
236
237 /* The linker's interface for adding a compiled input file.  */
238
239 typedef
240 enum ld_plugin_status
241 (*ld_plugin_add_input_file) (const char *pathname);
242
243 /* The linker's interface for adding a library that should be searched.  */
244
245 typedef
246 enum ld_plugin_status
247 (*ld_plugin_add_input_library) (const char *libname);
248
249 /* The linker's interface for adding a library path that should be searched.  */
250
251 typedef
252 enum ld_plugin_status
253 (*ld_plugin_set_extra_library_path) (const char *path);
254
255 /* The linker's interface for issuing a warning or error message.  */
256
257 typedef
258 enum ld_plugin_status
259 (*ld_plugin_message) (int level, const char *format, ...);
260
261 /* The linker's interface for retrieving the number of sections in an object.
262    The handle is obtained in the claim_file handler.  This interface should
263    only be invoked in the claim_file handler.   This function sets *COUNT to
264    the number of sections in the object.  */
265
266 typedef
267 enum ld_plugin_status
268 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
269
270 /* The linker's interface for retrieving the section type of a specific
271    section in an object.  This interface should only be invoked in the
272    claim_file handler.  This function sets *TYPE to an ELF SHT_xxx value.  */
273
274 typedef
275 enum ld_plugin_status
276 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
277                                      unsigned int *type);
278
279 /* The linker's interface for retrieving the name of a specific section in
280    an object. This interface should only be invoked in the claim_file handler.
281    This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
282    by malloc.  The plugin must free *SECTION_NAME_PTR.  */
283
284 typedef
285 enum ld_plugin_status
286 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
287                                      char **section_name_ptr);
288
289 /* The linker's interface for retrieving the contents of a specific section
290    in an object.  This interface should only be invoked in the claim_file
291    handler.  This function sets *SECTION_CONTENTS to point to a buffer that is
292    valid until clam_file handler returns.  It sets *LEN to the size of the
293    buffer.  */
294
295 typedef
296 enum ld_plugin_status
297 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
298                                          const unsigned char **section_contents,
299                                          size_t* len);
300
301 /* The linker's interface for specifying the desired order of sections.
302    The sections should be specifed using the array SECTION_LIST in the
303    order in which they should appear in the final layout.  NUM_SECTIONS
304    specifies the number of entries in each array.  This should be invoked
305    in the all_symbols_read handler.  */
306
307 typedef
308 enum ld_plugin_status
309 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
310                                    unsigned int num_sections);
311
312 /* The linker's interface for specifying that reordering of sections is
313    desired so that the linker can prepare for it.  This should be invoked
314    before update_section_order, preferably in the claim_file handler.  */
315
316 typedef
317 enum ld_plugin_status
318 (*ld_plugin_allow_section_ordering) (void);
319
320 enum ld_plugin_level
321 {
322   LDPL_INFO,
323   LDPL_WARNING,
324   LDPL_ERROR,
325   LDPL_FATAL
326 };
327
328 /* Values for the tv_tag field of the transfer vector.  */
329
330 enum ld_plugin_tag
331 {
332   LDPT_NULL = 0,
333   LDPT_API_VERSION,
334   LDPT_GOLD_VERSION,
335   LDPT_LINKER_OUTPUT,
336   LDPT_OPTION,
337   LDPT_REGISTER_CLAIM_FILE_HOOK,
338   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
339   LDPT_REGISTER_CLEANUP_HOOK,
340   LDPT_ADD_SYMBOLS,
341   LDPT_GET_SYMBOLS,
342   LDPT_ADD_INPUT_FILE,
343   LDPT_MESSAGE,
344   LDPT_GET_INPUT_FILE,
345   LDPT_RELEASE_INPUT_FILE,
346   LDPT_ADD_INPUT_LIBRARY,
347   LDPT_OUTPUT_NAME,
348   LDPT_SET_EXTRA_LIBRARY_PATH,
349   LDPT_GNU_LD_VERSION,
350   LDPT_GET_VIEW,
351   LDPT_GET_INPUT_SECTION_COUNT,
352   LDPT_GET_INPUT_SECTION_TYPE,
353   LDPT_GET_INPUT_SECTION_NAME,
354   LDPT_GET_INPUT_SECTION_CONTENTS,
355   LDPT_UPDATE_SECTION_ORDER,
356   LDPT_ALLOW_SECTION_ORDERING,
357   LDPT_GET_SYMBOLS_V2
358 };
359
360 /* The plugin transfer vector.  */
361
362 struct ld_plugin_tv
363 {
364   enum ld_plugin_tag tv_tag;
365   union
366   {
367     int tv_val;
368     const char *tv_string;
369     ld_plugin_register_claim_file tv_register_claim_file;
370     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
371     ld_plugin_register_cleanup tv_register_cleanup;
372     ld_plugin_add_symbols tv_add_symbols;
373     ld_plugin_get_symbols tv_get_symbols;
374     ld_plugin_add_input_file tv_add_input_file;
375     ld_plugin_message tv_message;
376     ld_plugin_get_input_file tv_get_input_file;
377     ld_plugin_get_view tv_get_view;
378     ld_plugin_release_input_file tv_release_input_file;
379     ld_plugin_add_input_library tv_add_input_library;
380     ld_plugin_set_extra_library_path tv_set_extra_library_path;
381     ld_plugin_get_input_section_count tv_get_input_section_count;
382     ld_plugin_get_input_section_type tv_get_input_section_type;
383     ld_plugin_get_input_section_name tv_get_input_section_name;
384     ld_plugin_get_input_section_contents tv_get_input_section_contents;
385     ld_plugin_update_section_order tv_update_section_order;
386     ld_plugin_allow_section_ordering tv_allow_section_ordering;
387   } tv_u;
388 };
389
390 /* The plugin library's "onload" entry point.  */
391
392 typedef
393 enum ld_plugin_status
394 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
395
396 #ifdef __cplusplus
397 }
398 #endif
399
400 #endif /* !defined(PLUGIN_API_H) */