PR testsuite/44195
[official-gcc.git] / gcc / ada / scos.ads
blob7111287c0a626c99a7d98c04e80df5716eae14d4
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- S C O S --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2009-2010, Free Software Foundation, Inc. --
10 -- --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING3. If not, go to --
19 -- http://www.gnu.org/licenses for a complete copy of the license. --
20 -- --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
23 -- --
24 ------------------------------------------------------------------------------
26 -- This package defines tables used to store Source Coverage Obligations. It
27 -- is used by Par_SCO to build the SCO information before writing it out to
28 -- the ALI file, and by Get_SCO/Put_SCO to read and write the text form that
29 -- is used in the ALI file.
31 with Types; use Types;
33 with GNAT.Table;
35 package SCOs is
37 -- SCO information can exist in one of two forms. In the ALI file, it is
38 -- represented using a text format that is described in this specification.
39 -- Internally it is stored using two tables SCO_Table and SCO_Unit_Table,
40 -- which are also defined in this unit.
42 -- Par_SCO is part of the compiler. It scans the parsed source tree and
43 -- populates the internal tables.
45 -- Get_SCO reads the text lines in ALI format and populates the internal
46 -- tables with corresponding information.
48 -- Put_SCO reads the internal tables and generates text lines in the ALI
49 -- format.
51 --------------------
52 -- SCO ALI Format --
53 --------------------
55 -- Source coverage obligations are generated on a unit-by-unit basis in the
56 -- ALI file, using lines that start with the identifying character C. These
57 -- lines are generated if the -gnateS switch is set.
59 -- Sloc Ranges
61 -- In several places in the SCO lines, Sloc ranges appear. These are used
62 -- to indicate the first and last Sloc of some construct in the tree and
63 -- they have the form:
65 -- line:col-line:col
67 -- Note that SCO's are generated only for generic templates, not for
68 -- generic instances (since only the first are part of the source). So
69 -- we don't need generic instantiation stuff in these line:col items.
71 -- SCO File headers
73 -- The SCO information follows the cross-reference information, so it
74 -- need not be read by tools like gnatbind, gnatmake etc. The SCO output
75 -- is divided into sections, one section for each unit for which SCO's
76 -- are generated. A SCO section has a header of the form:
78 -- C dependency-number filename
80 -- This header precedes SCO information for the unit identified by
81 -- dependency number and file name. The dependency number is the
82 -- index into the generated D lines and is ones origin (i.e. 2 =
83 -- reference to second generated D line).
85 -- Note that the filename here will reflect the original name if
86 -- a Source_Reference pragma was encountered (since all line number
87 -- references will be with respect to the original file).
89 -- Note: the filename is redundant in that it could be deduced from
90 -- the corresponding D line, but it is convenient at least for human
91 -- reading of the SCO information, and means that the SCO information
92 -- can stand on its own without needing other parts of the ALI file.
94 -- Statements
96 -- For the purpose of SCO generation, the notion of statement includes
97 -- simple statements and also the following declaration types:
99 -- type_declaration
100 -- subtype_declaration
101 -- object_declaration
102 -- renaming_declaration
103 -- generic_instantiation
105 -- and the following regions of the syntax tree:
107 -- the part of a case_statement from CASE up to the expression
108 -- the part of a FOR loop iteration scheme from FOR up to the
109 -- loop_parameter_specification
110 -- the part of a WHILE loop up to the condition
111 -- the part of an extended_return_statement from RETURN up to the
112 -- expression (if present) or to the return_subtype_indication (if
113 -- no expression)
115 -- and any pragma that occurs at a place where a statement or declaration
116 -- is allowed.
118 -- Statement lines
120 -- These lines correspond to one or more successive statements (in the
121 -- sense of the above list) which are always executed in sequence (in the
122 -- absence of exceptions or other external interruptions).
124 -- Entry points to such sequences are:
126 -- the first declaration of any declarative_part
127 -- the first statement of any sequence_of_statements that is not in a
128 -- body or block statement that has a non-empty declarative part
129 -- the first statement after a compound statement
130 -- the first statement after an EXIT, RAISE or GOTO statement
131 -- any statement with a label (the label itself is not part of the
132 -- entry point that is recorded).
134 -- Each entry point must appear as the first entry on a CS line.
135 -- The idea is that if any simple statement on a CS line is known to have
136 -- been executed, then all statements that appear before it on the same
137 -- CS line are certain to also have been executed.
139 -- The form of a statement line in the ALI file is:
141 -- CS *sloc-range [*sloc-range...]
143 -- where each sloc-range corresponds to a single statement, and * is
144 -- one of:
146 -- t type declaration
147 -- s subtype declaration
148 -- o object declaration
149 -- r renaming declaration
150 -- i generic instantiation
151 -- C CASE statement (from CASE through end of expression)
152 -- E EXIT statement
153 -- F FOR loop statement (from FOR through end of iteration scheme)
154 -- I IF statement (from IF through end of condition)
155 -- P PRAGMA
156 -- R extended RETURN statement
157 -- W WHILE loop statement (from WHILE through end of condition)
159 -- Note: for I and W, condition above is in the RM syntax sense (this
160 -- condition is a decision in SCO terminology).
162 -- and is omitted for all other cases.
164 -- Note: up to 6 entries can appear on a single CS line. If more than 6
165 -- entries appear in one logical statement sequence, continuation lines
166 -- are marked by Cs and appear immediately after the CS line.
168 -- Decisions
170 -- Note: in the following description, logical operator includes only the
171 -- short-circuited forms and NOT (so can be only NOT, AND THEN, OR ELSE).
172 -- The reason that we can exclude AND/OR/XOR is that we expect SCO's to
173 -- be generated using the restriction No_Direct_Boolean_Operators if we
174 -- are interested in decision coverage, which does not permit the use of
175 -- AND/OR/XOR on boolean operands. These are permitted on modular integer
176 -- types, but such operations do not count as decisions in any case. If
177 -- we are generating SCO's only for simple coverage, then we are not
178 -- interested in decisions in any case.
180 -- Note: the reason we include NOT is for informational purposes. The
181 -- presence of NOT does not generate additional coverage obligations,
182 -- but if we know where the NOT's are, the coverage tool can generate
183 -- more accurate diagnostics on uncovered tests.
185 -- A top level boolean expression is a boolean expression that is not an
186 -- operand of a logical operator.
188 -- Decisions are either simple or complex. A simple decision is a top
189 -- level boolean expresssion that has only one condition and that occurs
190 -- in the context of a control structure in the source program, including
191 -- WHILE, IF, EXIT WHEN, or in an Assert, Check, Pre_Condition or
192 -- Post_Condition pragma. For pragmas, decision SCOs are generated only
193 -- if the corresponding pragma is enabled. Note that a top level boolean
194 -- expression with only one condition that occurs in any other context,
195 -- for example as right hand side of an assignment, is not considered to
196 -- be a (simple) decision.
198 -- A complex decision is a top level boolean expression that has more
199 -- than one condition. A complex decision may occur in any boolean
200 -- expression context.
202 -- So for example, if we have
204 -- A, B, C, D : Boolean;
205 -- function F (Arg : Boolean) return Boolean);
206 -- ...
207 -- A and then (B or else F (C and then D))
209 -- There are two (complex) decisions here:
211 -- 1. X and then (Y or else Z)
213 -- where X = A, Y = B, and Z = F (C and then D)
215 -- 2. C and then D
217 -- For each decision, a decision line is generated with the form:
219 -- C* sloc expression
221 -- Here * is one of the following characters:
223 -- I decision in IF statement or conditional expression
224 -- E decision in EXIT WHEN statement
225 -- P decision in pragma Assert/Check/Pre_Condition/Post_Condition
226 -- W decision in WHILE iteration scheme
227 -- X decision appearing in some other expression context
229 -- For I, E, P, W, sloc is the source location of the IF, EXIT, PRAGMA or
230 -- WHILE token.
232 -- For X, sloc is omitted.
234 -- The expression is a prefix polish form indicating the structure of
235 -- the decision, including logical operators and short-circuit forms.
236 -- The following is a grammar showing the structure of expression:
238 -- expression ::= term (if expr is not logical operator)
239 -- expression ::= &sloc term term (if expr is AND or AND THEN)
240 -- expression ::= |sloc term term (if expr is OR or OR ELSE)
241 -- expression ::= !sloc term (if expr is NOT)
243 -- In the last four cases, sloc is the source location of the AND, OR,
244 -- or NOT token, respectively.
246 -- term ::= element
247 -- term ::= expression
249 -- element ::= outcome sloc-range
251 -- outcome is one of the following letters:
253 -- c condition
254 -- t true condition
255 -- f false condition
257 -- where t/f are used to mark a condition that has been recognized by
258 -- the compiler as always being true or false.
260 -- & indicates AND THEN connecting two conditions.
262 -- | indicates OR ELSE connecting two conditions.
264 -- ! indicates NOT applied to the expression.
266 -- Note that complex decisions do NOT include non-short-circuited logical
267 -- operators (AND/XOR/OR). In the context of existing coverage tools the
268 -- No_Direct_Boolean_Operators restriction is assumed, so these operators
269 -- cannot appear in the source in any case.
271 -- The SCO line for a decision always occurs after the CS line for the
272 -- enclosing statement. The SCO line for a nested decision always occurs
273 -- after the line for the enclosing decision.
275 -- Note that membership tests are considered to be a single simple
276 -- condition, and that is true even if the Ada 2005 set membership
277 -- form is used, e.g. A in (2,7,11.15).
279 -- Case Expressions
281 -- For case statements, we rely on statement coverage to make sure that
282 -- all branches of a case statement are covered, but that does not work
283 -- for case expressions, since the entire expression is contained in a
284 -- single statement. However, for complete coverage we really should be
285 -- able to check that every branch of the case statement is covered, so
286 -- we generate a SCO of the form:
288 -- CC sloc-range sloc-range ...
290 -- where sloc-range covers the range of the case expression.
292 -- Note: up to 6 entries can appear on a single CC line. If more than 6
293 -- entries appear in one logical statement sequence, continuation lines
294 -- are marked by Cc and appear immediately after the CC line.
296 ---------------------------------------------------------------------
297 -- Internal table used to store Source Coverage Obligations (SCOs) --
298 ---------------------------------------------------------------------
300 type Source_Location is record
301 Line : Logical_Line_Number;
302 Col : Column_Number;
303 end record;
305 No_Source_Location : Source_Location := (No_Line_Number, No_Column_Number);
307 type SCO_Table_Entry is record
308 From : Source_Location;
309 To : Source_Location;
310 C1 : Character;
311 C2 : Character;
312 Last : Boolean;
313 end record;
315 package SCO_Table is new GNAT.Table (
316 Table_Component_Type => SCO_Table_Entry,
317 Table_Index_Type => Nat,
318 Table_Low_Bound => 1,
319 Table_Initial => 500,
320 Table_Increment => 300);
322 -- The SCO_Table_Entry values appear as follows:
324 -- Statements
325 -- C1 = 'S' for entry point, 's' otherwise
326 -- C2 = statement type code to appear on CS line (or ' ' if none)
327 -- From = starting source location
328 -- To = ending source location
329 -- Last = False for all but the last entry, True for last entry
331 -- Note: successive statements (possibly interspersed with entries of
332 -- other kinds, that are ignored for this purpose), starting with one
333 -- labeled with C1 = 'S', up to and including the first one labeled with
334 -- Last = True, indicate the sequence to be output for a sequence of
335 -- statements on a single CS line (possibly followed by Cs continuation
336 -- lines).
338 -- Decision (IF/EXIT/WHILE)
339 -- C1 = 'I'/'E'/'W' (for IF/EXIT/WHILE)
340 -- C2 = ' '
341 -- From = IF/EXIT/WHILE token
342 -- To = No_Source_Location
343 -- Last = unused
345 -- Decision (PRAGMA)
346 -- C1 = 'P'
347 -- C2 = 'e'/'d' for enabled/disabled
348 -- From = PRAGMA token
349 -- To = No_Source_Location
350 -- Last = unused
352 -- Note: when the parse tree is first scanned, we unconditionally build
353 -- a pragma decision entry for any decision in a pragma (here as always
354 -- in SCO contexts, the only pragmas with decisions are Assert, Check,
355 -- Precondition and Postcondition), and we mark the pragma as disabled.
357 -- During analysis, if the pragma is enabled, Set_SCO_Pragma_Enabled to
358 -- mark the SCO decision table entry as enabled (C2 set to 'e'). Then
359 -- in Put_SCOs, we only output the decision for a pragma if C2 is 'e'.
361 -- When we read SCOs from an ALI file (in Get_SCOs), we always set C2
362 -- to 'e', since clearly the pragma is enabled if it was written out.
364 -- Decision (Expression)
365 -- C1 = 'X'
366 -- C2 = ' '
367 -- From = No_Source_Location
368 -- To = No_Source_Location
369 -- Last = unused
371 -- Operator
372 -- C1 = '!', '&', '|'
373 -- C2 = ' '
374 -- From = location of NOT/AND/OR token
375 -- To = No_Source_Location
376 -- Last = False
378 -- Element (condition)
379 -- C1 = ' '
380 -- C2 = 'c', 't', or 'f' (condition/true/false)
381 -- From = starting source location
382 -- To = ending source location
383 -- Last = False for all but the last entry, True for last entry
385 -- Note: the sequence starting with a decision, and continuing with
386 -- operators and elements up to and including the first one labeled with
387 -- Last = True, indicate the sequence to be output on one decision line.
389 ----------------
390 -- Unit Table --
391 ----------------
393 -- This table keeps track of the units and the corresponding starting and
394 -- ending indexes (From, To) in the SCO table. Note that entry zero is
395 -- unused, it is for convenience in calling the sort routine. Thus the
396 -- real lower bound for active entries is 1.
398 type SCO_Unit_Index is new Int;
399 -- Used to index values in this table. Values start at 1 and are assigned
400 -- sequentially as entries are constructed.
402 type SCO_Unit_Table_Entry is record
403 File_Name : String_Ptr;
404 -- Pointer to file name in ALI file
406 Dep_Num : Nat;
407 -- Dependency number in ALI file
409 From : Nat;
410 -- Starting index in SCO_Table of SCO information for this unit
412 To : Nat;
413 -- Ending index in SCO_Table of SCO information for this unit
414 end record;
416 package SCO_Unit_Table is new GNAT.Table (
417 Table_Component_Type => SCO_Unit_Table_Entry,
418 Table_Index_Type => SCO_Unit_Index,
419 Table_Low_Bound => 0, -- see note above on sorting
420 Table_Initial => 20,
421 Table_Increment => 200);
423 -----------------
424 -- Subprograms --
425 -----------------
427 procedure Initialize;
428 -- Reset tables for a new compilation
430 procedure Add_SCO
431 (From : Source_Location := No_Source_Location;
432 To : Source_Location := No_Source_Location;
433 C1 : Character := ' ';
434 C2 : Character := ' ';
435 Last : Boolean := False);
436 -- Adds one entry to SCO table with given field values
438 end SCOs;