@c Copyright (c) 2009, 2010 Free Software Foundation, Inc.
|
@c Copyright (c) 2009, 2010 Free Software Foundation, Inc.
|
@c Free Software Foundation, Inc.
|
@c Free Software Foundation, Inc.
|
@c This is part of the GCC manual.
|
@c This is part of the GCC manual.
|
@c For copying conditions, see the file gcc.texi.
|
@c For copying conditions, see the file gcc.texi.
|
|
|
@node Plugins
|
@node Plugins
|
@chapter Plugins
|
@chapter Plugins
|
@cindex Plugins
|
@cindex Plugins
|
|
|
@section Loading Plugins
|
@section Loading Plugins
|
|
|
Plugins are supported on platforms that support @option{-ldl
|
Plugins are supported on platforms that support @option{-ldl
|
-rdynamic}. They are loaded by the compiler using @code{dlopen}
|
-rdynamic}. They are loaded by the compiler using @code{dlopen}
|
and invoked at pre-determined locations in the compilation
|
and invoked at pre-determined locations in the compilation
|
process.
|
process.
|
|
|
Plugins are loaded with
|
Plugins are loaded with
|
|
|
@option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
|
@option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
|
|
|
The plugin arguments are parsed by GCC and passed to respective
|
The plugin arguments are parsed by GCC and passed to respective
|
plugins as key-value pairs. Multiple plugins can be invoked by
|
plugins as key-value pairs. Multiple plugins can be invoked by
|
specifying multiple @option{-fplugin} arguments.
|
specifying multiple @option{-fplugin} arguments.
|
|
|
|
|
@section Plugin API
|
@section Plugin API
|
|
|
Plugins are activated by the compiler at specific events as defined in
|
Plugins are activated by the compiler at specific events as defined in
|
@file{gcc-plugin.h}. For each event of interest, the plugin should
|
@file{gcc-plugin.h}. For each event of interest, the plugin should
|
call @code{register_callback} specifying the name of the event and
|
call @code{register_callback} specifying the name of the event and
|
address of the callback function that will handle that event.
|
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.
|
The header @file{gcc-plugin.h} must be the first gcc header to be included.
|
|
|
@subsection Plugin license check
|
@subsection Plugin license check
|
|
|
Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
|
Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
|
to assert that it has been licensed under a GPL-compatible license.
|
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
|
If this symbol does not exist, the compiler will emit a fatal error
|
and exit with the error message:
|
and exit with the error message:
|
|
|
@smallexample
|
@smallexample
|
fatal error: plugin <name> is not licensed under a GPL-compatible license
|
fatal error: plugin <name> is not licensed under a GPL-compatible license
|
<name>: undefined symbol: plugin_is_GPL_compatible
|
<name>: undefined symbol: plugin_is_GPL_compatible
|
compilation terminated
|
compilation terminated
|
@end smallexample
|
@end smallexample
|
|
|
The type of the symbol is irrelevant. The compiler merely asserts that
|
The type of the symbol is irrelevant. The compiler merely asserts that
|
it exists in the global scope. Something like this is enough:
|
it exists in the global scope. Something like this is enough:
|
|
|
@smallexample
|
@smallexample
|
int plugin_is_GPL_compatible;
|
int plugin_is_GPL_compatible;
|
@end smallexample
|
@end smallexample
|
|
|
@subsection Plugin initialization
|
@subsection Plugin initialization
|
|
|
Every plugin should export a function called @code{plugin_init} that
|
Every plugin should export a function called @code{plugin_init} that
|
is called right after the plugin is loaded. This function is
|
is called right after the plugin is loaded. This function is
|
responsible for registering all the callbacks required by the plugin
|
responsible for registering all the callbacks required by the plugin
|
and do any other required initialization.
|
and do any other required initialization.
|
|
|
This function is called from @code{compile_file} right before invoking
|
This function is called from @code{compile_file} right before invoking
|
the parser. The arguments to @code{plugin_init} are:
|
the parser. The arguments to @code{plugin_init} are:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item @code{plugin_info}: Plugin invocation information.
|
@item @code{plugin_info}: Plugin invocation information.
|
@item @code{version}: GCC version.
|
@item @code{version}: GCC version.
|
@end itemize
|
@end itemize
|
|
|
The @code{plugin_info} struct is defined as follows:
|
The @code{plugin_info} struct is defined as follows:
|
|
|
@smallexample
|
@smallexample
|
struct plugin_name_args
|
struct plugin_name_args
|
@{
|
@{
|
char *base_name; /* Short name of the plugin
|
char *base_name; /* Short name of the plugin
|
(filename without .so suffix). */
|
(filename without .so suffix). */
|
const char *full_name; /* Path to the plugin as specified with
|
const char *full_name; /* Path to the plugin as specified with
|
-fplugin=. */
|
-fplugin=. */
|
int argc; /* Number of arguments specified with
|
int argc; /* Number of arguments specified with
|
-fplugin-arg-.... */
|
-fplugin-arg-.... */
|
struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
|
struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
|
const char *version; /* Version string provided by plugin. */
|
const char *version; /* Version string provided by plugin. */
|
const char *help; /* Help string provided by plugin. */
|
const char *help; /* Help string provided by plugin. */
|
@}
|
@}
|
@end smallexample
|
@end smallexample
|
|
|
If initialization fails, @code{plugin_init} must return a non-zero
|
If initialization fails, @code{plugin_init} must return a non-zero
|
value. Otherwise, it should return 0.
|
value. Otherwise, it should return 0.
|
|
|
The version of the GCC compiler loading the plugin is described by the
|
The version of the GCC compiler loading the plugin is described by the
|
following structure:
|
following structure:
|
|
|
@smallexample
|
@smallexample
|
struct plugin_gcc_version
|
struct plugin_gcc_version
|
@{
|
@{
|
const char *basever;
|
const char *basever;
|
const char *datestamp;
|
const char *datestamp;
|
const char *devphase;
|
const char *devphase;
|
const char *revision;
|
const char *revision;
|
const char *configuration_arguments;
|
const char *configuration_arguments;
|
@};
|
@};
|
@end smallexample
|
@end smallexample
|
|
|
The function @code{plugin_default_version_check} takes two pointers to
|
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
|
such structure and compare them field by field. It can be used by the
|
plugin's @code{plugin_init} function.
|
plugin's @code{plugin_init} function.
|
|
|
The version of GCC used to compile the plugin can be found in the symbol
|
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
|
@code{gcc_version} defined in the header @file{plugin-version.h}. The
|
recommended version check to perform looks like
|
recommended version check to perform looks like
|
|
|
@smallexample
|
@smallexample
|
#include "plugin-version.h"
|
#include "plugin-version.h"
|
...
|
...
|
|
|
int
|
int
|
plugin_init (struct plugin_name_args *plugin_info,
|
plugin_init (struct plugin_name_args *plugin_info,
|
struct plugin_gcc_version *version)
|
struct plugin_gcc_version *version)
|
@{
|
@{
|
if (!plugin_default_version_check (version, &gcc_version))
|
if (!plugin_default_version_check (version, &gcc_version))
|
return 1;
|
return 1;
|
|
|
@}
|
@}
|
@end smallexample
|
@end smallexample
|
|
|
but you can also check the individual fields if you want a less strict check.
|
but you can also check the individual fields if you want a less strict check.
|
|
|
@subsection Plugin callbacks
|
@subsection Plugin callbacks
|
|
|
Callback functions have the following prototype:
|
Callback functions have the following prototype:
|
|
|
@smallexample
|
@smallexample
|
/* The prototype for a plugin callback function.
|
/* The prototype for a plugin callback function.
|
gcc_data - event-specific data provided by GCC
|
gcc_data - event-specific data provided by GCC
|
user_data - plugin-specific data provided by the plug-in. */
|
user_data - plugin-specific data provided by the plug-in. */
|
typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
|
typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
|
@end smallexample
|
@end smallexample
|
|
|
Callbacks can be invoked at the following pre-determined events:
|
Callbacks can be invoked at the following pre-determined events:
|
|
|
|
|
@smallexample
|
@smallexample
|
enum plugin_event
|
enum plugin_event
|
@{
|
@{
|
PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
|
PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
|
PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
|
PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
|
PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
|
PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
|
PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
|
PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
|
PLUGIN_FINISH, /* Called before GCC exits. */
|
PLUGIN_FINISH, /* Called before GCC exits. */
|
PLUGIN_INFO, /* Information about the plugin. */
|
PLUGIN_INFO, /* Information about the plugin. */
|
PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
|
PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
|
PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
|
PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
|
PLUGIN_GGC_END, /* Called at end of GGC. */
|
PLUGIN_GGC_END, /* Called at end of GGC. */
|
PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
|
PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
|
PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
|
PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
|
PLUGIN_ATTRIBUTES, /* Called during attribute registration */
|
PLUGIN_ATTRIBUTES, /* Called during attribute registration */
|
PLUGIN_START_UNIT, /* Called before processing a translation unit. */
|
PLUGIN_START_UNIT, /* Called before processing a translation unit. */
|
PLUGIN_PRAGMAS, /* Called during pragma registration. */
|
PLUGIN_PRAGMAS, /* Called during pragma registration. */
|
/* Called before first pass from all_passes. */
|
/* Called before first pass from all_passes. */
|
PLUGIN_ALL_PASSES_START,
|
PLUGIN_ALL_PASSES_START,
|
/* Called after last pass from all_passes. */
|
/* Called after last pass from all_passes. */
|
PLUGIN_ALL_PASSES_END,
|
PLUGIN_ALL_PASSES_END,
|
/* Called before first ipa pass. */
|
/* Called before first ipa pass. */
|
PLUGIN_ALL_IPA_PASSES_START,
|
PLUGIN_ALL_IPA_PASSES_START,
|
/* Called after last ipa pass. */
|
/* Called after last ipa pass. */
|
PLUGIN_ALL_IPA_PASSES_END,
|
PLUGIN_ALL_IPA_PASSES_END,
|
/* Allows to override pass gate decision for current_pass. */
|
/* Allows to override pass gate decision for current_pass. */
|
PLUGIN_OVERRIDE_GATE,
|
PLUGIN_OVERRIDE_GATE,
|
/* Called before executing a pass. */
|
/* Called before executing a pass. */
|
PLUGIN_PASS_EXECUTION,
|
PLUGIN_PASS_EXECUTION,
|
/* Called before executing subpasses of a GIMPLE_PASS in
|
/* Called before executing subpasses of a GIMPLE_PASS in
|
execute_ipa_pass_list. */
|
execute_ipa_pass_list. */
|
PLUGIN_EARLY_GIMPLE_PASSES_START,
|
PLUGIN_EARLY_GIMPLE_PASSES_START,
|
/* Called after executing subpasses of a GIMPLE_PASS in
|
/* Called after executing subpasses of a GIMPLE_PASS in
|
execute_ipa_pass_list. */
|
execute_ipa_pass_list. */
|
PLUGIN_EARLY_GIMPLE_PASSES_END,
|
PLUGIN_EARLY_GIMPLE_PASSES_END,
|
/* Called when a pass is first instantiated. */
|
/* Called when a pass is first instantiated. */
|
PLUGIN_NEW_PASS,
|
PLUGIN_NEW_PASS,
|
|
|
PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
|
PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
|
array. */
|
array. */
|
@};
|
@};
|
@end smallexample
|
@end smallexample
|
|
|
In addition, plugins can also look up the enumerator of a named event,
|
In addition, plugins can also look up the enumerator of a named event,
|
and / or generate new events dynamically, by calling the function
|
and / or generate new events dynamically, by calling the function
|
@code{get_named_event_id}.
|
@code{get_named_event_id}.
|
|
|
To register a callback, the plugin calls @code{register_callback} with
|
To register a callback, the plugin calls @code{register_callback} with
|
the arguments:
|
the arguments:
|
|
|
@itemize
|
@itemize
|
@item @code{char *name}: Plugin name.
|
@item @code{char *name}: Plugin name.
|
@item @code{int event}: The event code.
|
@item @code{int event}: The event code.
|
@item @code{plugin_callback_func callback}: The function that handles @code{event}.
|
@item @code{plugin_callback_func callback}: The function that handles @code{event}.
|
@item @code{void *user_data}: Pointer to plugin-specific data.
|
@item @code{void *user_data}: Pointer to plugin-specific data.
|
@end itemize
|
@end itemize
|
|
|
For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
|
For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
|
and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
|
and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
|
null, and the @code{user_data} is specific.
|
null, and the @code{user_data} is specific.
|
|
|
When the PLUGIN_PRAGMAS event is triggered (with a null
|
When the PLUGIN_PRAGMAS event is triggered (with a null
|
pointer as data from GCC), plugins may register their own pragmas
|
pointer as data from GCC), plugins may register their own pragmas
|
using functions like @code{c_register_pragma} or
|
using functions like @code{c_register_pragma} or
|
@code{c_register_pragma_with_expansion}.
|
@code{c_register_pragma_with_expansion}.
|
|
|
@section Interacting with the pass manager
|
@section Interacting with the pass manager
|
|
|
There needs to be a way to add/reorder/remove passes dynamically. This
|
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
|
is useful for both analysis plugins (plugging in after a certain pass
|
such as CFG or an IPA pass) and optimization plugins.
|
such as CFG or an IPA pass) and optimization plugins.
|
|
|
Basic support for inserting new passes or replacing existing passes is
|
Basic support for inserting new passes or replacing existing passes is
|
provided. A plugin registers a new pass with GCC by calling
|
provided. A plugin registers a new pass with GCC by calling
|
@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
|
@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
|
event and a pointer to a @code{struct register_pass_info} object defined as follows
|
|
|
@smallexample
|
@smallexample
|
enum pass_positioning_ops
|
enum pass_positioning_ops
|
@{
|
@{
|
PASS_POS_INSERT_AFTER, // Insert after the reference pass.
|
PASS_POS_INSERT_AFTER, // Insert after the reference pass.
|
PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
|
PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
|
PASS_POS_REPLACE // Replace the reference pass.
|
PASS_POS_REPLACE // Replace the reference pass.
|
@};
|
@};
|
|
|
struct register_pass_info
|
struct register_pass_info
|
@{
|
@{
|
struct opt_pass *pass; /* New pass provided by the plugin. */
|
struct opt_pass *pass; /* New pass provided by the plugin. */
|
const char *reference_pass_name; /* Name of the reference pass for hooking
|
const char *reference_pass_name; /* Name of the reference pass for hooking
|
up the new pass. */
|
up the new pass. */
|
int ref_pass_instance_number; /* Insert the pass at the specified
|
int ref_pass_instance_number; /* Insert the pass at the specified
|
instance number of the reference pass. */
|
instance number of the reference pass. */
|
/* Do it for every instance if it is 0. */
|
/* Do it for every instance if it is 0. */
|
enum pass_positioning_ops pos_op; /* how to insert the new pass. */
|
enum pass_positioning_ops pos_op; /* how to insert the new pass. */
|
@};
|
@};
|
|
|
|
|
/* Sample plugin code that registers a new pass. */
|
/* Sample plugin code that registers a new pass. */
|
int
|
int
|
plugin_init (struct plugin_name_args *plugin_info,
|
plugin_init (struct plugin_name_args *plugin_info,
|
struct plugin_gcc_version *version)
|
struct plugin_gcc_version *version)
|
@{
|
@{
|
struct register_pass_info pass_info;
|
struct register_pass_info pass_info;
|
|
|
...
|
...
|
|
|
/* Code to fill in the pass_info object with new pass information. */
|
/* Code to fill in the pass_info object with new pass information. */
|
|
|
...
|
...
|
|
|
/* Register the new pass. */
|
/* Register the new pass. */
|
register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
|
register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
|
|
|
...
|
...
|
@}
|
@}
|
@end smallexample
|
@end smallexample
|
|
|
|
|
@section Interacting with the GCC Garbage Collector
|
@section Interacting with the GCC Garbage Collector
|
|
|
Some plugins may want to be informed when GGC (the GCC Garbage
|
Some plugins may want to be informed when GGC (the GCC Garbage
|
Collector) is running. They can register callbacks for the
|
Collector) is running. They can register callbacks for the
|
@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
|
@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 callback is called with a null @code{gcc_data}) to be notified of
|
the start or end of the GCC garbage collection.
|
the start or end of the GCC garbage collection.
|
|
|
Some plugins may need to have GGC mark additional data. This can be
|
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})
|
done by registering a callback (called with a null @code{gcc_data})
|
for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
|
for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
|
@code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
|
@code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
|
(and conversely, these routines should usually not be used in plugins
|
(and conversely, these routines should usually not be used in plugins
|
outside of the @code{PLUGIN_GGC_MARKING} event).
|
outside of the @code{PLUGIN_GGC_MARKING} event).
|
|
|
Some plugins may need to add extra GGC root tables, e.g. to handle their own
|
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}
|
@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
|
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
|
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
|
@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
|
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*})
|
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}
|
as @code{user_data}. Running the @code{gengtype -p @var{source-dir}
|
@var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
|
@var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
|
|
|
You should understand the details of memory management inside GCC
|
You should understand the details of memory management inside GCC
|
before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
|
before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
|
or @code{PLUGIN_REGISTER_GGC_CACHES}.
|
or @code{PLUGIN_REGISTER_GGC_CACHES}.
|
|
|
|
|
@section Giving information about a plugin
|
@section Giving information about a plugin
|
|
|
A plugin should give some information to the user about itself. This
|
A plugin should give some information to the user about itself. This
|
uses the following structure:
|
uses the following structure:
|
|
|
@smallexample
|
@smallexample
|
struct plugin_info
|
struct plugin_info
|
@{
|
@{
|
const char *version;
|
const char *version;
|
const char *help;
|
const char *help;
|
@};
|
@};
|
@end smallexample
|
@end smallexample
|
|
|
Such a structure is passed as the @code{user_data} by the plugin's
|
Such a structure is passed as the @code{user_data} by the plugin's
|
init routine using @code{register_callback} with the
|
init routine using @code{register_callback} with the
|
@code{PLUGIN_INFO} pseudo-event and a null callback.
|
@code{PLUGIN_INFO} pseudo-event and a null callback.
|
|
|
@section Registering custom attributes or pragmas
|
@section Registering custom attributes or pragmas
|
|
|
For analysis (or other) purposes it is useful to be able to add custom
|
For analysis (or other) purposes it is useful to be able to add custom
|
attributes or pragmas.
|
attributes or pragmas.
|
|
|
The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
|
The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
|
registration. Use the @code{register_attribute} function to register
|
registration. Use the @code{register_attribute} function to register
|
custom attributes.
|
custom attributes.
|
|
|
@smallexample
|
@smallexample
|
/* Attribute handler callback */
|
/* Attribute handler callback */
|
static tree
|
static tree
|
handle_user_attribute (tree *node, tree name, tree args,
|
handle_user_attribute (tree *node, tree name, tree args,
|
int flags, bool *no_add_attrs)
|
int flags, bool *no_add_attrs)
|
@{
|
@{
|
return NULL_TREE;
|
return NULL_TREE;
|
@}
|
@}
|
|
|
/* Attribute definition */
|
/* Attribute definition */
|
static struct attribute_spec user_attr =
|
static struct attribute_spec user_attr =
|
@{ "user", 1, 1, false, false, false, handle_user_attribute @};
|
@{ "user", 1, 1, false, false, false, handle_user_attribute @};
|
|
|
/* Plugin callback called during attribute registration.
|
/* Plugin callback called during attribute registration.
|
Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
|
Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
|
*/
|
*/
|
static void
|
static void
|
register_attributes (void *event_data, void *data)
|
register_attributes (void *event_data, void *data)
|
@{
|
@{
|
warning (0, G_("Callback to register attributes"));
|
warning (0, G_("Callback to register attributes"));
|
register_attribute (&user_attr);
|
register_attribute (&user_attr);
|
@}
|
@}
|
|
|
@end smallexample
|
@end smallexample
|
|
|
|
|
The @code{PLUGIN_PRAGMAS} callback is called during pragmas
|
The @code{PLUGIN_PRAGMAS} callback is called during pragmas
|
registration. Use the @code{c_register_pragma} or
|
registration. Use the @code{c_register_pragma} or
|
@code{c_register_pragma_with_expansion} functions to register custom
|
@code{c_register_pragma_with_expansion} functions to register custom
|
pragmas.
|
pragmas.
|
|
|
@smallexample
|
@smallexample
|
/* Plugin callback called during pragmas registration. Registered with
|
/* Plugin callback called during pragmas registration. Registered with
|
register_callback (plugin_name, PLUGIN_PRAGMAS,
|
register_callback (plugin_name, PLUGIN_PRAGMAS,
|
register_my_pragma, NULL);
|
register_my_pragma, NULL);
|
*/
|
*/
|
static void
|
static void
|
register_my_pragma (void *event_data, void *data)
|
register_my_pragma (void *event_data, void *data)
|
@{
|
@{
|
warning (0, G_("Callback to register pragmas"));
|
warning (0, G_("Callback to register pragmas"));
|
c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
|
c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
|
@}
|
@}
|
@end smallexample
|
@end smallexample
|
|
|
It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
|
It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
|
your plugin) as the ``space'' argument of your pragma.
|
your plugin) as the ``space'' argument of your pragma.
|
|
|
|
|
@section Recording information about pass execution
|
@section Recording information about pass execution
|
|
|
The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
|
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
|
(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.
|
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
|
Note that this event will only be invoked if the gate check (if
|
applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
|
applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
|
You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
|
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_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
|
@code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_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
|
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.
|
in your plugin(s) in order to get context for the pass execution.
|
|
|
|
|
@section Controlling which passes are being run
|
@section Controlling which passes are being run
|
|
|
After the original gate function for a pass is called, its result
|
After the original gate function for a pass is called, its result
|
- the gate status - is stored as an integer.
|
- the gate status - is stored as an integer.
|
Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
|
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.
|
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.
|
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.
|
You can both read and write the gate status via the passed pointer.
|
|
|
|
|
@section Keeping track of available passes
|
@section Keeping track of available passes
|
|
|
When your plugin is loaded, you can inspect the various
|
When your plugin is loaded, you can inspect the various
|
pass lists to determine what passes are available. However, other
|
pass lists to determine what passes are available. However, other
|
plugins might add new passes. Also, future changes to GCC might cause
|
plugins might add new passes. Also, future changes to GCC might cause
|
generic passes to be added after plugin loading.
|
generic passes to be added after plugin loading.
|
When a pass is first added to one of the pass lists, the event
|
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{PLUGIN_NEW_PASS} is invoked, with the callback parameter
|
@code{gcc_data} pointing to the new pass.
|
@code{gcc_data} pointing to the new pass.
|
|
|
|
|
@section Building GCC plugins
|
@section Building GCC plugins
|
|
|
If plugins are enabled, GCC installs the headers needed to build a
|
If plugins are enabled, GCC installs the headers needed to build a
|
plugin (somewhere in the installation tree, e.g. under
|
plugin (somewhere in the installation tree, e.g. under
|
@file{/usr/local}). In particular a @file{plugin/include} directory
|
@file{/usr/local}). In particular a @file{plugin/include} directory
|
is installed, containing all the header files needed to build plugins.
|
is installed, containing all the header files needed to build plugins.
|
|
|
On most systems, you can query this @code{plugin} directory by
|
On most systems, you can query this @code{plugin} directory by
|
invoking @command{gcc -print-file-name=plugin} (replace if needed
|
invoking @command{gcc -print-file-name=plugin} (replace if needed
|
@command{gcc} with the appropriate program path).
|
@command{gcc} with the appropriate program path).
|
|
|
The following GNU Makefile excerpt shows how to build a simple plugin:
|
The following GNU Makefile excerpt shows how to build a simple plugin:
|
|
|
@smallexample
|
@smallexample
|
GCC=gcc
|
GCC=gcc
|
PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
|
PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
|
PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
|
PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
|
GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
|
GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
|
CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
|
CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
|
|
|
plugin.so: $(PLUGIN_OBJECT_FILES)
|
plugin.so: $(PLUGIN_OBJECT_FILES)
|
$(GCC) -shared $^ -o $@@
|
$(GCC) -shared $^ -o $@@
|
@end smallexample
|
@end smallexample
|
|
|
A single source file plugin may be built with @code{gcc -I`gcc
|
A single source file plugin may be built with @code{gcc -I`gcc
|
-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
|
-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
|
plugin.so}, using backquote shell syntax to query the @file{plugin}
|
plugin.so}, using backquote shell syntax to query the @file{plugin}
|
directory.
|
directory.
|
|
|
Plugins needing to use @command{gengtype} require a GCC build
|
Plugins needing to use @command{gengtype} require a GCC build
|
directory for the same version of GCC that they will be linked
|
directory for the same version of GCC that they will be linked
|
against.
|
against.
|
|
|
