Commit | Line | Data |
---|---|---|
89fc3421 CC |
1 | /* plugin-api.h -- External linker plugin API. */ |
2 | ||
b3adc24a | 3 | /* Copyright (C) 2009-2020 Free Software Foundation, Inc. |
89fc3421 CC |
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 | ||
0adbbe4a | 29 | #ifdef HAVE_STDINT_H |
89fc3421 | 30 | #include <stdint.h> |
0adbbe4a DD |
31 | #elif defined(HAVE_INTTYPES_H) |
32 | #include <inttypes.h> | |
33 | #endif | |
89fc3421 | 34 | #include <sys/types.h> |
0adbbe4a DD |
35 | #if !defined(HAVE_STDINT_H) && !defined(HAVE_INTTYPES_H) && \ |
36 | !defined(UINT64_MAX) && !defined(uint64_t) | |
a08da33e | 37 | #error cannot find uint64_t type |
0adbbe4a | 38 | #endif |
89fc3421 CC |
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, | |
bbb444b6 | 50 | LDPS_NO_SYMS, /* Attempt to get symbols that haven't been added. */ |
fa7f3e72 | 51 | LDPS_BAD_HANDLE, /* No claimed object associated with given handle. */ |
bbb444b6 | 52 | LDPS_ERR |
89fc3421 CC |
53 | /* Additional Error codes TBD. */ |
54 | }; | |
55 | ||
56 | /* The version of the API specification. */ | |
57 | ||
58 | enum ld_plugin_api_version | |
59 | { | |
bbb444b6 | 60 | LD_PLUGIN_API_VERSION = 1 |
89fc3421 CC |
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, | |
2202d7cd RÁE |
69 | LDPO_DYN, |
70 | LDPO_PIE | |
89fc3421 CC |
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; | |
3734bec8 ML |
90 | /* This is for compatibility with older ABIs. The older ABI defined |
91 | only 'def' field. */ | |
92 | #ifdef __BIG_ENDIAN__ | |
93 | char unused; | |
94 | char section_kind; | |
95 | char symbol_type; | |
96 | char def; | |
97 | #else | |
98 | char def; | |
99 | char symbol_type; | |
100 | char section_kind; | |
101 | char unused; | |
102 | #endif | |
89fc3421 CC |
103 | int visibility; |
104 | uint64_t size; | |
105 | char *comdat_key; | |
106 | int resolution; | |
107 | }; | |
108 | ||
e9552f7e ST |
109 | /* An object's section. */ |
110 | ||
111 | struct ld_plugin_section | |
112 | { | |
113 | const void* handle; | |
114 | unsigned int shndx; | |
115 | }; | |
116 | ||
89fc3421 CC |
117 | /* Whether the symbol is a definition, reference, or common, weak or not. */ |
118 | ||
119 | enum ld_plugin_symbol_kind | |
120 | { | |
121 | LDPK_DEF, | |
122 | LDPK_WEAKDEF, | |
123 | LDPK_UNDEF, | |
124 | LDPK_WEAKUNDEF, | |
bbb444b6 | 125 | LDPK_COMMON |
89fc3421 CC |
126 | }; |
127 | ||
128 | /* The visibility of the symbol. */ | |
129 | ||
130 | enum ld_plugin_symbol_visibility | |
131 | { | |
132 | LDPV_DEFAULT, | |
133 | LDPV_PROTECTED, | |
134 | LDPV_INTERNAL, | |
bbb444b6 | 135 | LDPV_HIDDEN |
89fc3421 CC |
136 | }; |
137 | ||
3734bec8 ML |
138 | /* The type of the symbol. */ |
139 | ||
140 | enum ld_plugin_symbol_type | |
141 | { | |
142 | LDST_UNKNOWN, | |
143 | LDST_FUNCTION, | |
144 | LDST_VARIABLE, | |
145 | }; | |
146 | ||
147 | enum ld_plugin_symbol_section_kind | |
148 | { | |
149 | LDSSK_DEFAULT, | |
150 | LDSSK_BSS | |
151 | }; | |
152 | ||
89fc3421 CC |
153 | /* How a symbol is resolved. */ |
154 | ||
155 | enum ld_plugin_symbol_resolution | |
156 | { | |
157 | LDPR_UNKNOWN = 0, | |
8341e15b ILT |
158 | |
159 | /* Symbol is still undefined at this point. */ | |
89fc3421 | 160 | LDPR_UNDEF, |
8341e15b ILT |
161 | |
162 | /* This is the prevailing definition of the symbol, with references from | |
163 | regular object code. */ | |
89fc3421 | 164 | LDPR_PREVAILING_DEF, |
8341e15b ILT |
165 | |
166 | /* This is the prevailing definition of the symbol, with no | |
167 | references from regular objects. It is only referenced from IR | |
168 | code. */ | |
89fc3421 | 169 | LDPR_PREVAILING_DEF_IRONLY, |
8341e15b ILT |
170 | |
171 | /* This definition was pre-empted by a definition in a regular | |
172 | object file. */ | |
89fc3421 | 173 | LDPR_PREEMPTED_REG, |
8341e15b ILT |
174 | |
175 | /* This definition was pre-empted by a definition in another IR file. */ | |
89fc3421 | 176 | LDPR_PREEMPTED_IR, |
8341e15b ILT |
177 | |
178 | /* This symbol was resolved by a definition in another IR file. */ | |
89fc3421 | 179 | LDPR_RESOLVED_IR, |
8341e15b ILT |
180 | |
181 | /* This symbol was resolved by a definition in a regular object | |
182 | linked into the main executable. */ | |
89fc3421 | 183 | LDPR_RESOLVED_EXEC, |
8341e15b ILT |
184 | |
185 | /* This symbol was resolved by a definition in a shared object. */ | |
79df06c4 DD |
186 | LDPR_RESOLVED_DYN, |
187 | ||
188 | /* This is the prevailing definition of the symbol, with no | |
189 | references from regular objects. It is only referenced from IR | |
190 | code, but the symbol is exported and may be referenced from | |
191 | a dynamic object (not seen at link time). */ | |
192 | LDPR_PREVAILING_DEF_IRONLY_EXP | |
89fc3421 CC |
193 | }; |
194 | ||
195 | /* The plugin library's "claim file" handler. */ | |
196 | ||
197 | typedef | |
198 | enum ld_plugin_status | |
199 | (*ld_plugin_claim_file_handler) ( | |
200 | const struct ld_plugin_input_file *file, int *claimed); | |
201 | ||
202 | /* The plugin library's "all symbols read" handler. */ | |
203 | ||
204 | typedef | |
205 | enum ld_plugin_status | |
206 | (*ld_plugin_all_symbols_read_handler) (void); | |
207 | ||
208 | /* The plugin library's cleanup handler. */ | |
209 | ||
210 | typedef | |
211 | enum ld_plugin_status | |
212 | (*ld_plugin_cleanup_handler) (void); | |
213 | ||
214 | /* The linker's interface for registering the "claim file" handler. */ | |
215 | ||
216 | typedef | |
217 | enum ld_plugin_status | |
218 | (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler); | |
219 | ||
220 | /* The linker's interface for registering the "all symbols read" handler. */ | |
221 | ||
222 | typedef | |
223 | enum ld_plugin_status | |
224 | (*ld_plugin_register_all_symbols_read) ( | |
225 | ld_plugin_all_symbols_read_handler handler); | |
226 | ||
227 | /* The linker's interface for registering the cleanup handler. */ | |
228 | ||
229 | typedef | |
230 | enum ld_plugin_status | |
231 | (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler); | |
232 | ||
233 | /* The linker's interface for adding symbols from a claimed input file. */ | |
234 | ||
235 | typedef | |
236 | enum ld_plugin_status | |
237 | (*ld_plugin_add_symbols) (void *handle, int nsyms, | |
238 | const struct ld_plugin_symbol *syms); | |
239 | ||
fa7f3e72 CC |
240 | /* The linker's interface for getting the input file information with |
241 | an open (possibly re-opened) file descriptor. */ | |
242 | ||
243 | typedef | |
244 | enum ld_plugin_status | |
245 | (*ld_plugin_get_input_file) (const void *handle, | |
246 | struct ld_plugin_input_file *file); | |
247 | ||
55406e10 RÁE |
248 | typedef |
249 | enum ld_plugin_status | |
250 | (*ld_plugin_get_view) (const void *handle, const void **viewp); | |
251 | ||
fa7f3e72 CC |
252 | /* The linker's interface for releasing the input file. */ |
253 | ||
254 | typedef | |
255 | enum ld_plugin_status | |
256 | (*ld_plugin_release_input_file) (const void *handle); | |
257 | ||
89fc3421 CC |
258 | /* The linker's interface for retrieving symbol resolution information. */ |
259 | ||
260 | typedef | |
261 | enum ld_plugin_status | |
262 | (*ld_plugin_get_symbols) (const void *handle, int nsyms, | |
263 | struct ld_plugin_symbol *syms); | |
264 | ||
265 | /* The linker's interface for adding a compiled input file. */ | |
266 | ||
267 | typedef | |
268 | enum ld_plugin_status | |
6508b958 | 269 | (*ld_plugin_add_input_file) (const char *pathname); |
89fc3421 | 270 | |
8341e15b ILT |
271 | /* The linker's interface for adding a library that should be searched. */ |
272 | ||
273 | typedef | |
274 | enum ld_plugin_status | |
6508b958 | 275 | (*ld_plugin_add_input_library) (const char *libname); |
8341e15b | 276 | |
42218b9f RÁE |
277 | /* The linker's interface for adding a library path that should be searched. */ |
278 | ||
279 | typedef | |
280 | enum ld_plugin_status | |
281 | (*ld_plugin_set_extra_library_path) (const char *path); | |
282 | ||
89fc3421 CC |
283 | /* The linker's interface for issuing a warning or error message. */ |
284 | ||
285 | typedef | |
286 | enum ld_plugin_status | |
6c52134c | 287 | (*ld_plugin_message) (int level, const char *format, ...); |
89fc3421 | 288 | |
e9552f7e ST |
289 | /* The linker's interface for retrieving the number of sections in an object. |
290 | The handle is obtained in the claim_file handler. This interface should | |
291 | only be invoked in the claim_file handler. This function sets *COUNT to | |
292 | the number of sections in the object. */ | |
293 | ||
294 | typedef | |
295 | enum ld_plugin_status | |
296 | (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count); | |
297 | ||
298 | /* The linker's interface for retrieving the section type of a specific | |
299 | section in an object. This interface should only be invoked in the | |
300 | claim_file handler. This function sets *TYPE to an ELF SHT_xxx value. */ | |
301 | ||
302 | typedef | |
303 | enum ld_plugin_status | |
304 | (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section, | |
305 | unsigned int *type); | |
306 | ||
307 | /* The linker's interface for retrieving the name of a specific section in | |
308 | an object. This interface should only be invoked in the claim_file handler. | |
309 | This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated | |
310 | by malloc. The plugin must free *SECTION_NAME_PTR. */ | |
311 | ||
312 | typedef | |
313 | enum ld_plugin_status | |
314 | (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section, | |
315 | char **section_name_ptr); | |
316 | ||
317 | /* The linker's interface for retrieving the contents of a specific section | |
318 | in an object. This interface should only be invoked in the claim_file | |
319 | handler. This function sets *SECTION_CONTENTS to point to a buffer that is | |
320 | valid until clam_file handler returns. It sets *LEN to the size of the | |
321 | buffer. */ | |
322 | ||
323 | typedef | |
324 | enum ld_plugin_status | |
325 | (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section, | |
326 | const unsigned char **section_contents, | |
327 | size_t* len); | |
328 | ||
329 | /* The linker's interface for specifying the desired order of sections. | |
330 | The sections should be specifed using the array SECTION_LIST in the | |
331 | order in which they should appear in the final layout. NUM_SECTIONS | |
332 | specifies the number of entries in each array. This should be invoked | |
333 | in the all_symbols_read handler. */ | |
334 | ||
335 | typedef | |
336 | enum ld_plugin_status | |
337 | (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list, | |
338 | unsigned int num_sections); | |
339 | ||
340 | /* The linker's interface for specifying that reordering of sections is | |
341 | desired so that the linker can prepare for it. This should be invoked | |
342 | before update_section_order, preferably in the claim_file handler. */ | |
343 | ||
344 | typedef | |
345 | enum ld_plugin_status | |
346 | (*ld_plugin_allow_section_ordering) (void); | |
347 | ||
16164a6b ST |
348 | /* The linker's interface for specifying that a subset of sections is |
349 | to be mapped to a unique segment. If the plugin wants to call | |
350 | unique_segment_for_sections, it must call this function from a | |
351 | claim_file_handler or when it is first loaded. */ | |
352 | ||
353 | typedef | |
354 | enum ld_plugin_status | |
355 | (*ld_plugin_allow_unique_segment_for_sections) (void); | |
356 | ||
357 | /* The linker's interface for specifying that a specific set of sections | |
358 | must be mapped to a unique segment. ELF segments do not have names | |
359 | and the NAME is used as the name of the newly created output section | |
360 | that is then placed in the unique PT_LOAD segment. FLAGS is used to | |
361 | specify if any additional segment flags need to be set. For instance, | |
362 | a specific segment flag can be set to identify this segment. Unsetting | |
363 | segment flags that would be set by default is not possible. The | |
364 | parameter SEGMENT_ALIGNMENT when non-zero will override the default. */ | |
365 | ||
366 | typedef | |
367 | enum ld_plugin_status | |
368 | (*ld_plugin_unique_segment_for_sections) ( | |
369 | const char* segment_name, | |
370 | uint64_t segment_flags, | |
371 | uint64_t segment_alignment, | |
372 | const struct ld_plugin_section * section_list, | |
373 | unsigned int num_sections); | |
374 | ||
82838bd6 CC |
375 | /* The linker's interface for retrieving the section alignment requirement |
376 | of a specific section in an object. This interface should only be invoked in the | |
377 | claim_file handler. This function sets *ADDRALIGN to the ELF sh_addralign | |
378 | value of the input section. */ | |
379 | ||
380 | typedef | |
381 | enum ld_plugin_status | |
382 | (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section, | |
383 | unsigned int *addralign); | |
384 | ||
385 | /* The linker's interface for retrieving the section size of a specific section | |
386 | in an object. This interface should only be invoked in the claim_file handler. | |
387 | This function sets *SECSIZE to the ELF sh_size | |
388 | value of the input section. */ | |
389 | ||
390 | typedef | |
391 | enum ld_plugin_status | |
392 | (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section, | |
393 | uint64_t *secsize); | |
394 | ||
c4e64843 SC |
395 | typedef |
396 | enum ld_plugin_status | |
397 | (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file); | |
398 | ||
399 | /* The linker's interface for registering the "new_input" handler. This handler | |
400 | will be notified when a new input file has been added after the | |
401 | all_symbols_read event, allowing the plugin to, for example, set a unique | |
402 | segment for sections in plugin-generated input files. */ | |
403 | ||
404 | typedef | |
405 | enum ld_plugin_status | |
406 | (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler); | |
407 | ||
0b65c07b ST |
408 | /* The linker's interface for getting the list of wrapped symbols using the |
409 | --wrap option. This sets *NUM_SYMBOLS to number of wrapped symbols and | |
410 | *WRAP_SYMBOL_LIST to the list of wrapped symbols. */ | |
411 | ||
412 | typedef | |
413 | enum ld_plugin_status | |
414 | (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols, | |
415 | const char ***wrap_symbol_list); | |
c4e64843 | 416 | |
89fc3421 CC |
417 | enum ld_plugin_level |
418 | { | |
419 | LDPL_INFO, | |
420 | LDPL_WARNING, | |
421 | LDPL_ERROR, | |
bbb444b6 | 422 | LDPL_FATAL |
89fc3421 CC |
423 | }; |
424 | ||
425 | /* Values for the tv_tag field of the transfer vector. */ | |
426 | ||
427 | enum ld_plugin_tag | |
428 | { | |
429 | LDPT_NULL = 0, | |
f5c033f1 ST |
430 | LDPT_API_VERSION = 1, |
431 | LDPT_GOLD_VERSION = 2, | |
432 | LDPT_LINKER_OUTPUT = 3, | |
433 | LDPT_OPTION = 4, | |
434 | LDPT_REGISTER_CLAIM_FILE_HOOK = 5, | |
435 | LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK = 6, | |
436 | LDPT_REGISTER_CLEANUP_HOOK = 7, | |
437 | LDPT_ADD_SYMBOLS = 8, | |
438 | LDPT_GET_SYMBOLS = 9, | |
439 | LDPT_ADD_INPUT_FILE = 10, | |
440 | LDPT_MESSAGE = 11, | |
441 | LDPT_GET_INPUT_FILE = 12, | |
442 | LDPT_RELEASE_INPUT_FILE = 13, | |
443 | LDPT_ADD_INPUT_LIBRARY = 14, | |
444 | LDPT_OUTPUT_NAME = 15, | |
445 | LDPT_SET_EXTRA_LIBRARY_PATH = 16, | |
446 | LDPT_GNU_LD_VERSION = 17, | |
447 | LDPT_GET_VIEW = 18, | |
448 | LDPT_GET_INPUT_SECTION_COUNT = 19, | |
449 | LDPT_GET_INPUT_SECTION_TYPE = 20, | |
450 | LDPT_GET_INPUT_SECTION_NAME = 21, | |
451 | LDPT_GET_INPUT_SECTION_CONTENTS = 22, | |
452 | LDPT_UPDATE_SECTION_ORDER = 23, | |
453 | LDPT_ALLOW_SECTION_ORDERING = 24, | |
454 | LDPT_GET_SYMBOLS_V2 = 25, | |
455 | LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS = 26, | |
95ecdfbf | 456 | LDPT_UNIQUE_SEGMENT_FOR_SECTIONS = 27, |
82838bd6 CC |
457 | LDPT_GET_SYMBOLS_V3 = 28, |
458 | LDPT_GET_INPUT_SECTION_ALIGNMENT = 29, | |
c4e64843 | 459 | LDPT_GET_INPUT_SECTION_SIZE = 30, |
0b65c07b | 460 | LDPT_REGISTER_NEW_INPUT_HOOK = 31, |
3734bec8 ML |
461 | LDPT_GET_WRAP_SYMBOLS = 32, |
462 | LDPT_ADD_SYMBOLS_V2 = 33 | |
89fc3421 CC |
463 | }; |
464 | ||
465 | /* The plugin transfer vector. */ | |
466 | ||
467 | struct ld_plugin_tv | |
468 | { | |
469 | enum ld_plugin_tag tv_tag; | |
470 | union | |
471 | { | |
472 | int tv_val; | |
473 | const char *tv_string; | |
474 | ld_plugin_register_claim_file tv_register_claim_file; | |
475 | ld_plugin_register_all_symbols_read tv_register_all_symbols_read; | |
476 | ld_plugin_register_cleanup tv_register_cleanup; | |
477 | ld_plugin_add_symbols tv_add_symbols; | |
478 | ld_plugin_get_symbols tv_get_symbols; | |
479 | ld_plugin_add_input_file tv_add_input_file; | |
480 | ld_plugin_message tv_message; | |
fa7f3e72 | 481 | ld_plugin_get_input_file tv_get_input_file; |
55406e10 | 482 | ld_plugin_get_view tv_get_view; |
fa7f3e72 | 483 | ld_plugin_release_input_file tv_release_input_file; |
8341e15b | 484 | ld_plugin_add_input_library tv_add_input_library; |
42218b9f | 485 | ld_plugin_set_extra_library_path tv_set_extra_library_path; |
e9552f7e ST |
486 | ld_plugin_get_input_section_count tv_get_input_section_count; |
487 | ld_plugin_get_input_section_type tv_get_input_section_type; | |
488 | ld_plugin_get_input_section_name tv_get_input_section_name; | |
489 | ld_plugin_get_input_section_contents tv_get_input_section_contents; | |
490 | ld_plugin_update_section_order tv_update_section_order; | |
491 | ld_plugin_allow_section_ordering tv_allow_section_ordering; | |
16164a6b ST |
492 | ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections; |
493 | ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections; | |
82838bd6 CC |
494 | ld_plugin_get_input_section_alignment tv_get_input_section_alignment; |
495 | ld_plugin_get_input_section_size tv_get_input_section_size; | |
c4e64843 | 496 | ld_plugin_register_new_input tv_register_new_input; |
0b65c07b | 497 | ld_plugin_get_wrap_symbols tv_get_wrap_symbols; |
89fc3421 CC |
498 | } tv_u; |
499 | }; | |
500 | ||
501 | /* The plugin library's "onload" entry point. */ | |
502 | ||
503 | typedef | |
504 | enum ld_plugin_status | |
505 | (*ld_plugin_onload) (struct ld_plugin_tv *tv); | |
506 | ||
507 | #ifdef __cplusplus | |
a6bfd026 | 508 | } |
89fc3421 CC |
509 | #endif |
510 | ||
511 | #endif /* !defined(PLUGIN_API_H) */ |