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   /* This is the prevailing definition of the symbol, with no
 161      references from regular objects.  It is only referenced from IR
 162      code, but the symbol is exported and may be referenced from
 163      a dynamic object (not seen at link time).  */
 164   LDPR_PREVAILING_DEF_IRONLY_EXP
 165 };
 166
 167 /* The plugin library's "claim file" handler.  */
 168
 169 typedef
 170 enum ld_plugin_status
 171 (*ld_plugin_claim_file_handler) (
 172   const struct ld_plugin_input_file *file, int *claimed);
 173
 174 /* The plugin library's "all symbols read" handler.  */
 175
 176 typedef
 177 enum ld_plugin_status
 178 (*ld_plugin_all_symbols_read_handler) (void);
 179
 180 /* The plugin library's cleanup handler.  */
 181
 182 typedef
 183 enum ld_plugin_status
 184 (*ld_plugin_cleanup_handler) (void);
 185
 186 /* The linker's interface for registering the "claim file" handler.  */
 187
 188 typedef
 189 enum ld_plugin_status
 190 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
 191
 192 /* The linker's interface for registering the "all symbols read" handler.  */
 193
 194 typedef
 195 enum ld_plugin_status
 196 (*ld_plugin_register_all_symbols_read) (
 197   ld_plugin_all_symbols_read_handler handler);
 198
 199 /* The linker's interface for registering the cleanup handler.  */
 200
 201 typedef
 202 enum ld_plugin_status
 203 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
 204
 205 /* The linker's interface for adding symbols from a claimed input file.  */
 206
 207 typedef
 208 enum ld_plugin_status
 209 (*ld_plugin_add_symbols) (void *handle, int nsyms,
 210                           const struct ld_plugin_symbol *syms);
 211
 212 /* The linker's interface for getting the input file information with
 213    an open (possibly re-opened) file descriptor.  */
 214
 215 typedef
 216 enum ld_plugin_status
 217 (*ld_plugin_get_input_file) (const void *handle,
 218                              struct ld_plugin_input_file *file);
 219
 220 typedef
 221 enum ld_plugin_status
 222 (*ld_plugin_get_view) (const void *handle, const void **viewp);
 223
 224 /* The linker's interface for releasing the input file.  */
 225
 226 typedef
 227 enum ld_plugin_status
 228 (*ld_plugin_release_input_file) (const void *handle);
 229
 230 /* The linker's interface for retrieving symbol resolution information.  */
 231
 232 typedef
 233 enum ld_plugin_status
 234 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
 235                           struct ld_plugin_symbol *syms);
 236
 237 /* The linker's interface for adding a compiled input file.  */
 238
 239 typedef
 240 enum ld_plugin_status
 241 (*ld_plugin_add_input_file) (const char *pathname);
 242
 243 /* The linker's interface for adding a library that should be searched.  */
 244
 245 typedef
 246 enum ld_plugin_status
 247 (*ld_plugin_add_input_library) (const char *libname);
 248
 249 /* The linker's interface for adding a library path that should be searched.  */
 250
 251 typedef
 252 enum ld_plugin_status
 253 (*ld_plugin_set_extra_library_path) (const char *path);
 254
 255 /* The linker's interface for issuing a warning or error message.  */
 256
 257 typedef
 258 enum ld_plugin_status
 259 (*ld_plugin_message) (int level, const char *format, ...);
 260
 261 /* The linker's interface for retrieving the number of sections in an object.
 262    The handle is obtained in the claim_file handler.  This interface should
 263    only be invoked in the claim_file handler.   This function sets *COUNT to
 264    the number of sections in the object.  */
 265
 266 typedef
 267 enum ld_plugin_status
 268 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
 269
 270 /* The linker's interface for retrieving the section type of a specific
 271    section in an object.  This interface should only be invoked in the
 272    claim_file handler.  This function sets *TYPE to an ELF SHT_xxx value.  */
 273
 274 typedef
 275 enum ld_plugin_status
 276 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
 277                                      unsigned int *type);
 278
 279 /* The linker's interface for retrieving the name of a specific section in
 280    an object. This interface should only be invoked in the claim_file handler.
 281    This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
 282    by malloc.  The plugin must free *SECTION_NAME_PTR.  */
 283
 284 typedef
 285 enum ld_plugin_status
 286 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
 287                                      char **section_name_ptr);
 288
 289 /* The linker's interface for retrieving the contents of a specific section
 290    in an object.  This interface should only be invoked in the claim_file
 291    handler.  This function sets *SECTION_CONTENTS to point to a buffer that is
 292    valid until clam_file handler returns.  It sets *LEN to the size of the
 293    buffer.  */
 294
 295 typedef
 296 enum ld_plugin_status
 297 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
 298                                          const unsigned char **section_contents,
 299                                          size_t* len);
 300
 301 /* The linker's interface for specifying the desired order of sections.
 302    The sections should be specifed using the array SECTION_LIST in the
 303    order in which they should appear in the final layout.  NUM_SECTIONS
 304    specifies the number of entries in each array.  This should be invoked
 305    in the all_symbols_read handler.  */
 306
 307 typedef
 308 enum ld_plugin_status
 309 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
 310                                    unsigned int num_sections);
 311
 312 /* The linker's interface for specifying that reordering of sections is
 313    desired so that the linker can prepare for it.  This should be invoked
 314    before update_section_order, preferably in the claim_file handler.  */
 315
 316 typedef
 317 enum ld_plugin_status
 318 (*ld_plugin_allow_section_ordering) (void);
 319
 320 enum ld_plugin_level
 321 {
 322   LDPL_INFO,
 323   LDPL_WARNING,
 324   LDPL_ERROR,
 325   LDPL_FATAL
 326 };
 327
 328 /* Values for the tv_tag field of the transfer vector.  */
 329
 330 enum ld_plugin_tag
 331 {
 332   LDPT_NULL = 0,
 333   LDPT_API_VERSION,
 334   LDPT_GOLD_VERSION,
 335   LDPT_LINKER_OUTPUT,
 336   LDPT_OPTION,
 337   LDPT_REGISTER_CLAIM_FILE_HOOK,
 338   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
 339   LDPT_REGISTER_CLEANUP_HOOK,
 340   LDPT_ADD_SYMBOLS,
 341   LDPT_GET_SYMBOLS,
 342   LDPT_ADD_INPUT_FILE,
 343   LDPT_MESSAGE,
 344   LDPT_GET_INPUT_FILE,
 345   LDPT_RELEASE_INPUT_FILE,
 346   LDPT_ADD_INPUT_LIBRARY,
 347   LDPT_OUTPUT_NAME,
 348   LDPT_SET_EXTRA_LIBRARY_PATH,
 349   LDPT_GNU_LD_VERSION,
 350   LDPT_GET_VIEW,
 351   LDPT_GET_INPUT_SECTION_COUNT,
 352   LDPT_GET_INPUT_SECTION_TYPE,
 353   LDPT_GET_INPUT_SECTION_NAME,
 354   LDPT_GET_INPUT_SECTION_CONTENTS,
 355   LDPT_UPDATE_SECTION_ORDER,
 356   LDPT_ALLOW_SECTION_ORDERING,
 357   LDPT_GET_SYMBOLS_V2
 358 };
 359
 360 /* The plugin transfer vector.  */
 361
 362 struct ld_plugin_tv
 363 {
 364   enum ld_plugin_tag tv_tag;
 365   union
 366   {
 367     int tv_val;
 368     const char *tv_string;
 369     ld_plugin_register_claim_file tv_register_claim_file;
 370     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
 371     ld_plugin_register_cleanup tv_register_cleanup;
 372     ld_plugin_add_symbols tv_add_symbols;
 373     ld_plugin_get_symbols tv_get_symbols;
 374     ld_plugin_add_input_file tv_add_input_file;
 375     ld_plugin_message tv_message;
 376     ld_plugin_get_input_file tv_get_input_file;
 377     ld_plugin_get_view tv_get_view;
 378     ld_plugin_release_input_file tv_release_input_file;
 379     ld_plugin_add_input_library tv_add_input_library;
 380     ld_plugin_set_extra_library_path tv_set_extra_library_path;
 381     ld_plugin_get_input_section_count tv_get_input_section_count;
 382     ld_plugin_get_input_section_type tv_get_input_section_type;
 383     ld_plugin_get_input_section_name tv_get_input_section_name;
 384     ld_plugin_get_input_section_contents tv_get_input_section_contents;
 385     ld_plugin_update_section_order tv_update_section_order;
 386     ld_plugin_allow_section_ordering tv_allow_section_ordering;
 387   } tv_u;
 388 };
 389
 390 /* The plugin library's "onload" entry point.  */
 391
 392 typedef
 393 enum ld_plugin_status
 394 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
 395
 396 #ifdef __cplusplus
 397 }
 398 #endif
 399
 400 #endif /* !defined(PLUGIN_API_H) */