GCC Middle and Back End API Reference
diagnostic-path.h
Go to the documentation of this file.
1/* Paths through the code associated with a diagnostic.
2 Copyright (C) 2019-2024 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
27class 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
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. */
88 enum noun
89 {
91
93 NOUN_sensitive, // this one isn't in SARIF v2.1.0; filed as https://github.com/oasis-tcs/sarif-spec/issues/530
98 };
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 {
121 meaning (enum verb verb, enum noun noun)
123 {
124 }
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
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 visualize 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 /* 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
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_object &/*thread_flow_loc_obj*/) const
169 {
170 }
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
179{
180public:
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
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 &
196
197 bool interprocedural_p () const;
198 bool multithreaded_p () const;
199
200private:
201 bool get_first_event_in_a_function (unsigned *out_idx) const;
202};
203
204/* Concrete subclasses. */
205
206/* A simple implementation of diagnostic_event. */
207
209{
210 public:
211 simple_diagnostic_event (location_t loc, tree fndecl, int depth,
212 const char *desc,
213 diagnostic_thread_id_t thread_id = 0);
215
216 location_t get_location () const final override { return m_loc; }
217 tree get_fndecl () const final override { return m_fndecl; }
218 int get_stack_depth () const final override { return m_depth; }
219 label_text get_desc (bool) const final override
220 {
221 return label_text::borrow (m_desc);
222 }
224 {
225 return NULL;
226 }
227 meaning get_meaning () const final override
228 {
229 return meaning ();
230 }
231 bool connect_to_next_event_p () const final override
232 {
234 }
236 {
237 return m_thread_id;
238 }
239
241 {
243 }
244
245 private:
246 location_t m_loc;
249 char *m_desc; // has been i18n-ed and formatted
252};
253
254/* A simple implementation of diagnostic_thread. */
255
257{
258public:
259 simple_diagnostic_thread (const char *name) : m_name (name) {}
260 label_text get_name (bool) const final override
261 {
262 return label_text::borrow (m_name);
263 }
264
265private:
266 const char *m_name; // has been i18n-ed and formatted
267};
268
269/* A simple implementation of diagnostic_path, as a vector of
270 simple_diagnostic_event instances. */
271
273{
274 public:
276
277 unsigned num_events () const final override;
278 const diagnostic_event & get_event (int idx) const final override;
279 unsigned num_threads () const final override;
280 const diagnostic_thread &
281 get_thread (diagnostic_thread_id_t) const final override;
282
283 diagnostic_thread_id_t add_thread (const char *name);
284
285 diagnostic_event_id_t add_event (location_t loc, tree fndecl, int depth,
286 const char *fmt, ...)
290 location_t loc, tree fndecl, int depth,
291 const char *fmt, ...)
293
294 void connect_to_next_event ();
295
297
298 private:
301
302 /* (for use by add_event). */
305};
306
307extern void debug (diagnostic_path *path);
308
309#endif /* ! GCC_DIAGNOSTIC_PATH_H */
Definition vec.h:1802
Definition diagnostic-event-id.h:37
Definition diagnostic-path.h:70
noun
Definition diagnostic-path.h:89
@ NOUN_resource
Definition diagnostic-path.h:97
@ NOUN_taint
Definition diagnostic-path.h:92
@ NOUN_function
Definition diagnostic-path.h:94
@ NOUN_lock
Definition diagnostic-path.h:95
@ NOUN_unknown
Definition diagnostic-path.h:90
@ NOUN_memory
Definition diagnostic-path.h:96
@ NOUN_sensitive
Definition diagnostic-path.h:93
virtual ~diagnostic_event()
Definition diagnostic-path.h:141
virtual void maybe_add_sarif_properties(sarif_object &) const
Definition diagnostic-path.h:168
virtual tree get_fndecl() const =0
verb
Definition diagnostic-path.h:75
@ VERB_danger
Definition diagnostic-path.h:86
@ VERB_return
Definition diagnostic-path.h:83
@ VERB_branch
Definition diagnostic-path.h:84
@ VERB_acquire
Definition diagnostic-path.h:78
@ VERB_call
Definition diagnostic-path.h:82
@ VERB_enter
Definition diagnostic-path.h:80
@ VERB_release
Definition diagnostic-path.h:79
@ VERB_unknown
Definition diagnostic-path.h:76
@ VERB_exit
Definition diagnostic-path.h:81
virtual const logical_location * get_logical_location() const =0
virtual int get_stack_depth() const =0
virtual location_t get_location() const =0
virtual bool connect_to_next_event_p() const =0
virtual meaning get_meaning() const =0
virtual diagnostic_thread_id_t get_thread_id() const =0
virtual label_text get_desc(bool can_colorize) const =0
property
Definition diagnostic-path.h:100
@ PROPERTY_unknown
Definition diagnostic-path.h:101
@ PROPERTY_false
Definition diagnostic-path.h:104
@ PROPERTY_true
Definition diagnostic-path.h:103
Definition diagnostic-path.h:188
virtual const diagnostic_event & get_event(int idx) const =0
bool multithreaded_p() const
virtual unsigned num_events() const =0
virtual unsigned num_threads() const =0
virtual ~diagnostic_path()
Definition diagnostic-path.h:190
bool interprocedural_p() const
Definition diagnostic.cc:1057
virtual const diagnostic_thread & get_thread(diagnostic_thread_id_t) const =0
bool get_first_event_in_a_function(unsigned *out_idx) const
Definition diagnostic.cc:1038
Definition diagnostic-path.h:179
virtual ~diagnostic_thread()
Definition diagnostic-path.h:181
virtual label_text get_name(bool can_colorize) const =0
Definition logical-location.h:52
Definition pretty-print.h:255
Definition diagnostic-format-sarif.h:42
Definition diagnostic-path.h:209
bool connect_to_next_event_p() const final override
Definition diagnostic-path.h:231
const logical_location * get_logical_location() const final override
Definition diagnostic-path.h:223
bool m_connected_to_next_event
Definition diagnostic-path.h:250
meaning get_meaning() const final override
Definition diagnostic-path.h:227
tree get_fndecl() const final override
Definition diagnostic-path.h:217
location_t get_location() const final override
Definition diagnostic-path.h:216
~simple_diagnostic_event()
Definition diagnostic.cc:2664
int m_depth
Definition diagnostic-path.h:248
tree m_fndecl
Definition diagnostic-path.h:247
simple_diagnostic_event(location_t loc, tree fndecl, int depth, const char *desc, diagnostic_thread_id_t thread_id=0)
Definition diagnostic.cc:2651
location_t m_loc
Definition diagnostic-path.h:246
void connect_to_next_event()
Definition diagnostic-path.h:240
diagnostic_thread_id_t get_thread_id() const final override
Definition diagnostic-path.h:235
char * m_desc
Definition diagnostic-path.h:249
label_text get_desc(bool) const final override
Definition diagnostic-path.h:219
diagnostic_thread_id_t m_thread_id
Definition diagnostic-path.h:251
int get_stack_depth() const final override
Definition diagnostic-path.h:218
Definition diagnostic-path.h:273
pretty_printer * m_event_pp
Definition diagnostic-path.h:303
const diagnostic_event & get_event(int idx) const final override
Definition diagnostic.cc:2542
diagnostic_event_id_t add_event(location_t loc, tree fndecl, int depth, const char *fmt,...) ATTRIBUTE_GCC_DIAG(5
Definition diagnostic.cc:2575
void disable_event_localization()
Definition diagnostic-path.h:296
auto_delete_vec< simple_diagnostic_event > m_events
Definition diagnostic-path.h:300
unsigned num_events() const final override
Definition diagnostic.cc:2533
diagnostic_event_id_t diagnostic_event_id_t add_thread_event(diagnostic_thread_id_t thread_id, location_t loc, tree fndecl, int depth, const char *fmt,...) ATTRIBUTE_GCC_DIAG(6
Definition diagnostic.cc:2604
bool m_localize_events
Definition diagnostic-path.h:304
auto_delete_vec< simple_diagnostic_thread > m_threads
Definition diagnostic-path.h:299
diagnostic_thread_id_t add_thread(const char *name)
Definition diagnostic.cc:2560
simple_diagnostic_path(pretty_printer *event_pp)
Definition diagnostic.cc:2522
const diagnostic_thread & get_thread(diagnostic_thread_id_t) const final override
Definition diagnostic.cc:2554
unsigned num_threads() const final override
Definition diagnostic.cc:2548
diagnostic_event_id_t diagnostic_event_id_t void connect_to_next_event()
Definition diagnostic.cc:2640
Definition diagnostic-path.h:257
const char * m_name
Definition diagnostic-path.h:266
simple_diagnostic_thread(const char *name)
Definition diagnostic-path.h:259
label_text get_name(bool) const final override
Definition diagnostic-path.h:260
bool debug
Definition collect-utils.cc:34
union tree_node * tree
Definition coretypes.h:97
#define ATTRIBUTE_GCC_DIAG(m, n)
Definition diagnostic-core.h:67
unsigned diagnostic_thread_id_t
Definition diagnostic-event-id.h:64
void final(rtx_insn *first, FILE *file, int optimize_p)
Definition final.cc:2002
Definition diagnostic-path.h:114
static const char * maybe_get_noun_str(enum noun)
Definition diagnostic.cc:987
meaning()
Definition diagnostic-path.h:115
static const char * maybe_get_property_str(enum property)
Definition diagnostic.cc:1014
meaning(enum verb verb, enum property property)
Definition diagnostic-path.h:125
enum verb m_verb
Definition diagnostic-path.h:136
void dump_to_pp(pretty_printer *pp) const
Definition diagnostic.cc:926
enum property m_property
Definition diagnostic-path.h:138
enum noun m_noun
Definition diagnostic-path.h:137
static const char * maybe_get_verb_str(enum verb)
Definition diagnostic.cc:956
meaning(enum verb verb, enum noun noun)
Definition diagnostic-path.h:121
#define NULL
Definition system.h:50