gcc/diagnostic-path.h

   1 /* Paths through the code associated with a diagnostic.
   2    Copyright (C) 2019-2023 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_DIAGNOSTIC_PATH_H
  22 #define GCC_DIAGNOSTIC_PATH_H
  23
  24 #include "diagnostic.h" /* for ATTRIBUTE_GCC_DIAG.  */
  25 #include "diagnostic-event-id.h"
  26
  27 /* A diagnostic_path is an optional additional piece of metadata associated
  28    with a diagnostic (via its rich_location).
  29
  30    It describes a sequence of events predicted by the compiler that
  31    lead to the problem occurring, with their locations in the user's source,
  32    and text descriptions.
  33
  34    For example, the following error has a 3-event path:
  35
  36      test.c: In function 'demo':
  37      test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which
  38        requires a non-NULL parameter
  39         29 |     PyList_Append(list, item);
  40            |     ^~~~~~~~~~~~~~~~~~~~~~~~~
  41        'demo': events 1-3
  42           |
  43           |   25 |   list = PyList_New(0);
  44           |      |          ^~~~~~~~~~~~~
  45           |      |          |
  46           |      |          (1) when 'PyList_New' fails, returning NULL
  47           |   26 |
  48           |   27 |   for (i = 0; i < count; i++) {
  49           |      |   ~~~
  50           |      |   |
  51           |      |   (2) when 'i < count'
  52           |   28 |     item = PyLong_FromLong(random());
  53           |   29 |     PyList_Append(list, item);
  54           |      |     ~~~~~~~~~~~~~~~~~~~~~~~~~
  55           |      |     |
  56           |      |     (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
  57           |
  58
  59     The diagnostic-printing code has consolidated the path into a single
  60     run of events, since all the events are near each other and within the same
  61     function; more complicated examples (such as interprocedural paths)
  62     might be printed as multiple runs of events.  */
  63
  64 /* Abstract base classes, describing events within a path, and the paths
  65    themselves.  */
  66
  67 /* One event within a diagnostic_path.  */
  68
  69 class diagnostic_event
  70 {
  71  public:
  72   /* Enums for giving a sense of what this event means.
  73      Roughly corresponds to SARIF v2.1.0 section 3.38.8.  */
  74   enum verb
  75   {
  76     VERB_unknown,
  77
  78     VERB_acquire,
  79     VERB_release,
  80     VERB_enter,
  81     VERB_exit,
  82     VERB_call,
  83     VERB_return,
  84     VERB_branch,
  85
  86     VERB_danger
  87   };
  88   enum noun
  89   {
  90     NOUN_unknown,
  91
  92     NOUN_taint,
  93     NOUN_sensitive, // this one isn't in SARIF v2.1.0; filed as https://github.com/oasis-tcs/sarif-spec/issues/530
  94     NOUN_function,
  95     NOUN_lock,
  96     NOUN_memory,
  97     NOUN_resource
  98   };
  99   enum property
 100   {
 101     PROPERTY_unknown,
 102
 103     PROPERTY_true,
 104     PROPERTY_false
 105   };
 106   /* A bundle of such enums, allowing for descriptions of the meaning of
 107      an event, such as
 108      - "acquire memory": meaning (VERB_acquire, NOUN_memory)
 109      - "take true branch"": meaning (VERB_branch, PROPERTY_true)
 110      - "return from function": meaning (VERB_return, NOUN_function)
 111      etc, as per SARIF's threadFlowLocation "kinds" property
 112      (SARIF v2.1.0 section 3.38.8).  */
 113   struct meaning
 114   {
 115     meaning ()
 116     : m_verb (VERB_unknown),
 117       m_noun (NOUN_unknown),
 118       m_property (PROPERTY_unknown)
 119     {
 120     }
 121     meaning (enum verb verb, enum noun noun)
 122     : m_verb (verb), m_noun (noun), m_property (PROPERTY_unknown)
 123     {
 124     }
 125     meaning (enum verb verb, enum property property)
 126     : m_verb (verb), m_noun (NOUN_unknown), m_property (property)
 127     {
 128     }
 129
 130     void dump_to_pp (pretty_printer *pp) const;
 131
 132     static const char *maybe_get_verb_str (enum verb);
 133     static const char *maybe_get_noun_str (enum noun);
 134     static const char *maybe_get_property_str (enum property);
 135
 136     enum verb m_verb;
 137     enum noun m_noun;
 138     enum property m_property;
 139   };
 140
 141   virtual ~diagnostic_event () {}
 142
 143   virtual location_t get_location () const = 0;
 144
 145   virtual tree get_fndecl () const = 0;
 146
 147   /* Stack depth, so that consumers can visualizes the interprocedural
 148      calls, returns, and frame nesting.  */
 149   virtual int get_stack_depth () const = 0;
 150
 151   /* Get a localized (and possibly colorized) description of this event.  */
 152   virtual label_text get_desc (bool can_colorize) const = 0;
 153
 154   /* Get a logical_location for this event, or NULL.  */
 155   virtual const logical_location *get_logical_location () const = 0;
 156
 157   virtual meaning get_meaning () const = 0;
 158
 159   virtual diagnostic_thread_id_t get_thread_id () const = 0;
 160 };
 161
 162 /* Abstract base class representing a thread of execution within
 163    a diagnostic_path.
 164    Each diagnostic_event is associated with one thread.
 165    Typically there is just one thread per diagnostic_path. */
 166
 167 class diagnostic_thread
 168 {
 169 public:
 170   virtual ~diagnostic_thread () {}
 171   virtual label_text get_name (bool can_colorize) const = 0;
 172 };
 173
 174 /* Abstract base class for getting at a sequence of events.  */
 175
 176 class diagnostic_path
 177 {
 178  public:
 179   virtual ~diagnostic_path () {}
 180   virtual unsigned num_events () const = 0;
 181   virtual const diagnostic_event & get_event (int idx) const = 0;
 182   virtual unsigned num_threads () const = 0;
 183   virtual const diagnostic_thread &
 184   get_thread (diagnostic_thread_id_t) const = 0;
 185
 186   bool interprocedural_p () const;
 187   bool multithreaded_p () const;
 188
 189 private:
 190   bool get_first_event_in_a_function (unsigned *out_idx) const;
 191 };
 192
 193 /* Concrete subclasses.  */
 194
 195 /* A simple implementation of diagnostic_event.  */
 196
 197 class simple_diagnostic_event : public diagnostic_event
 198 {
 199  public:
 200   simple_diagnostic_event (location_t loc, tree fndecl, int depth,
 201                            const char *desc,
 202                            diagnostic_thread_id_t thread_id = 0);
 203   ~simple_diagnostic_event ();
 204
 205   location_t get_location () const final override { return m_loc; }
 206   tree get_fndecl () const final override { return m_fndecl; }
 207   int get_stack_depth () const final override { return m_depth; }
 208   label_text get_desc (bool) const final override
 209   {
 210     return label_text::borrow (m_desc);
 211   }
 212   const logical_location *get_logical_location () const final override
 213   {
 214     return NULL;
 215   }
 216   meaning get_meaning () const final override
 217   {
 218     return meaning ();
 219   }
 220   diagnostic_thread_id_t get_thread_id () const final override
 221   {
 222     return m_thread_id;
 223   }
 224
 225  private:
 226   location_t m_loc;
 227   tree m_fndecl;
 228   int m_depth;
 229   char *m_desc; // has been i18n-ed and formatted
 230   diagnostic_thread_id_t m_thread_id;
 231 };
 232
 233 /* A simple implementation of diagnostic_thread.  */
 234
 235 class simple_diagnostic_thread : public diagnostic_thread
 236 {
 237 public:
 238   simple_diagnostic_thread (const char *name) : m_name (name) {}
 239   label_text get_name (bool) const final override
 240   {
 241     return label_text::borrow (m_name);
 242   }
 243
 244 private:
 245   const char *m_name; // has been i18n-ed and formatted
 246 };
 247
 248 /* A simple implementation of diagnostic_path, as a vector of
 249    simple_diagnostic_event instances.  */
 250
 251 class simple_diagnostic_path : public diagnostic_path
 252 {
 253  public:
 254   simple_diagnostic_path (pretty_printer *event_pp);
 255
 256   unsigned num_events () const final override;
 257   const diagnostic_event & get_event (int idx) const final override;
 258   unsigned num_threads () const final override;
 259   const diagnostic_thread &
 260   get_thread (diagnostic_thread_id_t) const final override;
 261
 262   diagnostic_thread_id_t add_thread (const char *name);
 263
 264   diagnostic_event_id_t add_event (location_t loc, tree fndecl, int depth,
 265                                    const char *fmt, ...)
 266     ATTRIBUTE_GCC_DIAG(5,6);
 267   diagnostic_event_id_t
 268   add_thread_event (diagnostic_thread_id_t thread_id,
 269                     location_t loc, tree fndecl, int depth,
 270                     const char *fmt, ...)
 271     ATTRIBUTE_GCC_DIAG(6,7);
 272
 273  private:
 274   auto_delete_vec<simple_diagnostic_thread> m_threads;
 275   auto_delete_vec<simple_diagnostic_event> m_events;
 276
 277   /* (for use by add_event).  */
 278   pretty_printer *m_event_pp;
 279 };
 280
 281 extern void debug (diagnostic_path *path);
 282
 283 #endif /* ! GCC_DIAGNOSTIC_PATH_H */