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 /* Whether the symbol is a definition, reference, or common, weak or not.  */
  97
  98 enum ld_plugin_symbol_kind
  99 {
 100   LDPK_DEF,
 101   LDPK_WEAKDEF,
 102   LDPK_UNDEF,
 103   LDPK_WEAKUNDEF,
 104   LDPK_COMMON
 105 };
 106
 107 /* The visibility of the symbol.  */
 108
 109 enum ld_plugin_symbol_visibility
 110 {
 111   LDPV_DEFAULT,
 112   LDPV_PROTECTED,
 113   LDPV_INTERNAL,
 114   LDPV_HIDDEN
 115 };
 116
 117 /* How a symbol is resolved.  */
 118
 119 enum ld_plugin_symbol_resolution
 120 {
 121   LDPR_UNKNOWN = 0,
 122
 123   /* Symbol is still undefined at this point.  */
 124   LDPR_UNDEF,
 125
 126   /* This is the prevailing definition of the symbol, with references from
 127      regular object code.  */
 128   LDPR_PREVAILING_DEF,
 129
 130   /* This is the prevailing definition of the symbol, with no
 131      references from regular objects.  It is only referenced from IR
 132      code.  */
 133   LDPR_PREVAILING_DEF_IRONLY,
 134
 135   /* This definition was pre-empted by a definition in a regular
 136      object file.  */
 137   LDPR_PREEMPTED_REG,
 138
 139   /* This definition was pre-empted by a definition in another IR file.  */
 140   LDPR_PREEMPTED_IR,
 141
 142   /* This symbol was resolved by a definition in another IR file.  */
 143   LDPR_RESOLVED_IR,
 144
 145   /* This symbol was resolved by a definition in a regular object
 146      linked into the main executable.  */
 147   LDPR_RESOLVED_EXEC,
 148
 149   /* This symbol was resolved by a definition in a shared object.  */
 150   LDPR_RESOLVED_DYN
 151 };
 152
 153 /* The plugin library's "claim file" handler.  */
 154
 155 typedef
 156 enum ld_plugin_status
 157 (*ld_plugin_claim_file_handler) (
 158   const struct ld_plugin_input_file *file, int *claimed);
 159
 160 /* The plugin library's "all symbols read" handler.  */
 161
 162 typedef
 163 enum ld_plugin_status
 164 (*ld_plugin_all_symbols_read_handler) (void);
 165
 166 /* The plugin library's cleanup handler.  */
 167
 168 typedef
 169 enum ld_plugin_status
 170 (*ld_plugin_cleanup_handler) (void);
 171
 172 /* The linker's interface for registering the "claim file" handler.  */
 173
 174 typedef
 175 enum ld_plugin_status
 176 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
 177
 178 /* The linker's interface for registering the "all symbols read" handler.  */
 179
 180 typedef
 181 enum ld_plugin_status
 182 (*ld_plugin_register_all_symbols_read) (
 183   ld_plugin_all_symbols_read_handler handler);
 184
 185 /* The linker's interface for registering the cleanup handler.  */
 186
 187 typedef
 188 enum ld_plugin_status
 189 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
 190
 191 /* The linker's interface for adding symbols from a claimed input file.  */
 192
 193 typedef
 194 enum ld_plugin_status
 195 (*ld_plugin_add_symbols) (void *handle, int nsyms,
 196                           const struct ld_plugin_symbol *syms);
 197
 198 /* The linker's interface for getting the input file information with
 199    an open (possibly re-opened) file descriptor.  */
 200
 201 typedef
 202 enum ld_plugin_status
 203 (*ld_plugin_get_input_file) (const void *handle,
 204                              struct ld_plugin_input_file *file);
 205
 206 typedef
 207 enum ld_plugin_status
 208 (*ld_plugin_get_view) (const void *handle, const void **viewp);
 209
 210 /* The linker's interface for releasing the input file.  */
 211
 212 typedef
 213 enum ld_plugin_status
 214 (*ld_plugin_release_input_file) (const void *handle);
 215
 216 /* The linker's interface for retrieving symbol resolution information.  */
 217
 218 typedef
 219 enum ld_plugin_status
 220 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
 221                           struct ld_plugin_symbol *syms);
 222
 223 /* The linker's interface for adding a compiled input file.  */
 224
 225 typedef
 226 enum ld_plugin_status
 227 (*ld_plugin_add_input_file) (const char *pathname);
 228
 229 /* The linker's interface for adding a library that should be searched.  */
 230
 231 typedef
 232 enum ld_plugin_status
 233 (*ld_plugin_add_input_library) (const char *libname);
 234
 235 /* The linker's interface for adding a library path that should be searched.  */
 236
 237 typedef
 238 enum ld_plugin_status
 239 (*ld_plugin_set_extra_library_path) (const char *path);
 240
 241 /* The linker's interface for issuing a warning or error message.  */
 242
 243 typedef
 244 enum ld_plugin_status
 245 (*ld_plugin_message) (int level, const char *format, ...);
 246
 247 enum ld_plugin_level
 248 {
 249   LDPL_INFO,
 250   LDPL_WARNING,
 251   LDPL_ERROR,
 252   LDPL_FATAL
 253 };
 254
 255 /* Values for the tv_tag field of the transfer vector.  */
 256
 257 enum ld_plugin_tag
 258 {
 259   LDPT_NULL = 0,
 260   LDPT_API_VERSION,
 261   LDPT_GOLD_VERSION,
 262   LDPT_LINKER_OUTPUT,
 263   LDPT_OPTION,
 264   LDPT_REGISTER_CLAIM_FILE_HOOK,
 265   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
 266   LDPT_REGISTER_CLEANUP_HOOK,
 267   LDPT_ADD_SYMBOLS,
 268   LDPT_GET_SYMBOLS,
 269   LDPT_ADD_INPUT_FILE,
 270   LDPT_MESSAGE,
 271   LDPT_GET_INPUT_FILE,
 272   LDPT_RELEASE_INPUT_FILE,
 273   LDPT_ADD_INPUT_LIBRARY,
 274   LDPT_OUTPUT_NAME,
 275   LDPT_SET_EXTRA_LIBRARY_PATH,
 276   LDPT_GNU_LD_VERSION,
 277   LDPT_GET_VIEW
 278 };
 279
 280 /* The plugin transfer vector.  */
 281
 282 struct ld_plugin_tv
 283 {
 284   enum ld_plugin_tag tv_tag;
 285   union
 286   {
 287     int tv_val;
 288     const char *tv_string;
 289     ld_plugin_register_claim_file tv_register_claim_file;
 290     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
 291     ld_plugin_register_cleanup tv_register_cleanup;
 292     ld_plugin_add_symbols tv_add_symbols;
 293     ld_plugin_get_symbols tv_get_symbols;
 294     ld_plugin_add_input_file tv_add_input_file;
 295     ld_plugin_message tv_message;
 296     ld_plugin_get_input_file tv_get_input_file;
 297     ld_plugin_get_view tv_get_view;
 298     ld_plugin_release_input_file tv_release_input_file;
 299     ld_plugin_add_input_library tv_add_input_library;
 300     ld_plugin_set_extra_library_path tv_set_extra_library_path;
 301   } tv_u;
 302 };
 303
 304 /* The plugin library's "onload" entry point.  */
 305
 306 typedef
 307 enum ld_plugin_status
 308 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
 309
 310 #ifdef __cplusplus
 311 }
 312 #endif
 313
 314 #endif /* !defined(PLUGIN_API_H) */