gcc/ada/scos.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                                 S C O S                                  --
   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 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.
  30
  31 with Types; use Types;
  32
  33 with GNAT.Table;
  34
  35 package SCOs is
  36
  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.
  41
  42    --  Par_SCO is part of the compiler. It scans the parsed source tree and
  43    --  populates the internal tables.
  44
  45    --  Get_SCO reads the text lines in ALI format and populates the internal
  46    --  tables with corresponding information.
  47
  48    --  Put_SCO reads the internal tables and generates text lines in the ALI
  49    --  format.
  50
  51    --------------------
  52    -- SCO ALI Format --
  53    --------------------
  54
  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 -gnatC switch is set.
  58
  59    --  Sloc Ranges
  60
  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:
  64
  65    --      line:col-line:col
  66
  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.
  70
  71    --  SCO File headers
  72
  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:
  77
  78    --      C  dependency-number  filename
  79
  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).
  84
  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).
  88
  89    --  Statements
  90
  91    --    For the purpose of SCO generation, the notion of statement includes
  92    --    simple statements and also the following declaration types:
  93
  94    --      type_declaration
  95    --      subtype_declaration
  96    --      object_declaration
  97    --      renaming_declaration
  98    --      generic_instantiation
  99
 100    --  Statement lines
 101
 102    --    These lines correspond to a sequence of one or more statements which
 103    --    are always exeecuted in sequence, The first statement may be an entry
 104    --    point (e.g. statement after a label), and the last statement may be
 105    --    an exit point (e.g. an exit statement), but no other entry or exit
 106    --    points may occur within the sequence of statements. The idea is that
 107    --    the sequence can be treated as a single unit from a coverage point of
 108    --    view, if any of the code for the statement sequence is executed, this
 109    --    corresponds to coverage of the entire statement sequence. The form of
 110    --    a statement line in the ALI file is:
 111
 112    --      CS sloc-range
 113
 114    --  Exit points
 115
 116    --    An exit point is a statement that causes transfer of control. Examples
 117    --    are exit statements, raise statements and return statements. The form
 118    --    of an exit point in the ALI file is:
 119
 120    --      CT sloc-range
 121
 122    --  Decisions
 123
 124    --    Decisions represent the most significant section of the SCO lines
 125
 126    --    Note: in the following description, logical operator includes the
 127    --    short circuited forms (so can be any of AND, OR, XOR, NOT, AND THEN,
 128    --    or OR ELSE).
 129
 130    --    Decisions are either simple or complex. A simple decision is a boolean
 131    --    expresssion that occurs in the context of a control structure in the
 132    --    source program, including WHILE, IF, EXIT WHEN. Note that a boolean
 133    --    expression in any other context, for example, on the right side of an
 134    --    assignment, is not considered to be a decision.
 135
 136    --    A complex decision is an occurrence of a logical operator which is not
 137    --    itself an operand of some other logical operator. If any operand of
 138    --    the logical operator is itself a logical operator, this is not a
 139    --    separate decision, it is part of the same decision.
 140
 141    --    So for example, if we have
 142
 143    --        A, B, C, D : Boolean;
 144    --        function F (Arg : Boolean) return Boolean);
 145    --        ...
 146    --        A and then (B or else F (C and then D))
 147
 148    --    There are two (complex) decisions here:
 149
 150    --        1. X and then (Y or else Z)
 151
 152    --           where X = A, Y = B, and Z = F (C and then D)
 153
 154    --        2. C and then D
 155
 156    --    For each decision, a decision line is generated with the form:
 157
 158    --      C* expression
 159
 160    --    Here * is one of the following characters:
 161
 162    --      I  decision in IF statement or conditional expression
 163    --      E  decision in EXIT WHEN statement
 164    --      W  decision in WHILE iteration scheme
 165    --      X  decision appearing in some other expression context
 166
 167    --    The expression is a prefix polish form indicating the structure of
 168    --    the decision, including logical operators and short circuit forms.
 169    --    The following is a grammar showing the structure of expression:
 170
 171    --      expression ::= term             (if expr is not logical operator)
 172    --      expression ::= & term term      (if expr is AND or AND THEN)
 173    --      expression ::= | term term      (if expr is OR or OR ELSE)
 174    --      expression ::= ^ term term      (if expr is XOR)
 175    --      expression ::= !term            (if expr is NOT)
 176
 177    --      term ::= element
 178    --      term ::= expression
 179
 180    --      element ::= outcome sloc-range
 181
 182    --    outcome is one of the following letters:
 183
 184    --      c  condition
 185    --      t  true condition
 186    --      f  false condition
 187
 188    --      where t/f are used to mark a condition that has been recognized by
 189    --      the compiler as always being true or false.
 190
 191    --    & indicates either AND or AND THEN connecting two conditions. In the
 192    --    context of couverture we only permit AND THEN in the source in any
 193    --    case, so & can always be understood to be AND THEN.
 194
 195    --    | indicates either OR or OR ELSE connection two conditions. In the
 196    --    context of couverture we only permit OR ELSE in the source in any
 197    --    case, so | can always be understood to be OR ELSE.
 198
 199    --    ^ indicates XOR connecting two conditions. In the context of
 200    --    couverture, we do not permit XOR, so this will never appear.
 201
 202    --    ! indicates NOT applied to the expression.
 203
 204    ---------------------------------------------------------------------
 205    -- Internal table used to store Source Coverage Obligations (SCOs) --
 206    ---------------------------------------------------------------------
 207
 208    type Source_Location is record
 209       Line : Logical_Line_Number;
 210       Col  : Column_Number;
 211    end record;
 212
 213    No_Source_Location : Source_Location := (No_Line_Number, No_Column_Number);
 214
 215    type SCO_Table_Entry is record
 216       From : Source_Location;
 217       To   : Source_Location;
 218       C1   : Character;
 219       C2   : Character;
 220       Last : Boolean;
 221    end record;
 222
 223    package SCO_Table is new GNAT.Table (
 224      Table_Component_Type => SCO_Table_Entry,
 225      Table_Index_Type     => Nat,
 226      Table_Low_Bound      => 1,
 227      Table_Initial        => 500,
 228      Table_Increment      => 300);
 229
 230    --  The SCO_Table_Entry values appear as follows:
 231
 232    --    Statements
 233    --      C1   = 'S'
 234    --      C2   = ' '
 235    --      From = starting source location
 236    --      To   = ending source location
 237    --      Last = unused
 238
 239    --    Exit
 240    --      C1   = 'T'
 241    --      C2   = ' '
 242    --      From = starting source location
 243    --      To   = ending source location
 244    --      Last = unused
 245
 246    --    Simple Decision
 247    --      C1   = 'I', 'E', 'W', 'X' (if/exit/while/expression)
 248    --      C2   = 'c', 't', or 'f'
 249    --      From = starting source location
 250    --      To   = ending source location
 251    --      Last = True
 252
 253    --    Complex Decision
 254    --      C1   = 'I', 'E', 'W', 'X' (if/exit/while/expression)
 255    --      C2   = ' '
 256    --      From = No_Location
 257    --      To   = No_Location
 258    --      Last = False
 259
 260    --    Operator
 261    --      C1   = '!', '^', '&', '|'
 262    --      C2   = ' '
 263    --      From = No_Location
 264    --      To   = No_Location
 265    --      Last = False
 266
 267    --    Element
 268    --      C1   = ' '
 269    --      C2   = 'c', 't', or 'f' (condition/true/false)
 270    --      From = starting source location
 271    --      To   = ending source location
 272    --      Last = False for all but the last entry, True for last entry
 273
 274    --    Note: the sequence starting with a decision, and continuing with
 275    --    operators and elements up to and including the first one labeled with
 276    --    Last=True, indicate the sequence to be output for a complex decision
 277    --    on a single CD decision line.
 278
 279    ----------------
 280    -- Unit Table --
 281    ----------------
 282
 283    --  This table keeps track of the units and the corresponding starting and
 284    --  ending indexes (From, To) in the SCO table. Note that entry zero is
 285    --  unused, it is for convenience in calling the sort routine. Thus the
 286    --  real lower bound for active entries is 1.
 287
 288    type SCO_Unit_Index is new Int;
 289    --  Used to index values in this table. Values start at 1 and are assigned
 290    --  sequentially as entries are constructed.
 291
 292    type SCO_Unit_Table_Entry is record
 293       File_Name : String_Ptr;
 294       --  Pointer to file name in ALI file
 295
 296       Dep_Num : Nat;
 297       --  Dependency number in ALI file
 298
 299       From : Nat;
 300       --  Starting index in SCO_Table of SCO information for this unit
 301
 302       To : Nat;
 303       --  Ending index in SCO_Table of SCO information for this unit
 304    end record;
 305
 306    package SCO_Unit_Table is new GNAT.Table (
 307      Table_Component_Type => SCO_Unit_Table_Entry,
 308      Table_Index_Type     => SCO_Unit_Index,
 309      Table_Low_Bound      => 0, -- see note above on sorting
 310      Table_Initial        => 20,
 311      Table_Increment      => 200);
 312
 313    -----------------
 314    -- Subprograms --
 315    -----------------
 316
 317    procedure Initialize;
 318    --  Reset tables for a new compilation
 319
 320    procedure Add_SCO
 321      (From : Source_Location := No_Source_Location;
 322       To   : Source_Location := No_Source_Location;
 323       C1   : Character       := ' ';
 324       C2   : Character       := ' ';
 325       Last : Boolean         := False);
 326    --  Adds one entry to SCO table with given field values
 327
 328 end SCOs;