1 /* plugin-api.h -- External linker plugin API. */ 2 3 /* Copyright (C) 2009-2016 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 /* The linker's interface for specifying that a subset of sections is 322 to be mapped to a unique segment. If the plugin wants to call 323 unique_segment_for_sections, it must call this function from a 324 claim_file_handler or when it is first loaded. */ 325 326 typedef 327 enum ld_plugin_status 328 (*ld_plugin_allow_unique_segment_for_sections) (void); 329 330 /* The linker's interface for specifying that a specific set of sections 331 must be mapped to a unique segment. ELF segments do not have names 332 and the NAME is used as the name of the newly created output section 333 that is then placed in the unique PT_LOAD segment. FLAGS is used to 334 specify if any additional segment flags need to be set. For instance, 335 a specific segment flag can be set to identify this segment. Unsetting 336 segment flags that would be set by default is not possible. The 337 parameter SEGMENT_ALIGNMENT when non-zero will override the default. */ 338 339 typedef 340 enum ld_plugin_status 341 (*ld_plugin_unique_segment_for_sections) ( 342 const char* segment_name, 343 uint64_t segment_flags, 344 uint64_t segment_alignment, 345 const struct ld_plugin_section * section_list, 346 unsigned int num_sections); 347 348 /* The linker's interface for retrieving the section alignment requirement 349 of a specific section in an object. This interface should only be invoked in the 350 claim_file handler. This function sets *ADDRALIGN to the ELF sh_addralign 351 value of the input section. */ 352 353 typedef 354 enum ld_plugin_status 355 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section, 356 unsigned int *addralign); 357 358 /* The linker's interface for retrieving the section size of a specific section 359 in an object. This interface should only be invoked in the claim_file handler. 360 This function sets *SECSIZE to the ELF sh_size 361 value of the input section. */ 362 363 typedef 364 enum ld_plugin_status 365 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section, 366 uint64_t *secsize); 367 368 enum ld_plugin_level 369 { 370 LDPL_INFO, 371 LDPL_WARNING, 372 LDPL_ERROR, 373 LDPL_FATAL 374 }; 375 376 /* Values for the tv_tag field of the transfer vector. */ 377 378 enum ld_plugin_tag 379 { 380 LDPT_NULL = 0, 381 LDPT_API_VERSION = 1, 382 LDPT_GOLD_VERSION = 2, 383 LDPT_LINKER_OUTPUT = 3, 384 LDPT_OPTION = 4, 385 LDPT_REGISTER_CLAIM_FILE_HOOK = 5, 386 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6, 387 LDPT_REGISTER_CLEANUP_HOOK = 7, 388 LDPT_ADD_SYMBOLS = 8, 389 LDPT_GET_SYMBOLS = 9, 390 LDPT_ADD_INPUT_FILE = 10, 391 LDPT_MESSAGE = 11, 392 LDPT_GET_INPUT_FILE = 12, 393 LDPT_RELEASE_INPUT_FILE = 13, 394 LDPT_ADD_INPUT_LIBRARY = 14, 395 LDPT_OUTPUT_NAME = 15, 396 LDPT_SET_EXTRA_LIBRARY_PATH = 16, 397 LDPT_GNU_LD_VERSION = 17, 398 LDPT_GET_VIEW = 18, 399 LDPT_GET_INPUT_SECTION_COUNT = 19, 400 LDPT_GET_INPUT_SECTION_TYPE = 20, 401 LDPT_GET_INPUT_SECTION_NAME = 21, 402 LDPT_GET_INPUT_SECTION_CONTENTS = 22, 403 LDPT_UPDATE_SECTION_ORDER = 23, 404 LDPT_ALLOW_SECTION_ORDERING = 24, 405 LDPT_GET_SYMBOLS_V2 = 25, 406 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26, 407 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27, 408 LDPT_GET_SYMBOLS_V3 = 28, 409 LDPT_GET_INPUT_SECTION_ALIGNMENT = 29, 410 LDPT_GET_INPUT_SECTION_SIZE = 30 411 }; 412 413 /* The plugin transfer vector. */ 414 415 struct ld_plugin_tv 416 { 417 enum ld_plugin_tag tv_tag; 418 union 419 { 420 int tv_val; 421 const char *tv_string; 422 ld_plugin_register_claim_file tv_register_claim_file; 423 ld_plugin_register_all_symbols_read tv_register_all_symbols_read; 424 ld_plugin_register_cleanup tv_register_cleanup; 425 ld_plugin_add_symbols tv_add_symbols; 426 ld_plugin_get_symbols tv_get_symbols; 427 ld_plugin_add_input_file tv_add_input_file; 428 ld_plugin_message tv_message; 429 ld_plugin_get_input_file tv_get_input_file; 430 ld_plugin_get_view tv_get_view; 431 ld_plugin_release_input_file tv_release_input_file; 432 ld_plugin_add_input_library tv_add_input_library; 433 ld_plugin_set_extra_library_path tv_set_extra_library_path; 434 ld_plugin_get_input_section_count tv_get_input_section_count; 435 ld_plugin_get_input_section_type tv_get_input_section_type; 436 ld_plugin_get_input_section_name tv_get_input_section_name; 437 ld_plugin_get_input_section_contents tv_get_input_section_contents; 438 ld_plugin_update_section_order tv_update_section_order; 439 ld_plugin_allow_section_ordering tv_allow_section_ordering; 440 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections; 441 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections; 442 ld_plugin_get_input_section_alignment tv_get_input_section_alignment; 443 ld_plugin_get_input_section_size tv_get_input_section_size; 444 } tv_u; 445 }; 446 447 /* The plugin library's "onload" entry point. */ 448 449 typedef 450 enum ld_plugin_status 451 (*ld_plugin_onload) (struct ld_plugin_tv *tv); 452 453 #ifdef __cplusplus 454 } 455 #endif 456 457 #endif /* !defined(PLUGIN_API_H) */ 458
