Subversion Repositories openrisc_2011-10-31

@c Copyright (c) 2009, 2010 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{-ldl

-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.

The header @file{gcc-plugin.h} must be the first gcc header to be included.

@subsection Plugin license check

Every plugin should define the global symbol @code{plugin_is_GPL_compatible}

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

and exit with the error message:

@smallexample

fatal error: plugin <name> is not licensed under a GPL-compatible license

<name>: undefined symbol: plugin_is_GPL_compatible

compilation terminated

@end smallexample

The type of the symbol is irrelevant.  The compiler merely asserts that

it exists in the global scope.  Something like this is enough:

@smallexample

int plugin_is_GPL_compatible;

@end smallexample

@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_info}: Plugin invocation information.

@item @code{version}: GCC version.

@end itemize

The @code{plugin_info} struct is defined as follows:

@smallexample

struct plugin_name_args

@{

  char *base_name;              /* Short name of the plugin

                                   (filename without .so suffix). */

  const char *full_name;        /* Path to the plugin as specified with

                                   -fplugin=. */

  int argc;                     /* Number of arguments specified with

                                   -fplugin-arg-.... */

  struct plugin_argument *argv; /* Array of ARGC key-value pairs. */

  const char *version;          /* Version string provided by plugin. */

  const char *help;             /* Help string provided by plugin. */

@}

@end smallexample

If initialization fails, @code{plugin_init} must return a non-zero

value.  Otherwise, it should return 0.

The version of the GCC compiler loading the plugin is described by the

following structure:

@smallexample

struct plugin_gcc_version

@{

  const char *basever;

  const char *datestamp;

  const char *devphase;

  const char *revision;

  const char *configuration_arguments;

@};

@end smallexample

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

plugin's @code{plugin_init} function.

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

recommended version check to perform looks like

@smallexample

#include "plugin-version.h"

...

int

plugin_init (struct plugin_name_args *plugin_info,

             struct plugin_gcc_version *version)

@{

  if (!plugin_default_version_check (version, &gcc_version))

    return 1;

@}

@end smallexample

but you can also check the individual fields if you want a less strict check.

@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_PRE_GENERICIZE,        /* Allows to see low level AST in C and C++ frontends.  */

  PLUGIN_FINISH,                /* Called before GCC exits.  */

  PLUGIN_INFO,                  /* Information about the plugin. */

  PLUGIN_GGC_START,             /* Called at start of GCC Garbage Collection. */

  PLUGIN_GGC_MARKING,           /* Extend the GGC marking. */

  PLUGIN_GGC_END,               /* Called at end of GGC. */

  PLUGIN_REGISTER_GGC_ROOTS,    /* Register an extra GGC root table. */

  PLUGIN_REGISTER_GGC_CACHES,   /* Register an extra GGC cache table. */

  PLUGIN_ATTRIBUTES,            /* Called during attribute registration */

  PLUGIN_START_UNIT,            /* Called before processing a translation unit.  */

  PLUGIN_PRAGMAS,               /* Called during pragma registration. */

  /* Called before first pass from all_passes.  */

  PLUGIN_ALL_PASSES_START,

  /* Called after last pass from all_passes.  */

  PLUGIN_ALL_PASSES_END,

  /* Called before first ipa pass.  */

  PLUGIN_ALL_IPA_PASSES_START,

  /* Called after last ipa pass.  */

  PLUGIN_ALL_IPA_PASSES_END,

  /* Allows to override pass gate decision for current_pass.  */

  PLUGIN_OVERRIDE_GATE,

  /* Called before executing a pass.  */

  PLUGIN_PASS_EXECUTION,

  /* Called before executing subpasses of a GIMPLE_PASS in

     execute_ipa_pass_list.  */

  PLUGIN_EARLY_GIMPLE_PASSES_START,

  /* Called after executing subpasses of a GIMPLE_PASS in

     execute_ipa_pass_list.  */

  PLUGIN_EARLY_GIMPLE_PASSES_END,

  /* Called when a pass is first instantiated.  */

  PLUGIN_NEW_PASS,

  PLUGIN_EVENT_FIRST_DYNAMIC    /* Dummy event used for indexing callback

                                   array.  */

