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