Commit | Line | Data |
---|---|---|
89fc3421 CC |
1 | /* plugin-api.h -- External linker plugin API. */ |
2 | ||
8341e15b | 3 | /* Copyright 2009 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 | ||
29 | #include <stdint.h> | |
30 | #include <sys/types.h> | |
31 | ||
32 | #ifdef __cplusplus | |
33 | extern "C" | |
34 | { | |
35 | #endif | |
36 | ||
37 | /* Status code returned by most API routines. */ | |
38 | ||
39 | enum ld_plugin_status | |
40 | { | |
41 | LDPS_OK = 0, | |
bbb444b6 | 42 | LDPS_NO_SYMS, /* Attempt to get symbols that haven't been added. */ |
fa7f3e72 | 43 | LDPS_BAD_HANDLE, /* No claimed object associated with given handle. */ |
bbb444b6 | 44 | LDPS_ERR |
89fc3421 CC |
45 | /* Additional Error codes TBD. */ |
46 | }; | |
47 | ||
48 | /* The version of the API specification. */ | |
49 | ||
50 | enum ld_plugin_api_version | |
51 | { | |
bbb444b6 | 52 | LD_PLUGIN_API_VERSION = 1 |
89fc3421 CC |
53 | }; |
54 | ||
55 | /* The type of output file being generated by the linker. */ | |
56 | ||
57 | enum ld_plugin_output_file_type | |
58 | { | |
59 | LDPO_REL, | |
60 | LDPO_EXEC, | |
bbb444b6 | 61 | LDPO_DYN |
89fc3421 CC |
62 | }; |
63 | ||
64 | /* An input file managed by the plugin library. */ | |
65 | ||
66 | struct ld_plugin_input_file | |
67 | { | |
68 | const char *name; | |
69 | int fd; | |
70 | off_t offset; | |
71 | off_t filesize; | |
72 | void *handle; | |
73 | }; | |
74 | ||
75 | /* A symbol belonging to an input file managed by the plugin library. */ | |
76 | ||
77 | struct ld_plugin_symbol | |
78 | { | |
79 | char *name; | |
80 | char *version; | |
81 | int def; | |
82 | int visibility; | |
83 | uint64_t size; | |
84 | char *comdat_key; | |
85 | int resolution; | |
86 | }; | |
87 | ||
88 | /* Whether the symbol is a definition, reference, or common, weak or not. */ | |
89 | ||
90 | enum ld_plugin_symbol_kind | |
91 | { | |
92 | LDPK_DEF, | |
93 | LDPK_WEAKDEF, | |
94 | LDPK_UNDEF, | |
95 | LDPK_WEAKUNDEF, | |
bbb444b6 | 96 | LDPK_COMMON |
89fc3421 CC |
97 | }; |
98 | ||
99 | /* The visibility of the symbol. */ | |
100 | ||
101 | enum ld_plugin_symbol_visibility | |
102 | { | |
103 | LDPV_DEFAULT, | |
104 | LDPV_PROTECTED, | |
105 | LDPV_INTERNAL, | |
bbb444b6 | 106 | LDPV_HIDDEN |
89fc3421 CC |
107 | }; |
108 | ||
109 | /* How a symbol is resolved. */ | |
110 | ||
111 | enum ld_plugin_symbol_resolution | |
112 | { | |
113 | LDPR_UNKNOWN = 0, | |
8341e15b ILT |
114 | |
115 | /* Symbol is still undefined at this point. */ | |
89fc3421 | 116 | LDPR_UNDEF, |
8341e15b ILT |
117 | |
118 | /* This is the prevailing definition of the symbol, with references from | |
119 | regular object code. */ | |
89fc3421 | 120 | LDPR_PREVAILING_DEF, |
8341e15b ILT |
121 | |
122 | /* This is the prevailing definition of the symbol, with no | |
123 | references from regular objects. It is only referenced from IR | |
124 | code. */ | |
89fc3421 | 125 | LDPR_PREVAILING_DEF_IRONLY, |
8341e15b ILT |
126 | |
127 | /* This definition was pre-empted by a definition in a regular | |
128 | object file. */ | |
89fc3421 | 129 | LDPR_PREEMPTED_REG, |
8341e15b ILT |
130 | |
131 | /* This definition was pre-empted by a definition in another IR file. */ | |
89fc3421 | 132 | LDPR_PREEMPTED_IR, |
8341e15b ILT |
133 | |
134 | /* This symbol was resolved by a definition in another IR file. */ | |
89fc3421 | 135 | LDPR_RESOLVED_IR, |
8341e15b ILT |
136 | |
137 | /* This symbol was resolved by a definition in a regular object | |
138 | linked into the main executable. */ | |
89fc3421 | 139 | LDPR_RESOLVED_EXEC, |
8341e15b ILT |
140 | |
141 | /* This symbol was resolved by a definition in a shared object. */ | |
bbb444b6 | 142 | LDPR_RESOLVED_DYN |
89fc3421 CC |
143 | }; |
144 | ||
145 | /* The plugin library's "claim file" handler. */ | |
146 | ||
147 | typedef | |
148 | enum ld_plugin_status | |
149 | (*ld_plugin_claim_file_handler) ( | |
150 | const struct ld_plugin_input_file *file, int *claimed); | |
151 | ||
152 | /* The plugin library's "all symbols read" handler. */ | |
153 | ||
154 | typedef | |
155 | enum ld_plugin_status | |
156 | (*ld_plugin_all_symbols_read_handler) (void); | |
157 | ||
158 | /* The plugin library's cleanup handler. */ | |
159 | ||
160 | typedef | |
161 | enum ld_plugin_status | |
162 | (*ld_plugin_cleanup_handler) (void); | |
163 | ||
164 | /* The linker's interface for registering the "claim file" handler. */ | |
165 | ||
166 | typedef | |
167 | enum ld_plugin_status | |
168 | (*ld_plugin_register_claim_file) (ld_plugin_claim_file_handler handler); | |
169 | ||
170 | /* The linker's interface for registering the "all symbols read" handler. */ | |
171 | ||
172 | typedef | |
173 | enum ld_plugin_status | |
174 | (*ld_plugin_register_all_symbols_read) ( | |
175 | ld_plugin_all_symbols_read_handler handler); | |
176 | ||
177 | /* The linker's interface for registering the cleanup handler. */ | |
178 | ||
179 | typedef | |
180 | enum ld_plugin_status | |
181 | (*ld_plugin_register_cleanup) (ld_plugin_cleanup_handler handler); | |
182 | ||
183 | /* The linker's interface for adding symbols from a claimed input file. */ | |
184 | ||
185 | typedef | |
186 | enum ld_plugin_status | |
187 | (*ld_plugin_add_symbols) (void *handle, int nsyms, | |
188 | const struct ld_plugin_symbol *syms); | |
189 | ||
fa7f3e72 CC |
190 | /* The linker's interface for getting the input file information with |
191 | an open (possibly re-opened) file descriptor. */ | |
192 | ||
193 | typedef | |
194 | enum ld_plugin_status | |
195 | (*ld_plugin_get_input_file) (const void *handle, | |
196 | struct ld_plugin_input_file *file); | |
197 | ||
198 | /* The linker's interface for releasing the input file. */ | |
199 | ||
200 | typedef | |
201 | enum ld_plugin_status | |
202 | (*ld_plugin_release_input_file) (const void *handle); | |
203 | ||
89fc3421 CC |
204 | /* The linker's interface for retrieving symbol resolution information. */ |
205 | ||
206 | typedef | |
207 | enum ld_plugin_status | |
208 | (*ld_plugin_get_symbols) (const void *handle, int nsyms, | |
209 | struct ld_plugin_symbol *syms); | |
210 | ||
211 | /* The linker's interface for adding a compiled input file. */ | |
212 | ||
213 | typedef | |
214 | enum ld_plugin_status | |
215 | (*ld_plugin_add_input_file) (char *pathname); | |
216 | ||
8341e15b ILT |
217 | /* The linker's interface for adding a library that should be searched. */ |
218 | ||
219 | typedef | |
220 | enum ld_plugin_status | |
221 | (*ld_plugin_add_input_library) (char *pathname); | |
222 | ||
89fc3421 CC |
223 | /* The linker's interface for issuing a warning or error message. */ |
224 | ||
225 | typedef | |
226 | enum ld_plugin_status | |
6c52134c | 227 | (*ld_plugin_message) (int level, const char *format, ...); |
89fc3421 CC |
228 | |
229 | enum ld_plugin_level | |
230 | { | |
231 | LDPL_INFO, | |
232 | LDPL_WARNING, | |
233 | LDPL_ERROR, | |
bbb444b6 | 234 | LDPL_FATAL |
89fc3421 CC |
235 | }; |
236 | ||
237 | /* Values for the tv_tag field of the transfer vector. */ | |
238 | ||
239 | enum ld_plugin_tag | |
240 | { | |
241 | LDPT_NULL = 0, | |
242 | LDPT_API_VERSION, | |
243 | LDPT_GOLD_VERSION, | |
244 | LDPT_LINKER_OUTPUT, | |
245 | LDPT_OPTION, | |
246 | LDPT_REGISTER_CLAIM_FILE_HOOK, | |
247 | LDPT_REGISTER_ALL_SYMBOLS_READ_HOOK, | |
248 | LDPT_REGISTER_CLEANUP_HOOK, | |
249 | LDPT_ADD_SYMBOLS, | |
250 | LDPT_GET_SYMBOLS, | |
251 | LDPT_ADD_INPUT_FILE, | |
fa7f3e72 CC |
252 | LDPT_MESSAGE, |
253 | LDPT_GET_INPUT_FILE, | |
8341e15b ILT |
254 | LDPT_RELEASE_INPUT_FILE, |
255 | LDPT_ADD_INPUT_LIBRARY | |
89fc3421 CC |
256 | }; |
257 | ||
258 | /* The plugin transfer vector. */ | |
259 | ||
260 | struct ld_plugin_tv | |
261 | { | |
262 | enum ld_plugin_tag tv_tag; | |
263 | union | |
264 | { | |
265 | int tv_val; | |
266 | const char *tv_string; | |
267 | ld_plugin_register_claim_file tv_register_claim_file; | |
268 | ld_plugin_register_all_symbols_read tv_register_all_symbols_read; | |
269 | ld_plugin_register_cleanup tv_register_cleanup; | |
270 | ld_plugin_add_symbols tv_add_symbols; | |
271 | ld_plugin_get_symbols tv_get_symbols; | |
272 | ld_plugin_add_input_file tv_add_input_file; | |
273 | ld_plugin_message tv_message; | |
fa7f3e72 CC |
274 | ld_plugin_get_input_file tv_get_input_file; |
275 | ld_plugin_release_input_file tv_release_input_file; | |
8341e15b | 276 | ld_plugin_add_input_library tv_add_input_library; |
89fc3421 CC |
277 | } tv_u; |
278 | }; | |
279 | ||
280 | /* The plugin library's "onload" entry point. */ | |
281 | ||
282 | typedef | |
283 | enum ld_plugin_status | |
284 | (*ld_plugin_onload) (struct ld_plugin_tv *tv); | |
285 | ||
286 | #ifdef __cplusplus | |
a6bfd026 | 287 | } |
89fc3421 CC |
288 | #endif |
289 | ||
290 | #endif /* !defined(PLUGIN_API_H) */ |