Index: gcc/doc/plugins.texi
===================================================================
--- gcc/doc/plugins.texi	(revision 147322)
+++ gcc/doc/plugins.texi	(working copy)
@@ -1,4 +1,4 @@
-@c Copyright (c) 2009 Free Software Foundation, Inc.
+on@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.
@@ -11,46 +11,91 @@
 
 Plugins are supported on platforms that support @option{-ld
 -rdynamic}.  They are loaded by the compiler using @code{dlopen}
-and invoked at pre-determined locations in the compilation
-process.
+and invoked during the compilation process.
 
 Plugins are loaded with 
 
-@option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
+@option{-fplugin=/path/to/NAME.so}
 
-The plugin arguments are parsed by GCC and passed to respective
-plugins as key-value pairs. Multiple plugins can be invoked by
+Multiple plugins can be invoked by
 specifying multiple @option{-fplugin} arguments.
 
+Command arguments are passed to plugins using
 
+@option{-fplugin-arg-NAME-<key1>[=<value1>]}
+
+Note that the name of the plugin is embedded in the argument, to
+determine which arguments are passed to which plugin. The plugin
+arguments are parsed by GCC and passed to the plugin as key-value pairs.
+
+So given the following command line arguments:
+@smallexample
+-fplugin=myoptimiser.so -fplugin=mysanitychecker -fplugin-arg-myopmtimiser-enable=yes \
+-fplugin-arg-myoptimiser-level=3 -fplugin-arg-mysanitychecker-enable=no
+@end smallexample
+
+the myoptimiser plugin will be passed enable=yes and level=3, and the mychecker
+plugin will be passed enable=no.
+
 @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.
+There are essentially three parts to the plugin API:
+@itemize @bullet
 
+@item
+The plugin initialization. The plugin needs to be registered with gcc, and
+to specify where it should be called into.
+
+@item
+The event-based callbacks. Plugins can receive callbacks at certain points.
+
+@item
+The pass execution. Plugins can perform actions as a seperate pass over
+the processed file (e.g. the GIMPLE state).
+
+@end itemize
+
+The main header for the plugin API is @file{gcc-version.h}. Consider reading
+that header in conjunction with this section.
+
 @subsection Plugin initialization
 
-Every plugin should export a function called @code{plugin_init} that
+Every plugin must export a function named @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:
+the parser. The function signature for @code{plugin_init} is:
+@smallexample
+typedef int (*plugin_init_func) (const char *@var{plugin_name},
+                                 struct plugin_gcc_version *@var{version},
+                                 int @var{argc}, struct plugin_argument *@var{argv});
+@end smallexample
 
+The arguments to @code{plugin_init} are:
 @itemize @bullet
-@item @code{plugin_name}: Name of the plugin.
-@item @code{argc}: Number of arguments specified with @option{-fplugin-arg-...}.
-@item @code{argv}: Array of @code{argc} key-value pairs.
+@item @var{plugin_name}: Name of the plugin.
+@item @var{version}: The plugin_gcc_version of the plugin itself
+@item @var{argc}: Number of arguments specified with @option{-fplugin-arg-...}.
+@item @var{argv}: Array of @var{argc} key-value pairs.
 @end itemize
 
 If initialization fails, @code{plugin_init} must return a non-zero
-value.  Otherwise, it should return 0.
+value.  Otherwise, @code{plugin_init} should return 0.
 
+Here is an example plugin, showing just the initialization code:
+@smallexample
+@include plugin_example.c
+@end smallexample
+
 @subsection Plugin callbacks
 
+Plugins can be 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.
+
 Callback functions have the following prototype:
 
 @smallexample
@@ -62,7 +107,6 @@
 
 Callbacks can be invoked at the following pre-determined events:
 
-
 @smallexample
 enum plugin_event
 @{
@@ -71,67 +115,107 @@
   PLUGIN_FINISH_UNIT,           /* Useful for summary processing.  */
   PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE.  */
   PLUGIN_FINISH,                /* Called before GCC exits.  */
+  PLUGIN_INFO,                  /* Information about the plugin */
   PLUGIN_EVENT_LAST             /* Dummy event used for indexing callback
                                    array.  */
 @};
 @end smallexample
 
-To register a callback, the plugin calls @code{register_callback} with the arguments:
+To register a callback, the plugin calls @code{register_callback}. The
+@code{register_callback} function has the following signature:
 
-@itemize
-@item @code{char *name}: Plugin name.
-@item @code{enum plugin_event 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
+@smallexample
+/* Called from the plugin's initialization code. Register a single callback.
+   This function can be called multiple times.
 
+   PLUGIN_NAME - display name for this plugin
+   EVENT       - which event the callback is for
+   CALLBACK    - the callback to be called at the event
+   USER_DATA   - plugin-provided data   */
 
+extern void register_callback (const char *plugin_name,
+                               enum plugin_event event,
+                               plugin_callback_func callback,
+                               void *user_data);
+@end smallexample
+
+Here is an example of how to register a callback:
+
+@smallexample
+/* Register a callback for the end-of-file handler */
+register_callback (plugin_name, PLUGIN_FINISH_UNIT, handle_end_of_compilation_unit, NULL);
+@end smallexample
+
 @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.
+In addition to getting callbacks at key events during a pass, a plugin
+can register a new pass, or replace an existing pass. Adding a new pass was shown
+above, however the example above did not use the gate or execute members. By
+registering an execute fuction, we can iterate over (and optionally modify) the
+the internal state as part of a pass within the plugin. @xref{Passes}.
 
-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 plugin_pass} object defined as follows
-
 @smallexample
-enum pass_positioning_ops
+static unsigned int example_exec( void )
 @{
-  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.
-@};
+	gimple_stmt_iterator gsi;
+	basic_block bb;
 
