nsharlit: remove duplicate const_string

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

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: Immeds,  Next: Symbolic Addresses,  Up: Other

Immediate Values
================

   An immediate value may be an integer constant, string constant,
floating-point constant, SUIF type, symbolic address, expression
operand, or instruction, or it can be undefined.  It can be used as the
source of an `ldc' (load constant) instruction (*note Load Constant
Instructions::.) or as an element of an annotation (*note
Annotations::.).  Only integers, floating-point values, and symbolic
addresses may be used in `ldc' instructions, while any kind of
immediate value may appear in an annotation.  Immediate values are
implemented by the `immed' class defined in the files `immed.h' and
`immed.cc'.

   The kind of value in an `immed' is identified by the `kind' method.
This returns a member of the `immed_kinds' enumerated type.  The
members of this enumeration are:

`im_int'
     Integer.  The `is_integer' method tests for this kind of immediate
     and the `integer' method returns the integer value.

`im_string'
     Character string.  The string is automatically entered in the
     lexicon (*note Lexicon::.) when the `immed' is created.  The
     `is_string' method checks if an `immed' is a string, and the
     `string' method returns a pointer to the string.

`im_float'
     Floating-point value.  The SUIF library stores all floating-point
     values using the `double' type, so the precision is limited by the
     precision for the `double' type.  The `is_flt' method checks for
     this kind of immediate, and the `flt' method returns the value.

`im_symbol'
     Symbolic address.  *Note Symbolic Addresses::.  The `is_symbol'
     method checks if an `immed' is a symbolic address.  The `addr'
     method returns the entire `sym_addr' object, but the `symbol' and
     `offset' methods are also available to retrieve the symbol pointer
     and integer offset separately.

`im_type'
     SUIF type.  The `is_type' method checks for this kind of immediate,
     and the `type' method returns a pointer to the SUIF type node.

`im_op'
     Expression operand.  The immed is considered to "own" the entire
     expression tree when it's in an annotation, so the same expression
     shouldn't be used in another annotation or as the source for an
     instruction; instead a copy should be made with the `clone'
     method.  The `is_op' method checks for this kind of immediate, and
     the `op' method returns the expression.

`im_instr'
     SUIF instruction.  The immed is considered to "own" the instruction
     and its expression trees when it's in an annotation, so the same
     instruction shouldn't be used in another annotation or in a
     `tree_node' or expression; instead a copy should be made with the
     `clone' method.  The `is_instr' method checks for this kind of
     immediate, and the `instr' method returns the instruction.

`im_undef'
     Undefined value.  This is included to signal errors by marking an
     immediate as undefined.  The `is_error' method also checks for this
     condition.

   Since an immediate value is small, there are no methods to change the
value of an `immed'.  Instead a variety of constructors are provided to
make it easy to create new immediate values.  That is, you can
initialize different kinds of immediates by providing arguments of
various types to constructors.

   The `immed' class provides two print methods, `print' and
`rawprint'.  The difference between them is that the latter doesn't
escape `"' and `\' when printing strings.

\x1f
File: suif1.info,  Node: Symbolic Addresses,  Next: Lexicon,  Prev: Immeds,  Up: Other

Symbolic Addresses
==================

   Symbolic addresses are currently only used in immediate values
(*note Immeds::.).  A symbolic address has two parts, a symbol and an
integer offset.  In many cases, the offset is set to zero, but for an
aggregate data structure the offset may specify the number of bits from
the beginning of the data structure to a particular field.  The
`sym_addr' class defined in the `symaddr.h' and `symaddr.cc' files
implements these symbolic addresses.

   The `symbol' method returns a pointer to the symbol in a symbolic
address, and the `offset' method returns the integer offset.  As with
most other offsets in SUIF, the offset is in *bits*.  Be careful to
avoid treating this as a byte or word offset.  As with immediate
values, there are no methods to change the contents of a symbolic
address.  Because these are small structures, it is just as easy to
create new `sym_addr' objects whenever they are needed.  To print a
symbolic address, use the `print' method.

\x1f
File: suif1.info,  Node: Lexicon,  Next: Target Machine Parameters,  Prev: Symbolic Addresses,  Up: Other

Lexicon
=======

   Almost all character strings in SUIF are entered in a hash table
