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 /* 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 enum ld_plugin_level 349 { 350 LDPL_INFO, 351 LDPL_WARNING, 352 LDPL_ERROR, 353 LDPL_FATAL 354 }; 355 356 /* Values for the tv_tag field of the transfer vector. */ 357 358 enum ld_plugin_tag 359 { 360 LDPT_NULL = 0, 361 LDPT_API_VERSION = 1, 362 LDPT_GOLD_VERSION = 2, 363 LDPT_LINKER_OUTPUT = 3, 364 LDPT_OPTION = 4, 365 LDPT_REGISTER_CLAIM_FILE_HOOK = 5, 366 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6, 367 LDPT_REGISTER_CLEANUP_HOOK = 7, 368 LDPT_ADD_SYMBOLS = 8, 369 LDPT_GET_SYMBOLS = 9, 370 LDPT_ADD_INPUT_FILE = 10, 371 LDPT_MESSAGE = 11, 372 LDPT_GET_INPUT_FILE = 12, 373 LDPT_RELEASE_INPUT_FILE = 13, 374 LDPT_ADD_INPUT_LIBRARY = 14, 375 LDPT_OUTPUT_NAME = 15, 376 LDPT_SET_EXTRA_LIBRARY_PATH = 16, 377 LDPT_GNU_LD_VERSION = 17, 378 LDPT_GET_VIEW = 18, 379 LDPT_GET_INPUT_SECTION_COUNT = 19, 380 LDPT_GET_INPUT_SECTION_TYPE = 20, 381 LDPT_GET_INPUT_SECTION_NAME = 21, 382 LDPT_GET_INPUT_SECTION_CONTENTS = 22, 383 LDPT_UPDATE_SECTION_ORDER = 23, 384 LDPT_ALLOW_SECTION_ORDERING = 24, 385 LDPT_GET_SYMBOLS_V2 = 25, 386 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26, 387 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27 388 }; 389 390 /* The plugin transfer vector. */ 391 392 struct ld_plugin_tv 393 { 394 enum ld_plugin_tag tv_tag; 395 union 396 { 397 int tv_val; 398 const char *tv_string; 399 ld_plugin_register_claim_file tv_register_claim_file; 400 ld_plugin_register_all_symbols_read tv_register_all_symbols_read; 401 ld_plugin_register_cleanup tv_register_cleanup; 402 ld_plugin_add_symbols tv_add_symbols; 403 ld_plugin_get_symbols tv_get_symbols; 404 ld_plugin_add_input_file tv_add_input_file; 405 ld_plugin_message tv_message; 406 ld_plugin_get_input_file tv_get_input_file; 407 ld_plugin_get_view tv_get_view; 408 ld_plugin_release_input_file tv_release_input_file; 409 ld_plugin_add_input_library tv_add_input_library; 410 ld_plugin_set_extra_library_path tv_set_extra_library_path; 411 ld_plugin_get_input_section_count tv_get_input_section_count; 412 ld_plugin_get_input_section_type tv_get_input_section_type; 413 ld_plugin_get_input_section_name tv_get_input_section_name; 414 ld_plugin_get_input_section_contents tv_get_input_section_contents; 415 ld_plugin_update_section_order tv_update_section_order; 416 ld_plugin_allow_section_ordering tv_allow_section_ordering; 417 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections; 418 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections; 419 } tv_u; 420 }; 421 422 /* The plugin library's "onload" entry point. */ 423 424 typedef 425 enum ld_plugin_status 426 (*ld_plugin_onload) (struct ld_plugin_tv *tv); 427 428 #ifdef __cplusplus 429 } 430 #endif 431 432 #endif /* !defined(PLUGIN_API_H) */ 433
