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