gcc/ada/alfa.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                                 A L F A                                  --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --             Copyright (C) 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 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
  31 with Types;      use Types;
  32 with GNAT.Table;
  33
  34 package 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
  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    --    FS . scope line type col entity (-> spec-file . spec-scope)?
  93
  94    --      (The ? mark stands for an optional entry in the syntax)
  95
  96    --      scope is the ones-origin scope number for the current file (e.g. 2 =
  97    --      reference to the second FS line in this FD block).
  98
  99    --      line is the line number of the scope entity. The name of the entity
 100    --      starts in column col. Columns are numbered from one, and if
 101    --      horizontal tab characters are present, the column number is computed
 102    --      assuming standard 1,9,17,.. tab stops. For example, if the entity is
 103    --      the first token on the line, and is preceded by space-HT-space, then
 104    --      the column would be column 10.
 105
 106    --      type is a single letter identifying the type of the entity, using
 107    --      the same code as in cross-references:
 108
 109    --        K = package
 110    --        V = function
 111    --        U = procedure
 112
 113    --      col is the column number of the scope entity
 114
 115    --      entity is the name of the scope entity, with casing in the canonical
 116    --      casing for the source file where it is defined.
 117
 118    --      spec-file and spec-scope are respectively the file and scope for the
 119    --      spec corresponding to the current body scope, when they differ.
 120
 121    --  ------------------
 122    --  -- Xref Section --
 123    --  ------------------
 124
 125    --  A second section defines cross-references useful for computing the set
 126    --  of global variables read/written in each subprogram/package.
 127
 128    --    FX dependency-number filename . entity-number entity
 129
 130    --      dependency-number and filename identity a file in FD lines
 131
 132    --      entity-number and identity identify a scope entity in FS lines for
 133    --      the file previously identified.
 134
 135    --    line typ col entity ref*
 136
 137    --      line is the line number of the referenced entity
 138
 139    --      typ is the type of the referenced entity, using a code similar to
 140    --      the one used for cross-references:
 141
 142    --        > = IN parameter
 143    --        < = OUT parameter
 144    --        = = IN OUT parameter
 145    --        * = all other cases
 146
 147    --      col is the column number of the referenced entity
 148
 149    --      entity is the name of the referenced entity as written in the source
 150    --      file where it is defined.
 151
 152    --  There may be zero or more ref entries on each line
 153
 154    --    (file |)? ((. scope :)? line type col)*
 155
 156    --      file is the dependency number of the file with the reference. It and
 157    --      the following vertical bar are omitted if the file is the same as
 158    --      the previous ref, and the refs for the current file are first (and
 159    --      do not need a bar).
 160
 161    --      scope is the scope number of the scope with the reference. It and
 162    --      the following colon are omitted if the scope is the same as the
 163    --      previous ref, and the refs for the current scope are first (and do
 164    --      not need a colon).
 165
 166    --      line is the line number of the reference
 167
 168    --      col is the column number of the reference
 169
 170    --      type is one of the following, using the same code as in
 171    --      cross-references:
 172
 173    --        m = modification
 174    --        r = reference
 175    --        s = subprogram reference in a static call
 176
 177    --  Special entries for reads and writes to memory reference a special
 178    --  variable called "__HEAP". These special entries are present in every
 179    --  scope where reads and writes to memory are present. Line and column for
 180    --  this special variable are always 0.
 181
 182    --    Examples: ??? add examples here
 183
 184    ----------------
 185    -- Xref Table --
 186    ----------------
 187
 188    --  The following table records Alfa cross-references
 189
 190    type Xref_Index is new Int;
 191    --  Used to index values in this table. Values start at 1 and are assigned
 192    --  sequentially as entries are constructed.
 193
 194    type Alfa_Xref_Record is record
 195       Entity_Name : String_Ptr;
 196       --  Pointer to entity name in ALI file
 197
 198       Entity_Line : Nat;
 199       --  Line number for the entity referenced
 200
 201       Etype : Character;
 202       --  Indicates type of entity, using code used in ALI file:
 203       --    > = IN parameter
 204       --    < = OUT parameter
 205       --    = = IN OUT parameter
 206       --    * = all other cases
 207
 208       Entity_Col : Nat;
 209       --  Column number for the entity referenced
 210
 211       File_Num : Nat;
 212       --  Set to the file dependency number for the cross-reference. Note
 213       --  that if no file entry is present explicitly, this is just a copy
 214       --  of the reference for the current cross-reference section.
 215
 216       Scope_Num : Nat;
 217       --  Set to the scope number for the cross-reference. Note that if no
 218       --  scope entry is present explicitly, this is just a copy of the
 219       --  reference for the current cross-reference section.
 220
 221       Line : Nat;
 222       --  Line number for the reference
 223
 224       Rtype : Character;
 225       --  Indicates type of reference, using code used in ALI file:
 226       --    r = reference
 227       --    m = modification
 228       --    s = call
 229
 230       Col : Nat;
 231       --  Column number for the reference
 232    end record;
 233
 234    package Alfa_Xref_Table is new GNAT.Table (
 235      Table_Component_Type => Alfa_Xref_Record,
 236      Table_Index_Type     => Xref_Index,
 237      Table_Low_Bound      => 1,
 238      Table_Initial        => 2000,
 239      Table_Increment      => 300);
 240
 241    -----------------
 242    -- Scope Table --
 243    -----------------
 244
 245    --  This table keeps track of the scopes and the corresponding starting and
 246    --  ending indexes (From, To) in the Xref table.
 247
 248    type Scope_Index is new Int;
 249    --  Used to index values in this table. Values start at 1 and are assigned
 250    --  sequentially as entries are constructed.
 251
 252    type Alfa_Scope_Record is record
 253       Scope_Name : String_Ptr;
 254       --  Pointer to scope name in ALI file
 255
 256       File_Num : Nat;
 257       --  Set to the file dependency number for the scope
 258
 259       Scope_Num : Nat;
 260       --  Set to the scope number for the scope
 261
 262       Spec_File_Num : Nat;
 263       --  Set to the file dependency number for the scope corresponding to the
 264       --  spec of the current scope entity, if different, or else 0.
 265
 266       Spec_Scope_Num : Nat;
 267       --  Set to the scope number for the scope corresponding to the spec of
 268       --  the current scope entity, if different, or else 0.
 269
 270       Line : Nat;
 271       --  Line number for the scope
 272
 273       Stype : Character;
 274       --  Indicates type of scope, using code used in ALI file:
 275       --    K = package
 276       --    V = function
 277       --    U = procedure
 278
 279       Col : Nat;
 280       --  Column number for the scope
 281
 282       From_Xref : Xref_Index;
 283       --  Starting index in Xref table for this scope
 284
 285       To_Xref : Xref_Index;
 286       --  Ending index in Xref table for this scope
 287
 288       --  The following component is only used in-memory, not printed out in
 289       --  ALI file.
 290
 291       Scope_Entity : Entity_Id := Empty;
 292       --  Entity (subprogram or package) for the scope
 293    end record;
 294
 295    package Alfa_Scope_Table is new GNAT.Table (
 296      Table_Component_Type => Alfa_Scope_Record,
 297      Table_Index_Type     => Scope_Index,
 298      Table_Low_Bound      => 1,
 299      Table_Initial        => 200,
 300      Table_Increment      => 300);
 301
 302    ----------------
 303    -- File Table --
 304    ----------------
 305
 306    --  This table keeps track of the units and the corresponding starting and
 307    --  ending indexes (From, To) in the Scope table.
 308
 309    type File_Index is new Int;
 310    --  Used to index values in this table. Values start at 1 and are assigned
 311    --  sequentially as entries are constructed.
 312
 313    type Alfa_File_Record is record
 314       File_Name : String_Ptr;
 315       --  Pointer to file name in ALI file
 316
 317       File_Num : Nat;
 318       --  Dependency number in ALI file
 319
 320       From_Scope : Scope_Index;
 321       --  Starting index in Scope table for this unit
 322
 323       To_Scope : Scope_Index;
 324       --  Ending index in Scope table for this unit
 325    end record;
 326
 327    package Alfa_File_Table is new GNAT.Table (
 328      Table_Component_Type => Alfa_File_Record,
 329      Table_Index_Type     => File_Index,
 330      Table_Low_Bound      => 1,
 331      Table_Initial        => 20,
 332      Table_Increment      => 200);
 333
 334    ---------------
 335    -- Constants --
 336    ---------------
 337
 338    Name_Of_Heap_Variable : constant String := "__HEAP";
 339    --  Name of special variable used in effects to denote reads and writes
 340    --  through explicit dereference.
 341
 342    -----------------
 343    -- Subprograms --
 344    -----------------
 345
 346    procedure Initialize_Alfa_Tables;
 347    --  Reset tables for a new compilation
 348
 349    procedure dalfa;
 350    --  Debug routine to dump internal Alfa tables. This is a raw format dump
 351    --  showing exactly what the tables contain.
 352
 353    procedure palfa;
 354    --  Debugging procedure to output contents of Alfa binary tables in the
 355    --  format in which they appear in an ALI file.
 356
 357 end Alfa;