Home | History | Annotate | Download | only in include
      1 /* plugin-api.h -- External linker plugin API.  */
      2 
      3 /* Copyright 2009, 2010 Free Software Foundation, Inc.
      4    Written by Cary Coutant <ccoutant (at) 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 enum ld_plugin_level
    322 {
    323   LDPL_INFO,
    324   LDPL_WARNING,
    325   LDPL_ERROR,
    326   LDPL_FATAL
    327 };
    328 
    329 /* Values for the tv_tag field of the transfer vector.  */
    330 
    331 enum ld_plugin_tag
    332 {
    333   LDPT_NULL = 0,
    334   LDPT_API_VERSION,
    335   LDPT_GOLD_VERSION,
    336   LDPT_LINKER_OUTPUT,
    337   LDPT_OPTION,
    338   LDPT_REGISTER_CLAIM_FILE_HOOK,
    339   LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
    340   LDPT_REGISTER_CLEANUP_HOOK,
    341   LDPT_ADD_SYMBOLS,
    342   LDPT_GET_SYMBOLS,
    343   LDPT_ADD_INPUT_FILE,
    344   LDPT_MESSAGE,
    345   LDPT_GET_INPUT_FILE,
    346   LDPT_RELEASE_INPUT_FILE,
    347   LDPT_ADD_INPUT_LIBRARY,
    348   LDPT_OUTPUT_NAME,
    349   LDPT_SET_EXTRA_LIBRARY_PATH,
    350   LDPT_GNU_LD_VERSION,
    351   LDPT_GET_VIEW,
    352   LDPT_GET_INPUT_SECTION_COUNT,
    353   LDPT_GET_INPUT_SECTION_TYPE,
    354   LDPT_GET_INPUT_SECTION_NAME,
    355   LDPT_GET_INPUT_SECTION_CONTENTS,
    356   LDPT_UPDATE_SECTION_ORDER,
    357   LDPT_ALLOW_SECTION_ORDERING,
    358   LDPT_GET_SYMBOLS_V2
    359 };
    360 
    361 /* The plugin transfer vector.  */
    362 
    363 struct ld_plugin_tv
    364 {
    365   enum ld_plugin_tag tv_tag;
    366   union
    367   {
    368     int tv_val;
    369     const char *tv_string;
    370     ld_plugin_register_claim_file tv_register_claim_file;
    371     ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
    372     ld_plugin_register_cleanup tv_register_cleanup;
    373     ld_plugin_add_symbols tv_add_symbols;
    374     ld_plugin_get_symbols tv_get_symbols;
    375     ld_plugin_add_input_file tv_add_input_file;
    376     ld_plugin_message tv_message;
    377     ld_plugin_get_input_file tv_get_input_file;
    378     ld_plugin_get_view tv_get_view;
    379     ld_plugin_release_input_file tv_release_input_file;
    380     ld_plugin_add_input_library tv_add_input_library;
    381     ld_plugin_set_extra_library_path tv_set_extra_library_path;
    382     ld_plugin_get_input_section_count tv_get_input_section_count;
    383     ld_plugin_get_input_section_type tv_get_input_section_type;
    384     ld_plugin_get_input_section_name tv_get_input_section_name;
    385     ld_plugin_get_input_section_contents tv_get_input_section_contents;
    386     ld_plugin_update_section_order tv_update_section_order;
    387     ld_plugin_allow_section_ordering tv_allow_section_ordering;
    388   } tv_u;
    389 };
    390 
    391 /* The plugin library's "onload" entry point.  */
    392 
    393 typedef
    394 enum ld_plugin_status
    395 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
    396 
    397 #ifdef __cplusplus
    398 }
    399 #endif
    400 
    401 #endif /* !defined(PLUGIN_API_H) */
    402