gcc.c-torture/execute/builtins/pr93262-chk.c: Remove return statement
[official-gcc.git] / include / plugin-api.h
blobf3cf2d8101bf254c6427bbd10d5399abb193670f
1 /* plugin-api.h -- External linker plugin API. */
3 /* Copyright (C) 2009-2023 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 cannot find uint64_t type
38 #endif
40 /* Detect endianess based on gcc's (>=4.6.0) __BYTE_ORDER__ macro. */
41 #if defined(__BYTE_ORDER__) && defined(__ORDER_BIG_ENDIAN__) && \
42 defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_PDP_ENDIAN__)
43 #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
44 #define PLUGIN_LITTLE_ENDIAN 1
45 #elif __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
46 #define PLUGIN_BIG_ENDIAN 1
47 #elif __BYTE_ORDER__ == __ORDER_PDP_ENDIAN__
48 #define PLUGIN_PDP_ENDIAN 1
49 #endif
51 #else
52 /* Include header files to define endian macros. */
53 #if defined(__GLIBC__) || defined(__GNU_LIBRARY__) || defined(__ANDROID__)
54 #include <endian.h>
56 #elif defined(__SVR4) && defined(__sun)
57 #include <sys/byteorder.h>
59 #elif defined(__FreeBSD__) || defined(__NetBSD__) || \
60 defined(__DragonFly__) || defined(__minix)
61 #include <sys/endian.h>
63 #elif defined(__OpenBSD__)
64 #include <machine/endian.h>
65 #endif
67 /* Detect endianess based on __BYTE_ORDER. */
68 #ifdef __BYTE_ORDER
69 #if __BYTE_ORDER == __LITTLE_ENDIAN
70 #define PLUGIN_LITTLE_ENDIAN 1
71 #elif __BYTE_ORDER == __BIG_ENDIAN
72 #define PLUGIN_BIG_ENDIAN 1
73 #endif
75 /* Detect endianess based on _BYTE_ORDER. */
76 #elif defined _BYTE_ORDER
77 #if _BYTE_ORDER == _LITTLE_ENDIAN
78 #define PLUGIN_LITTLE_ENDIAN 1
79 #elif _BYTE_ORDER == _BIG_ENDIAN
80 #define PLUGIN_BIG_ENDIAN 1
81 #endif
83 /* Detect based on _WIN32. */
84 #elif defined _WIN32
85 #define PLUGIN_LITTLE_ENDIAN 1
87 /* Detect based on __BIG_ENDIAN__ and __LITTLE_ENDIAN__ */
88 #elif defined __LITTLE_ENDIAN__ || defined _LITTLE_ENDIAN
89 #define PLUGIN_LITTLE_ENDIAN 1
90 #elif defined __BIG_ENDIAN__ || defined _BIG_ENDIAN
91 #define PLUGIN_BIG_ENDIAN 1
92 #endif
93 #endif
95 #ifdef __cplusplus
96 extern "C"
98 #endif
100 /* Status code returned by most API routines. */
102 enum ld_plugin_status
104 LDPS_OK = 0,
105 LDPS_NO_SYMS, /* Attempt to get symbols that haven't been added. */
106 LDPS_BAD_HANDLE, /* No claimed object associated with given handle. */
107 LDPS_ERR
108 /* Additional Error codes TBD. */
111 /* The version of the API specification. */
113 enum ld_plugin_api_version
115 LD_PLUGIN_API_VERSION = 1
118 /* The type of output file being generated by the linker. */
120 enum ld_plugin_output_file_type
122 LDPO_REL,
123 LDPO_EXEC,
124 LDPO_DYN,
125 LDPO_PIE
128 /* An input file managed by the plugin library. */
130 struct ld_plugin_input_file
132 const char *name;
133 int fd;
134 off_t offset;
135 off_t filesize;
136 void *handle;
139 /* A symbol belonging to an input file managed by the plugin library. */
141 struct ld_plugin_symbol
143 char *name;
144 char *version;
145 /* This is for compatibility with older ABIs. The older ABI defined
146 only 'def' field. */
147 #if PLUGIN_BIG_ENDIAN == 1
148 char unused;
149 char section_kind;
150 char symbol_type;
151 char def;
152 #elif PLUGIN_LITTLE_ENDIAN == 1
153 char def;
154 char symbol_type;
155 char section_kind;
156 char unused;
157 #elif PLUGIN_PDP_ENDIAN == 1
158 char symbol_type;
159 char def;
160 char unused;
161 char section_kind;
162 #else
163 #error "Could not detect architecture endianess"
164 #endif
165 int visibility;
166 uint64_t size;
167 char *comdat_key;
168 int resolution;
171 /* An object's section. */
173 struct ld_plugin_section
175 const void* handle;
176 unsigned int shndx;
179 /* Whether the symbol is a definition, reference, or common, weak or not. */
181 enum ld_plugin_symbol_kind
183 LDPK_DEF,
184 LDPK_WEAKDEF,
185 LDPK_UNDEF,
186 LDPK_WEAKUNDEF,
187 LDPK_COMMON
190 /* The visibility of the symbol. */
192 enum ld_plugin_symbol_visibility
194 LDPV_DEFAULT,
195 LDPV_PROTECTED,
196 LDPV_INTERNAL,
197 LDPV_HIDDEN
200 /* The type of the symbol. */
202 enum ld_plugin_symbol_type
204 LDST_UNKNOWN,
205 LDST_FUNCTION,
206 LDST_VARIABLE
209 enum ld_plugin_symbol_section_kind
211 LDSSK_DEFAULT,
212 LDSSK_BSS
215 /* How a symbol is resolved. */
217 enum ld_plugin_symbol_resolution
219 LDPR_UNKNOWN = 0,
221 /* Symbol is still undefined at this point. */
222 LDPR_UNDEF,
224 /* This is the prevailing definition of the symbol, with references from
225 regular object code. */
226 LDPR_PREVAILING_DEF,
228 /* This is the prevailing definition of the symbol, with no
229 references from regular objects. It is only referenced from IR
230 code. */
231 LDPR_PREVAILING_DEF_IRONLY,
233 /* This definition was pre-empted by a definition in a regular
234 object file. */
235 LDPR_PREEMPTED_REG,
237 /* This definition was pre-empted by a definition in another IR file. */
238 LDPR_PREEMPTED_IR,
240 /* This symbol was resolved by a definition in another IR file. */
241 LDPR_RESOLVED_IR,
243 /* This symbol was resolved by a definition in a regular object
244 linked into the main executable. */
245 LDPR_RESOLVED_EXEC,
247 /* This symbol was resolved by a definition in a shared object. */
248 LDPR_RESOLVED_DYN,
250 /* This is the prevailing definition of the symbol, with no
251 references from regular objects. It is only referenced from IR
252 code, but the symbol is exported and may be referenced from
253 a dynamic object (not seen at link time). */
254 LDPR_PREVAILING_DEF_IRONLY_EXP
257 /* The plugin library's "claim file" handler. */
259 typedef
260 enum ld_plugin_status
261 (*ld_plugin_claim_file_handler) (
262 const struct ld_plugin_input_file *file, int *claimed);
264 /* The plugin library's "claim file" handler, version 2. */
266 typedef
267 enum ld_plugin_status
268 (*ld_plugin_claim_file_handler_v2) (
269 const struct ld_plugin_input_file *file, int *claimed, int known_used);
271 /* The plugin library's "all symbols read" handler. */
273 typedef
274 enum ld_plugin_status
275 (*ld_plugin_all_symbols_read_handler) (void);
277 /* The plugin library's cleanup handler. */
279 typedef
280 enum ld_plugin_status
281 (*ld_plugin_cleanup_handler) (void);
283 /* The linker's interface for registering the "claim file" handler. */
285 typedef
286 enum ld_plugin_status
287 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
289 /* The linker's interface for registering the "claim file" handler,
290 version 2. */
292 typedef
293 enum ld_plugin_status
294 (*ld_plugin_register_claim_file_v2) (ld_plugin_claim_file_handler_v2 handler);
296 /* The linker's interface for registering the "all symbols read" handler. */
298 typedef
299 enum ld_plugin_status
300 (*ld_plugin_register_all_symbols_read) (
301 ld_plugin_all_symbols_read_handler handler);
303 /* The linker's interface for registering the cleanup handler. */
305 typedef
306 enum ld_plugin_status
307 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
309 /* The linker's interface for adding symbols from a claimed input file. */
311 typedef
312 enum ld_plugin_status
313 (*ld_plugin_add_symbols) (void *handle, int nsyms,
314 const struct ld_plugin_symbol *syms);
316 /* The linker's interface for getting the input file information with
317 an open (possibly re-opened) file descriptor. */
319 typedef
320 enum ld_plugin_status
321 (*ld_plugin_get_input_file) (const void *handle,
322 struct ld_plugin_input_file *file);
324 typedef
325 enum ld_plugin_status
326 (*ld_plugin_get_view) (const void *handle, const void **viewp);
328 /* The linker's interface for releasing the input file. */
330 typedef
331 enum ld_plugin_status
332 (*ld_plugin_release_input_file) (const void *handle);
334 /* The linker's interface for retrieving symbol resolution information. */
336 typedef
337 enum ld_plugin_status
338 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
339 struct ld_plugin_symbol *syms);
341 /* The linker's interface for adding a compiled input file. */
343 typedef
344 enum ld_plugin_status
345 (*ld_plugin_add_input_file) (const char *pathname);
347 /* The linker's interface for adding a library that should be searched. */
349 typedef
350 enum ld_plugin_status
351 (*ld_plugin_add_input_library) (const char *libname);
353 /* The linker's interface for adding a library path that should be searched. */
355 typedef
356 enum ld_plugin_status
357 (*ld_plugin_set_extra_library_path) (const char *path);
359 /* The linker's interface for issuing a warning or error message. */
361 typedef
362 enum ld_plugin_status
363 (*ld_plugin_message) (int level, const char *format, ...);
365 /* The linker's interface for retrieving the number of sections in an object.
366 The handle is obtained in the claim_file handler. This interface should
367 only be invoked in the claim_file handler. This function sets *COUNT to
368 the number of sections in the object. */
370 typedef
371 enum ld_plugin_status
372 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
374 /* The linker's interface for retrieving the section type of a specific
375 section in an object. This interface should only be invoked in the
376 claim_file handler. This function sets *TYPE to an ELF SHT_xxx value. */
378 typedef
379 enum ld_plugin_status
380 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
381 unsigned int *type);
383 /* The linker's interface for retrieving the name of a specific section in
384 an object. This interface should only be invoked in the claim_file handler.
385 This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
386 by malloc. The plugin must free *SECTION_NAME_PTR. */
388 typedef
389 enum ld_plugin_status
390 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
391 char **section_name_ptr);
393 /* The linker's interface for retrieving the contents of a specific section
394 in an object. This interface should only be invoked in the claim_file
395 handler. This function sets *SECTION_CONTENTS to point to a buffer that is
396 valid until clam_file handler returns. It sets *LEN to the size of the
397 buffer. */
399 typedef
400 enum ld_plugin_status
401 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
402 const unsigned char **section_contents,
403 size_t* len);
405 /* The linker's interface for specifying the desired order of sections.
406 The sections should be specifed using the array SECTION_LIST in the
407 order in which they should appear in the final layout. NUM_SECTIONS
408 specifies the number of entries in each array. This should be invoked
409 in the all_symbols_read handler. */
411 typedef
412 enum ld_plugin_status
413 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
414 unsigned int num_sections);
416 /* The linker's interface for specifying that reordering of sections is
417 desired so that the linker can prepare for it. This should be invoked
418 before update_section_order, preferably in the claim_file handler. */
420 typedef
421 enum ld_plugin_status
422 (*ld_plugin_allow_section_ordering) (void);
424 /* The linker's interface for specifying that a subset of sections is
425 to be mapped to a unique segment. If the plugin wants to call
426 unique_segment_for_sections, it must call this function from a
427 claim_file_handler or when it is first loaded. */
429 typedef
430 enum ld_plugin_status
431 (*ld_plugin_allow_unique_segment_for_sections) (void);
433 /* The linker's interface for specifying that a specific set of sections
434 must be mapped to a unique segment. ELF segments do not have names
435 and the NAME is used as the name of the newly created output section
436 that is then placed in the unique PT_LOAD segment. FLAGS is used to
437 specify if any additional segment flags need to be set. For instance,
438 a specific segment flag can be set to identify this segment. Unsetting
439 segment flags that would be set by default is not possible. The
440 parameter SEGMENT_ALIGNMENT when non-zero will override the default. */
442 typedef
443 enum ld_plugin_status
444 (*ld_plugin_unique_segment_for_sections) (
445 const char* segment_name,
446 uint64_t segment_flags,
447 uint64_t segment_alignment,
448 const struct ld_plugin_section * section_list,
449 unsigned int num_sections);
451 /* The linker's interface for retrieving the section alignment requirement
452 of a specific section in an object. This interface should only be invoked in the
453 claim_file handler. This function sets *ADDRALIGN to the ELF sh_addralign
454 value of the input section. */
456 typedef
457 enum ld_plugin_status
458 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section,
459 unsigned int *addralign);
461 /* The linker's interface for retrieving the section size of a specific section
462 in an object. This interface should only be invoked in the claim_file handler.
463 This function sets *SECSIZE to the ELF sh_size
464 value of the input section. */
466 typedef
467 enum ld_plugin_status
468 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
469 uint64_t *secsize);
471 typedef
472 enum ld_plugin_status
473 (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file);
475 /* The linker's interface for registering the "new_input" handler. This handler
476 will be notified when a new input file has been added after the
477 all_symbols_read event, allowing the plugin to, for example, set a unique
478 segment for sections in plugin-generated input files. */
480 typedef
481 enum ld_plugin_status
482 (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler);
484 /* The linker's interface for getting the list of wrapped symbols using the
485 --wrap option. This sets *NUM_SYMBOLS to number of wrapped symbols and
486 *WRAP_SYMBOL_LIST to the list of wrapped symbols. */
488 typedef
489 enum ld_plugin_status
490 (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols,
491 const char ***wrap_symbol_list);
493 enum ld_plugin_level
495 LDPL_INFO,
496 LDPL_WARNING,
497 LDPL_ERROR,
498 LDPL_FATAL
501 /* Contract between a plug-in and a linker. */
503 enum linker_api_version
505 /* The linker/plugin do not implement any of the API levels below, the API
506 is determined solely via the transfer vector. */
507 LAPI_V0,
509 /* API level v1. The linker provides get_symbols_v3, add_symbols_v2,
510 the plugin will use that and not any lower versions.
511 claim_file is thread-safe on the plugin side and
512 add_symbols on the linker side. */
513 LAPI_V1
516 /* The linker's interface for API version negotiation. A plug-in calls
517 the function (with its IDENTIFIER and VERSION), plus minimal and maximal
518 version of linker_api_version is provided. Linker then returns selected
519 API version and provides its IDENTIFIER and VERSION. The returned value
520 by linker must be in range [MINIMAL_API_SUPPORTED, MAXIMAL_API_SUPPORTED].
521 Identifier pointers remain valid as long as the plugin is loaded. */
523 typedef
525 (*ld_plugin_get_api_version) (const char *plugin_identifier,
526 const char *plugin_version,
527 int minimal_api_supported,
528 int maximal_api_supported,
529 const char **linker_identifier,
530 const char **linker_version);
532 /* Values for the tv_tag field of the transfer vector. */
534 enum ld_plugin_tag
536 LDPT_NULL,
537 LDPT_API_VERSION,
538 LDPT_GOLD_VERSION,
539 LDPT_LINKER_OUTPUT,
540 LDPT_OPTION,
541 LDPT_REGISTER_CLAIM_FILE_HOOK,
542 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
543 LDPT_REGISTER_CLEANUP_HOOK,
544 LDPT_ADD_SYMBOLS,
545 LDPT_GET_SYMBOLS,
546 LDPT_ADD_INPUT_FILE,
547 LDPT_MESSAGE,
548 LDPT_GET_INPUT_FILE,
549 LDPT_RELEASE_INPUT_FILE,
550 LDPT_ADD_INPUT_LIBRARY,
551 LDPT_OUTPUT_NAME,
552 LDPT_SET_EXTRA_LIBRARY_PATH,
553 LDPT_GNU_LD_VERSION,
554 LDPT_GET_VIEW,
555 LDPT_GET_INPUT_SECTION_COUNT,
556 LDPT_GET_INPUT_SECTION_TYPE,
557 LDPT_GET_INPUT_SECTION_NAME,
558 LDPT_GET_INPUT_SECTION_CONTENTS,
559 LDPT_UPDATE_SECTION_ORDER,
560 LDPT_ALLOW_SECTION_ORDERING,
561 LDPT_GET_SYMBOLS_V2,
562 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS,
563 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS,
564 LDPT_GET_SYMBOLS_V3,
565 LDPT_GET_INPUT_SECTION_ALIGNMENT,
566 LDPT_GET_INPUT_SECTION_SIZE,
567 LDPT_REGISTER_NEW_INPUT_HOOK,
568 LDPT_GET_WRAP_SYMBOLS,
569 LDPT_ADD_SYMBOLS_V2,
570 LDPT_GET_API_VERSION,
571 LDPT_REGISTER_CLAIM_FILE_HOOK_V2
574 /* The plugin transfer vector. */
576 struct ld_plugin_tv
578 enum ld_plugin_tag tv_tag;
579 union
581 int tv_val;
582 const char *tv_string;
583 ld_plugin_register_claim_file tv_register_claim_file;
584 ld_plugin_register_claim_file_v2 tv_register_claim_file_v2;
585 ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
586 ld_plugin_register_cleanup tv_register_cleanup;
587 ld_plugin_add_symbols tv_add_symbols;
588 ld_plugin_get_symbols tv_get_symbols;
589 ld_plugin_add_input_file tv_add_input_file;
590 ld_plugin_message tv_message;
591 ld_plugin_get_input_file tv_get_input_file;
592 ld_plugin_get_view tv_get_view;
593 ld_plugin_release_input_file tv_release_input_file;
594 ld_plugin_add_input_library tv_add_input_library;
595 ld_plugin_set_extra_library_path tv_set_extra_library_path;
596 ld_plugin_get_input_section_count tv_get_input_section_count;
597 ld_plugin_get_input_section_type tv_get_input_section_type;
598 ld_plugin_get_input_section_name tv_get_input_section_name;
599 ld_plugin_get_input_section_contents tv_get_input_section_contents;
600 ld_plugin_update_section_order tv_update_section_order;
601 ld_plugin_allow_section_ordering tv_allow_section_ordering;
602 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections;
603 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections;
604 ld_plugin_get_input_section_alignment tv_get_input_section_alignment;
605 ld_plugin_get_input_section_size tv_get_input_section_size;
606 ld_plugin_register_new_input tv_register_new_input;
607 ld_plugin_get_wrap_symbols tv_get_wrap_symbols;
608 ld_plugin_get_api_version tv_get_api_version;
609 } tv_u;
612 /* The plugin library's "onload" entry point. */
614 typedef
615 enum ld_plugin_status
616 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
618 #ifdef __cplusplus
620 #endif
622 #endif /* !defined(PLUGIN_API_H) */