]>
Commit | Line | Data |
---|---|---|
4bc1899b | 1 | /* Paths through the code associated with a diagnostic. |
a945c346 | 2 | Copyright (C) 2019-2024 Free Software Foundation, Inc. |
4bc1899b DM |
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 | ||
05c99b1c DM |
27 | class sarif_object; |
28 | ||
4bc1899b DM |
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 | | | |
45 | | 25 | list = PyList_New(0); | |
46 | | | ^~~~~~~~~~~~~ | |
47 | | | | | |
48 | | | (1) when 'PyList_New' fails, returning NULL | |
49 | | 26 | | |
50 | | 27 | for (i = 0; i < count; i++) { | |
51 | | | ~~~ | |
52 | | | | | |
53 | | | (2) when 'i < count' | |
54 | | 28 | item = PyLong_FromLong(random()); | |
55 | | 29 | PyList_Append(list, item); | |
56 | | | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
57 | | | | | |
58 | | | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1 | |
59 | | | |
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 | ||
71 | class diagnostic_event | |
72 | { | |
73 | public: | |
6cf276dd DM |
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 | ||
4bc1899b DM |
143 | virtual ~diagnostic_event () {} |
144 | ||
145 | virtual location_t get_location () const = 0; | |
146 | ||
147 | virtual tree get_fndecl () const = 0; | |
148 | ||
149 | /* Stack depth, so that consumers can visualizes the interprocedural | |
150 | calls, returns, and frame nesting. */ | |
151 | virtual int get_stack_depth () const = 0; | |
152 | ||
153 | /* Get a localized (and possibly colorized) description of this event. */ | |
154 | virtual label_text get_desc (bool can_colorize) const = 0; | |
6cf276dd DM |
155 | |
156 | /* Get a logical_location for this event, or NULL. */ | |
157 | virtual const logical_location *get_logical_location () const = 0; | |
158 | ||
159 | virtual meaning get_meaning () const = 0; | |
3a1e9f3e DM |
160 | |
161 | virtual diagnostic_thread_id_t get_thread_id () const = 0; | |
05c99b1c DM |
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 | } | |
3a1e9f3e DM |
169 | }; |
170 | ||
171 | /* Abstract base class representing a thread of execution within | |
172 | a diagnostic_path. | |
173 | Each diagnostic_event is associated with one thread. | |
174 | Typically there is just one thread per diagnostic_path. */ | |
175 | ||
176 | class diagnostic_thread | |
177 | { | |
178 | public: | |
179 | virtual ~diagnostic_thread () {} | |
180 | virtual label_text get_name (bool can_colorize) const = 0; | |
4bc1899b DM |
181 | }; |
182 | ||
183 | /* Abstract base class for getting at a sequence of events. */ | |
184 | ||
185 | class diagnostic_path | |
186 | { | |
187 | public: | |
188 | virtual ~diagnostic_path () {} | |
189 | virtual unsigned num_events () const = 0; | |
190 | virtual const diagnostic_event & get_event (int idx) const = 0; | |
3a1e9f3e DM |
191 | virtual unsigned num_threads () const = 0; |
192 | virtual const diagnostic_thread & | |
193 | get_thread (diagnostic_thread_id_t) const = 0; | |
4bc1899b DM |
194 | |
195 | bool interprocedural_p () const; | |
3a1e9f3e | 196 | bool multithreaded_p () const; |
1d86af24 DM |
197 | |
198 | private: | |
199 | bool get_first_event_in_a_function (unsigned *out_idx) const; | |
4bc1899b DM |
200 | }; |
201 | ||
202 | /* Concrete subclasses. */ | |
203 | ||
204 | /* A simple implementation of diagnostic_event. */ | |
205 | ||
206 | class simple_diagnostic_event : public diagnostic_event | |
207 | { | |
208 | public: | |
209 | simple_diagnostic_event (location_t loc, tree fndecl, int depth, | |
3a1e9f3e DM |
210 | const char *desc, |
211 | diagnostic_thread_id_t thread_id = 0); | |
4bc1899b DM |
212 | ~simple_diagnostic_event (); |
213 | ||
ff171cb1 DM |
214 | location_t get_location () const final override { return m_loc; } |
215 | tree get_fndecl () const final override { return m_fndecl; } | |
216 | int get_stack_depth () const final override { return m_depth; } | |
217 | label_text get_desc (bool) const final override | |
4bc1899b DM |
218 | { |
219 | return label_text::borrow (m_desc); | |
220 | } | |
6cf276dd DM |
221 | const logical_location *get_logical_location () const final override |
222 | { | |
223 | return NULL; | |
224 | } | |
225 | meaning get_meaning () const final override | |
226 | { | |
227 | return meaning (); | |
228 | } | |
3a1e9f3e DM |
229 | diagnostic_thread_id_t get_thread_id () const final override |
230 | { | |
231 | return m_thread_id; | |
232 | } | |
4bc1899b DM |
233 | |
234 | private: | |
235 | location_t m_loc; | |
236 | tree m_fndecl; | |
237 | int m_depth; | |
238 | char *m_desc; // has been i18n-ed and formatted | |
3a1e9f3e DM |
239 | diagnostic_thread_id_t m_thread_id; |
240 | }; | |
241 | ||
242 | /* A simple implementation of diagnostic_thread. */ | |
243 | ||
244 | class simple_diagnostic_thread : public diagnostic_thread | |
245 | { | |
246 | public: | |
247 | simple_diagnostic_thread (const char *name) : m_name (name) {} | |
248 | label_text get_name (bool) const final override | |
249 | { | |
250 | return label_text::borrow (m_name); | |
251 | } | |
252 | ||
253 | private: | |
254 | const char *m_name; // has been i18n-ed and formatted | |
4bc1899b DM |
255 | }; |
256 | ||
257 | /* A simple implementation of diagnostic_path, as a vector of | |
258 | simple_diagnostic_event instances. */ | |
259 | ||
260 | class simple_diagnostic_path : public diagnostic_path | |
261 | { | |
262 | public: | |
3a1e9f3e | 263 | simple_diagnostic_path (pretty_printer *event_pp); |
4bc1899b | 264 | |
ff171cb1 DM |
265 | unsigned num_events () const final override; |
266 | const diagnostic_event & get_event (int idx) const final override; | |
3a1e9f3e DM |
267 | unsigned num_threads () const final override; |
268 | const diagnostic_thread & | |
269 | get_thread (diagnostic_thread_id_t) const final override; | |
270 | ||
271 | diagnostic_thread_id_t add_thread (const char *name); | |
4bc1899b DM |
272 | |
273 | diagnostic_event_id_t add_event (location_t loc, tree fndecl, int depth, | |
274 | const char *fmt, ...) | |
275 | ATTRIBUTE_GCC_DIAG(5,6); | |
3a1e9f3e DM |
276 | diagnostic_event_id_t |
277 | add_thread_event (diagnostic_thread_id_t thread_id, | |
278 | location_t loc, tree fndecl, int depth, | |
279 | const char *fmt, ...) | |
280 | ATTRIBUTE_GCC_DIAG(6,7); | |
4bc1899b DM |
281 | |
282 | private: | |
3a1e9f3e | 283 | auto_delete_vec<simple_diagnostic_thread> m_threads; |
4bc1899b DM |
284 | auto_delete_vec<simple_diagnostic_event> m_events; |
285 | ||
286 | /* (for use by add_event). */ | |
287 | pretty_printer *m_event_pp; | |
288 | }; | |
289 | ||
290 | extern void debug (diagnostic_path *path); | |
291 | ||
292 | #endif /* ! GCC_DIAGNOSTIC_PATH_H */ |