-struct plugin_pass
-@{
-  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.  */
-@};
+	FOR_EACH_BB (bb) @{
+		for (gsi = gsi_start_bb (bb); !gsi_end_p (gsi); gsi_next (&gsi)) @{
+			do_something_with_statement( gsi_stmt( gsi ) );
+		@}
+	@}
 
+	return 0;
+@}
 
-/* Sample plugin code that registers a new pass.  */
-int
-plugin_init (const char *plugin_name, int argc, struct plugin_argument *argv)
+/* Pass gate function. Currently always returns true.  */
+static bool example_gate( void )
 @{
-  struct plugin_pass pass_info;
+	return true;
+@}
 
-  ...
+static struct gimple_opt_pass pass_plugin_example =
+@{
+	@{
+		GIMPLE_PASS,
+		"plugin_example",              /* name */
+		example_gate,                  /* gate */
+		example_exec,                  /* execute */
+		NULL,                          /* sub */
+		NULL,                          /* next */
+		0,                             /* static_pass_number */
+		0,                             /* tv_id */
+		PROP_cfg,                      /* properties_required */
+		0,                             /* properties_provided */
+		0,                             /* properties_destroyed */
+		0,                             /* todo_flags_start */
+		TODO_dump_func                 /* todo_flags_finish */
+	@}
+@};
+@end smallexample
 
-  /* Code to fill in the pass_info object with new pass information.  */
+@section Build Hints
 
-  ...
+A plugin may need to use some GCC additional headers. Certain GCC headers will
+behave differently depending on pre-processor definitions. In particular, the
+@code{IN_GCC} define may be required for certain definitions to be visible.
 
-  /* Register the new pass.  */
-  register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
+Here is a set of @code{#include} lines that may be useful in a plugin that
+works on GIMPLE form.
 
-  ...
-@}
+@smallexample
+#include "config.h"
+#define IN_GCC 1
+#include "system.h"
+#include "coretypes.h"
+#include "tm.h"
+#include "toplev.h"
+#include "basic-block.h"
+#include "gimple.h"
+#include "tree.h"
+#include "tree-pass.h"
+#include "intl.h"
+#include "gcc-plugin.h"
 @end smallexample
+
Index: gcc/doc/plugin_example.c
===================================================================
--- gcc/doc/plugin_example.c	(revision 0)
+++ gcc/doc/plugin_example.c	(revision 0)
@@ -0,0 +1,79 @@
+/* A sample plugin example that shows how to use the GCC plugin mechanism.  */
+
+
+#include "config.h"
+#include "system.h"
+#include "tree.h"
+#include "tree-pass.h"
+#include "intl.h"
+#include "gcc-plugin.h"
+
+static struct gimple_opt_pass pass_plugin_example =
+@{
+	@{
+		GIMPLE_PASS,
+		"plugin_example",              /* name */
+		NULL,                          /* gate */
+		NULL,                          /* execute */
+		NULL,                          /* sub */
+		NULL,                          /* next */
+		0,                             /* static_pass_number */
+		0,                             /* tv_id */
+		PROP_cfg,                      /* properties_required */
+		0,                             /* properties_provided */
+		0,                             /* properties_destroyed */
+		0,                             /* todo_flags_start */
+		TODO_dump_func                 /* todo_flags_finish */
+	@}
+@};
+
+/* Initialization function that GCC calls. This plugin takes an argument
+   that specifies the name of the reference pass and an instance number,
+   both of which determine where the plugin pass should be inserted.
+*/
+int plugin_init( const char *plugin_name, struct plugin_gcc_version *version, int argc, struct plugin_argument *argv )
+@{
+	struct plugin_pass	pass_info;
+	bool			enable = true;
+	int 			opt_level = 0;
+	int			i;
+	struct plugin_info info = @{ "0.0a",  "plugin_example help should go here" @};
+
+
+	/* Process the plugin arguments. This plugin takes the following arguments:
+	   enable=[yes|no] and optimisation_level=<NUM>.  */
+	for ( i = 0; i < argc; ++i ) @{
+		if ( strcmp (argv[i].key, "enable" ) == 0 ) @{
+			if ( strcmp( argv[i].value, "yes" ) == 0 ) @{
+				enable = true;
+			@} else if ( strcmp( argv[i].value, "no" ) == 0 ) @{
+				enable = false;
+			@} else @{
+				/* Not "yes" or "no", so complain */
+				warning( 0, G_("option '-fplugin-arg-%s-enable' accepts \"yes\" or \"no\""), plugin_name);
+			@}
+		@} else if ( strcmp (argv[i].key, "optimisation_level" ) == 0 )  @{
+			if ( argv[i].value ) @{
+				opt_level = strtol( argv[i].value, NULL, 0 );
+			@} else @{
+				warning (0, G_("option '-fplugin-arg-%s-optimisation_level' requires an integer value"), plugin_name);
+			@}
+		@} else @{
+			warning (0, G_("plugin %qs: unrecognized argument %qs ignored"), plugin_name, argv[i].key);
+		@}
+	@}
+
+	/* Set up the pass information. This controls where the plugin is inserted in gcc's processing */
+	pass_info.pass = &pass_plugin_example.pass; /* static structure defined above */
+	pass_info.reference_pass_name = "ssa";      /* other passes could be used */
+	pass_info.ref_pass_instance_number = 0;     /* which pass named "ssa" do we mean - zero means every one */
+	pass_info.pos_op = PASS_POS_INSERT_AFTER;   /* can be before, after or replace. see @code{enum pass_positioning_ops} */
+
+	/* Register a callback for the pass_info setup */
+	register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
+
+	/* Register a callback for our meta-data (version and help information) */
+	register_callback (plugin_name, PLUGIN_INFO, NULL, &info);
+
+	return 0;
+@}