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
160 /* Abstract base class for getting at a sequence of events. */
161
162 class diagnostic_path
163 {
164 public:
165 virtual ~diagnostic_path () {}
166 virtual unsigned num_events () const = 0;
167 virtual const diagnostic_event & get_event (int idx) const = 0;
168
169 bool interprocedural_p () const;
170
171 private:
172 bool get_first_event_in_a_function (unsigned *out_idx) const;
173 };
174
175 /* Concrete subclasses. */
176
177 /* A simple implementation of diagnostic_event. */
178
179 class simple_diagnostic_event : public diagnostic_event
180 {
181 public:
182 simple_diagnostic_event (location_t loc, tree fndecl, int depth,
183 const char *desc);
184 ~simple_diagnostic_event ();
185
186 location_t get_location () const final override { return m_loc; }
187 tree get_fndecl () const final override { return m_fndecl; }
188 int get_stack_depth () const final override { return m_depth; }
189 label_text get_desc (bool) const final override
190 {
191 return label_text::borrow (m_desc);
192 }
193 const logical_location *get_logical_location () const final override
194 {
195 return NULL;
196 }
197 meaning get_meaning () const final override
198 {
199 return meaning ();
200 }
201
202 private:
203 location_t m_loc;
204 tree m_fndecl;
205 int m_depth;
206 char *m_desc; // has been i18n-ed and formatted
207 };
208
209 /* A simple implementation of diagnostic_path, as a vector of
210 simple_diagnostic_event instances. */
211
212 class simple_diagnostic_path : public diagnostic_path
213 {
214 public:
215 simple_diagnostic_path (pretty_printer *event_pp)
216 : m_event_pp (event_pp) {}
217
218 unsigned num_events () const final override;
219 const diagnostic_event & get_event (int idx) const final override;
220
221 diagnostic_event_id_t add_event (location_t loc, tree fndecl, int depth,
222 const char *fmt, ...)
223 ATTRIBUTE_GCC_DIAG(5,6);
224
225 private:
226 auto_delete_vec<simple_diagnostic_event> m_events;
227
228 /* (for use by add_event). */
229 pretty_printer *m_event_pp;
230 };
231
232 extern void debug (diagnostic_path *path);
233
234 #endif /* ! GCC_DIAGNOSTIC_PATH_H */