include/plugin-api.h

   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) */