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-2011, 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 Snames; use Snames;
  32 --  Note: used for Pragma_Id only, no other feature from Snames should be used,
  33 --  as a simplified version is maintained in Xcov.
  34
  35 with Types;  use Types;
  36
  37 with GNAT.Table;
  38
  39 package SCOs is
  40
  41    --  SCO information can exist in one of two forms. In the ALI file, it is
  42    --  represented using a text format that is described in this specification.
  43    --  Internally it is stored using two tables SCO_Table and SCO_Unit_Table,
  44    --  which are also defined in this unit.
  45
  46    --  Par_SCO is part of the compiler. It scans the parsed source tree and
  47    --  populates the internal tables.
  48
  49    --  Get_SCO reads the text lines in ALI format and populates the internal
  50    --  tables with corresponding information.
  51
  52    --  Put_SCO reads the internal tables and generates text lines in the ALI
  53    --  format.
  54
  55    --------------------
  56    -- SCO ALI Format --
  57    --------------------
  58
  59    --  Source coverage obligations are generated on a unit-by-unit basis in the
  60    --  ALI file, using lines that start with the identifying character C. These
  61    --  lines are generated if the -gnateS switch is set.
  62
  63    --  Sloc Ranges
  64
  65    --    In several places in the SCO lines, Sloc ranges appear. These are used
  66    --    to indicate the first and last Sloc of some construct in the tree and
  67    --    they have the form:
  68
  69    --      line:col-line:col
  70
  71    --    Note that SCO's are generated only for generic templates, not for
  72    --    generic instances (since only the first are part of the source). So
  73    --    we don't need generic instantiation stuff in these line:col items.
  74
  75    --  SCO File headers
  76
  77    --    The SCO information follows the cross-reference information, so it
  78    --    need not be read by tools like gnatbind, gnatmake etc. The SCO output
  79    --    is divided into sections, one section for each unit for which SCO's
  80    --    are generated. A SCO section has a header of the form:
  81
  82    --      C dependency-number filename
  83
  84    --        This header precedes SCO information for the unit identified by
  85    --        dependency number and file name. The dependency number is the
  86    --        index into the generated D lines and is ones origin (i.e. 2 =
  87    --        reference to second generated D line).
  88
  89    --        Note that the filename here will reflect the original name if
  90    --        a Source_Reference pragma was encountered (since all line number
  91    --        references will be with respect to the original file).
  92
  93    --        Note: the filename is redundant in that it could be deduced from
  94    --        the corresponding D line, but it is convenient at least for human
  95    --        reading of the SCO information, and means that the SCO information
  96    --        can stand on its own without needing other parts of the ALI file.
  97
  98    --  Statements
  99
 100    --    For the purpose of SCO generation, the notion of statement includes
 101    --    simple statements and also the following declaration types:
 102
 103    --      type_declaration
 104    --      subtype_declaration
 105    --      object_declaration
 106    --      renaming_declaration
 107    --      generic_instantiation
 108
 109    --    and the following regions of the syntax tree:
 110
 111    --      the part of a case_statement from CASE up to the expression
 112    --      the part of a FOR loop iteration scheme from FOR up to the
 113    --        loop_parameter_specification
 114    --      the part of a WHILE loop up to the condition
 115    --      the part of an extended_return_statement from RETURN up to the
 116    --        expression (if present) or to the return_subtype_indication (if
 117    --        no expression)
 118
 119    --    and any pragma that occurs at a place where a statement or declaration
 120    --    is allowed.
 121
 122    --  Statement lines
 123
 124    --    These lines correspond to one or more successive statements (in the
 125    --    sense of the above list) which are always executed in sequence (in the
 126    --    absence of exceptions or other external interruptions).
 127
 128    --    Entry points to such sequences are:
 129
 130    --      the first declaration of any declarative_part
 131    --      the first statement of any sequence_of_statements that is not in a
 132    --        body or block statement that has a non-empty declarative part
 133    --      the first statement after a compound statement
 134    --      the first statement after an EXIT, RAISE or GOTO statement
 135    --      any statement with a label (the label itself is not part of the
 136    --       entry point that is recorded).
 137
 138    --    Each entry point must appear as the first entry on a CS line.
 139    --    The idea is that if any simple statement on a CS line is known to have
 140    --    been executed, then all statements that appear before it on the same
 141    --    CS line are certain to also have been executed.
 142
 143    --    The form of a statement line in the ALI file is:
 144
 145    --      CS *sloc-range [*sloc-range...]
 146
 147    --    where each sloc-range corresponds to a single statement, and * is
 148    --    one of:
 149
 150    --      t        type declaration
 151    --      s        subtype declaration
 152    --      o        object declaration
 153    --      r        renaming declaration
 154    --      i        generic instantiation
 155    --      C        CASE statement (from CASE through end of expression)
 156    --      E        EXIT statement
 157    --      F        FOR loop (from FOR through end of iteration scheme)
 158    --      I        IF statement (from IF through end of condition)
 159    --      P[name:] PRAGMA with the indicated name
 160    --      R        extended RETURN statement
 161    --      W        WHILE loop statement (from WHILE through end of condition)
 162
 163    --      Note: for I and W, condition above is in the RM syntax sense (this
 164    --      condition is a decision in SCO terminology).
 165
 166    --    and is omitted for all other cases
 167
 168    --    Note: up to 6 entries can appear on a single CS line. If more than 6
 169    --    entries appear in one logical statement sequence, continuation lines
 170    --    are marked by Cs and appear immediately after the CS line.
 171
 172    --    Implementation permission: a SCO generator is permitted to emit a
 173    --    narrower SLOC range for a statement if the corresponding code
 174    --    generation circuitry ensures that all debug information for the code
 175    --    implementing the statement will be labeled with SLOCs that fall within
 176    --    that narrower range.
 177
 178    --  Decisions
 179
 180    --    Note: in the following description, logical operator includes only the
 181    --    short-circuited forms and NOT (so can be only NOT, AND THEN, OR ELSE).
 182    --    The reason that we can exclude AND/OR/XOR is that we expect SCO's to
 183    --    be generated using the restriction No_Direct_Boolean_Operators if we
 184    --    are interested in decision coverage, which does not permit the use of
 185    --    AND/OR/XOR on boolean operands. These are permitted on modular integer
 186    --    types, but such operations do not count as decisions in any case. If
 187    --    we are generating SCO's only for simple coverage, then we are not
 188    --    interested in decisions in any case.
 189
 190    --    Note: the reason we include NOT is for informational purposes. The
 191    --    presence of NOT does not generate additional coverage obligations,
 192    --    but if we know where the NOT's are, the coverage tool can generate
 193    --    more accurate diagnostics on uncovered tests.
 194
 195    --    A top level boolean expression is a boolean expression that is not an
 196    --    operand of a logical operator.
 197
 198    --    Decisions are either simple or complex. A simple decision is a top
 199    --    level boolean expression that has only one condition and that occurs
 200    --    in the context of a control structure in the source program, including
 201    --    WHILE, IF, EXIT WHEN, or immediately within an Assert, Check,
 202    --    Pre_Condition or Post_Condition pragma, or as the first argument of a
 203    --    dyadic pragma Debug. Note that a top level boolean expression with
 204    --    only one condition that occurs in any other context, for example as
 205    --    right hand side of an assignment, is not considered to be a (simple)
 206    --    decision.
 207
 208    --    A complex decision is a top level boolean expression that has more
 209    --    than one condition. A complex decision may occur in any boolean
 210    --    expression context.
 211
 212    --    So for example, if we have
 213
 214    --        A, B, C, D : Boolean;
 215    --        function F (Arg : Boolean) return Boolean);
 216    --        ...
 217    --        A and then (B or else F (C and then D))
 218
 219    --    There are two (complex) decisions here:
 220
 221    --        1. X and then (Y or else Z)
 222
 223    --           where X = A, Y = B, and Z = F (C and then D)
 224
 225    --        2. C and then D
 226
 227    --    For each decision, a decision line is generated with the form:
 228
 229    --      C* sloc expression [chaining]
 230
 231    --    Here * is one of the following characters:
 232
 233    --      E  decision in EXIT WHEN statement
 234    --      G  decision in entry guard
 235    --      I  decision in IF statement or conditional expression
 236    --      P  decision in pragma Assert/Check/Pre_Condition/Post_Condition
 237    --      W  decision in WHILE iteration scheme
 238    --      X  decision appearing in some other expression context
 239
 240    --    For E, G, I, P, W, sloc is the source location of the EXIT, ENTRY, IF,
 241    --    PRAGMA or WHILE token, respectively
 242
 243    --    For X, sloc is omitted
 244
 245    --    The expression is a prefix polish form indicating the structure of
 246    --    the decision, including logical operators and short-circuit forms.
 247    --    The following is a grammar showing the structure of expression:
 248
 249    --      expression ::= term             (if expr is not logical operator)
 250    --      expression ::= &sloc term term  (if expr is AND or AND THEN)
 251    --      expression ::= |sloc term term  (if expr is OR or OR ELSE)
 252    --      expression ::= !sloc term       (if expr is NOT)
 253
 254    --      In the last three cases, sloc is the source location of the AND, OR,
 255    --      or NOT token, respectively.
 256
 257    --      term ::= element
 258    --      term ::= expression
 259
 260    --      element ::= *sloc-range
 261
 262    --    where * is one of the following letters:
 263
 264    --      c  condition
 265    --      t  true condition
 266    --      f  false condition
 267
 268    --      t/f are used to mark a condition that has been recognized by the
 269    --      compiler as always being true or false. c is the normal case of
 270    --      conditions whose value is not known at compile time.
 271
 272    --    & indicates AND THEN connecting two conditions
 273
 274    --    | indicates OR ELSE connecting two conditions
 275
 276    --    ! indicates NOT applied to the expression
 277
 278    --    Note that complex decisions do NOT include non-short-circuited logical
 279    --    operators (AND/XOR/OR). In the context of existing coverage tools the
 280    --    No_Direct_Boolean_Operators restriction is assumed, so these operators
 281    --    cannot appear in the source in any case.
 282
 283    --    The SCO line for a decision always occurs after the CS line for the
 284    --    enclosing statement. The SCO line for a nested decision always occurs
 285    --    after the line for the enclosing decision.
 286
 287    --    Note that membership tests are considered to be a single simple
 288    --    condition, and that is true even if the Ada 2005 set membership
 289    --    form is used, e.g. A in (2,7,11.15).
 290
 291    --    The expression can be followed by chaining indicators of the form
 292    --    Tsloc-range or Fsloc-range, where the sloc-range is that of some
 293    --    entry on a CS line.
 294
 295    --    T* is present when the statement with the given sloc range is executed
 296    --    if, and only if, the decision evaluates to TRUE.
 297
 298    --    F* is present when the statement with the given sloc range is executed
 299    --    if, and only if, the decision evaluates to FALSE.
 300
 301    --    For an IF statement or ELSIF part, a T chaining indicator is always
 302    --    present, with the sloc range of the first statement in the
 303    --    corresponding sequence.
 304
 305    --    For an ELSE part, the last decision in the IF statement (that of the
 306    --    last ELSIF part, if any, or that of the IF statement if there is no
 307    --    ELSIF part) has an F chaining indicator with the sloc range of the
 308    --    first statement in the sequence of the ELSE part.
 309
 310    --    For a WHILE loop, a T chaining indicator is always present, with the
 311    --    sloc range of the first statement in the loop, but no F chaining
 312    --    indicator is ever present.
 313
 314    --    For an EXIT WHEN statement, an F chaining indicator is present if
 315    --    there is an immediately following sequence in the same sequence of
 316    --    statements.
 317
 318    --    In all other cases, chaining indicators are omitted
 319
 320    --    Implementation permission: a SCO generator is permitted to emit a
 321    --    narrower SLOC range for a condition if the corresponding code
 322    --    generation circuitry ensures that all debug information for the code
 323    --    evaluating the condition will be labeled with SLOCs that fall within
 324    --    that narrower range.
 325
 326    --  Case Expressions
 327
 328    --    For case statements, we rely on statement coverage to make sure that
 329    --    all branches of a case statement are covered, but that does not work
 330    --    for case expressions, since the entire expression is contained in a
 331    --    single statement. However, for complete coverage we really should be
 332    --    able to check that every branch of the case statement is covered, so
 333    --    we generate a SCO of the form:
 334
 335    --      CC sloc-range sloc-range ...
 336
 337    --    where sloc-range covers the range of the case expression
 338
 339    --    Note: up to 6 entries can appear on a single CC line. If more than 6
 340    --    entries appear in one logical statement sequence, continuation lines
 341    --    are marked by Cc and appear immediately after the CC line.
 342
 343    --  Disabled pragmas
 344
 345    --    No SCO is generated for disabled pragmas
 346
 347    ---------------------------------------------------------------------
 348    -- Internal table used to store Source Coverage Obligations (SCOs) --
 349    ---------------------------------------------------------------------
 350
 351    type Source_Location is record
 352       Line : Logical_Line_Number;
 353       Col  : Column_Number;
 354    end record;
 355
 356    No_Source_Location : Source_Location := (No_Line_Number, No_Column_Number);
 357
 358    type SCO_Table_Entry is record
 359       From : Source_Location := No_Source_Location;
 360       To   : Source_Location := No_Source_Location;
 361       C1   : Character       := ' ';
 362       C2   : Character       := ' ';
 363       Last : Boolean         := False;
 364
 365       Pragma_Sloc : Source_Ptr := No_Location;
 366       --  For the statement SCO for a pragma, or for any expression SCO nested
 367       --  in a pragma Debug/Assert/PPC, location of PRAGMA token (used for
 368       --  control of SCO output, value not recorded in ALI file).
 369
 370       Pragma_Name : Pragma_Id := Unknown_Pragma;
 371       --  For the statement SCO for a pragma, gives the pragma name
 372    end record;
 373
 374    package SCO_Table is new GNAT.Table (
 375      Table_Component_Type => SCO_Table_Entry,
 376      Table_Index_Type     => Nat,
 377      Table_Low_Bound      => 1,
 378      Table_Initial        => 500,
 379      Table_Increment      => 300);
 380
 381    --  The SCO_Table_Entry values appear as follows:
 382
 383    --    Statements
 384    --      C1   = 'S' for entry point, 's' otherwise
 385    --      C2   = statement type code to appear on CS line (or ' ' if none)
 386    --      From = starting source location
 387    --      To   = ending source location
 388    --      Last = False for all but the last entry, True for last entry
 389
 390    --    Note: successive statements (possibly interspersed with entries of
 391    --    other kinds, that are ignored for this purpose), starting with one
 392    --    labeled with C1 = 'S', up to and including the first one labeled with
 393    --    Last = True, indicate the sequence to be output for a sequence of
 394    --    statements on a single CS line (possibly followed by Cs continuation
 395    --    lines).
 396
 397    --    Note: for a pragma that may be disabled (Debug, Assert, PPC, Check),
 398    --    the entry is initially created with C2 = 'p', to mark it as disabled.
 399    --    Later on during semantic analysis, if the pragma is enabled,
 400    --    Set_SCO_Pragma_Enabled changes C2 to 'P' to cause the entry to be
 401    --    emitted in Put_SCOs.
 402
 403    --    Decision (EXIT/entry guard/IF/WHILE)
 404    --      C1   = 'E'/'G'/'I'/'W' (for EXIT/entry Guard/IF/WHILE)
 405    --      C2   = ' '
 406    --      From = EXIT/ENTRY/IF/WHILE token
 407    --      To   = No_Source_Location
 408    --      Last = unused
 409
 410    --    Decision (PRAGMA)
 411    --      C1   = 'P'
 412    --      C2   = ' '
 413    --      From = PRAGMA token
 414    --      To   = No_Source_Location
 415    --      Last = unused
 416
 417    --    Note: when the parse tree is first scanned, we unconditionally build a
 418    --    pragma decision entry for any decision in a pragma (here as always in
 419    --    SCO contexts, the only pragmas with decisions are Assert, Check,
 420    --    dyadic Debug, Precondition and Postcondition). These entries will
 421    --    be omitted in output if the pragma is disabled (see comments for
 422    --    statement entries).
 423
 424    --    Decision (Expression)
 425    --      C1   = 'X'
 426    --      C2   = ' '
 427    --      From = No_Source_Location
 428    --      To   = No_Source_Location
 429    --      Last = unused
 430
 431    --    Operator
 432    --      C1   = '!', '&', '|'
 433    --      C2   = ' '
 434    --      From = location of NOT/AND/OR token
 435    --      To   = No_Source_Location
 436    --      Last = False
 437
 438    --    Element (condition)
 439    --      C1   = ' '
 440    --      C2   = 'c', 't', or 'f' (condition/true/false)
 441    --      From = starting source location
 442    --      To   = ending source location
 443    --      Last = False for all but the last entry, True for last entry
 444
 445    --    Element (chaining indicator)
 446    --      C1   = 'H' (cHain)
 447    --      C2   = 'T' or 'F' (chaining on decision true/false)
 448    --      From = starting source location of chained statement
 449    --      To   = ending source location of chained statement
 450
 451    --    Note: the sequence starting with a decision, and continuing with
 452    --    operators and elements up to and including the first one labeled with
 453    --    Last = True, indicate the sequence to be output on one decision line.
 454
 455    ----------------
 456    -- Unit Table --
 457    ----------------
 458
 459    --  This table keeps track of the units and the corresponding starting and
 460    --  ending indexes (From, To) in the SCO table. Note that entry zero is
 461    --  present but unused, it is for convenience in calling the sort routine.
 462    --  Thus the lower bound for real entries is 1.
 463
 464    type SCO_Unit_Index is new Int;
 465    --  Used to index values in this table. Values start at 1 and are assigned
 466    --  sequentially as entries are constructed.
 467
 468    type SCO_Unit_Table_Entry is record
 469       File_Name : String_Ptr;
 470       --  Pointer to file name in ALI file
 471
 472       Dep_Num : Nat;
 473       --  Dependency number in ALI file
 474
 475       From : Nat;
 476       --  Starting index in SCO_Table of SCO information for this unit
 477
 478       To : Nat;
 479       --  Ending index in SCO_Table of SCO information for this unit
 480    end record;
 481
 482    package SCO_Unit_Table is new GNAT.Table (
 483      Table_Component_Type => SCO_Unit_Table_Entry,
 484      Table_Index_Type     => SCO_Unit_Index,
 485      Table_Low_Bound      => 0, -- see note above on sorting
 486      Table_Initial        => 20,
 487      Table_Increment      => 200);
 488
 489    -----------------
 490    -- Subprograms --
 491    -----------------
 492
 493    procedure Initialize;
 494    --  Reset tables for a new compilation
 495
 496 end SCOs;