gcc/ada/par_sco.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              P A R _ S C O                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --             Copyright (C) 2009, 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 ------------------------------------------------------------------------------
  25
  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.
  28
  29 with Types; use Types;
  30
  31 package Par_SCO is
  32
  33    ----------------
  34    -- SCO Format --
  35    ----------------
  36
  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.
  40
  41    --  Sloc Ranges
  42
  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:
  46
  47    --      line:col-line:col
  48
  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.
  52
  53    --  SCO File headers
  54
  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:
  59
  60    --      C  dependency-number  filename
  61
  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).
  66
  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).
  70
  71    --  Statements
  72
  73    --    For the purpose of SCO generation, the notion of statement includes
  74    --    simple statements and also the following declaration types:
  75
  76    --      type_declaration
  77    --      subtype_declaration
  78    --      object_declaration
  79    --      renaming_declaration
  80    --      generic_instantiation
  81
  82    --      ??? is this list complete ???
  83
  84    --    ??? what is the exact story on complex statements such as blocks ???
  85    --    ??? are the simple statements inside sufficient ???
  86
  87    --  Statement lines
  88
  89    --    These lines correspond to a sequence of one or more statements which
  90    --    are always exeecuted in sequence, The first statement may be an entry
  91    --    point (e.g. statement after a label), and the last statement may be
  92    --    an exit point (e.g. an exit statement), but no other entry or exit
  93    --    points may occur within the sequence of statements. The idea is that
  94    --    the sequence can be treated as a single unit from a coverage point of
  95    --    view, if any of the code for the statement sequence is executed, this
  96    --    corresponds to coverage of the entire statement sequence. The form of
  97    --    a statement line in the ALI file is:
  98
  99    --      CS sloc-range
 100
 101    --  Exit points
 102
 103    --    An exit point is a statement that causes transfer of control. Examples
 104    --    are exit statements, raise statements and return statements. The form
 105    --    of an exit point in the ALI file is:
 106
 107    --      CT sloc-range
 108
 109    --  Decisions
 110
 111    --    Decisions represent the most significant section of the SCO lines
 112
 113    --    Note: in the following description, logical operator includes the
 114    --    short circuited forms (so can be any of AND, OR, XOR, NOT, AND THEN,
 115    --    or OR ELSE).
 116
 117    --    Decisions are either simple or complex. A simple decision is a boolean
 118    --    expresssion that occurs in the context of a control structure in the
 119    --    source program, including WHILE, IF, EXIT WHEN. Note that a boolean
 120    --    expression in any other context, e.g. on the right side of an
 121    --    assignment, is not considered to be a decision.
 122
 123    --    A complex decision is an occurrence of a logical operator which is not
 124    --    itself an operand of some other logical operator. If any operand of
 125    --    the logical operator is itself a logical operator, this is not a
 126    --    separate decision, it is part of the same decision.
 127
 128    --    So for example, if we have
 129
 130    --        A, B, C, D : Boolean;
 131    --        function F (Arg : Boolean) return Boolean);
 132    --        ...
 133    --        A and then (B or else F (C and then D))
 134
 135    --    There are two (complex) decisions here:
 136
 137    --        1. X and then (Y or else Z)
 138
 139    --           where X = A, Y = B, and Z = F (C and then D)
 140
 141    --        2. C and then D
 142
 143    --    For each decision, a decision line is generated with the form:
 144
 145    --      C* expression
 146
 147    --    Here * is one of the following characters:
 148
 149    --      I  decision in IF statement or conditional expression
 150    --      E  decision in EXIT WHEN statement
 151    --      W  decision in WHILE iteration scheme
 152    --      X  decision appearing in some other expression context
 153
 154    --    The expression is a prefix polish form indicating the structure of
 155    --    the decision, including logical operators and short circuit forms.
 156    --    The following is a grammar showing the structure of expression:
 157
 158    --      expression ::= term             (if expr is not logical operator)
 159    --      expression ::= & term term      (if expr is AND or AND THEN)
 160    --      expression ::= | term term      (if expr is OR or OR ELSE)
 161    --      expression ::= ^ term term      (if expr is XOR)
 162    --      expression ::= !term            (if expr is NOT)
 163
 164    --      term ::= element
 165    --      term ::= expression
 166
 167    --      element ::= outcome sloc-range
 168
 169    --    outcome is one of the following letters:
 170
 171    --      c  condition
 172    --      t  true condition
 173    --      f  false condition
 174
 175    --      where t/f are used to mark a condition that has been recognized by
 176    --      the compiler as always being true or false.
 177
 178    --    & indicates either AND or AND THEN connecting two conditions. In the
 179    --    context of couverture we only permit AND THEN in the source in any
 180    --    case, so & can always be understood to be AND THEN.
 181
 182    --    | indicates either OR or OR ELSE connection two conditions. In the
 183    --    context of couverture we only permit OR ELSE in the source in any
 184    --    case, so | can always be understood to be OR ELSE.
 185
 186    --    ^ indicates XOR connecting two conditions. In the context of
 187    --    couverture, we do not permit XOR, so this will never appear.
 188
 189    --    ! indicates NOT applied to the expression.
 190
 191    -----------------
 192    -- Subprograms --
 193    -----------------
 194
 195    procedure Initialize;
 196    --  Initialize internal tables for a new compilation
 197
 198    procedure SCO_Record (U : Unit_Number_Type);
 199    --  This procedure scans the tree for the unit identified by U, populating
 200    --  internal tables recording the SCO information. Note that this is done
 201    --  before any semantic analysis/expansion happens.
 202
 203    procedure Set_SCO_Condition (First_Loc : Source_Ptr; Typ : Character);
 204    --  This procedure is called during semantic analysis to record a condition
 205    --  which has been identified as always True (Typ = 't') or always False
 206    --  (Typ = 'f') by the compiler. The condition is identified by the
 207    --  First_Sloc value in the original tree.
 208
 209    procedure SCO_Output;
 210    --  Outputs SCO lines for all units, with appropriate section headers, for
 211    --  unit U in the ALI file, as recorded by previous calls to SCO_Record,
 212    --  possibly modified by calls to Set_SCO_Condition.
 213
 214    procedure dsco;
 215    --  Debug routine to dump SCO table. This is a raw format dump showing
 216    --  exactly what the tables contain.
 217
 218    procedure pscos;
 219    --  Debugging procedure to output contents of SCO binary tables in the
 220    --  format in which they appear in an ALI file.
 221
 222 end Par_SCO;