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
