include/plugin-api.h

   1 /* plugin-api.h -- External linker plugin API.  */
   2
   3 /* Copyright (C) 2009-2023 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 "claim file" handler, version 2.  */
 264
 265 typedef
 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);
 269
 270 /* The plugin library's "all symbols read" handler.  */
 271
 272 typedef
 273 enum ld_plugin_status
 274 (*ld_plugin_all_symbols_read_handler) (void);
 275
 276 /* The plugin library's cleanup handler.  */
 277
 278 typedef
 279 enum ld_plugin_status
 280 (*ld_plugin_cleanup_handler) (void);
 281
 282 /* The linker's interface for registering the "claim file" handler.  */
 283
 284 typedef
 285 enum ld_plugin_status
 286 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
 287
 288 /* The linker's interface for registering the "claim file" handler,
 289    version 2.  */
 290
 291 typedef
 292 enum ld_plugin_status
 293 (*ld_plugin_register_claim_file_v2) (ld_plugin_claim_file_handler_v2 handler);
 294
 295 /* The linker's interface for registering the "all symbols read" handler.  */
 296
 297 typedef
 298 enum ld_plugin_status
 299 (*ld_plugin_register_all_symbols_read) (
 300   ld_plugin_all_symbols_read_handler handler);
 301
 302 /* The linker's interface for registering the cleanup handler.  */
 303
 304 typedef
 305 enum ld_plugin_status
 306 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
 307
 308 /* The linker's interface for adding symbols from a claimed input file.  */
 309
 310 typedef
 311 enum ld_plugin_status
 312 (*ld_plugin_add_symbols) (void *handle, int nsyms,
 313                           const struct ld_plugin_symbol *syms);
 314
 315 /* The linker's interface for getting the input file information with
 316    an open (possibly re-opened) file descriptor.  */
 317
 318 typedef
 319 enum ld_plugin_status
 320 (*ld_plugin_get_input_file) (const void *handle,
 321                              struct ld_plugin_input_file *file);
 322
 323 typedef
 324 enum ld_plugin_status
 325 (*ld_plugin_get_view) (const void *handle, const void **viewp);
 326
 327 /* The linker's interface for releasing the input file.  */
 328
 329 typedef
 330 enum ld_plugin_status
 331 (*ld_plugin_release_input_file) (const void *handle);
 332
 333 /* The linker's interface for retrieving symbol resolution information.  */
 334
 335 typedef
 336 enum ld_plugin_status
 337 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
 338                           struct ld_plugin_symbol *syms);
 339
 340 /* The linker's interface for adding a compiled input file.  */
 341
 342 typedef
 343 enum ld_plugin_status
 344 (*ld_plugin_add_input_file) (const char *pathname);
 345
 346 /* The linker's interface for adding a library that should be searched.  */
 347
 348 typedef
 349 enum ld_plugin_status
 350 (*ld_plugin_add_input_library) (const char *libname);
 351
 352 /* The linker's interface for adding a library path that should be searched.  */
 353
 354 typedef
 355 enum ld_plugin_status
 356 (*ld_plugin_set_extra_library_path) (const char *path);
 357
 358 /* The linker's interface for issuing a warning or error message.  */
 359
 360 typedef
 361 enum ld_plugin_status
 362 (*ld_plugin_message) (int level, const char *format, ...);
 363
 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.  */
 368
 369 typedef
 370 enum ld_plugin_status
 371 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
 372
 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.  */
 376
 377 typedef
 378 enum ld_plugin_status
 379 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
 380                                      unsigned int *type);
 381
 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.  */
 386
 387 typedef
 388 enum ld_plugin_status
 389 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
 390                                      char **section_name_ptr);
 391
 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
 396    buffer.  */
 397
 398 typedef
 399 enum ld_plugin_status
 400 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
 401                                          const unsigned char **section_contents,
 402                                          size_t* len);
 403
 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.  */
 409
 410 typedef
 411 enum ld_plugin_status
 412 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
 413                                    unsigned int num_sections);
 414
 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.  */
 418
 419 typedef
 420 enum ld_plugin_status
 421 (*ld_plugin_allow_section_ordering) (void);
 422
 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.  */
 427
 428 typedef
 429 enum ld_plugin_status
 430 (*ld_plugin_allow_unique_segment_for_sections) (void);
 431
 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.  */
 440
 441 typedef
 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);
 449
 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.  */
 454
 455 typedef
 456 enum ld_plugin_status
 457 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section,
 458                                           unsigned int *addralign);
 459
 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.  */
 464
 465 typedef
 466 enum ld_plugin_status
 467 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
 468                                      uint64_t *secsize);
 469
 470 typedef
 471 enum ld_plugin_status
 472 (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file);
 473
 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. */
 478
 479 typedef
 480 enum ld_plugin_status
 481 (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler);
 482
 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. */
 486
 487 typedef
 488 enum ld_plugin_status
 489 (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols,
 490                                const char ***wrap_symbol_list);
 491
 492 enum ld_plugin_level
 493 {
 494   LDPL_INFO,
 495   LDPL_WARNING,
 496   LDPL_ERROR,
 497   LDPL_FATAL
 498 };
 499
 500 /* Contract between a plug-in and a linker.  */
 501
 502 enum linker_api_version
 503 {
 504    /* The linker/plugin do not implement any of the API levels below, the API
 505        is determined solely via the transfer vector.  */
 506    LAPI_V0,
 507
 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.  */
 512    LAPI_V1
 513 };
 514
 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.  */
 521
 522 typedef
 523 int
 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);
 530
 531 /* Values for the tv_tag field of the transfer vector.  */
 532
 533 enum ld_plugin_tag
 534 {
 535   LDPT_NULL,
 536   LDPT_API_VERSION,
 537   LDPT_GOLD_VERSION,
 538   LDPT_LINKER_OUTPUT,
 539   LDPT_OPTION,
 540   LDPT_REGISTER_CLAIM_FILE_HOOK,
 541   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
 542   LDPT_REGISTER_CLEANUP_HOOK,
 543   LDPT_ADD_SYMBOLS,
 544   LDPT_GET_SYMBOLS,
 545   LDPT_ADD_INPUT_FILE,
 546   LDPT_MESSAGE,
 547   LDPT_GET_INPUT_FILE,
 548   LDPT_RELEASE_INPUT_FILE,
 549   LDPT_ADD_INPUT_LIBRARY,
 550   LDPT_OUTPUT_NAME,
 551   LDPT_SET_EXTRA_LIBRARY_PATH,
 552   LDPT_GNU_LD_VERSION,
 553   LDPT_GET_VIEW,
 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,
 560   LDPT_GET_SYMBOLS_V2,
 561   LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS,
 562   LDPT_UNIQUE_SEGMENT_FOR_SECTIONS,
 563   LDPT_GET_SYMBOLS_V3,
 564   LDPT_GET_INPUT_SECTION_ALIGNMENT,
 565   LDPT_GET_INPUT_SECTION_SIZE,
 566   LDPT_REGISTER_NEW_INPUT_HOOK,
 567   LDPT_GET_WRAP_SYMBOLS,
 568   LDPT_ADD_SYMBOLS_V2,
 569   LDPT_GET_API_VERSION,
 570   LDPT_REGISTER_CLAIM_FILE_HOOK_V2
 571 };
 572
 573 /* The plugin transfer vector.  */
 574
 575 struct ld_plugin_tv
 576 {
 577   enum ld_plugin_tag tv_tag;
 578   union
 579   {
 580     int tv_val;
 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;
 608   } tv_u;
 609 };
 610
 611 /* The plugin library's "onload" entry point.  */
 612
 613 typedef
 614 enum ld_plugin_status
 615 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
 616
 617 #ifdef __cplusplus
 618 }
 619 #endif
 620
 621 #endif /* !defined(PLUGIN_API_H) */