snoot: immed_and_type_for_C_intconst: properly parse "0"

[suif.git] / info / suif1.info-3

This is Info file suif1.info, produced by Makeinfo version 1.68 from
the input file suif1.texi.

   This file documents the SUIF library.

   Copyright (C) 1994 Stanford University.  All rights reserved.

   Permission is given to use, copy, and modify this documentation for
any non-commercial purpose as long as this copyright notice is not
removed.  All other uses, including redistribution in whole or in part,
are forbidden without prior written permission.

\x1f
File: suif1.info,  Node: Load Constant Instructions,  Next: Call Instructions,  Prev: Branch and Jump Instructions,  Up: Instructions

Load Constant Instructions
==========================

   Rather than allowing constant values to be used directly as operands,
SUIF uses separate `ldc' instructions to load constant values.  The
`in_ldc' class holds these instructions.  Instead of the usual source
operands, this class has an immediate value field (*note Immeds::.).
The `value' and `set_value' methods may be used to access this field.

   Only certain kinds of immediate values are supported in an `ldc'
instruction:

Symbolic addresses (*Note Symbolic Addresses::)
     The result type of the instruction must be a pointer type.

Integers
     The result type must be an integer or pointer type.  Pointer types
     are allowed so that the null pointer can be loaded as the integer
     value zero.

Floating-point values
     The result type must be a floating-point type.

Other kinds of immediate values may be stored in the `value' field of
an `ldc' instruction, but most SUIF passes and certain library
functions will not be able to handle them.

\x1f
File: suif1.info,  Node: Call Instructions,  Next: Array Instructions,  Prev: Load Constant Instructions,  Up: Instructions

Call Instructions
=================

   SUIF uses a special `cal' instruction to represent procedure calls.
This high-level representation hides the details of various linkage
conventions.  The `in_cal' class is used to represent these call
instructions.  A call instruction contains a source operand to hold a
pointer to the procedure to be called.  The `addr_op' and `set_addr_op'
methods access this operand field.

   The actual parameters for the procedure are stored in an array of
operands.  The `num_args' method returns the number of elements in this
array.  The size of the array can be changed at any time using the
`set_num_args' method.  If necessary, the array will be reallocated.
Elements of the argument array may be accessed using the `argument' and
`set_argument' methods.  You must specify the array index.  The first
argument is at index zero.

   Call instructions must obey some conventions on the types of the
operands.  The `addr' operand must hold a pointer to a function type
which is compatible with the type of the procedure being called.  The
result type of the call instruction must match the return type of the
procedure.  The restrictions on instruction result types (*note Result
Types::.) guarantee that the return type will either be void or have
known, non-zero size.  If the function type specifies the number of
arguments, it must match the number of actual parameters (unless the
function takes a variable number of arguments).  Moreover, each operand
in the argument array must be compatible with the type of the
corresponding formal parameter.  Whether or not the function type
specifies the argument types, the restrictions on instruction result
types (*note Result Types::.) and variables (*note Variable Symbols::.)
guarantee that all arguments will have known, non-zero size.

\x1f
File: suif1.info,  Node: Array Instructions,  Next: Multi-way Branch Instructions,  Prev: Call Instructions,  Up: Instructions

Array Instructions
==================

   Because many SUIF passes focus on analyzing and optimizing Fortran
code, a high-level representation of array references is crucial.  SUIF
provides `array' instructions which retain all of the high-level
information in combination with other fields needed to generate code for
the address computations.  The `in_array' class is used to hold these
array instructions.

   Array instructions include a number of fields.  First, a pointer to
the base of the array is specified in an operand field that can be
accessed with the `base_op' and `set_base_op' methods.  If the array
elements are structures, a constant offset within the selected element
may be included.  This optional integer offset can be accessed using the
`offset' and `set_offset' methods.  The element size is needed to
generate low-level code for the array address calculation.  The
`elem_size' method returns the element size in bits.  The
`set_elem_size' method may be used to change the element size.

   Because Fortran arrays do not always begin with index zero, an
optional operand, which is referenced using the `offset_op' and
`set_offset_op' methods, is provided to specify an offset.  Since there
is a single offset operand, the offsets for all of the dimensions must
be combined into a single value.  The arrays are stored in row-major
form, so the offset for the first dimension is multiplied by the size
of the remaining dimensions, etc.  If the offset operand is provided,
it must have an integer type.

   Array instructions can treat arrays of arrays as multidimensional
arrays, even though the type system does not support that directly.
Each array instruction includes a field to specify the number of
dimensions in the array.  This field may be accessed with the `dims'
and `set_dims' methods.  The indexes for the array reference are stored
in an array of source operands, one for each dimension.  These index
operands can be accessed using the `index' and `set_index' methods.
The dimensions are numbered beginning with zero.  Similarly, the number
of elements in each dimension are stored in another array of source
operands, which can be accessed with the `bound' and `set_bound'
methods.

   The result type of an array instruction must be a pointer.  However,
