source/include/plugin-api.h

0001 /* plugin-api.h -- External linker plugin API.  */
0002
0003 /* Copyright (C) 2009-2022 Free Software Foundation, Inc.
0004    Written by Cary Coutant <ccoutant@google.com>.
0005
0006    This file is part of binutils.
0007
0008    This program is free software; you can redistribute it and/or modify
0009    it under the terms of the GNU General Public License as published by
0010    the Free Software Foundation; either version 3 of the License, or
0011    (at your option) any later version.
0012
0013    This program is distributed in the hope that it will be useful,
0014    but WITHOUT ANY WARRANTY; without even the implied warranty of
0015    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0016    GNU General Public License for more details.
0017
0018    You should have received a copy of the GNU General Public License
0019    along with this program; if not, write to the Free Software
0020    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
0021    MA 02110-1301, USA.  */
0022
0023 /* This file defines the interface for writing a linker plugin, which is
0024    described at < http://gcc.gnu.org/wiki/whopr/driver >.  */
0025
0026 #ifndef PLUGIN_API_H
0027 #define PLUGIN_API_H
0028
0029 #ifdef HAVE_STDINT_H
0030 #include <stdint.h>
0031 #elif defined(HAVE_INTTYPES_H)
0032 #include <inttypes.h>
0033 #endif
0034 #include <sys/types.h>
0035 #if !defined(HAVE_STDINT_H) && !defined(HAVE_INTTYPES_H) && \
0036     !defined(UINT64_MAX) && !defined(uint64_t)
0037 #error cannot find uint64_t type
0038 #endif
0039
0040 /* Detect endianess based on __BYTE_ORDER__ macro.  */
0041 #if defined(__BYTE_ORDER__) && defined(__ORDER_BIG_ENDIAN__) && \
0042     defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_PDP_ENDIAN__)
0043 #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
0044 #define PLUGIN_LITTLE_ENDIAN 1
0045 #elif __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
0046 #define PLUGIN_BIG_ENDIAN 1
0047 #elif __BYTE_ORDER__ == __ORDER_PDP_ENDIAN__
0048 #define PLUGIN_PDP_ENDIAN 1
0049 #endif
0050 #else
0051 /* Older GCC releases (<4.6.0) can make detection from glibc macros.  */
0052 #if defined(__GLIBC__) || defined(__GNU_LIBRARY__) || defined(__ANDROID__)
0053 #include <endian.h>
0054 #ifdef __BYTE_ORDER
0055 #if __BYTE_ORDER == __LITTLE_ENDIAN
0056 #define PLUGIN_LITTLE_ENDIAN 1
0057 #elif __BYTE_ORDER == __BIG_ENDIAN
0058 #define PLUGIN_BIG_ENDIAN 1
0059 #endif
0060 #endif
0061 #endif
0062 /* Include all necessary header files based on target.  */
0063 #if defined(__SVR4) && defined(__sun)
0064 #include <sys/byteorder.h>
0065 #endif
0066 #if defined(__FreeBSD__) || defined(__NetBSD__) || \
0067     defined(__DragonFly__) || defined(__minix)
0068 #include <sys/endian.h>
0069 #endif
0070 #if defined(__OpenBSD__)
0071 #include <machine/endian.h>
0072 #endif
0073 /* Detect endianess based on _BYTE_ORDER.  */
0074 #ifdef _BYTE_ORDER
0075 #if _BYTE_ORDER == _LITTLE_ENDIAN
0076 #define PLUGIN_LITTLE_ENDIAN 1
0077 #elif _BYTE_ORDER == _BIG_ENDIAN
0078 #define PLUGIN_BIG_ENDIAN 1
0079 #endif
0080 #endif
0081 /* Detect based on _WIN32.  */
0082 #if defined(_WIN32)
0083 #define PLUGIN_LITTLE_ENDIAN 1
0084 #endif
0085 /* Detect based on __BIG_ENDIAN__ and __LITTLE_ENDIAN__ */
0086 #ifdef __LITTLE_ENDIAN__
0087 #define PLUGIN_LITTLE_ENDIAN 1
0088 #endif
0089 #ifdef __BIG_ENDIAN__
0090 #define PLUGIN_BIG_ENDIAN 1
0091 #endif
0092 #endif
0093
0094 #ifdef __cplusplus
0095 extern "C"
0096 {
0097 #endif
0098
0099 /* Status code returned by most API routines.  */
0100
0101 enum ld_plugin_status
0102 {
0103   LDPS_OK = 0,
0104   LDPS_NO_SYMS,         /* Attempt to get symbols that haven't been added. */
0105   LDPS_BAD_HANDLE,      /* No claimed object associated with given handle. */
0106   LDPS_ERR
0107   /* Additional Error codes TBD.  */
0108 };
0109
0110 /* The version of the API specification.  */
0111
0112 enum ld_plugin_api_version
0113 {
0114   LD_PLUGIN_API_VERSION = 1
0115 };
0116
0117 /* The type of output file being generated by the linker.  */
0118
0119 enum ld_plugin_output_file_type
0120 {
0121   LDPO_REL,
0122   LDPO_EXEC,
0123   LDPO_DYN,
0124   LDPO_PIE
0125 };
0126
0127 /* An input file managed by the plugin library.  */
0128
0129 struct ld_plugin_input_file
0130 {
0131   const char *name;
0132   int fd;
0133   off_t offset;
0134   off_t filesize;
0135   void *handle;
0136 };
0137
0138 /* A symbol belonging to an input file managed by the plugin library.  */
0139
0140 struct ld_plugin_symbol
0141 {
0142   char *name;
0143   char *version;
0144   /* This is for compatibility with older ABIs.  The older ABI defined
0145      only 'def' field.  */
0146 #if PLUGIN_BIG_ENDIAN == 1
0147   char unused;
0148   char section_kind;
0149   char symbol_type;
0150   char def;
0151 #elif PLUGIN_LITTLE_ENDIAN == 1
0152   char def;
0153   char symbol_type;
0154   char section_kind;
0155   char unused;
0156 #elif PLUGIN_PDP_ENDIAN == 1
0157   char symbol_type;
0158   char def;
0159   char unused;
0160   char section_kind;
0161 #else
0162 #error "Could not detect architecture endianess"
0163 #endif
0164   int visibility;
0165   uint64_t size;
0166   char *comdat_key;
0167   int resolution;
0168 };
0169
0170 /* An object's section.  */
0171
0172 struct ld_plugin_section
0173 {
0174   const void* handle;
0175   unsigned int shndx;
0176 };
0177
0178 /* Whether the symbol is a definition, reference, or common, weak or not.  */
0179
0180 enum ld_plugin_symbol_kind
0181 {
0182   LDPK_DEF,
0183   LDPK_WEAKDEF,
0184   LDPK_UNDEF,
0185   LDPK_WEAKUNDEF,
0186   LDPK_COMMON
0187 };
0188
0189 /* The visibility of the symbol.  */
0190
0191 enum ld_plugin_symbol_visibility
0192 {
0193   LDPV_DEFAULT,
0194   LDPV_PROTECTED,
0195   LDPV_INTERNAL,
0196   LDPV_HIDDEN
0197 };
0198
0199 /* The type of the symbol.  */
0200
0201 enum ld_plugin_symbol_type
0202 {
0203   LDST_UNKNOWN,
0204   LDST_FUNCTION,
0205   LDST_VARIABLE
0206 };
0207
0208 enum ld_plugin_symbol_section_kind
0209 {
0210   LDSSK_DEFAULT,
0211   LDSSK_BSS
0212 };
0213
0214 /* How a symbol is resolved.  */
0215
0216 enum ld_plugin_symbol_resolution
0217 {
0218   LDPR_UNKNOWN = 0,
0219
0220   /* Symbol is still undefined at this point.  */
0221   LDPR_UNDEF,
0222
0223   /* This is the prevailing definition of the symbol, with references from
0224      regular object code.  */
0225   LDPR_PREVAILING_DEF,
0226
0227   /* This is the prevailing definition of the symbol, with no
0228      references from regular objects.  It is only referenced from IR
0229      code.  */
0230   LDPR_PREVAILING_DEF_IRONLY,
0231
0232   /* This definition was pre-empted by a definition in a regular
0233      object file.  */
0234   LDPR_PREEMPTED_REG,
0235
0236   /* This definition was pre-empted by a definition in another IR file.  */
0237   LDPR_PREEMPTED_IR,
0238
0239   /* This symbol was resolved by a definition in another IR file.  */
0240   LDPR_RESOLVED_IR,
0241
0242   /* This symbol was resolved by a definition in a regular object
0243      linked into the main executable.  */
0244   LDPR_RESOLVED_EXEC,
0245
0246   /* This symbol was resolved by a definition in a shared object.  */
0247   LDPR_RESOLVED_DYN,
0248
0249   /* This is the prevailing definition of the symbol, with no
0250      references from regular objects.  It is only referenced from IR
0251      code, but the symbol is exported and may be referenced from
0252      a dynamic object (not seen at link time).  */
0253   LDPR_PREVAILING_DEF_IRONLY_EXP
0254 };
0255
0256 /* The plugin library's "claim file" handler.  */
0257
0258 typedef
0259 enum ld_plugin_status
0260 (*ld_plugin_claim_file_handler) (
0261   const struct ld_plugin_input_file *file, int *claimed);
0262
0263 /* The plugin library's "all symbols read" handler.  */
0264
0265 typedef
0266 enum ld_plugin_status
0267 (*ld_plugin_all_symbols_read_handler) (void);
0268
0269 /* The plugin library's cleanup handler.  */
0270
0271 typedef
0272 enum ld_plugin_status
0273 (*ld_plugin_cleanup_handler) (void);
0274
0275 /* The linker's interface for registering the "claim file" handler.  */
0276
0277 typedef
0278 enum ld_plugin_status
0279 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
0280
0281 /* The linker's interface for registering the "all symbols read" handler.  */
0282
0283 typedef
0284 enum ld_plugin_status
0285 (*ld_plugin_register_all_symbols_read) (
0286   ld_plugin_all_symbols_read_handler handler);
0287
0288 /* The linker's interface for registering the cleanup handler.  */
0289
0290 typedef
0291 enum ld_plugin_status
0292 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
0293
0294 /* The linker's interface for adding symbols from a claimed input file.  */
0295
0296 typedef
0297 enum ld_plugin_status
0298 (*ld_plugin_add_symbols) (void *handle, int nsyms,
0299                           const struct ld_plugin_symbol *syms);
0300
0301 /* The linker's interface for getting the input file information with
0302    an open (possibly re-opened) file descriptor.  */
0303
0304 typedef
0305 enum ld_plugin_status
0306 (*ld_plugin_get_input_file) (const void *handle,
0307                              struct ld_plugin_input_file *file);
0308
0309 typedef
0310 enum ld_plugin_status
0311 (*ld_plugin_get_view) (const void *handle, const void **viewp);
0312
0313 /* The linker's interface for releasing the input file.  */
0314
0315 typedef
0316 enum ld_plugin_status
0317 (*ld_plugin_release_input_file) (const void *handle);
0318
0319 /* The linker's interface for retrieving symbol resolution information.  */
0320
0321 typedef
0322 enum ld_plugin_status
0323 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
0324                           struct ld_plugin_symbol *syms);
0325
0326 /* The linker's interface for adding a compiled input file.  */
0327
0328 typedef
0329 enum ld_plugin_status
0330 (*ld_plugin_add_input_file) (const char *pathname);
0331
0332 /* The linker's interface for adding a library that should be searched.  */
0333
0334 typedef
0335 enum ld_plugin_status
0336 (*ld_plugin_add_input_library) (const char *libname);
0337
0338 /* The linker's interface for adding a library path that should be searched.  */
0339
0340 typedef
0341 enum ld_plugin_status
0342 (*ld_plugin_set_extra_library_path) (const char *path);
0343
0344 /* The linker's interface for issuing a warning or error message.  */
0345
0346 typedef
0347 enum ld_plugin_status
0348 (*ld_plugin_message) (int level, const char *format, ...);
0349
0350 /* The linker's interface for retrieving the number of sections in an object.
0351    The handle is obtained in the claim_file handler.  This interface should
0352    only be invoked in the claim_file handler.   This function sets *COUNT to
0353    the number of sections in the object.  */
0354
0355 typedef
0356 enum ld_plugin_status
0357 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
0358
0359 /* The linker's interface for retrieving the section type of a specific
0360    section in an object.  This interface should only be invoked in the
0361    claim_file handler.  This function sets *TYPE to an ELF SHT_xxx value.  */
0362
0363 typedef
0364 enum ld_plugin_status
0365 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
0366                                      unsigned int *type);
0367
0368 /* The linker's interface for retrieving the name of a specific section in
0369    an object. This interface should only be invoked in the claim_file handler.
0370    This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
0371    by malloc.  The plugin must free *SECTION_NAME_PTR.  */
0372
0373 typedef
0374 enum ld_plugin_status
0375 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
0376                                      char **section_name_ptr);
0377
0378 /* The linker's interface for retrieving the contents of a specific section
0379    in an object.  This interface should only be invoked in the claim_file
0380    handler.  This function sets *SECTION_CONTENTS to point to a buffer that is
0381    valid until clam_file handler returns.  It sets *LEN to the size of the
0382    buffer.  */
0383
0384 typedef
0385 enum ld_plugin_status
0386 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
0387                                          const unsigned char **section_contents,
0388                                          size_t* len);
0389
0390 /* The linker's interface for specifying the desired order of sections.
0391    The sections should be specifed using the array SECTION_LIST in the
0392    order in which they should appear in the final layout.  NUM_SECTIONS
0393    specifies the number of entries in each array.  This should be invoked
0394    in the all_symbols_read handler.  */
0395
0396 typedef
0397 enum ld_plugin_status
0398 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
0399                    unsigned int num_sections);
0400
0401 /* The linker's interface for specifying that reordering of sections is
0402    desired so that the linker can prepare for it.  This should be invoked
0403    before update_section_order, preferably in the claim_file handler.  */
0404
0405 typedef
0406 enum ld_plugin_status
0407 (*ld_plugin_allow_section_ordering) (void);
0408
0409 /* The linker's interface for specifying that a subset of sections is
0410    to be mapped to a unique segment.  If the plugin wants to call
0411    unique_segment_for_sections, it must call this function from a
0412    claim_file_handler or when it is first loaded.  */
0413
0414 typedef
0415 enum ld_plugin_status
0416 (*ld_plugin_allow_unique_segment_for_sections) (void);
0417
0418 /* The linker's interface for specifying that a specific set of sections
0419    must be mapped to a unique segment.  ELF segments do not have names
0420    and the NAME is used as the name of the newly created output section
0421    that is then placed in the unique PT_LOAD segment.  FLAGS is used to
0422    specify if any additional segment flags need to be set.  For instance,
0423    a specific segment flag can be set to identify this segment.  Unsetting
0424    segment flags that would be set by default is not possible.  The
0425    parameter SEGMENT_ALIGNMENT when non-zero will override the default.  */
0426
0427 typedef
0428 enum ld_plugin_status
0429 (*ld_plugin_unique_segment_for_sections) (
0430     const char* segment_name,
0431     uint64_t segment_flags,
0432     uint64_t segment_alignment,
0433     const struct ld_plugin_section * section_list,
0434     unsigned int num_sections);
0435
0436 /* The linker's interface for retrieving the section alignment requirement
0437    of a specific section in an object.  This interface should only be invoked in the
0438    claim_file handler.  This function sets *ADDRALIGN to the ELF sh_addralign
0439    value of the input section.  */
0440
0441 typedef
0442 enum ld_plugin_status
0443 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section,
0444                                           unsigned int *addralign);
0445
0446 /* The linker's interface for retrieving the section size of a specific section
0447    in an object.  This interface should only be invoked in the claim_file handler.
0448    This function sets *SECSIZE to the ELF sh_size
0449    value of the input section.  */
0450
0451 typedef
0452 enum ld_plugin_status
0453 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
0454                                      uint64_t *secsize);
0455
0456 typedef
0457 enum ld_plugin_status
0458 (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file);
0459
0460 /* The linker's interface for registering the "new_input" handler. This handler
0461    will be notified when a new input file has been added after the
0462    all_symbols_read event, allowing the plugin to, for example, set a unique
0463    segment for sections in plugin-generated input files. */
0464
0465 typedef
0466 enum ld_plugin_status
0467 (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler);
0468
0469 /* The linker's interface for getting the list of wrapped symbols using the
0470    --wrap option. This sets *NUM_SYMBOLS to number of wrapped symbols and
0471    *WRAP_SYMBOL_LIST to the list of wrapped symbols. */
0472
0473 typedef
0474 enum ld_plugin_status
0475 (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols,
0476                                const char ***wrap_symbol_list);
0477
0478 enum ld_plugin_level
0479 {
0480   LDPL_INFO,
0481   LDPL_WARNING,
0482   LDPL_ERROR,
0483   LDPL_FATAL
0484 };
0485
0486 /* Values for the tv_tag field of the transfer vector.  */
0487
0488 enum ld_plugin_tag
0489 {
0490   LDPT_NULL = 0,
0491   LDPT_API_VERSION = 1,
0492   LDPT_GOLD_VERSION = 2,
0493   LDPT_LINKER_OUTPUT = 3,
0494   LDPT_OPTION = 4,
0495   LDPT_REGISTER_CLAIM_FILE_HOOK = 5,
0496   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6,
0497   LDPT_REGISTER_CLEANUP_HOOK = 7,
0498   LDPT_ADD_SYMBOLS = 8,
0499   LDPT_GET_SYMBOLS = 9,
0500   LDPT_ADD_INPUT_FILE = 10,
0501   LDPT_MESSAGE = 11,
0502   LDPT_GET_INPUT_FILE = 12,
0503   LDPT_RELEASE_INPUT_FILE = 13,
0504   LDPT_ADD_INPUT_LIBRARY = 14,
0505   LDPT_OUTPUT_NAME = 15,
0506   LDPT_SET_EXTRA_LIBRARY_PATH = 16,
0507   LDPT_GNU_LD_VERSION = 17,
0508   LDPT_GET_VIEW = 18,
0509   LDPT_GET_INPUT_SECTION_COUNT = 19,
0510   LDPT_GET_INPUT_SECTION_TYPE = 20,
0511   LDPT_GET_INPUT_SECTION_NAME = 21,
0512   LDPT_GET_INPUT_SECTION_CONTENTS = 22,
0513   LDPT_UPDATE_SECTION_ORDER = 23,
0514   LDPT_ALLOW_SECTION_ORDERING = 24,
0515   LDPT_GET_SYMBOLS_V2 = 25,
0516   LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26,
0517   LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27,
0518   LDPT_GET_SYMBOLS_V3 = 28,
0519   LDPT_GET_INPUT_SECTION_ALIGNMENT = 29,
0520   LDPT_GET_INPUT_SECTION_SIZE = 30,
0521   LDPT_REGISTER_NEW_INPUT_HOOK = 31,
0522   LDPT_GET_WRAP_SYMBOLS = 32,
0523   LDPT_ADD_SYMBOLS_V2 = 33
0524 };
0525
0526 /* The plugin transfer vector.  */
0527
0528 struct ld_plugin_tv
0529 {
0530   enum ld_plugin_tag tv_tag;
0531   union
0532   {
0533     int tv_val;
0534     const char *tv_string;
0535     ld_plugin_register_claim_file tv_register_claim_file;
0536     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
0537     ld_plugin_register_cleanup tv_register_cleanup;
0538     ld_plugin_add_symbols tv_add_symbols;
0539     ld_plugin_get_symbols tv_get_symbols;
0540     ld_plugin_add_input_file tv_add_input_file;
0541     ld_plugin_message tv_message;
0542     ld_plugin_get_input_file tv_get_input_file;
0543     ld_plugin_get_view tv_get_view;
0544     ld_plugin_release_input_file tv_release_input_file;
0545     ld_plugin_add_input_library tv_add_input_library;
0546     ld_plugin_set_extra_library_path tv_set_extra_library_path;
0547     ld_plugin_get_input_section_count tv_get_input_section_count;
0548     ld_plugin_get_input_section_type tv_get_input_section_type;
0549     ld_plugin_get_input_section_name tv_get_input_section_name;
0550     ld_plugin_get_input_section_contents tv_get_input_section_contents;
0551     ld_plugin_update_section_order tv_update_section_order;
0552     ld_plugin_allow_section_ordering tv_allow_section_ordering;
0553     ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections;
0554     ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections;
0555     ld_plugin_get_input_section_alignment tv_get_input_section_alignment;
0556     ld_plugin_get_input_section_size tv_get_input_section_size;
0557     ld_plugin_register_new_input tv_register_new_input;
0558     ld_plugin_get_wrap_symbols tv_get_wrap_symbols;
0559   } tv_u;
0560 };
0561
0562 /* The plugin library's "onload" entry point.  */
0563
0564 typedef
0565 enum ld_plugin_status
0566 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
0567
0568 #ifdef __cplusplus
0569 }
0570 #endif
0571
0572 #endif /* !defined(PLUGIN_API_H) */