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 type of the symbol is irrelevant. The compiler merely asserts that
54 it exists in the global scope. Something like this is enough:
57 int plugin_is_GPL_compatible;
60 @subsection Plugin initialization
62 Every plugin should export a function called @code{plugin_init} that
63 is called right after the plugin is loaded. This function is
64 responsible for registering all the callbacks required by the plugin
65 and do any other required initialization.
67 This function is called from @code{compile_file} right before invoking
68 the parser. The arguments to @code{plugin_init} are:
71 @item @code{plugin_info}: Plugin invocation information.
72 @item @code{version}: GCC version.
75 The @code{plugin_info} struct is defined as follows:
78 struct plugin_name_args
80 char *base_name; /* Short name of the plugin
81 (filename without .so suffix). */
82 const char *full_name; /* Path to the plugin as specified with
84 int argc; /* Number of arguments specified with
86 struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
87 const char *version; /* Version string provided by plugin. */
88 const char *help; /* Help string provided by plugin. */
92 If initialization fails, @code{plugin_init} must return a non-zero
93 value. Otherwise, it should return 0.
95 The version of the GCC compiler loading the plugin is described by the
99 struct plugin_gcc_version
102 const char *datestamp;
103 const char *devphase;
104 const char *revision;
105 const char *configuration_arguments;
109 The function @code{plugin_default_version_check} takes two pointers to
110 such structure and compare them field by field. It can be used by the
111 plugin's @code{plugin_init} function.
113 The version of GCC used to compile the plugin can be found in the symbol
114 @code{gcc_version} defined in the header @file{plugin-version.h}. The
115 recommended version check to perform looks like
118 #include "plugin-version.h"
122 plugin_init (struct plugin_name_args *plugin_info,
123 struct plugin_gcc_version *version)
125 if (!plugin_default_version_check (version, &gcc_version))
131 but you can also check the individual fields if you want a less strict check.
133 @subsection Plugin callbacks
135 Callback functions have the following prototype:
138 /* The prototype for a plugin callback function.
139 gcc_data - event-specific data provided by GCC
140 user_data - plugin-specific data provided by the plug-in. */
141 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
144 Callbacks can be invoked at the following pre-determined events:
150 PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
151 PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
152 PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
153 PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
154 PLUGIN_FINISH, /* Called before GCC exits. */
155 PLUGIN_INFO, /* Information about the plugin. */
156 PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
157 PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
158 PLUGIN_GGC_END, /* Called at end of GGC. */
159 PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
160 PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
161 PLUGIN_ATTRIBUTES, /* Called during attribute registration */
162 PLUGIN_START_UNIT, /* Called before processing a translation unit. */
163 PLUGIN_PRAGMAS, /* Called during pragma registration. */
164 /* Called before first pass from all_passes. */
165 PLUGIN_ALL_PASSES_START,
166 /* Called after last pass from all_passes. */
167 PLUGIN_ALL_PASSES_END,
168 /* Called before first ipa pass. */
169 PLUGIN_ALL_IPA_PASSES_START,
170 /* Called after last ipa pass. */
171 PLUGIN_ALL_IPA_PASSES_END,
172 /* Allows to override pass gate decision for current_pass. */
173 PLUGIN_OVERRIDE_GATE,
174 /* Called before executing a pass. */
175 PLUGIN_PASS_EXECUTION,
176 /* Called before executing subpasses of a GIMPLE_PASS in
177 execute_ipa_pass_list. */
178 PLUGIN_EARLY_GIMPLE_PASSES_START,
179 /* Called after executing subpasses of a GIMPLE_PASS in
180 execute_ipa_pass_list. */
181 PLUGIN_EARLY_GIMPLE_PASSES_END,
182 /* Called when a pass is first instantiated. */
185 PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
190 In addition, plugins can also look up the enumerator of a named event,
191 and / or generate new events dynamically, by calling the function
192 @code{get_named_event_id}.
194 To register a callback, the plugin calls @code{register_callback} with
198 @item @code{char *name}: Plugin name.
199 @item @code{int event}: The event code.
200 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
201 @item @code{void *user_data}: Pointer to plugin-specific data.
204 For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
205 and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
206 null, and the @code{user_data} is specific.
208 When the PLUGIN_PRAGMAS event is triggered (with a null
209 pointer as data from GCC), plugins may register their own pragmas
210 using functions like @code{c_register_pragma} or
211 @code{c_register_pragma_with_expansion}.
213 @section Interacting with the pass manager
215 There needs to be a way to add/reorder/remove passes dynamically. This
216 is useful for both analysis plugins (plugging in after a certain pass
217 such as CFG or an IPA pass) and optimization plugins.
219 Basic support for inserting new passes or replacing existing passes is
220 provided. A plugin registers a new pass with GCC by calling
221 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
222 event and a pointer to a @code{struct register_pass_info} object defined as follows
225 enum pass_positioning_ops
227 PASS_POS_INSERT_AFTER, // Insert after the reference pass.
228 PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
229 PASS_POS_REPLACE // Replace the reference pass.
232 struct register_pass_info
234 struct opt_pass *pass; /* New pass provided by the plugin. */
235 const char *reference_pass_name; /* Name of the reference pass for hooking
237 int ref_pass_instance_number; /* Insert the pass at the specified
238 instance number of the reference pass. */
239 /* Do it for every instance if it is 0. */
240 enum pass_positioning_ops pos_op; /* how to insert the new pass. */
244 /* Sample plugin code that registers a new pass. */
246 plugin_init (struct plugin_name_args *plugin_info,
247 struct plugin_gcc_version *version)
249 struct register_pass_info pass_info;
253 /* Code to fill in the pass_info object with new pass information. */
257 /* Register the new pass. */
258 register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
265 @section Interacting with the GCC Garbage Collector
267 Some plugins may want to be informed when GGC (the GCC Garbage
268 Collector) is running. They can register callbacks for the
269 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
270 the callback is called with a null @code{gcc_data}) to be notified of
271 the start or end of the GCC garbage collection.
273 Some plugins may need to have GGC mark additional data. This can be
274 done by registering a callback (called with a null @code{gcc_data})
275 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
276 @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
277 (and conversely, these routines should usually not be used in plugins
278 outside of the @code{PLUGIN_GGC_MARKING} event).
280 Some plugins may need to add extra GGC root tables, e.g. to handle their own
281 @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
282 pseudo-event with a null callback and the extra root table (of type @code{struct
283 ggc_root_tab*}) as @code{user_data}. Plugins that want to use the
284 @code{if_marked} hash table option can add the extra GGC cache tables generated
285 by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with
286 a null callback and the extra cache table (of type @code{struct ggc_cache_tab*})
287 as @code{user_data}. Running the @code{gengtype -p @var{source-dir}
288 @var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
290 You should understand the details of memory management inside GCC
291 before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
292 or @code{PLUGIN_REGISTER_GGC_CACHES}.
295 @section Giving information about a plugin
297 A plugin should give some information to the user about itself. This
298 uses the following structure:
308 Such a structure is passed as the @code{user_data} by the plugin's
309 init routine using @code{register_callback} with the
310 @code{PLUGIN_INFO} pseudo-event and a null callback.
312 @section Registering custom attributes or pragmas
314 For analysis (or other) purposes it is useful to be able to add custom
315 attributes or pragmas.
317 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
318 registration. Use the @code{register_attribute} function to register
322 /* Attribute handler callback */
324 handle_user_attribute (tree *node, tree name, tree args,
325 int flags, bool *no_add_attrs)
330 /* Attribute definition */
331 static struct attribute_spec user_attr =
332 @{ "user", 1, 1, false, false, false, handle_user_attribute @};
334 /* Plugin callback called during attribute registration.
335 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
338 register_attributes (void *event_data, void *data)
340 warning (0, G_("Callback to register attributes"));
341 register_attribute (&user_attr);
347 The @code{PLUGIN_PRAGMAS} callback is called during pragmas
348 registration. Use the @code{c_register_pragma} or
349 @code{c_register_pragma_with_expansion} functions to register custom
353 /* Plugin callback called during pragmas registration. Registered with
354 register_callback (plugin_name, PLUGIN_PRAGMAS,
355 register_my_pragma, NULL);
358 register_my_pragma (void *event_data, void *data)
360 warning (0, G_("Callback to register pragmas"));
361 c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
365 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
366 your plugin) as the ``space'' argument of your pragma.
369 @section Recording information about pass execution
371 The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
372 (the same as current_pass) as @code{gcc_data} to the callback. You can also
373 inspect cfun to find out about which function this pass is executed for.
374 Note that this event will only be invoked if the gate check (if
375 applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
376 You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
377 @code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
378 @code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
379 and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
380 in your plugin(s) in order to get context for the pass execution.
383 @section Controlling which passes are being run
385 After the original gate function for a pass is called, its result
386 - the gate status - is stored as an integer.
387 Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
388 to the gate status in the @code{gcc_data} parameter to the callback function.
389 A nonzero value of the gate status means that the pass is to be executed.
390 You can both read and write the gate status via the passed pointer.
393 @section Keeping track of available passes
395 When your plugin is loaded, you can inspect the various
396 pass lists to determine what passes are available. However, other
397 plugins might add new passes. Also, future changes to GCC might cause
398 generic passes to be added after plugin loading.
399 When a pass is first added to one of the pass lists, the event
400 @code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
401 @code{gcc_data} pointing to the new pass.
404 @section Building GCC plugins
406 If plugins are enabled, GCC installs the headers needed to build a
407 plugin (somewhere in the installation tree, e.g. under
408 @file{/usr/local}). In particular a @file{plugin/include} directory
409 is installed, containing all the header files needed to build plugins.
411 On most systems, you can query this @code{plugin} directory by
412 invoking @command{gcc -print-file-name=plugin} (replace if needed
413 @command{gcc} with the appropriate program path).
415 Inside plugins, this @code{plugin} directory name can be queried by
416 calling @code{default_plugin_dir_name ()}.
418 The following GNU Makefile excerpt shows how to build a simple plugin:
422 PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
423 PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
424 GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
425 CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
427 plugin.so: $(PLUGIN_OBJECT_FILES)
428 $(GCC) -shared $^ -o $@@
431 A single source file plugin may be built with @code{gcc -I`gcc
432 -print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
433 plugin.so}, using backquote shell syntax to query the @file{plugin}
436 Plugins needing to use @command{gengtype} require a GCC build
437 directory for the same version of GCC that they will be linked