source: trunk/libs/newlib/src/include/plugin-api.h @ 689

Last change on this file since 689 was 444, checked in by satin@…, 6 years ago

add newlib,libalmos-mkh, restructure shared_syscalls.h and mini-libc

File size: 13.7 KB
Line 
1/* plugin-api.h -- External linker plugin API.  */
2
3/* Copyright (C) 2009-2016 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 can not find uint64_t type
38#endif
39
40#ifdef __cplusplus
41extern "C"
42{
43#endif
44
45/* Status code returned by most API routines.  */
46
47enum 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
58enum 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
65enum 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
75struct 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
86struct 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
99struct 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
107enum 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
118enum 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
128enum 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
170typedef
171enum 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
177typedef
178enum ld_plugin_status
179(*ld_plugin_all_symbols_read_handler) (void);
180
181/* The plugin library's cleanup handler.  */
182
183typedef
184enum ld_plugin_status
185(*ld_plugin_cleanup_handler) (void);
186
187/* The linker's interface for registering the "claim file" handler.  */
188
189typedef
190enum 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
195typedef
196enum 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
202typedef
203enum 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
208typedef
209enum 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
216typedef
217enum ld_plugin_status
218(*ld_plugin_get_input_file) (const void *handle,
219                             struct ld_plugin_input_file *file);
220
221typedef
222enum 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
227typedef
228enum ld_plugin_status
229(*ld_plugin_release_input_file) (const void *handle);
230
231/* The linker's interface for retrieving symbol resolution information.  */
232
233typedef
234enum 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
240typedef
241enum 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
246typedef
247enum 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
252typedef
253enum 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
258typedef
259enum 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
267typedef
268enum 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
275typedef
276enum 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
285typedef
286enum 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
296typedef
297enum 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
308typedef
309enum 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
317typedef
318enum 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
326typedef
327enum 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
339typedef
340enum 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
353typedef
354enum 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
363typedef
364enum ld_plugin_status
365(*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
366                                     uint64_t *secsize);
367
368enum 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
378enum 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
415struct 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
449typedef
450enum 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) */
Note: See TracBrowser for help on using the repository browser.