Daily bump.
[official-gcc.git] / include / plugin-api.h
blob03e21f4a0c445e881918a71c07b538e3a3fa1bd2
1 /* plugin-api.h -- External linker plugin API. */
3 /* Copyright (C) 2009-2018 Free Software Foundation, Inc.
4 Written by Cary Coutant <ccoutant@google.com>.
6 This file is part of binutils.
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.
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.
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. */
23 /* This file defines the interface for writing a linker plugin, which is
24 described at < http://gcc.gnu.org/wiki/whopr/driver >. */
26 #ifndef PLUGIN_API_H
27 #define PLUGIN_API_H
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
40 #ifdef __cplusplus
41 extern "C"
43 #endif
45 /* Status code returned by most API routines. */
47 enum ld_plugin_status
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. */
56 /* The version of the API specification. */
58 enum ld_plugin_api_version
60 LD_PLUGIN_API_VERSION = 1
63 /* The type of output file being generated by the linker. */
65 enum ld_plugin_output_file_type
67 LDPO_REL,
68 LDPO_EXEC,
69 LDPO_DYN,
70 LDPO_PIE
73 /* An input file managed by the plugin library. */
75 struct ld_plugin_input_file
77 const char *name;
78 int fd;
79 off_t offset;
80 off_t filesize;
81 void *handle;
84 /* A symbol belonging to an input file managed by the plugin library. */
86 struct ld_plugin_symbol
88 char *name;
89 char *version;
90 int def;
91 int visibility;
92 uint64_t size;
93 char *comdat_key;
94 int resolution;
97 /* An object's section. */
99 struct ld_plugin_section
101 const void* handle;
102 unsigned int shndx;
105 /* Whether the symbol is a definition, reference, or common, weak or not. */
107 enum ld_plugin_symbol_kind
109 LDPK_DEF,
110 LDPK_WEAKDEF,
111 LDPK_UNDEF,
112 LDPK_WEAKUNDEF,
113 LDPK_COMMON
116 /* The visibility of the symbol. */
118 enum ld_plugin_symbol_visibility
120 LDPV_DEFAULT,
121 LDPV_PROTECTED,
122 LDPV_INTERNAL,
123 LDPV_HIDDEN
126 /* How a symbol is resolved. */
128 enum ld_plugin_symbol_resolution
130 LDPR_UNKNOWN = 0,
132 /* Symbol is still undefined at this point. */
133 LDPR_UNDEF,
135 /* This is the prevailing definition of the symbol, with references from
136 regular object code. */
137 LDPR_PREVAILING_DEF,
139 /* This is the prevailing definition of the symbol, with no
140 references from regular objects. It is only referenced from IR
141 code. */
142 LDPR_PREVAILING_DEF_IRONLY,
144 /* This definition was pre-empted by a definition in a regular
145 object file. */
146 LDPR_PREEMPTED_REG,
148 /* This definition was pre-empted by a definition in another IR file. */
149 LDPR_PREEMPTED_IR,
151 /* This symbol was resolved by a definition in another IR file. */
152 LDPR_RESOLVED_IR,
154 /* This symbol was resolved by a definition in a regular object
155 linked into the main executable. */
156 LDPR_RESOLVED_EXEC,
158 /* This symbol was resolved by a definition in a shared object. */
159 LDPR_RESOLVED_DYN,
161 /* This is the prevailing definition of the symbol, with no
162 references from regular objects. It is only referenced from IR
163 code, but the symbol is exported and may be referenced from
164 a dynamic object (not seen at link time). */
165 LDPR_PREVAILING_DEF_IRONLY_EXP
168 /* The plugin library's "claim file" handler. */
170 typedef
171 enum ld_plugin_status
172 (*ld_plugin_claim_file_handler) (
173 const struct ld_plugin_input_file *file, int *claimed);
175 /* The plugin library's "all symbols read" handler. */
177 typedef
178 enum ld_plugin_status
179 (*ld_plugin_all_symbols_read_handler) (void);
181 /* The plugin library's cleanup handler. */
183 typedef
184 enum ld_plugin_status
185 (*ld_plugin_cleanup_handler) (void);
187 /* The linker's interface for registering the "claim file" handler. */
189 typedef
190 enum ld_plugin_status
191 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
193 /* The linker's interface for registering the "all symbols read" handler. */
195 typedef
196 enum ld_plugin_status
197 (*ld_plugin_register_all_symbols_read) (
198 ld_plugin_all_symbols_read_handler handler);
200 /* The linker's interface for registering the cleanup handler. */
202 typedef
203 enum ld_plugin_status
204 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
206 /* The linker's interface for adding symbols from a claimed input file. */
208 typedef
209 enum ld_plugin_status
210 (*ld_plugin_add_symbols) (void *handle, int nsyms,
211 const struct ld_plugin_symbol *syms);
213 /* The linker's interface for getting the input file information with
214 an open (possibly re-opened) file descriptor. */
216 typedef
217 enum ld_plugin_status
218 (*ld_plugin_get_input_file) (const void *handle,
219 struct ld_plugin_input_file *file);
221 typedef
222 enum ld_plugin_status
223 (*ld_plugin_get_view) (const void *handle, const void **viewp);
225 /* The linker's interface for releasing the input file. */
227 typedef
228 enum ld_plugin_status
229 (*ld_plugin_release_input_file) (const void *handle);
231 /* The linker's interface for retrieving symbol resolution information. */
233 typedef
234 enum ld_plugin_status
235 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
236 struct ld_plugin_symbol *syms);
238 /* The linker's interface for adding a compiled input file. */
240 typedef
241 enum ld_plugin_status
242 (*ld_plugin_add_input_file) (const char *pathname);
244 /* The linker's interface for adding a library that should be searched. */
246 typedef
247 enum ld_plugin_status
248 (*ld_plugin_add_input_library) (const char *libname);
250 /* The linker's interface for adding a library path that should be searched. */
252 typedef
253 enum ld_plugin_status
254 (*ld_plugin_set_extra_library_path) (const char *path);
256 /* The linker's interface for issuing a warning or error message. */
258 typedef
259 enum ld_plugin_status
260 (*ld_plugin_message) (int level, const char *format, ...);
262 /* The linker's interface for retrieving the number of sections in an object.
263 The handle is obtained in the claim_file handler. This interface should
264 only be invoked in the claim_file handler. This function sets *COUNT to
265 the number of sections in the object. */
267 typedef
268 enum ld_plugin_status
269 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
271 /* The linker's interface for retrieving the section type of a specific
272 section in an object. This interface should only be invoked in the
273 claim_file handler. This function sets *TYPE to an ELF SHT_xxx value. */
275 typedef
276 enum ld_plugin_status
277 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
278 unsigned int *type);
280 /* The linker's interface for retrieving the name of a specific section in
281 an object. This interface should only be invoked in the claim_file handler.
282 This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
283 by malloc. The plugin must free *SECTION_NAME_PTR. */
285 typedef
286 enum ld_plugin_status
287 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
288 char **section_name_ptr);
290 /* The linker's interface for retrieving the contents of a specific section
291 in an object. This interface should only be invoked in the claim_file
292 handler. This function sets *SECTION_CONTENTS to point to a buffer that is
293 valid until clam_file handler returns. It sets *LEN to the size of the
294 buffer. */
296 typedef
297 enum ld_plugin_status
298 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
299 const unsigned char **section_contents,
300 size_t* len);
302 /* The linker's interface for specifying the desired order of sections.
303 The sections should be specifed using the array SECTION_LIST in the
304 order in which they should appear in the final layout. NUM_SECTIONS
305 specifies the number of entries in each array. This should be invoked
306 in the all_symbols_read handler. */
308 typedef
309 enum ld_plugin_status
310 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
311 unsigned int num_sections);
313 /* The linker's interface for specifying that reordering of sections is
314 desired so that the linker can prepare for it. This should be invoked
315 before update_section_order, preferably in the claim_file handler. */
317 typedef
318 enum ld_plugin_status
319 (*ld_plugin_allow_section_ordering) (void);
321 /* The linker's interface for specifying that a subset of sections is
322 to be mapped to a unique segment. If the plugin wants to call
323 unique_segment_for_sections, it must call this function from a
324 claim_file_handler or when it is first loaded. */
326 typedef
327 enum ld_plugin_status
328 (*ld_plugin_allow_unique_segment_for_sections) (void);
330 /* The linker's interface for specifying that a specific set of sections
331 must be mapped to a unique segment. ELF segments do not have names
332 and the NAME is used as the name of the newly created output section
333 that is then placed in the unique PT_LOAD segment. FLAGS is used to
334 specify if any additional segment flags need to be set. For instance,
335 a specific segment flag can be set to identify this segment. Unsetting
336 segment flags that would be set by default is not possible. The
337 parameter SEGMENT_ALIGNMENT when non-zero will override the default. */
339 typedef
340 enum ld_plugin_status
341 (*ld_plugin_unique_segment_for_sections) (
342 const char* segment_name,
343 uint64_t segment_flags,
344 uint64_t segment_alignment,
345 const struct ld_plugin_section * section_list,
346 unsigned int num_sections);
348 /* The linker's interface for retrieving the section alignment requirement
349 of a specific section in an object. This interface should only be invoked in the
350 claim_file handler. This function sets *ADDRALIGN to the ELF sh_addralign
351 value of the input section. */
353 typedef
354 enum ld_plugin_status
355 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section,
356 unsigned int *addralign);
358 /* The linker's interface for retrieving the section size of a specific section
359 in an object. This interface should only be invoked in the claim_file handler.
360 This function sets *SECSIZE to the ELF sh_size
361 value of the input section. */
363 typedef
364 enum ld_plugin_status
365 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
366 uint64_t *secsize);
368 typedef
369 enum ld_plugin_status
370 (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file);
372 /* The linker's interface for registering the "new_input" handler. This handler
373 will be notified when a new input file has been added after the
374 all_symbols_read event, allowing the plugin to, for example, set a unique
375 segment for sections in plugin-generated input files. */
377 typedef
378 enum ld_plugin_status
379 (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler);
382 enum ld_plugin_level
384 LDPL_INFO,
385 LDPL_WARNING,
386 LDPL_ERROR,
387 LDPL_FATAL
390 /* Values for the tv_tag field of the transfer vector. */
392 enum ld_plugin_tag
394 LDPT_NULL = 0,
395 LDPT_API_VERSION = 1,
396 LDPT_GOLD_VERSION = 2,
397 LDPT_LINKER_OUTPUT = 3,
398 LDPT_OPTION = 4,
399 LDPT_REGISTER_CLAIM_FILE_HOOK = 5,
400 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6,
401 LDPT_REGISTER_CLEANUP_HOOK = 7,
402 LDPT_ADD_SYMBOLS = 8,
403 LDPT_GET_SYMBOLS = 9,
404 LDPT_ADD_INPUT_FILE = 10,
405 LDPT_MESSAGE = 11,
406 LDPT_GET_INPUT_FILE = 12,
407 LDPT_RELEASE_INPUT_FILE = 13,
408 LDPT_ADD_INPUT_LIBRARY = 14,
409 LDPT_OUTPUT_NAME = 15,
410 LDPT_SET_EXTRA_LIBRARY_PATH = 16,
411 LDPT_GNU_LD_VERSION = 17,
412 LDPT_GET_VIEW = 18,
413 LDPT_GET_INPUT_SECTION_COUNT = 19,
414 LDPT_GET_INPUT_SECTION_TYPE = 20,
415 LDPT_GET_INPUT_SECTION_NAME = 21,
416 LDPT_GET_INPUT_SECTION_CONTENTS = 22,
417 LDPT_UPDATE_SECTION_ORDER = 23,
418 LDPT_ALLOW_SECTION_ORDERING = 24,
419 LDPT_GET_SYMBOLS_V2 = 25,
420 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26,
421 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27,
422 LDPT_GET_SYMBOLS_V3 = 28,
423 LDPT_GET_INPUT_SECTION_ALIGNMENT = 29,
424 LDPT_GET_INPUT_SECTION_SIZE = 30,
425 LDPT_REGISTER_NEW_INPUT_HOOK = 31
428 /* The plugin transfer vector. */
430 struct ld_plugin_tv
432 enum ld_plugin_tag tv_tag;
433 union
435 int tv_val;
436 const char *tv_string;
437 ld_plugin_register_claim_file tv_register_claim_file;
438 ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
439 ld_plugin_register_cleanup tv_register_cleanup;
440 ld_plugin_add_symbols tv_add_symbols;
441 ld_plugin_get_symbols tv_get_symbols;
442 ld_plugin_add_input_file tv_add_input_file;
443 ld_plugin_message tv_message;
444 ld_plugin_get_input_file tv_get_input_file;
445 ld_plugin_get_view tv_get_view;
446 ld_plugin_release_input_file tv_release_input_file;
447 ld_plugin_add_input_library tv_add_input_library;
448 ld_plugin_set_extra_library_path tv_set_extra_library_path;
449 ld_plugin_get_input_section_count tv_get_input_section_count;
450 ld_plugin_get_input_section_type tv_get_input_section_type;
451 ld_plugin_get_input_section_name tv_get_input_section_name;
452 ld_plugin_get_input_section_contents tv_get_input_section_contents;
453 ld_plugin_update_section_order tv_update_section_order;
454 ld_plugin_allow_section_ordering tv_allow_section_ordering;
455 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections;
456 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections;
457 ld_plugin_get_input_section_alignment tv_get_input_section_alignment;
458 ld_plugin_get_input_section_size tv_get_input_section_size;
459 ld_plugin_register_new_input tv_register_new_input;
460 } tv_u;
463 /* The plugin library's "onload" entry point. */
465 typedef
466 enum ld_plugin_status
467 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
469 #ifdef __cplusplus
471 #endif
473 #endif /* !defined(PLUGIN_API_H) */