it need not be a pointer to the element type.  If the elements are
structures, the result type may be a pointer to one of the structure
fields.  SUIF does not actually require that the result type match
anything within the array element type, although that is highly
recommended.  The `elem_type' method can be used to determine the
actual type of the element being addressed.

   The types of the array instruction operands must follow some
conventions.  The index and bound operands must all have integer types.
The base operand must be a pointer to an array.  If the array
instruction has multiple dimensions, the base must point to a nested
array (an array of arrays of arrays...) with the same depth as the
number of dimensions.  For each dimension, if the bound operand is a
constant, it must match the number of elements specified in the
corresponding array type.  (If the lower and upper bounds in the array
type are not both constant, then the bound operand may have any value.)
The bound operand for the first dimension is optional and may be null.
Finally, the element size must match the size of the elements in the
array type.

\x1f
File: suif1.info,  Node: Multi-way Branch Instructions,  Next: Label Instructions,  Prev: Array Instructions,  Up: Instructions

Multi-way Branch Instructions
=============================

   Fortran computed `goto' statements and C `switch' statements are
represented in SUIF by multi-way branch (`mbr') instructions.  These
are easier to analyze than the equivalent series of conditional
branches, and they can easily be used to generate efficient jump table
code.  The `in_mbr' class holds these multi-way branch instructions.

   The `in_mbr' class contains a field with a pointer to an array of
label symbols.  The `num_labs' method returns the number of labels in
the array.  The size of the array can be changed at any time using the
`set_num_labs' method; if necessary the array will be reallocated.  A
particular element within the array can be accessed using the `label'
and `set_label' methods.  You must specify the array index, and, as
usual, the elements are numbered beginning with zero.

   A multi-way branch instruction transfers control to one of the target
labels depending on the value in the source operand.  This operand must
have an integer type.  It can be accessed using the `src_op' and
`set_src' methods.  The value of the source operand is combined with an
integer offset to determine the target label.  The offset can be
accessed with the `lower' and `set_lower' methods.  The offset is
subtracted from the value in the source operand and the result is used
to index into the array of target labels.  If the index is within the
range of the array, the instruction branches to the label at that
position in the array; otherwise, it branches to the default target
label.  The `default_lab' and `set_default_lab' methods access this
default label field.  The destination operand of a multi-way branch is
unused and trying to set it will cause an error.  The result type
should always be the SUIF `void' type.

\x1f
File: suif1.info,  Node: Label Instructions,  Next: Generic Instructions,  Prev: Multi-way Branch Instructions,  Up: Instructions

Label Instructions
==================

   SUIF uses special pseudo-instructions to mark the positions of labels
within the lists of instructions.  These label (`lab') instructions are
represented by the `in_lab' class, which contains a single field
holding the symbol for a label.  The `label' and `set_label' methods
access this field.

   No operation is performed by a label instruction.  Its only purpose
is to mark the location of a label symbol in an instruction list.  The
`label' field must be a pointer to the symbol for the label, which must
be defined within the scope where the label instruction occurs.  The
destination operand is unused and trying to set it will cause an error.
The result type should always be the SUIF `void' type.

\x1f
File: suif1.info,  Node: Generic Instructions,  Prev: Label Instructions,  Up: Instructions

Generic Instructions
====================

   To help support special-purpose extensions to SUIF, we have provided
a generic class of instructions.  This is implemented in the `in_gen'
class.  These generic instructions contain arbitrarily large arrays of
source operands and a character string field to hold user-defined names
that function as "sub-opcodes".  Generic instructions are not part of
standard SUIF and most SUIF passes will not handle them.

   Because it is difficult to add new opcodes to SUIF at run-time, the
generic instructions all share the same `gen' opcode.  Instead, they
are distinguished by user-defined names.  The `name' and `set_name'
methods may be used to access these character string fields.  The
`set_name' method automatically enters the name in the lexicon (*note
Lexicon::.).

   A generic instruction contains a pointer to an array of source
operands.  The base class `num_srcs' method may be used to determine
the size of this array.  The size may be changed at any time using the
`set_num_srcs' method.  If necessary, the array will be reallocated.
The elements of the source operand array can be accessed using the
standard base class `src_op' and `set_src_op' methods.  *Note Source
Operands::.

\x1f
File: suif1.info,  Node: Symbol Tables,  Next: Annotations,  Prev: Types,  Up: Top

Symbol Tables
*************

   Symbol tables contain the definitions of the symbols and types used
within a SUIF program.  Each symbol table is associated with an object
corresponding to a particular scope.  For example, a procedure symbol
table is attached to the abstract syntax tree representing the body of
the procedure.  The symbol tables can be reached through the
corresponding objects and vice versa.

   This section describes the symbol table hierarchy and the details of
the symbol table operations, such as looking up symbol table entries and
adding new entries.  It also explains how the symbol tables handle the
task of assigning unique ID numbers to the symbols and types.  The
`symtab.h' and `symtab.cc' files contain the code for symbol tables.

* Menu:

* Symbol Table Hierarchy::      Different kinds of symbol tables.
* Basic Symtab Features::       Basic features common to all symbol tables.
* Lookup Methods::              Finding symbol table entries.
* Creating New Entries::        Creating new objects in a symbol table.
* Adding and Removing Entries::  Changing the symbol table contents.
* Numbering Types and Symbols::  Assigning ID numbers to types and symbols.

\x1f
File: suif1.info,  Node: Symbol Table Hierarchy,  Next: Basic Symtab Features,  Up: Symbol Tables

Symbol Table Hierarchy
======================

   The SUIF symbol tables are organized in a hierarchy of nested scopes
and maintained internally within a tree structure.  Every table
contains a list of the symbol tables that are its children, and each
table also has a pointer back to its parent in the tree (except for the
global symbol table which does not have a parent).  The `children'
method returns a pointer to the list of children and the `parent'
method gets the pointer to the parent symbol table.  Thus, to search
through all of the enclosing scopes, one can follow the parent pointers
back to the global symbol table, visiting all of the symbol tables
along the way.  The `is_ancestor' method provides an easy way to check
if a given symbol table is an ancestor (i.e. an enclosing scope) of the
current table.

   Note that the symbol table hierarchy is not independent.  The primary
objects in a SUIF program are the files and the abstract syntax trees
for the procedures.  The symbol tables are always attached to these
primary objects and are generally treated as if they are parts of those
objects.  For example, when a block of code is deleted the associated
symbol table is automatically removed from the hierarchy and deleted.

   The `base_symtab' class is the base class from which the other
symbol table classes are derived, but it is an abstract class and cannot
be used directly.  There are four different derived symbol tables
classes.  They have much in common, but each is used at a different
level in the hierarchy and thus has slightly different features.

* Menu:

* Global Symbol Table::         Global scope (shared across files).
* File Symbol Tables::          File-level global scopes.
* Procedure Symbol Tables::     Top-level procedure scopes.
* Block Symbol Tables::         Nested scopes within procedures.

\x1f
File: suif1.info,  Node: Global Symbol Table,  Next: File Symbol Tables,  Up: Symbol Table Hierarchy

The Global Symbol Table
-----------------------

   The global symbol table is at the top of the symbol table hierarchy
and corresponds to the outermost global scope.  It contains objects
that are visible across source files (i.e. shared types and global
symbols with external linkage).  For this reason, it is associated with
the `file_set' object.  *Note File Set::.

   The advantage of using a shared global symbol table appears when
performing interprocedural analyses and transformations.  Without a
common symbol table, it can be quite a burden to deal with references to
symbols that are defined in some files but not in others.  Even trying
to determine which symbols from different files correspond to the same
objects is difficult.  In essence, each interprocedural pass would need
to do the work of a linker!  The shared global symbol table avoids all
of these problems and makes interprocedural optimization relatively
easy.

   Along with the benefits of the global symbol table come a few
difficulties.  Sharing the global symbol table across files makes it
difficult to support separate compilation.  Each file must contain a
copy of the global symbol table, and if these files are manipulated
individually, their copies of the global symbol table will not be
consistent.  Thus, before a group of files can be combined in a SUIF
file set, their global symbol tables must be "linked" together using
the SUIF linker pass.  Whether this is preferable to just combining all
of the source files into one big SUIF file is debatable.

   The `global_symtab' class is used to represent the global symbol
table.  It is also used as the base class for file symbol tables.
Because procedure symbols may only be entered in global and file symbol
tables, this class contains the methods to deal with them.  The
`new_proc' method creates a new procedure symbol and enters it in the
table (*note Creating New Entries::.), and the `lookup_proc' method
searches for an existing procedure symbol (*note Lookup Methods::.).
The `number_globals' method in this class handles the task of assigning
ID numbers to the symbols and types in global and file symbol tables
(*note Numbering Types and Symbols::.).

\x1f
File: suif1.info,  Node: File Symbol Tables,  Next: Procedure Symbol Tables,  Prev: Global Symbol Table,  Up: Symbol Table Hierarchy

File Symbol Tables
------------------

   A file symbol table corresponds to the global scope for a source
file.  It contains procedure symbols and global variable symbols with
static linkage, as well as types that are only used within the file.
Each file symbol table is associated with a particular file set entry.
*Note File Set Entries::.

   The `file_symtab' class is derived from the `global_symtab' class to
implement the file symbol tables.  Besides the features that this class
inherits from its base class, it also contains a field to record the
file set entry with which it is associated.  This field is set
automatically when the file symbol table is created by the file set
entry.  The `fse' method retrieves the value of this field.

\x1f
File: suif1.info,  Node: Procedure Symbol Tables,  Next: Block Symbol Tables,  Prev: File Symbol Tables,  Up: Symbol Table Hierarchy

Procedure Symbol Tables
-----------------------

   Procedure symbol tables represent the top-level scopes within
procedures and are associated with the `tree_proc' objects at the roots
of the abstract syntax trees for the procedures.  *Note Procedure
Nodes::.  Because the procedure symbol tables provide a superset of the
block symbol table functions, they are implemented by deriving the
`proc_symtab' class from the `block_symtab' class.  Thus, all of the
`block_symtab' methods can also be applied to `proc_symtab' objects.

   Besides the inherited methods, the procedure symbol tables have some
added features.  Each procedure symbol table contains a list of the
formal parameters for the procedure.  The `params' method returns a
pointer to this list.  The entries on this list must be pointers to
symbols for variables that are contained within the procedure symbol
table.  (Formal parameters cannot be global variables or local variables
in inner scopes.)  The symbols are listed in order.  If the function
type for the procedure specifies the parameter types, they should match
the types of the variables on the parameter list.

   The procedure symbol table also records the next instruction ID
number for the procedure (*note ID Numbers::.).  The `number_locals'
method handles the task of assigning ID numbers to the symbols and
types in symbol tables within the procedure (*note Numbering Types and
Symbols::.).

\x1f
File: suif1.info,  Node: Block Symbol Tables,  Prev: Procedure Symbol Tables,  Up: Symbol Table Hierarchy

Block Symbol Tables
-------------------

   The `block_symtab' class is used for nested block symbol tables and
as the base class for procedure symbol tables.  Each one is associated
with a particular `tree_block' (or `tree_proc') node in an abstract
syntax tree.  *Note Block Nodes::.  Each block symbol table contains a
pointer to the corresponding `tree_block' node.  The `block' method
retrieves the value of this pointer.  When a symbol table is connected
to a `tree_block', its `block' pointer is set automatically.

   Since label symbols may not be declared in global scopes, the
