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