1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
|
@c Copyright (c) 2009, 2010 Free Software Foundation, Inc.
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
@node Plugins
@chapter Plugins
@cindex Plugins
GCC plugin is a loadable module that provides extra
features to the compiler, which they can further pass
around as a shareable module.
GCC plugins provide developers with a rich subset of
the GCC API to allow them to extend GCC as they see fit.
Whether it is writing an additional optimization pass,
transforming code, or analyzing information, plugins
can be quite useful.
@menu
* Plugins loading:: How can we load plugins.
* Plugin API:: The APIs for plugins.
* Plugins pass:: How a plugin interact with the pass manager.
* Plugins GC:: How a plugin Interact with GCC Garbage Collector.
* Plugins description:: Giving information about a plugin itself.
* Plugins attr:: Registering custom attributes or pragmas.
* Plugins recording:: Recording information about pass execution.
* Plugins gate:: Controlling which passes are being run.
* Plugins tracking:: Keeping track of available passes.
* Plugins building:: How can we build a plugin.
@end menu
@node Plugins loading
@section Loading Plugins
Plugins are supported on platforms that support @option{-ldl
-rdynamic}. They are loaded by the compiler using @code{dlopen}
and invoked at pre-determined locations in the compilation
process.
Plugins are loaded with
@option{-fplugin=/path/to/@var{name}.so} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]}
The plugin arguments are parsed by GCC and passed to respective
plugins as key-value pairs. Multiple plugins can be invoked by
specifying multiple @option{-fplugin} arguments.
A plugin can be simply given by its short name (no dots or
slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is
loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is
the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.so},
using backquote shell syntax to query the @file{plugin} directory.
@node Plugin API
@section Plugin API
Plugins are activated by the compiler at specific events as defined in
@file{gcc-plugin.h}. For each event of interest, the plugin should
call @code{register_callback} specifying the name of the event and
address of the callback function that will handle that event.
The header @file{gcc-plugin.h} must be the first gcc header to be included.
@subsection Plugin license check
Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
to assert that it has been licensed under a GPL-compatible license.
If this symbol does not exist, the compiler will emit a fatal error
and exit with the error message:
@smallexample
fatal error: plugin @var{name} is not licensed under a GPL-compatible license
@var{name}: undefined symbol: plugin_is_GPL_compatible
compilation terminated
@end smallexample
The declared type of the symbol should be int, to match a forward declaration
in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in
any allocated section, though. The compiler merely asserts that
the symbol exists in the global scope. Something like this is enough:
@smallexample
int plugin_is_GPL_compatible;
@end smallexample
@subsection Plugin initialization
Every plugin should export a function called @code{plugin_init} that
is called right after the plugin is loaded. This function is
responsible for registering all the callbacks required by the plugin
and do any other required initialization.
This function is called from @code{compile_file} right before invoking
the parser. The arguments to @code{plugin_init} are:
@itemize @bullet
@item @code{plugin_info}: Plugin invocation information.
@item @code{version}: GCC version.
@end itemize
The @code{plugin_info} struct is defined as follows:
@smallexample
struct plugin_name_args
@{
char *base_name; /* Short name of the plugin
(filename without .so suffix). */
const char *full_name; /* Path to the plugin as specified with
-fplugin=. */
int argc; /* Number of arguments specified with
-fplugin-arg-.... */
struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
const char *version; /* Version string provided by plugin. */
const char *help; /* Help string provided by plugin. */
@}
@end smallexample
If initialization fails, @code{plugin_init} must return a non-zero
value. Otherwise, it should return 0.
The version of the GCC compiler loading the plugin is described by the
following structure:
@smallexample
struct plugin_gcc_version
@{
const char *basever;
const char *datestamp;
const char *devphase;
const char *revision;
const char *configuration_arguments;
@};
@end smallexample
The function @code{plugin_default_version_check} takes two pointers to
such structure and compare them field by field. It can be used by the
plugin's @code{plugin_init} function.
The version of GCC used to compile the plugin can be found in the symbol
@code{gcc_version} defined in the header @file{plugin-version.h}. The
recommended version check to perform looks like
@smallexample
#include "plugin-version.h"
...
int
plugin_init (struct plugin_name_args *plugin_info,
struct plugin_gcc_version *version)
@{
if (!plugin_default_version_check (version, &gcc_version))
return 1;
@}
@end smallexample
but you can also check the individual fields if you want a less strict check.
@subsection Plugin callbacks
Callback functions have the following prototype:
@smallexample
/* The prototype for a plugin callback function.
gcc_data - event-specific data provided by GCC
user_data - plugin-specific data provided by the plug-in. */
typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
@end smallexample
Callbacks can be invoked at the following pre-determined events:
@smallexample
enum plugin_event
@{
PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */
PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
PLUGIN_FINISH, /* Called before GCC exits. */
PLUGIN_INFO, /* Information about the plugin. */
PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
PLUGIN_GGC_END, /* Called at end of GGC. */
PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
PLUGIN_ATTRIBUTES, /* Called during attribute registration */
PLUGIN_START_UNIT, /* Called before processing a translation unit. */
PLUGIN_PRAGMAS, /* Called during pragma registration. */
/* Called before first pass from all_passes. */
PLUGIN_ALL_PASSES_START,
/* Called after last pass from all_passes. */
PLUGIN_ALL_PASSES_END,
/* Called before first ipa pass. */
PLUGIN_ALL_IPA_PASSES_START,
/* Called after last ipa pass. */
PLUGIN_ALL_IPA_PASSES_END,
/* Allows to override pass gate decision for current_pass. */
PLUGIN_OVERRIDE_GATE,
/* Called before executing a pass. */
PLUGIN_PASS_EXECUTION,
/* Called before executing subpasses of a GIMPLE_PASS in
execute_ipa_pass_list. */
PLUGIN_EARLY_GIMPLE_PASSES_START,
/* Called after executing subpasses of a GIMPLE_PASS in
execute_ipa_pass_list. */
PLUGIN_EARLY_GIMPLE_PASSES_END,
/* Called when a pass is first instantiated. */
PLUGIN_NEW_PASS,
PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
array. */
@};
@end smallexample
In addition, plugins can also look up the enumerator of a named event,
and / or generate new events dynamically, by calling the function
@code{get_named_event_id}.
To register a callback, the plugin calls @code{register_callback} with
the arguments:
@itemize
@item @code{char *name}: Plugin name.
@item @code{int event}: The event code.
@item @code{plugin_callback_func callback}: The function that handles @code{event}.
@item @code{void *user_data}: Pointer to plugin-specific data.
@end itemize
For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
null, and the @code{user_data} is specific.
When the PLUGIN_PRAGMAS event is triggered (with a null
pointer as data from GCC), plugins may register their own pragmas
using functions like @code{c_register_pragma} or
@code{c_register_pragma_with_expansion}.
@node Plugins pass
@section Interacting with the pass manager
There needs to be a way to add/reorder/remove passes dynamically. This
is useful for both analysis plugins (plugging in after a certain pass
such as CFG or an IPA pass) and optimization plugins.
Basic support for inserting new passes or replacing existing passes is
provided. A plugin registers a new pass with GCC by calling
@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
event and a pointer to a @code{struct register_pass_info} object defined as follows
@smallexample
enum pass_positioning_ops
@{
PASS_POS_INSERT_AFTER, // Insert after the reference pass.
PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
PASS_POS_REPLACE // Replace the reference pass.
@};
struct register_pass_info
@{
struct opt_pass *pass; /* New pass provided by the plugin. */
const char *reference_pass_name; /* Name of the reference pass for hooking
up the new pass. */
int ref_pass_instance_number; /* Insert the pass at the specified
instance number of the reference pass. */
/* Do it for every instance if it is 0. */
enum pass_positioning_ops pos_op; /* how to insert the new pass. */
@};
/* Sample plugin code that registers a new pass. */
int
plugin_init (struct plugin_name_args *plugin_info,
struct plugin_gcc_version *version)
@{
struct register_pass_info pass_info;
...
/* Code to fill in the pass_info object with new pass information. */
...
/* Register the new pass. */
register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
...
@}
@end smallexample
@node Plugins GC
@section Interacting with the GCC Garbage Collector
Some plugins may want to be informed when GGC (the GCC Garbage
Collector) is running. They can register callbacks for the
@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
the callback is called with a null @code{gcc_data}) to be notified of
the start or end of the GCC garbage collection.
Some plugins may need to have GGC mark additional data. This can be
done by registering a callback (called with a null @code{gcc_data})
for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
@code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro
(and conversely, these routines should usually not be used in plugins
outside of the @code{PLUGIN_GGC_MARKING} event).
Some plugins may need to add extra GGC root tables, e.g. to handle their own
@code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
pseudo-event with a null callback and the extra root table (of type @code{struct
ggc_root_tab*}) as @code{user_data}. Plugins that want to use the
@code{if_marked} hash table option can add the extra GGC cache tables generated
by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with
a null callback and the extra cache table (of type @code{struct ggc_cache_tab*})
as @code{user_data}. Running the @code{gengtype -p @var{source-dir}
@var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
You should understand the details of memory management inside GCC
before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
or @code{PLUGIN_REGISTER_GGC_CACHES}.
@node Plugins description
@section Giving information about a plugin
A plugin should give some information to the user about itself. This
uses the following structure:
@smallexample
struct plugin_info
@{
const char *version;
const char *help;
@};
@end smallexample
Such a structure is passed as the @code{user_data} by the plugin's
init routine using @code{register_callback} with the
@code{PLUGIN_INFO} pseudo-event and a null callback.
@node Plugins attr
@section Registering custom attributes or pragmas
For analysis (or other) purposes it is useful to be able to add custom
attributes or pragmas.
The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
registration. Use the @code{register_attribute} function to register
custom attributes.
@smallexample
/* Attribute handler callback */
static tree
handle_user_attribute (tree *node, tree name, tree args,
int flags, bool *no_add_attrs)
@{
return NULL_TREE;
@}
/* Attribute definition */
static struct attribute_spec user_attr =
@{ "user", 1, 1, false, false, false, handle_user_attribute, false @};
/* Plugin callback called during attribute registration.
Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
*/
static void
register_attributes (void *event_data, void *data)
@{
warning (0, G_("Callback to register attributes"));
register_attribute (&user_attr);
@}
@end smallexample
The @code{PLUGIN_PRAGMAS} callback is called during pragmas
registration. Use the @code{c_register_pragma} or
@code{c_register_pragma_with_expansion} functions to register custom
pragmas.
@smallexample
/* Plugin callback called during pragmas registration. Registered with
register_callback (plugin_name, PLUGIN_PRAGMAS,
register_my_pragma, NULL);
*/
static void
register_my_pragma (void *event_data, void *data)
@{
warning (0, G_("Callback to register pragmas"));
c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
@}
@end smallexample
It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
your plugin) as the ``space'' argument of your pragma.
@node Plugins recording
@section Recording information about pass execution
The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
(the same as current_pass) as @code{gcc_data} to the callback. You can also
inspect cfun to find out about which function this pass is executed for.
Note that this event will only be invoked if the gate check (if
applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
@code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
@code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
in your plugin(s) in order to get context for the pass execution.
@node Plugins gate
@section Controlling which passes are being run
After the original gate function for a pass is called, its result
- the gate status - is stored as an integer.
Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
to the gate status in the @code{gcc_data} parameter to the callback function.
A nonzero value of the gate status means that the pass is to be executed.
You can both read and write the gate status via the passed pointer.
@node Plugins tracking
@section Keeping track of available passes
When your plugin is loaded, you can inspect the various
pass lists to determine what passes are available. However, other
plugins might add new passes. Also, future changes to GCC might cause
generic passes to be added after plugin loading.
When a pass is first added to one of the pass lists, the event
@code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
@code{gcc_data} pointing to the new pass.
@node Plugins building
@section Building GCC plugins
If plugins are enabled, GCC installs the headers needed to build a
plugin (somewhere in the installation tree, e.g. under
@file{/usr/local}). In particular a @file{plugin/include} directory
is installed, containing all the header files needed to build plugins.
On most systems, you can query this @code{plugin} directory by
invoking @command{gcc -print-file-name=plugin} (replace if needed
@command{gcc} with the appropriate program path).
Inside plugins, this @code{plugin} directory name can be queried by
calling @code{default_plugin_dir_name ()}.
Plugins may know, when they are compiled, the GCC version for which
@file{plugin-version.h} is provided. The constant macros
@code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR},
@code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are
integer numbers, so a plugin could ensure it is built for GCC 4.7 with
@smallexample
#if GCCPLUGIN_VERSION != 4007
#error this GCC plugin is for GCC 4.7
#endif
@end smallexample
The following GNU Makefile excerpt shows how to build a simple plugin:
@smallexample
GCC=gcc
PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
plugin.so: $(PLUGIN_OBJECT_FILES)
$(GCC) -shared $^ -o $@@
@end smallexample
A single source file plugin may be built with @code{gcc -I`gcc
-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
plugin.so}, using backquote shell syntax to query the @file{plugin}
directory.
When a plugin needs to use @command{gengtype}, be sure that both
@file{gengtype} and @file{gtype.state} have the same version as the
GCC for which the plugin is built.
|