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    --  Statement lines
  83
  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:
  93
  94    --      CS sloc-range
  95
  96    --  Exit points
  97
  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:
 101
 102    --      CT sloc-range
 103
 104    --  Decisions
 105
 106    --    Decisions represent the most significant section of the SCO lines
 107
 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,
 110    --    or OR ELSE).
 111
 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.
 117
 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.
 122
 123    --    So for example, if we have
 124
 125    --        A, B, C, D : Boolean;
 126    --        function F (Arg : Boolean) return Boolean);
 127    --        ...
 128    --        A and then (B or else F (C and then D))
 129
 130    --    There are two (complex) decisions here:
 131
 132    --        1. X and then (Y or else Z)
 133
 134    --           where X = A, Y = B, and Z = F (C and then D)
 135
 136    --        2. C and then D
 137
 138    --    For each decision, a decision line is generated with the form:
 139
 140    --      C* expression
 141
 142    --    Here * is one of the following characters:
 143
 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
 148
 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:
 152
 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)
 157
 158    --      term ::= element
 159    --      term ::= expression
 160
 161    --      element ::= outcome sloc-range
 162
 163    --    outcome is one of the following letters:
 164
 165    --      c  condition
 166    --      t  true condition
 167    --      f  false condition
 168
 169    --      where t/f are used to mark a condition that has been recognized by
 170    --      the compiler as always being true or false.
 171
 172    --    & indicates either AND THEN connecting two conditions
 173
 174    --    | indicates either OR ELSE connection two conditions
 175
 176    --    ! indicates NOT applied to the expression
 177
 178    -----------------
 179    -- Subprograms --
 180    -----------------
 181
 182    procedure Initialize;
 183    --  Initialize internal tables for a new compilation
 184
 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.
 189
 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.
 195
 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.
 200
 201    procedure dsco;
 202    --  Debug routine to dump SCO table. This is a raw format dump showing
 203    --  exactly what the tables contain.
 204
 205    procedure pscos;
 206    --  Debugging procedure to output contents of SCO binary tables in the
 207    --  format in which they appear in an ALI file.
 208
 209 end Par_SCO;