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 initialization
37 Every plugin should export a function called @code{plugin_init} that
38 is called right after the plugin is loaded. This function is
39 responsible for registering all the callbacks required by the plugin
40 and do any other required initialization.
42 This function is called from @code{compile_file} right before invoking
43 the parser. The arguments to @code{plugin_init} are:
46 @item @code{plugin_info}: Plugin invocation information.
47 @item @code{version}: GCC version.
50 The @code{plugin_info} struct is defined as follows:
53 struct plugin_name_args
55 char *base_name; /* Short name of the plugin
56 (filename without .so suffix). */
57 const char *full_name; /* Path to the plugin as specified with
59 int argc; /* Number of arguments specified with
61 struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
62 const char *version; /* Version string provided by plugin. */
63 const char *help; /* Help string provided by plugin. */
67 If initialization fails, @code{plugin_init} must return a non-zero
68 value. Otherwise, it should return 0.
70 The version of the GCC compiler loading the plugin is described by the
74 struct plugin_gcc_version
77 const char *datestamp;
80 const char *configuration_arguments;
84 The function @code{plugin_default_version_check} takes two pointers to
85 such structure and compare them field by field. It can be used by the
86 plugin's @code{plugin_init} function.
89 @subsection Plugin callbacks
91 Callback functions have the following prototype:
94 /* The prototype for a plugin callback function.
95 gcc_data - event-specific data provided by GCC
96 user_data - plugin-specific data provided by the plug-in. */
97 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
100 Callbacks can be invoked at the following pre-determined events:
106 PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
107 PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
108 PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
109 PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE. */
110 PLUGIN_FINISH, /* Called before GCC exits. */
111 PLUGIN_INFO, /* Information about the plugin. */
112 PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
113 PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
114 PLUGIN_GGC_END, /* Called at end of GGC. */
115 PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
116 PLUGIN_ATTRIBUTES, /* Called during attribute registration */
117 PLUGIN_EVENT_LAST /* Dummy event used for indexing callback
123 To register a callback, the plugin calls @code{register_callback} with
127 @item @code{char *name}: Plugin name.
128 @item @code{enum plugin_event event}: The event code.
129 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
130 @item @code{void *user_data}: Pointer to plugin-specific data.
133 For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, and
134 PLUGIN_REGISTER_GGC_ROOTS pseudo-events the @code{callback} should be
135 null, and the @code{user_data} is specific.
137 @section Interacting with the pass manager
139 There needs to be a way to add/reorder/remove passes dynamically. This
140 is useful for both analysis plugins (plugging in after a certain pass
141 such as CFG or an IPA pass) and optimization plugins.
143 Basic support for inserting new passes or replacing existing passes is
144 provided. A plugin registers a new pass with GCC by calling
145 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
146 event and a pointer to a @code{struct plugin_pass} object defined as follows
149 enum pass_positioning_ops
151 PASS_POS_INSERT_AFTER, // Insert after the reference pass.
152 PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
153 PASS_POS_REPLACE // Replace the reference pass.
158 struct opt_pass *pass; /* New pass provided by the plugin. */
159 const char *reference_pass_name; /* Name of the reference pass for hooking
161 int ref_pass_instance_number; /* Insert the pass at the specified
162 instance number of the reference pass. */
163 /* Do it for every instance if it is 0. */
164 enum pass_positioning_ops pos_op; /* how to insert the new pass. */
168 /* Sample plugin code that registers a new pass. */
170 plugin_init (struct plugin_name_args *plugin_info,
171 struct plugin_gcc_version *version)
173 struct plugin_pass pass_info;
177 /* Code to fill in the pass_info object with new pass information. */
181 /* Register the new pass. */
182 register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
189 @section Interacting with the GCC Garbage Collector
191 Some plugins may want to be informed when GGC (the GCC Garbage
192 Collector) is running. They can register callbacks for the
193 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
194 the callback is called with a null @code{gcc_data}) to be notified of
195 the start or end of the GCC garbage collection.
197 Some plugins may need to have GGC mark additional data. This can be
198 done by registering a callback (called with a null @code{gcc_data})
199 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
200 @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
201 (and conversly, these routines should usually not be used in plugins
202 outside of the @code{PLUGIN_GGC_MARKING} event).
204 Some plugins may need to add extra GGC root tables, e.g. to handle
205 their own @code{GTY}-ed data. This can be done with the
206 @code{PLUGIN_REGISTER_GGC_ROOTS} pseudo-event with a null callback and the
207 extra root table as @code{user_data}.
209 You should understand the details of memory management inside GCC
210 before using @code{PLUGIN_GGC_MARKING} or
211 @code{PLUGIN_REGISTER_GGC_ROOTS}.
214 @section Giving information about a plugin
216 A plugin should give some information to the user about itself. This
217 uses the following structure:
227 Such a structure is passed as the @code{user_data} by the plugin's
228 init routine using @code{register_callback} with the
229 @code{PLUGIN_INFO} pseudo-event and a null callback.
231 @section Registering custom attributes
233 For analysis purposes it is useful to be able to add custom attributes.
235 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
236 registration. Use the @code{register_attribute} function to register
240 /* Attribute handler callback */
242 handle_user_attribute (tree *node, tree name, tree args,
243 int flags, bool *no_add_attrs)
248 /* Attribute definition */
249 static struct attribute_spec user_attr =
250 @{ "user", 1, 1, false, false, false, handle_user_attribute @};
252 /* Plugin callback called during attribute registration.
253 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
256 register_attributes (void *event_data, void *data)
258 warning (0, G_("Callback to register attributes"));
259 register_attribute (&user_attr);