`block_symtab' class is the natural place to provide methods for
working with labels.  The `new_label' method creates a new label symbol
and enters it in the table (*note Creating New Entries::.).  The
`new_unique_label' does the same thing but it first makes sure that the
label will have a unique name.  The `lookup_label' method searches for
an existing label symbol (*note Lookup Methods::.).

   Block symbol tables also provide a method to create a new child
symbol table, i.e. an inner scope.  The `new_unique_child' method can be
used to create a new child block symtab with a unique name (*note
Creating New Entries::.).  This method is not provided for global
symbol tables, because their children must correspond to procedures,
which already have unique names.

\x1f
File: suif1.info,  Node: Basic Symtab Features,  Next: Lookup Methods,  Prev: Symbol Table Hierarchy,  Up: Symbol Tables

Basic Features
==============

   Symbol tables contain three different kinds of objects: types,
symbols, and variable definitions.  The entries within a symbol table
may only be referenced within the corresponding scope.  This includes
references within registered annotations.  Violating this condition may
lead to strange and unexpected errors.

   For simplicity, the symbol table entries are stored on lists instead
of using hash tables.  In theory, the actual implementation (lists or
hash tables) should not be visible in the symbol table interface.
Unfortunately that is not completely true for the current implementation
of SUIF--the lists can be accessed directly.  The `types', `symbols',
and `var_defs' methods return pointers to the lists.  However, these
lists should only be accessed to examine the entries and should never
be modified directly.  The symbol table classes provide other methods
to add and remove entries from the lists and those methods should
always be used.  If the list implementation becomes a performance
bottleneck, we may need to switch to hash tables, and code that
modifies the lists directly will be relatively hard to convert.

   To distinguish the symbol tables nested within a particular scope,
each table is given a name.  The `name' and `set_name' methods retrieve
and modify this name.  If a scope in the source program has a name
associated with it, that name may be used for the corresponding symbol
table.  For example, the name of a procedure-level symbol table should
generally be the same as the name of the procedure.  On the other hand,
nested scopes within procedures are typically unnamed, and names must
be generated for the corresponding symbol tables.

   The symbol table names are used when printing a reference to a
