Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/plugins.texi @ 55:77e2b8dfacca gcc-4.4.5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update it from 4.4.3 to 4.5.0
author ryoma <e075725@ie.u-ryukyu.ac.jp>
date Fri, 12 Feb 2010 23:39:51 +0900
parents
children b7f97abdc517
comparison
equal deleted inserted replaced
52:c156f1bd5cd9 55:77e2b8dfacca
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 The version of GCC used to compile the plugin can be found in the symbol
109 @code{gcc_version} defined in the header @file{plugin-version.h}. The
110 recommended version check to perform looks like
111
112 @smallexample
113 #include "plugin-version.h"
114 ...
115
116 int
117 plugin_init (struct plugin_name_args *plugin_info,
118 struct plugin_gcc_version *version)
119 @{
120 if (!plugin_default_version_check (version, &gcc_version))
121 return 1;
122
123 @}
124 @end smallexample
125
126 but you can also check the individual fields if you want a less strict check.
127
128 @subsection Plugin callbacks
129
130 Callback functions have the following prototype:
131
132 @smallexample
133 /* The prototype for a plugin callback function.
134 gcc_data - event-specific data provided by GCC
135 user_data - plugin-specific data provided by the plug-in. */
136 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
137 @end smallexample
138
139 Callbacks can be invoked at the following pre-determined events:
140
141
142 @smallexample
143 enum plugin_event
144 @{
145 PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
146 PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
147 PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
148 PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
149 PLUGIN_FINISH, /* Called before GCC exits. */
150 PLUGIN_INFO, /* Information about the plugin. */
151 PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
152 PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
153 PLUGIN_GGC_END, /* Called at end of GGC. */
154 PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
155 PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
156 PLUGIN_ATTRIBUTES, /* Called during attribute registration */
157 PLUGIN_START_UNIT, /* Called before processing a translation unit. */
158 PLUGIN_PRAGMAS, /* Called during pragma registration. */
159 /* Called before first pass from all_passes. */
160 PLUGIN_ALL_PASSES_START,
161 /* Called after last pass from all_passes. */
162 PLUGIN_ALL_PASSES_END,
163 /* Called before first ipa pass. */
164 PLUGIN_ALL_IPA_PASSES_START,
165 /* Called after last ipa pass. */
166 PLUGIN_ALL_IPA_PASSES_END,
167 /* Allows to override pass gate decision for current_pass. */
168 PLUGIN_OVERRIDE_GATE,
169 /* Called before executing a pass. */
170 PLUGIN_PASS_EXECUTION,
171 /* Called before executing subpasses of a GIMPLE_PASS in
172 execute_ipa_pass_list. */
173 PLUGIN_EARLY_GIMPLE_PASSES_START,
174 /* Called after executing subpasses of a GIMPLE_PASS in
175 execute_ipa_pass_list. */
176 PLUGIN_EARLY_GIMPLE_PASSES_END,
177 /* Called when a pass is first instantiated. */
178 PLUGIN_NEW_PASS,
179
180 PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
181 array. */
182 @};
183 @end smallexample
184
185 In addition, plugins can also look up the enumerator of a named event,
186 and / or generate new events dynamically, by calling the function
187 @code{get_named_event_id}.
188
189 To register a callback, the plugin calls @code{register_callback} with
190 the arguments:
191
192 @itemize
193 @item @code{char *name}: Plugin name.
194 @item @code{int event}: The event code.
195 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
196 @item @code{void *user_data}: Pointer to plugin-specific data.
197 @end itemize
198
199 For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
200 and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
201 null, and the @code{user_data} is specific.
202
203 When the PLUGIN_PRAGMAS event is triggered (with a null
204 pointer as data from GCC), plugins may register their own pragmas
205 using functions like @code{c_register_pragma} or
206 @code{c_register_pragma_with_expansion}.
207
208 @section Interacting with the pass manager
209
210 There needs to be a way to add/reorder/remove passes dynamically. This
211 is useful for both analysis plugins (plugging in after a certain pass
212 such as CFG or an IPA pass) and optimization plugins.
213
214 Basic support for inserting new passes or replacing existing passes is
215 provided. A plugin registers a new pass with GCC by calling
216 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
217 event and a pointer to a @code{struct register_pass_info} object defined as follows
218
219 @smallexample
220 enum pass_positioning_ops
221 @{
222 PASS_POS_INSERT_AFTER, // Insert after the reference pass.
223 PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
224 PASS_POS_REPLACE // Replace the reference pass.
225 @};
226
227 struct register_pass_info
228 @{
229 struct opt_pass *pass; /* New pass provided by the plugin. */
230 const char *reference_pass_name; /* Name of the reference pass for hooking
231 up the new pass. */
232 int ref_pass_instance_number; /* Insert the pass at the specified
233 instance number of the reference pass. */
234 /* Do it for every instance if it is 0. */
235 enum pass_positioning_ops pos_op; /* how to insert the new pass. */
236 @};
237
238
239 /* Sample plugin code that registers a new pass. */
240 int
241 plugin_init (struct plugin_name_args *plugin_info,
242 struct plugin_gcc_version *version)
243 @{
244 struct register_pass_info pass_info;
245
246 ...
247
248 /* Code to fill in the pass_info object with new pass information. */
249
250 ...
251
252 /* Register the new pass. */
253 register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
254
255 ...
256 @}
257 @end smallexample
258
259
260 @section Interacting with the GCC Garbage Collector
261
262 Some plugins may want to be informed when GGC (the GCC Garbage
263 Collector) is running. They can register callbacks for the
264 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
265 the callback is called with a null @code{gcc_data}) to be notified of
266 the start or end of the GCC garbage collection.
267
268 Some plugins may need to have GGC mark additional data. This can be
269 done by registering a callback (called with a null @code{gcc_data})
270 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
271 @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
272 (and conversely, these routines should usually not be used in plugins
273 outside of the @code{PLUGIN_GGC_MARKING} event).
274
275 Some plugins may need to add extra GGC root tables, e.g. to handle their own
276 @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
277 pseudo-event with a null callback and the extra root table (of type @code{struct
278 ggc_root_tab*}) as @code{user_data}. Plugins that want to use the
279 @code{if_marked} hash table option can add the extra GGC cache tables generated
280 by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with
281 a null callback and the extra cache table (of type @code{struct ggc_cache_tab*})
282 as @code{user_data}. Running the @code{gengtype -p @var{source-dir}
283 @var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
284
285 You should understand the details of memory management inside GCC
286 before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
287 or @code{PLUGIN_REGISTER_GGC_CACHES}.
288
289
290 @section Giving information about a plugin
291
292 A plugin should give some information to the user about itself. This
293 uses the following structure:
294
295 @smallexample
296 struct plugin_info
297 @{
298 const char *version;
299 const char *help;
300 @};
301 @end smallexample
302
303 Such a structure is passed as the @code{user_data} by the plugin's
304 init routine using @code{register_callback} with the
305 @code{PLUGIN_INFO} pseudo-event and a null callback.
306
307 @section Registering custom attributes or pragmas
308
309 For analysis (or other) purposes it is useful to be able to add custom
310 attributes or pragmas.
311
312 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
313 registration. Use the @code{register_attribute} function to register
314 custom attributes.
315
316 @smallexample
317 /* Attribute handler callback */
318 static tree
319 handle_user_attribute (tree *node, tree name, tree args,
320 int flags, bool *no_add_attrs)
321 @{
322 return NULL_TREE;
323 @}
324
325 /* Attribute definition */
326 static struct attribute_spec user_attr =
327 @{ "user", 1, 1, false, false, false, handle_user_attribute @};
328
329 /* Plugin callback called during attribute registration.
330 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
331 */
332 static void
333 register_attributes (void *event_data, void *data)
334 @{
335 warning (0, G_("Callback to register attributes"));
336 register_attribute (&user_attr);
337 @}
338
339 @end smallexample
340
341
342 The @code{PLUGIN_PRAGMAS} callback is called during pragmas
343 registration. Use the @code{c_register_pragma} or
344 @code{c_register_pragma_with_expansion} functions to register custom
345 pragmas.
346
347 @smallexample
348 /* Plugin callback called during pragmas registration. Registered with
349 register_callback (plugin_name, PLUGIN_PRAGMAS,
350 register_my_pragma, NULL);
351 */
352 static void
353 register_my_pragma (void *event_data, void *data)
354 @{
355 warning (0, G_("Callback to register pragmas"));
356 c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
357 @}
358 @end smallexample
359
360 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
361 your plugin) as the ``space'' argument of your pragma.
362
363
364 @section Recording information about pass execution
365
366 The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
367 (the same as current_pass) as @code{gcc_data} to the callback. You can also
368 inspect cfun to find out about which function this pass is executed for.
369 Note that this event will only be invoked if the gate check (if
370 applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
371 You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
372 @code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
373 @code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
374 and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
375 in your plugin(s) in order to get context for the pass execution.
376
377
378 @section Controlling which passes are being run
379
380 After the original gate function for a pass is called, its result
381 - the gate status - is stored as an integer.
382 Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
383 to the gate status in the @code{gcc_data} parameter to the callback function.
384 A nonzero value of the gate status means that the pass is to be executed.
385 You can both read and write the gate status via the passed pointer.
386
387
388 @section Keeping track of available passes
389
390 When your plugin is loaded, you can inspect the various
391 pass lists to determine what passes are available. However, other
392 plugins might add new passes. Also, future changes to GCC might cause
393 generic passes to be added after plugin loading.
394 When a pass is first added to one of the pass lists, the event
395 @code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
396 @code{gcc_data} pointing to the new pass.
397
398
399 @section Building GCC plugins
400
401 If plugins are enabled, GCC installs the headers needed to build a
402 plugin (somewhere in the installation tree, e.g. under
403 @file{/usr/local}). In particular a @file{plugin/include} directory
404 is installed, containing all the header files needed to build plugins.
405
406 On most systems, you can query this @code{plugin} directory by
407 invoking @command{gcc -print-file-name=plugin} (replace if needed
408 @command{gcc} with the appropriate program path).
409
410 The following GNU Makefile excerpt shows how to build a simple plugin:
411
412 @smallexample
413 GCC=gcc
414 PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
415 PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
416 GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
417 CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
418
419 plugin.so: $(PLUGIN_OBJECT_FILES)
420 $(GCC) -shared $^ -o $@@
421 @end smallexample
422
423 A single source file plugin may be built with @code{gcc -I`gcc
424 -print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
425 plugin.so}, using backquote shell syntax to query the @file{plugin}
426 directory.
427
428 Plugins needing to use @command{gengtype} require a GCC build
429 directory for the same version of GCC that they will be linked
430 against.