include/plugin-api.h

   1 /* plugin-api.h -- External linker plugin API.  */
   2
   3 /* Copyright (C) 2009-2024 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 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) */