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
5This file is part of GCC.
6
7GCC is free software; you can redistribute it and/or modify it under
8the terms of the GNU General Public License as published by the Free
9Software Foundation; either version 3, or (at your option) any later
10version.
11
12GCC is distributed in the hope that it will be useful, but WITHOUT ANY
13WARRANTY; without even the implied warranty of MERCHANTABILITY or
14FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15for more details.
16
17You should have received a copy of the GNU General Public License
18along 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#include "logical-location.h"
27
28class sarif_builder;
29class sarif_object;
30
31/* A diagnostic_path is an optional additional piece of metadata associated
32 with a diagnostic (via its rich_location).
33
34 It describes a sequence of events predicted by the compiler that
35 lead to the problem occurring, with their locations in the user's source,
36 and text descriptions.
37
38 For example, the following error has a 3-event path:
39
40 test.c: In function 'demo':
41 test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which
42 requires a non-NULL parameter
43 29 | PyList_Append(list, item);
44 | ^~~~~~~~~~~~~~~~~~~~~~~~~
45 'demo': events 1-3
46 25 | list = PyList_New(0);
47 | ^~~~~~~~~~~~~
48 | |
49 | (1) when 'PyList_New' fails, returning NULL
50 26 |
51 27 | for (i = 0; i < count; i++) {
52 | ~~~
53 | |
54 | (2) when 'i < count'
55 28 | item = PyLong_FromLong(random());
56 29 | PyList_Append(list, item);
57 | ~~~~~~~~~~~~~~~~~~~~~~~~~
58 | |
59 | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
60
61 The diagnostic-printing code has consolidated the path into a single
62 run of events, since all the events are near each other and within the same
63 function; more complicated examples (such as interprocedural paths)
64 might be printed as multiple runs of events. */
65
66/* Abstract base classes, describing events within a path, and the paths
67 themselves. */
68
69/* One event within a diagnostic_path. */
70
71class diagnostic_event
72{
73 public:
74 /* Enums for giving a sense of what this event means.
75 Roughly corresponds to SARIF v2.1.0 section 3.38.8. */
76 enum verb
77 {
78 VERB_unknown,
79
80 VERB_acquire,
81 VERB_release,
82 VERB_enter,
83 VERB_exit,
84 VERB_call,
85 VERB_return,
86 VERB_branch,
87
88 VERB_danger
89 };
90 enum noun
91 {
92 NOUN_unknown,
93
94 NOUN_taint,
95 NOUN_sensitive, // this one isn't in SARIF v2.1.0; filed as https://github.com/oasis-tcs/sarif-spec/issues/530
96 NOUN_function,
97 NOUN_lock,
98 NOUN_memory,
99 NOUN_resource
100 };
101 enum property
102 {
103 PROPERTY_unknown,
104
105 PROPERTY_true,
106 PROPERTY_false
107 };
108 /* A bundle of such enums, allowing for descriptions of the meaning of
109 an event, such as
110 - "acquire memory": meaning (VERB_acquire, NOUN_memory)
111 - "take true branch"": meaning (VERB_branch, PROPERTY_true)
112 - "return from function": meaning (VERB_return, NOUN_function)
113 etc, as per SARIF's threadFlowLocation "kinds" property
114 (SARIF v2.1.0 section 3.38.8). */
115 struct meaning
116 {
117 meaning ()
118 : m_verb (VERB_unknown),
119 m_noun (NOUN_unknown),
120 m_property (PROPERTY_unknown)
121 {
122 }
123 meaning (enum verb verb, enum noun noun)
124 : m_verb (verb), m_noun (noun), m_property (PROPERTY_unknown)
125 {
126 }
127 meaning (enum verb verb, enum property property)
128 : m_verb (verb), m_noun (NOUN_unknown), m_property (property)
129 {
130 }
131
132 void dump_to_pp (pretty_printer *pp) const;
133
134 static const char *maybe_get_verb_str (enum verb);
135 static const char *maybe_get_noun_str (enum noun);
136 static const char *maybe_get_property_str (enum property);
137
138 enum verb m_verb;
139 enum noun m_noun;
140 enum property m_property;
141 };
142
143 virtual ~diagnostic_event () {}
144
145 virtual location_t get_location () const = 0;
146
147 /* Stack depth, so that consumers can visualize the interprocedural
148 calls, returns, and frame nesting. */
149 virtual int get_stack_depth () const = 0;
150
151 /* Print a localized (and possibly colorized) description of this event. */
152 virtual void print_desc (pretty_printer &pp) const = 0;
153
154 /* Get a logical location for this event, or null if there is none. */
155 virtual logical_location get_logical_location () const = 0;
156
157 virtual meaning get_meaning () const = 0;
158
159 /* True iff we should draw a line connecting this event to the
160 next event (e.g. to highlight control flow). */
161 virtual bool connect_to_next_event_p () const = 0;
162
163 virtual diagnostic_thread_id_t get_thread_id () const = 0;
164
165 /* Hook for SARIF output to allow for adding diagnostic-specific
166 properties to the threadFlowLocation object's property bag. */
167 virtual void
168 maybe_add_sarif_properties (sarif_builder &,
169 sarif_object &/*thread_flow_loc_obj*/) const
170 {
171 }
172
173 label_text get_desc (pretty_printer &ref_pp) const;
174};
175
176/* Abstract base class representing a thread of execution within
177 a diagnostic_path.
178 Each diagnostic_event is associated with one thread.
179 Typically there is just one thread per diagnostic_path. */
180
181class diagnostic_thread
182{
183public:
184 virtual ~diagnostic_thread () {}
185 virtual label_text get_name (bool can_colorize) const = 0;
186};
187
188/* Abstract base class for getting at a sequence of events. */
189
190class diagnostic_path
191{
192 public:
193 virtual ~diagnostic_path () {}
194 virtual unsigned num_events () const = 0;
195 virtual const diagnostic_event & get_event (int idx) const = 0;
196 virtual unsigned num_threads () const = 0;
197 virtual const diagnostic_thread &
198 get_thread (diagnostic_thread_id_t) const = 0;
199
200 /* Return true iff the two events are both within the same function,
201 or both outside of any function. */
202 virtual bool
203 same_function_p (int event_idx_a,
204 int event_idx_b) const = 0;
205
206 bool interprocedural_p () const;
207 bool multithreaded_p () const;
208
209 const logical_location_manager &get_logical_location_manager () const
210 {
211 return m_logical_loc_mgr;
212 }
213
214protected:
215 diagnostic_path (const logical_location_manager &logical_loc_mgr)
216 : m_logical_loc_mgr (logical_loc_mgr)
217 {
218 }
219
220private:
221 bool get_first_event_in_a_function (unsigned *out_idx) const;
222
223 const logical_location_manager &m_logical_loc_mgr;
224};
225
226/* Concrete subclasses of the above can be found in
227 simple-diagnostic-path.h. */
228
229extern void debug (diagnostic_path *path);
230
231#endif /* ! GCC_DIAGNOSTIC_PATH_H */
232

source code of gcc/diagnostic-path.h