1 /* plugin-api.h -- External linker plugin API. */
2
3 /* Copyright (C) 2009-2023 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 cannot find uint64_t type
38 #endif
39
40 /* Detect endianess based on __BYTE_ORDER__ macro. */
41 #if defined(__BYTE_ORDER__) && defined(__ORDER_BIG_ENDIAN__) && \
42 defined(__ORDER_LITTLE_ENDIAN__) && defined(__ORDER_PDP_ENDIAN__)
43 #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
44 #define PLUGIN_LITTLE_ENDIAN 1
45 #elif __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
46 #define PLUGIN_BIG_ENDIAN 1
47 #elif __BYTE_ORDER__ == __ORDER_PDP_ENDIAN__
48 #define PLUGIN_PDP_ENDIAN 1
49 #endif
50 #else
51 /* Older GCC releases (<4.6.0) can make detection from glibc macros. */
52 #if defined(__GLIBC__) || defined(__GNU_LIBRARY__) || defined(__ANDROID__)
53 #include <endian.h>
54 #ifdef __BYTE_ORDER
55 #if __BYTE_ORDER == __LITTLE_ENDIAN
56 #define PLUGIN_LITTLE_ENDIAN 1
57 #elif __BYTE_ORDER == __BIG_ENDIAN
58 #define PLUGIN_BIG_ENDIAN 1
59 #endif
60 #endif
61 #endif
62 /* Include all necessary header files based on target. */
63 #if defined(__SVR4) && defined(__sun)
64 #include <sys/byteorder.h>
65 #endif
66 #if defined(__FreeBSD__) || defined(__NetBSD__) || \
67 defined(__DragonFly__) || defined(__minix)
68 #include <sys/endian.h>
69 #endif
70 #if defined(__OpenBSD__)
71 #include <machine/endian.h>
72 #endif
73 /* Detect endianess based on _BYTE_ORDER. */
74 #ifdef _BYTE_ORDER
75 #if _BYTE_ORDER == _LITTLE_ENDIAN
76 #define PLUGIN_LITTLE_ENDIAN 1
77 #elif _BYTE_ORDER == _BIG_ENDIAN
78 #define PLUGIN_BIG_ENDIAN 1
79 #endif
80 #endif
81 /* Detect based on _WIN32. */
82 #if defined(_WIN32)
83 #define PLUGIN_LITTLE_ENDIAN 1
84 #endif
85 /* Detect based on __BIG_ENDIAN__ and __LITTLE_ENDIAN__ */
86 #ifdef __LITTLE_ENDIAN__
87 #define PLUGIN_LITTLE_ENDIAN 1
88 #endif
89 #ifdef __BIG_ENDIAN__
90 #define PLUGIN_BIG_ENDIAN 1
91 #endif
92 #endif
93
94 #ifdef __cplusplus
95 extern "C"
96 {
97 #endif
98
99 /* Status code returned by most API routines. */
100
101 enum ld_plugin_status
102 {
103 LDPS_OK = 0,
104 LDPS_NO_SYMS, /* Attempt to get symbols that haven't been added. */
105 LDPS_BAD_HANDLE, /* No claimed object associated with given handle. */
106 LDPS_ERR
107 /* Additional Error codes TBD. */
108 };
109
110 /* The version of the API specification. */
111
112 enum ld_plugin_api_version
113 {
114 LD_PLUGIN_API_VERSION = 1
115 };
116
117 /* The type of output file being generated by the linker. */
118
119 enum ld_plugin_output_file_type
120 {
121 LDPO_REL,
122 LDPO_EXEC,
123 LDPO_DYN,
124 LDPO_PIE
125 };
126
127 /* An input file managed by the plugin library. */
128
129 struct ld_plugin_input_file
130 {
131 const char *name;
132 int fd;
133 off_t offset;
134 off_t filesize;
135 void *handle;
136 };
137
138 /* A symbol belonging to an input file managed by the plugin library. */
139
140 struct ld_plugin_symbol
141 {
142 char *name;
143 char *version;
144 /* This is for compatibility with older ABIs. The older ABI defined
145 only 'def' field. */
146 #if PLUGIN_BIG_ENDIAN == 1
147 char unused;
148 char section_kind;
149 char symbol_type;
150 char def;
151 #elif PLUGIN_LITTLE_ENDIAN == 1
152 char def;
153 char symbol_type;
154 char section_kind;
155 char unused;
156 #elif PLUGIN_PDP_ENDIAN == 1
157 char symbol_type;
158 char def;
159 char unused;
160 char section_kind;
161 #else
162 #error "Could not detect architecture endianess"
163 #endif
164 int visibility;
165 uint64_t size;
166 char *comdat_key;
167 int resolution;
168 };
169
170 /* An object's section. */
171
172 struct ld_plugin_section
173 {
174 const void* handle;
175 unsigned int shndx;
176 };
177
178 /* Whether the symbol is a definition, reference, or common, weak or not. */
179
180 enum ld_plugin_symbol_kind
181 {
182 LDPK_DEF,
183 LDPK_WEAKDEF,
184 LDPK_UNDEF,
185 LDPK_WEAKUNDEF,
186 LDPK_COMMON
187 };
188
189 /* The visibility of the symbol. */
190
191 enum ld_plugin_symbol_visibility
192 {
193 LDPV_DEFAULT,
194 LDPV_PROTECTED,
195 LDPV_INTERNAL,
196 LDPV_HIDDEN
197 };
198
199 /* The type of the symbol. */
200
201 enum ld_plugin_symbol_type
202 {
203 LDST_UNKNOWN,
204 LDST_FUNCTION,
205 LDST_VARIABLE
206 };
207
208 enum ld_plugin_symbol_section_kind
209 {
210 LDSSK_DEFAULT,
211 LDSSK_BSS
212 };
213
214 /* How a symbol is resolved. */
215
216 enum ld_plugin_symbol_resolution
217 {
218 LDPR_UNKNOWN = 0,
219
220 /* Symbol is still undefined at this point. */
221 LDPR_UNDEF,
222
223 /* This is the prevailing definition of the symbol, with references from
224 regular object code. */
225 LDPR_PREVAILING_DEF,
226
227 /* This is the prevailing definition of the symbol, with no
228 references from regular objects. It is only referenced from IR
229 code. */
230 LDPR_PREVAILING_DEF_IRONLY,
231
232 /* This definition was pre-empted by a definition in a regular
233 object file. */
234 LDPR_PREEMPTED_REG,
235
236 /* This definition was pre-empted by a definition in another IR file. */
237 LDPR_PREEMPTED_IR,
238
239 /* This symbol was resolved by a definition in another IR file. */
240 LDPR_RESOLVED_IR,
241
242 /* This symbol was resolved by a definition in a regular object
243 linked into the main executable. */
244 LDPR_RESOLVED_EXEC,
245
246 /* This symbol was resolved by a definition in a shared object. */
247 LDPR_RESOLVED_DYN,
248
249 /* This is the prevailing definition of the symbol, with no
250 references from regular objects. It is only referenced from IR
251 code, but the symbol is exported and may be referenced from
252 a dynamic object (not seen at link time). */
253 LDPR_PREVAILING_DEF_IRONLY_EXP
254 };
255
256 /* The plugin library's "claim file" handler. */
257
258 typedef
259 enum ld_plugin_status
260 (*ld_plugin_claim_file_handler) (
261 const struct ld_plugin_input_file *file, int *claimed);
262
263 /* The plugin library's "all symbols read" handler. */
264
265 typedef
266 enum ld_plugin_status
267 (*ld_plugin_all_symbols_read_handler) (void);
268
269 /* The plugin library's cleanup handler. */
270
271 typedef
272 enum ld_plugin_status
273 (*ld_plugin_cleanup_handler) (void);
274
275 /* The linker's interface for registering the "claim file" handler. */
276
277 typedef
278 enum ld_plugin_status
279 (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler);
280
281 /* The linker's interface for registering the "all symbols read" handler. */
282
283 typedef
284 enum ld_plugin_status
285 (*ld_plugin_register_all_symbols_read) (
286 ld_plugin_all_symbols_read_handler handler);
287
288 /* The linker's interface for registering the cleanup handler. */
289
290 typedef
291 enum ld_plugin_status
292 (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler);
293
294 /* The linker's interface for adding symbols from a claimed input file. */
295
296 typedef
297 enum ld_plugin_status
298 (*ld_plugin_add_symbols) (void *handle, int nsyms,
299 const struct ld_plugin_symbol *syms);
300
301 /* The linker's interface for getting the input file information with
302 an open (possibly re-opened) file descriptor. */
303
304 typedef
305 enum ld_plugin_status
306 (*ld_plugin_get_input_file) (const void *handle,
307 struct ld_plugin_input_file *file);
308
309 typedef
310 enum ld_plugin_status
311 (*ld_plugin_get_view) (const void *handle, const void **viewp);
312
313 /* The linker's interface for releasing the input file. */
314
315 typedef
316 enum ld_plugin_status
317 (*ld_plugin_release_input_file) (const void *handle);
318
319 /* The linker's interface for retrieving symbol resolution information. */
320
321 typedef
322 enum ld_plugin_status
323 (*ld_plugin_get_symbols) (const void *handle, int nsyms,
324 struct ld_plugin_symbol *syms);
325
326 /* The linker's interface for adding a compiled input file. */
327
328 typedef
329 enum ld_plugin_status
330 (*ld_plugin_add_input_file) (const char *pathname);
331
332 /* The linker's interface for adding a library that should be searched. */
333
334 typedef
335 enum ld_plugin_status
336 (*ld_plugin_add_input_library) (const char *libname);
337
338 /* The linker's interface for adding a library path that should be searched. */
339
340 typedef
341 enum ld_plugin_status
342 (*ld_plugin_set_extra_library_path) (const char *path);
343
344 /* The linker's interface for issuing a warning or error message. */
345
346 typedef
347 enum ld_plugin_status
348 (*ld_plugin_message) (int level, const char *format, ...);
349
350 /* The linker's interface for retrieving the number of sections in an object.
351 The handle is obtained in the claim_file handler. This interface should
352 only be invoked in the claim_file handler. This function sets *COUNT to
353 the number of sections in the object. */
354
355 typedef
356 enum ld_plugin_status
357 (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count);
358
359 /* The linker's interface for retrieving the section type of a specific
360 section in an object. This interface should only be invoked in the
361 claim_file handler. This function sets *TYPE to an ELF SHT_xxx value. */
362
363 typedef
364 enum ld_plugin_status
365 (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section,
366 unsigned int *type);
367
368 /* The linker's interface for retrieving the name of a specific section in
369 an object. This interface should only be invoked in the claim_file handler.
370 This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated
371 by malloc. The plugin must free *SECTION_NAME_PTR. */
372
373 typedef
374 enum ld_plugin_status
375 (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section,
376 char **section_name_ptr);
377
378 /* The linker's interface for retrieving the contents of a specific section
379 in an object. This interface should only be invoked in the claim_file
380 handler. This function sets *SECTION_CONTENTS to point to a buffer that is
381 valid until clam_file handler returns. It sets *LEN to the size of the
382 buffer. */
383
384 typedef
385 enum ld_plugin_status
386 (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section,
387 const unsigned char **section_contents,
388 size_t* len);
389
390 /* The linker's interface for specifying the desired order of sections.
391 The sections should be specifed using the array SECTION_LIST in the
392 order in which they should appear in the final layout. NUM_SECTIONS
393 specifies the number of entries in each array. This should be invoked
394 in the all_symbols_read handler. */
395
396 typedef
397 enum ld_plugin_status
398 (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list,
399 unsigned int num_sections);
400
401 /* The linker's interface for specifying that reordering of sections is
402 desired so that the linker can prepare for it. This should be invoked
403 before update_section_order, preferably in the claim_file handler. */
404
405 typedef
406 enum ld_plugin_status
407 (*ld_plugin_allow_section_ordering) (void);
408
409 /* The linker's interface for specifying that a subset of sections is
410 to be mapped to a unique segment. If the plugin wants to call
411 unique_segment_for_sections, it must call this function from a
412 claim_file_handler or when it is first loaded. */
413
414 typedef
415 enum ld_plugin_status
416 (*ld_plugin_allow_unique_segment_for_sections) (void);
417
418 /* The linker's interface for specifying that a specific set of sections
419 must be mapped to a unique segment. ELF segments do not have names
420 and the NAME is used as the name of the newly created output section
421 that is then placed in the unique PT_LOAD segment. FLAGS is used to
422 specify if any additional segment flags need to be set. For instance,
423 a specific segment flag can be set to identify this segment. Unsetting
424 segment flags that would be set by default is not possible. The
425 parameter SEGMENT_ALIGNMENT when non-zero will override the default. */
426
427 typedef
428 enum ld_plugin_status
429 (*ld_plugin_unique_segment_for_sections) (
430 const char* segment_name,
431 uint64_t segment_flags,
432 uint64_t segment_alignment,
433 const struct ld_plugin_section * section_list,
434 unsigned int num_sections);
435
436 /* The linker's interface for retrieving the section alignment requirement
437 of a specific section in an object. This interface should only be invoked in the
438 claim_file handler. This function sets *ADDRALIGN to the ELF sh_addralign
439 value of the input section. */
440
441 typedef
442 enum ld_plugin_status
443 (*ld_plugin_get_input_section_alignment) (const struct ld_plugin_section section,
444 unsigned int *addralign);
445
446 /* The linker's interface for retrieving the section size of a specific section
447 in an object. This interface should only be invoked in the claim_file handler.
448 This function sets *SECSIZE to the ELF sh_size
449 value of the input section. */
450
451 typedef
452 enum ld_plugin_status
453 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
454 uint64_t *secsize);
455
456 typedef
457 enum ld_plugin_status
458 (*ld_plugin_new_input_handler) (const struct ld_plugin_input_file *file);
459
460 /* The linker's interface for registering the "new_input" handler. This handler
461 will be notified when a new input file has been added after the
462 all_symbols_read event, allowing the plugin to, for example, set a unique
463 segment for sections in plugin-generated input files. */
464
465 typedef
466 enum ld_plugin_status
467 (*ld_plugin_register_new_input) (ld_plugin_new_input_handler handler);
468
469 /* The linker's interface for getting the list of wrapped symbols using the
470 --wrap option. This sets *NUM_SYMBOLS to number of wrapped symbols and
471 *WRAP_SYMBOL_LIST to the list of wrapped symbols. */
472
473 typedef
474 enum ld_plugin_status
475 (*ld_plugin_get_wrap_symbols) (uint64_t *num_symbols,
476 const char ***wrap_symbol_list);
477
478 enum ld_plugin_level
479 {
480 LDPL_INFO,
481 LDPL_WARNING,
482 LDPL_ERROR,
483 LDPL_FATAL
484 };
485
486 /* Contract between a plug-in and a linker. */
487
488 enum linker_api_version
489 {
490 /* The linker/plugin do not implement any of the API levels below, the API
491 is determined solely via the transfer vector. */
492 LAPI_V0,
493
494 /* API level v1. The linker provides get_symbols_v3, add_symbols_v2,
495 the plugin will use that and not any lower versions.
496 claim_file is thread-safe on the plugin side and
497 add_symbols on the linker side. */
498 LAPI_V1
499 };
500
501 /* The linker's interface for API version negotiation. A plug-in calls
502 the function (with its IDENTIFIER and VERSION), plus minimal and maximal
503 version of linker_api_version is provided. Linker then returns selected
504 API version and provides its IDENTIFIER and VERSION. The returned value
505 by linker must be in range [MINIMAL_API_SUPPORTED, MAXIMAL_API_SUPPORTED].
506 Identifier pointers remain valid as long as the plugin is loaded. */
507
508 typedef
509 int
510 (*ld_plugin_get_api_version) (const char *plugin_identifier,
511 const char *plugin_version,
512 int minimal_api_supported,
513 int maximal_api_supported,
514 const char **linker_identifier,
515 const char **linker_version);
516
517 /* Values for the tv_tag field of the transfer vector. */
518
519 enum ld_plugin_tag
520 {
521 LDPT_NULL,
522 LDPT_API_VERSION,
523 LDPT_GOLD_VERSION,
524 LDPT_LINKER_OUTPUT,
525 LDPT_OPTION,
526 LDPT_REGISTER_CLAIM_FILE_HOOK,
527 LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK,
528 LDPT_REGISTER_CLEANUP_HOOK,
529 LDPT_ADD_SYMBOLS,
530 LDPT_GET_SYMBOLS,
531 LDPT_ADD_INPUT_FILE,
532 LDPT_MESSAGE,
533 LDPT_GET_INPUT_FILE,
534 LDPT_RELEASE_INPUT_FILE,
535 LDPT_ADD_INPUT_LIBRARY,
536 LDPT_OUTPUT_NAME,
537 LDPT_SET_EXTRA_LIBRARY_PATH,
538 LDPT_GNU_LD_VERSION,
539 LDPT_GET_VIEW,
540 LDPT_GET_INPUT_SECTION_COUNT,
541 LDPT_GET_INPUT_SECTION_TYPE,
542 LDPT_GET_INPUT_SECTION_NAME,
543 LDPT_GET_INPUT_SECTION_CONTENTS,
544 LDPT_UPDATE_SECTION_ORDER,
545 LDPT_ALLOW_SECTION_ORDERING,
546 LDPT_GET_SYMBOLS_V2,
547 LDPT_ALLOW_UNIQUE_SEGMENT_FOR_SECTIONS,
548 LDPT_UNIQUE_SEGMENT_FOR_SECTIONS,
549 LDPT_GET_SYMBOLS_V3,
550 LDPT_GET_INPUT_SECTION_ALIGNMENT,
551 LDPT_GET_INPUT_SECTION_SIZE,
552 LDPT_REGISTER_NEW_INPUT_HOOK,
553 LDPT_GET_WRAP_SYMBOLS,
554 LDPT_ADD_SYMBOLS_V2,
555 LDPT_GET_API_VERSION,
556 };
557
558 /* The plugin transfer vector. */
559
560 struct ld_plugin_tv
561 {
562 enum ld_plugin_tag tv_tag;
563 union
564 {
565 int tv_val;
566 const char *tv_string;
567 ld_plugin_register_claim_file tv_register_claim_file;
568 ld_plugin_register_all_symbols_read tv_register_all_symbols_read;
569 ld_plugin_register_cleanup tv_register_cleanup;
570 ld_plugin_add_symbols tv_add_symbols;
571 ld_plugin_get_symbols tv_get_symbols;
572 ld_plugin_add_input_file tv_add_input_file;
573 ld_plugin_message tv_message;
574 ld_plugin_get_input_file tv_get_input_file;
575 ld_plugin_get_view tv_get_view;
576 ld_plugin_release_input_file tv_release_input_file;
577 ld_plugin_add_input_library tv_add_input_library;
578 ld_plugin_set_extra_library_path tv_set_extra_library_path;
579 ld_plugin_get_input_section_count tv_get_input_section_count;
580 ld_plugin_get_input_section_type tv_get_input_section_type;
581 ld_plugin_get_input_section_name tv_get_input_section_name;
582 ld_plugin_get_input_section_contents tv_get_input_section_contents;
583 ld_plugin_update_section_order tv_update_section_order;
584 ld_plugin_allow_section_ordering tv_allow_section_ordering;
585 ld_plugin_allow_unique_segment_for_sections tv_allow_unique_segment_for_sections;
586 ld_plugin_unique_segment_for_sections tv_unique_segment_for_sections;
587 ld_plugin_get_input_section_alignment tv_get_input_section_alignment;
588 ld_plugin_get_input_section_size tv_get_input_section_size;
589 ld_plugin_register_new_input tv_register_new_input;
590 ld_plugin_get_wrap_symbols tv_get_wrap_symbols;
591 ld_plugin_get_api_version tv_get_api_version;
592 } tv_u;
593 };
594
595 /* The plugin library's "onload" entry point. */
596
597 typedef
598 enum ld_plugin_status
599 (*ld_plugin_onload) (struct ld_plugin_tv *tv);
600
601 #ifdef __cplusplus
602 }
603 #endif
604
605 #endif /* !defined(PLUGIN_API_H) */