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 libsuif_ver_string and libsuif_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 (see section Structured Annotations) 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 (7). 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.