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{-ldl
  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 The header @file{gcc-plugin.h} must be the first gcc header to be included.
  34
  35 @subsection Plugin initialization
  36
  37 Every plugin should export a function called @code{plugin_init} that
  38 is called right after the plugin is loaded. This function is
  39 responsible for registering all the callbacks required by the plugin
  40 and do any other required initialization.
  41
  42 This function is called from @code{compile_file} right before invoking
  43 the parser.  The arguments to @code{plugin_init} are:
  44
  45 @itemize @bullet
  46 @item @code{plugin_info}: Plugin invocation information.
  47 @item @code{version}: GCC version.
  48 @end itemize
  49
  50 The @code{plugin_info} struct is defined as follows:
  51
  52 @smallexample
  53 struct plugin_name_args
  54 @{
  55   char *base_name;              /* Short name of the plugin
  56                                    (filename without .so suffix). */
  57   const char *full_name;        /* Path to the plugin as specified with
  58                                    -fplugin=. */
  59   int argc;                     /* Number of arguments specified with
  60                                    -fplugin-arg-.... */
  61   struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
  62   const char *version;          /* Version string provided by plugin. */
  63   const char *help;             /* Help string provided by plugin. */
  64 @}
  65 @end smallexample
  66
  67 If initialization fails, @code{plugin_init} must return a non-zero
  68 value.  Otherwise, it should return 0.
  69
  70 The version of the GCC compiler loading the plugin is described by the
  71 following structure:
  72
  73 @smallexample
  74 struct plugin_gcc_version
  75 @{
  76   const char *basever;
  77   const char *datestamp;
  78   const char *devphase;
  79   const char *revision;
  80   const char *configuration_arguments;
  81 @};
  82 @end smallexample
  83
  84 The function @code{plugin_default_version_check} takes two pointers to
  85 such structure and compare them field by field. It can be used by the
  86 plugin's @code{plugin_init} function.
  87
  88
  89 @subsection Plugin callbacks
  90
  91 Callback functions have the following prototype:
  92
  93 @smallexample
  94 /* The prototype for a plugin callback function.
  95      gcc_data  - event-specific data provided by GCC
  96      user_data - plugin-specific data provided by the plug-in.  */
  97 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
  98 @end smallexample
  99
 100 Callbacks can be invoked at the following pre-determined events:
 101
 102
 103 @smallexample
 104 enum plugin_event
 105 @{
 106   PLUGIN_PASS_MANAGER_SETUP,    /* To hook into pass manager.  */
 107   PLUGIN_FINISH_TYPE,           /* After finishing parsing a type.  */
 108   PLUGIN_FINISH_UNIT,           /* Useful for summary processing.  */
 109   PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE.  */
 110   PLUGIN_FINISH,                /* Called before GCC exits.  */
 111   PLUGIN_INFO,                  /* Information about the plugin. */
 112   PLUGIN_GGC_START,             /* Called at start of GCC Garbage Collection. */
 113   PLUGIN_GGC_MARKING,           /* Extend the GGC marking. */
 114   PLUGIN_GGC_END,               /* Called at end of GGC. */
 115   PLUGIN_REGISTER_GGC_ROOTS,    /* Register an extra GGC root table. */
 116   PLUGIN_ATTRIBUTES,            /* Called during attribute registration */
 117   PLUGIN_EVENT_LAST             /* Dummy event used for indexing callback
 118                                    array.  */
 119 @};
 120 @end smallexample
 121
 122
 123 To register a callback, the plugin calls @code{register_callback} with
 124 the arguments:
 125
 126 @itemize
 127 @item @code{char *name}: Plugin name.
 128 @item @code{enum plugin_event event}: The event code.
 129 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
 130 @item @code{void *user_data}: Pointer to plugin-specific data.
 131 @end itemize
 132
 133 For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, and
 134 PLUGIN_REGISTER_GGC_ROOTS pseudo-events the @code{callback} should be
 135 null, and the @code{user_data} is specific.
 136
 137 @section Interacting with the pass manager
 138
 139 There needs to be a way to add/reorder/remove passes dynamically. This
 140 is useful for both analysis plugins (plugging in after a certain pass
 141 such as CFG or an IPA pass) and optimization plugins.
 142
 143 Basic support for inserting new passes or replacing existing passes is
 144 provided. A plugin registers a new pass with GCC by calling
 145 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
 146 event and a pointer to a @code{struct plugin_pass} object defined as follows
 147
 148 @smallexample
 149 enum pass_positioning_ops
 150 @{
 151   PASS_POS_INSERT_AFTER,  // Insert after the reference pass.
 152   PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
 153   PASS_POS_REPLACE        // Replace the reference pass.
 154 @};
 155
 156 struct plugin_pass
 157 @{
 158   struct opt_pass *pass;            /* New pass provided by the plugin.  */
 159   const char *reference_pass_name;  /* Name of the reference pass for hooking
 160                                        up the new pass.  */
 161   int ref_pass_instance_number;     /* Insert the pass at the specified
 162                                        instance number of the reference pass.  */
 163                                     /* Do it for every instance if it is 0.  */
 164   enum pass_positioning_ops pos_op; /* how to insert the new pass.  */
 165 @};
 166
 167
 168 /* Sample plugin code that registers a new pass.  */
 169 int
 170 plugin_init (struct plugin_name_args *plugin_info,
 171              struct plugin_gcc_version *version)
 172 @{
 173   struct plugin_pass pass_info;
 174
 175   ...
 176
 177   /* Code to fill in the pass_info object with new pass information.  */
 178
 179   ...
 180
 181   /* Register the new pass.  */
 182   register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
 183
 184   ...
 185 @}
 186 @end smallexample
 187
 188
 189 @section Interacting with the GCC Garbage Collector
 190
 191 Some plugins may want to be informed when GGC (the GCC Garbage
 192 Collector) is running. They can register callbacks for the
 193 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
 194 the callback is called with a null @code{gcc_data}) to be notified of
 195 the start or end of the GCC garbage collection.
 196
 197 Some plugins may need to have GGC mark additional data. This can be
 198 done by registering a callback (called with a null @code{gcc_data})
 199 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
 200 @code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
 201 (and conversely, these routines should usually not be used in plugins
 202 outside of the @code{PLUGIN_GGC_MARKING} event).
 203
 204 Some plugins may need to add extra GGC root tables, e.g. to handle
 205 their own @code{GTY}-ed data. This can be done with the
 206 @code{PLUGIN_REGISTER_GGC_ROOTS} pseudo-event with a null callback and
 207 the extra root table as @code{user_data}.  Running the @code{gengtype
 208 -p @var{source-dir} @var{file-list} @var{plugin*.c} ...} utility
 209 generates this extra root table.
 210
 211 You should understand the details of memory management inside GCC
 212 before using @code{PLUGIN_GGC_MARKING} or
 213 @code{PLUGIN_REGISTER_GGC_ROOTS}.
 214
 215
 216 @section Giving information about a plugin
 217
 218 A plugin should give some information to the user about itself. This
 219 uses the following structure:
 220
 221 @smallexample
 222 struct plugin_info
 223 @{
 224   const char *version;
 225   const char *help;
 226 @};
 227 @end smallexample
 228
 229 Such a structure is passed as the @code{user_data} by the plugin's
 230 init routine using @code{register_callback} with the
 231 @code{PLUGIN_INFO} pseudo-event and a null callback.
 232
 233 @section Registering custom attributes
 234
 235 For analysis purposes it is useful to be able to add custom attributes.
 236
 237 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
 238 registration. Use the @code{register_attribute} function to register
 239 custom attributes.
 240
 241 @smallexample
 242 /* Attribute handler callback */
 243 static tree
 244 handle_user_attribute (tree *node, tree name, tree args,
 245                         int flags, bool *no_add_attrs)
 246 @{
 247   return NULL_TREE;
 248 @}
 249
 250 /* Attribute definition */
 251 static struct attribute_spec user_attr =
 252   @{ "user", 1, 1, false,  false, false, handle_user_attribute @};
 253
 254 /* Plugin callback called during attribute registration.
 255 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
 256 */
 257 static void
 258 register_attributes (void *event_data, void *data)
 259 @{
 260   warning (0, G_("Callback to register attributes"));
 261   register_attribute (&user_attr);
 262 @}
 263
 264 @end smallexample
 265
 266
 267 @section Building GCC plugins
 268
 269 If plugins are enabled, GCC installs the headers needed to build a
 270 plugin (somehwere in the installation tree, e.g. under
 271 @file{/usr/local}).  In particular a @file{plugin/include} directory
 272 is installed, containing all the header files needed to build plugins.
 273
 274 On most systems, you can query this @code{plugin} directory by
 275 invoking @command{gcc -print-file-name=plugin} (replace if needed
 276 @command{gcc} with the appropriate program path).
 277
 278 The following GNU Makefile excerpt shows how to build a simple plugin:
 279
 280 @smallexample
 281 GCC=gcc
 282 PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
 283 PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
 284 GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
 285 CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
 286
 287 plugin.so: $(PLUGIN_OBJECT_FILES)
 288    $(GCC) -shared $^ -o $@
 289 @end smallexample
 290
 291 A single source file plugin may be built with @code{gcc -I`gcc
 292 -print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
 293 plugin.so}, using backquote shell syntax to query the @file{plugin}
 294 directory.
 295
 296 Plugins needing to use @command{gengtype} require a GCC build
 297 directory for the same version of GCC that they will be linked
 298 against.