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.
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.
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.
33 The header @file{gcc-plugin.h} must be the first gcc header to be included.
35 @subsection Plugin license check
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:
43 fatal error: plugin <name> is not licensed under a GPL-compatible license
44 <name>: undefined symbol: plugin_is_GPL_compatible
45 compilation terminated
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:
52 int plugin_is_GPL_compatible;
55 @subsection Plugin initialization
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.
62 This function is called from @code{compile_file} right before invoking
63 the parser. The arguments to @code{plugin_init} are:
66 @item @code{plugin_info}: Plugin invocation information.
67 @item @code{version}: GCC version.
70 The @code{plugin_info} struct is defined as follows:
73 struct plugin_name_args
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
79 int argc; /* Number of arguments specified with
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. */
87 If initialization fails, @code{plugin_init} must return a non-zero
88 value. Otherwise, it should return 0.
90 The version of the GCC compiler loading the plugin is described by the
94 struct plugin_gcc_version
97 const char *datestamp;
100 const char *configuration_arguments;
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.
109 @subsection Plugin callbacks
111 Callback functions have the following prototype:
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);
120 Callbacks can be invoked at the following pre-determined events:
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. */
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. */
136 PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
137 PLUGIN_ATTRIBUTES, /* Called during attribute registration */
138 PLUGIN_START_UNIT, /* Called before processing a translation unit. */
139 PLUGIN_PRAGMAS, /* Called during pragma registration. */
140 PLUGIN_EVENT_LAST /* Dummy event used for indexing callback
146 To register a callback, the plugin calls @code{register_callback} with
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.
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
158 null, and the @code{user_data} is specific.
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}.
165 @section Interacting with the pass manager
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.
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}
174 event and a pointer to a @code{struct register_pass_info} object defined as follows
177 enum pass_positioning_ops
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.
184 struct register_pass_info
186 struct opt_pass *pass; /* New pass provided by the plugin. */
187 const char *reference_pass_name; /* Name of the reference pass for hooking
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. */
196 /* Sample plugin code that registers a new pass. */
198 plugin_init (struct plugin_name_args *plugin_info,
199 struct plugin_gcc_version *version)
201 struct register_pass_info pass_info;
205 /* Code to fill in the pass_info object with new pass information. */
209 /* Register the new pass. */
210 register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
217 @section Interacting with the GCC Garbage Collector
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.
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
229 (and conversely, these routines should usually not be used in plugins
230 outside of the @code{PLUGIN_GGC_MARKING} event).
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.
242 You should understand the details of memory management inside GCC
243 before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
244 or @code{PLUGIN_REGISTER_GGC_CACHES}.
247 @section Giving information about a plugin
249 A plugin should give some information to the user about itself. This
250 uses the following structure:
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.
264 @section Registering custom attributes
266 For analysis purposes it is useful to be able to add custom attributes.
268 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
269 registration. Use the @code{register_attribute} function to register
273 /* Attribute handler callback */
275 handle_user_attribute (tree *node, tree name, tree args,
276 int flags, bool *no_add_attrs)
281 /* Attribute definition */
282 static struct attribute_spec user_attr =
283 @{ "user", 1, 1, false, false, false, handle_user_attribute @};
285 /* Plugin callback called during attribute registration.
286 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
289 register_attributes (void *event_data, void *data)
291 warning (0, G_("Callback to register attributes"));
292 register_attribute (&user_attr);
298 @section Building GCC plugins
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.
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).
309 The following GNU Makefile excerpt shows how to build a simple plugin:
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
318 plugin.so: $(PLUGIN_OBJECT_FILES)
319 $(GCC) -shared $^ -o $@@
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}
327 Plugins needing to use @command{gengtype} require a GCC build
328 directory for the same version of GCC that they will be linked