called the `lexicon'.  This table removes duplicate strings so that
string comparisons can be reduced to simple pointer comparisons.  The
`lexicon' is an object of the `string_table' class defined in the
`stringtable.h' and `stringtable.cc' files.

   A `string_table' is an open hash table; each bucket is a linked list
of string entries represented by objects of the `string_e' class.  The
only public method in the `string_table' class is called `enter'.  This
method searches the table for a specified string.  If the string is
found, `enter' returns a pointer to the existing `string_e' entry.
Otherwise, it creates a new entry and adds it to the table.  In either
case, the actual character string pointer can be retrieved directly
from the `sp' field of the resulting `string_e' entry.

   None of the strings in the `lexicon' are deallocated until a SUIF
program terminates.  Consequently, when adding a new string to the
table, it is copied to the heap in case the original string is stored on
the stack.  If the string is known to be allocated on the heap and will
never be modified or deallocated, this string copy can be avoided by
setting the optional `fixed' flag when calling `enter'.

\x1f
File: suif1.info,  Node: Target Machine Parameters,  Next: Initialization,  Prev: Lexicon,  Up: Other

Target Machine Parameters
=========================

   The SUIF library includes a structure to record various parameters of
the target machine.  The back-end of the compiler may be either a code
generator for a specific processor or the system's C compiler, using the
SUIF-to-C translator.  Thus, the target machine parameters include
fields that deal both with hardware requirements and with details of the
back-end C compiler.  These parameters are stored in the `target'
`machine_params' structure.  The front-end is responsible for setting
the target parameters, but they are then saved in the SUIF files and
passed along to all subsequent passes of the compiler.

   The first fields in the `machine_params' structure deal with the
addressing in the underlying hardware.  The `is_big_endian' field
specifies the byte order, and the `addressable_size' field specifies
the size in bits of the smallest addressable unit.  Since most machines
are byte-addressable, the `addressable_size' is usually set to eight.

   Next, the sizes and alignments for various C types are specified.
The possible C types are listed in the `C_types' enumeration:

`C_char'

`C_short'

`C_int'

`C_long'

`C_longlong'

`C_float'

`C_double'

`C_longdouble'

`C_ptr'
The `size' and `align' fields of the `machine_params' structure are
arrays containing the size and alignment for each C type.  Both are
specified in bits (not bytes).  Some C compilers require additional
alignment restrictions for arrays and structures.  The `array_align'
and `struct_align' fields contain these alignment requirements in bits.
Note that these do not replace the alignment restrictions for the
components of an array or structure; the most restrictive alignments
must always be maintained.

   The remaining fields are only applicable to the back-end C compiler.
The `char_is_signed' field specifies if the default `char' type is
signed.  This is just to allow the SUIF-to-C translator to avoid
cluttering up the C code by explicitly putting `signed' or `unsigned'
in every declaration of a `char' type.  When two pointers are
subtracted in C, the result type is implementation defined.  The
`ptr_diff_type' field in `machine_params' specifies the type produced
by such pointer subtractions for use in SUIF-to-C.

\x1f
File: suif1.info,  Node: Initialization,  Next: Command-Line Parser,  Prev: Target Machine Parameters,  Up: Other

Initialization and Finalization
===============================

   Before using any features of the SUIF library, a program must first
initialize it.  The `init_suif' function, defined in the `initsuif.h'
and `initsuif.cc' files, performs this initialization.  The `main'
function of a SUIF program should call `init_suif' first.  The `argc'
and `argv' parameters are passed to `init_suif' so that it can check
for the following standard options:

`-version'
     Print the version numbers and compilation information for the
     program and for any libraries with which it is linked.  The
     `prog_ver_string' and `prog_who_string' strings contain the
     version number and compilation information for the program.  They
     are usually set automatically by the standard SUIF makefiles.
     Similarly, the `libsuif1_ver_string' and `libsuif1_who_string'
     strings are used for the SUIF library.  Information for other
     libraries is recorded when they are registered (as described
     below).

`-print-flat'
     Do not print structured annotations (*note Structured Annotes::.)
     using the user-defined printing functions.  If all annotations are
     printed as flat lists of immediate values, the output could be
     parsed and converted back to a binary SUIF file.

`-no-types'
     Do not print the result types for instructions.  This is just to
     help make the output more readable in situations where the result
     types are not of interest.

`-no-symtabs'
     Do not print out symbol tables.  If the symbolic information is not
     needed, this makes the output shorter and easier to read.

These options are potentially applicable to all SUIF programs, so they
are included in the library.

   At the end of a SUIF program, the data structures in the SUIF library
may be deallocated.  Although this is not absolutely necessary, it may
simplify debugging by making it easier to read the output from Purify
and other tools.  Besides deallocating the data structures, it may
someday be useful to perform other actions at the end of a SUIF program.
The `exit_suif' function is provided to perform this finalization.  If
used, it should be called at the very end of the program.

   Besides the base SUIF library, many SUIF programs are linked with
