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