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) */ 315