other libraries that also need to be initialized.  Rather than just
initializing them directly, they are registered with the SUIF library
along with initialization and finalization functions.  The
initialization functions are then called automatically by `init_suif'
and the finalization functions by `exit_suif'.  This allows the SUIF
library to record and print version numbers and other information for
all of the libraries linked with a program.  The `register_library'
function records the name, version, and compilation information for a
library along with pointers to the functions to initialize and finalize
that library.  The initialization function must match the `lib_init_f'
type, which takes the `argc' and `argv' parameters for the command line
and returns `void'.  Similarly, the finalization function must match the
`lib_exit_f' type, which takes no arguments and returns `void'.  The
parameters for the name, version, and compilation information are
required, but the initialization and finalization functions are
optional.  The libraries must be registered, in the order in which they
should be initialized, before calling `init_suif'.  The finalization
functions are called in the reverse order in which the libraries were
registered.

   The situation is much simpler if you use the standard SUIF makefiles.
These makefiles automatically generate strings holding the version and
compilation information.  The `LIBRARY' macro may be used to register a
library using these version strings.  You only need to specify the base
name of the library and the names of the initialization and
finalization functions (1).  To make things even easier, the SUIF
makefiles also generate a new function called `start_suif'.  This
function automatically registers all of the libraries linked with the
program and then calls `init_suif'.  So to make a long story short, if
a SUIF program begins with a call to `start_suif' all of the libraries
will be automatically registered and initialized.

   ---------- Footnotes ----------

   (1) Unlike when calling `register_library' directly, the function
arguments are required when using the `LIBRARY' macro.

\x1f
File: suif1.info,  Node: Command-Line Parser,  Next: Error Handling,  Prev: Initialization,  Up: Other

Command-Line Parser
===================

   The SUIF library provides a generic interface for a command line
parser.  The parser is defined and implemented in the files
`cmdparse.h' and `cmdparse.cc'.  The SUIF program can provide a
structure that contains a list of command line options, the type of
arguments these options can handle, and pointers to data where the
argument values will be stored.  The data locations will be initialized
to default values specified in the options table before parsing begins.
The `parse_cmd_line' function is called with `argc', `argv', the
options table, and the number of options in the table.  If the parser
finds one of the options on the command line, the option (and its
argument, if any) are removed from `argv' and `argc' is appropriately
adjusted.  Thus when parsing is finished, `argv' contains only
unrecognized options (such as file names).

   The following types of arguments are supported:

`CLO_NOARG'
     No argument is expected.  The default value is 0.  If the argument
     is present, the value becomes 1.

`CLO_INT'
     A single integer is expected.

`CLO_STRING'
     A single string is expected.

`CLO_MULTI_STRING'
     A single string is expected for each occurrence of this option, but
     the option can be repeated with different arguments.

   For example:

     static boolean quiet;
     static int size;
     static cmd_line_option my_options[] = {
         { CLO_NOARG, "-quiet", "", &quiet },
         { CLO_INT, "-size", "8", &size }
     };
     
     parse_cmd_line(argc, argv, my_options,
                    sizeof(my_options)/sizeof(cmd_line_option));

\x1f
File: suif1.info,  Node: Error Handling,  Next: Procedure Iterators,  Prev: Command-Line Parser,  Up: Other

Error Handling
==============

   The SUIF library includes a number of functions for error handling.
These functions handle three kinds of problems: errors, warnings, and
assertions.  Assertions are tests for things that should never occur in
a correct program.  Any problem that could potentially occur in a
correct program due to bad input or other external conditions should be
treated as an error rather than an assertion failure.  Warnings are used
to report potentially troublesome conditions that are not serious enough
to cause a fatal error.

   Two macros are available to implement assertions.  The `assert'
macro takes a single expression as an argument.  If the expression
evaluates to zero, a message is printed showing the current line number,
file name, and the expression that failed, and then the `abort'
function is called to terminate the program.  The `assert_msg' macro is
similar except that it also prints a user-defined message if the
assertion fails.  Besides the expression to be tested, `assert_msg'
takes an argument that contains the message to be printed.  This second
argument must hold the `printf' format string and the arguments for the
call to `printf', separated by commas.  To keep the commas from
splitting up the second argument, it must be surrounded by parentheses.
For example:

     assert_msg(sym->parent(), ("no parent for %s", sym->name()));

   Errors may be reported using the `error_line' function.  The