symbol or named type.  Because the symbol or type name alone may not be
sufficient to identify it uniquely, the `chain_name' method is used to
identify the symbol table.  The chain name of a symbol table includes
the names of all of the symbol tables from the procedure-level downward,
separated by slashes (as in a Unix path).  The file-level name is not
included since it should always be clear from the context.  The chain
name for a global or file symbol table is the empty string.

   Duplicate names within a symbol table should be avoided whenever
possible.  Each kind of symbol has a separate name space.  A variable,
for example, may have the same name as a label in the same symbol table.
Named types and child symbol table names are also in separate name
spaces.  Duplicate names may be temporarily introduced but to avoid
problems they should be renamed as soon as possible.  The
`rename_duplicates' method is provided to check for and rename any
duplicates in a symbol table.  This method is automatically called
before writing out each symbol table.

\x1f
File: suif1.info,  Node: Lookup Methods,  Next: Creating New Entries,  Prev: Basic Symtab Features,  Up: Symbol Tables

Lookup Methods
==============

   SUIF symbol tables provide a number of methods to search for and
retrieve particular types, symbols, and variable definitions.  Most of
these lookup methods will optionally search all the ancestor symbol
tables, making it easy to determine if an object is defined in the
current scope.

   The `lookup_type' method is available at all levels in the symbol
table hierarchy to search for SUIF types.  Given an existing type, the
method searches for a type that is the same.  It uses the `is_same'
method from the `type_node' class to perform these comparisons.  If a
matching type is not found within the current symbol table,
`lookup_type' will continue searching in the ancestor symbol tables by
default.  However, if the optional `up' parameter is set to `FALSE', it
will give up after searching the first table.

   Several methods are provided to lookup symbols.  Each different kind
