gcc/diagnostic-path.h

   1 /* Paths through the code associated with a diagnostic.
   2    Copyright (C) 2019-2025 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 class sarif_object;
  28
  29 /* A diagnostic_path is an optional additional piece of metadata associated
  30    with a diagnostic (via its rich_location).
  31
  32    It describes a sequence of events predicted by the compiler that
  33    lead to the problem occurring, with their locations in the user's source,
  34    and text descriptions.
  35
  36    For example, the following error has a 3-event path:
  37
  38      test.c: In function 'demo':
  39      test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which
  40        requires a non-NULL parameter
  41         29 |     PyList_Append(list, item);
  42            |     ^~~~~~~~~~~~~~~~~~~~~~~~~
  43        'demo': events 1-3
  44         25 |   list = PyList_New(0);
  45            |          ^~~~~~~~~~~~~
  46            |          |
  47            |          (1) when 'PyList_New' fails, returning NULL
  48         26 |
  49         27 |   for (i = 0; i < count; i++) {
  50            |   ~~~
  51            |   |
  52            |   (2) when 'i < count'
  53         28 |     item = PyLong_FromLong(random());
  54         29 |     PyList_Append(list, item);
  55            |     ~~~~~~~~~~~~~~~~~~~~~~~~~
  56            |     |
  57            |     (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
  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   /* Stack depth, so that consumers can visualize the interprocedural
 146      calls, returns, and frame nesting.  */
 147   virtual int get_stack_depth () const = 0;
 148
 149   /* Print a localized (and possibly colorized) description of this event.  */
 150   virtual void print_desc (pretty_printer &pp) const = 0;
 151
 152   /* Get a logical_location for this event, or nullptr if there is none.  */
 153   virtual const logical_location *get_logical_location () const = 0;
 154
 155   virtual meaning get_meaning () const = 0;
 156
 157   /* True iff we should draw a line connecting this event to the
 158      next event (e.g. to highlight control flow).  */
 159   virtual bool connect_to_next_event_p () const = 0;
 160
 161   virtual diagnostic_thread_id_t get_thread_id () const = 0;
 162
 163   /* Hook for SARIF output to allow for adding diagnostic-specific
 164      properties to the threadFlowLocation object's property bag.  */
 165   virtual void
 166   maybe_add_sarif_properties (sarif_object &/*thread_flow_loc_obj*/) const
 167   {
 168   }
 169
 170   label_text get_desc (pretty_printer &ref_pp) const;
 171 };
 172
 173 /* Abstract base class representing a thread of execution within
 174    a diagnostic_path.
 175    Each diagnostic_event is associated with one thread.
 176    Typically there is just one thread per diagnostic_path. */
 177
 178 class diagnostic_thread
 179 {
 180 public:
 181   virtual ~diagnostic_thread () {}
 182   virtual label_text get_name (bool can_colorize) const = 0;
 183 };
 184
 185 /* Abstract base class for getting at a sequence of events.  */
 186
 187 class diagnostic_path
 188 {
 189  public:
 190   virtual ~diagnostic_path () {}
 191   virtual unsigned num_events () const = 0;
 192   virtual const diagnostic_event & get_event (int idx) const = 0;
 193   virtual unsigned num_threads () const = 0;
 194   virtual const diagnostic_thread &
 195   get_thread (diagnostic_thread_id_t) const = 0;
 196
 197   /* Return true iff the two events are both within the same function,
 198      or both outside of any function.  */
 199   virtual bool
 200   same_function_p (int event_idx_a,
 201                    int event_idx_b) const = 0;
 202
 203   bool interprocedural_p () const;
 204   bool multithreaded_p () const;
 205
 206 private:
 207   bool get_first_event_in_a_function (unsigned *out_idx) const;
 208 };
 209
 210 /* Concrete subclasses of the above can be found in
 211    simple-diagnostic-path.h.  */
 212
 213 extern void debug (diagnostic_path *path);
 214
 215 #endif /* ! GCC_DIAGNOSTIC_PATH_H */