`return_code' parameter specifies the method of terminating the
program.  If the return code is negative, the `abort' function is
called.  If it is greater than zero, the `exit' function is called with
the specified return code.  If the return code is zero, the error
message will be printed but the program will not terminate.  The
`the_node' parameter is optional and may be set to `NULL'.  If used, it
points to the AST node closest to the point where the error was
detected, and the library tries to use it to find and print the
corresponding source line number.  Finally, the `fmt' parameter
specifies the `printf' format string used to print the error message
and any additional parameters are passed on to `printf'.  The
`verror_line' function is identical to `error_line' except that it
passes the variable arguments for `printf' using a `varargs'-style
list.  This is just like the standard `vprintf' function.

   The `warning_line' and `vwarning_line' functions are just like the
corresponding error functions, except that they print warning messages
and do not terminate the program.  Consequently, they do not have
`return_code' parameters.

\x1f
File: suif1.info,  Node: Procedure Iterators,  Prev: Error Handling,  Up: Other

Procedure Iterators
===================

   Most SUIF programs work on one procedure at a time.  These programs
require basically the same code to iterate through the file set entries
and procedures.  The `suif_proc_iter' routine is provided to handle
this common case.

   Before calling the procedure iterator, you must initialize the SUIF
library (*note Initialization::.), which also parses and removes some
standard options from the command-line arguments.  Either the SUIF
library's command-line parser (*note Command-Line Parser::.) or the
`getopt' function (from the standard C library) may be called before
the procedure iterator to parse command-line options not removed by the
library initialization.  The `suif_proc_iter' function then reads the
input and output file names from the command-line.  The first file name
on the command line is treated as an input file.  If the `writeback'
flag is set, the second file is treated as an output file and any
additional file names on the command line are alternately treated as
input and output files.  If the `writeback' flag is not set, all the
file names are treated as input files.

   The procedure bodies are then read one at a time and processed by a
user-specified function.  This function must be of the type
`prociter_f', which takes a single `tree_proc' argument and has a
`void' return type.  When a procedure is read, the `exp_trees' and
`use_fortran_form' parameters are passed on to the `read_proc' method
for the `proc_sym'.  The `exp_trees' argument specifies whether the
procedure bodies are converted to expression trees (*note Expression
Trees::.), and the `use_fortran_form' argument determines whether
Fortran form is used (*note Fortran::.).  The defaults are to create
expression trees but not to use Fortran form.  If the `writeback' flag
is set, the procedure bodies are written to the output files after they
have been processed.

\x1f
File: suif1.info,  Node: Appendix,  Next: Function Index,  Prev: Other,  Up: Top

Appendix
********

   Please note that the diagrams are only available in the PostScript of
HTML versions of this document.  This section won't mean much to you
otherwise.

* Menu:

* Inherit Diagram::
* Overview Diagram::
* Symbol Table Diagram::

\x1f
File: suif1.info,  Node: Inherit Diagram,  Next: Overview Diagram,  Up: Appendix

Class Inheritance of Major SUIF Structures
==========================================

   All major SUIF data structures are derived from the `suif_object'
base class. *Note SUIF Objects::. The class `file_set_entry' is defined
in *Note File Set Entries::, the class `tree_node' and its derived
classes are explained in *Note Tree Nodes::, the class `sym_node' and
its derived classes are described in *Note Symbols::, the class
`type_node' and its derived classes are defined in *Note Types::, the
class `instruction' and its derived classes are defined in *Note
Instructions:: and the class `var_def' is defined in *Note Variable
Symbols::.

\x1f
File: suif1.info,  Node: Overview Diagram,  Next: Symbol Table Diagram,  Prev: Inherit Diagram,  Up: Appendix

Overview of the SUIF Hierarchy
==============================

   This diagram represents the overall hierarchical structure of the
SUIF intermediate representation. At the top level, the global symbol
information is kept. *Note Global Symbol Table::. In the next level,
information regarding each input and output file is kept.  *Note File
Representation::. The third level is the abstract syntax tree
representation.  *Note Trees::. The bottom level contains the expression
trees.  *Note Instructions::.

\x1f
File: suif1.info,  Node: Symbol Table Diagram,  Prev: Overview Diagram,  Up: Appendix

The Symbol Table Representation
===============================

   The first diagram below illustrates the symbol table structure.  The
second shows the hierarchy of symbol tables. *Note Symbol Table
Hierarchy:: for more details.