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
|
@c Copyright (c) 2009 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
@section Loading Plugins
Plugins are supported on platforms that support @option{-ld
-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/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<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.
@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.
@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_name}: Name of the plugin.
@item @code{argc}: Number of arguments specified with @option{-fplugin-arg-...}.
@item @code{argv}: Array of @code{argc} key-value pairs.
@end itemize
If initialization fails, @code{plugin_init} must return a non-zero
value. Otherwise, it should return 0.
@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_UNIT, /* Useful for summary processing. */
PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE. */
PLUGIN_FINISH, /* Called before GCC exits. */
PLUGIN_ATTRIBUTES, /* Called during attribute registration */
PLUGIN_EVENT_LAST /* Dummy event used for indexing callback
array. */
@};
@end smallexample
To register a callback, the plugin calls @code{register_callback} with the arguments:
@itemize
@item @code{char *name}: Plugin name.
@item @code{enum plugin_event 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
@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 plugin_pass} 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 plugin_pass
@{
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 (const char *plugin_name, int argc, struct plugin_argument *argv)
@{
struct plugin_pass pass_info;
...
/* Code to fill in the pass_info object with new pass information. */
...
/* Register the new pass. */
register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
...
@}
@end smallexample
@section Registering custom attributes
For analysis purposes it is useful to be able to add custom attributes.
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 @};
/* 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
|