of symbol (variable, procedure, and label) has its own name space, so
the `lookup_sym' method requires that you specify both the name and the
kind of symbol for which to search.  This method may be used with all
symbol tables.  For convenience, other methods are defined as wrappers
around `lookup_sym'.  Each of these wrappers searches for a particular
kind of symbol: `lookup_var' searches for variables, `lookup_proc'
searches for procedures, and `lookup_label' searches for labels.
Because procedure symbols may only be defined in global symbol tables,
the `lookup_proc' method is declared in the `global_symtab' class.
Similarly, the `lookup_label' method is declared in the `block_symtab'
class, because labels may only be defined within procedures.  By
default, all of these methods search the current symbol table and, if
unsuccessful, proceed to search the ancestor symbol tables.  The
optional `up' parameters may be set to `FALSE' to turn off this default
behavior and only search the current symbol table.

   A symbol for a global variable is just a declaration of that variable
and does not automatically have any storage allocated.  Variable
definitions are required to allocate storage and to specify alignment
requirements and any initial data for the variable.  Since the variable
definitions are not directly connected to the variable symbols, the
`lookup_var_def' method is provided to search a symbol table for the
definition of a particular variable symbol.  This method does not
search the parent symbol table.  In general the `definition' method in
the `var_sym' class is a better way to locate a variable definition.

   Symbols and types are assigned ID numbers (*note Numbering Types and
Symbols::.) that uniquely identify them within a particular context.
The `lookup_type_id' method searches the types defined within a symbol
table and its ancestors for a type with the specified ID number.  The
`lookup_sym_id' does the same thing for symbols.

   Besides searching for one of the entries in a symbol table, you can
also search for one of its children in the symbol table hierarchy.  The
`lookup_child' method searches through the list of children for a
symbol table with a given name.  This may not be very useful, but it is
included for completeness.

\x1f
File: suif1.info,  Node: Creating New Entries,  Next: Adding and Removing Entries,  Prev: Lookup Methods,  Up: Symbol Tables

Creating New Entries
====================

   To make it easier to add new entries, the symbol tables provide
methods that combine the steps of creating new objects and then
entering them in the tables.  Some of these methods automatically make
sure that the new entries have unique names and that is particularly
useful.

   New variables can be added to tables anywhere in the symbol table
hierarchy.  The `new_var' method creates a new variable with a given
name and type and then enters the new variable symbol in the table.
The `new_unique_var' method is similar, but it also checks that the
name of the new variable is unique.  If not, it appends a number to the
specified name until it is unique.  With this method, the base name is
optional; the default value is `suif_tmp'.

   Procedure symbols can be created in global and file symbol tables
using the `new_proc' method.  The name of the procedure, its type, and
the source language must be specified.  There is currently no method to
automatically create a new procedure symbol with a unique name.

   Because label symbols may only be declared within procedures, the
`new_label' and `new_unique_label' methods are provided in the
`block_symtab' class.  The only parameter of these methods is the name
of the label.  The name is optional for `new_unique_label'; its default
value is `L'.  Just as with variables, unique label names are created
by adding a number to the end of the base names.

   Within a procedure, new inner scopes may be created to be used with
new `tree_block' nodes.  The `block_symtab' class provides the
`new_unique_child' method to create a new symbol table, give it a
unique name, and add it to the list of children.  The unique name is
created by appending a number to the optional base name.  If the base
name is not given, it defaults to `block'.  This method is not needed
at the global level, because the child symbol tables there correspond
to procedures which should already have unique names.

   Finally, new variable definitions can be added to any symbol table
