1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- A L F A -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 2011-2012, 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 information needed for the Alfa 27-- mode. It is used by procedures in Lib.Xref.Alfa to build the Alfa 28-- information before writing it out to the ALI file, and by Get_Alfa/Put_Alfa 29-- to read and write the text form that is used in the ALI file. 30 31with Types; use Types; 32with GNAT.Table; 33 34package Alfa is 35 36 -- Alfa information can exist in one of two forms. In the ALI file, it is 37 -- represented using a text format that is described in this specification. 38 -- Internally it is stored using three tables Alfa_Xref_Table, 39 -- Alfa_Scope_Table and Alfa_File_Table, which are also defined in this 40 -- unit. 41 42 -- Lib.Xref.Alfa is part of the compiler. It extracts Alfa information from 43 -- the complete set of cross-references generated during compilation. 44 45 -- Get_Alfa reads the text lines in ALI format and populates the internal 46 -- tables with corresponding information. 47 48 -- Put_Alfa reads the internal tables and generates text lines in the ALI 49 -- format. 50 51 --------------------- 52 -- Alfa ALI Format -- 53 --------------------- 54 55 -- Alfa information is generated on a unit-by-unit basis in the ALI file, 56 -- using lines that start with the identifying character F ("Formal"). 57 -- These lines are generated if one of the -gnatd.E (SPARK generation mode) 58 -- or gnatd.F (Why generation mode) switches is set. 59 60 -- The Alfa information follows the cross-reference information, so it 61 -- needs not be read by tools like gnatbind, gnatmake etc. 62 63 -- ------------------- 64 -- -- Scope Section -- 65 -- ------------------- 66 67 -- A first section defines the scopes in which entities are defined and 68 -- referenced. A scope is a package/subprogram declaration/body. Note that 69 -- a package declaration and body define two different scopes. Similarly, a 70 -- subprogram declaration and body, when both present, define two different 71 -- scopes. 72 73 -- FD dependency-number filename (-> unit-filename)? 74 75 -- This header precedes scope information for the unit identified by 76 -- dependency number and file name. The dependency number is the index 77 -- into the generated D lines and is ones-origin (e.g. 2 = reference to 78 -- second generated D line). 79 80 -- The list of FD lines should match the list of D lines defined in the 81 -- ALI file, in the same order. 82 83 -- Note that the filename here will reflect the original name if a 84 -- Source_Reference pragma was encountered (since all line number 85 -- references will be with respect to the original file). 86 87 -- Note: the filename is redundant in that it could be deduced from the 88 -- corresponding D line, but it is convenient at least for human 89 -- reading of the Alfa information, and means that the Alfa information 90 -- can stand on its own without needing other parts of the ALI file. 91 92 -- The optional unit filename is given only for subunits. 93 94 -- FS . scope line type col entity (-> spec-file . spec-scope)? 95 96 -- (The ? mark stands for an optional entry in the syntax) 97 98 -- scope is the ones-origin scope number for the current file (e.g. 2 = 99 -- reference to the second FS line in this FD block). 100 101 -- line is the line number of the scope entity. The name of the entity 102 -- starts in column col. Columns are numbered from one, and if 103 -- horizontal tab characters are present, the column number is computed 104 -- assuming standard 1,9,17,.. tab stops. For example, if the entity is 105 -- the first token on the line, and is preceded by space-HT-space, then 106 -- the column would be column 10. 107 108 -- type is a single letter identifying the type of the entity, using 109 -- the same code as in cross-references: 110 111 -- K = package 112 -- V = function 113 -- U = procedure 114 115 -- col is the column number of the scope entity 116 117 -- entity is the name of the scope entity, with casing in the canonical 118 -- casing for the source file where it is defined. 119 120 -- spec-file and spec-scope are respectively the file and scope for the 121 -- spec corresponding to the current body scope, when they differ. 122 123 -- ------------------ 124 -- -- Xref Section -- 125 -- ------------------ 126 127 -- A second section defines cross-references useful for computing the set 128 -- of global variables read/written in each subprogram/package. 129 130 -- FX dependency-number filename . entity-number entity 131 132 -- dependency-number and filename identity a file in FD lines 133 134 -- entity-number and identity identify a scope entity in FS lines for 135 -- the file previously identified. 136 137 -- line typ col entity ref* 138 139 -- line is the line number of the referenced entity 140 141 -- typ is the type of the referenced entity, using a code similar to 142 -- the one used for cross-references: 143 144 -- > = IN parameter 145 -- < = OUT parameter 146 -- = = IN OUT parameter 147 -- * = all other cases 148 149 -- col is the column number of the referenced entity 150 151 -- entity is the name of the referenced entity as written in the source 152 -- file where it is defined. 153 154 -- There may be zero or more ref entries on each line 155 156 -- (file |)? ((. scope :)? line type col)* 157 158 -- file is the dependency number of the file with the reference. It and 159 -- the following vertical bar are omitted if the file is the same as 160 -- the previous ref, and the refs for the current file are first (and 161 -- do not need a bar). 162 163 -- scope is the scope number of the scope with the reference. It and 164 -- the following colon are omitted if the scope is the same as the 165 -- previous ref, and the refs for the current scope are first (and do 166 -- not need a colon). 167 168 -- line is the line number of the reference 169 170 -- col is the column number of the reference 171 172 -- type is one of the following, using the same code as in 173 -- cross-references: 174 175 -- m = modification 176 -- r = reference 177 -- s = subprogram reference in a static call 178 179 -- Special entries for reads and writes to memory reference a special 180 -- variable called "__HEAP". These special entries are present in every 181 -- scope where reads and writes to memory are present. Line and column for 182 -- this special variable are always 0. 183 184 -- Examples: ??? add examples here 185 186 ---------------- 187 -- Xref Table -- 188 ---------------- 189 190 -- The following table records Alfa cross-references 191 192 type Xref_Index is new Int; 193 -- Used to index values in this table. Values start at 1 and are assigned 194 -- sequentially as entries are constructed. 195 196 type Alfa_Xref_Record is record 197 Entity_Name : String_Ptr; 198 -- Pointer to entity name in ALI file 199 200 Entity_Line : Nat; 201 -- Line number for the entity referenced 202 203 Etype : Character; 204 -- Indicates type of entity, using code used in ALI file: 205 -- > = IN parameter 206 -- < = OUT parameter 207 -- = = IN OUT parameter 208 -- * = all other cases 209 210 Entity_Col : Nat; 211 -- Column number for the entity referenced 212 213 File_Num : Nat; 214 -- Set to the file dependency number for the cross-reference. Note 215 -- that if no file entry is present explicitly, this is just a copy 216 -- of the reference for the current cross-reference section. 217 218 Scope_Num : Nat; 219 -- Set to the scope number for the cross-reference. Note that if no 220 -- scope entry is present explicitly, this is just a copy of the 221 -- reference for the current cross-reference section. 222 223 Line : Nat; 224 -- Line number for the reference 225 226 Rtype : Character; 227 -- Indicates type of reference, using code used in ALI file: 228 -- r = reference 229 -- m = modification 230 -- s = call 231 232 Col : Nat; 233 -- Column number for the reference 234 end record; 235 236 package Alfa_Xref_Table is new GNAT.Table ( 237 Table_Component_Type => Alfa_Xref_Record, 238 Table_Index_Type => Xref_Index, 239 Table_Low_Bound => 1, 240 Table_Initial => 2000, 241 Table_Increment => 300); 242 243 ----------------- 244 -- Scope Table -- 245 ----------------- 246 247 -- This table keeps track of the scopes and the corresponding starting and 248 -- ending indexes (From, To) in the Xref table. 249 250 type Scope_Index is new Int; 251 -- Used to index values in this table. Values start at 1 and are assigned 252 -- sequentially as entries are constructed. 253 254 type Alfa_Scope_Record is record 255 Scope_Name : String_Ptr; 256 -- Pointer to scope name in ALI file 257 258 File_Num : Nat; 259 -- Set to the file dependency number for the scope 260 261 Scope_Num : Nat; 262 -- Set to the scope number for the scope 263 264 Spec_File_Num : Nat; 265 -- Set to the file dependency number for the scope corresponding to the 266 -- spec of the current scope entity, if different, or else 0. 267 268 Spec_Scope_Num : Nat; 269 -- Set to the scope number for the scope corresponding to the spec of 270 -- the current scope entity, if different, or else 0. 271 272 Line : Nat; 273 -- Line number for the scope 274 275 Stype : Character; 276 -- Indicates type of scope, using code used in ALI file: 277 -- K = package 278 -- V = function 279 -- U = procedure 280 281 Col : Nat; 282 -- Column number for the scope 283 284 From_Xref : Xref_Index; 285 -- Starting index in Xref table for this scope 286 287 To_Xref : Xref_Index; 288 -- Ending index in Xref table for this scope 289 290 -- The following component is only used in-memory, not printed out in 291 -- ALI file. 292 293 Scope_Entity : Entity_Id := Empty; 294 -- Entity (subprogram or package) for the scope 295 end record; 296 297 package Alfa_Scope_Table is new GNAT.Table ( 298 Table_Component_Type => Alfa_Scope_Record, 299 Table_Index_Type => Scope_Index, 300 Table_Low_Bound => 1, 301 Table_Initial => 200, 302 Table_Increment => 300); 303 304 ---------------- 305 -- File Table -- 306 ---------------- 307 308 -- This table keeps track of the units and the corresponding starting and 309 -- ending indexes (From, To) in the Scope table. 310 311 type File_Index is new Int; 312 -- Used to index values in this table. Values start at 1 and are assigned 313 -- sequentially as entries are constructed. 314 315 type Alfa_File_Record is record 316 File_Name : String_Ptr; 317 -- Pointer to file name in ALI file 318 319 Unit_File_Name : String_Ptr; 320 -- Pointer to file name for unit in ALI file, when File_Name refers to a 321 -- subunit. Otherwise null. 322 323 File_Num : Nat; 324 -- Dependency number in ALI file 325 326 From_Scope : Scope_Index; 327 -- Starting index in Scope table for this unit 328 329 To_Scope : Scope_Index; 330 -- Ending index in Scope table for this unit 331 end record; 332 333 package Alfa_File_Table is new GNAT.Table ( 334 Table_Component_Type => Alfa_File_Record, 335 Table_Index_Type => File_Index, 336 Table_Low_Bound => 1, 337 Table_Initial => 20, 338 Table_Increment => 200); 339 340 --------------- 341 -- Constants -- 342 --------------- 343 344 Name_Of_Heap_Variable : constant String := "__HEAP"; 345 -- Name of special variable used in effects to denote reads and writes 346 -- through explicit dereference. 347 348 ----------------- 349 -- Subprograms -- 350 ----------------- 351 352 procedure Initialize_Alfa_Tables; 353 -- Reset tables for a new compilation 354 355 procedure dalfa; 356 -- Debug routine to dump internal Alfa tables. This is a raw format dump 357 -- showing exactly what the tables contain. 358 359 procedure palfa; 360 -- Debugging procedure to output contents of Alfa binary tables in the 361 -- format in which they appear in an ALI file. 362 363end Alfa; 364