[multiple changes]

2009-04-14  Diego Novillo  <dnovillo@google.com>
	    Le-Chun Wu  <lcwu@google.com>

	* configure.ac: Add --enable-plugin support.
	Define ENABLE_PLUGIN and PLUGINLIBS when specified.
	* Makefile.in (PLUGIN_H): Define.
	Export ENABLE_PLUGIN and GMPINC to site.exp.
	Add PLUGINLIBS to link command.
	Add/modify dependencies for plugin.o and files including plugin.h.
	(plugin.o): New.
	* config.in: Regenerate.
	
	* opts.c (common_handle_option): Handle OPT_fplugin_ and
	OPT_fplugin_arg_.

2009-04-14  Le-Chun Wu  <lcwu@google.com>

	* tree-pass.h (register_one_dump_file): Add a prototype for
	register_one_dump_file.
	* toplev.c (compile_file): Call initialize_plugins.
	(do_compile): Call invoke_plugin_callbacks.
	(toplev_main): Call invoke_plugin_callbacks.
	* common.opt: Add -fplugin= and -fplugin-arg-.
	* gcc-plugin.h: New public header file for plugins to include.
	* plugin.c: New source file.
	* plugin.h: New internal header file.
	* passes.c (register_one_dump_file): Make it external.
	
	* c-parser.c (c_parser_declspecs): Call invoke_plugin_callbacks.

2009-04-14  Diego Novillo  <dnovillo@google.com>

	* doc/plugins.texi: New.
	* doc/gccint.texi: Add reference to Plugins chapter.
	* doc/invoke.texi: Document -fplugin and -fplugin-arg
	* diagnostic.c (diagnostic_report_diagnostic): Warn about
	loaded plugins, if any.
	* timevar.def (TV_PLUGIN_INIT): Define.
	(TV_PLUGIN_RUN): Define.
	* plugin.c: Include timevar.h
	(plugins_active_p): New.
	(dump_active_plugins): New.
	(debug_active_plugins): New.


cp/ChangeLog

2009-04-14  Le-Chun Wu  <lcwu@google.com>

	* Make-lang.in: Modify dependencies of files including plugin.h.
	* decl.c (finish_function): Call invoke_plugin_callbacks.
	* parser.c (cp_parser_type_specifier): Call invoke_plugin_callbacks.

From-SVN: r146059

1 files changed, 137 insertions, 0 deletions

diff --git a/gcc/doc/plugins.texi b/gcc/doc/plugins.texi
new file mode 100644
index 0000000..7c3fbed
--- /dev/null
+++ b/gcc/doc/plugins.texi
@@ -0,0 +1,137 @@
+@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{-ld
+-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.
+
+@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_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.
+@end itemize
+
+If initialization fails, @code{plugin_init} must return a non-zero
+value.  Otherwise, it should return 0.
+
+@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_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE.  */
+  PLUGIN_FINISH,                /* Called before GCC exits.  */
+  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:
+
+@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
+
+
+@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 plugin_pass} 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 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.  */
+@};
+
+
+/* Sample plugin code that registers a new pass.  */
+int
+plugin_init (const char *plugin_name, int argc, struct plugin_argument *argv)
+@{
+  struct plugin_pass pass_info;
+
+  ...
+
+  /* Code to fill in the pass_info object with new pass information.  */
+
+  ...
+
+  /* Register the new pass.  */
+  register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
+
+  ...
+@}
+@end smallexample