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
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 /* 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 
353 typedef
354 enum 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 
363 typedef
364 enum ld_plugin_status
365 (*ld_plugin_get_input_section_size) (const struct ld_plugin_section section,
366                                      uint64_t *secsize);
367 
368 enum 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 
378 enum 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 
415 struct 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 
449 typedef
450 enum 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) */
458