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