]>
Commit | Line | Data |
---|---|---|
9227b6fc | 1 | @c Copyright (c) 2009 Free Software Foundation, Inc. |
2 | @c Free Software Foundation, Inc. | |
3 | @c This is part of the GCC manual. | |
4 | @c For copying conditions, see the file gcc.texi. | |
5 | ||
6 | @node Plugins | |
7 | @chapter Plugins | |
8 | @cindex Plugins | |
9 | ||
10 | @section Loading Plugins | |
11 | ||
740cd0be | 12 | Plugins are supported on platforms that support @option{-ldl |
9227b6fc | 13 | -rdynamic}. They are loaded by the compiler using @code{dlopen} |
14 | and invoked at pre-determined locations in the compilation | |
15 | process. | |
16 | ||
17 | Plugins are loaded with | |
18 | ||
19 | @option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]} | |
20 | ||
21 | The plugin arguments are parsed by GCC and passed to respective | |
22 | plugins as key-value pairs. Multiple plugins can be invoked by | |
23 | specifying multiple @option{-fplugin} arguments. | |
24 | ||
25 | ||
26 | @section Plugin API | |
27 | ||
28 | Plugins are activated by the compiler at specific events as defined in | |
29 | @file{gcc-plugin.h}. For each event of interest, the plugin should | |
30 | call @code{register_callback} specifying the name of the event and | |
31 | address of the callback function that will handle that event. | |
32 | ||
a0b14cdf | 33 | The header @file{gcc-plugin.h} must be the first gcc header to be included. |
34 | ||
8e6de413 | 35 | @subsection Plugin license check |
36 | ||
37 | Every plugin should define the global symbol @code{plugin_is_GPL_compatible} | |
38 | to assert that it has been licensed under a GPL-compatible license. | |
39 | If this symbol does not exist, the compiler will emit a fatal error | |
40 | and exit with the error message: | |
41 | ||
42 | @smallexample | |
43 | fatal error: plugin <name> is not licensed under a GPL-compatible license | |
44 | <name>: undefined symbol: plugin_is_GPL_compatible | |
45 | compilation terminated | |
46 | @end smallexample | |
47 | ||
48 | The type of the symbol is irrelevant. The compiler merely asserts that | |
49 | it exists in the global scope. Something like this is enough: | |
50 | ||
51 | @smallexample | |
52 | int plugin_is_GPL_compatible; | |
53 | @end smallexample | |
54 | ||
9227b6fc | 55 | @subsection Plugin initialization |
56 | ||
57 | Every plugin should export a function called @code{plugin_init} that | |
58 | is called right after the plugin is loaded. This function is | |
59 | responsible for registering all the callbacks required by the plugin | |
60 | and do any other required initialization. | |
61 | ||
62 | This function is called from @code{compile_file} right before invoking | |
63 | the parser. The arguments to @code{plugin_init} are: | |
64 | ||
65 | @itemize @bullet | |
0b3a031a | 66 | @item @code{plugin_info}: Plugin invocation information. |
67 | @item @code{version}: GCC version. | |
9227b6fc | 68 | @end itemize |
69 | ||
0b3a031a | 70 | The @code{plugin_info} struct is defined as follows: |
71 | ||
72 | @smallexample | |
73 | struct plugin_name_args | |
74 | @{ | |
75 | char *base_name; /* Short name of the plugin | |
76 | (filename without .so suffix). */ | |
77 | const char *full_name; /* Path to the plugin as specified with | |
78 | -fplugin=. */ | |
79 | int argc; /* Number of arguments specified with | |
80 | -fplugin-arg-.... */ | |
81 | struct plugin_argument *argv; /* Array of ARGC key-value pairs. */ | |
82 | const char *version; /* Version string provided by plugin. */ | |
83 | const char *help; /* Help string provided by plugin. */ | |
84 | @} | |
85 | @end smallexample | |
86 | ||
9227b6fc | 87 | If initialization fails, @code{plugin_init} must return a non-zero |
88 | value. Otherwise, it should return 0. | |
89 | ||
740cd0be | 90 | The version of the GCC compiler loading the plugin is described by the |
91 | following structure: | |
92 | ||
93 | @smallexample | |
94 | struct plugin_gcc_version | |
95 | @{ | |
96 | const char *basever; | |
97 | const char *datestamp; | |
98 | const char *devphase; | |
99 | const char *revision; | |
100 | const char *configuration_arguments; | |
101 | @}; | |
102 | @end smallexample | |
103 | ||
104 | The function @code{plugin_default_version_check} takes two pointers to | |
105 | such structure and compare them field by field. It can be used by the | |
106 | plugin's @code{plugin_init} function. | |
107 | ||
108 | ||
9227b6fc | 109 | @subsection Plugin callbacks |
110 | ||
111 | Callback functions have the following prototype: | |
112 | ||
113 | @smallexample | |
114 | /* The prototype for a plugin callback function. | |
115 | gcc_data - event-specific data provided by GCC | |
116 | user_data - plugin-specific data provided by the plug-in. */ | |
117 | typedef void (*plugin_callback_func)(void *gcc_data, void *user_data); | |
118 | @end smallexample | |
119 | ||
120 | Callbacks can be invoked at the following pre-determined events: | |
121 | ||
122 | ||
123 | @smallexample | |
124 | enum plugin_event | |
125 | @{ | |
126 | PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */ | |
127 | PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */ | |
128 | PLUGIN_FINISH_UNIT, /* Useful for summary processing. */ | |
129 | PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE. */ | |
130 | PLUGIN_FINISH, /* Called before GCC exits. */ | |
740cd0be | 131 | PLUGIN_INFO, /* Information about the plugin. */ |
132 | PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */ | |
133 | PLUGIN_GGC_MARKING, /* Extend the GGC marking. */ | |
134 | PLUGIN_GGC_END, /* Called at end of GGC. */ | |
135 | PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */ | |
86b63696 | 136 | PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */ |
e3fced1a | 137 | PLUGIN_ATTRIBUTES, /* Called during attribute registration */ |
275b769b | 138 | PLUGIN_START_UNIT, /* Called before processing a translation unit. */ |
329786f7 | 139 | PLUGIN_PRAGMAS, /* Called during pragma registration. */ |
9227b6fc | 140 | PLUGIN_EVENT_LAST /* Dummy event used for indexing callback |
141 | array. */ | |
142 | @}; | |
143 | @end smallexample | |
144 | ||
740cd0be | 145 | |
146 | To register a callback, the plugin calls @code{register_callback} with | |
147 | the arguments: | |
9227b6fc | 148 | |
149 | @itemize | |
150 | @item @code{char *name}: Plugin name. | |
151 | @item @code{enum plugin_event event}: The event code. | |
152 | @item @code{plugin_callback_func callback}: The function that handles @code{event}. | |
153 | @item @code{void *user_data}: Pointer to plugin-specific data. | |
154 | @end itemize | |
155 | ||
86b63696 | 156 | For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS |
157 | and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be | |
740cd0be | 158 | null, and the @code{user_data} is specific. |
9227b6fc | 159 | |
329786f7 | 160 | When the PLUGIN_PRAGMAS event is triggered (with a null |
161 | pointer as data from GCC), plugins may register their own pragmas | |
162 | using functions like @code{c_register_pragma} or | |
163 | @code{c_register_pragma_with_expansion}. | |
164 | ||
9227b6fc | 165 | @section Interacting with the pass manager |
166 | ||
167 | There needs to be a way to add/reorder/remove passes dynamically. This | |
168 | is useful for both analysis plugins (plugging in after a certain pass | |
169 | such as CFG or an IPA pass) and optimization plugins. | |
170 | ||
171 | Basic support for inserting new passes or replacing existing passes is | |
172 | provided. A plugin registers a new pass with GCC by calling | |
173 | @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP} | |
2a17b85d | 174 | event and a pointer to a @code{struct register_pass_info} object defined as follows |
9227b6fc | 175 | |
176 | @smallexample | |
177 | enum pass_positioning_ops | |
178 | @{ | |
179 | PASS_POS_INSERT_AFTER, // Insert after the reference pass. | |
180 | PASS_POS_INSERT_BEFORE, // Insert before the reference pass. | |
181 | PASS_POS_REPLACE // Replace the reference pass. | |
182 | @}; | |
183 | ||
2a17b85d | 184 | struct register_pass_info |
9227b6fc | 185 | @{ |
186 | struct opt_pass *pass; /* New pass provided by the plugin. */ | |
187 | const char *reference_pass_name; /* Name of the reference pass for hooking | |
188 | up the new pass. */ | |
189 | int ref_pass_instance_number; /* Insert the pass at the specified | |
190 | instance number of the reference pass. */ | |
191 | /* Do it for every instance if it is 0. */ | |
192 | enum pass_positioning_ops pos_op; /* how to insert the new pass. */ | |
193 | @}; | |
194 | ||
195 | ||
196 | /* Sample plugin code that registers a new pass. */ | |
197 | int | |
0b3a031a | 198 | plugin_init (struct plugin_name_args *plugin_info, |
199 | struct plugin_gcc_version *version) | |
9227b6fc | 200 | @{ |
2a17b85d | 201 | struct register_pass_info pass_info; |
9227b6fc | 202 | |
203 | ... | |
204 | ||
205 | /* Code to fill in the pass_info object with new pass information. */ | |
206 | ||
207 | ... | |
208 | ||
209 | /* Register the new pass. */ | |
0b3a031a | 210 | register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info); |
9227b6fc | 211 | |
212 | ... | |
213 | @} | |
214 | @end smallexample | |
740cd0be | 215 | |
216 | ||
217 | @section Interacting with the GCC Garbage Collector | |
218 | ||
219 | Some plugins may want to be informed when GGC (the GCC Garbage | |
220 | Collector) is running. They can register callbacks for the | |
221 | @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which | |
222 | the callback is called with a null @code{gcc_data}) to be notified of | |
223 | the start or end of the GCC garbage collection. | |
224 | ||
225 | Some plugins may need to have GGC mark additional data. This can be | |
226 | done by registering a callback (called with a null @code{gcc_data}) | |
227 | for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the | |
228 | @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro | |
9dc75945 | 229 | (and conversely, these routines should usually not be used in plugins |
230 | outside of the @code{PLUGIN_GGC_MARKING} event). | |
740cd0be | 231 | |
86b63696 | 232 | Some plugins may need to add extra GGC root tables, e.g. to handle their own |
233 | @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS} | |
234 | pseudo-event with a null callback and the extra root table (of type @code{struct | |
235 | ggc_root_tab*}) as @code{user_data}. Plugins that want to use the | |
236 | @code{if_marked} hash table option can add the extra GGC cache tables generated | |
237 | by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with | |
238 | a null callback and the extra cache table (of type @code{struct ggc_cache_tab*}) | |
239 | as @code{user_data}. Running the @code{gengtype -p @var{source-dir} | |
240 | @var{file-list} @var{plugin*.c} ...} utility generates these extra root tables. | |
740cd0be | 241 | |
242 | You should understand the details of memory management inside GCC | |
86b63696 | 243 | before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS} |
244 | or @code{PLUGIN_REGISTER_GGC_CACHES}. | |
740cd0be | 245 | |
246 | ||
247 | @section Giving information about a plugin | |
248 | ||
249 | A plugin should give some information to the user about itself. This | |
250 | uses the following structure: | |
251 | ||
252 | @smallexample | |
253 | struct plugin_info | |
254 | @{ | |
255 | const char *version; | |
256 | const char *help; | |
257 | @}; | |
258 | @end smallexample | |
259 | ||
260 | Such a structure is passed as the @code{user_data} by the plugin's | |
261 | init routine using @code{register_callback} with the | |
262 | @code{PLUGIN_INFO} pseudo-event and a null callback. | |
263 | ||
e3fced1a | 264 | @section Registering custom attributes |
265 | ||
266 | For analysis purposes it is useful to be able to add custom attributes. | |
267 | ||
268 | The @code{PLUGIN_ATTRIBUTES} callback is called during attribute | |
269 | registration. Use the @code{register_attribute} function to register | |
270 | custom attributes. | |
271 | ||
272 | @smallexample | |
273 | /* Attribute handler callback */ | |
274 | static tree | |
275 | handle_user_attribute (tree *node, tree name, tree args, | |
276 | int flags, bool *no_add_attrs) | |
277 | @{ | |
278 | return NULL_TREE; | |
279 | @} | |
280 | ||
281 | /* Attribute definition */ | |
282 | static struct attribute_spec user_attr = | |
283 | @{ "user", 1, 1, false, false, false, handle_user_attribute @}; | |
284 | ||
285 | /* Plugin callback called during attribute registration. | |
286 | Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL) | |
287 | */ | |
288 | static void | |
289 | register_attributes (void *event_data, void *data) | |
290 | @{ | |
291 | warning (0, G_("Callback to register attributes")); | |
292 | register_attribute (&user_attr); | |
293 | @} | |
294 | ||
295 | @end smallexample | |
d4fcd9bc | 296 | |
297 | ||
298 | @section Building GCC plugins | |
299 | ||
300 | If plugins are enabled, GCC installs the headers needed to build a | |
301 | plugin (somehwere in the installation tree, e.g. under | |
302 | @file{/usr/local}). In particular a @file{plugin/include} directory | |
303 | is installed, containing all the header files needed to build plugins. | |
304 | ||
305 | On most systems, you can query this @code{plugin} directory by | |
306 | invoking @command{gcc -print-file-name=plugin} (replace if needed | |
307 | @command{gcc} with the appropriate program path). | |
308 | ||
309 | The following GNU Makefile excerpt shows how to build a simple plugin: | |
310 | ||
311 | @smallexample | |
312 | GCC=gcc | |
313 | PLUGIN_SOURCE_FILES= plugin1.c plugin2.c | |
314 | PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES)) | |
315 | GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin) | |
316 | CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2 | |
317 | ||
318 | plugin.so: $(PLUGIN_OBJECT_FILES) | |
f5494808 | 319 | $(GCC) -shared $^ -o $@@ |
d4fcd9bc | 320 | @end smallexample |
321 | ||
322 | A single source file plugin may be built with @code{gcc -I`gcc | |
323 | -print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o | |
324 | plugin.so}, using backquote shell syntax to query the @file{plugin} | |
325 | directory. | |
326 | ||
327 | Plugins needing to use @command{gengtype} require a GCC build | |
328 | directory for the same version of GCC that they will be linked | |
329 | against. |