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
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
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
69class 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
167class diagnostic_thread
168{
169public:
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
176class 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
189private:
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
197class 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 (buffer: 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
235class simple_diagnostic_thread : public diagnostic_thread
236{
237public:
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 (buffer: m_name);
242 }
243
244private:
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
251class 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
281extern void debug (diagnostic_path *path);
282
283#endif /* ! GCC_DIAGNOSTIC_PATH_H */
284

source code of gcc/diagnostic-path.h