1 @c Copyright (c) 2009, 2010 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.
10 @section Loading Plugins
12 Plugins are supported on platforms that support @option{-ldl
13 -rdynamic}. They are loaded by the compiler using @code{dlopen}
14 and invoked at pre-determined locations in the compilation
17 Plugins are loaded with
19 @option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
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.
25 A plugin can be simply given by its short name (no dots or
26 slashes). When simply passing @option{-fplugin=NAME}, the plugin is
27 loaded from the @file{plugin} directory, so @option{-fplugin=NAME} is
28 the same as @option{-fplugin=`gcc -print-file-name=plugin`/NAME.so},
29 using backquote shell syntax to query the @file{plugin} directory.
33 Plugins are activated by the compiler at specific events as defined in
34 @file{gcc-plugin.h}. For each event of interest, the plugin should
35 call @code{register_callback} specifying the name of the event and
36 address of the callback function that will handle that event.
38 The header @file{gcc-plugin.h} must be the first gcc header to be included.
40 @subsection Plugin license check
42 Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
43 to assert that it has been licensed under a GPL-compatible license.
44 If this symbol does not exist, the compiler will emit a fatal error
45 and exit with the error message:
48 fatal error: plugin <name> is not licensed under a GPL-compatible license
49 <name>: undefined symbol: plugin_is_GPL_compatible
50 compilation terminated
53 The declared type of the symbol should be int, to match a forward declaration
54 in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in
55 any allocated section, though. The compiler merely asserts that
56 the symbol exists in the global scope. Something like this is enough:
59 int plugin_is_GPL_compatible;
62 @subsection Plugin initialization
64 Every plugin should export a function called @code{plugin_init} that
65 is called right after the plugin is loaded. This function is
66 responsible for registering all the callbacks required by the plugin
67 and do any other required initialization.
69 This function is called from @code{compile_file} right before invoking
70 the parser. The arguments to @code{plugin_init} are:
73 @item @code{plugin_info}: Plugin invocation information.
74 @item @code{version}: GCC version.
77 The @code{plugin_info} struct is defined as follows:
80 struct plugin_name_args
82 char *base_name; /* Short name of the plugin
83 (filename without .so suffix). */
84 const char *full_name; /* Path to the plugin as specified with
86 int argc; /* Number of arguments specified with
88 struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
89 const char *version; /* Version string provided by plugin. */
90 const char *help; /* Help string provided by plugin. */
94 If initialization fails, @code{plugin_init} must return a non-zero
95 value. Otherwise, it should return 0.
97 The version of the GCC compiler loading the plugin is described by the
101 struct plugin_gcc_version
104 const char *datestamp;
105 const char *devphase;
106 const char *revision;
107 const char *configuration_arguments;
111 The function @code{plugin_default_version_check} takes two pointers to
112 such structure and compare them field by field. It can be used by the
113 plugin's @code{plugin_init} function.
115 The version of GCC used to compile the plugin can be found in the symbol
116 @code{gcc_version} defined in the header @file{plugin-version.h}. The
117 recommended version check to perform looks like
120 #include "plugin-version.h"
124 plugin_init (struct plugin_name_args *plugin_info,
125 struct plugin_gcc_version *version)
127 if (!plugin_default_version_check (version, &gcc_version))
133 but you can also check the individual fields if you want a less strict check.
135 @subsection Plugin callbacks
137 Callback functions have the following prototype:
140 /* The prototype for a plugin callback function.
141 gcc_data - event-specific data provided by GCC
142 user_data - plugin-specific data provided by the plug-in. */
143 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
146 Callbacks can be invoked at the following pre-determined events:
152 PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
153 PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
154 PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
155 PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
156 PLUGIN_FINISH, /* Called before GCC exits. */
157 PLUGIN_INFO, /* Information about the plugin. */
158 PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
159 PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
160 PLUGIN_GGC_END, /* Called at end of GGC. */
161 PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
162 PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
163 PLUGIN_ATTRIBUTES, /* Called during attribute registration */
164 PLUGIN_START_UNIT, /* Called before processing a translation unit. */
165 PLUGIN_PRAGMAS, /* Called during pragma registration. */
166 /* Called before first pass from all_passes. */
167 PLUGIN_ALL_PASSES_START,
168 /* Called after last pass from all_passes. */
169 PLUGIN_ALL_PASSES_END,
170 /* Called before first ipa pass. */
171 PLUGIN_ALL_IPA_PASSES_START,
172 /* Called after last ipa pass. */
173 PLUGIN_ALL_IPA_PASSES_END,
174 /* Allows to override pass gate decision for current_pass. */
175 PLUGIN_OVERRIDE_GATE,
176 /* Called before executing a pass. */
177 PLUGIN_PASS_EXECUTION,
178 /* Called before executing subpasses of a GIMPLE_PASS in
179 execute_ipa_pass_list. */
180 PLUGIN_EARLY_GIMPLE_PASSES_START,
181 /* Called after executing subpasses of a GIMPLE_PASS in
182 execute_ipa_pass_list. */
183 PLUGIN_EARLY_GIMPLE_PASSES_END,
184 /* Called when a pass is first instantiated. */
187 PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
192 In addition, plugins can also look up the enumerator of a named event,
193 and / or generate new events dynamically, by calling the function
194 @code{get_named_event_id}.
196 To register a callback, the plugin calls @code{register_callback} with
200 @item @code{char *name}: Plugin name.
201 @item @code{int event}: The event code.
202 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
203 @item @code{void *user_data}: Pointer to plugin-specific data.
206 For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
207 and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
208 null, and the @code{user_data} is specific.
210 When the PLUGIN_PRAGMAS event is triggered (with a null
211 pointer as data from GCC), plugins may register their own pragmas
212 using functions like @code{c_register_pragma} or
213 @code{c_register_pragma_with_expansion}.
215 @section Interacting with the pass manager
217 There needs to be a way to add/reorder/remove passes dynamically. This
218 is useful for both analysis plugins (plugging in after a certain pass
219 such as CFG or an IPA pass) and optimization plugins.
221 Basic support for inserting new passes or replacing existing passes is
222 provided. A plugin registers a new pass with GCC by calling
223 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
224 event and a pointer to a @code{struct register_pass_info} object defined as follows
227 enum pass_positioning_ops
229 PASS_POS_INSERT_AFTER, // Insert after the reference pass.
230 PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
231 PASS_POS_REPLACE // Replace the reference pass.
234 struct register_pass_info
236 struct opt_pass *pass; /* New pass provided by the plugin. */
237 const char *reference_pass_name; /* Name of the reference pass for hooking
239 int ref_pass_instance_number; /* Insert the pass at the specified
240 instance number of the reference pass. */
241 /* Do it for every instance if it is 0. */
242 enum pass_positioning_ops pos_op; /* how to insert the new pass. */
246 /* Sample plugin code that registers a new pass. */
248 plugin_init (struct plugin_name_args *plugin_info,
249 struct plugin_gcc_version *version)
251 struct register_pass_info pass_info;
255 /* Code to fill in the pass_info object with new pass information. */
259 /* Register the new pass. */
260 register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
267 @section Interacting with the GCC Garbage Collector
269 Some plugins may want to be informed when GGC (the GCC Garbage
270 Collector) is running. They can register callbacks for the
271 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
272 the callback is called with a null @code{gcc_data}) to be notified of
273 the start or end of the GCC garbage collection.
275 Some plugins may need to have GGC mark additional data. This can be
276 done by registering a callback (called with a null @code{gcc_data})
277 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
278 @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
279 (and conversely, these routines should usually not be used in plugins
280 outside of the @code{PLUGIN_GGC_MARKING} event).
282 Some plugins may need to add extra GGC root tables, e.g. to handle their own
283 @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
284 pseudo-event with a null callback and the extra root table (of type @code{struct
285 ggc_root_tab*}) as @code{user_data}. Plugins that want to use the
286 @code{if_marked} hash table option can add the extra GGC cache tables generated
287 by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with
288 a null callback and the extra cache table (of type @code{struct ggc_cache_tab*})
289 as @code{user_data}. Running the @code{gengtype -p @var{source-dir}
290 @var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
292 You should understand the details of memory management inside GCC
293 before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
294 or @code{PLUGIN_REGISTER_GGC_CACHES}.
297 @section Giving information about a plugin
299 A plugin should give some information to the user about itself. This
300 uses the following structure:
310 Such a structure is passed as the @code{user_data} by the plugin's
311 init routine using @code{register_callback} with the
312 @code{PLUGIN_INFO} pseudo-event and a null callback.
314 @section Registering custom attributes or pragmas
316 For analysis (or other) purposes it is useful to be able to add custom
317 attributes or pragmas.
319 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
320 registration. Use the @code{register_attribute} function to register
324 /* Attribute handler callback */
326 handle_user_attribute (tree *node, tree name, tree args,
327 int flags, bool *no_add_attrs)
332 /* Attribute definition */
333 static struct attribute_spec user_attr =
334 @{ "user", 1, 1, false, false, false, handle_user_attribute @};
336 /* Plugin callback called during attribute registration.
337 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
340 register_attributes (void *event_data, void *data)
342 warning (0, G_("Callback to register attributes"));
343 register_attribute (&user_attr);
349 The @code{PLUGIN_PRAGMAS} callback is called during pragmas
350 registration. Use the @code{c_register_pragma} or
351 @code{c_register_pragma_with_expansion} functions to register custom
355 /* Plugin callback called during pragmas registration. Registered with
356 register_callback (plugin_name, PLUGIN_PRAGMAS,
357 register_my_pragma, NULL);
360 register_my_pragma (void *event_data, void *data)
362 warning (0, G_("Callback to register pragmas"));
363 c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
367 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
368 your plugin) as the ``space'' argument of your pragma.
371 @section Recording information about pass execution
373 The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
374 (the same as current_pass) as @code{gcc_data} to the callback. You can also
375 inspect cfun to find out about which function this pass is executed for.
376 Note that this event will only be invoked if the gate check (if
377 applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
378 You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
379 @code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
380 @code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
381 and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
382 in your plugin(s) in order to get context for the pass execution.
385 @section Controlling which passes are being run
387 After the original gate function for a pass is called, its result
388 - the gate status - is stored as an integer.
389 Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
390 to the gate status in the @code{gcc_data} parameter to the callback function.
391 A nonzero value of the gate status means that the pass is to be executed.
392 You can both read and write the gate status via the passed pointer.
395 @section Keeping track of available passes
397 When your plugin is loaded, you can inspect the various
398 pass lists to determine what passes are available. However, other
399 plugins might add new passes. Also, future changes to GCC might cause
400 generic passes to be added after plugin loading.
401 When a pass is first added to one of the pass lists, the event
402 @code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
403 @code{gcc_data} pointing to the new pass.
406 @section Building GCC plugins
408 If plugins are enabled, GCC installs the headers needed to build a
409 plugin (somewhere in the installation tree, e.g. under
410 @file{/usr/local}). In particular a @file{plugin/include} directory
411 is installed, containing all the header files needed to build plugins.
413 On most systems, you can query this @code{plugin} directory by
414 invoking @command{gcc -print-file-name=plugin} (replace if needed
415 @command{gcc} with the appropriate program path).
417 Inside plugins, this @code{plugin} directory name can be queried by
418 calling @code{default_plugin_dir_name ()}.
420 The following GNU Makefile excerpt shows how to build a simple plugin:
424 PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
425 PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
426 GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
427 CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
429 plugin.so: $(PLUGIN_OBJECT_FILES)
430 $(GCC) -shared $^ -o $@@
433 A single source file plugin may be built with @code{gcc -I`gcc
434 -print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
435 plugin.so}, using backquote shell syntax to query the @file{plugin}
438 Plugins needing to use @command{gengtype} require a GCC build
439 directory for the same version of GCC that they will be linked