@};

@end smallexample

In addition, plugins can also look up the enumerator of a named event,

and / or generate new events dynamically, by calling the function

@code{get_named_event_id}.

To register a callback, the plugin calls @code{register_callback} with

the arguments:

@itemize

@item @code{char *name}: Plugin name.

@item @code{int 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

For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS

and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be

null, and the @code{user_data} is specific.

When the PLUGIN_PRAGMAS event is triggered (with a null

pointer as data from GCC), plugins may register their own pragmas

using functions like @code{c_register_pragma} or

@code{c_register_pragma_with_expansion}.

@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 register_pass_info} 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 register_pass_info

@{

  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 (struct plugin_name_args *plugin_info,

             struct plugin_gcc_version *version)

@{

  struct register_pass_info pass_info;

  ...

  /* Code to fill in the pass_info object with new pass information.  */

  ...

  /* Register the new pass.  */

  register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);

  ...

@}

@end smallexample

@section Interacting with the GCC Garbage Collector

Some plugins may want to be informed when GGC (the GCC Garbage

Collector) is running. They can register callbacks for the

@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 start or end of the GCC garbage collection.

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})

for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the

@code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro

(and conversely, these routines should usually not be used in plugins

outside of the @code{PLUGIN_GGC_MARKING} event).

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}

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

@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

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}

@var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.

You should understand the details of memory management inside GCC

before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}

or @code{PLUGIN_REGISTER_GGC_CACHES}.

@section Giving information about a plugin

A plugin should give some information to the user about itself. This

uses the following structure:

@smallexample

struct plugin_info

@{

  const char *version;

  const char *help;

@};

@end smallexample

Such a structure is passed as the @code{user_data} by the plugin's

init routine using @code{register_callback} with the

@code{PLUGIN_INFO} pseudo-event and a null callback.

@section Registering custom attributes or pragmas

For analysis (or other) purposes it is useful to be able to add custom

attributes or pragmas.

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

The @code{PLUGIN_PRAGMAS} callback is called during pragmas

registration. Use the @code{c_register_pragma} or

@code{c_register_pragma_with_expansion} functions to register custom

pragmas.

@smallexample

/* Plugin callback called during pragmas registration. Registered with

     register_callback (plugin_name, PLUGIN_PRAGMAS,

                        register_my_pragma, NULL);

*/

static void

register_my_pragma (void *event_data, void *data)

@{

  warning (0, G_("Callback to register pragmas"));

  c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);

@}

@end smallexample

It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying

your plugin) as the ``space'' argument of your pragma.

@section Recording information about pass execution

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

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

applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.

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_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},

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.

@section Controlling which passes are being run

After the original gate function for a pass is called, its result

- the gate status - is stored as an integer.

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.

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.

@section Keeping track of available passes

When your plugin is loaded, you can inspect the various

pass lists to determine what passes are available.  However, other

plugins might add new passes.  Also, future changes to GCC might cause

generic passes to be added after plugin loading.

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{gcc_data} pointing to the new pass.

@section Building GCC plugins

If plugins are enabled, GCC installs the headers needed to build a

plugin (somewhere in the installation tree, e.g. under

@file{/usr/local}).  In particular a @file{plugin/include} directory

is installed, containing all the header files needed to build plugins.

On most systems, you can query this @code{plugin} directory by

invoking @command{gcc -print-file-name=plugin} (replace if needed

@command{gcc} with the appropriate program path).

The following GNU Makefile excerpt shows how to build a simple plugin:

@smallexample

GCC=gcc

PLUGIN_SOURCE_FILES= plugin1.c plugin2.c

PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))

GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)

CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2

plugin.so: $(PLUGIN_OBJECT_FILES)

   $(GCC) -shared $^ -o $@@

@end smallexample

A single source file plugin may be built with @code{gcc -I`gcc

-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o

plugin.so}, using backquote shell syntax to query the @file{plugin}

directory.

Plugins needing to use @command{gengtype} require a GCC build

directory for the same version of GCC that they will be linked

against.