Guillaume Oget - Corinne Ancourt
5 octobre 1998
tpips is the line interface and scripting language of the PIPS project. All PIPS functionalities are available, with on-line help and automatic completion.
tpips is more efficient than the pips based scripts ( Init,
Display,...) because the database is not open, read, written and closed
for each command. tpips is less user-friendly than wpips and epips,
although it provides the unique opportunity to apply a transformation or
display some information on several modules with one command, using
pipsmake metavariables,
%CALLERS and %CALLEES, or environment user defined variables such
as $MODULES (see Example 4.2). The jpips future user
interface will provide these pips/tpips functionalities too.
tpips is recommended for large benchmarks and experiments, when analysis and optimization results do not require interactive working. tpips is used for the validation of each new pips version.
tpips can be used to automatically replay a manual wpips or
tpips session by using logfile_to_tpips. The
logfile_to_tpips command derives a tpips script
from a logfile in a workspace (see Example 4.2). A PIPS beginner
should start with a window interface, wpips or epips, and not with
tpips.
Access to Unix Shell and to PIPS properties is provided by tpips. PIPS properties can be modified from tpips , and only from tpips during a PIPS session (see Example4.3). On the other hand, Wpips reads at the beginning of the session the default properties and the new ones (re)defined in the properties.rc file, but no change can be done afterwards. Resetting properties during a session can be used to rebuild an application when some modules have been updated by PIPS, e.g. after partial evaluation.
The tpips commands are listed on-line by the help command. Possible arguments are completed or suggested by automatic completion (TAB and TAB/TAB). A command may be spread on several lines by guarding the line feed characters by backslashes.
Different functions can be activated with the tpips commands. We decompose these functions in those related to the workspace, the analysis and transformation requests, the pips properties and options and the the environment. Functions and their arguments are presented in the next subsections.
These commands can be used several times during a session or within a tpips script file.
To apply a transformation or request a particular resource, use the following tpips commands.
_FILE extension.
A resource, i.e. any piece of information computed by PIPS, can be required by command:
make <resource>
or
make <resource[owner]>
which uses interproceduraly and recursively default rules
(see pips command Build). Or it is produced by a specific
rule:
apply <rule>
which will require all its resource arguments by recursively calling make (see pips command Perform).
The owner of a resource is the module it is attached to. By default, the owner is assumed to be the current module.
File resources can be displayed on screen:
display <printable_resource>
as with the pips Display script.
A specific current module is selected as current module with:
module MODULE_NAME
When several rules, i.e. functions, can be used to compute the same resource, for instance a parallel version of a module, the rule selection command is:
activate <rule>
It is equivalent to the pips Select command.
echo ${<variable-name>})
- <file-name>
- Unix path and file name.
Shell syntax, such as*.f, can be used whensoption is specified orTPIPS_IS_A_SHELLvariable is set.- <workspace-name>
- Unix file name - no path.
- <module-name>
- Fortran function name in capital letters.
- <rule-name>
- rule name (see Section 5)
- <resource-descriptor>
- It is a
resource[OWNER]expression: a pipsmake resource name to be computed for each module associated to OWNER (see Sections 6 and 7).- <rule-descriptor>
- It is a
rulename[OWNER]expression: a pipsmake instantiated rule to be applied on each module associated to OWNER (see Section 5).
The OWNER - used in the previous <rule-descriptor> and < resource-descriptor> - can take these formats:
- module-name
- the target module name.
- %PROGRAM
- the whole program (for global resource) .
- %MAIN
- the main module of the program.
- %MODULE
- the current module.
- ${MODULES}
- the modules associated to the Shell variable MODULES. The different names are SPACE or/and TAB separated.
- %ALL
- All worksapce modules
- %CALLEES
- All the callees of the current selected module.
- %CALLERS
- All the callers of the current selected module.
A simple tpips session is made of a few steps. First, a
workspace must be created:
create work source1.f source2.f
and a subdirectory of the current directory, here work.database, is created to store and retrieve code and information computed by PIPS about subroutines and functions found in source1.f or source2.f.
Then, you have to select a module, let say FOO, by typing:
module FOO
unless there is only one function or subroutine in the Fortran file(s) which were passed to the create command, in which case it is automatically selected.
To keep it simple the first time, you should then try to display the sequential code of routine FOO by typing:
display PRINTED_FILE
Other resource names let you visualize the parallelized code (PARALLELPRINTED_FILE), or the call graph (CALLGRAPH_FILE)... Names for printable resources usually contain the string FILE.
The standard command to leave tpips is quit but a control-D or end-of-file condition are valid too.
Interactive analysis of module MATMUL from source code pgmsrc.f, in workspace pgm:
$ tpips
tpips > create pgm pgm-src.f
tpips > module MATMUL
tpips > display PARALLELPRINTED_FILE
tpips > quit
This example presents a use of:
setenv PIPS_SRCPATH SRC
*.f,
CALLGRAPH_FILE[%ALL]
setenv PIPS_SRCPATH SRC # initiates the source file directory to SRC
create wc *.f # creates the wc workspace for the
# Fortran files of the PIPS_SRCPATH
# directory
display CALLGRAPH_FILE[%ALL] # CONTROL GRAPH COMPUTATION for each routine
close
quit
|
This example presents some Pips analyses and use of
module TEST,
MUST_REGIONS, REGION_CHAINS
logfile_to_tpips command
sh>tpips # run tpips
tpips> create wfoo essai.f # create a workspace for the program essai.f
tpips> module TEST # select the default module TEST
tpips> display CALLGRAPH_FILE # display the sub-callgraph for the
module TEST
tpips> make PROPER_EFFECTS[%ALL] # compute proper effects for every
modules
tpips> activate MUST_REGIONS # select the rule must_regions instead
of the default rule may_regions
tpips> activate REGION_CHAINS # select the rule regions_chains for
computing Use-Def chains in essai.f
tpips> display DG_FILE[%ALL] # display all the dependance graphs
tpips> close wfoo # close the workspace
tpips> quit # quit tpips
|
To store this simple session in a tpips file, use the command:
logfile_to_tpips wfoo > foo.tpips
that generates the following tpips commands in File foo.tpips.
# # file generated by logfile_to_tpips for workspace wfoo # create wfoo essai.f module TEST display CALLGRAPH_FILE[TEST] display PROPER_EFFECTS[TEST] activate MUST_REGIONS activate REGION_CHAINS display DG_FILE[TEST] close quit # EOF |
Note that expression %ALL has been expanded by all
program routines, in that example there is only one TEST
routine in essai.f.
This example presents some pips transformations and use of
PREPROCESSOR_MISSING_FILE_HANDLING "generate" ,
apply CLONE_ON_ARGUMENT[FUNCT].
PRINT_CODE,..
SUPPRESS_DEAD_CODE[${modules}], UNSPLIT[%PROGRAM],..
PRINTED_FILE[FUNCT], CALLGRAPH_FILE[%ALL],..
# Delete Workspace clone in case it already exists
delete clone
setenv PIPS_SRCPATH SRC
# Stop as soon as the first user error occurs
setproperty ABORT_ON_USER_ERROR TRUE
# Generates missing files and routines
setproperty PREPROCESSOR_MISSING_FILE_HANDLING "generate"
# Substitute Fortran statement functions
setproperty PARSER_EXPAND_STATEMENT_FUNCTIONS TRUE
# Restructures the program to eliminate as many GOTO as possible
setproperty UNSPAGHETTIFY_TEST_RESTRUCTURING=TRUE
setproperty UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION=TRUE
#
# prettyprinter settings
setproperty PRETTYPRINT_ALL_DECLARATIONS TRUE
# creates the workspace
create clone *.f
echo # initial version of FUNCT
display PRINTED_FILE[FUNCT]
#
# just to insure that all routines are generated.
make CALLGRAPH_FILE[%ALL]
#
# let us clone FUNCT on the second argument.
# no interprocedural analysis is needed.
setproperty TRANSFORMATION_CLONE_ON_ARGUMENT 2
capply CLONE_ON_ARGUMENT[FUNCT]
# The clone transformation generates 4 clones
# because there are 4 different values for the second
# argument of FUNCT
setenv modules "FUNCT_0 FUNCT_1 FUNCT_2 FUNCT_3"
#
# suppress dead code must be applied twice...
# eliminate dead code after cloning
apply SUPPRESS_DEAD_CODE[${modules}]
apply SUPPRESS_DEAD_CODE[${modules}]
# Eliminates useless declaration after cloning and dead code
# suppression
apply CLEAN_DECLARATIONS[FUNCT ${modules}]
echo # after cloning, dead code elimination and declarations cleaning
make PRINTED_FILE[${modules}]
#
# regenerates the source files with calls to cloned functions only
#
activate PRINT_CODE
apply UNSPLIT[%PROGRAM]
close
|
capply PARTIAL_EVAL[%ALL]
applies a partial evaluation on all routines concurrently without any
verification process between two transformations. The partial evaluation
of a routine does not modify other routine predicates, even if the code
(one routine) has been modified by the transformation. It is not
necessary to ask for a sequential application that will impose the
analysis and re-computation of all routine predicates between two partial
evaluations.
create foo *.f echo echo CALL_GRAPH[%ALL] Computation echo display CALLGRAPH_FILE[%ALL] # ask interprocedural information activate PRECONDITIONS_INTER_FULL activate TRANSFORMERS_INTER_FULL module FUNCT capply PARTIAL_EVAL[%ALL] #echo #echo PRINT_CODE_PROPER_EFFECTS Activation #echo # #activate PRINT_CODE_PROPER_EFFECTS #display PRINTED_FILE[%ALL] # #echo #echo PRINT_CODE_CUMULATED_EFFECTS Activation #echo # #activate PRINT_CODE_CUMULATED_EFFECTS #display PRINTED_FILE[%ALL] echo echo PRINT_CODE_TRANSFORMERS Activation echo activate PRINT_CODE_TRANSFORMERS display PRINTED_FILE[%ALL] echo echo PRINT_CODE_PRECONDITIONS Activation echo activate PRINT_CODE_PRECONDITIONS display PRINTED_FILE[%ALL] echo echo ICFG_WITH_LOOPS_REGIONS echo activate PRINT_ICFG_WITH_LOOPS_REGIONS display ICFG_FILE[%ALL] echo echo REGIONS Computation echo activate MUST_REGIONS activate PRINT_CODE_REGIONS display PRINTED_FILE[%ALL] close quit |
# resize the entities table. Useful for large benchmarks.
setenv NEWGEN_MAX_TABULATED_ELEMENTS 150000
setenv MAINROUTINE TOTO
delete DVCG
create DVCG *.f
echo
echo CALLGRAPH_FILE[${MAINROUTINE}] Computation
echo
make CALLGRAPH_FILE[${MAINROUTINE}]
echo
echo DVCG_FILE[${MAINROUTINE}] Computation
echo
make DVCG_FILE[${MAINROUTINE}]
# type DaVinci DVCG.database/${MAINROUTINE}/${MAINROUTINE}.daVinci
# to visualize
close
quit
|
# # Perfect club ADM benchmark. echo Perfect/adm.f # delete adm create adm adm.f cputim.f elapse.f setproperty UNSPAGHETTIFY_TEST_RESTRUCTURING=TRUE setproperty UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION=TRUE setproperty PARALLELIZATION_STATISTICS=TRUE echo ADM scalar privatization... capply PRIVATIZE_MODULE[%ALL] activate PRECONDITIONS_INTER_FULL activate TRANSFORMERS_INTER_FULL activate RICE_SEMANTICS_DEPENDENCE_GRAPH apply PARTIAL_EVAL[%ALL] echo ADM parallelization... make PARALLELPRINTED_FILE[%ALL] close quit |
PRECONDITIONS_INTER_FULL), interprocedural transformer
(TRANSFORMERS_INTER_FULL) and accurate
dependencies (RICE_SEMANTICS_DEPENDENCE_GRAPH). Rules are selected
by activate or selected and applied by apply and capply.
More information on each particular rule is presented in the pipsmake documentation.
#### ANALYSES #### ATOMIC_CHAINS CONTINUATION_CONDITIONS FLINTER PROPER_REFERENCES ### COMPLEXITITY ANY_COMPLEXITIES FP_COMPLEXITIES UNIFORM_COMPLEXITIES SUMMARY_COMPLEXITY ### PRIVATIZATION ARRAY_PRIVATIZER ARRAY_SECTION_PRIVATIZER DECLARATIONS_PRIVATIZER PRIVATIZE_MODULE ### EFFECTS CUMULATED_EFFECTS CUMULATED_REDUCTIONS CUMULATED_REFERENCES IN_EFFECTS IN_SUMMARY_EFFECTS OUT_EFFECTS OUT_SUMMARY_EFFECTS PROPER_EFFECTS SUMMARY_EFFECTS ### PRECONDITIONS PRECONDITIONS_INTER_FAST PRECONDITIONS_INTER_FULL PRECONDITIONS_INTRA SUMMARY_PRECONDITION ### TRANSFORMERS SUMMARY_TRANSFORMER TRANSFORMERS_INTER_FAST TRANSFORMERS_INTER_FULL TRANSFORMERS_INTRA_FAST TRANSFORMERS_INTRA_FULL ### REGIONS IN_OUT_REGIONS_CHAINS IN_REGIONS IN_SUMMARY_REGIONS MAY_REGIONS MUST_REGIONS OUT_REGIONS OUT_SUMMARY_REGIONS REGION_CHAINS SUMMARY_REGIONS ### CALLGRAPH FULL_GRAPH_OF_CALLS CALLGRAPH GRAPH_OF_CALLS ### DEPENDENCES RICE_ALL_DEPENDENCE RICE_CRAY RICE_DATA_DEPENDENCE RICE_FAST_DEPENDENCE_GRAPH RICE_FULL_DEPENDENCE_GRAPH RICE_REGIONS_DEPENDENCE_GRAPH RICE_SEMANTICS_DEPENDENCE_GRAPH ### REDUCTIONS PROPER_REDUCTIONS SUMMARY_REDUCTIONS #### TRANSFORMATIONS #### FORWARD_SUBSTITUTE PARTIAL_EVAL ### RESTRUCTURATION ATOMIZER CLEAN_DECLARATIONS CLONE CLONE_ON_ARGUMENT CLONE_SUBSTITUTE RESTRUCTURE_CONTROL SUPPRESS_DEAD_CODE UNSPAGHETTIFY UNSPLIT USE_DEF_ELIMINATION ### LOOP TRANSFORMATION DISTRIBUTER FULL_UNROLL LOOP_INTERCHANGE LOOP_NORMALIZE LOOP_REDUCTIONS STRIP_MINE UNROLL ### PARALLELIZATION COARSE_GRAIN_PARALLELIZATION NEST_PARALLELIZATION |
#### PRETTYPRINT #### ### PRINT_CALL_GRAPH PRINT_CALL_GRAPH PRINT_CALL_GRAPH_WITH_COMPLEXITIES PRINT_CALL_GRAPH_WITH_CUMULATED_EFFECTS PRINT_CALL_GRAPH_WITH_IN_REGIONS PRINT_CALL_GRAPH_WITH_OUT_REGIONS PRINT_CALL_GRAPH_WITH_PRECONDITIONS PRINT_CALL_GRAPH_WITH_PROPER_EFFECTS PRINT_CALL_GRAPH_WITH_REGIONS PRINT_CALL_GRAPH_WITH_TRANSFORMERS ### PRINT_CHAINS_GRAPH PRINT_CHAINS_GRAPH ### PRINT_CODE WITH ... PRINT_CODE PRINT_CODE_AS_A_GRAPH PRINT_CODE_AS_A_GRAPH_COMPLEXITIES PRINT_CODE_AS_A_GRAPH_CUMULATED_EFFECTS PRINT_CODE_AS_A_GRAPH_IN_REGIONS PRINT_CODE_AS_A_GRAPH_OUT_REGIONS PRINT_CODE_AS_A_GRAPH_PRECONDITIONS PRINT_CODE_AS_A_GRAPH_PROPER_EFFECTS PRINT_CODE_AS_A_GRAPH_REGIONS PRINT_CODE_AS_A_GRAPH_TRANSFORMERS PRINT_CODE_COMPLEMENTARY_SECTIONS PRINT_CODE_COMPLEXITIES PRINT_CODE_CONTINUATION_CONDITIONS PRINT_CODE_CUMULATED_EFFECTS PRINT_CODE_CUMULATED_REDUCTIONS PRINT_CODE_CUMULATED_REFERENCES PRINT_CODE_IN_EFFECTS PRINT_CODE_IN_REGIONS PRINT_CODE_OUT_EFFECTS PRINT_CODE_OUT_REGIONS PRINT_CODE_PRECONDITIONS PRINT_CODE_PRIVATIZED_REGIONS PRINT_CODE_PROPER_EFFECTS PRINT_CODE_PROPER_REDUCTIONS PRINT_CODE_PROPER_REFERENCES PRINT_CODE_PROPER_REGIONS PRINT_CODE_REGIONS PRINT_CODE_STATIC_CONTROL PRINT_CODE_TRANSFORMERS ### PRINT_DEPENDENCE_GRAPH PRINT_EFFECTIVE_DEPENDENCE_GRAPH PRINT_LOOP_CARRIED_DEPENDENCE_GRAPH PRINT_WHOLE_DEPENDENCE_GRAPH ### PRINT_ICFG PRINT_ICFG PRINT_ICFG_WITH_COMPLEXITIES PRINT_ICFG_WITH_CONTROL PRINT_ICFG_WITH_CONTROL_COMPLEXITIES PRINT_ICFG_WITH_CONTROL_CUMULATED_EFFECTS PRINT_ICFG_WITH_CONTROL_IN_REGIONS PRINT_ICFG_WITH_CONTROL_OUT_REGIONS PRINT_ICFG_WITH_CONTROL_PRECONDITIONS PRINT_ICFG_WITH_CONTROL_PROPER_EFFECTS PRINT_ICFG_WITH_CONTROL_REGIONS PRINT_ICFG_WITH_CONTROL_TRANSFORMERS PRINT_ICFG_WITH_CUMULATED_EFFECTS PRINT_ICFG_WITH_IN_REGIONS PRINT_ICFG_WITH_LOOPS PRINT_ICFG_WITH_LOOPS_COMPLEXITIES PRINT_ICFG_WITH_LOOPS_CUMULATED_EFFECTS PRINT_ICFG_WITH_LOOPS_IN_REGIONS PRINT_ICFG_WITH_LOOPS_OUT_REGIONS PRINT_ICFG_WITH_LOOPS_PRECONDITIONS PRINT_ICFG_WITH_LOOPS_PROPER_EFFECTS PRINT_ICFG_WITH_LOOPS_REGIONS PRINT_ICFG_WITH_LOOPS_TRANSFORMERS PRINT_ICFG_WITH_OUT_REGIONS PRINT_ICFG_WITH_PRECONDITIONS PRINT_ICFG_WITH_PROPER_EFFECTS PRINT_ICFG_WITH_REGIONS PRINT_ICFG_WITH_TRANSFORMERS PRINT_INITIAL_PRECONDITION ### PRINT_PARALLELIZED_CODE PRINT_PARALLELIZED77_CODE PRINT_PARALLELIZED90_CODE PRINT_PARALLELIZEDCMF_CODE PRINT_PARALLELIZEDCRAFT_CODE PRINT_PARALLELIZEDCRAY_CODE PRINT_PARALLELIZEDHPF_CODE PRINT_PARALLELIZEDOMP_CODE ### PRINT_SOURCE PRINT_SOURCE PRINT_SOURCE_COMPLEXITIES PRINT_SOURCE_CONTINUATION_CONDITIONS PRINT_SOURCE_CUMULATED_EFFECTS PRINT_SOURCE_IN_EFFECTS PRINT_SOURCE_IN_REGIONS PRINT_SOURCE_OUT_EFFECTS PRINT_SOURCE_OUT_REGIONS PRINT_SOURCE_PRECONDITIONS PRINT_SOURCE_PROPER_EFFECTS PRINT_SOURCE_REGIONS PRINT_SOURCE_TRANSFORMERS |
make and display commands. These
non-printable resources are encoded in internal data structures. The
corresponding printable resources are listed in the following section.
These resources are detailed in the pipsmake documentation.
CALLEES CALLERS CHAINS COMPLEXITIES DG ENTITIES SUMMARY_COMPLEXITY ## CODE CODE PARALLELIZED_CODE PARSED_CODE ## EFFECTS CUMULATED_EFFECTS CUMULATED_IN_EFFECTS IN_EFFECTS IN_SUMMARY_EFFECTS OUT_EFFECTS OUT_SUMMARY_EFFECTS PROPER_EFFECTS SUMMARY_EFFECTS |
## REGIONS COPY_OUT_REGIONS CUMULATED_IN_REGIONS INV_IN_REGIONS INV_REGIONS IN_REGIONS IN_SUMMARY_REGIONS OUT_REGIONS OUT_SUMMARY_REGIONS PRIVATIZED_REGIONS PROPER_REGIONS REGIONS SUMMARY_REGIONS ## REDUCTIONS CUMULATED_REDUCTIONS PROPER_REDUCTIONS SUMMARY_REDUCTIONS ## REFERENCES CUMULATED_REFERENCES PROPER_REFERENCES |
## PRECONDITION INITIAL_PRECONDITION PRECONDITIONS PROGRAM_PRECONDITION SUMMARY_PRECONDITION ## TRANSFORMERS SUMMARY_TRANSFORMER TRANSFORMERS ## CONTINUATION MAY_CONTINUATION MAY_SUMMARY_CONTINUATION MUST_CONTINUATION MUST_SUMMARY_CONTINUATION |
display tpips command. They are stored as
human readable ASCII file in the workspace. The current resources which
are printable follow, for more information see the pipsmake documentation.
CALLGRAPH_FILE # call graph file DG_FILE # Dependence graph file DVCG_FILE # Davinci Dependence graph file FLINTED_FILE # source file with errors GRAPH_PRINTED_FILE # control graph ICFG_FILE # interprocedural control flow graph INITIAL_FILE # after splitting PARALLELPRINTED_FILE # parallel version PRINTED_FILE # annoted sequential version SOURCE_FILE # after the preprocessing phase USER_FILE # after regeneration of user files |
Before using tpips, you need to add a PIPS root directory to your path and to set some PIPS environment variables. In order to do that, you can execute the shell script Pips/pipsrc.sh for any sh compatible shell, e.g. ksh or bash, or Pips/pipsrc.csh for any csh compatible shell, e.g. tcsh.
This document was generated using the LaTeX2HTML translator Version 97.1 (release) (July 13th, 1997)
Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
The command line arguments were:
latex2html -split 0 tpips.tex.
The translation was initiated by Corinne ANCOURT on 10/5/1998