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