Imported Upstream version 4.8.1
[platform/upstream/gcc48.git] / 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-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
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 (-> 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
363 end Alfa;