Plugins
*******

Loading Plugins
===============

Plugins are supported on platforms that support -ld -rdynamic.  They are loaded by the compiler using dlopen and invoked at pre-determined locations in the compilation process.

Plugins are loaded with

-fplugin=/path/to/NAME.so -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 -fplugin arguments.

Plugin API
==========

Plugins are activated by the compiler at specific events as defined in gcc-plugin.h.  For each event of interest, the plugin should call register_callback specifying the name of the event and address of the callback function that will handle that event.

Plugin initialization
---------------------

Every plugin should export a function called 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 compile_file right before invoking the parser.  The arguments to plugin_init are:

  * plugin_name: Name of the plugin.

  * argc: Number of arguments specified with -fplugin-arg-....

  * argv: Array of argc key-value pairs.

If initialization fails, plugin_init must return a non-zero value.  Otherwise, it should return 0.

Plugin callbacks
----------------

Callback functions have the following prototype:

     /* 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);

Callbacks can be invoked at the following pre-determined events:

     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_ATTRIBUTES,            /* Called during attribute registration */
       PLUGIN_EVENT_LAST             /* Dummy event used for indexing callback
                                        array.  */
     };

To register a callback, the plugin calls register_callback with the arguments:

  * char *name: Plugin name.

  * enum plugin_event event: The event code.

  * plugin_callback_func callback: The function that handles event.

  * void *user_data: Pointer to plugin-specific data.

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 register_callback with the PLUGIN_PASS_MANAGER_SETUP event and a pointer to a struct plugin_pass object defined as follows

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

       ...
     }

Registering custom attributes
=============================

For analysis purposes it is useful to be able to add custom attributes.

The PLUGIN_ATTRIBUTES callback is called during attribute registration. Use the register_attribute function to register custom attributes.

     /* 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);
     }