include/plugin-api.h

   1 /* plugin-api.h -- External linker plugin API.  */
   2
   3 /* Copyright 2009, 2010 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 can not find uint64_t type
  38 #endif
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #endif
  44
  45 /* Status code returned by most API routines.  */
  46
  47 enum ld_plugin_status
  48 {
  49   LDPS_OK = 0,
  50   LDPS_NO_SYMS,         /* Attempt to get symbols that haven't been added. */
  51   LDPS_BAD_HANDLE,      /* No claimed object associated with given handle. */
  52   LDPS_ERR
  53   /* Additional Error codes TBD.  */
  54 };
  55
  56 /* The version of the API specification.  */
  57
  58 enum ld_plugin_api_version
  59 {
  60   LD_PLUGIN_API_VERSION = 1
  61 };
  62
  63 /* The type of output file being generated by the linker.  */
  64
  65 enum ld_plugin_output_file_type
  66 {
  67   LDPO_REL,
  68   LDPO_EXEC,
  69   LDPO_DYN,
  70   LDPO_PIE
  71 };
  72
  73 /* An input file managed by the plugin library.  */
  74
  75 struct ld_plugin_input_file
  76 {
  77   const char *name;
  78   int fd;
  79   off_t offset;
  80   off_t filesize;
  81   void *handle;
  82 };
  83
  84 /* A symbol belonging to an input file managed by the plugin library.  */
  85
  86 struct ld_plugin_symbol
  87 {
  88   char *name;
  89   char *version;
  90   int def;
  91   int visibility;
  92   uint64_t size;
  93   char *comdat_key;
  94   int resolution;
  95 };
  96
  97 /* An object's section.  */
  98
  99 struct ld_plugin_section
 100 {
 101   const void* handle;
 102   unsigned int shndx;
 103 };
 104
 105 /* Whether the symbol is a definition, reference, or common, weak or not.  */
 106
 107 enum ld_plugin_symbol_kind
 108 {
 109   LDPK_DEF,
 110   LDPK_WEAKDEF,
 111   LDPK_UNDEF,
 112   LDPK_WEAKUNDEF,
 113   LDPK_COMMON
 114 };
 115
 116 /* The visibility of the symbol.  */
 117
 118 enum ld_plugin_symbol_visibility
 119 {
 120   LDPV_DEFAULT,
 121   LDPV_PROTECTED,
 122   LDPV_INTERNAL,
 123   LDPV_HIDDEN
 124 };
 125
 126 /* How a symbol is resolved.  */
 127
 128 enum ld_plugin_symbol_resolution
 129 {
 130   LDPR_UNKNOWN = 0,
 131
 132   /* Symbol is still undefined at this point.  */
 133   LDPR_UNDEF,
 134
 135   /* This is the prevailing definition of the symbol, with references from
 136      regular object code.  */
 137   LDPR_PREVAILING_DEF,
 138
 139   /* This is the prevailing definition of the symbol, with no
 140      references from regular objects.  It is only referenced from IR
 141      code.  */
 142   LDPR_PREVAILING_DEF_IRONLY,
 143
 144   /* This definition was pre-empted by a definition in a regular
 145      object file.  */
 146   LDPR_PREEMPTED_REG,
 147
 148   /* This definition was pre-empted by a definition in another IR file.  */
 149   LDPR_PREEMPTED_IR,
 150
 151   /* This symbol was resolved by a definition in another IR file.  */
 152   LDPR_RESOLVED_IR,
 153
 154   /* This symbol was resolved by a definition in a regular object
 155      linked into the main executable.  */
 156   LDPR_RESOLVED_EXEC,
 157
 158   /* This symbol was resolved by a definition in a shared object.  */
 159   LDPR_RESOLVED_DYN,
 160
 161   /* This is the prevailing definition of the symbol, with no
 162      references from regular objects.  It is only referenced from IR
 163      code, but the symbol is exported and may be referenced from
 164      a dynamic object (not seen at link time).  */
 165   LDPR_PREVAILING_DEF_IRONLY_EXP
 166 };
 167
 168 /* The plugin library's "claim file" handler.  */
 169
 170 typedef
 171 enum ld_plugin_status
 172 (*ld_plugin_claim_file_handler) (
 173   const struct ld_plugin_input_file *file, int *claimed);
 174
 175 /* The plugin library's "all symbols read" handler.  */
 176
 177 typedef
 178 enum ld_plugin_status
 179 (*ld_plugin_all_symbols_read_handler) (void);
 180
 181 /* The plugin library's cleanup handler.  */
 182
 183 typedef
 184 enum ld_plugin_status
 185 (*ld_plugin_cleanup_handler) (void);
 186
 187 /* The linker's interface for registering the "claim file" handler.  */
 188
 189 typedef
 190 enum ld_plugin_status
 191 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
 192
 193 /* The linker's interface for registering the "all symbols read" handler.  */
 194
 195 typedef
 196 enum ld_plugin_status
 197 (*ld_plugin_register_all_symbols_read) (
 198   ld_plugin_all_symbols_read_handler handler);
 199
 200 /* The linker's interface for registering the cleanup handler.  */
 201
 202 typedef
 203 enum ld_plugin_status
 204 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
 205
 206 /* The linker's interface for adding symbols from a claimed input file.  */
 207
 208 typedef
 209 enum ld_plugin_status
 210 (*ld_plugin_add_symbols) (void *handle, int nsyms,
 211                           const struct ld_plugin_symbol *syms);
 212
 213 /* The linker's interface for getting the input file information with
 214    an open (possibly re-opened) file descriptor.  */
 215
 216 typedef
 217 enum ld_plugin_status
 218 (*ld_plugin_get_input_file) (const void *handle,
 219                              struct ld_plugin_input_file *file);
 220
 221 typedef
 222 enum ld_plugin_status
 223 (*ld_plugin_get_view) (const void *handle, const void **viewp);
 224
 225 /* The linker's interface for releasing the input file.  */
 226
 227 typedef
 228 enum ld_plugin_status
 229 (*ld_plugin_release_input_file) (const void *handle);
 230
 231 /* The linker's interface for retrieving symbol resolution information.  */
 232
 233 typedef
 234 enum ld_plugin_status
 235 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
 236                           struct ld_plugin_symbol *syms);
 237
 238 /* The linker's interface for adding a compiled input file.  */
 239
 240 typedef
 241 enum ld_plugin_status
 242 (*ld_plugin_add_input_file) (const char *pathname);
 243
 244 /* The linker's interface for adding a library that should be searched.  */
 245
 246 typedef
 247 enum ld_plugin_status
 248 (*ld_plugin_add_input_library) (const char *libname);
 249
 250 /* The linker's interface for adding a library path that should be searched.  */
 251
 252 typedef
 253 enum ld_plugin_status
 254 (*ld_plugin_set_extra_library_path) (const char *path);
 255
 256 /* The linker's interface for issuing a warning or error message.  */
 257
 258 typedef
 259 enum ld_plugin_status
 260 (*ld_plugin_message) (int level, const char *format, ...);
 261
 262 /* The linker's interface for retrieving the number of sections in an object.
 263    The handle is obtained in the claim_file handler.  This interface should
 264    only be invoked in the claim_file handler.   This function sets *COUNT to
 265    the number of sections in the object.  */
 266
 267 typedef
 268 enum ld_plugin_status
 269 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
 270
 271 /* The linker's interface for retrieving the section type of a specific
 272    section in an object.  This interface should only be invoked in the
 273    claim_file handler.  This function sets *TYPE to an ELF SHT_xxx value.  */
 274
 275 typedef
 276 enum ld_plugin_status
 277 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
 278                                      unsigned int *type);
 279
 280 /* The linker's interface for retrieving the name of a specific section in
 281    an object. This interface should only be invoked in the claim_file handler.
 282    This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
 283    by malloc.  The plugin must free *SECTION_NAME_PTR.  */
 284
 285 typedef
 286 enum ld_plugin_status
 287 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
 288                                      char **section_name_ptr);
 289
 290 /* The linker's interface for retrieving the contents of a specific section
 291    in an object.  This interface should only be invoked in the claim_file
 292    handler.  This function sets *SECTION_CONTENTS to point to a buffer that is
 293    valid until clam_file handler returns.  It sets *LEN to the size of the
 294    buffer.  */
 295
 296 typedef
 297 enum ld_plugin_status
 298 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
 299                                          const unsigned char **section_contents,
 300                                          size_t* len);
 301
 302 /* The linker's interface for specifying the desired order of sections.
 303    The sections should be specifed using the array SECTION_LIST in the
 304    order in which they should appear in the final layout.  NUM_SECTIONS
 305    specifies the number of entries in each array.  This should be invoked
 306    in the all_symbols_read handler.  */
 307
 308 typedef
 309 enum ld_plugin_status
 310 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
 311                                    unsigned int num_sections);
 312
 313 /* The linker's interface for specifying that reordering of sections is
 314    desired so that the linker can prepare for it.  This should be invoked
 315    before update_section_order, preferably in the claim_file handler.  */
 316
 317 typedef
 318 enum ld_plugin_status
 319 (*ld_plugin_allow_section_ordering) (void);
 320
 321 /* The linker's interface for specifying that a subset of sections is
 322    to be mapped to a unique segment.  If the plugin wants to call
 323    unique_segment_for_sections, it must call this function from a
 324    claim_file_handler or when it is first loaded.  */
 325
 326 typedef
 327 enum ld_plugin_status
 328 (*ld_plugin_allow_unique_segment_for_sections) (void);
 329
 330 /* The linker's interface for specifying that a specific set of sections
 331    must be mapped to a unique segment.  ELF segments do not have names
 332    and the NAME is used as the name of the newly created output section
 333    that is then placed in the unique PT_LOAD segment.  FLAGS is used to
 334    specify if any additional segment flags need to be set.  For instance,
 335    a specific segment flag can be set to identify this segment.  Unsetting
 336    segment flags that would be set by default is not possible.  The
 337    parameter SEGMENT_ALIGNMENT when non-zero will override the default.  */
 338
 339 typedef
 340 enum ld_plugin_status
 341 (*ld_plugin_unique_segment_for_sections) (
 342     const char* segment_name,
 343     uint64_t segment_flags,
 344     uint64_t segment_alignment,
 345     const struct ld_plugin_section * section_list,
 346     unsigned int num_sections);
 347
 348 enum ld_plugin_level
 349 {
 350   LDPL_INFO,
 351   LDPL_WARNING,
 352   LDPL_ERROR,
 353   LDPL_FATAL
 354 };
 355
 356 /* Values for the tv_tag field of the transfer vector.  */
 357
 358 enum ld_plugin_tag
 359 {
 360   LDPT_NULL = 0,
 361   LDPT_API_VERSION = 1,
 362   LDPT_GOLD_VERSION = 2,
 363   LDPT_LINKER_OUTPUT = 3,
 364   LDPT_OPTION = 4,
 365   LDPT_REGISTER_CLAIM_FILE_HOOK = 5,
 366   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6,
 367   LDPT_REGISTER_CLEANUP_HOOK = 7,
 368   LDPT_ADD_SYMBOLS = 8,
 369   LDPT_GET_SYMBOLS = 9,
 370   LDPT_ADD_INPUT_FILE = 10,
 371   LDPT_MESSAGE = 11,
 372   LDPT_GET_INPUT_FILE = 12,
 373   LDPT_RELEASE_INPUT_FILE = 13,
 374   LDPT_ADD_INPUT_LIBRARY = 14,
 375   LDPT_OUTPUT_NAME = 15,
 376   LDPT_SET_EXTRA_LIBRARY_PATH = 16,
 377   LDPT_GNU_LD_VERSION = 17,
 378   LDPT_GET_VIEW = 18,
 379   LDPT_GET_INPUT_SECTION_COUNT = 19,
 380   LDPT_GET_INPUT_SECTION_TYPE = 20,
 381   LDPT_GET_INPUT_SECTION_NAME = 21,
 382   LDPT_GET_INPUT_SECTION_CONTENTS = 22,
 383   LDPT_UPDATE_SECTION_ORDER = 23,
 384   LDPT_ALLOW_SECTION_ORDERING = 24,
 385   LDPT_GET_SYMBOLS_V2 = 25,
 386   LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26,
 387   LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27
 388 };
 389
 390 /* The plugin transfer vector.  */
 391
 392 struct ld_plugin_tv
 393 {
 394   enum ld_plugin_tag tv_tag;
 395   union
 396   {
 397     int tv_val;
 398     const char *tv_string;
 399     ld_plugin_register_claim_file tv_register_claim_file;
 400     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
 401     ld_plugin_register_cleanup tv_register_cleanup;
 402     ld_plugin_add_symbols tv_add_symbols;
 403     ld_plugin_get_symbols tv_get_symbols;
 404     ld_plugin_add_input_file tv_add_input_file;
 405     ld_plugin_message tv_message;
 406     ld_plugin_get_input_file tv_get_input_file;
 407     ld_plugin_get_view tv_get_view;
 408     ld_plugin_release_input_file tv_release_input_file;
 409     ld_plugin_add_input_library tv_add_input_library;
 410     ld_plugin_set_extra_library_path tv_set_extra_library_path;
 411     ld_plugin_get_input_section_count tv_get_input_section_count;
 412     ld_plugin_get_input_section_type tv_get_input_section_type;
 413     ld_plugin_get_input_section_name tv_get_input_section_name;
 414     ld_plugin_get_input_section_contents tv_get_input_section_contents;
 415     ld_plugin_update_section_order tv_update_section_order;
 416     ld_plugin_allow_section_ordering tv_allow_section_ordering;
 417     ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections;
 418     ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections;
 419   } tv_u;
 420 };
 421
 422 /* The plugin library's "onload" entry point.  */
 423
 424 typedef
 425 enum ld_plugin_status
 426 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
 427
 428 #ifdef __cplusplus
 429 }
 430 #endif
 431
 432 #endif /* !defined(PLUGIN_API_H) */