include/plugin-api.h

   1 /* plugin-api.h -- External linker plugin API.  */
   2
   3 /* Copyright 2009 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 /* The linker's interface for releasing the input file.  */
 207
 208 typedef
 209 enum ld_plugin_status
 210 (*ld_plugin_release_input_file) (const void *handle);
 211
 212 /* The linker's interface for retrieving symbol resolution information.  */
 213
 214 typedef
 215 enum ld_plugin_status
 216 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
 217                           struct ld_plugin_symbol *syms);
 218
 219 /* The linker's interface for adding a compiled input file.  */
 220
 221 typedef
 222 enum ld_plugin_status
 223 (*ld_plugin_add_input_file) (const char *pathname);
 224
 225 /* The linker's interface for adding a library that should be searched.  */
 226
 227 typedef
 228 enum ld_plugin_status
 229 (*ld_plugin_add_input_library) (const char *libname);
 230
 231 /* The linker's interface for adding a library path that should be searched.  */
 232
 233 typedef
 234 enum ld_plugin_status
 235 (*ld_plugin_set_extra_library_path) (const char *path);
 236
 237 /* The linker's interface for issuing a warning or error message.  */
 238
 239 typedef
 240 enum ld_plugin_status
 241 (*ld_plugin_message) (int level, const char *format, ...);
 242
 243 enum ld_plugin_level
 244 {
 245   LDPL_INFO,
 246   LDPL_WARNING,
 247   LDPL_ERROR,
 248   LDPL_FATAL
 249 };
 250
 251 /* Values for the tv_tag field of the transfer vector.  */
 252
 253 enum ld_plugin_tag
 254 {
 255   LDPT_NULL = 0,
 256   LDPT_API_VERSION,
 257   LDPT_GOLD_VERSION,
 258   LDPT_LINKER_OUTPUT,
 259   LDPT_OPTION,
 260   LDPT_REGISTER_CLAIM_FILE_HOOK,
 261   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
 262   LDPT_REGISTER_CLEANUP_HOOK,
 263   LDPT_ADD_SYMBOLS,
 264   LDPT_GET_SYMBOLS,
 265   LDPT_ADD_INPUT_FILE,
 266   LDPT_MESSAGE,
 267   LDPT_GET_INPUT_FILE,
 268   LDPT_RELEASE_INPUT_FILE,
 269   LDPT_ADD_INPUT_LIBRARY,
 270   LDPT_OUTPUT_NAME,
 271   LDPT_SET_EXTRA_LIBRARY_PATH
 272 };
 273
 274 /* The plugin transfer vector.  */
 275
 276 struct ld_plugin_tv
 277 {
 278   enum ld_plugin_tag tv_tag;
 279   union
 280   {
 281     int tv_val;
 282     const char *tv_string;
 283     ld_plugin_register_claim_file tv_register_claim_file;
 284     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
 285     ld_plugin_register_cleanup tv_register_cleanup;
 286     ld_plugin_add_symbols tv_add_symbols;
 287     ld_plugin_get_symbols tv_get_symbols;
 288     ld_plugin_add_input_file tv_add_input_file;
 289     ld_plugin_message tv_message;
 290     ld_plugin_get_input_file tv_get_input_file;
 291     ld_plugin_release_input_file tv_release_input_file;
 292     ld_plugin_add_input_library tv_add_input_library;
 293     ld_plugin_set_extra_library_path tv_set_extra_library_path;
 294   } tv_u;
 295 };
 296
 297 /* The plugin library's "onload" entry point.  */
 298
 299 typedef
 300 enum ld_plugin_status
 301 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
 302
 303 #ifdef __cplusplus
 304 }
 305 #endif
 306
 307 #endif /* !defined(PLUGIN_API_H) */