1 /* plugin-api.h -- External linker plugin API. */ 2 3 /* Copyright (C) 2009-2026 Free Software Foundation, Inc. 4 Written by Cary Coutant <ccoutant (at) 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 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 50 51 #else 52 /* Include header files to define endian macros. */ 53 #if defined(__GLIBC__) || defined(__GNU_LIBRARY__) || defined(__ANDROID__) 54 #include <endian.h> 55 56 #elif defined(__SVR4) && defined(__sun) 57 #include <sys/byteorder.h> 58 59 #elif defined(__FreeBSD__) || defined(__NetBSD__) || \ 60 defined(__DragonFly__) || defined(__minix) 61 #include <sys/endian.h> 62 63 #elif defined(__OpenBSD__) 64 #include <machine/endian.h> 65 #endif 66 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 74 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 82 83 /* Detect based on _WIN32. */ 84 #elif defined _WIN32 85 #define PLUGIN_LITTLE_ENDIAN 1 86 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 94 95 #ifdef __cplusplus 96 extern "C" 97 { 98 #endif 99 100 /* Status code returned by most API routines. */ 101 102 enum ld_plugin_status 103 { 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. */ 109 }; 110 111 /* The version of the API specification. */ 112 113 enum ld_plugin_api_version 114 { 115 LD_PLUGIN_API_VERSION = 1 116 }; 117 118 /* The type of output file being generated by the linker. */ 119 120 enum ld_plugin_output_file_type 121 { 122 LDPO_REL, 123 LDPO_EXEC, 124 LDPO_DYN, 125 LDPO_PIE 126 }; 127 128 /* An input file managed by the plugin library. */ 129 130 struct ld_plugin_input_file 131 { 132 const char *name; 133 int fd; 134 off_t offset; 135 off_t filesize; 136 void *handle; 137 }; 138 139 /* A symbol belonging to an input file managed by the plugin library. */ 140 141 struct ld_plugin_symbol 142 { 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; 169 }; 170 171 /* An object's section. */ 172 173 struct ld_plugin_section 174 { 175 const void* handle; 176 unsigned int shndx; 177 }; 178 179 /* Whether the symbol is a definition, reference, or common, weak or not. */ 180 181 enum ld_plugin_symbol_kind 182 { 183 LDPK_DEF, 184 LDPK_WEAKDEF, 185 LDPK_UNDEF, 186 LDPK_WEAKUNDEF, 187 LDPK_COMMON 188 }; 189 190 /* The visibility of the symbol. */ 191 192 enum ld_plugin_symbol_visibility 193 { 194 LDPV_DEFAULT, 195 LDPV_PROTECTED, 196 LDPV_INTERNAL, 197 LDPV_HIDDEN 198 }; 199 200 /* The type of the symbol. */ 201 202 enum ld_plugin_symbol_type 203 { 204 LDST_UNKNOWN, 205 LDST_FUNCTION, 206 LDST_VARIABLE 207 }; 208 209 enum ld_plugin_symbol_section_kind 210 { 211 LDSSK_DEFAULT, 212 LDSSK_BSS 213 }; 214 215 /* How a symbol is resolved. */ 216 217 enum ld_plugin_symbol_resolution 218 { 219 LDPR_UNKNOWN = 0, 220 221 /* Symbol is still undefined at this point. */ 222 LDPR_UNDEF, 223 224 /* This is the prevailing definition of the symbol, with references from 225 regular object code. */ 226 LDPR_PREVAILING_DEF, 227 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, 232 233 /* This definition was pre-empted by a definition in a regular 234 object file. */ 235 LDPR_PREEMPTED_REG, 236 237 /* This definition was pre-empted by a definition in another IR file. */ 238 LDPR_PREEMPTED_IR, 239 240 /* This symbol was resolved by a definition in another IR file. */ 241 LDPR_RESOLVED_IR, 242 243 /* This symbol was resolved by a definition in a regular object 244 linked into the main executable. */ 245 LDPR_RESOLVED_EXEC, 246 247 /* This symbol was resolved by a definition in a shared object. */ 248 LDPR_RESOLVED_DYN, 249 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 255 }; 256 257 /* The plugin library's "claim file" handler. */ 258 259 typedef 260 enum ld_plugin_status 261 (*ld_plugin_claim_file_handler) ( 262 const struct ld_plugin_input_file *file, int *claimed); 263 264 /* The plugin library's "claim file" handler, version 2. */ 265 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); 270 271 /* The plugin library's "all symbols read" handler. */ 272 273 typedef 274 enum ld_plugin_status 275 (*ld_plugin_all_symbols_read_handler) (void); 276 277 /* The plugin library's cleanup handler. */ 278 279 typedef 280 enum ld_plugin_status 281 (*ld_plugin_cleanup_handler) (void); 282 283 /* The linker's interface for registering the "claim file" handler. */ 284 285 typedef 286 enum ld_plugin_status 287 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler); 288 289 /* The linker's interface for registering the "claim file" handler, 290 version 2. */ 291 292 typedef 293 enum ld_plugin_status 294 (*ld_plugin_register_claim_file_v2) (ld_plugin_claim_file_handler_v2 handler); 295 296 /* The linker's interface for registering the "all symbols read" handler. */ 297 298 typedef 299 enum ld_plugin_status 300 (*ld_plugin_register_all_symbols_read) ( 301 ld_plugin_all_symbols_read_handler handler); 302 303 /* The linker's interface for registering the cleanup handler. */ 304 305 typedef 306 enum ld_plugin_status 307 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler); 308 309 /* The linker's interface for adding symbols from a claimed input file. */ 310 311 typedef 312 enum ld_plugin_status 313 (*ld_plugin_add_symbols) (void *handle, int nsyms, 314 const struct ld_plugin_symbol *syms); 315 316 /* The linker's interface for getting the input file information with 317 an open (possibly re-opened) file descriptor. */ 318 319 typedef 320 enum ld_plugin_status 321 (*ld_plugin_get_input_file) (const void *handle, 322 struct ld_plugin_input_file *file); 323 324 typedef 325 enum ld_plugin_status 326 (*ld_plugin_get_view) (const void *handle, const void **viewp); 327 328 /* The linker's interface for releasing the input file. */ 329 330 typedef 331 enum ld_plugin_status 332 (*ld_plugin_release_input_file) (const void *handle); 333 334 /* The linker's interface for retrieving symbol resolution information. */ 335 336 typedef 337 enum ld_plugin_status 338 (*ld_plugin_get_symbols) (const void *handle, int nsyms, 339 struct ld_plugin_symbol *syms); 340 341 /* The linker's interface for adding a compiled input file. */ 342 343 typedef 344 enum ld_plugin_status 345 (*ld_plugin_add_input_file) (const char *pathname); 346 347 /* The linker's interface for adding a library that should be searched. */ 348 349 typedef 350 enum ld_plugin_status 351 (*ld_plugin_add_input_library) (const char *libname); 352 353 /* The linker's interface for adding a library path that should be searched. */ 354 355 typedef 356 enum ld_plugin_status 357 (*ld_plugin_set_extra_library_path) (const char *path); 358 359 /* The linker's interface for issuing a warning or error message. */ 360 361 typedef 362 enum ld_plugin_status 363 (*ld_plugin_message) (int level, const char *format, ...); 364 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. */ 369 370 typedef 371 enum ld_plugin_status 372 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count); 373 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. */ 377 378 typedef 379 enum ld_plugin_status 380 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section, 381 unsigned int *type); 382 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. */ 387 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); 392 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. */ 398 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); 404 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. */ 410 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); 415 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. */ 419 420 typedef 421 enum ld_plugin_status 422 (*ld_plugin_allow_section_ordering) (void); 423 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. */ 428 429 typedef 430 enum ld_plugin_status 431 (*ld_plugin_allow_unique_segment_for_sections) (void); 432 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. */ 441 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); 450 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. */ 455 456 typedef 457 enum ld_plugin_status 458 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section, 459 unsigned int *addralign); 460 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. */ 465 466 typedef 467 enum ld_plugin_status 468 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section, 469 uint64_t *secsize); 470 471 typedef 472 enum ld_plugin_status 473 (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file); 474 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. */ 479 480 typedef 481 enum ld_plugin_status 482 (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler); 483 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. */ 487 488 typedef 489 enum ld_plugin_status 490 (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols, 491 const char ***wrap_symbol_list); 492 493 enum ld_plugin_level 494 { 495 LDPL_INFO, 496 LDPL_WARNING, 497 LDPL_ERROR, 498 LDPL_FATAL 499 }; 500 501 /* Contract between a plug-in and a linker. */ 502 503 enum linker_api_version 504 { 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, 508 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 514 }; 515 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. */ 522 523 typedef 524 int 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); 531 532 /* Values for the tv_tag field of the transfer vector. */ 533 534 enum ld_plugin_tag 535 { 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 572 }; 573 574 /* The plugin transfer vector. */ 575 576 struct ld_plugin_tv 577 { 578 enum ld_plugin_tag tv_tag; 579 union 580 { 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; 610 }; 611 612 /* The plugin library's "onload" entry point. */ 613 614 typedef 615 enum ld_plugin_status 616 (*ld_plugin_onload) (struct ld_plugin_tv *tv); 617 618 #ifdef __cplusplus 619 } 620 #endif 621 622 #endif /* !defined(PLUGIN_API_H) */ 623
Indexes created Tue Feb 24 08:35:24 UTC 2026