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 "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 /* Contract between a plug-in and a linker.  */
 487
 488 enum 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
 508 typedef
 509 int
 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
 519 enum 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
 560 struct 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
 597 typedef
 598 enum 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) */