Commit | Line | Data |
---|---|---|
89fc3421 CC |
1 | /* plugin-api.h -- External linker plugin API. */ |
2 | ||
59e11e17 | 3 | /* Copyright 2009, 2010 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) | |
37 | #error can not find uint64_t type | |
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, | |
bbb444b6 | 69 | LDPO_DYN |
89fc3421 CC |
70 | }; |
71 | ||
72 | /* An input file managed by the plugin library. */ | |
73 | ||
74 | struct ld_plugin_input_file | |
75 | { | |
76 | const char *name; | |
77 | int fd; | |
78 | off_t offset; | |
79 | off_t filesize; | |
80 | void *handle; | |
81 | }; | |
82 | ||
83 | /* A symbol belonging to an input file managed by the plugin library. */ | |
84 | ||
85 | struct ld_plugin_symbol | |
86 | { | |
87 | char *name; | |
88 | char *version; | |
89 | int def; | |
90 | int visibility; | |
91 | uint64_t size; | |
92 | char *comdat_key; | |
93 | int resolution; | |
94 | }; | |
95 | ||
e9552f7e ST |
96 | /* An object's section. */ |
97 | ||
98 | struct ld_plugin_section | |
99 | { | |
100 | const void* handle; | |
101 | unsigned int shndx; | |
102 | }; | |
103 | ||
89fc3421 CC |
104 | /* Whether the symbol is a definition, reference, or common, weak or not. */ |
105 | ||
106 | enum ld_plugin_symbol_kind | |
107 | { | |
108 | LDPK_DEF, | |
109 | LDPK_WEAKDEF, | |
110 | LDPK_UNDEF, | |
111 | LDPK_WEAKUNDEF, | |
bbb444b6 | 112 | LDPK_COMMON |
89fc3421 CC |
113 | }; |
114 | ||
115 | /* The visibility of the symbol. */ | |
116 | ||
117 | enum ld_plugin_symbol_visibility | |
118 | { | |
119 | LDPV_DEFAULT, | |
120 | LDPV_PROTECTED, | |
121 | LDPV_INTERNAL, | |
bbb444b6 | 122 | LDPV_HIDDEN |
89fc3421 CC |
123 | }; |
124 | ||
125 | /* How a symbol is resolved. */ | |
126 | ||
127 | enum ld_plugin_symbol_resolution | |
128 | { | |
129 | LDPR_UNKNOWN = 0, | |
8341e15b ILT |
130 | |
131 | /* Symbol is still undefined at this point. */ | |
89fc3421 | 132 | LDPR_UNDEF, |
8341e15b ILT |
133 | |
134 | /* This is the prevailing definition of the symbol, with references from | |
135 | regular object code. */ | |
89fc3421 | 136 | LDPR_PREVAILING_DEF, |
8341e15b ILT |
137 | |
138 | /* This is the prevailing definition of the symbol, with no | |
139 | references from regular objects. It is only referenced from IR | |
140 | code. */ | |
89fc3421 | 141 | LDPR_PREVAILING_DEF_IRONLY, |
8341e15b ILT |
142 | |
143 | /* This definition was pre-empted by a definition in a regular | |
144 | object file. */ | |
89fc3421 | 145 | LDPR_PREEMPTED_REG, |
8341e15b ILT |
146 | |
147 | /* This definition was pre-empted by a definition in another IR file. */ | |
89fc3421 | 148 | LDPR_PREEMPTED_IR, |
8341e15b ILT |
149 | |
150 | /* This symbol was resolved by a definition in another IR file. */ | |
89fc3421 | 151 | LDPR_RESOLVED_IR, |
8341e15b ILT |
152 | |
153 | /* This symbol was resolved by a definition in a regular object | |
154 | linked into the main executable. */ | |
89fc3421 | 155 | LDPR_RESOLVED_EXEC, |
8341e15b ILT |
156 | |
157 | /* This symbol was resolved by a definition in a shared object. */ | |
79df06c4 DD |
158 | LDPR_RESOLVED_DYN, |
159 | ||
160 | /* This is the prevailing definition of the symbol, with no | |
161 | references from regular objects. It is only referenced from IR | |
162 | code, but the symbol is exported and may be referenced from | |
163 | a dynamic object (not seen at link time). */ | |
164 | LDPR_PREVAILING_DEF_IRONLY_EXP | |
89fc3421 CC |
165 | }; |
166 | ||
167 | /* The plugin library's "claim file" handler. */ | |
168 | ||
169 | typedef | |
170 | enum ld_plugin_status | |
171 | (*ld_plugin_claim_file_handler) ( | |
172 | const struct ld_plugin_input_file *file, int *claimed); | |
173 | ||
174 | /* The plugin library's "all symbols read" handler. */ | |
175 | ||
176 | typedef | |
177 | enum ld_plugin_status | |
178 | (*ld_plugin_all_symbols_read_handler) (void); | |
179 | ||
180 | /* The plugin library's cleanup handler. */ | |
181 | ||
182 | typedef | |
183 | enum ld_plugin_status | |
184 | (*ld_plugin_cleanup_handler) (void); | |
185 | ||
186 | /* The linker's interface for registering the "claim file" handler. */ | |
187 | ||
188 | typedef | |
189 | enum ld_plugin_status | |
190 | (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler); | |
191 | ||
192 | /* The linker's interface for registering the "all symbols read" handler. */ | |
193 | ||
194 | typedef | |
195 | enum ld_plugin_status | |
196 | (*ld_plugin_register_all_symbols_read) ( | |
197 | ld_plugin_all_symbols_read_handler handler); | |
198 | ||
199 | /* The linker's interface for registering the cleanup handler. */ | |
200 | ||
201 | typedef | |
202 | enum ld_plugin_status | |
203 | (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler); | |
204 | ||
205 | /* The linker's interface for adding symbols from a claimed input file. */ | |
206 | ||
207 | typedef | |
208 | enum ld_plugin_status | |
209 | (*ld_plugin_add_symbols) (void *handle, int nsyms, | |
210 | const struct ld_plugin_symbol *syms); | |
211 | ||
fa7f3e72 CC |
212 | /* The linker's interface for getting the input file information with |
213 | an open (possibly re-opened) file descriptor. */ | |
214 | ||
215 | typedef | |
216 | enum ld_plugin_status | |
217 | (*ld_plugin_get_input_file) (const void *handle, | |
218 | struct ld_plugin_input_file *file); | |
219 | ||
55406e10 RÁE |
220 | typedef |
221 | enum ld_plugin_status | |
222 | (*ld_plugin_get_view) (const void *handle, const void **viewp); | |
223 | ||
fa7f3e72 CC |
224 | /* The linker's interface for releasing the input file. */ |
225 | ||
226 | typedef | |
227 | enum ld_plugin_status | |
228 | (*ld_plugin_release_input_file) (const void *handle); | |
229 | ||
89fc3421 CC |
230 | /* The linker's interface for retrieving symbol resolution information. */ |
231 | ||
232 | typedef | |
233 | enum ld_plugin_status | |
234 | (*ld_plugin_get_symbols) (const void *handle, int nsyms, | |
235 | struct ld_plugin_symbol *syms); | |
236 | ||
237 | /* The linker's interface for adding a compiled input file. */ | |
238 | ||
239 | typedef | |
240 | enum ld_plugin_status | |
6508b958 | 241 | (*ld_plugin_add_input_file) (const char *pathname); |
89fc3421 | 242 | |
8341e15b ILT |
243 | /* The linker's interface for adding a library that should be searched. */ |
244 | ||
245 | typedef | |
246 | enum ld_plugin_status | |
6508b958 | 247 | (*ld_plugin_add_input_library) (const char *libname); |
8341e15b | 248 | |
42218b9f RÁE |
249 | /* The linker's interface for adding a library path that should be searched. */ |
250 | ||
251 | typedef | |
252 | enum ld_plugin_status | |
253 | (*ld_plugin_set_extra_library_path) (const char *path); | |
254 | ||
89fc3421 CC |
255 | /* The linker's interface for issuing a warning or error message. */ |
256 | ||
257 | typedef | |
258 | enum ld_plugin_status | |
6c52134c | 259 | (*ld_plugin_message) (int level, const char *format, ...); |
89fc3421 | 260 | |
e9552f7e ST |
261 | /* The linker's interface for retrieving the number of sections in an object. |
262 | The handle is obtained in the claim_file handler. This interface should | |
263 | only be invoked in the claim_file handler. This function sets *COUNT to | |
264 | the number of sections in the object. */ | |
265 | ||
266 | typedef | |
267 | enum ld_plugin_status | |
268 | (*ld_plugin_get_input_section_count) (const void* handle, unsigned int *count); | |
269 | ||
270 | /* The linker's interface for retrieving the section type of a specific | |
271 | section in an object. This interface should only be invoked in the | |
272 | claim_file handler. This function sets *TYPE to an ELF SHT_xxx value. */ | |
273 | ||
274 | typedef | |
275 | enum ld_plugin_status | |
276 | (*ld_plugin_get_input_section_type) (const struct ld_plugin_section section, | |
277 | unsigned int *type); | |
278 | ||
279 | /* The linker's interface for retrieving the name of a specific section in | |
280 | an object. This interface should only be invoked in the claim_file handler. | |
281 | This function sets *SECTION_NAME_PTR to a null-terminated buffer allocated | |
282 | by malloc. The plugin must free *SECTION_NAME_PTR. */ | |
283 | ||
284 | typedef | |
285 | enum ld_plugin_status | |
286 | (*ld_plugin_get_input_section_name) (const struct ld_plugin_section section, | |
287 | char **section_name_ptr); | |
288 | ||
289 | /* The linker's interface for retrieving the contents of a specific section | |
290 | in an object. This interface should only be invoked in the claim_file | |
291 | handler. This function sets *SECTION_CONTENTS to point to a buffer that is | |
292 | valid until clam_file handler returns. It sets *LEN to the size of the | |
293 | buffer. */ | |
294 | ||
295 | typedef | |
296 | enum ld_plugin_status | |
297 | (*ld_plugin_get_input_section_contents) (const struct ld_plugin_section section, | |
298 | const unsigned char **section_contents, | |
299 | size_t* len); | |
300 | ||
301 | /* The linker's interface for specifying the desired order of sections. | |
302 | The sections should be specifed using the array SECTION_LIST in the | |
303 | order in which they should appear in the final layout. NUM_SECTIONS | |
304 | specifies the number of entries in each array. This should be invoked | |
305 | in the all_symbols_read handler. */ | |
306 | ||
307 | typedef | |
308 | enum ld_plugin_status | |
309 | (*ld_plugin_update_section_order) (const struct ld_plugin_section *section_list, | |
310 | unsigned int num_sections); | |
311 | ||
312 | /* The linker's interface for specifying that reordering of sections is | |
313 | desired so that the linker can prepare for it. This should be invoked | |
314 | before update_section_order, preferably in the claim_file handler. */ | |
315 | ||
316 | typedef | |
317 | enum ld_plugin_status | |
318 | (*ld_plugin_allow_section_ordering) (void); | |
319 | ||
89fc3421 CC |
320 | enum ld_plugin_level |
321 | { | |
322 | LDPL_INFO, | |
323 | LDPL_WARNING, | |
324 | LDPL_ERROR, | |
bbb444b6 | 325 | LDPL_FATAL |
89fc3421 CC |
326 | }; |
327 | ||
328 | /* Values for the tv_tag field of the transfer vector. */ | |
329 | ||
330 | enum ld_plugin_tag | |
331 | { | |
332 | LDPT_NULL = 0, | |
333 | LDPT_API_VERSION, | |
334 | LDPT_GOLD_VERSION, | |
335 | LDPT_LINKER_OUTPUT, | |
336 | LDPT_OPTION, | |
337 | LDPT_REGISTER_CLAIM_FILE_HOOK, | |
338 | LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK, | |
339 | LDPT_REGISTER_CLEANUP_HOOK, | |
340 | LDPT_ADD_SYMBOLS, | |
341 | LDPT_GET_SYMBOLS, | |
342 | LDPT_ADD_INPUT_FILE, | |
fa7f3e72 CC |
343 | LDPT_MESSAGE, |
344 | LDPT_GET_INPUT_FILE, | |
8341e15b | 345 | LDPT_RELEASE_INPUT_FILE, |
3537c84b | 346 | LDPT_ADD_INPUT_LIBRARY, |
42218b9f | 347 | LDPT_OUTPUT_NAME, |
5d3236ee | 348 | LDPT_SET_EXTRA_LIBRARY_PATH, |
55406e10 | 349 | LDPT_GNU_LD_VERSION, |
e9552f7e ST |
350 | LDPT_GET_VIEW, |
351 | LDPT_GET_INPUT_SECTION_COUNT, | |
352 | LDPT_GET_INPUT_SECTION_TYPE, | |
353 | LDPT_GET_INPUT_SECTION_NAME, | |
354 | LDPT_GET_INPUT_SECTION_CONTENTS, | |
355 | LDPT_UPDATE_SECTION_ORDER, | |
79df06c4 DD |
356 | LDPT_ALLOW_SECTION_ORDERING, |
357 | LDPT_GET_SYMBOLS_V2 | |
89fc3421 CC |
358 | }; |
359 | ||
360 | /* The plugin transfer vector. */ | |
361 | ||
362 | struct ld_plugin_tv | |
363 | { | |
364 | enum ld_plugin_tag tv_tag; | |
365 | union | |
366 | { | |
367 | int tv_val; | |
368 | const char *tv_string; | |
369 | ld_plugin_register_claim_file tv_register_claim_file; | |
370 | ld_plugin_register_all_symbols_read tv_register_all_symbols_read; | |
371 | ld_plugin_register_cleanup tv_register_cleanup; | |
372 | ld_plugin_add_symbols tv_add_symbols; | |
373 | ld_plugin_get_symbols tv_get_symbols; | |
374 | ld_plugin_add_input_file tv_add_input_file; | |
375 | ld_plugin_message tv_message; | |
fa7f3e72 | 376 | ld_plugin_get_input_file tv_get_input_file; |
55406e10 | 377 | ld_plugin_get_view tv_get_view; |
fa7f3e72 | 378 | ld_plugin_release_input_file tv_release_input_file; |
8341e15b | 379 | ld_plugin_add_input_library tv_add_input_library; |
42218b9f | 380 | ld_plugin_set_extra_library_path tv_set_extra_library_path; |
e9552f7e ST |
381 | ld_plugin_get_input_section_count tv_get_input_section_count; |
382 | ld_plugin_get_input_section_type tv_get_input_section_type; | |
383 | ld_plugin_get_input_section_name tv_get_input_section_name; | |
384 | ld_plugin_get_input_section_contents tv_get_input_section_contents; | |
385 | ld_plugin_update_section_order tv_update_section_order; | |
386 | ld_plugin_allow_section_ordering tv_allow_section_ordering; | |
89fc3421 CC |
387 | } tv_u; |
388 | }; | |
389 | ||
390 | /* The plugin library's "onload" entry point. */ | |
391 | ||
392 | typedef | |
393 | enum ld_plugin_status | |
394 | (*ld_plugin_onload) (struct ld_plugin_tv *tv); | |
395 | ||
396 | #ifdef __cplusplus | |
a6bfd026 | 397 | } |
89fc3421 CC |
398 | #endif |
399 | ||
400 | #endif /* !defined(PLUGIN_API_H) */ |