1*ec02198aSmrg@c Copyright (C) 2009-2020 Free Software Foundation, Inc. 210d565efSmrg@c Free Software Foundation, Inc. 310d565efSmrg@c This is part of the GCC manual. 410d565efSmrg@c For copying conditions, see the file gcc.texi. 510d565efSmrg 610d565efSmrg@node Plugins 710d565efSmrg@chapter Plugins 810d565efSmrg@cindex Plugins 910d565efSmrg 1010d565efSmrgGCC plugins are loadable modules that provide extra features to the 1110d565efSmrgcompiler. Like GCC itself they can be distributed in source and 1210d565efSmrgbinary forms. 1310d565efSmrg 1410d565efSmrgGCC plugins provide developers with a rich subset of 1510d565efSmrgthe GCC API to allow them to extend GCC as they see fit. 1610d565efSmrgWhether it is writing an additional optimization pass, 1710d565efSmrgtransforming code, or analyzing information, plugins 1810d565efSmrgcan be quite useful. 1910d565efSmrg 2010d565efSmrg@menu 2110d565efSmrg* Plugins loading:: How can we load plugins. 2210d565efSmrg* Plugin API:: The APIs for plugins. 2310d565efSmrg* Plugins pass:: How a plugin interact with the pass manager. 2410d565efSmrg* Plugins GC:: How a plugin Interact with GCC Garbage Collector. 2510d565efSmrg* Plugins description:: Giving information about a plugin itself. 2610d565efSmrg* Plugins attr:: Registering custom attributes or pragmas. 2710d565efSmrg* Plugins recording:: Recording information about pass execution. 2810d565efSmrg* Plugins gate:: Controlling which passes are being run. 2910d565efSmrg* Plugins tracking:: Keeping track of available passes. 3010d565efSmrg* Plugins building:: How can we build a plugin. 3110d565efSmrg@end menu 3210d565efSmrg 3310d565efSmrg@node Plugins loading 3410d565efSmrg@section Loading Plugins 3510d565efSmrg 3610d565efSmrgPlugins are supported on platforms that support @option{-ldl 37c7a68eb7Smrg-rdynamic} as well as Windows/MinGW. They are loaded by the compiler 38c7a68eb7Smrgusing @code{dlopen} or equivalent and invoked at pre-determined 39c7a68eb7Smrglocations in the compilation process. 4010d565efSmrg 4110d565efSmrgPlugins are loaded with 4210d565efSmrg 43c7a68eb7Smrg@option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]} 4410d565efSmrg 45c7a68eb7SmrgWhere @var{name} is the plugin name and @var{ext} is the platform-specific 46c7a68eb7Smrgdynamic library extension. It should be @code{dll} on Windows/MinGW, 47c7a68eb7Smrg@code{dylib} on Darwin/Mac OS X, and @code{so} on all other platforms. 4810d565efSmrgThe plugin arguments are parsed by GCC and passed to respective 4910d565efSmrgplugins as key-value pairs. Multiple plugins can be invoked by 5010d565efSmrgspecifying multiple @option{-fplugin} arguments. 5110d565efSmrg 5210d565efSmrgA plugin can be simply given by its short name (no dots or 5310d565efSmrgslashes). When simply passing @option{-fplugin=@var{name}}, the plugin is 5410d565efSmrgloaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is 55c7a68eb7Smrgthe same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}}, 5610d565efSmrgusing backquote shell syntax to query the @file{plugin} directory. 5710d565efSmrg 5810d565efSmrg@node Plugin API 5910d565efSmrg@section Plugin API 6010d565efSmrg 6110d565efSmrgPlugins are activated by the compiler at specific events as defined in 6210d565efSmrg@file{gcc-plugin.h}. For each event of interest, the plugin should 6310d565efSmrgcall @code{register_callback} specifying the name of the event and 6410d565efSmrgaddress of the callback function that will handle that event. 6510d565efSmrg 6610d565efSmrgThe header @file{gcc-plugin.h} must be the first gcc header to be included. 6710d565efSmrg 6810d565efSmrg@subsection Plugin license check 6910d565efSmrg 7010d565efSmrgEvery plugin should define the global symbol @code{plugin_is_GPL_compatible} 7110d565efSmrgto assert that it has been licensed under a GPL-compatible license. 7210d565efSmrgIf this symbol does not exist, the compiler will emit a fatal error 7310d565efSmrgand exit with the error message: 7410d565efSmrg 7510d565efSmrg@smallexample 7610d565efSmrgfatal error: plugin @var{name} is not licensed under a GPL-compatible license 7710d565efSmrg@var{name}: undefined symbol: plugin_is_GPL_compatible 7810d565efSmrgcompilation terminated 7910d565efSmrg@end smallexample 8010d565efSmrg 8110d565efSmrgThe declared type of the symbol should be int, to match a forward declaration 8210d565efSmrgin @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in 8310d565efSmrgany allocated section, though. The compiler merely asserts that 8410d565efSmrgthe symbol exists in the global scope. Something like this is enough: 8510d565efSmrg 8610d565efSmrg@smallexample 8710d565efSmrgint plugin_is_GPL_compatible; 8810d565efSmrg@end smallexample 8910d565efSmrg 9010d565efSmrg@subsection Plugin initialization 9110d565efSmrg 9210d565efSmrgEvery plugin should export a function called @code{plugin_init} that 9310d565efSmrgis called right after the plugin is loaded. This function is 9410d565efSmrgresponsible for registering all the callbacks required by the plugin 9510d565efSmrgand do any other required initialization. 9610d565efSmrg 9710d565efSmrgThis function is called from @code{compile_file} right before invoking 9810d565efSmrgthe parser. The arguments to @code{plugin_init} are: 9910d565efSmrg 10010d565efSmrg@itemize @bullet 10110d565efSmrg@item @code{plugin_info}: Plugin invocation information. 10210d565efSmrg@item @code{version}: GCC version. 10310d565efSmrg@end itemize 10410d565efSmrg 10510d565efSmrgThe @code{plugin_info} struct is defined as follows: 10610d565efSmrg 10710d565efSmrg@smallexample 10810d565efSmrgstruct plugin_name_args 10910d565efSmrg@{ 11010d565efSmrg char *base_name; /* Short name of the plugin 11110d565efSmrg (filename without .so suffix). */ 11210d565efSmrg const char *full_name; /* Path to the plugin as specified with 11310d565efSmrg -fplugin=. */ 11410d565efSmrg int argc; /* Number of arguments specified with 11510d565efSmrg -fplugin-arg-.... */ 11610d565efSmrg struct plugin_argument *argv; /* Array of ARGC key-value pairs. */ 11710d565efSmrg const char *version; /* Version string provided by plugin. */ 11810d565efSmrg const char *help; /* Help string provided by plugin. */ 11910d565efSmrg@} 12010d565efSmrg@end smallexample 12110d565efSmrg 12210d565efSmrgIf initialization fails, @code{plugin_init} must return a non-zero 12310d565efSmrgvalue. Otherwise, it should return 0. 12410d565efSmrg 12510d565efSmrgThe version of the GCC compiler loading the plugin is described by the 12610d565efSmrgfollowing structure: 12710d565efSmrg 12810d565efSmrg@smallexample 12910d565efSmrgstruct plugin_gcc_version 13010d565efSmrg@{ 13110d565efSmrg const char *basever; 13210d565efSmrg const char *datestamp; 13310d565efSmrg const char *devphase; 13410d565efSmrg const char *revision; 13510d565efSmrg const char *configuration_arguments; 13610d565efSmrg@}; 13710d565efSmrg@end smallexample 13810d565efSmrg 13910d565efSmrgThe function @code{plugin_default_version_check} takes two pointers to 14010d565efSmrgsuch structure and compare them field by field. It can be used by the 14110d565efSmrgplugin's @code{plugin_init} function. 14210d565efSmrg 14310d565efSmrgThe version of GCC used to compile the plugin can be found in the symbol 14410d565efSmrg@code{gcc_version} defined in the header @file{plugin-version.h}. The 14510d565efSmrgrecommended version check to perform looks like 14610d565efSmrg 14710d565efSmrg@smallexample 14810d565efSmrg#include "plugin-version.h" 14910d565efSmrg... 15010d565efSmrg 15110d565efSmrgint 15210d565efSmrgplugin_init (struct plugin_name_args *plugin_info, 15310d565efSmrg struct plugin_gcc_version *version) 15410d565efSmrg@{ 15510d565efSmrg if (!plugin_default_version_check (version, &gcc_version)) 15610d565efSmrg return 1; 15710d565efSmrg 15810d565efSmrg@} 15910d565efSmrg@end smallexample 16010d565efSmrg 16110d565efSmrgbut you can also check the individual fields if you want a less strict check. 16210d565efSmrg 16310d565efSmrg@subsection Plugin callbacks 16410d565efSmrg 16510d565efSmrgCallback functions have the following prototype: 16610d565efSmrg 16710d565efSmrg@smallexample 16810d565efSmrg/* The prototype for a plugin callback function. 16910d565efSmrg gcc_data - event-specific data provided by GCC 17010d565efSmrg user_data - plugin-specific data provided by the plug-in. */ 17110d565efSmrgtypedef void (*plugin_callback_func)(void *gcc_data, void *user_data); 17210d565efSmrg@end smallexample 17310d565efSmrg 17410d565efSmrgCallbacks can be invoked at the following pre-determined events: 17510d565efSmrg 17610d565efSmrg 17710d565efSmrg@smallexample 17810d565efSmrgenum plugin_event 17910d565efSmrg@{ 18010d565efSmrg PLUGIN_START_PARSE_FUNCTION, /* Called before parsing the body of a function. */ 18110d565efSmrg PLUGIN_FINISH_PARSE_FUNCTION, /* After finishing parsing a function. */ 18210d565efSmrg PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */ 18310d565efSmrg PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */ 18410d565efSmrg PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */ 18510d565efSmrg PLUGIN_FINISH_UNIT, /* Useful for summary processing. */ 18610d565efSmrg PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */ 18710d565efSmrg PLUGIN_FINISH, /* Called before GCC exits. */ 18810d565efSmrg PLUGIN_INFO, /* Information about the plugin. */ 18910d565efSmrg PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */ 19010d565efSmrg PLUGIN_GGC_MARKING, /* Extend the GGC marking. */ 19110d565efSmrg PLUGIN_GGC_END, /* Called at end of GGC. */ 19210d565efSmrg PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */ 19310d565efSmrg PLUGIN_ATTRIBUTES, /* Called during attribute registration */ 19410d565efSmrg PLUGIN_START_UNIT, /* Called before processing a translation unit. */ 19510d565efSmrg PLUGIN_PRAGMAS, /* Called during pragma registration. */ 19610d565efSmrg /* Called before first pass from all_passes. */ 19710d565efSmrg PLUGIN_ALL_PASSES_START, 19810d565efSmrg /* Called after last pass from all_passes. */ 19910d565efSmrg PLUGIN_ALL_PASSES_END, 20010d565efSmrg /* Called before first ipa pass. */ 20110d565efSmrg PLUGIN_ALL_IPA_PASSES_START, 20210d565efSmrg /* Called after last ipa pass. */ 20310d565efSmrg PLUGIN_ALL_IPA_PASSES_END, 20410d565efSmrg /* Allows to override pass gate decision for current_pass. */ 20510d565efSmrg PLUGIN_OVERRIDE_GATE, 20610d565efSmrg /* Called before executing a pass. */ 20710d565efSmrg PLUGIN_PASS_EXECUTION, 20810d565efSmrg /* Called before executing subpasses of a GIMPLE_PASS in 20910d565efSmrg execute_ipa_pass_list. */ 21010d565efSmrg PLUGIN_EARLY_GIMPLE_PASSES_START, 21110d565efSmrg /* Called after executing subpasses of a GIMPLE_PASS in 21210d565efSmrg execute_ipa_pass_list. */ 21310d565efSmrg PLUGIN_EARLY_GIMPLE_PASSES_END, 21410d565efSmrg /* Called when a pass is first instantiated. */ 21510d565efSmrg PLUGIN_NEW_PASS, 21610d565efSmrg/* Called when a file is #include-d or given via the #line directive. 21710d565efSmrg This could happen many times. The event data is the included file path, 21810d565efSmrg as a const char* pointer. */ 21910d565efSmrg PLUGIN_INCLUDE_FILE, 22010d565efSmrg 22110d565efSmrg PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback 22210d565efSmrg array. */ 22310d565efSmrg@}; 22410d565efSmrg@end smallexample 22510d565efSmrg 22610d565efSmrgIn addition, plugins can also look up the enumerator of a named event, 22710d565efSmrgand / or generate new events dynamically, by calling the function 22810d565efSmrg@code{get_named_event_id}. 22910d565efSmrg 23010d565efSmrgTo register a callback, the plugin calls @code{register_callback} with 23110d565efSmrgthe arguments: 23210d565efSmrg 23310d565efSmrg@itemize 23410d565efSmrg@item @code{char *name}: Plugin name. 23510d565efSmrg@item @code{int event}: The event code. 23610d565efSmrg@item @code{plugin_callback_func callback}: The function that handles @code{event}. 23710d565efSmrg@item @code{void *user_data}: Pointer to plugin-specific data. 23810d565efSmrg@end itemize 23910d565efSmrg 24010d565efSmrgFor the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO}, and 24110d565efSmrg@i{PLUGIN_REGISTER_GGC_ROOTS} pseudo-events the @code{callback} should be null, 24210d565efSmrgand the @code{user_data} is specific. 24310d565efSmrg 24410d565efSmrgWhen the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as 24510d565efSmrgdata from GCC), plugins may register their own pragmas. Notice that 24610d565efSmrgpragmas are not available from @file{lto1}, so plugins used with 24710d565efSmrg@code{-flto} option to GCC during link-time optimization cannot use 24810d565efSmrgpragmas and do not even see functions like @code{c_register_pragma} or 24910d565efSmrg@code{pragma_lex}. 25010d565efSmrg 25110d565efSmrgThe @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as 25210d565efSmrgGCC data, is triggered for processing of @code{#include} or 25310d565efSmrg@code{#line} directives. 25410d565efSmrg 25510d565efSmrgThe @i{PLUGIN_FINISH} event is the last time that plugins can call GCC 25610d565efSmrgfunctions, notably emit diagnostics with @code{warning}, @code{error} 25710d565efSmrgetc. 25810d565efSmrg 25910d565efSmrg 26010d565efSmrg@node Plugins pass 26110d565efSmrg@section Interacting with the pass manager 26210d565efSmrg 26310d565efSmrgThere needs to be a way to add/reorder/remove passes dynamically. This 26410d565efSmrgis useful for both analysis plugins (plugging in after a certain pass 26510d565efSmrgsuch as CFG or an IPA pass) and optimization plugins. 26610d565efSmrg 26710d565efSmrgBasic support for inserting new passes or replacing existing passes is 26810d565efSmrgprovided. A plugin registers a new pass with GCC by calling 26910d565efSmrg@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP} 27010d565efSmrgevent and a pointer to a @code{struct register_pass_info} object defined as follows 27110d565efSmrg 27210d565efSmrg@smallexample 27310d565efSmrgenum pass_positioning_ops 27410d565efSmrg@{ 27510d565efSmrg PASS_POS_INSERT_AFTER, // Insert after the reference pass. 27610d565efSmrg PASS_POS_INSERT_BEFORE, // Insert before the reference pass. 27710d565efSmrg PASS_POS_REPLACE // Replace the reference pass. 27810d565efSmrg@}; 27910d565efSmrg 28010d565efSmrgstruct register_pass_info 28110d565efSmrg@{ 28210d565efSmrg struct opt_pass *pass; /* New pass provided by the plugin. */ 28310d565efSmrg const char *reference_pass_name; /* Name of the reference pass for hooking 28410d565efSmrg up the new pass. */ 28510d565efSmrg int ref_pass_instance_number; /* Insert the pass at the specified 28610d565efSmrg instance number of the reference pass. */ 28710d565efSmrg /* Do it for every instance if it is 0. */ 28810d565efSmrg enum pass_positioning_ops pos_op; /* how to insert the new pass. */ 28910d565efSmrg@}; 29010d565efSmrg 29110d565efSmrg 29210d565efSmrg/* Sample plugin code that registers a new pass. */ 29310d565efSmrgint 29410d565efSmrgplugin_init (struct plugin_name_args *plugin_info, 29510d565efSmrg struct plugin_gcc_version *version) 29610d565efSmrg@{ 29710d565efSmrg struct register_pass_info pass_info; 29810d565efSmrg 29910d565efSmrg ... 30010d565efSmrg 30110d565efSmrg /* Code to fill in the pass_info object with new pass information. */ 30210d565efSmrg 30310d565efSmrg ... 30410d565efSmrg 30510d565efSmrg /* Register the new pass. */ 30610d565efSmrg register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info); 30710d565efSmrg 30810d565efSmrg ... 30910d565efSmrg@} 31010d565efSmrg@end smallexample 31110d565efSmrg 31210d565efSmrg 31310d565efSmrg@node Plugins GC 31410d565efSmrg@section Interacting with the GCC Garbage Collector 31510d565efSmrg 31610d565efSmrgSome plugins may want to be informed when GGC (the GCC Garbage 31710d565efSmrgCollector) is running. They can register callbacks for the 31810d565efSmrg@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which 31910d565efSmrgthe callback is called with a null @code{gcc_data}) to be notified of 32010d565efSmrgthe start or end of the GCC garbage collection. 32110d565efSmrg 32210d565efSmrgSome plugins may need to have GGC mark additional data. This can be 32310d565efSmrgdone by registering a callback (called with a null @code{gcc_data}) 32410d565efSmrgfor the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the 32510d565efSmrg@code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro 32610d565efSmrg(and conversely, these routines should usually not be used in plugins 32710d565efSmrgoutside of the @code{PLUGIN_GGC_MARKING} event). Plugins that wish to hold 32810d565efSmrgweak references to gc data may also use this event to drop weak references when 32910d565efSmrgthe object is about to be collected. The @code{ggc_marked_p} function can be 33010d565efSmrgused to tell if an object is marked, or is about to be collected. The 33110d565efSmrg@code{gt_clear_cache} overloads which some types define may also be of use in 33210d565efSmrgmanaging weak references. 33310d565efSmrg 3340fc04c29SmrgSome plugins may need to add extra GGC root tables, e.g.@: to handle their own 33510d565efSmrg@code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS} 33610d565efSmrgpseudo-event with a null callback and the extra root table (of type @code{struct 33710d565efSmrgggc_root_tab*}) as @code{user_data}. Running the 33810d565efSmrg @code{gengtype -p @var{source-dir} @var{file-list} @var{plugin*.c} ...} 33910d565efSmrgutility generates these extra root tables. 34010d565efSmrg 34110d565efSmrgYou should understand the details of memory management inside GCC 34210d565efSmrgbefore using @code{PLUGIN_GGC_MARKING} or @code{PLUGIN_REGISTER_GGC_ROOTS}. 34310d565efSmrg 34410d565efSmrg 34510d565efSmrg@node Plugins description 34610d565efSmrg@section Giving information about a plugin 34710d565efSmrg 34810d565efSmrgA plugin should give some information to the user about itself. This 34910d565efSmrguses the following structure: 35010d565efSmrg 35110d565efSmrg@smallexample 35210d565efSmrgstruct plugin_info 35310d565efSmrg@{ 35410d565efSmrg const char *version; 35510d565efSmrg const char *help; 35610d565efSmrg@}; 35710d565efSmrg@end smallexample 35810d565efSmrg 35910d565efSmrgSuch a structure is passed as the @code{user_data} by the plugin's 36010d565efSmrginit routine using @code{register_callback} with the 36110d565efSmrg@code{PLUGIN_INFO} pseudo-event and a null callback. 36210d565efSmrg 36310d565efSmrg@node Plugins attr 36410d565efSmrg@section Registering custom attributes or pragmas 36510d565efSmrg 36610d565efSmrgFor analysis (or other) purposes it is useful to be able to add custom 36710d565efSmrgattributes or pragmas. 36810d565efSmrg 36910d565efSmrgThe @code{PLUGIN_ATTRIBUTES} callback is called during attribute 37010d565efSmrgregistration. Use the @code{register_attribute} function to register 37110d565efSmrgcustom attributes. 37210d565efSmrg 37310d565efSmrg@smallexample 37410d565efSmrg/* Attribute handler callback */ 37510d565efSmrgstatic tree 37610d565efSmrghandle_user_attribute (tree *node, tree name, tree args, 37710d565efSmrg int flags, bool *no_add_attrs) 37810d565efSmrg@{ 37910d565efSmrg return NULL_TREE; 38010d565efSmrg@} 38110d565efSmrg 38210d565efSmrg/* Attribute definition */ 38310d565efSmrgstatic struct attribute_spec user_attr = 384c7a68eb7Smrg @{ "user", 1, 1, false, false, false, false, handle_user_attribute, NULL @}; 38510d565efSmrg 38610d565efSmrg/* Plugin callback called during attribute registration. 38710d565efSmrgRegistered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL) 38810d565efSmrg*/ 38910d565efSmrgstatic void 39010d565efSmrgregister_attributes (void *event_data, void *data) 39110d565efSmrg@{ 39210d565efSmrg warning (0, G_("Callback to register attributes")); 39310d565efSmrg register_attribute (&user_attr); 39410d565efSmrg@} 39510d565efSmrg 39610d565efSmrg@end smallexample 39710d565efSmrg 39810d565efSmrg 39910d565efSmrgThe @i{PLUGIN_PRAGMAS} callback is called once during pragmas 40010d565efSmrgregistration. Use the @code{c_register_pragma}, 40110d565efSmrg@code{c_register_pragma_with_data}, 40210d565efSmrg@code{c_register_pragma_with_expansion}, 40310d565efSmrg@code{c_register_pragma_with_expansion_and_data} functions to register 40410d565efSmrgcustom pragmas and their handlers (which often want to call 40510d565efSmrg@code{pragma_lex}) from @file{c-family/c-pragma.h}. 40610d565efSmrg 40710d565efSmrg@smallexample 40810d565efSmrg/* Plugin callback called during pragmas registration. Registered with 40910d565efSmrg register_callback (plugin_name, PLUGIN_PRAGMAS, 41010d565efSmrg register_my_pragma, NULL); 41110d565efSmrg*/ 41210d565efSmrgstatic void 41310d565efSmrgregister_my_pragma (void *event_data, void *data) 41410d565efSmrg@{ 41510d565efSmrg warning (0, G_("Callback to register pragmas")); 41610d565efSmrg c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello); 41710d565efSmrg@} 41810d565efSmrg@end smallexample 41910d565efSmrg 42010d565efSmrgIt is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying 42110d565efSmrgyour plugin) as the ``space'' argument of your pragma. 42210d565efSmrg 42310d565efSmrgPragmas registered with @code{c_register_pragma_with_expansion} or 42410d565efSmrg@code{c_register_pragma_with_expansion_and_data} support 42510d565efSmrgpreprocessor expansions. For example: 42610d565efSmrg 42710d565efSmrg@smallexample 42810d565efSmrg#define NUMBER 10 42910d565efSmrg#pragma GCCPLUGIN foothreshold (NUMBER) 43010d565efSmrg@end smallexample 43110d565efSmrg 43210d565efSmrg@node Plugins recording 43310d565efSmrg@section Recording information about pass execution 43410d565efSmrg 43510d565efSmrgThe event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass 43610d565efSmrg(the same as current_pass) as @code{gcc_data} to the callback. You can also 43710d565efSmrginspect cfun to find out about which function this pass is executed for. 43810d565efSmrgNote that this event will only be invoked if the gate check (if 43910d565efSmrgapplicable, modified by PLUGIN_OVERRIDE_GATE) succeeds. 44010d565efSmrgYou can use other hooks, like @code{PLUGIN_ALL_PASSES_START}, 44110d565efSmrg@code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START}, 44210d565efSmrg@code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START}, 44310d565efSmrgand/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state 44410d565efSmrgin your plugin(s) in order to get context for the pass execution. 44510d565efSmrg 44610d565efSmrg 44710d565efSmrg@node Plugins gate 44810d565efSmrg@section Controlling which passes are being run 44910d565efSmrg 45010d565efSmrgAfter the original gate function for a pass is called, its result 45110d565efSmrg- the gate status - is stored as an integer. 45210d565efSmrgThen the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer 45310d565efSmrgto the gate status in the @code{gcc_data} parameter to the callback function. 45410d565efSmrgA nonzero value of the gate status means that the pass is to be executed. 45510d565efSmrgYou can both read and write the gate status via the passed pointer. 45610d565efSmrg 45710d565efSmrg 45810d565efSmrg@node Plugins tracking 45910d565efSmrg@section Keeping track of available passes 46010d565efSmrg 46110d565efSmrgWhen your plugin is loaded, you can inspect the various 46210d565efSmrgpass lists to determine what passes are available. However, other 46310d565efSmrgplugins might add new passes. Also, future changes to GCC might cause 46410d565efSmrggeneric passes to be added after plugin loading. 46510d565efSmrgWhen a pass is first added to one of the pass lists, the event 46610d565efSmrg@code{PLUGIN_NEW_PASS} is invoked, with the callback parameter 46710d565efSmrg@code{gcc_data} pointing to the new pass. 46810d565efSmrg 46910d565efSmrg 47010d565efSmrg@node Plugins building 47110d565efSmrg@section Building GCC plugins 47210d565efSmrg 47310d565efSmrgIf plugins are enabled, GCC installs the headers needed to build a 4740fc04c29Smrgplugin (somewhere in the installation tree, e.g.@: under 47510d565efSmrg@file{/usr/local}). In particular a @file{plugin/include} directory 47610d565efSmrgis installed, containing all the header files needed to build plugins. 47710d565efSmrg 47810d565efSmrgOn most systems, you can query this @code{plugin} directory by 47910d565efSmrginvoking @command{gcc -print-file-name=plugin} (replace if needed 48010d565efSmrg@command{gcc} with the appropriate program path). 48110d565efSmrg 48210d565efSmrgInside plugins, this @code{plugin} directory name can be queried by 48310d565efSmrgcalling @code{default_plugin_dir_name ()}. 48410d565efSmrg 48510d565efSmrgPlugins may know, when they are compiled, the GCC version for which 48610d565efSmrg@file{plugin-version.h} is provided. The constant macros 48710d565efSmrg@code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR}, 48810d565efSmrg@code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are 48910d565efSmrginteger numbers, so a plugin could ensure it is built for GCC 4.7 with 49010d565efSmrg@smallexample 49110d565efSmrg#if GCCPLUGIN_VERSION != 4007 49210d565efSmrg#error this GCC plugin is for GCC 4.7 49310d565efSmrg#endif 49410d565efSmrg@end smallexample 49510d565efSmrg 49610d565efSmrgThe following GNU Makefile excerpt shows how to build a simple plugin: 49710d565efSmrg 49810d565efSmrg@smallexample 49910d565efSmrgHOST_GCC=g++ 50010d565efSmrgTARGET_GCC=gcc 50110d565efSmrgPLUGIN_SOURCE_FILES= plugin1.c plugin2.cc 50210d565efSmrgGCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin) 50310d565efSmrgCXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2 50410d565efSmrg 50510d565efSmrgplugin.so: $(PLUGIN_SOURCE_FILES) 50610d565efSmrg $(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@@ 50710d565efSmrg@end smallexample 50810d565efSmrg 50910d565efSmrgA single source file plugin may be built with @code{g++ -I`gcc 51010d565efSmrg-print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.c -o 51110d565efSmrgplugin.so}, using backquote shell syntax to query the @file{plugin} 51210d565efSmrgdirectory. 51310d565efSmrg 514c7a68eb7SmrgPlugin support on Windows/MinGW has a number of limitations and 515c7a68eb7Smrgadditional requirements. When building a plugin on Windows we have to 516c7a68eb7Smrglink an import library for the corresponding backend executable, for 517c7a68eb7Smrgexample, @file{cc1.exe}, @file{cc1plus.exe}, etc., in order to gain 518c7a68eb7Smrgaccess to the symbols provided by GCC. This means that on Windows a 519c7a68eb7Smrgplugin is language-specific, for example, for C, C++, etc. If you wish 520c7a68eb7Smrgto use your plugin with multiple languages, then you will need to 521c7a68eb7Smrgbuild multiple plugin libraries and either instruct your users on how 522c7a68eb7Smrgto load the correct version or provide a compiler wrapper that does 523c7a68eb7Smrgthis automatically. 524c7a68eb7Smrg 525c7a68eb7SmrgAdditionally, on Windows the plugin library has to export the 526c7a68eb7Smrg@code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you 527c7a68eb7Smrgdo not wish to modify the source code of your plugin, then you can use 528c7a68eb7Smrgthe @option{-Wl,--export-all-symbols} option or provide a suitable DEF 529c7a68eb7Smrgfile. Alternatively, you can export just these two symbols by decorating 530c7a68eb7Smrgthem with @code{__declspec(dllexport)}, for example: 531c7a68eb7Smrg 532c7a68eb7Smrg@smallexample 533c7a68eb7Smrg#ifdef _WIN32 534c7a68eb7Smrg__declspec(dllexport) 535c7a68eb7Smrg#endif 536c7a68eb7Smrgint plugin_is_GPL_compatible; 537c7a68eb7Smrg 538c7a68eb7Smrg#ifdef _WIN32 539c7a68eb7Smrg__declspec(dllexport) 540c7a68eb7Smrg#endif 541c7a68eb7Smrgint plugin_init (plugin_name_args *, plugin_gcc_version *) 542c7a68eb7Smrg@end smallexample 543c7a68eb7Smrg 544c7a68eb7SmrgThe import libraries are installed into the @code{plugin} directory 545c7a68eb7Smrgand their names are derived by appending the @code{.a} extension to 546c7a68eb7Smrgthe backend executable names, for example, @file{cc1.exe.a}, 547c7a68eb7Smrg@file{cc1plus.exe.a}, etc. The following command line shows how to 548c7a68eb7Smrgbuild the single source file plugin on Windows to be used with the C++ 549c7a68eb7Smrgcompiler: 550c7a68eb7Smrg 551c7a68eb7Smrg@smallexample 552c7a68eb7Smrgg++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \ 553c7a68eb7Smrg-o plugin.dll plugin.c `gcc -print-file-name=plugin`/cc1plus.exe.a 554c7a68eb7Smrg@end smallexample 555c7a68eb7Smrg 55610d565efSmrgWhen a plugin needs to use @command{gengtype}, be sure that both 55710d565efSmrg@file{gengtype} and @file{gtype.state} have the same version as the 55810d565efSmrgGCC for which the plugin is built. 559