OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-dev/] [or1k-gcc/] [gcc/] [doc/] [plugins.texi] - Blame information for rev 801

Go to most recent revision | Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.