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 };
  71
  72 /* An input file managed by the plugin library.  */
  73
  74 struct ld_plugin_input_file
  75 {
  76   const char *name;
  77   int fd;
  78   off_t offset;
  79   off_t filesize;
  80   void *handle;
  81 };
  82
  83 /* A symbol belonging to an input file managed by the plugin library.  */
  84
  85 struct ld_plugin_symbol
  86 {
  87   char *name;
  88   char *version;
  89   int def;
  90   int visibility;
  91   uint64_t size;
  92   char *comdat_key;
  93   int resolution;
  94 };
  95
  96 /* An object's section.  */
  97
  98 struct ld_plugin_section
  99 {
 100   const void* handle;
 101   unsigned int shndx;
 102 };
 103
 104 /* Whether the symbol is a definition, reference, or common, weak or not.  */
 105
 106 enum ld_plugin_symbol_kind
 107 {
 108   LDPK_DEF,
 109   LDPK_WEAKDEF,
 110   LDPK_UNDEF,
 111   LDPK_WEAKUNDEF,
 112   LDPK_COMMON
 113 };
 114
 115 /* The visibility of the symbol.  */
 116
 117 enum ld_plugin_symbol_visibility
 118 {
 119   LDPV_DEFAULT,
 120   LDPV_PROTECTED,
 121   LDPV_INTERNAL,
 122   LDPV_HIDDEN
 123 };
 124
 125 /* How a symbol is resolved.  */
 126
 127 enum ld_plugin_symbol_resolution
 128 {
 129   LDPR_UNKNOWN = 0,
 130
 131   /* Symbol is still undefined at this point.  */
 132   LDPR_UNDEF,
 133
 134   /* This is the prevailing definition of the symbol, with references from
 135      regular object code.  */
 136   LDPR_PREVAILING_DEF,
 137
 138   /* This is the prevailing definition of the symbol, with no
 139      references from regular objects.  It is only referenced from IR
 140      code.  */
 141   LDPR_PREVAILING_DEF_IRONLY,
 142
 143   /* This definition was pre-empted by a definition in a regular
 144      object file.  */
 145   LDPR_PREEMPTED_REG,
 146
 147   /* This definition was pre-empted by a definition in another IR file.  */
 148   LDPR_PREEMPTED_IR,
 149
 150   /* This symbol was resolved by a definition in another IR file.  */
 151   LDPR_RESOLVED_IR,
 152
 153   /* This symbol was resolved by a definition in a regular object
 154      linked into the main executable.  */
 155   LDPR_RESOLVED_EXEC,
 156
 157   /* This symbol was resolved by a definition in a shared object.  */
 158   LDPR_RESOLVED_DYN
 159 };
 160
 161 /* The plugin library's "claim file" handler.  */
 162
 163 typedef
 164 enum ld_plugin_status
 165 (*ld_plugin_claim_file_handler) (
 166   const struct ld_plugin_input_file *file, int *claimed);
 167
 168 /* The plugin library's "all symbols read" handler.  */
 169
 170 typedef
 171 enum ld_plugin_status
 172 (*ld_plugin_all_symbols_read_handler) (void);
 173
 174 /* The plugin library's cleanup handler.  */
 175
 176 typedef
 177 enum ld_plugin_status
 178 (*ld_plugin_cleanup_handler) (void);
 179
 180 /* The linker's interface for registering the "claim file" handler.  */
 181
 182 typedef
 183 enum ld_plugin_status
 184 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
 185
 186 /* The linker's interface for registering the "all symbols read" handler.  */
 187
 188 typedef
 189 enum ld_plugin_status
 190 (*ld_plugin_register_all_symbols_read) (
 191   ld_plugin_all_symbols_read_handler handler);
 192
 193 /* The linker's interface for registering the cleanup handler.  */
 194
 195 typedef
 196 enum ld_plugin_status
 197 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
 198
 199 /* The linker's interface for adding symbols from a claimed input file.  */
 200
 201 typedef
 202 enum ld_plugin_status
 203 (*ld_plugin_add_symbols) (void *handle, int nsyms,
 204                           const struct ld_plugin_symbol *syms);
 205
 206 /* The linker's interface for getting the input file information with
 207    an open (possibly re-opened) file descriptor.  */
 208
 209 typedef
 210 enum ld_plugin_status
 211 (*ld_plugin_get_input_file) (const void *handle,
 212                              struct ld_plugin_input_file *file);
 213
 214 typedef
 215 enum ld_plugin_status
 216 (*ld_plugin_get_view) (const void *handle, const void **viewp);
 217
 218 /* The linker's interface for releasing the input file.  */
 219
 220 typedef
 221 enum ld_plugin_status
 222 (*ld_plugin_release_input_file) (const void *handle);
 223
 224 /* The linker's interface for retrieving symbol resolution information.  */
 225
 226 typedef
 227 enum ld_plugin_status
 228 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
 229                           struct ld_plugin_symbol *syms);
 230
 231 /* The linker's interface for adding a compiled input file.  */
 232
 233 typedef
 234 enum ld_plugin_status
 235 (*ld_plugin_add_input_file) (const char *pathname);
 236
 237 /* The linker's interface for adding a library that should be searched.  */
 238
 239 typedef
 240 enum ld_plugin_status
 241 (*ld_plugin_add_input_library) (const char *libname);
 242
 243 /* The linker's interface for adding a library path that should be searched.  */
 244
 245 typedef
 246 enum ld_plugin_status
 247 (*ld_plugin_set_extra_library_path) (const char *path);
 248
 249 /* The linker's interface for issuing a warning or error message.  */
 250
 251 typedef
 252 enum ld_plugin_status
 253 (*ld_plugin_message) (int level, const char *format, ...);
 254
 255 /* The linker's interface for retrieving the number of sections in an object.
 256    The handle is obtained in the claim_file handler.  This interface should
 257    only be invoked in the claim_file handler.   This function sets *COUNT to
 258    the number of sections in the object.  */
 259
 260 typedef
 261 enum ld_plugin_status
 262 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
 263
 264 /* The linker's interface for retrieving the section type of a specific
 265    section in an object.  This interface should only be invoked in the
 266    claim_file handler.  This function sets *TYPE to an ELF SHT_xxx value.  */
 267
 268 typedef
 269 enum ld_plugin_status
 270 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
 271                                      unsigned int *type);
 272
 273 /* The linker's interface for retrieving the name of a specific section in
 274    an object. This interface should only be invoked in the claim_file handler.
 275    This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
 276    by malloc.  The plugin must free *SECTION_NAME_PTR.  */
 277
 278 typedef
 279 enum ld_plugin_status
 280 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
 281                                      char **section_name_ptr);
 282
 283 /* The linker's interface for retrieving the contents of a specific section
 284    in an object.  This interface should only be invoked in the claim_file
 285    handler.  This function sets *SECTION_CONTENTS to point to a buffer that is
 286    valid until clam_file handler returns.  It sets *LEN to the size of the
 287    buffer.  */
 288
 289 typedef
 290 enum ld_plugin_status
 291 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
 292                                          const unsigned char **section_contents,
 293                                          size_t* len);
 294
 295 /* The linker's interface for specifying the desired order of sections.
 296    The sections should be specifed using the array SECTION_LIST in the
 297    order in which they should appear in the final layout.  NUM_SECTIONS
 298    specifies the number of entries in each array.  This should be invoked
 299    in the all_symbols_read handler.  */
 300
 301 typedef
 302 enum ld_plugin_status
 303 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
 304                                    unsigned int num_sections);
 305
 306 /* The linker's interface for specifying that reordering of sections is
 307    desired so that the linker can prepare for it.  This should be invoked
 308    before update_section_order, preferably in the claim_file handler.  */
 309
 310 typedef
 311 enum ld_plugin_status
 312 (*ld_plugin_allow_section_ordering) (void);
 313
 314 enum ld_plugin_level
 315 {
 316   LDPL_INFO,
 317   LDPL_WARNING,
 318   LDPL_ERROR,
 319   LDPL_FATAL
 320 };
 321
 322 /* Values for the tv_tag field of the transfer vector.  */
 323
 324 enum ld_plugin_tag
 325 {
 326   LDPT_NULL = 0,
 327   LDPT_API_VERSION,
 328   LDPT_GOLD_VERSION,
 329   LDPT_LINKER_OUTPUT,
 330   LDPT_OPTION,
 331   LDPT_REGISTER_CLAIM_FILE_HOOK,
 332   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
 333   LDPT_REGISTER_CLEANUP_HOOK,
 334   LDPT_ADD_SYMBOLS,
 335   LDPT_GET_SYMBOLS,
 336   LDPT_ADD_INPUT_FILE,
 337   LDPT_MESSAGE,
 338   LDPT_GET_INPUT_FILE,
 339   LDPT_RELEASE_INPUT_FILE,
 340   LDPT_ADD_INPUT_LIBRARY,
 341   LDPT_OUTPUT_NAME,
 342   LDPT_SET_EXTRA_LIBRARY_PATH,
 343   LDPT_GNU_LD_VERSION,
 344   LDPT_GET_VIEW,
 345   LDPT_GET_INPUT_SECTION_COUNT,
 346   LDPT_GET_INPUT_SECTION_TYPE,
 347   LDPT_GET_INPUT_SECTION_NAME,
 348   LDPT_GET_INPUT_SECTION_CONTENTS,
 349   LDPT_UPDATE_SECTION_ORDER,
 350   LDPT_ALLOW_SECTION_ORDERING
 351 };
 352
 353 /* The plugin transfer vector.  */
 354
 355 struct ld_plugin_tv
 356 {
 357   enum ld_plugin_tag tv_tag;
 358   union
 359   {
 360     int tv_val;
 361     const char *tv_string;
 362     ld_plugin_register_claim_file tv_register_claim_file;
 363     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
 364     ld_plugin_register_cleanup tv_register_cleanup;
 365     ld_plugin_add_symbols tv_add_symbols;
 366     ld_plugin_get_symbols tv_get_symbols;
 367     ld_plugin_add_input_file tv_add_input_file;
 368     ld_plugin_message tv_message;
 369     ld_plugin_get_input_file tv_get_input_file;
 370     ld_plugin_get_view tv_get_view;
 371     ld_plugin_release_input_file tv_release_input_file;
 372     ld_plugin_add_input_library tv_add_input_library;
 373     ld_plugin_set_extra_library_path tv_set_extra_library_path;
 374     ld_plugin_get_input_section_count tv_get_input_section_count;
 375     ld_plugin_get_input_section_type tv_get_input_section_type;
 376     ld_plugin_get_input_section_name tv_get_input_section_name;
 377     ld_plugin_get_input_section_contents tv_get_input_section_contents;
 378     ld_plugin_update_section_order tv_update_section_order;
 379     ld_plugin_allow_section_ordering tv_allow_section_ordering;
 380   } tv_u;
 381 };
 382
 383 /* The plugin library's "onload" entry point.  */
 384
 385 typedef
 386 enum ld_plugin_status
 387 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
 388
 389 #ifdef __cplusplus
 390 }
 391 #endif
 392
 393 #endif /* !defined(PLUGIN_API_H) */