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