1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 2009, 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 contains the routines used to deal with generation and output
27 -- of Soure Coverage Obligations (SCO's) used for coverage analysis purposes.
29 with Types; use Types;
37 -- Source coverage obligations are generated on a unit-by-unit basis in the
38 -- ALI file, using lines that start with the identifying character C. These
39 -- lines are generated if the -gnatC switch is set.
43 -- In several places in the SCO lines, Sloc ranges appear. These are used
44 -- to indicate the first and last Sloc of some construct in the tree and
45 -- they have the form:
49 -- Note that SCO's are generated only for generic templates, not for
50 -- generic instances (since only the first are part of the source). So
51 -- we don't need generic instantiation stuff in these line:col items.
55 -- The SCO information follows the cross-reference information, so it
56 -- need not be read by tools like gnatbind, gnatmake etc. The SCO output
57 -- is divided into sections, one section for each unit for which SCO's
58 -- are generated. A SCO section has a header of the form:
60 -- C dependency-number filename
62 -- This header precedes SCO information for the unit identified by
63 -- dependency number and file name. The dependency number is the
64 -- index into the generated D lines and is ones origin (i.e. 2 =
65 -- reference to second generated D line).
67 -- Note that the filename here will reflect the original name if
68 -- a Source_Reference pragma was encountered (since all line number
69 -- references will be with respect to the original file).
73 -- For the purpose of SCO generation, the notion of statement includes
74 -- simple statements and also the following declaration types:
77 -- subtype_declaration
79 -- renaming_declaration
80 -- generic_instantiation
84 -- These lines correspond to a sequence of one or more statements which
85 -- are always exeecuted in sequence, The first statement may be an entry
86 -- point (e.g. statement after a label), and the last statement may be
87 -- an exit point (e.g. an exit statement), but no other entry or exit
88 -- points may occur within the sequence of statements. The idea is that
89 -- the sequence can be treated as a single unit from a coverage point of
90 -- view, if any of the code for the statement sequence is executed, this
91 -- corresponds to coverage of the entire statement sequence. The form of
92 -- a statement line in the ALI file is:
98 -- An exit point is a statement that causes transfer of control. Examples
99 -- are exit statements, raise statements and return statements. The form
100 -- of an exit point in the ALI file is:
106 -- Decisions represent the most significant section of the SCO lines
108 -- Note: in the following description, logical operator includes the
109 -- short circuited forms (so can be any of AND, OR, XOR, NOT, AND THEN,
112 -- Decisions are either simple or complex. A simple decision is a boolean
113 -- expresssion that occurs in the context of a control structure in the
114 -- source program, including WHILE, IF, EXIT WHEN. Note that a boolean
115 -- expression in any other context, e.g. on the right side of an
116 -- assignment, is not considered to be a decision.
118 -- A complex decision is an occurrence of a logical operator which is not
119 -- itself an operand of some other logical operator. If any operand of
120 -- the logical operator is itself a logical operator, this is not a
121 -- separate decision, it is part of the same decision.
123 -- So for example, if we have
125 -- A, B, C, D : Boolean;
126 -- function F (Arg : Boolean) return Boolean);
128 -- A and then (B or else F (C and then D))
130 -- There are two (complex) decisions here:
132 -- 1. X and then (Y or else Z)
134 -- where X = A, Y = B, and Z = F (C and then D)
138 -- For each decision, a decision line is generated with the form:
142 -- Here * is one of the following characters:
144 -- I decision in IF statement or conditional expression
145 -- E decision in EXIT WHEN statement
146 -- W decision in WHILE iteration scheme
147 -- X decision appearing in some other expression context
149 -- The expression is a prefix polish form indicating the structure of
150 -- the decision, including logical operators and short circuit forms.
151 -- The following is a grammar showing the structure of expression:
153 -- expression ::= term (if expr is not logical operator)
154 -- expression ::= & term term (if expr is AND THEN)
155 -- expression ::= | term term (if expr is OR ELSE)
156 -- expression ::= !term (if expr is NOT)
159 -- term ::= expression
161 -- element ::= outcome sloc-range
163 -- outcome is one of the following letters:
169 -- where t/f are used to mark a condition that has been recognized by
170 -- the compiler as always being true or false.
172 -- & indicates either AND THEN connecting two conditions
174 -- | indicates either OR ELSE connection two conditions
176 -- ! indicates NOT applied to the expression
182 procedure Initialize;
183 -- Initialize internal tables for a new compilation
185 procedure SCO_Record (U : Unit_Number_Type);
186 -- This procedure scans the tree for the unit identified by U, populating
187 -- internal tables recording the SCO information. Note that this is done
188 -- before any semantic analysis/expansion happens.
190 procedure Set_SCO_Condition (First_Loc : Source_Ptr; Typ : Character);
191 -- This procedure is called during semantic analysis to record a condition
192 -- which has been identified as always True (Typ = 't') or always False
193 -- (Typ = 'f') by the compiler. The condition is identified by the
194 -- First_Sloc value in the original tree.
196 procedure SCO_Output;
197 -- Outputs SCO lines for all units, with appropriate section headers, for
198 -- unit U in the ALI file, as recorded by previous calls to SCO_Record,
199 -- possibly modified by calls to Set_SCO_Condition.
202 -- Debug routine to dump SCO table. This is a raw format dump showing
203 -- exactly what the tables contain.
206 -- Debugging procedure to output contents of SCO binary tables in the
207 -- format in which they appear in an ALI file.