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 >. */
31 #elif defined(HAVE_INTTYPES_H)
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
40 /* Detect endianess based on __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
51 /* Older GCC releases (<4.6.0) can make detection from glibc macros. */
52 #if defined(__GLIBC__) || defined(__GNU_LIBRARY__) || defined(__ANDROID__)
55 #if __BYTE_ORDER == __LITTLE_ENDIAN
56 #define PLUGIN_LITTLE_ENDIAN 1
57 #elif __BYTE_ORDER == __BIG_ENDIAN
58 #define PLUGIN_BIG_ENDIAN 1
62 /* Include all necessary header files based on target. */
63 #if defined(__SVR4) && defined(__sun)
64 #include <sys/byteorder.h>
66 #if defined(__FreeBSD__) || defined(__NetBSD__) || \
67 defined(__DragonFly__) || defined(__minix)
68 #include <sys/endian.h>
70 #if defined(__OpenBSD__)
71 #include <machine/endian.h>
73 /* Detect endianess based on _BYTE_ORDER. */
75 #if _BYTE_ORDER == _LITTLE_ENDIAN
76 #define PLUGIN_LITTLE_ENDIAN 1
77 #elif _BYTE_ORDER == _BIG_ENDIAN
78 #define PLUGIN_BIG_ENDIAN 1
81 /* Detect based on _WIN32. */
83 #define PLUGIN_LITTLE_ENDIAN 1
85 /* Detect based on __BIG_ENDIAN__ and __LITTLE_ENDIAN__ */
86 #ifdef __LITTLE_ENDIAN__
87 #define PLUGIN_LITTLE_ENDIAN 1
90 #define PLUGIN_BIG_ENDIAN 1
99 /* Status code returned by most API routines. */
101 enum ld_plugin_status
104 LDPS_NO_SYMS
, /* Attempt to get symbols that haven't been added. */
105 LDPS_BAD_HANDLE
, /* No claimed object associated with given handle. */
107 /* Additional Error codes TBD. */
110 /* The version of the API specification. */
112 enum ld_plugin_api_version
114 LD_PLUGIN_API_VERSION
= 1
117 /* The type of output file being generated by the linker. */
119 enum ld_plugin_output_file_type
127 /* An input file managed by the plugin library. */
129 struct ld_plugin_input_file
138 /* A symbol belonging to an input file managed by the plugin library. */
140 struct ld_plugin_symbol
144 /* This is for compatibility with older ABIs. The older ABI defined
146 #if PLUGIN_BIG_ENDIAN == 1
151 #elif PLUGIN_LITTLE_ENDIAN == 1
156 #elif PLUGIN_PDP_ENDIAN == 1
162 #error "Could not detect architecture endianess"
170 /* An object's section. */
172 struct ld_plugin_section
178 /* Whether the symbol is a definition, reference, or common, weak or not. */
180 enum ld_plugin_symbol_kind
189 /* The visibility of the symbol. */
191 enum ld_plugin_symbol_visibility
199 /* The type of the symbol. */
201 enum ld_plugin_symbol_type
208 enum ld_plugin_symbol_section_kind
214 /* How a symbol is resolved. */
216 enum ld_plugin_symbol_resolution
220 /* Symbol is still undefined at this point. */
223 /* This is the prevailing definition of the symbol, with references from
224 regular object code. */
227 /* This is the prevailing definition of the symbol, with no
228 references from regular objects. It is only referenced from IR
230 LDPR_PREVAILING_DEF_IRONLY
,
232 /* This definition was pre-empted by a definition in a regular
236 /* This definition was pre-empted by a definition in another IR file. */
239 /* This symbol was resolved by a definition in another IR file. */
242 /* This symbol was resolved by a definition in a regular object
243 linked into the main executable. */
246 /* This symbol was resolved by a definition in a shared object. */
249 /* This is the prevailing definition of the symbol, with no
250 references from regular objects. It is only referenced from IR
251 code, but the symbol is exported and may be referenced from
252 a dynamic object (not seen at link time). */
253 LDPR_PREVAILING_DEF_IRONLY_EXP
256 /* The plugin library's "claim file" handler. */
259 enum ld_plugin_status
260 (*ld_plugin_claim_file_handler
) (
261 const struct ld_plugin_input_file
*file
, int *claimed
);
263 /* The plugin library's "claim file" handler, version 2. */
266 enum ld_plugin_status
267 (*ld_plugin_claim_file_handler_v2
) (
268 const struct ld_plugin_input_file
*file
, int *claimed
, int known_used
);
270 /* The plugin library's "all symbols read" handler. */
273 enum ld_plugin_status
274 (*ld_plugin_all_symbols_read_handler
) (void);
276 /* The plugin library's cleanup handler. */
279 enum ld_plugin_status
280 (*ld_plugin_cleanup_handler
) (void);
282 /* The linker's interface for registering the "claim file" handler. */
285 enum ld_plugin_status
286 (*ld_plugin_register_claim_file
) (ld_plugin_claim_file_handler handler
);
288 /* The linker's interface for registering the "claim file" handler,
292 enum ld_plugin_status
293 (*ld_plugin_register_claim_file_v2
) (ld_plugin_claim_file_handler_v2 handler
);
295 /* The linker's interface for registering the "all symbols read" handler. */
298 enum ld_plugin_status
299 (*ld_plugin_register_all_symbols_read
) (
300 ld_plugin_all_symbols_read_handler handler
);
302 /* The linker's interface for registering the cleanup handler. */
305 enum ld_plugin_status
306 (*ld_plugin_register_cleanup
) (ld_plugin_cleanup_handler handler
);
308 /* The linker's interface for adding symbols from a claimed input file. */
311 enum ld_plugin_status
312 (*ld_plugin_add_symbols
) (void *handle
, int nsyms
,
313 const struct ld_plugin_symbol
*syms
);
315 /* The linker's interface for getting the input file information with
316 an open (possibly re-opened) file descriptor. */
319 enum ld_plugin_status
320 (*ld_plugin_get_input_file
) (const void *handle
,
321 struct ld_plugin_input_file
*file
);
324 enum ld_plugin_status
325 (*ld_plugin_get_view
) (const void *handle
, const void **viewp
);
327 /* The linker's interface for releasing the input file. */
330 enum ld_plugin_status
331 (*ld_plugin_release_input_file
) (const void *handle
);
333 /* The linker's interface for retrieving symbol resolution information. */
336 enum ld_plugin_status
337 (*ld_plugin_get_symbols
) (const void *handle
, int nsyms
,
338 struct ld_plugin_symbol
*syms
);
340 /* The linker's interface for adding a compiled input file. */
343 enum ld_plugin_status
344 (*ld_plugin_add_input_file
) (const char *pathname
);
346 /* The linker's interface for adding a library that should be searched. */
349 enum ld_plugin_status
350 (*ld_plugin_add_input_library
) (const char *libname
);
352 /* The linker's interface for adding a library path that should be searched. */
355 enum ld_plugin_status
356 (*ld_plugin_set_extra_library_path
) (const char *path
);
358 /* The linker's interface for issuing a warning or error message. */
361 enum ld_plugin_status
362 (*ld_plugin_message
) (int level
, const char *format
, ...);
364 /* The linker's interface for retrieving the number of sections in an object.
365 The handle is obtained in the claim_file handler. This interface should
366 only be invoked in the claim_file handler. This function sets *COUNT to
367 the number of sections in the object. */
370 enum ld_plugin_status
371 (*ld_plugin_get_input_section_count
) (const void* handle
, unsigned int *count
);
373 /* The linker's interface for retrieving the section type of a specific
374 section in an object. This interface should only be invoked in the
375 claim_file handler. This function sets *TYPE to an ELF SHT_xxx value. */
378 enum ld_plugin_status
379 (*ld_plugin_get_input_section_type
) (const struct ld_plugin_section section
,
382 /* The linker's interface for retrieving the name of a specific section in
383 an object. This interface should only be invoked in the claim_file handler.
384 This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
385 by malloc. The plugin must free *SECTION_NAME_PTR. */
388 enum ld_plugin_status
389 (*ld_plugin_get_input_section_name
) (const struct ld_plugin_section section
,
390 char **section_name_ptr
);
392 /* The linker's interface for retrieving the contents of a specific section
393 in an object. This interface should only be invoked in the claim_file
394 handler. This function sets *SECTION_CONTENTS to point to a buffer that is
395 valid until clam_file handler returns. It sets *LEN to the size of the
399 enum ld_plugin_status
400 (*ld_plugin_get_input_section_contents
) (const struct ld_plugin_section section
,
401 const unsigned char **section_contents
,
404 /* The linker's interface for specifying the desired order of sections.
405 The sections should be specifed using the array SECTION_LIST in the
406 order in which they should appear in the final layout. NUM_SECTIONS
407 specifies the number of entries in each array. This should be invoked
408 in the all_symbols_read handler. */
411 enum ld_plugin_status
412 (*ld_plugin_update_section_order
) (const struct ld_plugin_section
*section_list
,
413 unsigned int num_sections
);
415 /* The linker's interface for specifying that reordering of sections is
416 desired so that the linker can prepare for it. This should be invoked
417 before update_section_order, preferably in the claim_file handler. */
420 enum ld_plugin_status
421 (*ld_plugin_allow_section_ordering
) (void);
423 /* The linker's interface for specifying that a subset of sections is
424 to be mapped to a unique segment. If the plugin wants to call
425 unique_segment_for_sections, it must call this function from a
426 claim_file_handler or when it is first loaded. */
429 enum ld_plugin_status
430 (*ld_plugin_allow_unique_segment_for_sections
) (void);
432 /* The linker's interface for specifying that a specific set of sections
433 must be mapped to a unique segment. ELF segments do not have names
434 and the NAME is used as the name of the newly created output section
435 that is then placed in the unique PT_LOAD segment. FLAGS is used to
436 specify if any additional segment flags need to be set. For instance,
437 a specific segment flag can be set to identify this segment. Unsetting
438 segment flags that would be set by default is not possible. The
439 parameter SEGMENT_ALIGNMENT when non-zero will override the default. */
442 enum ld_plugin_status
443 (*ld_plugin_unique_segment_for_sections
) (
444 const char* segment_name
,
445 uint64_t segment_flags
,
446 uint64_t segment_alignment
,
447 const struct ld_plugin_section
* section_list
,
448 unsigned int num_sections
);
450 /* The linker's interface for retrieving the section alignment requirement
451 of a specific section in an object. This interface should only be invoked in the
452 claim_file handler. This function sets *ADDRALIGN to the ELF sh_addralign
453 value of the input section. */
456 enum ld_plugin_status
457 (*ld_plugin_get_input_section_alignment
) (const struct ld_plugin_section section
,
458 unsigned int *addralign
);
460 /* The linker's interface for retrieving the section size of a specific section
461 in an object. This interface should only be invoked in the claim_file handler.
462 This function sets *SECSIZE to the ELF sh_size
463 value of the input section. */
466 enum ld_plugin_status
467 (*ld_plugin_get_input_section_size
) (const struct ld_plugin_section section
,
471 enum ld_plugin_status
472 (*ld_plugin_new_input_handler
) (const struct ld_plugin_input_file
*file
);
474 /* The linker's interface for registering the "new_input" handler. This handler
475 will be notified when a new input file has been added after the
476 all_symbols_read event, allowing the plugin to, for example, set a unique
477 segment for sections in plugin-generated input files. */
480 enum ld_plugin_status
481 (*ld_plugin_register_new_input
) (ld_plugin_new_input_handler handler
);
483 /* The linker's interface for getting the list of wrapped symbols using the
484 --wrap option. This sets *NUM_SYMBOLS to number of wrapped symbols and
485 *WRAP_SYMBOL_LIST to the list of wrapped symbols. */
488 enum ld_plugin_status
489 (*ld_plugin_get_wrap_symbols
) (uint64_t *num_symbols
,
490 const char ***wrap_symbol_list
);
500 /* Contract between a plug-in and a linker. */
502 enum linker_api_version
504 /* The linker/plugin do not implement any of the API levels below, the API
505 is determined solely via the transfer vector. */
508 /* API level v1. The linker provides get_symbols_v3, add_symbols_v2,
509 the plugin will use that and not any lower versions.
510 claim_file is thread-safe on the plugin side and
511 add_symbols on the linker side. */
515 /* The linker's interface for API version negotiation. A plug-in calls
516 the function (with its IDENTIFIER and VERSION), plus minimal and maximal
517 version of linker_api_version is provided. Linker then returns selected
518 API version and provides its IDENTIFIER and VERSION. The returned value
519 by linker must be in range [MINIMAL_API_SUPPORTED, MAXIMAL_API_SUPPORTED].
520 Identifier pointers remain valid as long as the plugin is loaded. */
524 (*ld_plugin_get_api_version
) (const char *plugin_identifier
,
525 const char *plugin_version
,
526 int minimal_api_supported
,
527 int maximal_api_supported
,
528 const char **linker_identifier
,
529 const char **linker_version
);
531 /* Values for the tv_tag field of the transfer vector. */
540 LDPT_REGISTER_CLAIM_FILE_HOOK
,
541 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK
,
542 LDPT_REGISTER_CLEANUP_HOOK
,
548 LDPT_RELEASE_INPUT_FILE
,
549 LDPT_ADD_INPUT_LIBRARY
,
551 LDPT_SET_EXTRA_LIBRARY_PATH
,
554 LDPT_GET_INPUT_SECTION_COUNT
,
555 LDPT_GET_INPUT_SECTION_TYPE
,
556 LDPT_GET_INPUT_SECTION_NAME
,
557 LDPT_GET_INPUT_SECTION_CONTENTS
,
558 LDPT_UPDATE_SECTION_ORDER
,
559 LDPT_ALLOW_SECTION_ORDERING
,
561 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS
,
562 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS
,
564 LDPT_GET_INPUT_SECTION_ALIGNMENT
,
565 LDPT_GET_INPUT_SECTION_SIZE
,
566 LDPT_REGISTER_NEW_INPUT_HOOK
,
567 LDPT_GET_WRAP_SYMBOLS
,
569 LDPT_GET_API_VERSION
,
570 LDPT_REGISTER_CLAIM_FILE_HOOK_V2
573 /* The plugin transfer vector. */
577 enum ld_plugin_tag tv_tag
;
581 const char *tv_string
;
582 ld_plugin_register_claim_file tv_register_claim_file
;
583 ld_plugin_register_claim_file_v2 tv_register_claim_file_v2
;
584 ld_plugin_register_all_symbols_read tv_register_all_symbols_read
;
585 ld_plugin_register_cleanup tv_register_cleanup
;
586 ld_plugin_add_symbols tv_add_symbols
;
587 ld_plugin_get_symbols tv_get_symbols
;
588 ld_plugin_add_input_file tv_add_input_file
;
589 ld_plugin_message tv_message
;
590 ld_plugin_get_input_file tv_get_input_file
;
591 ld_plugin_get_view tv_get_view
;
592 ld_plugin_release_input_file tv_release_input_file
;
593 ld_plugin_add_input_library tv_add_input_library
;
594 ld_plugin_set_extra_library_path tv_set_extra_library_path
;
595 ld_plugin_get_input_section_count tv_get_input_section_count
;
596 ld_plugin_get_input_section_type tv_get_input_section_type
;
597 ld_plugin_get_input_section_name tv_get_input_section_name
;
598 ld_plugin_get_input_section_contents tv_get_input_section_contents
;
599 ld_plugin_update_section_order tv_update_section_order
;
600 ld_plugin_allow_section_ordering tv_allow_section_ordering
;
601 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections
;
602 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections
;
603 ld_plugin_get_input_section_alignment tv_get_input_section_alignment
;
604 ld_plugin_get_input_section_size tv_get_input_section_size
;
605 ld_plugin_register_new_input tv_register_new_input
;
606 ld_plugin_get_wrap_symbols tv_get_wrap_symbols
;
607 ld_plugin_get_api_version tv_get_api_version
;
611 /* The plugin library's "onload" entry point. */
614 enum ld_plugin_status
615 (*ld_plugin_onload
) (struct ld_plugin_tv
*tv
);
621 #endif /* !defined(PLUGIN_API_H) */