1 /* plugin-api.h -- External linker plugin API. */ 2 3 /* Copyright (C) 2009-2021 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 95 extern "C" 96 { 97 #endif 98 99 /* Status code returned by most API routines. */ 100 101 enum 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 112 enum 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 119 enum 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 129 struct 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 140 struct 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 172 struct 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 180 enum 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 191 enum 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 201 enum ld_plugin_symbol_type 202 { 203 LDST_UNKNOWN, 204 LDST_FUNCTION, 205 LDST_VARIABLE 206 }; 207 208 enum ld_plugin_symbol_section_kind 209 { 210 LDSSK_DEFAULT, 211 LDSSK_BSS 212 }; 213 214 /* How a symbol is resolved. */ 215 216 enum 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 258 typedef 259 enum 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 265 typedef 266 enum ld_plugin_status 267 (*ld_plugin_all_symbols_read_handler) (void); 268 269 /* The plugin library's cleanup handler. */ 270 271 typedef 272 enum ld_plugin_status 273 (*ld_plugin_cleanup_handler) (void); 274 275 /* The linker's interface for registering the "claim file" handler. */ 276 277 typedef 278 enum 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 283 typedef 284 enum 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 290 typedef 291 enum 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 296 typedef 297 enum 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 304 typedef 305 enum ld_plugin_status 306 (*ld_plugin_get_input_file) (const void *handle, 307 struct ld_plugin_input_file *file); 308 309 typedef 310 enum 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 315 typedef 316 enum ld_plugin_status 317 (*ld_plugin_release_input_file) (const void *handle); 318 319 /* The linker's interface for retrieving symbol resolution information. */ 320 321 typedef 322 enum 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 328 typedef 329 enum 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 334 typedef 335 enum 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 340 typedef 341 enum 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 346 typedef 347 enum 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 355 typedef 356 enum 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 363 typedef 364 enum 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 373 typedef 374 enum 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 384 typedef 385 enum 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 396 typedef 397 enum 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 405 typedef 406 enum 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 414 typedef 415 enum 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 427 typedef 428 enum 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 441 typedef 442 enum 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 451 typedef 452 enum ld_plugin_status 453 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section, 454 uint64_t *secsize); 455 456 typedef 457 enum 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 465 typedef 466 enum 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 473 typedef 474 enum ld_plugin_status 475 (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols, 476 const char ***wrap_symbol_list); 477 478 enum ld_plugin_level 479 { 480 LDPL_INFO, 481 LDPL_WARNING, 482 LDPL_ERROR, 483 LDPL_FATAL 484 }; 485 486 /* Values for the tv_tag field of the transfer vector. */ 487 488 enum ld_plugin_tag 489 { 490 LDPT_NULL = 0, 491 LDPT_API_VERSION = 1, 492 LDPT_GOLD_VERSION = 2, 493 LDPT_LINKER_OUTPUT = 3, 494 LDPT_OPTION = 4, 495 LDPT_REGISTER_CLAIM_FILE_HOOK = 5, 496 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6, 497 LDPT_REGISTER_CLEANUP_HOOK = 7, 498 LDPT_ADD_SYMBOLS = 8, 499 LDPT_GET_SYMBOLS = 9, 500 LDPT_ADD_INPUT_FILE = 10, 501 LDPT_MESSAGE = 11, 502 LDPT_GET_INPUT_FILE = 12, 503 LDPT_RELEASE_INPUT_FILE = 13, 504 LDPT_ADD_INPUT_LIBRARY = 14, 505 LDPT_OUTPUT_NAME = 15, 506 LDPT_SET_EXTRA_LIBRARY_PATH = 16, 507 LDPT_GNU_LD_VERSION = 17, 508 LDPT_GET_VIEW = 18, 509 LDPT_GET_INPUT_SECTION_COUNT = 19, 510 LDPT_GET_INPUT_SECTION_TYPE = 20, 511 LDPT_GET_INPUT_SECTION_NAME = 21, 512 LDPT_GET_INPUT_SECTION_CONTENTS = 22, 513 LDPT_UPDATE_SECTION_ORDER = 23, 514 LDPT_ALLOW_SECTION_ORDERING = 24, 515 LDPT_GET_SYMBOLS_V2 = 25, 516 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26, 517 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27, 518 LDPT_GET_SYMBOLS_V3 = 28, 519 LDPT_GET_INPUT_SECTION_ALIGNMENT = 29, 520 LDPT_GET_INPUT_SECTION_SIZE = 30, 521 LDPT_REGISTER_NEW_INPUT_HOOK = 31, 522 LDPT_GET_WRAP_SYMBOLS = 32, 523 LDPT_ADD_SYMBOLS_V2 = 33 524 }; 525 526 /* The plugin transfer vector. */ 527 528 struct ld_plugin_tv 529 { 530 enum ld_plugin_tag tv_tag; 531 union 532 { 533 int tv_val; 534 const char *tv_string; 535 ld_plugin_register_claim_file tv_register_claim_file; 536 ld_plugin_register_all_symbols_read tv_register_all_symbols_read; 537 ld_plugin_register_cleanup tv_register_cleanup; 538 ld_plugin_add_symbols tv_add_symbols; 539 ld_plugin_get_symbols tv_get_symbols; 540 ld_plugin_add_input_file tv_add_input_file; 541 ld_plugin_message tv_message; 542 ld_plugin_get_input_file tv_get_input_file; 543 ld_plugin_get_view tv_get_view; 544 ld_plugin_release_input_file tv_release_input_file; 545 ld_plugin_add_input_library tv_add_input_library; 546 ld_plugin_set_extra_library_path tv_set_extra_library_path; 547 ld_plugin_get_input_section_count tv_get_input_section_count; 548 ld_plugin_get_input_section_type tv_get_input_section_type; 549 ld_plugin_get_input_section_name tv_get_input_section_name; 550 ld_plugin_get_input_section_contents tv_get_input_section_contents; 551 ld_plugin_update_section_order tv_update_section_order; 552 ld_plugin_allow_section_ordering tv_allow_section_ordering; 553 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections; 554 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections; 555 ld_plugin_get_input_section_alignment tv_get_input_section_alignment; 556 ld_plugin_get_input_section_size tv_get_input_section_size; 557 ld_plugin_register_new_input tv_register_new_input; 558 ld_plugin_get_wrap_symbols tv_get_wrap_symbols; 559 } tv_u; 560 }; 561 562 /* The plugin library's "onload" entry point. */ 563 564 typedef 565 enum ld_plugin_status 566 (*ld_plugin_onload) (struct ld_plugin_tv *tv); 567 568 #ifdef __cplusplus 569 } 570 #endif 571 572 #endif /* !defined(PLUGIN_API_H) */ 573