using the `define_var' method.  The parameters are the variable symbol
and the alignment for the storage to be defined.  It returns a pointer
to the new variable definition object, so that you can attach initial
data annotations to it.

\x1f
File: suif1.info,  Node: Adding and Removing Entries,  Next: Numbering Types and Symbols,  Prev: Creating New Entries,  Up: Symbol Tables

Adding and Removing Entries
===========================

   Entries in symbol tables should always be added and removed using the
methods provided by the symbol tables.  Although it is possible to add
and remove entries by directly manipulating the lists, that should never
be done.  The methods for adding and removing entries hide the
underlying representation and using them will make it much easier to
update your code if that representation changes.  Even more importantly,
most symbol table entries contain back pointers to the tables which hold
them, and the adding and removing methods are responsible for
maintaining those pointers and for performing a few other automatic
checks and updates.

   Types, symbols, and child symbol tables may be added using the
`add_type', `add_sym', and `add_child' methods, respectively.  Each of
these entries contains a pointer back to the parent symbol table, and
these methods automatically set those back pointers.  They do not,
however, perform any other sanity checks, such as checking for
duplicate names.  Similarly, the `remove_type', `remove_sym', and
`remove_child' methods remove types, symbols, and child symbol table
entries.  These methods clear the parent pointers but do not delete the
entries that are removed.

   Variable definitions are treated a bit differently from other kinds
of symbol table entries.  They do not have parent pointers so the
`add_def' and `remove_def' methods do not have to deal with that.
However, adding and removing variable definitions change some
attributes of the corresponding variables, and those attributes must be
automatically updated.  First, each variable has a flag to indicate
whether a variable definition exists for it.  A variable cannot have
more than one definition, so the `add_def' method will fail if this
flag is already set.  Otherwise, it sets the flag when the new
definition is added.  Second, variable symbols also have a flag to
indicate whether they are actual definitions or just declarations of
symbols with external linkage.  This `extern' flag must be set to
`FALSE' when a variable definition is added for a global variable.
When removing a variable definition, these flags must be reversed.

   Unlike symbol nodes which always define separate symbols, multiple
type nodes can represent the same type.  The basic `add_type' method
will add a new type even if an equivalent type was already defined in
the same scope.  In most cases, what is actually needed is a method to
first check if an equivalent type exists and if so to throw away the
duplicate and return the existing type.  The `install_type' method
provides this functionality.  It first checks if a type has already been
entered in the symbol table or one of its ancestors using the
`lookup_type' method.  If so, it deletes the new type and returns the
existing one.  If a type is not found, it is entered into the symbol
table and returned.  All of the components of a type are recursively
installed before the type itself.  This makes it easy to create new
types without worrying about duplicate entries in the symbol tables.

\x1f
File: suif1.info,  Node: Numbering Types and Symbols,  Prev: Adding and Removing Entries,  Up: Symbol Tables

Numbering Types and Symbols
===========================

   Every symbol and type is assigned an ID number that uniquely
identifies it within a particular context.  These ID numbers should be
used to refer to symbols and types in annotations that will be written
to the output files and in other situations where pointers to the
symbol and type nodes cannot be used.  The `sym_id' method retrieves
the ID number for a symbol, and the `type_id' method gets the number
for a type.

   For symbols and types within a procedure, the ID numbers are only
unique within that procedure.  Similarly, the ID numbers for symbols
and types in a file symbol table are only unique within that file.
Only in the global symbol table are the ID numbers truly unique.  This
is implemented by dividing the ID numbers into three ranges.  Each
range is reserved for a particular level in the symbol table hierarchy.
To make it easier to read an ID number, the `print_id_number' function
prints it as a character to identify the range (`g' for global, `f' for
file, `p' for procedure) combined with the offset of the number within
that range.

   The symbol and type ID numbers cannot be assigned individually, but
the symbol tables provide methods to set them.  The `number_globals'
method is defined in the `global_symtab' class to number the entries in
global and file symbol tables, and the `number_locals' method is
defined in the `proc_symtab' class to number all of the entries in the
procedure symbol table and its descendents.  These methods only assign
ID numbers to symbols and types that do not already have numbers.
These methods are called automatically before writing things out to
files, but they can also be called whenever you want to assign numbers
to new symbols and types.

   The `clear_sym_id' symbol method and `clear_type_id' method are
provided to reset the ID numbers to zero manually, but as far as the
library itself is concerned, this is never necessary.  The library
automatically changes ID numbers when necessary, such as when moving
from one symbol table to another.

\x1f
File: suif1.info,  Node: Symbols,  Next: Types,  Prev: Instructions,  Up: Top

