OSDN Git Service

bb32bccbf185d8b74365365cc4d1286a66c82ff2
[pf3gnuchains/gcc-fork.git] / gcc / doc / plugins.texi
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
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
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
33 The header @file{gcc-plugin.h} must be the first gcc header to be included.
34
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
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
66 @item @code{plugin_info}: Plugin invocation information.
67 @item @code{version}: GCC version.
68 @end itemize
69
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
87 If initialization fails, @code{plugin_init} must return a non-zero
88 value.  Otherwise, it should return 0.
89
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
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.  */
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_EVENT_LAST             /* Dummy event used for indexing callback
140                                    array.  */
141 @};
142 @end smallexample
143
144
145 To register a callback, the plugin calls @code{register_callback} with
146 the arguments:
147
148 @itemize
149 @item @code{char *name}: Plugin name.
150 @item @code{enum plugin_event event}: The event code.
151 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
152 @item @code{void *user_data}: Pointer to plugin-specific data.
153 @end itemize
154
155 For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
156 and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
157 null, and the @code{user_data} is specific.
158
159 @section Interacting with the pass manager
160
161 There needs to be a way to add/reorder/remove passes dynamically. This
162 is useful for both analysis plugins (plugging in after a certain pass
163 such as CFG or an IPA pass) and optimization plugins.
164
165 Basic support for inserting new passes or replacing existing passes is
166 provided. A plugin registers a new pass with GCC by calling
167 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
168 event and a pointer to a @code{struct plugin_pass} object defined as follows
169
170 @smallexample
171 enum pass_positioning_ops
172 @{
173   PASS_POS_INSERT_AFTER,  // Insert after the reference pass.
174   PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
175   PASS_POS_REPLACE        // Replace the reference pass.
176 @};
177
178 struct plugin_pass
179 @{
180   struct opt_pass *pass;            /* New pass provided by the plugin.  */
181   const char *reference_pass_name;  /* Name of the reference pass for hooking
182                                        up the new pass.  */
183   int ref_pass_instance_number;     /* Insert the pass at the specified
184                                        instance number of the reference pass.  */
185                                     /* Do it for every instance if it is 0.  */
186   enum pass_positioning_ops pos_op; /* how to insert the new pass.  */
187 @};
188
189
190 /* Sample plugin code that registers a new pass.  */
191 int
192 plugin_init (struct plugin_name_args *plugin_info,
193              struct plugin_gcc_version *version)
194 @{
195   struct plugin_pass pass_info;
196
197   ...
198
199   /* Code to fill in the pass_info object with new pass information.  */
200
201   ...
202
203   /* Register the new pass.  */
204   register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
205
206   ...
207 @}
208 @end smallexample
209
210
211 @section Interacting with the GCC Garbage Collector 
212
213 Some plugins may want to be informed when GGC (the GCC Garbage
214 Collector) is running. They can register callbacks for the
215 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
216 the callback is called with a null @code{gcc_data}) to be notified of
217 the start or end of the GCC garbage collection.
218
219 Some plugins may need to have GGC mark additional data. This can be
220 done by registering a callback (called with a null @code{gcc_data})
221 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
222 @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
223 (and conversely, these routines should usually not be used in plugins
224 outside of the @code{PLUGIN_GGC_MARKING} event).  
225
226 Some plugins may need to add extra GGC root tables, e.g. to handle their own
227 @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
228 pseudo-event with a null callback and the extra root table (of type @code{struct
229 ggc_root_tab*}) as @code{user_data}.  Plugins that want to use the
230 @code{if_marked} hash table option can add the extra GGC cache tables generated
231 by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with
232 a null callback and the extra cache table (of type @code{struct ggc_cache_tab*})
233 as @code{user_data}.  Running the @code{gengtype -p @var{source-dir}
234 @var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
235
236 You should understand the details of memory management inside GCC
237 before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
238 or @code{PLUGIN_REGISTER_GGC_CACHES}.
239
240
241 @section Giving information about a plugin
242
243 A plugin should give some information to the user about itself. This
244 uses the following structure:
245
246 @smallexample
247 struct plugin_info
248 @{
249   const char *version;
250   const char *help;
251 @};
252 @end smallexample
253
254 Such a structure is passed as the @code{user_data} by the plugin's
255 init routine using @code{register_callback} with the
256 @code{PLUGIN_INFO} pseudo-event and a null callback.
257
258 @section Registering custom attributes
259
260 For analysis purposes it is useful to be able to add custom attributes.
261
262 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
263 registration. Use the @code{register_attribute} function to register
264 custom attributes.
265
266 @smallexample
267 /* Attribute handler callback */
268 static tree
269 handle_user_attribute (tree *node, tree name, tree args,
270                         int flags, bool *no_add_attrs)
271 @{
272   return NULL_TREE;
273 @}
274
275 /* Attribute definition */
276 static struct attribute_spec user_attr =
277   @{ "user", 1, 1, false,  false, false, handle_user_attribute @};
278
279 /* Plugin callback called during attribute registration.
280 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
281 */
282 static void 
283 register_attributes (void *event_data, void *data)
284 @{
285   warning (0, G_("Callback to register attributes"));
286   register_attribute (&user_attr);
287 @}
288
289 @end smallexample
290
291
292 @section Building GCC plugins
293
294 If plugins are enabled, GCC installs the headers needed to build a
295 plugin (somehwere in the installation tree, e.g. under
296 @file{/usr/local}).  In particular a @file{plugin/include} directory
297 is installed, containing all the header files needed to build plugins.
298
299 On most systems, you can query this @code{plugin} directory by
300 invoking @command{gcc -print-file-name=plugin} (replace if needed
301 @command{gcc} with the appropriate program path).
302
303 The following GNU Makefile excerpt shows how to build a simple plugin:
304
305 @smallexample
306 GCC=gcc
307 PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
308 PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
309 GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
310 CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
311
312 plugin.so: $(PLUGIN_OBJECT_FILES)
313    $(GCC) -shared $^ -o $@@
314 @end smallexample
315
316 A single source file plugin may be built with @code{gcc -I`gcc
317 -print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
318 plugin.so}, using backquote shell syntax to query the @file{plugin}
319 directory.
320
321 Plugins needing to use @command{gengtype} require a GCC build
322 directory for the same version of GCC that they will be linked
323 against.