gcc/doc/plugins.texi

   1 @c Copyright (c) 2009 Free Software Foundation, Inc.
   2 @c Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Plugins
   7 @chapter Plugins
   8 @cindex Plugins
   9
  10 @section Loading Plugins
  11
  12 Plugins are supported on platforms that support @option{-ld
  13 -rdynamic}.  They are loaded by the compiler using @code{dlopen}
  14 and invoked at pre-determined locations in the compilation
  15 process.
  16
  17 Plugins are loaded with
  18
  19 @option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
  20
  21 The plugin arguments are parsed by GCC and passed to respective
  22 plugins as key-value pairs. Multiple plugins can be invoked by
  23 specifying multiple @option{-fplugin} arguments.
  24
  25
  26 @section Plugin API
  27
  28 Plugins are activated by the compiler at specific events as defined in
  29 @file{gcc-plugin.h}.  For each event of interest, the plugin should
  30 call @code{register_callback} specifying the name of the event and
  31 address of the callback function that will handle that event.
  32
  33 @subsection Plugin initialization
  34
  35 Every plugin should export a function called @code{plugin_init} that
  36 is called right after the plugin is loaded. This function is
  37 responsible for registering all the callbacks required by the plugin
  38 and do any other required initialization.
  39
  40 This function is called from @code{compile_file} right before invoking
  41 the parser.  The arguments to @code{plugin_init} are:
  42
  43 @itemize @bullet
  44 @item @code{plugin_name}: Name of the plugin.
  45 @item @code{argc}: Number of arguments specified with @option{-fplugin-arg-...}.
  46 @item @code{argv}: Array of @code{argc} key-value pairs.
  47 @end itemize
  48
  49 If initialization fails, @code{plugin_init} must return a non-zero
  50 value.  Otherwise, it should return 0.
  51
  52 @subsection Plugin callbacks
  53
  54 Callback functions have the following prototype:
  55
  56 @smallexample
  57 /* The prototype for a plugin callback function.
  58      gcc_data  - event-specific data provided by GCC
  59      user_data - plugin-specific data provided by the plug-in.  */
  60 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
  61 @end smallexample
  62
  63 Callbacks can be invoked at the following pre-determined events:
  64
  65
  66 @smallexample
  67 enum plugin_event
  68 @{
  69   PLUGIN_PASS_MANAGER_SETUP,    /* To hook into pass manager.  */
  70   PLUGIN_FINISH_TYPE,           /* After finishing parsing a type.  */
  71   PLUGIN_FINISH_UNIT,           /* Useful for summary processing.  */
  72   PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE.  */
  73   PLUGIN_FINISH,                /* Called before GCC exits.  */
  74   PLUGIN_ATTRIBUTES,            /* Called during attribute registration */
  75   PLUGIN_EVENT_LAST             /* Dummy event used for indexing callback
  76                                    array.  */
  77 @};
  78 @end smallexample
  79
  80 To register a callback, the plugin calls @code{register_callback} with the arguments:
  81
  82 @itemize
  83 @item @code{char *name}: Plugin name.
  84 @item @code{enum plugin_event event}: The event code.
  85 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
  86 @item @code{void *user_data}: Pointer to plugin-specific data.
  87 @end itemize
  88
  89
  90 @section Interacting with the pass manager
  91
  92 There needs to be a way to add/reorder/remove passes dynamically. This
  93 is useful for both analysis plugins (plugging in after a certain pass
  94 such as CFG or an IPA pass) and optimization plugins.
  95
  96 Basic support for inserting new passes or replacing existing passes is
  97 provided. A plugin registers a new pass with GCC by calling
  98 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
  99 event and a pointer to a @code{struct plugin_pass} object defined as follows
 100
 101 @smallexample
 102 enum pass_positioning_ops
 103 @{
 104   PASS_POS_INSERT_AFTER,  // Insert after the reference pass.
 105   PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
 106   PASS_POS_REPLACE        // Replace the reference pass.
 107 @};
 108
 109 struct plugin_pass
 110 @{
 111   struct opt_pass *pass;            /* New pass provided by the plugin.  */
 112   const char *reference_pass_name;  /* Name of the reference pass for hooking
 113                                        up the new pass.  */
 114   int ref_pass_instance_number;     /* Insert the pass at the specified
 115                                        instance number of the reference pass.  */
 116                                     /* Do it for every instance if it is 0.  */
 117   enum pass_positioning_ops pos_op; /* how to insert the new pass.  */
 118 @};
 119
 120
 121 /* Sample plugin code that registers a new pass.  */
 122 int
 123 plugin_init (const char *plugin_name, int argc, struct plugin_argument *argv)
 124 @{
 125   struct plugin_pass pass_info;
 126
 127   ...
 128
 129   /* Code to fill in the pass_info object with new pass information.  */
 130
 131   ...
 132
 133   /* Register the new pass.  */
 134   register_callback (plugin_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
 135
 136   ...
 137 @}
 138 @end smallexample
 139 @section Registering custom attributes
 140
 141 For analysis purposes it is useful to be able to add custom attributes.
 142
 143 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
 144 registration. Use the @code{register_attribute} function to register
 145 custom attributes.
 146
 147 @smallexample
 148 /* Attribute handler callback */
 149 static tree
 150 handle_user_attribute (tree *node, tree name, tree args,
 151                         int flags, bool *no_add_attrs)
 152 @{
 153   return NULL_TREE;
 154 @}
 155
 156 /* Attribute definition */
 157 static struct attribute_spec user_attr =
 158   @{ "user", 1, 1, false,  false, false, handle_user_attribute @};
 159
 160 /* Plugin callback called during attribute registration.
 161 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
 162 */
 163 static void
 164 register_attributes (void *event_data, void *data)
 165 @{
 166   warning (0, G_("Callback to register attributes"));
 167   register_attribute (&user_attr);
 168 @}
 169
 170 @end smallexample