--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gcc/doc/plugins.texi	Fri Feb 12 23:39:51 2010 +0900
@@ -0,0 +1,430 @@
+@c Copyright (c) 2009 Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node Plugins
+@chapter Plugins
+@cindex Plugins
+
+@section Loading Plugins
+
+Plugins are supported on platforms that support @option{-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.