Symbols
*******

   SUIF symbols are stored in the symbol tables (*note Symbol
Tables::.) to represent variables, labels, and procedures.  The
`sym_node' class is the base class for all SUIF symbols.  This is an
abstract class so it cannot be used directly.  The library also defines
the `sym_node_list' class for lists of pointers to symbols.  Classes
are derived from the `sym_node' class for each kind of symbol.  Given
an arbitrary symbol, the `kind' method identifies the kind of symbol
and thus the derived class to which it belongs.  This method returns a
value from the `sym_kinds' enumerated type.  The following values are
defined in that enumeration:

`SYM_VAR'
     Variable symbol.  The `var_sym' class represents variable symbols.

`SYM_LABEL'
     Label symbol.  The `label_sym' class represents label symbols.

`SYM_PROC'
     Procedure symbol.  The `proc_sym' class represents procedure
     symbols.

   All symbols share some common fields including the symbol names.
These are described in the first section below.  Each kind of symbol
also uses additional fields that are specific to that kind.  For
example, variable symbols specify the types of the variables.  The
subsequent sections describe the specific features of each kind of
symbol.

   The `symbols.h' and `symbols.cc' files contain the source code for
SUIF symbols.

* Menu:

* Symbol Features::             Basic features of all symbols.
* Procedure Symbols::           Procedures.
* Label Symbols::               Labels.
* Variable Symbols::            Variables.

\x1f
File: suif1.info,  Node: Symbol Features,  Next: Procedure Symbols,  Up: Symbols

Basic Features of Symbols
=========================

   The `sym_node' class defines several fields that are used by all
kinds of symbols.  The most obvious of these is the symbol name.  Each
symbol has a name that should be unique within the symbol table where it
is defined.  The `name' and `set_name' methods access this field.  The
names are automatically entered in the lexicon (*note Lexicon::.) by
`set_name'.  Because the name of a symbol alone is generally
insufficient to uniquely identify it, the symbols are also given ID
numbers.  *Note Numbering Types and Symbols::.

   When a symbol is entered in a symbol table, it automatically records
a pointer to that parent table.  Similarly, when the symbol is removed
from the symbol table, its parent pointer is cleared.  The `parent'
method retrieves this parent pointer.

   All symbols contain flags to specify various attributes.  The
`sym_node' class provides methods to access these flags.  The
`is_userdef' method tests a flag to see if it is a user-defined symbol
(from the source code) or a new symbol introduced by the compiler.  The
`set_userdef' and `reset_userdef' methods change the value of this flag.

   Another flag is used to mark symbols that are only declarations of
external symbols, rather than actual definitions.  This flag is set
automatically.  The `is_extern' method retrieves its value.  Label
symbols are never `extern'.  A procedure symbol is `extern' unless the
procedure body is defined in the input file(s).  A global variable
symbol is `extern' unless it has a separate definition (*note Variable
Definitions::.); no other variables are `extern'.

   Since symbols may be treated differently depending on their scopes,
the `sym_node' class includes methods to determine which kind of symbol
table contains a symbol.  The `is_global' method checks if the parent
table is a global or file symbol table.  This is really only useful for
variable symbols, because procedures are always global and labels are
never global.  The `is_private' method checks if a symbol is global but
private to one source file by checking if the parent symbol table is a
file symbol table.  This is obviously irrelevant for label symbols.

   The `add_to_table' and `remove_from_table' methods are provided for
convenience when adding or removing symbols from symbol tables.  In the
case of variable symbols, the entire hierarchy of sub-variables (*note
Sub-Variables::.) is added or removed at one time by this method.

   The `copy' method makes a copy of a symbol.  This is a virtual
function so it copies the fields that are specific to each kind of
symbol.  However, it only copies the symbol itself: copying a procedure
symbol will not copy the procedure body and copying a variable symbol
will not copy the variable definition.  The `copy' method does not copy
annotations on the symbol, either.  Since the copy will have the same
name as the original symbol, it should generally be renamed or used in
a different symbol table.

   Two different methods are available for printing symbols.  The
`print' method just prints the name of the symbol.  Label symbols are
prefixed by `L:' and procedure symbols by `P:' to distinguish them from
variable symbols.  The `print_full' method is used by the library when
listing the contents of symbol tables.  It includes all the fields from
the `sym_node'.

\x1f
File: suif1.info,  Node: Procedure Symbols,  Next: Label Symbols,  Prev: Symbol Features,  Up: Symbols

Procedure Symbols
=================

   Procedure symbols are represented by objects of the `proc_sym'
class.  SUIF does not support nested procedures, so these symbols may
only be entered in global and file symbol tables.  The fields in a
procedure symbol hold information about the procedure, including a
pointer to the body if it is in memory.  The `proc_sym' class also
provides methods to read procedure bodies from input files, write them
to the output files, and flush them from memory.

   Each procedure symbol contains a field to record the source language
