2009-12-01 Grigori Fursin <grigori.fursin@inria.fr>

            Joern Rennecke  <amylaar@spamcop.net>

        * cgraphunit.c (plugin.h): Include.
        (ipa_passes): Invoke PLUGIN_ALL_IPA_PASSES_START /
        PLUGIN_ALL_IPA_PASSES_END at start / end of processing.
        * gcc-plugin.h (highlev-plugin-common.h, hashtab.h): Include.
        (enum plugin_event): Define by including plugin.def.
        Last enumerator is now called PLUGIN_EVENT_FIRST_DYNAMIC.
        (plugin_event_name): Change type to const char **.
        (get_event_last, get_named_event_id, unregister_callback): Declare.
        (register_callback): Change type of event argument to int.
        (highlev-plugin-common.h): New file.
        * Makefile.in (GCC_PLUGIN_H): Add highlev-plugin-common.h and
        $(HASHTAB_H)
        (tree-optimize.o passes.o): Depend on $(PLUGIN_H).
        (PLUGIN_HEADERS): Add opts.h, $(PARAMS_H) and plugin.def.
        (s-header-vars): New rule.
        (install-plugin): Depend on s-header-vars.  Install b-header-vars.
        * params.c (get_num_compiler_params): New function.
        * params.h (get_num_compiler_params): Declare.
        * passes.c (plugin.h): Include.
        (make_pass_instance): Invoke PLUGIN_NEW_PASS.
        (do_per_function_toporder, pass_init_dump_file): No longer static.
        (pass_fini_dump_file): Likewise.
        (execute_one_pass): Likewise.  Invoke PLUGIN_OVERRIDE_GATE and
        PLUGIN_PASS_EXECUTION.
        (execute_ipa_pass_list): Invoke PLUGIN_EARLY_GIMPLE_PASSES_START and
        PLUGIN_EARLY_GIMPLE_PASSES_END.
        * plugin.c (plugin_event_name_init): New array, defined by
        including plugin.def.
        (FMT_FOR_PLUGIN_EVENT): Update.
        (plugin_event_name): Change type to const char ** and initialize
        to plugin_event_name_init.
        (event_tab, event_last, event_horizon): New variable.
        (get_event_last): New function.
        (plugin_callbacks_init): New array.
        (plugin_callbacks: Change type to struct callback_info **.
        Initialize to plugin_callbacks_init.
        (htab_event_eq, get_named_event_id, unregister_callback): New function.
        (invoke_plugin_va_callbacks): Likewise.
        (register_callback): Change type of event argument to int.
        Handle new events.  Allow dynamic events.
        (invoke_plugin_callbacks): Likewise.  Return success status.
        (plugins_active_p): Allow dynamic callbacks.
        * plugin.def: New file.
        * plugin.h (invoke_plugin_callbacks): Update prototype.
        (invoke_plugin_va_callbacks): Declare.
        * tree-optimize.c (plugin.h): Include.
        (tree_rest_of_compilation): Invoke PLUGIN_ALL_PASSES_START and
        PLUGIN_ALL_PASSES_END.
        * tree-pass.h (execute_one_pass, pass_init_dump_file): Declare.
        (pass_fini_dump_file, do_per_function_toporder): Likewise.
        * doc/plugin.texi: Document new event types.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@154877 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 61 insertions, 2 deletions

diff --git a/gcc/doc/plugins.texi b/gcc/doc/plugins.texi
index eb1008e8f2c..8aac0f7b65c 100644
--- a/gcc/doc/plugins.texi
+++ b/gcc/doc/plugins.texi
@@ -156,18 +156,42 @@ enum plugin_event
   PLUGIN_ATTRIBUTES,            /* Called during attribute registration */
   PLUGIN_START_UNIT,            /* Called before processing a translation unit.  */
   PLUGIN_PRAGMAS,	        /* Called during pragma registration. */
-  PLUGIN_EVENT_LAST             /* Dummy event used for indexing callback
+  /* 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{enum plugin_event 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{void *user_data}: Pointer to plugin-specific data.
 @end itemize
@@ -337,6 +361,41 @@ 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