gcc/optinfo.h

   1 /* Optimization information.
   2    Copyright (C) 2018-2024 Free Software Foundation, Inc.
   3    Contributed by David Malcolm <dmalcolm@redhat.com>.
   4
   5 This file is part of GCC.
   6
   7 GCC is free software; you can redistribute it and/or modify it under
   8 the terms of the GNU General Public License as published by the Free
   9 Software Foundation; either version 3, or (at your option) any later
  10 version.
  11
  12 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GCC; see the file COPYING3.  If not see
  19 <http://www.gnu.org/licenses/>.  */
  20
  21 #ifndef GCC_OPTINFO_H
  22 #define GCC_OPTINFO_H
  23
  24 /* This header uses std::unique_ptr, but <memory> can't be directly
  25    included due to issues with macros.  Hence <memory> must be included
  26    from system.h by defining INCLUDE_MEMORY in any source file using
  27    optinfo.h.  */
  28
  29 #ifndef INCLUDE_MEMORY
  30 # error "You must define INCLUDE_MEMORY before including system.h to use optinfo.h"
  31 #endif
  32
  33 /* An "optinfo" is a bundle of information describing part of an
  34    optimization, which can be emitted to zero or more of several
  35    destinations, such as:
  36
  37    * saved to a file as an "optimization record"
  38
  39    They are generated in response to calls to the "dump_*" API in
  40    dumpfile.h; repeated calls to the "dump_*" API are consolidated
  41    into a pending optinfo instance, with a "dump_*_loc" starting a new
  42    optinfo instance.
  43
  44    The data sent to the dump calls are captured within the pending optinfo
  45    instance as a sequence of optinfo_items.  For example, given:
  46
  47       if (dump_enabled_p ())
  48         {
  49           dump_printf_loc (MSG_MISSED_OPTIMIZATION, vect_location,
  50                            "not vectorized: live stmt not supported: ");
  51           dump_gimple_stmt (MSG_MISSED_OPTIMIZATION, TDF_SLIM, stmt, 0);
  52         }
  53
  54    the "dump_printf_loc" call begins a new optinfo containing two items:
  55    (1) a text item containing "not vectorized: live stmt not supported: "
  56    (2) a gimple item for "stmt"
  57
  58    Dump destinations are thus able to access rich metadata about the
  59    items when the optinfo is emitted to them, rather than just having plain
  60    text.  For example, when saving the above optinfo to a file as an
  61    "optimization record", the record could capture the source location of
  62    "stmt" above, rather than just its textual form.
  63
  64    The currently pending optinfo is emitted and deleted:
  65    * each time a "dump_*_loc" call occurs (which starts the next optinfo), or
  66    * when the dump files are changed (at the end of a pass)
  67
  68    Dumping to an optinfo instance is non-trivial (due to building optinfo_item
  69    instances), so all usage should be guarded by
  70
  71      if (optinfo_enabled_p ())
  72
  73    which is off by default.  */
  74
  75
  76 /* Forward decls.  */
  77 class opt_pass;
  78 class optinfo_item;
  79
  80 /* Return true if any of the active optinfo destinations make use
  81    of inlining information.
  82    (if true, then the information is preserved).  */
  83
  84 extern bool optinfo_wants_inlining_info_p ();
  85
  86 /* The various kinds of optinfo.  */
  87
  88 enum optinfo_kind
  89 {
  90   OPTINFO_KIND_SUCCESS,
  91   OPTINFO_KIND_FAILURE,
  92   OPTINFO_KIND_NOTE,
  93   OPTINFO_KIND_SCOPE
  94 };
  95
  96 extern const char *optinfo_kind_to_string (enum optinfo_kind kind);
  97
  98 class dump_context;
  99
 100 /* A bundle of information describing part of an optimization.  */
 101
 102 class optinfo
 103 {
 104   friend class dump_context;
 105
 106  public:
 107   optinfo (const dump_location_t &loc,
 108            enum optinfo_kind kind,
 109            opt_pass *pass)
 110   : m_loc (loc), m_kind (kind), m_pass (pass), m_items ()
 111   {}
 112   ~optinfo ();
 113
 114   const dump_location_t &
 115   get_dump_location () const { return m_loc; }
 116
 117   const dump_user_location_t &
 118   get_user_location () const { return m_loc.get_user_location (); }
 119
 120   const dump_impl_location_t &
 121   get_impl_location () const { return m_loc.get_impl_location (); }
 122
 123   enum optinfo_kind get_kind () const { return m_kind; }
 124   opt_pass *get_pass () const { return m_pass; }
 125   unsigned int num_items () const { return m_items.length (); }
 126   const optinfo_item *get_item (unsigned int i) const { return m_items[i]; }
 127
 128   location_t get_location_t () const { return m_loc.get_location_t (); }
 129   profile_count get_count () const { return m_loc.get_count (); }
 130
 131   void add_item (std::unique_ptr<optinfo_item> item);
 132
 133   void emit_for_opt_problem () const;
 134
 135  private:
 136   /* Pre-canned ways of manipulating the optinfo, for use by friend class
 137      dump_context.  */
 138   void handle_dump_file_kind (dump_flags_t);
 139
 140  private:
 141   dump_location_t m_loc;
 142   enum optinfo_kind m_kind;
 143   opt_pass *m_pass;
 144   auto_vec <optinfo_item *> m_items;
 145 };
 146
 147 /* An enum for discriminating between different kinds of optinfo_item.  */
 148
 149 enum optinfo_item_kind
 150 {
 151   OPTINFO_ITEM_KIND_TEXT,
 152   OPTINFO_ITEM_KIND_TREE,
 153   OPTINFO_ITEM_KIND_GIMPLE,
 154   OPTINFO_ITEM_KIND_SYMTAB_NODE
 155 };
 156
 157 /* An item within an optinfo.  */
 158
 159 class optinfo_item
 160 {
 161  public:
 162   optinfo_item (enum optinfo_item_kind kind, location_t location,
 163                 char *text);
 164   ~optinfo_item ();
 165
 166   enum optinfo_item_kind get_kind () const { return m_kind; }
 167   location_t get_location () const { return m_location; }
 168   const char *get_text () const { return m_text; }
 169
 170  private:
 171   /* Metadata (e.g. for optimization records).  */
 172   enum optinfo_item_kind m_kind;
 173   location_t m_location;
 174
 175   /* The textual form of the item, owned by the item.  */
 176   char *m_text;
 177 };
 178
 179 #endif /* #ifndef GCC_OPTINFO_H */