gcc/doc/gccint/plugins/interacting-with-the-pass-manager.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _plugins-pass:
   7
   8 Interacting with the pass manager
   9 *********************************
  10
  11 There needs to be a way to add/reorder/remove passes dynamically. This
  12 is useful for both analysis plugins (plugging in after a certain pass
  13 such as CFG or an IPA pass) and optimization plugins.
  14
  15 Basic support for inserting new passes or replacing existing passes is
  16 provided. A plugin registers a new pass with GCC by calling
  17 ``register_callback`` with the ``PLUGIN_PASS_MANAGER_SETUP``
  18 event and a pointer to a ``struct register_pass_info`` object defined as follows
  19
  20 .. code-block:: c++
  21
  22   enum pass_positioning_ops
  23   {
  24     PASS_POS_INSERT_AFTER,  // Insert after the reference pass.
  25     PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
  26     PASS_POS_REPLACE        // Replace the reference pass.
  27   };
  28
  29   struct register_pass_info
  30   {
  31     struct opt_pass *pass;            /* New pass provided by the plugin.  */
  32     const char *reference_pass_name;  /* Name of the reference pass for hooking
  33                                          up the new pass.  */
  34     int ref_pass_instance_number;     /* Insert the pass at the specified
  35                                          instance number of the reference pass.  */
  36                                       /* Do it for every instance if it is 0.  */
  37     enum pass_positioning_ops pos_op; /* how to insert the new pass.  */
  38   };
  39
  40   /* Sample plugin code that registers a new pass.  */
  41   int
  42   plugin_init (struct plugin_name_args *plugin_info,
  43                struct plugin_gcc_version *version)
  44   {
  45     struct register_pass_info pass_info;
  46
  47     ...
  48
  49     /* Code to fill in the pass_info object with new pass information.  */
  50
  51     ...
  52
  53     /* Register the new pass.  */
  54     register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
  55
  56     ...
  57   }