for the procedure.  The `src_lang' and `set_src_lang' methods access
this field, which holds a value from `src_lang_type' enumeration:
`src_unknown', `src_c', `src_fortran', or `src_verilog'.  Other values
may be added in the future.

   A procedure symbol also has a field that specifies the type of the
procedure.  The `type' and `set_type' methods retrieve and change this
field.  The type must be a function type.  *Note Function Types::.

   The body of a procedure is represented by its abstract syntax tree.
*Note Trees::.  The procedure symbol contains a pointer to the root node
of this tree.  The `block' and `set_block' methods access this pointer.
If the body is not in memory, the `block' pointer will be `NULL'; the
`is_in_memory' method is provided to check this condition.

   The `proc_sym' class contains the methods to read procedure bodies
from binary SUIF files and to write them out again.  The details of SUIF
I/O are thus hidden from users; only entire procedures can be read and
written.  If one of the input files contains the body for a procedure, a
pointer to the file set entry (*note File Set Entries::.) is recorded in
the procedure symbol.  The `file' method retrieves this pointer for a
particular `proc_sym'.  The same procedure can be read in and flushed
from memory many times, but once it has been written out it can no
longer be read or written again.  The procedure symbol contains a flag
to indicate if it has been written out yet.  The `is_written' method
returns the value of this flag.  The `is_readable' method checks if the
procedure body exists in one of the input files and if it has not yet
been written out.  If this method returns `TRUE', the `read_proc'
method can be used to read the body of the procedure.  By default,
`read_proc' also converts the procedure to expression tree form (*note
Expression Trees::.) but it does not convert to Fortran form (*note
Fortran::.).  The `exp_trees' and `use_fortran_form' parameters to
`read_proc' can be used to override these defaults.

   After a procedure body has been read in and possibly modified, it
can be written to the output file using the procedure symbol's
`write_proc' method.  You must specify the file set entry to which the
procedure should be written.  In most cases, the input and output file
set entry will be the same, and you will just use the `file' method to
determine the output file set entry.  As mentioned above, once a
procedure has been written out it cannot be rewritten or read in again.
Obviously, it should not be changed after that point because the
changes could not be saved.  Besides avoiding changes directly to the
procedure, however, you must also be careful to avoid certain changes to
the global symbol tables.  The symbols and types within the procedure
are written out using their ID numbers.  *Note Numbering Types and
Symbols::.  Thus, you must not do anything to the global symbol tables
that would cause the ID numbers for those symbols and types to change.
For example, moving a symbol from a file symbol table to the global
symbol table would require that its ID number change.  The best solution
to this is to not write out the procedures until you are certain that
such changes to the symbol tables will not be needed.

   When a procedure body is no longer needed, typically after it has
been written out, call the `flush_proc' method for the procedure symbol
to deallocate the storage used by the procedure.  In some cases, you may
want to flush the procedure before it is written.  For example,
interprocedural analysis requires that all procedures be read in and
analyzed together.  To save space, the procedures can be summarized for
the purpose of the particular analysis and then flushed.  After the
analysis is complete, they can be re-read and the results can be
attached to the code.

\x1f
File: suif1.info,  Node: Label Symbols,  Next: Variable Symbols,  Prev: Procedure Symbols,  Up: Symbols

Label Symbols
=============

   The `label_sym' class represents label symbols.  Labels are used
within procedures to specify targets of branch and jump instructions.
They may not be entered in global or file symbol tables.  The position
of a label is usually indicated by a label instruction (*note Label
Instructions::.), but for labels associated with high-level AST nodes,
the label positions may be implicit.  The `label_sym' class contains no
extra fields beyond those in the base `sym_node' class.

\x1f
File: suif1.info,  Node: Variable Symbols,  Prev: Label Symbols,  Up: Symbols

Variable Symbols
================

   In SUIF, variable symbols represent data objects.  Variable symbols
are represented by objects of the `var_sym' class.  This class adds a
field to specify the type of the variable as well as some additional
flags.  Unlike procedures and labels, variables may be defined in any
scope.

   SUIF provides optional "sub-variables" to make it easier to deal
with pieces of aggregate objects that may or may not overlap, in
particular Fortran equivalences and reshaped common blocks.  Instead of
referring to a piece of an aggregate by an offset combined with the
aggregate symbol, a sub-variable can be created to represent the data at
a particular offset within the aggregate, so that it can be referenced
in the same way as if it were not contained within an aggregate
structure.

* Menu:

* Variable Features::           Basic features of variables.
* Sub-Variables::               Variables contained within aggregates.
* Variable Definitions::        Definitions of global and static variables.