1@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 12Plugins are supported on platforms that support @option{-ldl 13-rdynamic}. They are loaded by the compiler using @code{dlopen} 14and invoked at pre-determined locations in the compilation 15process. 16 17Plugins are loaded with 18 19@option{-fplugin=/path/to/@var{name}.so} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]} 20 21The plugin arguments are parsed by GCC and passed to respective 22plugins as key-value pairs. Multiple plugins can be invoked by 23specifying multiple @option{-fplugin} arguments. 24 25A plugin can be simply given by its short name (no dots or 26slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is 27loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is 28the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.so}, 29using backquote shell syntax to query the @file{plugin} directory. 30 31@section Plugin API 32 33Plugins are activated by the compiler at specific events as defined in 34@file{gcc-plugin.h}. For each event of interest, the plugin should 35call @code{register_callback} specifying the name of the event and 36address of the callback function that will handle that event. 37 38The header @file{gcc-plugin.h} must be the first gcc header to be included. 39 40@subsection Plugin license check 41 42Every plugin should define the global symbol @code{plugin_is_GPL_compatible} 43to assert that it has been licensed under a GPL-compatible license. 44If this symbol does not exist, the compiler will emit a fatal error 45and exit with the error message: 46 47@smallexample 48fatal error: plugin @var{name} is not licensed under a GPL-compatible license 49@var{name}: undefined symbol: plugin_is_GPL_compatible 50compilation terminated 51@end smallexample 52 53The declared type of the symbol should be int, to match a forward declaration 54in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in 55any allocated section, though. The compiler merely asserts that 56the symbol exists in the global scope. Something like this is enough: 57 58@smallexample 59int plugin_is_GPL_compatible; 60@end smallexample 61 62@subsection Plugin initialization 63 64Every plugin should export a function called @code{plugin_init} that 65is called right after the plugin is loaded. This function is 66responsible for registering all the callbacks required by the plugin 67and do any other required initialization. 68 69This function is called from @code{compile_file} right before invoking 70the 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 77The @code{plugin_info} struct is defined as follows: 78 79@smallexample 80struct 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 94If initialization fails, @code{plugin_init} must return a non-zero 95value. Otherwise, it should return 0. 96 97The version of the GCC compiler loading the plugin is described by the 98following structure: 99 100@smallexample 101struct 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 111The function @code{plugin_default_version_check} takes two pointers to 112such structure and compare them field by field. It can be used by the 113plugin's @code{plugin_init} function. 114 115The 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 117recommended version check to perform looks like 118 119@smallexample 120#include "plugin-version.h" 121... 122 123int 124plugin_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 133but you can also check the individual fields if you want a less strict check. 134 135@subsection Plugin callbacks 136 137Callback 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. */ 143typedef void (*plugin_callback_func)(void *gcc_data, void *user_data); 144@end smallexample 145 146Callbacks can be invoked at the following pre-determined events: 147 148 149@smallexample 150enum 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 193In addition, plugins can also look up the enumerator of a named event, 194and / or generate new events dynamically, by calling the function 195@code{get_named_event_id}. 196 197To register a callback, the plugin calls @code{register_callback} with 198the 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 207For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS 208and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be 209null, and the @code{user_data} is specific. 210 211When the PLUGIN_PRAGMAS event is triggered (with a null 212pointer as data from GCC), plugins may register their own pragmas 213using functions like @code{c_register_pragma} or 214@code{c_register_pragma_with_expansion}. 215 216@section Interacting with the pass manager 217 218There needs to be a way to add/reorder/remove passes dynamically. This 219is useful for both analysis plugins (plugging in after a certain pass 220such as CFG or an IPA pass) and optimization plugins. 221 222Basic support for inserting new passes or replacing existing passes is 223provided. A plugin registers a new pass with GCC by calling 224@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP} 225event and a pointer to a @code{struct register_pass_info} object defined as follows 226 227@smallexample 228enum 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 235struct 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. */ 248int 249plugin_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 270Some plugins may want to be informed when GGC (the GCC Garbage 271Collector) is running. They can register callbacks for the 272@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which 273the callback is called with a null @code{gcc_data}) to be notified of 274the start or end of the GCC garbage collection. 275 276Some plugins may need to have GGC mark additional data. This can be 277done by registering a callback (called with a null @code{gcc_data}) 278for 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 281outside of the @code{PLUGIN_GGC_MARKING} event). 282 283Some 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} 285pseudo-event with a null callback and the extra root table (of type @code{struct 286ggc_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 288by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with 289a null callback and the extra cache table (of type @code{struct ggc_cache_tab*}) 290as @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 293You should understand the details of memory management inside GCC 294before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS} 295or @code{PLUGIN_REGISTER_GGC_CACHES}. 296 297 298@section Giving information about a plugin 299 300A plugin should give some information to the user about itself. This 301uses the following structure: 302 303@smallexample 304struct plugin_info 305@{ 306 const char *version; 307 const char *help; 308@}; 309@end smallexample 310 311Such a structure is passed as the @code{user_data} by the plugin's 312init 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 317For analysis (or other) purposes it is useful to be able to add custom 318attributes or pragmas. 319 320The @code{PLUGIN_ATTRIBUTES} callback is called during attribute 321registration. Use the @code{register_attribute} function to register 322custom attributes. 323 324@smallexample 325/* Attribute handler callback */ 326static tree 327handle_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 */ 334static struct attribute_spec user_attr = 335 @{ "user", 1, 1, false, false, false, handle_user_attribute, false @}; 336 337/* Plugin callback called during attribute registration. 338Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL) 339*/ 340static void 341register_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 350The @code{PLUGIN_PRAGMAS} callback is called during pragmas 351registration. Use the @code{c_register_pragma} or 352@code{c_register_pragma_with_expansion} functions to register custom 353pragmas. 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*/ 360static void 361register_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 368It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying 369your plugin) as the ``space'' argument of your pragma. 370 371 372@section Recording information about pass execution 373 374The 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 376inspect cfun to find out about which function this pass is executed for. 377Note that this event will only be invoked if the gate check (if 378applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds. 379You 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}, 382and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state 383in your plugin(s) in order to get context for the pass execution. 384 385 386@section Controlling which passes are being run 387 388After the original gate function for a pass is called, its result 389- the gate status - is stored as an integer. 390Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer 391to the gate status in the @code{gcc_data} parameter to the callback function. 392A nonzero value of the gate status means that the pass is to be executed. 393You can both read and write the gate status via the passed pointer. 394 395 396@section Keeping track of available passes 397 398When your plugin is loaded, you can inspect the various 399pass lists to determine what passes are available. However, other 400plugins might add new passes. Also, future changes to GCC might cause 401generic passes to be added after plugin loading. 402When 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 409If plugins are enabled, GCC installs the headers needed to build a 410plugin (somewhere in the installation tree, e.g. under 411@file{/usr/local}). In particular a @file{plugin/include} directory 412is installed, containing all the header files needed to build plugins. 413 414On most systems, you can query this @code{plugin} directory by 415invoking @command{gcc -print-file-name=plugin} (replace if needed 416@command{gcc} with the appropriate program path). 417 418Inside plugins, this @code{plugin} directory name can be queried by 419calling @code{default_plugin_dir_name ()}. 420 421Plugins 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 425integer 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 432The following GNU Makefile excerpt shows how to build a simple plugin: 433 434@smallexample 435GCC=gcc 436PLUGIN_SOURCE_FILES= plugin1.c plugin2.c 437PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES)) 438GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin) 439CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2 440 441plugin.so: $(PLUGIN_OBJECT_FILES) 442 $(GCC) -shared $^ -o $@@ 443@end smallexample 444 445A single source file plugin may be built with @code{gcc -I`gcc 446-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o 447plugin.so}, using backquote shell syntax to query the @file{plugin} 448directory. 449 450When a plugin needs to use @command{gengtype}, be sure that both 451@file{gengtype} and @file{gtype.state} have the same version as the 452GCC for which the plugin is built. 453