1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 2009-2012, Free Software Foundation, Inc. --
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. --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
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 Snames; use Snames;
32 -- Note: used for Pragma_Id only, no other feature from Snames should be used,
33 -- as a simplified version is maintained in Xcov.
35 with Types; use Types;
41 -- SCO information can exist in one of two forms. In the ALI file, it is
42 -- represented using a text format that is described in this specification.
43 -- Internally it is stored using two tables SCO_Table and SCO_Unit_Table,
44 -- which are also defined in this unit.
46 -- Par_SCO is part of the compiler. It scans the parsed source tree and
47 -- populates the internal tables.
49 -- Get_SCO reads the text lines in ALI format and populates the internal
50 -- tables with corresponding information.
52 -- Put_SCO reads the internal tables and generates text lines in the ALI
59 -- Source coverage obligations are generated on a unit-by-unit basis in the
60 -- ALI file, using lines that start with the identifying character C. These
61 -- lines are generated if the -gnateS switch is set.
65 -- In several places in the SCO lines, Sloc ranges appear. These are used
66 -- to indicate the first and last Sloc of some construct in the tree and
67 -- they have the form:
71 -- Note that SCO's are generated only for generic templates, not for
72 -- generic instances (since only the first are part of the source). So
73 -- we don't need generic instantiation stuff in these line:col items.
77 -- The SCO information follows the cross-reference information, so it
78 -- need not be read by tools like gnatbind, gnatmake etc. The SCO output
79 -- is divided into sections, one section for each unit for which SCO's
80 -- are generated. A SCO section has a header of the form:
82 -- C dependency-number filename
84 -- This header precedes SCO information for the unit identified by
85 -- dependency number and file name. The dependency number is the
86 -- index into the generated D lines and is ones origin (i.e. 2 =
87 -- reference to second generated D line).
89 -- Note that the filename here will reflect the original name if
90 -- a Source_Reference pragma was encountered (since all line number
91 -- references will be with respect to the original file).
93 -- Note: the filename is redundant in that it could be deduced from
94 -- the corresponding D line, but it is convenient at least for human
95 -- reading of the SCO information, and means that the SCO information
96 -- can stand on its own without needing other parts of the ALI file.
100 -- For the purpose of SCO generation, the notion of statement includes
101 -- simple statements and also the following declaration types:
104 -- subtype_declaration
105 -- object_declaration
106 -- renaming_declaration
107 -- generic_instantiation
109 -- and the following regions of the syntax tree:
111 -- the part of a case_statement from CASE up to the expression
112 -- the part of a FOR loop iteration scheme from FOR up to the
113 -- loop_parameter_specification
114 -- the part of a WHILE loop up to the condition
115 -- the part of an extended_return_statement from RETURN up to the
116 -- expression (if present) or to the return_subtype_indication (if
119 -- and any pragma that occurs at a place where a statement or declaration
124 -- These lines correspond to one or more successive statements (in the
125 -- sense of the above list) which are always executed in sequence (in the
126 -- absence of exceptions or other external interruptions).
128 -- Entry points to such sequences are:
130 -- the first declaration of any declarative_part
131 -- the first statement of any sequence_of_statements that is not in a
132 -- body or block statement that has a non-empty declarative part
133 -- the first statement after a compound statement
134 -- the first statement after an EXIT, RAISE or GOTO statement
135 -- any statement with a label (the label itself is not part of the
136 -- entry point that is recorded).
138 -- Each entry point must appear as the first statement entry on a CS
139 -- line. Thus, if any simple statement on a CS line is known to have
140 -- been executed, then all statements that appear before it on the same
141 -- CS line are certain to also have been executed.
143 -- The form of a statement line in the ALI file is:
145 -- CS [dominance] *sloc-range [*sloc-range...]
147 -- where each sloc-range corresponds to a single statement, and * is
150 -- t type declaration
151 -- s subtype declaration
152 -- o object declaration
153 -- r renaming declaration
154 -- i generic instantiation
155 -- C CASE statement (from CASE through end of expression)
157 -- F FOR loop (from FOR through end of iteration scheme)
158 -- I IF statement (from IF through end of condition)
159 -- P[name:] PRAGMA with the indicated name
160 -- p[name:] disabled PRAGMA with the indicated name
161 -- R extended RETURN statement
162 -- W WHILE loop statement (from WHILE through end of condition)
164 -- Note: for I and W, condition above is in the RM syntax sense (this
165 -- condition is a decision in SCO terminology).
167 -- and is omitted for all other cases
169 -- The optional dominance marker is of the form gives additional
170 -- information as to how the sequence of statements denoted by the CS
171 -- line can be entered:
174 -- sequence is entered only if the decision at <sloc> is False
176 -- sequence is entered only if the decision at <sloc> is True
179 -- sequence is entered only if the statement at <sloc> has been
183 -- sequence is the sequence of statements for a exception_handler
184 -- with the given sloc range
186 -- Note: up to 6 entries can appear on a single CS line. If more than 6
187 -- entries appear in one logical statement sequence, continuation lines
188 -- are marked by Cs and appear immediately after the CS line.
190 -- Implementation permission: a SCO generator is permitted to emit a
191 -- narrower SLOC range for a statement if the corresponding code
192 -- generation circuitry ensures that all debug information for the code
193 -- implementing the statement will be labeled with SLOCs that fall within
194 -- that narrower range.
198 -- Note: in the following description, logical operator includes only the
199 -- short-circuited forms and NOT (so can be only NOT, AND THEN, OR ELSE).
200 -- The reason that we can exclude AND/OR/XOR is that we expect SCO's to
201 -- be generated using the restriction No_Direct_Boolean_Operators if we
202 -- are interested in decision coverage, which does not permit the use of
203 -- AND/OR/XOR on boolean operands. These are permitted on modular integer
204 -- types, but such operations do not count as decisions in any case. If
205 -- we are generating SCO's only for simple coverage, then we are not
206 -- interested in decisions in any case.
208 -- Note: the reason we include NOT is for informational purposes. The
209 -- presence of NOT does not generate additional coverage obligations,
210 -- but if we know where the NOT's are, the coverage tool can generate
211 -- more accurate diagnostics on uncovered tests.
213 -- A top level boolean expression is a boolean expression that is not an
214 -- operand of a logical operator.
216 -- Decisions are either simple or complex. A simple decision is a top
217 -- level boolean expression that has only one condition and that occurs
218 -- in the context of a control structure in the source program, including
219 -- WHILE, IF, EXIT WHEN, or immediately within an Assert, Check,
220 -- Pre_Condition or Post_Condition pragma, or as the first argument of a
221 -- dyadic pragma Debug. Note that a top level boolean expression with
222 -- only one condition that occurs in any other context, for example as
223 -- right hand side of an assignment, is not considered to be a (simple)
226 -- A complex decision is a top level boolean expression that has more
227 -- than one condition. A complex decision may occur in any boolean
228 -- expression context.
230 -- So for example, if we have
232 -- A, B, C, D : Boolean;
233 -- function F (Arg : Boolean) return Boolean);
235 -- A and then (B or else F (C and then D))
237 -- There are two (complex) decisions here:
239 -- 1. X and then (Y or else Z)
241 -- where X = A, Y = B, and Z = F (C and then D)
245 -- For each decision, a decision line is generated with the form:
247 -- C* sloc expression [chaining]
249 -- Here * is one of the following characters:
251 -- E decision in EXIT WHEN statement
252 -- G decision in entry guard
253 -- I decision in IF statement or conditional expression
254 -- P decision in pragma Assert/Check/Pre_Condition/Post_Condition
255 -- W decision in WHILE iteration scheme
256 -- X decision appearing in some other expression context
258 -- For E, G, I, P, W, sloc is the source location of the EXIT, ENTRY, IF,
259 -- PRAGMA or WHILE token, respectively
261 -- For X, sloc is omitted
263 -- The expression is a prefix polish form indicating the structure of
264 -- the decision, including logical operators and short-circuit forms.
265 -- The following is a grammar showing the structure of expression:
267 -- expression ::= term (if expr is not logical operator)
268 -- expression ::= &sloc term term (if expr is AND or AND THEN)
269 -- expression ::= |sloc term term (if expr is OR or OR ELSE)
270 -- expression ::= !sloc term (if expr is NOT)
272 -- In the last three cases, sloc is the source location of the AND, OR,
273 -- or NOT token, respectively.
276 -- term ::= expression
278 -- element ::= *sloc-range
280 -- where * is one of the following letters:
286 -- t/f are used to mark a condition that has been recognized by the
287 -- compiler as always being true or false. c is the normal case of
288 -- conditions whose value is not known at compile time.
290 -- & indicates AND THEN connecting two conditions
292 -- | indicates OR ELSE connecting two conditions
294 -- ! indicates NOT applied to the expression
296 -- Note that complex decisions do NOT include non-short-circuited logical
297 -- operators (AND/XOR/OR). In the context of existing coverage tools the
298 -- No_Direct_Boolean_Operators restriction is assumed, so these operators
299 -- cannot appear in the source in any case.
301 -- The SCO line for a decision always occurs after the CS line for the
302 -- enclosing statement. The SCO line for a nested decision always occurs
303 -- after the line for the enclosing decision.
305 -- Note that membership tests are considered to be a single simple
306 -- condition, and that is true even if the Ada 2005 set membership
307 -- form is used, e.g. A in (2,7,11.15).
309 -- The expression can be followed by chaining indicators of the form
310 -- Tsloc-range or Fsloc-range, where the sloc-range is that of some
311 -- entry on a CS line.
313 -- T* is present when the statement with the given sloc range is executed
314 -- if, and only if, the decision evaluates to TRUE.
316 -- F* is present when the statement with the given sloc range is executed
317 -- if, and only if, the decision evaluates to FALSE.
319 -- For an IF statement or ELSIF part, a T chaining indicator is always
320 -- present, with the sloc range of the first statement in the
321 -- corresponding sequence.
323 -- For an ELSE part, the last decision in the IF statement (that of the
324 -- last ELSIF part, if any, or that of the IF statement if there is no
325 -- ELSIF part) has an F chaining indicator with the sloc range of the
326 -- first statement in the sequence of the ELSE part.
328 -- For a WHILE loop, a T chaining indicator is always present, with the
329 -- sloc range of the first statement in the loop, but no F chaining
330 -- indicator is ever present.
332 -- For an EXIT WHEN statement, an F chaining indicator is present if
333 -- there is an immediately following sequence in the same sequence of
336 -- In all other cases, chaining indicators are omitted
338 -- Implementation permission: a SCO generator is permitted to emit a
339 -- narrower SLOC range for a condition if the corresponding code
340 -- generation circuitry ensures that all debug information for the code
341 -- evaluating the condition will be labeled with SLOCs that fall within
342 -- that narrower range.
346 -- For case statements, we rely on statement coverage to make sure that
347 -- all branches of a case statement are covered, but that does not work
348 -- for case expressions, since the entire expression is contained in a
349 -- single statement. However, for complete coverage we really should be
350 -- able to check that every branch of the case statement is covered, so
351 -- we generate a SCO of the form:
353 -- CC sloc-range sloc-range ...
355 -- where sloc-range covers the range of the case expression
357 -- Note: up to 6 entries can appear on a single CC line. If more than 6
358 -- entries appear in one logical statement sequence, continuation lines
359 -- are marked by Cc and appear immediately after the CC line.
363 -- No SCO is generated for disabled pragmas
365 ---------------------------------------------------------------------
366 -- Internal table used to store Source Coverage Obligations (SCOs) --
367 ---------------------------------------------------------------------
369 type Source_Location is record
370 Line : Logical_Line_Number;
374 No_Source_Location : Source_Location := (No_Line_Number, No_Column_Number);
376 type SCO_Table_Entry is record
377 From : Source_Location := No_Source_Location;
378 To : Source_Location := No_Source_Location;
379 C1 : Character := ' ';
380 C2 : Character := ' ';
381 Last : Boolean := False;
383 Pragma_Sloc : Source_Ptr := No_Location;
384 -- For the statement SCO for a pragma, or for any expression SCO nested
385 -- in a pragma Debug/Assert/PPC, location of PRAGMA token (used for
386 -- control of SCO output, value not recorded in ALI file).
388 Pragma_Name : Pragma_Id := Unknown_Pragma;
389 -- For the statement SCO for a pragma, gives the pragma name
392 package SCO_Table is new GNAT.Table (
393 Table_Component_Type => SCO_Table_Entry,
394 Table_Index_Type => Nat,
395 Table_Low_Bound => 1,
396 Table_Initial => 500,
397 Table_Increment => 300);
399 -- The SCO_Table_Entry values appear as follows:
403 -- C2 = statement type code to appear on CS line (or ' ' if none)
404 -- From = starting source location
405 -- To = ending source location
406 -- Last = False for all but the last entry, True for last entry
408 -- Note: successive statements (possibly interspersed with entries of
409 -- other kinds, that are ignored for this purpose), starting with one
410 -- labeled with C1 = 'S', up to and including the first one labeled with
411 -- Last = True, indicate the sequence to be output for a sequence of
412 -- statements on a single CS line (possibly followed by Cs continuation
415 -- Note: for a pragma that may be disabled (Debug, Assert, PPC, Check),
416 -- the entry is initially created with C2 = 'p', to mark it as disabled.
417 -- Later on during semantic analysis, if the pragma is enabled,
418 -- Set_SCO_Pragma_Enabled changes C2 to 'P' to cause the entry to be
419 -- emitted in Put_SCOs.
423 -- C2 = 'F'/'T'/'S'/'E'
424 -- From = Decision/statement sloc ('F'/'T'/'S'),
425 -- handler first sloc ('E')
426 -- To = No_Source_Location ('F'/'T'/'S'), handler last sloc ('E')
428 -- Note: A dominance marker is always followed by a statement entry
430 -- Decision (EXIT/entry guard/IF/WHILE)
431 -- C1 = 'E'/'G'/'I'/'W' (for EXIT/entry Guard/IF/WHILE)
433 -- From = EXIT/ENTRY/IF/WHILE token
434 -- To = No_Source_Location
440 -- From = PRAGMA token
441 -- To = No_Source_Location
444 -- Note: when the parse tree is first scanned, we unconditionally build a
445 -- pragma decision entry for any decision in a pragma (here as always in
446 -- SCO contexts, the only pragmas with decisions are Assert, Check,
447 -- dyadic Debug, Precondition and Postcondition). These entries will
448 -- be omitted in output if the pragma is disabled (see comments for
449 -- statement entries).
451 -- Decision (Expression)
454 -- From = No_Source_Location
455 -- To = No_Source_Location
459 -- C1 = '!', '&', '|'
461 -- From = location of NOT/AND/OR token
462 -- To = No_Source_Location
465 -- Element (condition)
467 -- C2 = 'c', 't', or 'f' (condition/true/false)
468 -- From = starting source location
469 -- To = ending source location
470 -- Last = False for all but the last entry, True for last entry
472 -- Element (chaining indicator)
474 -- C2 = 'T' or 'F' (chaining on decision true/false)
475 -- From = starting source location of chained statement
476 -- To = ending source location of chained statement
478 -- Note: the sequence starting with a decision, and continuing with
479 -- operators and elements up to and including the first one labeled with
480 -- Last = True, indicate the sequence to be output on one decision line.
486 -- This table keeps track of the units and the corresponding starting and
487 -- ending indexes (From, To) in the SCO table. Note that entry zero is
488 -- present but unused, it is for convenience in calling the sort routine.
489 -- Thus the lower bound for real entries is 1.
491 type SCO_Unit_Index is new Int;
492 -- Used to index values in this table. Values start at 1 and are assigned
493 -- sequentially as entries are constructed.
495 type SCO_Unit_Table_Entry is record
496 File_Name : String_Ptr;
497 -- Pointer to file name in ALI file
500 -- Dependency number in ALI file
503 -- Starting index in SCO_Table of SCO information for this unit
506 -- Ending index in SCO_Table of SCO information for this unit
509 package SCO_Unit_Table is new GNAT.Table (
510 Table_Component_Type => SCO_Unit_Table_Entry,
511 Table_Index_Type => SCO_Unit_Index,
512 Table_Low_Bound => 0, -- see note above on sorting
514 Table_Increment => 200);
520 procedure Initialize;
521 -- Reset tables for a new compilation