%%
%% $Id$
%%
%% Copyright 1989-2016 MINES ParisTech
%%
%% This file is part of PIPS.
%%
%% PIPS is free software: you can redistribute it and/or modify it
%% under the terms of the GNU General Public License as published by
%% the Free Software Foundation, either version 3 of the License, or
%% any later version.
%%
%% PIPS is distributed in the hope that it will be useful, but WITHOUT ANY
%% WARRANTY; without even the implied warranty of MERCHANTABILITY or
%% FITNESS FOR A PARTICULAR PURPOSE.
%%
%% See the GNU General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with PIPS. If not, see .
%%
% PIPS Project
%
% Description des enchainements possibles des passes et analyses de PIPS
% pour pipsmake
%
% Attention : chaque phase ne doit utiliser, pour les modules,
% que des ressources definies dans une phase precedente !
%
% Derivation rules and aliases must be included in verbatim environments.
% Nothing else should appear in a verbatim environment.
%
% Some tourist information from the last century follows... Read the log
% for fresh news instead!
%
% Modifications:
% - a dependence on MODULE.cumulated_effects for print_transformers and
% print_preconditions
% - print_code_complexities depends on MODULE.summary_complexity
% added by Lei Zhou Feb.28 91
% - atomizer, a program transformation that translates the fortran
% instructions into atomic instructions (still in fortran style).
% added by Alexis Platonoff, Jun 12 1991
% - wp65, code generation for distributed memory machines: PUMA,
% ESPRIT project 2701, Francois Irigoin, 15 October 1991
% - loop_normalize, introduced by A.Platonoff, Oct. 30 1991.
% - print_parallelized_code is removed, because it is identical to
% print_parallelized77_code. L. Zhou, Jan. 20 1992.
% - reductions, Pierre Jouvelot, Apr. 1992
% - rice_data_dependence_graph,Pierre Jouvelot, Apr. 1992
% - print_rice_semantics_dependence_graph, Yi-Qing Yang, June, 1992
% - choice for use-def chains between standard (atomic) use-def chains
% and use-def chains based on regions;
% - MODULE.code added as a production of the four parallelization rules
% to overcome the inconsistency of hash tables after a
% parallelization, Francois Irigoin, 18 May 1993
% - Last modification undone because of a
% methods_io.c:122: `DBR_PARALLELIZED_CODE' undeclared, outside of functions
% in ~pips/Pips/Development/Lib/pipsdbm. Ronan Keryell, 19 may 1993.
% - hpfc rules added, Fabien Coelho, 16/09/93
% - static_controlize, print_code_static_control, rules added,
% Arnauld Leservot et Alexis Platonoff, 6/10/93
% - loop_normalize removed, A.Platonoff, 6/10/93
% - normalization of rule names as names of functions called by
% pipsmake; this is necessary to automatize the computation of the
% builder_map; Francois Irigoin, 8 October 1993
% - array_dfg, skeleton, print_array_dfg, scheduling, print_bdt rules added
% AL, AP, 12/10/93
% - Flinter and print_parallelized*_code replaced so that those
% phases use only resources previously defined. AL 13/10/93
% - hpfcompile will use regions. FC 24/03/94
% - prgm_mapping, reindexing, print_parallelizedCMF_code,
% print_parallelizedCRAFT_code rules added, AP, 9/11/94
% - reindexed_code resource added, AP, 9/11/94
% - skeleton removed, AP, 9/11/94
% - unspaghettify added. RK, 26/07/1995.
% - loop_normalize (again :-), in transformations, AP, 22/09/95
% - continuation added, BC, 26/2/96.
% - reductions added, FC 15/06/96
\documentclass[a4paper]{report}
\usepackage[latin9]{inputenc}
%\usepackage{alltt,html,fancybox,amstext,xspace,psfig}
\usepackage{amstext,alltt}
\usepackage[backref,pagebackref]{hyperref}
\usepackage{xspace}
% For the smileys: :-)
\usepackage{wasysym}
\usepackage{graphicx,ifpdf}
% Use classical figure extension if we are in classical LaTeX (instead of
% pdflatex), necessary for TeX4ht (htlatex):
\ifpdf
\else
\DeclareGraphicsExtensions{.idraw,.eps}
\fi
\makeatletter
% Test for a TeX4ht command:
%%\@ifundefined{HCode}{%
%% % We are generating PDF, so allow to break down URL:
%% \usepackage{breakurl}}{%
%% % else we are generating HTML with TeX4ht, use plain url:
%% \usepackage{url}}
\usepackage{makeidx}
\usepackage{listings}
\lstset{extendedchars=true, language=C}
%% Cannot work with verbatim: \begin{verbatim} absorbs \end{example}
%% \newenvironment{example}{\begin{verbatim}}{\end{verbatim}}
\newenvironment{PipsExample}{\VerbatimEnvironment
\begin{Verbatim}}{\end{Verbatim}}
%%\newenvironment{PipsProp}{\VerbatimEnvironment
%%\begin{Verbatim}}{\end{Verbatim}}
%% \newenvironment{PipsMake}{\VerbatimEnvironment
%% \begin{Verbatim}}{\end{Verbatim}}
\newenvironment{PipsMake}{\begin{alltt}}{\end{alltt}}
\newcommand{\PipsPIPSmakePDF}{\url{http://www.cri.ensmp.fr/pips/pipsmake-rc.htdoc/pipsmake-rc.pdf}\xspace}
\newcommand{\PipsPIPSmakeHTDOC}{\url{http://www.cri.ensmp.fr/pips/pipsmake-rc.htdoc}\xspace}
\newcommand{\PdaVinci}{\LINK{\emph{daVinci}}{http://www.informatik.uni-bremen.de/~davinci}}
% Some day it should point to the right place for the given property...
% SG: done !
\newcommand{\PipsPropRef}[1]{\texttt{\detokenize{#1}}~\ref{prop:#1}}
\newcommand{\PipsPassRef}[1]{\texttt{\detokenize{#1}}~\ref{pass:#1}}
%\newcommand{\PipsProp}[2]{\label{prop:#1}\texttt{\detokenize{#1}} (defaults: \texttt{\detokenize{#2}})}
\lstnewenvironment{PipsProp}[1]
{\lstset{basicstyle=\ttfamily\small,frame=single,label=prop:#1}}
{}
\newenvironment{PipsPass}[1]{\label{pass:#1}}{}
% To keep track of all titles down to subsubsections
\setcounter{tocdepth}{3}
\title{PIPS High-Level Software Interface \\
Pipsmake Configuration}
\author{R\'emi Triolet, Fran\c{c}ois Irigoin\\
and many other contributors\\
MINES ParisTech \\
Math\'ematiques et Syst\`emes \\
Centre de Recherche en Informatique \\
77305 Fontainebleau Cedex \\
France \\}
\date{
$~$Id$~$\\[3cm]
You can get a printable version of this document on\\
\PipsPIPSmakePDF and a HTML version on \PipsPIPSmakeHTDOC.
}
% Number everything in the TOC:
\setcounter{secnumdepth}{10}
\setcounter{tocdepth}{10}
% \addtolength{\textwidth}{72pt}
% \addtolength{\oddsidemargin}{-48pt}
% \addtolength{\evensidemargin}{-48pt}
% \addtolength{\textheight}{172pt}
% \addtolength{\topmargin}{-60pt}
\renewcommand{\indexname}{Index}
\makeindex
%% short term fix to html style
\newcommand{\LINK}[2]{\href{#2}{#1}\footnote{\url{#2}}\xspace}
%%@UserManualDeclarations
%% Some declarations used to factorize all the label names and so on:
%% Warning : spaces inside \htmladdnormallink{} seems to lead to wrong
%% results...
\newcommand{\CPU}{{\em CPU}}
\newcommand{\HPF}{{\em HPF}}
\newcommand{\HPFC}{\LINK{\emph{HPFC}}{http://www.cri.ensmp.fr/pips/hpfc.html}}
\newcommand{\HPFcompiler}{\LINK{\emph{HPF\space{}compiler}}{http://www.cri.ensmp.fr/pips/hpfc.html}}
\newcommand{\PArrayDataFlowGraphView}{{Array Data Flow Graph View}}
\newcommand{\PELSE}{{\tt ELSE}}
\newcommand{\PGOTO}{{\tt GOTO}}
\newcommand{\PIF}{\texttt{IF}}
\newcommand{\Pips}{\texttt{PIPS}}
\newcommand{\PIPS}{\LINK{\emph{PIPS}}{http://www.cri.ensmp.fr/pips}}
\newcommand{\Pipsmake}{\texttt{pipsmake}}
\newcommand{\PIPSMAKE}{\LINK{\emph{pipsmake}}{http://www.cri.ensmp.fr/pips/pipsmake.html}\xspace}
\newcommand{\PLinear}{\emph{Linear C$^3$}}
\newcommand{\PNEWGEN}{\LINK{\emph{NewGen}}{http://www.cri.ensmp.fr/pips/newgen-manual/newgen-manual.html}}
%% This link is no longer good: Fabien has merged properties-rc.tex in
%% the current document
%% \newcommand{\PROPERTIES}{\LINK{\emph{properties}}{http://www.cri.ensmp.fr/pips/properties-rc}}
\newcommand{\PROPERTIES}{{\em properties}}
\newcommand{\PTHEN}{{\tt THEN}}
\newcommand{\PVM}{{\em PVM}}
\newcommand{\PCallgraphView}{{Call Tree View}}
\newcommand{\PCompileAnHPFProgram}{{Compile an HPF Program}}
\newcommand{\Pcontrolgraph}{{control flow graph}}
\newcommand{\Pcurrentmodule}{{current module}}
\newcommand{\PuDrawGraph}{\LINK{\emph{uDrawGraph}}{http://www.informatik.uni-bremen.de/uDrawGraph}\xspace}
\newcommand{\PDependenceGraphView}{{Dependence Graph View}}
\newcommand{\PDistributedView}{{Distributed View}}
\newcommand{\PEdit}{{Edit}}
\newcommand{\PFlintView}{{Flint View}}
\newcommand{\PICFGView}{{ICFGView}}
\newcommand{\PMakeAnHPFProgram}{{Make an HPF Program}}
\newcommand{\PParallelView}{{Parallel View}}
\newcommand{\PPartialEval}{{Partial Eval}}
\newcommand{\PPlacementView}{{Placement View}}
\newcommand{\Ppreconditions}{{preconditions}}
\newcommand{\PRunAnHPFProgram}{{Run an HPF Program}}
\newcommand{\PSchedulingView}{{Scheduling View}}
\newcommand{\PSequentialView}{{Sequential View}}
\newcommand{\PSequentialViewControlGraph}{{Sequential View with
Control Graph}}
\newcommand{\Punstructured}{{unstructured}}
\newcommand{\PUserView}{{User View}}
\newcommand{\PAliasView}{{Alias View}}
\newcommand{\PViewTheHPFCompilerOutput}{{View the HPF
Compiler Output}}
\newcommand{\Pri}{\LINK{\emph{PIPS Internal\space{}Representation of
Fortran and C code}}{http://www.cri.ensmp.fr/pips/newgen/ri.htdoc}}
\newcommand{\WPsc}{\LINK{\emph{WP65}}{http://www.cri.ensmp.fr/pips/wp65.html}}
%% Now the interface names :
\newcommand{\pips}{\LINK{\texttt{pips}}{http://www.cri.ensmp.fr/pips/batch-interface.html}}
%% This link ends up with 404
%%\newcommand{\EPIPS}{\LINK{\texttt{epips}}{http://www.cri.ensmp.fr/pips/wpips-epips-user-manual.htdoc}}
\newcommand{\EPIPS}{{\em epip}}
\newcommand{\TPIPS}{\LINK{\texttt{tpips}}{http://www.cri.ensmp.fr/pips/line-interface.html}}
\newcommand{\Tpips}{{\em tpips}}
%% This link ends up with 404
%% \newcommand{\WPIPS}{\LINK{\texttt{wpips}}{http://www.cri.ensmp.fr/pips/wpips-epips-user-manual.htdoc}}
\newcommand{\WPIPS}{{\em wpips}}
%% All these links to man pages of PIPS first user interface are corrupted
%% \newcommand{\Init}{\LINK{\texttt{Init}}{http://www.cri.ensmp.fr/pips/Init.html}}
\newcommand{\Init}{{\em Init}}
%% \newcommand{\Select}{\LINK{\texttt{Select}}{http://www.cri.ensmp.fr/pips/Select.html}}
\newcommand{\Select}{{\em Select}}
%% \newcommand{\Perform}{\LINK{\texttt{Perform}}{http://www.cri.ensmp.fr/pips/Perform.html}}
\newcommand{\Perform}{{\em Perform}}
%% \newcommand{\Display}{\LINK{\texttt{Display}}{http://www.cri.ensmp.fr/pips/Display.html}}
\newcommand{\Display}{{\em Display}}
%% \newcommand{\Delete}{\LINK{\texttt{Delete}}{http://www.cri.ensmp.fr/pips/Delete.html}}
\newcommand{\Delete}{{\em Delete}}
%% Pour Beatrice :
\newcommand{\exact}[0]{{\tt EXACT}}
\newcommand{\incluseg}{\subseteq}
\newcommand{\phik}[1]{\ifmmode\phi_{#1}\else$\phi_{#1}$\fi}
\newcommand{\must}[0]{{\tt MUST}}
\newcommand{\may}[0]{{\tt MAY}}
%%!UserManualDeclarations
%%\externallabels{http://www.cri.ensmp.fr/pips/ri}{public_html/ri/labels.pl}
\makeindex
\begin{document}
\thispagestyle{empty}
\maketitle
% \begin{abstract}
% \end{abstract}
%\begin{PipsExample}
%petit essai
%\end{PipsExample}
%% The environment used to mark up the menus layout :
\newenvironment{PipsMenu}[1]{\par{\bf #1}\\\begin{alltt}}{\end{alltt}}
\chapter{Introduction}
\label{chapter:introduction}
This paper describes high-level objects and functions that are
potentially user-visible in a \PIPS{}~\cite{IJT91} interactive
environment. It defines the internal {\em software} interface between
a user interface and program analyses and transformations. This is
clearly not a user guide but can be used as a reference guide, the
best one before source code because {\tt PIPS} user interfaces are very
closely mapped on this document: some of their features are
automatically derived from it.
Objects can be viewed and functions activated by one of \Pips{}
existing user interfaces: \TPIPS{}, the tty style interface which is
currently recommended, \pips{}~\cite{BIJ91}, the old batch
interface, improved by many shell scripts\footnote{Manual pages are
available for \Init{}, \Select{}, \Perform{}, \Display{}, and
\Delete{}, and \pips{}.}, \WPIPS{} and {\tt epips}, the X-Window
System interfaces. The {\tt epips} interface is an extension of
\WPIPS{} which uses {\tt Emacs} to display more information in a more
convenient way. Unfortunately, right now these window-based interfaces
are no longer working and have been replaced by {\tt gpips}. It is
also possible to use \Pips{} through a Python API, pyps.
From a theoretical point of view, the object types and functions
available in {\tt PIPS} define an heterogeneous algebra with
constructors (e.g. parser), extractors (e.g. prettyprinter) and
operators (e.g. loop unrolling). Very few combinations of functions
make sense, but many functions and object types are available. This
abundance is confusing for casual and experiences users as well, and
it was deemed necessary to assist them by providing default
computation rules and automatic consistency management similar to {\tt
make}. The rule interpretor is called \PIPSMAKE{} and described
in~\cite{Bar91}. Its key concepts are the {\em phase}, which correspond
to a \Pips{} function made user-visible, for instance, a parser, the
{\em resources}, which correspond to objects used or defined by the
phases, for instance, a source file or an AST (parsed code), and the
virtual {\em rules}, which define the set of input resources used by a
phase and the set of output resources defined by the phase. Since
\Pips{} is an interprocedural tool, some real inpu resources are not
known until execution. Some variables such as \verb/CALLERS/ or
\verb/CALLEES/ can be used in virtual rules. They are expanded at
execution to obtain an effective rule with the precise resources needed.
For debugging purposes and for advanced users, the precise choice and
tuning of an algorithm can be made using \PROPERTIES{}. Default
properties are installed with \Pips{} but they can be redefined,
partly or entirely, by a {\tt properties.rc} file located in the
current directory. Properties can also be redefined from the user
interfaces, for example with the command \texttt{setproperty} when the
\Tpips{} interface is used.
As far as their static structures are concerned, most object types are
described in more details in \Pri. A dynamic view is given here. In
which order should functions be applied? Which object do they produce
and vice-versa which function does produce such and such objects? How
does \Pips{} cope with bottom-up and top-down interprocedurality?
Resources produced by several rules and their associated rule must be
given alias names when they should be explicitly computed or activated
by an interactive interface\marginpar{FI: I do not understand.}. This
is otherwise not relevant. The alias names are used to generate
automatically header files and/or test files used by PIPS interfaces.
No more than one resource should be produced per line of rule because
different files are automatically extracted from this one\footnote{See
the local Makefile: pipsmake-rc, and alias file: wpips-rc.}. Another
caveat is that \emph{all} resources whose names are suffixed with
\verb|_file| are considered printable or displayable, and the others
are considered binary data, even though they may be ASCII strings.
This \LaTeX{} file is used by several procedures to derive some pieces
of C code and ASCII files. The useful information is located in the
{\em PipsMake} areas, a very simple literate programming
environment... For instance \verb+alias+ information is used to
generate automatically menus for window-based interfaces such as
\verb+wpips+ or \verb+gpips+. Object (a.k.a resource) types and
functions are renamed using the alias declaration. The name space of
aliases is global. All aliases must have different names. Function
declarations are used to build a mapping table between function names
and pointer to C functions, \texttt{phases.h}. Object suffixes are
used to derive a header file, {\tt resources.h}, with all resource
names. Parts of this file are also extracted to generate on-line
information for {\tt wpips} and automatic completion for {\tt tpips}.
The behavior of {\tt PIPS} can be slightly tuned by using {\tt
properties} and some environment variables.
%%
Most properties are linked to a particular phase, for instance to
prettyprint, but some are linked to {\tt PIPS} infrastructure and are
presented in Chapter~\ref{chapter-global-options}.
\section{Informal Pipsmake Syntax}
\label{sec:informal-syntax}
To understand and to be able to write new rules for {\tt pipsmake}, a
few things need to be known.
\subsection{Example}
\label{sec:example}
The rule:
\begin{alltt}
proper_references > MODULE.proper_references
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_effects
\end{alltt}
means that the method \verb|proper_references| is used to generate the
\verb|proper_references| resource of a given \texttt{MODULE}. But to
generate this resource, the method needs access to the resource holding
the symbole table, \texttt{entities}, of the \texttt{PROGRAM} currently
analyzed, the \texttt{code} resource (the instructions) of the given
\texttt{MODULE} and the \PipsPassRef{summary_effects} resource (the side effects
on the memory) of the functions and procedures called by the given
\texttt{MODULE}, the \texttt{CALLEES}.
Properties are also declared in this file. For instance
\begin{alltt}
ABORT_ON_USER_ERROR FALSE
\end{alltt}
declares a property to stop interpreting user commands when an error
is made and sets its default value to false, which makes sense most of
the time for interactive uses of {\tt PIPS}. But for non-regression
tests, it may be better to turn on this property.
\subsection{Pipsmake variables}
\label{sec:program-pieces}
The following variables are defined to handle interprocedurality:
\begin{description}
\item[\texttt{PROGRAM}:] the whole application currently analyzed;
\item[\texttt{MODULE}:] the current \texttt{MODULE} (a procedure or
function);
\item[\texttt{ALL}:] all the \texttt{MODULE}s of the current
\texttt{PROGRAM}, functions and compilation units;
\item[\texttt{ALLFUNC}:] all the \texttt{MODULE}s of the current
\texttt{PROGRAM} that are functions;
\item[\texttt{CALLEES}:] all the \texttt{MODULE}s called in the given
\texttt{MODULE};
\item[\texttt{CALLERS}:] all the \texttt{MODULE}s that call the given
\texttt{MODULE}.
\end{description}
These variables are used in the rule definitions and instantiated
before \texttt{pipsmake} infers which resources are pre-requisites for a
rule.
The environment variable \verb|PIPS_IGNORE_FUNCTION_RX| is taken as a
regular expression to filter out unwanted functions, such as static
functions, inlined or not, which arise in some standard header files
from time to time.
%%
For instance, with gcc 4.8, you should define
\begin{verbatim}
export PIPS_IGNORE_FUNCTION_RX='!__bswap_'
\end{verbatim}
\section{Properties and Environment Variables}
This paper also defines and describes global variables used to modify
or fine tune PIPS behavior. Since global variables are useful for some
purposes, but always dangerous, PIPS programmers are required to avoid
them or to declare them explicitly as \emph{properties}. Properties
have an ASCII name and can have boolean, integer or string values.
% The information here is machine and/or site independent.
Casual users should not use them. Some properties are modified for them by
the user interface and/or the high-level functions. Some property
combinations may be meaningless. More experienced users can set their
values, using their names and a user interface.
Experienced users can also modify properties by inserting a file
called \texttt{properties.rc} in their local directory. Of course,
they cannot declare new properties, since they would not be recognized
by the {\tt PIPS} system. The local property file is read \emph{after}
the default property file, \verb+$PIPS_ROOT/etc/properties.rc+.
% $ emacs latex environment does not know about \verb
Some user-specified property
values may be ignored because they are modified by a PIPS function before
it had a chance to have any effect. Unfortunately, there is no explicit
indication of usefulness for the properties in this report.
The default property file can be used to generate a custom version of
\texttt{properties.rc}. It is derived automatically from this documentation,
\verb+Documentation/pipsmake-rc.tex+.
PIPS behavior can also be altered by Shell environment variables. Their
generic names is \verb+XXXX_DEBUG_LEVEL+, where \verb+XXXX+ is a library
or a phase or an interface name (of course, there are
exceptions). Theoretically these environment variables are also declared
as properties, but this is generally forgotten by programmers. A debug
level of 0 is equivalent to no tracing. The amount of tracing increases
with the debug level. The maximum useful value is 9.
Another Shell environment variable, \verb+NEWGEN_MAX_TABULATED_ELEMENTS+,
is useful to analyze large programs. Its default value is 12,000 but it is
not uncommon to have to set it up to 200,000.
Properties and environement variables are listed below on a source
library basis. Properties used in more than one library or used by
{\tt PIPS} infrastructure are presented
first. Section~\ref{section-pips-infrastructure} contains information
about properties related to infrastructure, external and user
interface libraries. Properties for analyses are grouped in
Chapter~\ref{section-analyses}. Properties for program
transformations, parallelization and distribution phases are listed in
the next section in Chapters~\ref{section-program-transformations} and
\ref{section-program-transformations-parallelization-distribution}. User
output produced by different kinds of prettyprinters are presented in
Chapter~\ref{section-output-files}.
Chaper~\ref{section-feautrier-methods} is dedicated to properties of
the libraries added by CEA to implement Feautrier's method.
\section{Outline}
Rule and object declaration are grouped in chapters: input files
(Chapter~\ref{section-input-files}), syntax analysis and abstract
syntax tree (Chapter~\ref{section-abstract-syntax-tree}), analyses
(Chapter~\ref{section-analyses}), parallelizations
(Chapter~\ref{section-program-transformations-parallelization-distribution}),
program transformations
(Chapter~\ref{section-program-transformations}) and prettyprinters of
output files (Chapter~\ref{section-output-files}).
Chapter~\ref{section-feautrier-methods} describes several analyses
defined by Paul
\textsc{Feautrier}. Chapter~\ref{section-user-interface-menu-layouts}
contains a set of menu declarations for the window-based interfaces.
Virtually every PIPS programmer contributed some lines in this
report. Inconsistencies are likely. Please report them to the PIPS
team\footnote{pips-support@cri.ensmp.fr}!
\tableofcontents
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% GLOBALS
\chapter{Global Options}
\label{chapter-global-options}
Options are called {\em properties} in \Pips{}. Most of them are
related to a specific {\em phase}, for instance the dependence graph
computation. They are declared next to the corresponding phase
declaration. But some are related to one library or even to several
libraries and they are declared in this chapter.
Skip this chapter on first reading. Also skip this chapter on second
reading because you are unlikely to need these properties until you
develop in {\tt PIPS}.
\section{Fortran Loops}
Are DO loops bodies executed at least once (F-66 style), or not (Fortran~77)?
\begin{PipsProp}{ONE_TRIP_DO_FALSE}
ONE_TRIP_DO FALSE
\end{PipsProp}
is useful for use/def and semantics analysis but is not used for
region analyses. This dangerous property should be set to FALSE. It is
not consistently checked by {\tt PIPS} phases, because nobody seems to
use this obsolete Fortran feature anymore.
\section{Logging}
\index{Logging}
With
\begin{PipsProp}{LOG_TIMINGS}
LOG_TIMINGS FALSE
\end{PipsProp}
it is possible to display the amount of real, cpu and system times
directly spent in each phase as well as the times spent
reading/writing data structures from/to {\tt PIPS} database. The computation
of total time used to complete a \Pipsmake{} request is broken down into
global times, a set of phase times which is the accumulation of the
times spent in each phase, and a set of IO times, also accumulated
through phases.
Note that the IO times are included in the phase times.
With
\begin{PipsProp}{LOG_MEMORY_USAGE}
LOG_MEMORY_USAGE FALSE
\end{PipsProp}
it is possible to log the amount of memory used by each phase and by
each request. This is mainly useful to check if a computation can be
performed on a given machine. This memory log can also be used to
track memory leaks. {\tt Valgrind} may be more useful to track memory
leaks.
\section{PIPS Infrastructure}
\label{section-pips-infrastructure}
\Pips{} infrastructure is based on a few external libraries, Newgen
and Linear, and on three key \PIPS libraries:
\begin{itemize}
\item \verb/pipsdbm/ which manages resources such as \verb/code/
produced by PIPS and ensures persistance,
\item \verb/pipsmake/ which ensures consistency within a
\verb/workspace/ with respect to the producer-consumer rules
declared in this file,
\item and \verb/top-level/ which defines a common API for all \Pips{}
user interfaces, whether human or API.
\end{itemize}
\subsection{Newgen}
\index{NewGen}
\index{Debugging}
Newgen offers some debugging support to check object consistency
(\verb+gen_consistent_p+ and \verb+gen_defined_p+), and for dynamic type
checking. See Newgen documentation\cite{JT89}\cite{JT90}.
\subsection{C3 Linear Library}
\index{C3 Linear Library}
This library is external and offers an independent debugging system.
The following properties specify how null (
\begin{PipsProp}{SYSTEM_NULL}
SYSTEM_NULL ""
\end{PipsProp}
),
undefined
\begin{PipsProp}{SYSTEM_UNDEFINED}
SYSTEM_UNDEFINED ""
\end{PipsProp}
) or non feasible
systems
\begin{PipsProp}{SYSTEM_NOT_FEASIBLE}
SYSTEM_NOT_FEASIBLE "{0==-1}"
\end{PipsProp}
are prettyprinted by {\tt PIPS}.
\subsection{PipsMake Library}
\index{Pipsmake}
\index{checkpoint}
With
\begin{PipsProp}{CHECK_RESOURCE_USAGE}
CHECK_RESOURCE_USAGE FALSE
\end{PipsProp}
it is possible to log and report differences between the set of resources
actually read and written by the procedures called by pipsmake and the set
of resources declared as read or written in pipsmake.rc file.
\begin{PipsProp}{ACTIVATE_DEL_DERIVED_RES}
ACTIVATE_DEL_DERIVED_RES TRUE
\end{PipsProp}
controls the rule activation process that may delete from the database all the
derived resources from the newly activated rule to make sure that
non-consistent resources cannot be used by accident.
\begin{PipsProp}{PIPSMAKE_CHECKPOINTS}
PIPSMAKE_CHECKPOINTS 0
\end{PipsProp}
controls how often resources should be saved and freed. $0$ means never, and
a positive value means every $n$ applications of a rule. This feature
was added to allow long big automatic tpips scripts that can coredump and
be restarted latter on close to the state before the core. As another side
effect, it allows to free the memory and to keep memory consumption as
moderate as possible, as opposed to usual tpips runs which keep all
memory allocated. Note that it should not be too often saved, because it
may last a long time, especially when entities are considered on big
workspaces. The frequency may be adapted in a script, rarely at the
beginning to more often latter.
\subsection{PipsDBM Library}
\index{Pipsdbm}
\index{PIPSDBM\_NO\_FREE\_ON\_QUIT}
Shell environment variables \verb+PIPSDBM_DEBUG_LEVEL+ can be set to ?
to check object consistency when they are stored in the database, and to
? to check object consistency when they are stored or retrieved (in case
an intermediate phase has corrupted some data structure unwillingly).
You can control what is done when a workspace is closed and resources are
saved. The
\begin{PipsProp}{PIPSDBM_RESOURCES_TO_DELETE}
PIPSDBM_RESOURCES_TO_DELETE "obsolete"
\end{PipsProp}
property can be set to to "obsolete" or to "all".
Note that it is not managed from {\tt pipsdbm} but from {\tt pipsmake},
which knows what is obsolete or not.
\subsection{Top Level Library}
\index{Top Level}
\index{Logging}
\index{Abort}
The \verb/top-level/ library is built on top of the \verb/pipsmake/
and \verb/pipsdbm/ libraries to factorize functions useful to build a
\Pips{} user interface or API.
Property
\begin{PipsProp}{USER_LOG_P}
USER_LOG_P TRUE
\end{PipsProp}
controls the logging of the session in the database of the current
workspace. This log can be processed by \Pips{} utility \verb/logfile2tpips/
to generate automatically a \Tpips{} script which can be used to
replay the current \Pips{} session, workspace by workspace, regardless
of the \Pips user interface used.
Property
\begin{PipsProp}{ABORT_ON_USER_ERROR}
ABORT_ON_USER_ERROR FALSE
\end{PipsProp}
specifies how user errors impact execution once the error message is
printed on \texttt{stderr}: return and go ahead, usually when \Pips{}
is used interactively (default behavior), or abort and core dump for
debugging purposes and for script executions, especially
non-regression tests.
Property
\begin{PipsProp}{CLOSE_WORKSPACE_AND_QUIT_ON_ERROR}
CLOSE_WORKSPACE_AND_QUIT_ON_ERROR FALSE
\end{PipsProp}
specifies that user and internal errors must preserve as much as
possible the workspace created by \Pips{}. This behavior stores on
disk, as much as possible, all information available on the process
that has just failed. This is useful when \Pips{} is called by another
tool. This is not compatible with \PipsPropRef{ABORT_ON_USER_ERROR},
which seeks an immediate termination of the \Pips{} process.
Property
\begin{PipsProp}{MAXIMUM_USER_ERROR}
MAXIMUM_USER_ERROR 2
\end{PipsProp}
specifies the number of user error allowed before the programs brutally aborts.
%% note: when doing a specialized version of tpips
%% this property should be updated...
Property
\begin{PipsProp}{ACTIVE_PHASES}
ACTIVE_PHASES "PRINT_SOURCE PRINT_CODE PRINT_PARALLELIZED77_CODE PRINT_CALL_GRAPH PRINT_ICFG TRANSFORMERS_INTER_FULL INTERPROCEDURAL_SUMMARY_PRECONDITION PRECONDITIONS_INTER_FULL ATOMIC_CHAINS RICE_SEMANTICS_DEPENDENCE_GRAPH MAY_REGIONS"
\end{PipsProp}
specifies which \Pipsmake{} phases should be used when several phases
can be used to produce the same resource. This property is used when a
workspace is created. A workspace is the database maintained by
\Pips{} to contain all resources defined for a whole application or
for the whole set of files used to create it.
Property
\begin{PipsProp}{PIPSMAKE_WARNINGS}
PIPSMAKE_WARNINGS TRUE
\end{PipsProp}
controls whether to show warning when reading and activating pipsmake rules.
Turning it off is useful when validating with a specialized version of \Pips{},
as some undesirable warnings can be shown then.
Resources that create ambiguities for \Pipsmake{} are at least:
\begin{itemize}
\item parsed\_printed\_file
\item printed\_file
\item callgraph\_file
\item icfg\_file
\item parsed\_code, because several parsers are available
\item transformers
\item summary\_precondition
\item preconditions
\item regions
\item chains
\item dg
\end{itemize}
This list must be updated according to new rules and new resources
declared in this file. Note that no default parser is usually
specified in this property, because it is selected automatically
according to the source file suffixes when possible.
Until October 2009, the active phases were:
\begin{verbatim}
ACTIVE_PHASES "PRINT_SOURCE PRINT_CODE PRINT_PARALLELIZED77_CODE
PRINT_CALL_GRAPH PRINT_ICFG TRANSFORMERS_INTRA_FAST
INTRAPROCEDURAL_SUMMARY_PRECONDITION
PRECONDITIONS_INTRA ATOMIC_CHAINS
RICE_FAST_DEPENDENCE_GRAPH MAY_REGIONS"
\end{verbatim}
They still are used for the old non-regression tests.
Property
\begin{PipsProp}{CONSISTENCY_ENFORCED_P}
CONSISTENCY_ENFORCED_P FALSE
\end{PipsProp}
specifies that properties cannot be set once a PIPS database has been
created. Pipsmake does not know the impacts of properties on the
resources. Setting a property can make a resource obsolete, but
pipsmake is going to use it as consistent. To avoid the issue, set
\PipsPropRef{CONSISTENCY_ENFORCED_P} to true and \TPIPS{} will detect
a user error if a property is possibly altered during a processing
phase.
\subsection{Warning Management}
\index{Warning}
\index{NO\_USER\_WARNING}
\index{WARNING\_ON\_STAT\_ERROR}
\index{WARN\_ABOUT\_EMPTY\_SEQUENCES}
User warnings may be turned off. Definitely, this is not the default
option! Most warnings {\em must} be read to understand surprising results.
This property is used by library \verb/misc/.
\begin{PipsProp}{NO_USER_WARNING}
NO_USER_WARNING FALSE
\end{PipsProp}
By default, {\tt PIPS} reports errors generated by system call \verb/stat/
which is used in library \verb/pipsdbm/ to check the time a resource has
been written and hence its temporal consistency.
\begin{PipsProp}{WARNING_ON_STAT_ERROR}
WARNING_ON_STAT_ERROR TRUE
\end{PipsProp}
Error messages are also copied in the Warnings file.
\subsection{Option for C Code Generation}
The syntactic constraints of C89 have been eased for declarations in
C99, where it is possible to intersperse statement declarations within
executable statements. This property is used to request C89 compatible
code generation.
\begin{PipsProp}{C89_CODE_GENERATION}
C89_CODE_GENERATION FALSE
\end{PipsProp}
So the default option is to generate C99 code, which may be changed
because it is likely to make the code generated by PIPS unparsable by PIPS.
There is no guarantee that each code generation phase is going to
comply with this property. It is up to each developper to decide if
this global property is to be used or not in his/her local phase.
\section{User and Programming Interfaces}
\subsection{Tpips Command Line Interface}
\index{Tpips}
\index{TPIPS\_IS\_A\_SHELL}
\Tpips{} is one of PIPS user interfaces.
% no longer used {
% \begin{PipsProp}{TPIPS_NO_EXECUTION_MODE}
% TPIPS_NO_EXECUTION_MODE FALSE
% \end{PipsProp}
% controls whether we shall execute the instructions of just check the syntax:
% }
\begin{PipsProp}{TPIPS_IS_A_SHELL}
TPIPS_IS_A_SHELL FALSE
\end{PipsProp}
controls whether \Tpips{} should behave as an extended shell and
consider any input command that is not a \Tpips{} command a Shell
command.
\subsection{Pyps API}
This property is automatically set to TRUE when pyps is running.
\begin{PipsProp}{PYPS}
PYPS FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% INPUT FILES
\chapter{Input Files}
\label{section-input-files}
\index{Input File}
\section{User File}
\label{subsection-user-file}
\index{User File}
An input program is a set of user Fortran~77, Fortran~90 or C source files and a name,
called a {\em workspace}. The files are looked for in the current
directory, then by using the colon-separated \verb|PIPS_SRCPATH| variable
for other directories where they might be found. The first occurrence of
the file name in the ordered directories is chosen, which is consistent
with \texttt{PATH} and \texttt{MANPATH} behaviour.
The source files are splitted by \Pips{} at the
program initialization phase to produce one \Pips{}-private source file
for each procedure, subroutine or function, and for each block data. A
function like \verb+fsplit+ is used and the new files are stored in the
workspace, which simply is a UNIX sub-directory of the current directory.
These new files have names suffixed by {\tt .f.orig}.
Since \Pips{} performs interprocedural analyses, it expects to find a
source code file for each procedure or function called. Missing modules
can be replaced by stubs, which can be made more or less precise with
respect to their effects on formal parameters and global variables. A
stub may be empty. Empty stubs can be automatically generated if the code
is properly typed (see Section~\ref{subsection-source-file}).
The {\em user} source files should not be edited by the user once \Pips{}
has been started because these editions are not going to be taken into
account unless a new workspace is created.
But their preprocessed copies, the
\Pips{} source files, safely can be edited while running \Pips{}. The
automatic consistency mechanism makes sure that any information
displayed to the user is consistent with the current state of the
sources files in the workspace. These source files have names terminated
by the standard suffix, {\tt .f}.
New user source files should be automatically and completely re-built when the program
is no longer under \Pips{} control, i.e. when the
workspace is closed. An executable application can easily be regenerated
after code transformations using the \TPIPS{} interface and requesting the
{\tt PRINTED\_FILE} resources for all modules, including compilation units in C:
\begin{quote}
{\tt display PRINTED\_FILE[\%ALL]}
\end{quote}
Note that compilation units can be left out with:
\begin{quote}
{\tt display PRINTED\_FILE[\%ALLFUNC]}
\end{quote}
In both cases with C source code, the order of modules may be unsuitable
for direct recompilation and compilation units should be included anyway,
but this is what is done by explicitly requesting the code regeneration as
described in \S~\ref{sec:regen-user-source}.
Note that \Pips{} expects proper ANSI Fortran 77 code. Its parser was not
designed to locate syntax errors. It is highly recommended to check source
files with a standard Fortran compiler (see
Section~\ref{subsection-preprocessing-and-splitting}) before submitting them to
\Pips{}.
\section{Preprocessing and Splitting}
\label{subsection-preprocessing-and-splitting}
\index{Preprocessing}
\index{Splitting}
\index{Include}
\index{Hollerith}
\index{Missing file}
\subsection{Fortran 77 Preprocessing and Splitting}
\label{sec:fortran-case}
The Fortran 77 files specified as input to \Pips{} by the user are
preprocessed in various ways.
\subsubsection{Fortran 77 Syntactic Verification}
\label{sec:fortr-synt-verif}
If the \verb|PIPS_CHECK_FORTRAN| shell environment variable is defined
to \verb|false| or \verb|no| or \verb|0|, the syntax of the source
files is not checked by compiling it with a C compiler.If the
\verb|PIPS_CHECK_FORTRAN| shell environment variable is defined to
\verb|true| or \verb|yes| or \verb|1|, the syntax of the file is
checked by compiling it with a Fortran 77 compiler. If the
\verb|PIPS_CHECK_FORTRAN| shell environment variable is not defined,
the check is performed according to
\PipsPropRef{CHECK_FORTRAN_SYNTAX_BEFORE_RUNNING_PIPS}.
The Fortran compiler is defined by the \verb|PIPS_FLINT| environment
variable. If it is undefined, the default compiler is
\verb|f77 -c -ansi|).
In case of failure, a warning is displayed. Note that if the program
cannot be compiled properly with a Fortran compiler, it is likely that
many problems will be encountered within \Pips{}.
The next property also triggers this preliminary syntactic verification.
\begin{PipsProp}{CHECK_FORTRAN_SYNTAX_BEFORE_RUNNING_PIPS}
CHECK_FORTRAN_SYNTAX_BEFORE_RUNNING_PIPS TRUE
\end{PipsProp}
\Pips{} requires source code for all leaves in its visible call graph. By
default, a user error is raised by Function \verb/initializer/ if a user
request cannot be satisfied because some source code is missing. It also
is possible to generate some synthetic code (also known as {\em stubs})
and to update the current module list but this is not a very satisfying
option because all interprocedural analysis results are going to be wrong.
The user should retrieve the generated \verb/.f/ files in the workspace,
under the \texttt{Tmp} directory, and add some assignments (\emph{def})
and \emph{use}s to mimic the action of the real code to have a sufficient
behavior from the point of view of the analysis or transformations you
want to apply on the whole program. The user modified synthetic files
should then be saved and used to generate a new workspace.
If \PipsPropRef{PREPROCESSOR_MISSING_FILE_HANDLING} is set to
\verb|"query"|, a script can optionally be set to handle the interactive
request using \PipsPropRef{PREPROCESSOR_MISSING_FILE_GENERATOR}. This
script is passed the function name and prints the filename on standard
output. When empty, it uses an internal one.
Valid settings: \verb|error| or \verb|generate| or \verb|query|.
\begin{PipsProp}{PREPROCESSOR_MISSING_FILE_HANDLING}
PREPROCESSOR_MISSING_FILE_HANDLING "error"
\end{PipsProp}
\begin{PipsProp}{PREPROCESSOR_MISSING_FILE_GENERATOR}
PREPROCESSOR_MISSING_FILE_GENERATOR ""
\end{PipsProp}
The generated stub can have various default effect, say to prevent
over-optimistic parallelization.
\begin{PipsProp}{STUB_MEMORY_BARRIER}
STUB_MEMORY_BARRIER FALSE
\end{PipsProp}
\begin{PipsProp}{STUB_IO_BARRIER}
STUB_IO_BARRIER FALSE
\end{PipsProp}
\subsubsection{Fortran 77 File Preprocessing}
\label{sec:fortr-file-prepr}
If the file suffix is \verb|.F| then the file is preprocessed. By default
PIPS uses \verb|gfortran -E| for Fortran files. This preprocessor can be
changed by setting the \verb|PIPS_FPP| environment variable.
Moreover the default preprocessing options are %
\verb|-P -D__PIPS__ -D__HPFC__| and they can be extended (not replaced...)
with the \verb|PIPS_FPP_FLAGS| environment variable.
\subsubsection{Fortran 77 Split}
\label{sec:fortran-split}
The file is then split into one file per module using a PIPS specialized
version of \texttt{fsplit}\footnote{The PIPS version of \texttt{fsplit} is
derived from the BSD \texttt{fsplit} and several improvements have been
performed.}. This preprocessing also handles
\begin{enumerate}
\item Hollerith constants by converting them to the quoted
syntax\footnote{Hollerith constants are considered obsolete by the new
Fortran standards and date back to 1889...};
\item unnamed modules by adding \texttt{MAIN000} or \texttt{PROGRAM
MAIN000} or or \texttt{DATA000} or \texttt{BLOCK DATA DATA000}
according to needs.
\end{enumerate}
The output of this phase is a set of \verb|.f_initial| files in per-module
subdirectories. They constitute the resource \verb|INITIAL_FILE|.
\subsubsection{Fortran Syntactic Preprocessing}
\label{subsection-syntactic-preprocessing}
\index{Preprocessing}
\index{Include}
\index{Complex Constant}
\index{Implicit None}
A second step of preprocessing is performed to produce \verb/SOURCE_FILE/
files with standard Fortran suffix \texttt{.f} from the \verb|.f_initial|
files. The two preprocessing steps are shown in
Figure~\ref{figure-user-and-source-files}.
\begin{figure}
\begin{center}
\mbox{\includegraphics[width=\hsize]{user-and-source-files}}
\end{center}
\caption{Preprocessing phases: from a user file to a source file}
\label{figure-user-and-source-files}
\end{figure}
Each module source file is then processed by \texttt{top-level} to handle
Fortran \verb|include| and to comment out \texttt{IMPLICIT NONE} which are
not managed by \Pips{}. Also this phase performs some transformations of
complex constants to help the \Pips{} parser. Files referenced in Fortran
\texttt{include} statements are looked for from the directory where the
Fortran file is. The Shell variable \verb|PIPS_CPP_FLAGS| is {\em not}
used to locate these include files.
\subsection{C Preprocessing and Splitting}
\label{sec:c-case-preprocessing}
The C preprocessor is applied before the splitting. By default PIPS uses
\verb|cpp -C| for C files. This preprocessor can be changed by setting
the \verb|PIPS_CPP| environment variable.
Moreover the \verb|-D__PIPS__ -D__HPFC__ -U__GNUC__| preprocessing options
are used and can be extended (not replaced) with the \verb|PIPS_CPP_FLAGS|
environment variable.
This \verb|PIPS_CPP_FLAGS| variable can also be used to locate the include
files. Directories to search are specified with the \texttt{-I\emph{file}}
option, as usual for the C preprocessor.
\subsubsection{C Syntactic Verification}
\label{sec:c-synt-verif}
If the \verb|PIPS_CHECK_C| shell environment variable is defined to
\verb|false| or \verb|no| or \verb|0|, the syntax of the source files
is not checked by compiling it with a C compiler. If the
\verb|PIPS_CHECK_C| shell environment variable is defined to
\verb|true| or \verb|yes| or \verb|1|, the syntax of the file is
checked by compiling it with a C compiler. If the
\verb|PIPS_CHECK_C| shell environment variable is not defined, the
check is performed according to \PipsPropRef{CHECK_C_SYNTAX_BEFORE_RUNNING_PIPS}.
The environment variable
\verb|PIPS_CC| is used to define the C compiler available. If it is undefined, the
compiler chosen is \verb|gcc -c |).
In case of failure, a warning is displayed.
If the environement variable \verb|PIPS_CPP_FLAGS| is defined, it
should contain the options \verb|-Wall| and \verb|-Werror| for the
check to be effective.
The next property also triggers this preliminary syntactic verification.
\begin{PipsProp}{CHECK_C_SYNTAX_BEFORE_RUNNING_PIPS}
CHECK_C_SYNTAX_BEFORE_RUNNING_PIPS TRUE
\end{PipsProp}
Although its default value is \verb|FALSE|, it is much safer to set it
to true when dealing with new sources files. \Pips{} is not designed to
process non-standard source code. Bugs in source files are not well
explained or localized. They can result in weird behaviors and
inexpected core dumps. Before complaining about \Pips{}, it is higly
recommended to set this property to \verb|TRUE|.
Note: the C and Fortran syntactic verifications could be controlled by
a unique property.
\subsection{Fortran 90 Preprocessing and Splitting}
\label{sec:fortran-90-preprocessing-and-splitting}
The Fortran 90 parser is a separate program, derived from gcc Fortran
parser. It is activated directly when the workspace is created, and
not by pipsmake.
\subsection{Source File Hierarchy}
\label{sec:source-file-hierarchy}
The source files may be placed in different directories and have the
same name, which makes resource management more difficult. The default
option is to assume that no file name conflicts occur. This is the
historical option and it leads to much simpler module names.
\begin{PipsProp}{PREPROCESSOR_FILE_NAME_CONFLICT_HANDLING}
PREPROCESSOR_FILE_NAME_CONFLICT_HANDLING FALSE
\end{PipsProp}
\section{Source Files}
\label{subsection-source-file}
\index{Source File}
\index{Missing Code}
\index{Type Checking}
A \verb/source_file/ contains the code of exactly one module. Source files
are created from user source files at program initialization by
\texttt{fsplit} or a similar function if \texttt{fsplit} is not available (see
Section~\ref{subsection-preprocessing-and-splitting}). A
source file may be updated by the user\footnote{The
X-window interface, \texttt{wpips} has an \texttt{edit} entry in the
transformation menu.}, but not by \Pips{}. Program
transformations are performed on the internal representation
(see~\ref{section-abstract-syntax-tree}) and visible in the prettyprinted
output (see~\ref{section-output-files}).
Source code splitting and preprocessing, e.g. \texttt{cpp}, are performed
by the function \verb/create_workspace()/ from the \texttt{top-level} library,
in collaboration with \verb/db_create_workspace()/ from library
\texttt{pipsdbm} which creates the workspace directory. The user source
files have names suffixed by \texttt{.f} or \texttt{.F} if \texttt{cpp}
must be applied. They are split into {\em original} \verb/user_files/ with
suffix \texttt{.f.orig}. These so-called original user files are in fact
copies stored in the workspace. The syntactic PIPS preprocessor is
applied to generate what is known as a \verb/source_file/ by PIPS. This
process is fully automatized and not visible from PIPS user interfaces.
However, the cpp preprocessor actions can be controlled using the Shell
environment variable \verb/PIPS_CPP_FLAGS/.
Function \verb/initializer/ is only called when the source code is not
found. If the user code is properly typed, it is possible to force
\verb/initializer/ to generate empty stubs by setting properties
\PipsPropRef{PREPROCESSOR_MISSING_FILE_HANDLING} and, to avoid inconsistency,
\PipsPropRef{PARSER_TYPE_CHECK_CALL_SITES}. But remember that many Fortran codes
use subroutines with variable numbers of arguments and with polymorphic
types. Fortran varargs mechanism can be achieved by using or not the
second argument according to the first one. Polymorphism can be useful to
design an IO package or generic array subroutine, e.g. a subroutine
setting an array to zero or a subroutine to copy an array into another
one.
The current default option is to generate a user error if some source code
is missing. This decision was made for two reasons:
\begin{enumerate}
\item too many warnings about typing are generated as soon as polymorphism
is used;
\item analysis results and code transformations are potentially wrong
because no memory effects are synthesized; see Properties
\PipsPropRef{MAXIMAL_PARAMETER_EFFECTS_FOR_UNKNOWN_FUNCTIONS} and
\PipsPropRef{MAXIMAL_EFFECTS_FOR_UNKNOWN_FUNCTIONS}.
\end{enumerate}
Sometimes, a function happen to be defined (and not only declared) inside a header file with
the inline keyword. In that case PIPS can consider it as a regular module
or just ignore it, as its presence may be system-dependant. Property
\PipsPropRef{IGNORE_FUNCTION_IN_HEADER} control this behavior and must be
set \emph{before} workspace creation.
\begin{PipsProp}{IGNORE_FUNCTION_IN_HEADER}
IGNORE_FUNCTION_IN_HEADER TRUE
\end{PipsProp}
\begin{PipsPass}{flag_as_stub}
Modules can be flagged as ``stubs'', aka functions provided to PIPS but which
shouldn't be inlined or modified. Property
\PipsPropRef{PREPROCESSOR_INITIALIZER_FLAG_AS_STUB} controls if the initializer
should declare new files as stubs.
\end{PipsPass}
\begin{PipsMake}
bootstrap_stubs > PROGRAM.stubs
\end{PipsMake}
\begin{PipsMake}
flag_as_stub > PROGRAM.stubs
< PROGRAM.stubs
\end{PipsMake}
\begin{PipsProp}{PREPROCESSOR_INITIALIZER_FLAG_AS_STUB}
PREPROCESSOR_INITIALIZER_FLAG_AS_STUB TRUE
\end{PipsProp}
\begin{PipsMake}
initializer > MODULE.user_file
> MODULE.initial_file
\end{PipsMake}
Note: the generation of the resource \verb|user_file| here above is mainly
directed in having the resource concept here. More thought is needed to
have the concept of user files managed by \Pipsmake{}.
MUST appear after initializer:
\begin{PipsMake}
filter_file > MODULE.source_file
< MODULE.initial_file
< MODULE.user_file
\end{PipsMake}
In C, the initializer can generate directly a \verb|c_source_file| and
its compilation unit.
\begin{PipsMake}
c_initializer > MODULE.c_source_file
> COMPILATION_UNIT.c_source_file
> MODULE.input_file_name
\end{PipsMake}
\section{Regeneration of User Source Files}
\label{sec:regen-user-source}
The \PipsPassRef{unsplit} phase regenerates user files from available
\verb|printed_file|. The various modules that where initially stored in
single file are appended together in a file with the same name. Not that
just \texttt{fsplit} is reversed, not a preprocessing through \texttt{cpp}.
Also the \texttt{include} file preprocessing is not reversed.
\begin{PipsPass}{unsplit}
Regeneration of user files. The various modules that where initially stored in
single file are appended together in a file with the same name.
\end{PipsPass}
\begin{PipsMake}
alias unsplit 'User files Regeneration'
unsplit > PROGRAM.user_file
< ALL.user_file
< ALL.printed_file
unsplit_parsed > PROGRAM.user_file
< ALL.user_file
< ALL.parsed_printed_file
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \chapter{Abstract Syntax Tree}
\chapter{Building the Internal Representation}
\label{section-abstract-syntax-tree}
\index{AST}
\index{IR}
\index{RI}
\index{Abstract Syntax Tree}
The abstract syntax tree, a.k.a intermediate representation,
a.k.a. internal representation, is presented in~\cite{IJT92} and in \Pri{}.
\section{Entities}
\label{subsubsection-entities}
\index{Entity}
\index{Variable}
\index{Module}
Program entities are stored in \Pips{} unique symbol table\footnote{FI:
retrospectively, having a {\em unique} symbol table for all modules was
a design mistake. The decision was made to have homogeneous accesses to
local and global entities. It was also made to match NewGen {\em
tabulated} type declaration.}, called \verb+entities+. Fortran entities,
like intrinsics and operators, are created by \verb+bootstrap+ at
program initialization. The symbol table is updated with user local and
global variables when modules are parsed or linked together. This side
effect is not disclosed to \Pipsmake{}.
\begin{PipsMake}
bootstrap > PROGRAM.entities
\end{PipsMake}
The entity data structure is described in \Pri{}.
The declaration of new intrinsics is not easy because it was assumed that
there number was fixed and limited by the Fortran standard. In fact,
Fortran extensions define new ones. To add a new intrinsic, C code in
\texttt{bootstrap/bootstrap.c} and in \texttt{effects-generic/intrinsics.c}
must be added to declare its name, type and Read/Write memory effects.
Information about entities generated by the parsers is printed out
conditionally to property: \PipsPropRef{PARSER_DUMP_SYMBOL_TABLE}.
which is set to false by default. Unless you are debugging the parser,
do not set this property to TRUE but display the symbol table file. See Section~\ref{subsubsection:declaration-of-the-standard-parser}
for Fortran and Section~\ref{subsection:declaration-of-the-C-parsers}
for C.
\section{Parsed Code and Callees}
\label{subsection-parsed-code-and-callees}
\index{Parsed Code}
\index{Callees}
Each module source code is parsed to produce an internal representation
called \verb+parsed_code+ and a list of called module names,
\verb+callees+.
\subsection{Fortran 77}
\label{sec:fortran}
Source code is assumed to be fully Fortran-77 compliant. The syntax
should be checked by a standard Fortran compiler, e.g. \verb/fort77/
or at least \verb/gfortran/, before the PIPS Fortran 77 parser is
activated. On the first encountered error, the parser may be able to
emit a useful message or the non-analyzed part of the source code is
printed out.
\Pips{} input language is standard Fortran~77 with few extensions and some
restrictions. The input character set includes underscore, \verb/_/, and
varying length variable names, i.e. they are not restricted to 6
characters are supported as well as dependent types for arrays.
\subsubsection{Fortran 77 Restrictions}
\begin{enumerate}
\item \texttt{ENTRY} statements are not recognized and a user error is
generated. Very few cases of this obsolete feature were
encountered in the codes initially used to benchmark \Pips{}. ENTRY statements have to be replaced manually by \texttt{SUBROUTINE} or
\texttt{FUNCTION} and appropriate commons. If the parser bumps into a
call to an ENTRY point, it may wrongly diagnose a missing source code
for this entry, or even generate a useless but \Pipsmake{} satisfying stub if the corresponding
property has been set (see Section~\ref{subsection-source-file}).
\item Multiple returns are not in \Pips{} Fortran.
\item \texttt{ASSIGN} and assigned \texttt{GOTO} are not in \Pips{} Fortran.
\item Computed \texttt{GOTO}s are not in \Pips{} Fortran.
They are automatically
replaced by a \texttt{IF...ELSEIF...ENDIF} construct in the parser.
\item Functional formal parameters are not accepted. This is deeply
exploited in \Pipsmake{}.
\item Integer PARAMETERs must be initialized with integer constant
expressions because conversion functions are not implemented.
\item DO loop headers should have no label. Add a \texttt{CONTINUE} just
before the loop when it happens. This can be performed automatically if
the property
\PipsPropRef{PARSER_SIMPLIFY_LABELLED_LOOPS}
is set to \texttt{TRUE}. This
restriction is imposed by the parallelization phases, not by the parser.
\item Complex constants, e.g. \texttt{(0.,1.)}, are not directly
recognized by the
parser. They must be replaced by a call to intrinsic \texttt{CMPLX}. The
\Pips{} preprocessing replaces them by a call to \texttt{COMPLX\_}.
\item Function formulae are not recognized by the parser. An undeclared
array and/or an
unsupported macro is diagnosed. They may be substituted in an unsafe way
by the preprocessor if the property
\begin{quote}
\PipsPropRef{PARSER_EXPAND_STATEMENT_FUNCTIONS}
\end{quote}
is set. If the substitution is considered possibly unsafe, a warning is
displayed.
\end{enumerate}
These parser restrictions were based on funding constraints. They are
mostly alleviated by the preprocessing phase. PerfectClub and SPEC-CFP95
benchmarks are handled without manual editing, but for ENTRY statements
which are obsoleted by the current Fortran standard.
\subsubsection{Some Additional Remarks}
\begin{itemize}
\item The PIPS preprocessing stage included in \texttt{fsplit()} is going
to name unnamed modules \texttt{MAIN000} and unnamed blockdata
\texttt{DATA000} to be consistent with the generated file name.
\item Hollerith constants are converted to a more readable quoted form,
and then output as such by the prettyprinter.
\end{itemize}
\subsubsection{Some Unfriendly Features}
\begin{enumerate}
\item Source code is read in columns 1-72 only. Lines ending in columns
73 and beyond usually generate incomprehensible errors. A warning is
generated for lines ending after column 72.
\item Comments are carried by the {\em following} statement. Comments
carried by \texttt{RETURN}, \texttt{ENDDO}, \texttt{GOTO} or
\texttt{CONTINUE} statements are not always preserved because the
internal representation transforms these statements or because the
parallelization phase regenerates some of them. However, they are
more likely to be hidden by the prettyprinter. There is a large
range of prettyprinter \PROPERTIES{} to obtain less filtered view of
the code.
\item Formats and character constants are not properly handled. Multi-line
formats and constants are not always reprinted in a Fortran correct
form.
\item Declarations are exploited on-the-fly. Thus type and dimension
information must be available {\em before} common declaration. If not,
wrong common offsets are computed at first and fixed
later in Function \texttt{EndOfProcedure}). Also, formal arguments
implicitly are declared using the default implicit rule. If it is
necessary to declare them, this new declarations should occur {\em
before} an \texttt{IMPLICIT} declaration. Users are surprised by the
{\em type redefinition} errors displayed.
% \item Double quote is not accepted as substitute for simple quote in
% character string constants.
\end{enumerate}
\subsubsection{Declaration of the Standard Fortran 77 Parser}
\label{subsubsection:declaration-of-the-standard-parser}
\index{PARSER\_WARN\_FOR\_COLUMNS\_73\_80}
\index{Symbol table}
\begin{PipsMake}
parser > MODULE.parsed_code
> MODULE.callees
< PROGRAM.entities
< MODULE.source_file
\end{PipsMake}
For parser debugging purposes, it is possible to print a summary of the symbol
table, when enabling this property:
\begin{PipsProp}{PARSER_DUMP_SYMBOL_TABLE}
PARSER_DUMP_SYMBOL_TABLE FALSE
\end{PipsProp}
This should be avoided and the resource \verb/symbol_table_file/ be
displayed instead.
The prettyprint of the symbol table for a Fortran or C module is generated with:
\begin{PipsMake}
parsed_symbol_table > MODULE.parsed_symbol_table_file
< PROGRAM.entities
< MODULE.parsed_code
\end{PipsMake}
\subsubsection*{Input Format}
Some subtle errors occur because the PIPS parser uses a fixed
format. Columns 73 to 80 are ignored, but the parser may emit a warning
if some characters are encountered in this comment field.
\begin{PipsProp}{PARSER_WARN_FOR_COLUMNS_73_80}
PARSER_WARN_FOR_COLUMNS_73_80 TRUE
\end{PipsProp}
\subsubsection*{ANSI extension}
\index{PARSER\_ACCEPT\_ANSI\_EXTENSIONS}
\index{correctness}
PIPS has been initially developed to parse correct Fortran compliant
programs only. Real applications use lots of ANSI extensions\dots{} and they
are not always correct! To make sure that PIPS output is correct, the
input code should be checked against ANSI extensions using property
\begin{quote}
CHECK\_FORTRAN\_SYNTAX\_BEFORE\_PIPS
\end{quote}
(see Section~\ref{subsection-preprocessing-and-splitting}) and the property below should
be set to false.
\begin{PipsProp}{PARSER_ACCEPT_ANSI_EXTENSIONS}
PARSER_ACCEPT_ANSI_EXTENSIONS TRUE
\end{PipsProp}
Currently, this property is not used often enough in PIPS parser which let
go many mistakes... as expected by real users!
\subsubsection*{Array Range Extension}
\index{PARSER\_ACCEPT\_ARRAY\_RANGE\_EXTENSION}
\index{Fortran 90}
PIPS has been developed to parse correct Fortran-77 compliant programs
only. Array ranges are used to improve readability. They can be generated
by PIPS prettyprinter. They are not parsed as correct input by default.
\begin{PipsProp}{PARSER_ACCEPT_ARRAY_RANGE_EXTENSION}
PARSER_ACCEPT_ARRAY_RANGE_EXTENSION FALSE
\end{PipsProp}
\subsubsection*{Type Checking}
\index{Type Checking}
\index{PARSER\_TYPE\_CHECK\_CALL\_SITES}
Each argument list at calls to a function or a subroutine is compared to
the functional type of the callee. Turn this off if you need to support
variable numbers of arguments or if you use overloading and do not want to
hear about it. For instance, an IO routine can be used to write an array
of integers or an array of reals or an array of complex if the length
parameter is appropriate.
Since the functional typing is shaky, let's turn it off by default!
\begin{PipsProp}{PARSER_TYPE_CHECK_CALL_SITES}
PARSER_TYPE_CHECK_CALL_SITES FALSE
\end{PipsProp}
\subsubsection*{Loop Header with Label}
\index{PARSER\_SIMPLIFY\_LABELLED\_LOOPS}
\index{PARSER\_LINEARIZE\_LOOP\_BOUNDS}
The PIPS implementation of Allen\&Kennedy algorithm cannot cope with
labeled DO loops because the loop, and hence its label, may be
replicated if the loop is distributed. The parser can generate an extra
\verb/CONTINUE/ statement to carry the label and produce a label-free
loop. This is not the standard option because \Pips{} is designed to
output code as close as possible to the user source code.
\begin{PipsProp}{PARSER_SIMPLIFY_LABELLED_LOOPS}
PARSER_SIMPLIFY_LABELLED_LOOPS FALSE
\end{PipsProp}
Most PIPS analyses work better if do loop bounds are affine. It is sometimes
possible to improve results for non-affine bounds by assigning the bound
to an integer variables and by using this variable as bound. But this
is implemented for Fortran, but not for C.
\begin{PipsProp}{PARSER_LINEARIZE_LOOP_BOUNDS}
PARSER_LINEARIZE_LOOP_BOUNDS FALSE
\end{PipsProp}
\subsubsection*{Entry}
\index{ENTRY}
\index{PARSER\_SUBSTITUTE\_ENTRIES}
The entry construct can be seen as an early attempt at object-oriented
programming. The same object can be processed by several function. The
object is declared as a standard subroutine or function and entry points
are placed in the executable code. The entry points have different sets of
formal parameters, they may share some common pieces of code, they share
the declared variables, especially the static ones.
The entry mechanism is dangerous because of the flow of control between
entries. It is now obsolete and is not analyzed directly by PIPS. Instead
each entry may be converted into a first class function or subroutine and
static variables are gathered in a specific common. This is the default
option. If the substitution is not acceptable, the property may be turned
off and entries results in a parser error.
\begin{PipsProp}{PARSER_SUBSTITUTE_ENTRIES}
PARSER_SUBSTITUTE_ENTRIES TRUE
\end{PipsProp}
\subsubsection*{Alternate Return}
\index{Alternate Return}
\index{Return (Alternate)}
\index{PARSER\_SUBSTITUTE\_ALTERNATE\_RETURNS}
\index{PARSER\_RETURN\_CODE\_VARIABLE}
\index{PARSER\_FORMAL\_LABEL\_SUBSTITUTE\_PREFIX}
\index{PRETTYPRINT\_REGENERATE\_ALTERNATE\_RETURNS}
Alternate returns are put among the obsolete Fortran features by the
Fortran~90 standard. It is possible (1) to refuse them (option "NO"), or
(2) to ignore them and to replace alternate returns by {\tt STOP} (option
"STOP"), or (3) to substitute them by a semantically equivalent code based
on return code values (option "RC" or option "HRC"). Option (2) is useful
if the alternate returns are used to propagate error conditions. Option
(3) is useful to understand the impact of the alternate returns on the
control flow graph and to maintain the code semantics. Option "RC" uses
an additional parameter while option "HRC" uses a set of PIPS run-time
functions to hide the set and get of the return code which make
declaration regeneration less useful. By default, the
first option is selected and alternate returns are refused.
To produce an executable code, the declarations must be
regenerated: see property \PipsPropRef{PRETTYPRINT_ALL_DECLARATIONS} in
Section~\ref{subsubsection-declarations}. This is not necessary with
option "HRC". Fewer new declarations are needed if variable
\PipsPropRef{PARSER_RETURN_CODE_VARIABLE} is implicitly integer
because its first letter is in the I-N range.
With option (2), the code can still be executed if alternate returns are
used only for errors and if no errors occur. It can also be analyzed to
understand what the {\em normal} behavior is. For instance, OUT regions
are more likely to be exact when exceptions and errors are ignored.
Formal and actual label variables are replaced by string variables to
preserve the parameter ordre and as much source information as possible.
See \PipsPropRef{PARSER_FORMAL_LABEL_SUBSTITUTE_PREFIX} which is used
to generate new variable names.
\begin{PipsProp}{PARSER_SUBSTITUTE_ALTERNATE_RETURNS}
PARSER_SUBSTITUTE_ALTERNATE_RETURNS "NO"
\end{PipsProp}
\begin{PipsProp}{PARSER_RETURN_CODE_VARIABLE}
PARSER_RETURN_CODE_VARIABLE "I_PIPS_RETURN_CODE_"
\end{PipsProp}
\begin{PipsProp}{PARSER_FORMAL_LABEL_SUBSTITUTE_PREFIX}
PARSER_FORMAL_LABEL_SUBSTITUTE_PREFIX "FORMAL_RETURN_LABEL_"
\end{PipsProp}
The internal representation can be hidden and the alternate returns can be
prettyprinted at the call sites and modules declaration by turning on the
following property:
\begin{PipsProp}{PRETTYPRINT_REGENERATE_ALTERNATE_RETURNS}
PRETTYPRINT_REGENERATE_ALTERNATE_RETURNS FALSE
\end{PipsProp}
Using a mixed C / Fortran RI is troublesome for comments handling:
sometimes the comment guard is stored in the comment, sometime not.
Sometimes it is on purpose, sometimes it is not.
When following property is set to true, \PIPS does its best to prettyprint comments correctly.
\begin{PipsProp}{PRETTYPRINT_CHECK_COMMENTS}
PRETTYPRINT_CHECK_COMMENTS TRUE
\end{PipsProp}
% no longer used {
% \begin{PipsProp}{PRETTYPRINT_REGENERATED_LABEL}
% PRETTYPRINT_REGENERATED_LABEL "12345"
% \end{PipsProp}
%
% This is useful to link modules processed by PIPS with user modules using
% the alternate return constructs if alternate returns are replaced by STOP
% statement in the code processed by PIPS. The actual labels present in call
% sites may be dead code eliminated and a fake non-conflicting label must be
% used. It is defined by property \PipsPropRef{PRETTYPRINT_REGENERATED_LABEL}.
% }
If all modules have been processed by PIPS, it is possible not to
regenerate alternate returns and to use a code close to the internal
representation. If they are regenerated in the call sites and module
declaration, they are nevertheless not used by the code generated by PIPS
which is consistent with the internal representation.
Here is a possible implementation of the two PIPS run-time subroutines
required by the hidden return code ("HRC") option:
\begin{quote}
subroutine SET\_I\_PIPS\_RETURN\_CODE\_(irc)\\
common /PIPS\_RETURN\_CODE\_COMMON/irc\_shared\\
irc\_shared = irc\\
end\\
subroutine GET\_I\_PIPS\_RETURN\_CODE\_(irc)\\
common /PIPS\_RETURN\_CODE\_COMMON/irc\_shared\\
irc = irc\_shared\\
end
\end{quote}
Note that the subroutine names depend on the
\PipsPropRef{PARSER_RETURN_CODE_VARIABLE} property. They are generated by
prefixing it with \verb/SET_/ and \verb/GET_/. There implementation is
free. The common name used should not conflict with application common
names. The ENTRY mechanism is not used because it would be desugared by
PIPS anyway.
\subsubsection*{Assigned GO TO}
\index{Assigned GO TO}
\index{GO TO (Assigned)}
\index{Computed GO TO}
\index{GO TO (Computed)}
\index{PARSER\_SUBSTITUTE\_ASSIGNED\_GOTO}
By default, assigned GO TO and ASSIGN statements are not accepted.
These constructs are obsolete and will not be part of future Fortran
standards.
However, it is possible to replace them automatically in a way similar to
computed GO TO. Each ASSIGN statement is replaced by a standard integer
assignment. The label is converted to its numerical value. When an
assigned GO TO with its optional list of labels is encountered, it is
transformed into a sequence of logical IF statement with appropriate tests
and GO TO's. According to Fortran 77 Standard, Section 11.3, Page 11-2,
the control variable must be set to one of the labels in the optional
list. Hence a STOP statement is generated to interrupt the execution in case
this happens, but note that compilers such as SUN f77 and g77 do not check
this condition at run-time (it is undecidable statically).
\begin{PipsProp}{PARSER_SUBSTITUTE_ASSIGNED_GOTO}
PARSER_SUBSTITUTE_ASSIGNED_GOTO FALSE
\end{PipsProp}
Assigned GO TO without the optional list of labels are not processed. In
other words, PIPS make the optional list mandatory for substitution. It
usually is quite easy to add manually the list of potential targets.
Also, ASSIGN statements cannot be used to define a FORMAT label. If the
desugaring option is selected, an illegal program is produced by PIPS
parser.
\subsubsection*{Statement Function}
\index{Statement Function}
\index{PARSER\_EXPAND\_STATEMENT\_FUNCTIONS}
This property controls the processing of Fortran statement functions by text
substitution in the parser. No other processing is available and the
parser stops with an error message when a statement function declaration
is encountered.
The default used to be not to perform this unchecked replacement, which might
change the semantics of the program because type coercion is not enforced
and actual parameters are not assigned to intermediate variables.
However most statement functions do not require these extra-steps and it
is legal to perform the textual substitution. For user convenience, the
default option is textual substitution.
Note that the parser does not have enough information to check the validity
of the transformation, but a warning is issued if legality is doubtful. If
strange results are obtained when executing codes transformed with PIPS,
his property should be set to false.
A better method would be to represent them somehow a local functions in
the internal representation, but the implications for \Pipsmake{}
and other issues are clearly not all foreseen\ldots (Fabien Coelho).
\begin{PipsProp}{PARSER_EXPAND_STATEMENT_FUNCTIONS}
PARSER_EXPAND_STATEMENT_FUNCTIONS TRUE
\end{PipsProp}
\subsection{Declaration of HPFC Parser}
\begin{PipsPass}{hpfc_parser}
This parser takes a different Fortran file but applies the same
processing as the previous parser. The Fortran file is the result of the
preprocessing by the \PipsPassRef{hpfc_filter} phase of the original file in
order to extract the directives and switch them to a Fortran~77 parsable
form. As another side-effect, this parser hides some callees from
\Pipsmake{}. This callees are temporary functions used to encode HPF
directives. Their call sites are removed from the code before requesting full analyses
to PIPS. This parser is triggered automatically by the \PipsPassRef{hpfc_close}
phase when requested. It should never be selected or activated by hand.
\end{PipsPass}
\begin{PipsMake}
hpfc_parser > MODULE.parsed_code
> MODULE.callees
< PROGRAM.entities
< MODULE.hpfc_filtered_file
\end{PipsMake}
\subsection{Declaration of the C Parsers}
\label{subsection:declaration-of-the-C-parsers}
Three C parsers are used by \PIPS{}. The first one, called the
C preprocessor parser, is used to break down a C file or a set of C
files into multiple files, with one function per file and a global
file with all external declarations, the compilation unit. This is
performed when \PIPS{} is launched and its {\em workspace} is created.
The second one is called the C parser. It is designed to parse the
function files. The last one is called the compilation unit parser and
it deals with the compilation unit file.
\subsubsection{Language parsed by the C Parsers}
The C parsers are all based on the same initial set of lexical and
syntactic rules designed for C77. They support some C99 extensions
such as VLA, declarations in for loops...
The language parsed is larger than the language handled
interprocedurally by PIPS:
\begin{enumerate}
\item recursion is not supported;
\item pointers to function are not supported;
\item internal functions, a gcc extension, are not supported.
\end{enumerate}
\subsubsection{Handling of C Code}
A C file is seen in PIPS as a compilation unit, that contains all the
objects declarations that are global to this file, and as many as module
(function or procedure) definitions defined in this file.
Thus the compilation unit contains the file-global macros, the include
statements, the local and global variable definitions, the type
definitions, and the function declarations if any found in the C file.
When the PIPS workspace is created by PIPS preprocessor, each C file is
preprocessed\footnote{Macros are interpreted and include files are
expanded. The result depends on the C preprocessor used,on its option
and on the system environment (\texttt{/usr/include},...).} using for
instance \texttt{gcc -E}\footnote{It can be redefined using
\texttt{CPP\_PIPS} and \texttt{PIPS\_CPP\_FLAGS} environment variables
as explained in \S~\ref{sec:c-case-preprocessing}.} and broken into a
new \index{compilation unit} which contains only the file-global variable
declarations, the function declarations and the type definitions, and one
C file for each C function defined in the initial C file.
The new compilation units must be parsed before the new files, containing
each one exactly one function definition, can be parsed. The new
compilation units are named like the initial file names but with a bang
extension.
For example, considering a C file \verb|foo.c| with 2 function
definitions:
\begin{lstlisting}
enum { N = 2008 };
typedef float data_t;
data_t matrix[N][N];
extern int errno;
int calc(data_t a[N][N]) {
[...]
}
int main(int argc, char *argv[]) {
[..]
}
\end{lstlisting}
After preprocessing, it leads to a file \verb|foo.cpp_processed.c| that is
then split into a new \verb|foo!.cpp_processed.c| compilation unit
containing
\begin{lstlisting}
enum { N = 2008 };
typedef float data_t;
data_t matrix[N][N];
extern int errno;
int calc(data_t a[N][N]);}
int main(int argc, char *argv[]);
\end{lstlisting}
and 2 module files containing the definitions of the 2 functions, a
\verb|calc.c|
\begin{lstlisting}
int calc(data_t a[N][N]) {
[...]
}
\end{lstlisting}
and a \verb|main.c|
\begin{lstlisting}
int main(int argc, char *argv[]) {
[..]
}
\end{lstlisting}
Note that it is possible to have an empty compilation unit and no module
file if the original file does not contain sensible C informations (such
as an empty file containing only blank characters and so on).
\subsubsection{Compilation Unit Parser}
\begin{PipsMake}
compilation_unit_parser > COMPILATION_UNIT.declarations
< COMPILATION_UNIT.c_source_file
< PROGRAM.entities
\end{PipsMake}
The resource \verb/COMPILATION_UNIT.declarations/ produced by
\texttt{compilation\_unit\_parser} is a special resource used to force the
parsing of the new compilation unit before the parsing of its associated
functions. It is in fact a hash table containing the file-global C
keywords and typedef names defined in each compilation unit.
In fact phase compilation\_unit\_parser also produces parsed\_code and
callees resources for the compilation unit. This is done to work
around the fact that rule c\_parser was invoked on compilation units
by later phases, in particular for the computation of initial
preconditions, breaking the declarations of function
prototypes. These two resources are not declared here because pipsmake
gets confused between the different rules to compute parsed code :
there is no simple way to distinguish between compilation units and
modules at some times and handling them similarly at other times.
% The parsed code of the compilation unit is about empty but it contains
% declarations that are used by function \verb/find_enum_of_member()/
% because the compilation unit declarations were not satisfactory (to be
% investigated: they might be satisfactory now).
\subsubsection{C Parser}
\begin{PipsMake}
c_parser > MODULE.parsed_code
> MODULE.callees
< PROGRAM.entities
< MODULE.c_source_file
< MODULE.input_file_name
< COMPILATION_UNIT.declarations
\end{PipsMake}
\begin{PipsPass}{c_parser}
If you want to parse some C code using \texttt{tpips}, it is possible to
select the C parser with
\begin{alltt}
activate C_PARSER
\end{alltt}
but this is not necessary as the parser is selected according to the
source file extension.
%%
Some properties useful (have a look at \PROPERTIES) to deal with
a C program are
\begin{alltt}
PRETTYPRINT_C_CODE TRUE (obsolete, replaced by PRETTYPRINT_LANGUAGE ``C'')
PRETTYPRINT_STATEMENT_NUMBER FALSE
PRETTYPRINT_BLOCK_IF_ONLY TRUE
\end{alltt}
\end{PipsPass}
\subsubsection{C Symbol Table}
%%\begin{PipsPass}{c_symbol_table}
A prettyprint of the symbol table for a C module can be generated with
passes \PipsPassRef{parsed_symbol_table} and
\PipsPassRef{symbol_table}.
%%\end{PipsPass}
%%\begin{PipsMake}
%%c_symbol_table > MODULE.symbol_table_file
%% < PROGRAM.entities
%% < MODULE.parsed_code
%% \end{PipsMake}
The \PipsPropRef{EXTENDED_VARIABLE_INFORMATION} property can be used
to extend the information available for variables. By default the
entity name, the offset and the size are printed. Using this property
the type and the user name, which may be different from the internal
name, are also displayed.
\begin{PipsProp}{EXTENDED_VARIABLE_INFORMATION}
EXTENDED_VARIABLE_INFORMATION FALSE
\end{PipsProp}
\subsubsection{Properties Used by the C Parsers}
The \PipsPropRef{C_PARSER_RETURN_SUBSTITUTION} property can be used to
handle properly multiple returns within one function. The current
default value is false, which preserves best the source aspect but
modifies the control flow because the calls to return are assumed to
flow in sequence. If the property is set to true, C return statement
are replaced, when necessary, either by a simple goto for void
functions, or by an assignment of the returned value to a special
variable and a goto. A unique return statement is placed at the
syntactic end of the function. For functions with no return statement
or with a unique return statement placed at the end of their bodies,
this property is useless.
\begin{PipsProp}{C_PARSER_RETURN_SUBSTITUTION}
C_PARSER_RETURN_SUBSTITUTION FALSE
\end{PipsProp}
The C99 for-loop with a declaration such as %
\lstinline|for(int i = a;...;...)| can be represented in the RI with a
naive representation such as:
\begin{lstlisting}
{
int i = a;
for(;...;...)
}
\end{lstlisting}
This is done when the
\PipsPropRef{C_PARSER_GENERATE_NAIVE_C99_FOR_LOOP_DECLARATION} property is
set to \texttt{TRUE}
\begin{PipsProp}{C_PARSER_GENERATE_NAIVE_C99_FOR_LOOP_DECLARATION}
C_PARSER_GENERATE_NAIVE_C99_FOR_LOOP_DECLARATION FALSE
\end{PipsProp}
Else, we can generate more or less other representation. For example, with
some declaration splitting, we can generate a more representative version:
\begin{lstlisting}
{
int i;
for(i = a;...;...)
}
\end{lstlisting}
if \PipsPropRef{C_PARSER_GENERATE_COMPACT_C99_FOR_LOOP_DECLARATION} property
set to \texttt{FALSE}.
\begin{PipsProp}{C_PARSER_GENERATE_COMPACT_C99_FOR_LOOP_DECLARATION}
C_PARSER_GENERATE_COMPACT_C99_FOR_LOOP_DECLARATION FALSE
\end{PipsProp}
Else, we can generate a more compact (but newer representation that can
choke some parts of \PIPS{}...) like:
\begin{lstlisting}
statement with "int i;" declaration
instruction for(i = a;...;...)
}
\end{lstlisting}
This representation is not yet implemented.
\subsection{Fortran 90}
The Fortran 90 parser is not integrated in pipsmake. It is activated
earlier when the workspace is created.
\section{Controlized Code (Hierarchical Control Flow Graph)}
\label{subsection-controlized-code}
\index{Controlizer}
\index{CFG}
\index{hCFG}
\index{Control Flow Graph}
\index{Hierarchical Control Flow Graph}
\Pips{} analyses and transformations take advantage of a hierarchical
control flow graph (HCFG), which preserves structured part of code as such, and
uses a control flow graph only when no syntactic representation is
available (see~\cite{IJT91}). The encoding of the relationship between
structured and unstructured parts of code is explained elsewhere, mainly
in the \Pri.
%% in \externalref{section-code}.
\begin{PipsPass}{controlizer}
The \PipsPassRef{controlizer} is the historical controlizer phase
that removes \verb+GOTO+ statements in the parsed code and generates a
similar representation with small CFGs. It was developped for
Fortran~77 code.
\end{PipsPass}
The Fortran controlizer phase was too hacked and undocumented to be improved and
debugged for C99 code so a new version has been developed, documented
and is designed to be simpler and easier to understand. But, for comparison, the
Fortran controlizer phase can still be used.
\begin{PipsMake}
controlizer > MODULE.code
< PROGRAM.entities
< MODULE.parsed_code
\end{PipsMake}
For debugging and validation purpose, by setting \emph{at most} one of the
\verb|PIPS_USE_OLD_CONTROLIZER| or \verb|PIPS_USE_NEW_CONTROLIZER|
environment variables, you can force the use of the specific version of
the controlizer you want to use. This override the setting by activate\marginpar{Ronan?}.
Note that the controlizer choice impacts the HCFG
when Fortran entries are used. If you do not know what
Fortran entries are, it is deprecated stuff anyway... \smiley
\begin{PipsPass}{new_controlizer}
The \PipsPassRef{new_controlizer} removes \verb+GOTO+
statements in the parsed code and generates a similar representation
with small CFGs. It is designed to work according to C and C99
standards. Sequences of sequence and variable declarations are handled
properly. However, the prettyprinter is tuned for code generated by
\PipsPassRef{controlizer}, which does not always minimize the number
of goto statements regenerated.
\end{PipsPass}
The hierarchical control flow graph built by the \PipsPassRef{controlizer} is
pretty crude. The partial control flow graphs, called
\texttt{unstructured} statements, are derived from syntactic
constructs. The control scope of an unstructured is the smallest
enclosing structured construct, whether a loop, a test or a sequence.
Thus some statements, which might be seen as part of structured code, end up
as nodes of an unstructured.
Note that sequences of statements are identified as such by
\PipsPassRef{controlizer}. Each of them appears as a unique node.
Also, useless CONTINUE statements may be added as provisional landing
pads and not removed. The exit node should never have successors but this
may happen after some PIPS function calls. The
exit node, as well as several other nodes, also may be unreachable. After
clean up, there should be no unreachable node or the only unreachable node
should be the exit node.
Function \PipsPassRef{unspaghettify} (see
Section~\ref{sec:unspaghettify}) is applied by default to clean
up and to reduce the control flow graphs after \PipsPassRef{controlizer}.
The {\tt GOTO} statements are transformed in arcs but also in {\tt
CONTINUE} statements to preserve as many user comments as possible.
The top statement of a module returned by the \PipsPassRef{controlizer} used to
contain always an unstructured instruction with only one node. Several phases
in \Pips{} assumed that this always is the case, although other program
transformations may well return any kind of top statement, most likely a
\texttt{block}. This is no longer true. The top statement of a module may
contain any kind of instruction.
Here is declared the C and C99 controlizer:
\begin{PipsMake}
new_controlizer > MODULE.code
< PROGRAM.entities
< MODULE.parsed_code
\end{PipsMake}
Control restructuring eliminates empty sequences but as empty true or
false branch of structured \verb/IF/. This semantic property of \Pri{}
is enforced by libraries \verb/effects/,
\verb/regions/, \verb/hpfc/, \verb/effects-generic/.
\begin{PipsProp}{WARN_ABOUT_EMPTY_SEQUENCES}
WARN_ABOUT_EMPTY_SEQUENCES FALSE
\end{PipsProp}
By unsetting this property \PipsPassRef{unspaghettify} is not applied
implicitly in the controlizer phase.
\begin{PipsProp}{UNSPAGHETTIFY_IN_CONTROLIZER}
UNSPAGHETTIFY_IN_CONTROLIZER TRUE
\end{PipsProp}
The next property is used to convert C for loops into C while
loops. The purpose is to speed up the re-use of Fortran analyses and
transformation for C code. This property is set to false by default
and should ultimately disappear. But for new user convenience, it is
set to TRUE by \verb/activate_language()/ when the language is C.
\begin{PipsProp}{FOR_TO_WHILE_LOOP_IN_CONTROLIZER}
FOR_TO_WHILE_LOOP_IN_CONTROLIZER FALSE
\end{PipsProp}
The next property is used to convert C for loops into C do loops when
syntactically possible. The conversion is not safe because the effect of
the loop body on the loop index is not checked. The purpose is to speed up
the re-use of Fortran analyses and transformation for C code. This
property is set to false by default and should disappear soon. But for
new user convenience, it is set to TRUE by \verb/activate_language()/
when the language is C.
\begin{PipsProp}{FOR_TO_DO_LOOP_IN_CONTROLIZER}
FOR_TO_DO_LOOP_IN_CONTROLIZER FALSE
\end{PipsProp}
This can also explicitly applied by calling the phase described in
\S~\ref{sec:loop-do-loop}.
\subsubsection*{FORMAT Restructuring}
\index{Format (Fortran)}
\index{GATHER\_FORMATS\_AT\_BEGINNING}
\index{GATHER\_FORMATS\_AT\_END}
To able deeper code transformation, FORMATs can be gathered at the
very beginning of the code or at the very end according to the
following options in the unspaghettify or control restructuring phase.
\begin{PipsProp}{GATHER_FORMATS_AT_BEGINNING}
GATHER_FORMATS_AT_BEGINNING FALSE
\end{PipsProp}
\begin{PipsProp}{GATHER_FORMATS_AT_END}
GATHER_FORMATS_AT_END FALSE
\end{PipsProp}
\subsection{Properties for Clean Up Sequences}
% FI: should be moved next to the declaration of the pass
\index{CLEAN\_UP\_SEQUENCES\_DISPLAY\_STATISTICS}
To display the statistics about cleaning-up sequences and removing
useless CONTINUE or empty statement.
\begin{PipsProp}{CLEAN_UP_SEQUENCES_DISPLAY_STATISTICS}
CLEAN_UP_SEQUENCES_DISPLAY_STATISTICS FALSE
\end{PipsProp}
\index{FUSE\_CONTROL\_NODES\_WITH\_COMMENTS\_OR\_LABEL}
There is a trade-off between keeping the comments associated to labels and
goto and the cleaning that can be do on the control graph.
By default, do not fuse empty control nodes that have labels or comments:
\begin{PipsProp}{FUSE_CONTROL_NODES_WITH_COMMENTS_OR_LABEL}
FUSE_CONTROL_NODES_WITH_COMMENTS_OR_LABEL FALSE
\end{PipsProp}
By default, do not fuse sequences with internal declarations. Turning
this to \texttt{TRUE} results in variable renamings when the same
variable name is used at several places in the analyzed module.
\begin{PipsProp}{CLEAN_UP_SEQUENCES_WITH_DECLARATIONS}
CLEAN_UP_SEQUENCES_WITH_DECLARATIONS FALSE
\end{PipsProp}
\subsection{Symbol Table Related to a Module Code}
The prettyprint of the symbol table for a Fortran or C module is generated with:
\begin{PipsMake}
symbol_table > MODULE.symbol_table_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\section{Parallel Code}
\label{subsection-parallel-code}
The internal representation includes special field to declare parallel
constructs such as parallel loops. A parallel code internal
representation does not differ fundamentally from a sequential code.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% FI-> ??: why is it located here?
\chapter{Pedagogical Phases}
\label{chapter:pedagogical-phases}
\label{cha:pedagogical-phases}
Although this phases should be spread elsewhere in this manual, we have
put some pedagogical phases useful to jump into PIPS first.
\section{Using XML backend}
\label{sec:using-xml-backend}
A phase that displays, in debug mode, statements matching an XPath
expression on the internal representation:
\begin{PipsMake}
alias simple_xpath_test 'Output debug information about XPath matching'
simple_xpath_test > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\section{Operating of gen\_multi\_recurse}
\label{sec:gen-multi-recurse-explorer}
A phase that displays the explore path of function gen\_multi\_recurse.
\begin{PipsMake}
alias gen_multi_recurse_explorer 'Output debug information about XPath matching'
gen_multi_recurse_explorer > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\section{Prepending a comment}
\label{sec:prepending-comment}
\begin{PipsPass}{prepend_comment}
Prepends a comment to the first statement of a module.
Useful to apply post-processing after PIPS.
\end{PipsPass}
\begin{PipsMake}
alias prepend_comment 'Prepend a comment to the first statement of a module'
prepend_comment > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
The comment to add is selected by this property:
\begin{PipsProp}{PREPEND_COMMENT}
PREPEND_COMMENT "/* This comment is added by PREPEND_COMMENT phase */"
\end{PipsProp}
\section{Prepending a call}
\label{sec:prepending-call}
\begin{PipsPass}{prepend_call}
This phase inserts a call to function \verb/MY_TRACK/ just before the first statement of a module.
Useful as a pedagogical example to explore the internal representation
and Newgen. Not to be used for any pratical purpose as it is
bugged. Debugging it is a pedagogical exercise.
\end{PipsPass}
\begin{PipsMake}
alias prepend_call 'Insert a call to MY_TRACK just before the first statement of a module'
prepend_call > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
The called function could be defined by this property:
\begin{PipsProp}{PREPEND_CALL}
PREPEND_CALL "MY_TRACK"
\end{PipsProp}
but it is not.
\section{Add a pragma to a module}
\label{sec:add-pragma}
\begin{PipsPass}{add_pragma}
This phase prepend or appends a pragma to a module.
\end{PipsPass}
\begin{PipsMake}
alias add_pragma 'Prepends or append a pragma to the code of a module'
add_pragma > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
The pragma name can be defined by this property:
\begin{PipsProp}{PRAGMA_NAME}
PRAGMA_NAME "MY_PRAGMA"
\end{PipsProp}
The pragma can be append or prepend thanks to this property:
\begin{PipsProp}{PRAGMA_PREPEND}
PRAGMA_PREPEND TRUE
\end{PipsProp}
\begin{PipsPass}{clear_pragma}
The pass \PipsPassRef{clear_pragma} clears all pragma, this should be done on
any input with unhandled pragma, we don't what semantic we might break.
\end{PipsPass}
\begin{PipsMake}
clear_pragma > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{pragma_outliner}
The pass \PipsPassRef{pragma_outliner} is used for outlining a sequence of
statements contained between two given sentinel pragmas using properties
\PipsPropRef{PRAGMA_OUTLINER_BEGIN} and \PipsPropRef{PRAGMA_OUTLINER_END}.
The name of the new function is controlled using
\PipsPropRef{PRAGMA_OUTLINER_PREFIX}.
\end{PipsPass}
\begin{PipsMake}
pragma_outliner > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.regions
< CALLEES.summary_regions
< MODULE.summary_regions
< MODULE.transformers
< MODULE.preconditions
\end{PipsMake}
\begin{PipsProp}{PRAGMA_OUTLINER_BEGIN}
PRAGMA_OUTLINER_BEGIN "begin"
\end{PipsProp}
\begin{PipsProp}{PRAGMA_OUTLINER_END}
PRAGMA_OUTLINER_END "end"
\end{PipsProp}
\begin{PipsProp}{PRAGMA_OUTLINER_PREFIX}
PRAGMA_OUTLINER_PREFIX "pips_outlined"
\end{PipsProp}
\begin{PipsPass}{remove_useless_label}
Remove labels that are not usefull
\end{PipsPass}
\begin{PipsMake}
remove_useless_label > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Loop labels can be kept thanks to this property:
\begin{PipsProp}{REMOVE_USELESS_LABEL_KEEP_LOOP_LABEL}
REMOVE_USELESS_LABEL_KEEP_LOOP_LABEL FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ANALYSES
\chapter{Static Analyses}
\label{section-analyses}
\index{Analysis}
Analyses encompass the computations of call graphs, the memory effects,
reductions, use-def chains, dependence graphs, interprocedural checks
({\em flinter}), semantics information (transformers and preconditions),
continuations, complexities, convex array regions, dynamic aliases and
complementary regions.
\section{Call Graph}
\label{subsection-call-graph}
\index{Call Graph}
All lists of callees are needed to build the global lists of callers
for each module. The callers and callees lists are used by \Pipsmake{}
to control top-down and bottom-up analyses. The call graph is
assumed to be a DAG, i.e. no recursive cycle exists, but it is not
necessarily connected.
The height of a module can be used to schedule bottom-up analyses. It is
zero if the module has no callees. Else, it is the maximal height of the
callees plus one.
The depth of a module can be used to schedule top-down analyses. It is
zero if the module has no callers. Else, it it the maximal depth of the
callers plus one.
\begin{PipsMake}
callgraph > ALL.callers
> ALL.height
> ALL.depth
< ALL.callees
\end{PipsMake}
The following pass generates a \PuDrawGraph version of the callgraph. Its
quite partial since it should rely on an hypothetical \emph{all callees},
direct and indirect, resource.
\begin{PipsMake}
alias dvcg_file 'Graphical Call Graph'
alias graph_of_calls 'For current module'
alias full_graph_of_calls 'For all modules'
graph_of_calls > MODULE.dvcg_file
< ALL.callees
full_graph_of_calls > PROGRAM.dvcg_file
< ALL.callees
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Memory Effects
\section{Memory Effects}
\label{subsection-effects}
\index{Effect}
\index{Memory Effect}
The data structures used to represent memory effects and their
computation are described in~\cite{IJT92}. Another description is
available on line, in \Pri{} Technical Report.
Note that the standard name in the Dragon book is likely to be {\em
Gen} and {\em Kill} sets in the standard data flow analysis
framework, but PIPS uses the more general concept of {\em effect}
developped by P.~Jouvelot and D.~Gifford~\cite{JG89} and its analyses are mostly
based on the abstract syntac tree (AST) rather than the control flow
graph (CFG).
\subsection{Proper Memory Effects}
\label{subsubsection-proper-effects}
\index{Proper Effects}
\index{Effects (Proper)}
\begin{PipsPass}{proper_effects}
The proper memory effects of a statement basically are a list of variables
that may be read (used) or written (defined) by the statement. They are used to build use-def
chains (see~\cite{ASU86} or a later edition) and then the dependence graph.
Proper means that the effects of a compound statement do not include the
effects of lower level statements. For instance, the body of a loop, true and
false branches of a test statement, control nodes in an unstructured
statement ... are ignored to compute the proper effects of a loop, a
test or an unstructured.
Two families of effects are computed : {\tt pointer\_effects} are
effects in which intermediary access paths may refer to different
memory locations at different program points; regular {\tt effects}
are constant path effects, which means that their intermediary access
paths all refer to unique memory locations. The same distinction holds
for convex array regions (see section~\ref{subsection-array-regions}).
{\tt proper\_effects\_with\_points\_to} and {\tt
proper\_effects\_with\_pointer\_values} are alternatives to compute
constant path proper effects using points-to (see
subsection~\ref{subsection-points-to-analysis}) or pointer values
analyses (see subsection~\ref{subsection-pointer-values}). This is
still at an experimental stage.
Summary effects (see
Section~\ref{subsubection-summary-data-flow-information}) of a called
module are used to compute the proper effects at the corresponding
call sites. They are translated from the callee's scope into the
caller's scope. The translation is based on the actual-to-formal
binding. If too many actual arguments are defined, a user warning is
issued but the processing goes on because a simple semantics is
available: ignore useless actual arguments. If too few actual
arguments are provided, a user error is issued because the effects of
the call are not defined.
Variables private to loops are handled like regular variable.
\end{PipsPass}
\begin{PipsPass}{proper_pointer_effects}
See \PipsPassRef{proper_effects}
\end{PipsPass}
\begin{PipsPass}{proper_effects_with_points_to}
See \PipsPassRef{proper_effects}
\end{PipsPass}
\begin{PipsMake}
proper_pointer_effects > MODULE.proper_pointer_effects
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_pointer_effects
\end{PipsMake}
\begin{PipsMake}
proper_effects > MODULE.proper_effects
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_effects
\end{PipsMake}
When pointers are used, points-to information is useful to obtain
precise proper memory effects.
Because points-to analysis is able to detect some cases of segfaults,
variables that are not defined/written can nevertheless have a
different abstract value at the beginning and at the end of a piece of
code.
This leads to difficulties with memory effects. Firstly, if a piece of
code is not reachable because a segfault always occurs before it is
executed, it has no memory effects (as usual, the PIPS output is
pretty surprising...). Secondly, cumulated memory effects can either
be any effect that is linked to any execution of a piece of code or
any effect that happens when the executions reach the end of the piece
of code.
So EffectsWithPointsTo contains weird results either because the code
always segfault somewhere or because the code might segfault because a
function argument is not checked before it is used. Hence, effects
disappear or must effects become may effects.
\begin{PipsMake}
proper_effects_with_points_to > MODULE.proper_effects
< PROGRAM.entities
< MODULE.code
< MODULE.points_to
< CALLEES.summary_effects
\end{PipsMake}
% Specific functions used:
%
% simple_effect_to_constant_path_effects_with_points_to
% eval_simple_cell_with_points_to()
% generic_eval_cell_with_points_to()
% transform_sink_cells_from_matching_list
% simple_cell_reference_with_address_of_cell_reference_translation
% simple_cell_reference_with_address_of_cell_reference_translation_fi
%
% For debugging: EVAL_CELL_WITH_POINTS_TO_DEBUG_LEVEL
\begin{PipsMake}
proper_effects_with_pointer_values > MODULE.proper_effects
< PROGRAM.entities
< MODULE.code
< MODULE.simple_pointer_values
< CALLEES.summary_effects
\end{PipsMake}
\subsection{Filtered Proper Memory Effects}
\label{subsubsection-filtered-proper-effects}
\marginpar{To be continued...by whom?}
\begin{PipsPass}{filter_proper_effects}
This phase collects information about where a given global variable is
actually modified in the program.
\end{PipsPass}
\begin{PipsMake}
filter_proper_effects > MODULE.filtered_proper_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< CALLEES.summary_effects
\end{PipsMake}
\subsection{Cumulated Memory Effects}
\label{subsubsection-cumulated-effects}
\index{Cumulated Effects}
\index{Effects (Cumulated)}
\begin{PipsPass}{cumulated_effects}
Cumulated effects of statements are lists of read or written
variables, just like the proper effects
(see Section~\ref{subsubsection-proper-effects}).
Cumulated means that the effects of a compound statement, do
loop, test or unstructured, include the effects of the lower level
statements such as a loop body or a test branch.
For return, exit and abort statements
(only for the main function or what is consider as the main function),
cumulated effects will also add the read on LUNS (Logical Units)
that are present for the function.
The goal of adding read LUNS for these statements is to improve
OUT Effects (and Regions) especially for the last statements
that make a write on LUNS.
% NL: There is a random bug when creating a ressource that is never use
% when deleting obsoleted ressources
% in function check_physical_resource_up_to_date?
% To have information about useful\_variables\_effects
% see Section~\ref{section-useful_variables_regions}.
\end{PipsPass}
% > MODULE.useful_variables_effects
\begin{PipsMake}
cumulated_effects > MODULE.cumulated_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\begin{PipsPass}{cumulated_effects_with_points_to}
TODO: inline documentation
\end{PipsPass}
% > MODULE.useful_variables_effects
\begin{PipsMake}
cumulated_effects_with_points_to > MODULE.cumulated_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\begin{PipsPass}{cumulated_effects_with_pointer_values}
TODO: inline documentation
\end{PipsPass}
% > MODULE.useful_variables_effects
\begin{PipsMake}
cumulated_effects_with_pointer_values > MODULE.cumulated_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\begin{PipsPass}{cumulated_pointer_effects}
TODO: inline documentation
\end{PipsPass}
% > MODULE.useful_variables_effects
\begin{PipsMake}
cumulated_pointer_effects > MODULE.cumulated_pointer_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_pointer_effects
\end{PipsMake}
\begin{PipsPass}{cumulated_pointer_effects_with_points_to}
TODO: inline documentation
\end{PipsPass}
% > MODULE.useful_variables_effects
\begin{PipsMake}
cumulated_pointer_effects_with_points_to > MODULE.cumulated_pointer_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_pointer_effects
< MODULE.points_to
\end{PipsMake}
\begin{PipsPass}{cumulated_pointer_effects_with_pointer_values}
TODO: inline documentation
\end{PipsPass}
% > MODULE.useful_variables_effects
\begin{PipsMake}
cumulated_pointer_effects_with_pointer_values > MODULE.cumulated_pointer_effects
< PROGRAM.entities
< MODULE.code
< MODULE.proper_pointer_effects
< MODULE.simple_pointer_values
\end{PipsMake}
\subsection{Summary Data Flow Information (SDFI)}
\label{subsubection-summary-data-flow-information}
\index{SDFI}
Summary data flow information is the simplest interprocedural
information needed to take procedure into account in a
parallelizer. It was introduced in Parafrase (see~\cite{LY88c}) under
this name, but should be called summary memory effects in PIPS context.
\begin{PipsPass}{summary_effects}
The \PipsPassRef{summary_effects} of a module are the cumulated memory
effects of its
top level statement (see Section~\ref{subsubsection-cumulated-effects}), but effects on local dynamic variables are
ignored (because they cannot be observed by the callers\footnote{Unless
it accesses illegally the stack: see Tom Reps,
http://pages.cs.wisc.edu/~reps}) and subscript expressions of remaining
effects are eliminated.
\end{PipsPass}
\begin{PipsMake}
summary_pointer_effects > MODULE.summary_pointer_effects
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_pointer_effects
\end{PipsMake}
\begin{PipsMake}
summary_effects > MODULE.summary_effects
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{IN and OUT Effects}
\label{subsubsection-in-and-out-effects}
\index{IN Effects}
\index{OUT Effects}
\index{Effects (IN)}
\index{Effects (OUT)}
IN and OUT memory effects of a statement $s$ are memory locations
whose input values are used by statement $s$ or whose output values
are used by statement $s$ continuation. Variables allocated in the
statement are not part of the IN or OUT effects. Variables defined
before they are used ar not part of the IN effects. OUT effects
require an interprocedural analysis\footnote{They are not validated as
of June 21, 2008 (FI).}
\begin{PipsMake}
in_effects > MODULE.in_effects
> MODULE.cumulated_in_effects
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< CALLEES.in_summary_effects
in_summary_effects > MODULE.in_summary_effects
< PROGRAM.entities
< MODULE.code
< MODULE.in_effects
out_summary_effects > MODULE.out_summary_effects
< PROGRAM.entities
< MODULE.code
< CALLERS.out_effects
out_effects > MODULE.out_effects
< PROGRAM.entities
< MODULE.code
< MODULE.out_summary_effects
< MODULE.cumulated_in_effects
\end{PipsMake}
\subsection{Proper and Cumulated References}
%\label{subsubsection-cumulated-effects}
%\index{Cumulated Effects}
%\index{Effects (Cumulated)}
The concept of {\em proper references} is not yet clearly defined. The
original idea is to keep track of the actual objects of Newgen domain
{\tt reference} used in the program representation of the current
statement, while retaining if they correspond to a read or a write of
the corresponding memory locations. Proper references are
represented as effects.
For C programs, where memory accesses are not necessarily represented
by objects of Newgen domain {\tt reference}, the semantics of this
analysis is unclear.
Cumulated references gather proper references over the program
code, without taking into account the modification of memory stores by
the program execution.
\emph{FC: I should implement real summary references?}
\begin{PipsMake}
proper_references > MODULE.proper_references
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_effects
cumulated_references > MODULE.cumulated_references
< PROGRAM.entities
< MODULE.code
< MODULE.proper_references
\end{PipsMake}
\subsection{Effect Properties}
\index{Effects (Memory)}
\index{Memory Effects}
\index{EFFECTS\_FILTER\_ON\_VARIABLE}
%% \index{EFFECTS\_PRINT\_SDFI} Obsolete
%% \index{MEMORY\_EFFECTS\_ONLY} Moved in a subsubsection
% no longer used {
% Print SDFI just after computation:
%
% \begin{PipsProp}{EFFECTS_PRINT_SDFI}
% EFFECTS_PRINT_SDFI TRUE
% \end{PipsProp}
% }
Effects are a first or second level analysis. They are analyzed using
only some information about pointers, either none, or points-to or
pointer values. They are used by many passes such as dependence graph
analysis (Rice Pass), semantics analysis (Transformers passes), convex
array regions analysis...
It is often tempting, useful or necessary to ignore some effects. It
is always safer to ignore effects when they are used by a pass to
avoid possible inconsistencies due to other passes using
effects. However, it may be necessary to ignore some effects in an
effect pass because effects are merged and cannot be unmerged by a
later pass. Of course, this is not a standard setting for PIPS and the
semantics of the resulting codes or later analyses is unknown in
general, but to the person who makes the decision for a subset of
input codes or for experimental reasons.
\subsubsection{Effects Filtering}
\index{EFFECTS\_FILTER\_ON\_VARIABLE}
\index{USER\_EFFECTS\_ON\_STD\_FILES}
Filter this variable in phase \PipsPassRef{filter_proper_effects}.
\begin{PipsProp}{EFFECTS_FILTER_ON_VARIABLE}
EFFECTS_FILTER_ON_VARIABLE ""
\end{PipsProp}
Property \PipsPropRef{USER_EFFECTS_ON_STD_FILES} is used to control the
way the user uses {\tt stdout}, {\tt stdin} and {\tt stderr}. The
default case ({\tt FALSE}) means that the user does not modify these
global variables. When set to {\tt TRUE}, they are considered as user
variables, and dereferencing them through calls to stdio functions
leads to less precise effects.
\begin{PipsProp}{USER_EFFECTS_ON_STD_FILES}
USER_EFFECTS_ON_STD_FILES FALSE
\end{PipsProp}
\subsubsection{Checking Pointer Updates}
\index{EFFECTS\_POINTER\_MODIFICATION\_CHECKING}
When set to {\tt TRUE},
\PipsPropRef{EFFECTS_POINTER_MODIFICATION_CHECKING} enables pointer
modification checking during the computation of cumulated effects
and/or RW convex array regions. Since this is still at experimentation
level, it's default value is FALSE.
%%
This property should disappear when pointer modification analyses are
more mature.
\begin{PipsProp}{EFFECTS_POINTER_MODIFICATION_CHECKING}
EFFECTS_POINTER_MODIFICATION_CHECKING FALSE
\end{PipsProp}
\subsubsection{Dereferencing Effects}
\index{CONSTANT\_PATH\_EFFECTS}
\index{TRUST\_CONSTANT\_PATH\_EFFECTS\_IN\_CONFLICTS}
The default (and correct) behaviour for the computation of effects is
to transform dereferencing paths into constant paths using the
information available, either none or points-to or pointer values, and
abstract locations used to represent sets of locations.
When property \PipsPropRef{CONSTANT_PATH_EFFECTS} is set to {\tt
FALSE}, the latter transformation is skipped. Effects are then
equivalent to pointer\_effects. This property is available for
backward compatibility and experimental purpose. It must be born in
mind that analyses and transformations using the resulting effects may
yield uncorrect results. This property also affects the computation of
convex array regions.
\begin{PipsProp}{CONSTANT_PATH_EFFECTS}
CONSTANT_PATH_EFFECTS TRUE
\end{PipsProp}
Since \PipsPropRef{CONSTANT_PATH_EFFECTS} may be set to {\tt FALSE}
erroneously, some tests are included in conflicts testing to avoid
generating wrong code. However, these tests are costly, and can be
turned off by setting
\PipsPropRef{TRUST_CONSTANT_PATH_EFFECTS_IN_CONFLICTS} to {\tt
FALSE}. This must be used with care and only when there is no aliasing.
\begin{PipsProp}{TRUST_CONSTANT_PATH_EFFECTS_IN_CONFLICTS }
TRUST_CONSTANT_PATH_EFFECTS_IN_CONFLICTS FALSE
\end{PipsProp}
\PipsPropRef{EFFECTS_IGNORE_DEREFERENCING} is set to {\tt FALSE}. This
must be used with extreme care and only when pointer operations are
known no to matter with the analysis performed because only a subset
of input codes is used. Constant path effects are obtained by
filtering constant path effects and by dropping effects due to a
pointer-related address computation as in \texttt{*p=3;} or
\texttt{p->i=3;}.
\begin{PipsProp}{EFFECTS_IGNORE_DEREFERENCING}
EFFECTS_IGNORE_DEREFERENCING FALSE
\end{PipsProp}
\subsubsection{Effects of References to a Variable Length Array (VLA)}
\index{VLA\_EFFECT\_READ}
Property \PipsPropRef{VLA_EFFECT_READ} makes a read effect on variables
dimension of an variable-length array (vla) at each use of it.
For instance, with an array declared as {\tt a[size]}, at each occurence
of {\tt a}, like {\tt a[i]}, a {\tt READ effect} will be made for {\tt size}.
Normally, no reason to set it to {\tt FALSE}.
For parallelization purpose, maybe want to set it to false?
\begin{PipsProp}{VLA_EFFECT_READ}
VLA_EFFECT_READ TRUE
\end{PipsProp}
\subsubsection{Memory Effects vs Environment Effects}
\index{MEMORY\_EFFECTS\_ONLY}
Property \PipsPropRef{MEMORY_EFFECTS_ONLY} is used to restrict the
action kind of an effect action to \verb/store/. In other words,
variable declarations and type declarations are not considered to
alter the execution state when this property is set to TRUE. This is
fine for Fortran code because variables cannot be declared among
executable statements and because new type cannot be declared. But
this leads to wrong result for C code when loop distribution or
use-def elimination is performed.
Currently, PIPS does not have the capability to store default values
depending on the source code language. The default value is TRUE to
avoid disturbing too many phases of PIPS at the same time while
environment and type declaration effects are introduced.
\begin{PipsProp}{MEMORY_EFFECTS_ONLY}
MEMORY_EFFECTS_ONLY TRUE
\end{PipsProp}
\subsubsection{Time Effects}
\index{TIME\_EFFECTS\_USED}
Some programs do measure execution times. All code placed between
measurement points must not be moved out, as can happen when loops are
distributed or, more generally, instructions are rescheduled. Since
loops using time effects are not parallel, a clock variable is always
updated when a time-related function is called. This is sufficient to
avoid most problems, but not all of them because time effects of all
other executed statements are kept implicit, i.e. the real time clock
is not updated: and loops can still be distributed. If time
measurements are key, this property must be turned on. By default, it
is turned off.
\begin{PipsProp}{TIME_EFFECTS_USED}
TIME_EFFECTS_USED FALSE
\end{PipsProp}
\subsubsection{Effects of Unknown Functions}
\index{MAXIMAL\_PARAMETER\_EFFECTS\_FOR\_UNKNOWN\_FUNCTIONS}
\index{MAXIMAL\_EFFECTS\_FOR\_UNKNOWN\_FUNCTIONS}
Some source code is sometimes missing. \PIPS does not have any way to
guess the memory effects of functions whose source code is
missing. Several approaches are possible to approximate the exact
effects. Two optimistic ones are implemented: either we assume that
the function only computes a result and has no side effects thru
pointer parameters, global variables or static variables (default
option), or we assume the maximal possible effects through pointers
(this should be clarified: for all pointers \verb/p/, \verb/*p/ is
written) but not thru static or global variables.
\begin{PipsProp}{MAXIMAL_PARAMETER_EFFECTS_FOR_UNKNOWN_FUNCTIONS}
MAXIMAL_PARAMETER_EFFECTS_FOR_UNKNOWN_FUNCTIONS FALSE
\end{PipsProp}
For safety, a pessimitic option is be implemented and a maximal memory
effect, \verb/*ANYMODULE*:*ANYWHERE*/, is associated to such unknown
functions.
\begin{PipsProp}{MAXIMAL_EFFECTS_FOR_UNKNOWN_FUNCTIONS}
MAXIMAL_EFFECTS_FOR_UNKNOWN_FUNCTIONS FALSE
\end{PipsProp}
These two properties should not be true simultaneously.
\subsubsection{Other Properties Impacting EFfects}
\index{ALIASING\_ACROSS\_TYPES}
Property \PipsPropRef{ALIASING_ACROSS_TYPES} has an impact on effect
computation. When the locations used or defined by a memory effect are
unknown, an abstract location is used to represent either all possible
locations of the program (TRUE) or all locations of a certain type (FALSE).
\section{Live Memory Access Paths}
\label{subsection-live-memory-paths}
\index{Live variables}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Reductions
\section{Reductions}
\label{sec:reductions}
The proper reductions are computed from a code.
\begin{PipsMake}
proper_reductions > MODULE.proper_reductions
< PROGRAM.entities
< MODULE.code
< MODULE.proper_references
< CALLEES.summary_effects
< CALLEES.summary_reductions
\end{PipsMake}
The cumulated reductions propagate the reductions in the code, upwards.
\begin{PipsMake}
cumulated_reductions > MODULE.cumulated_reductions
< PROGRAM.entities
< MODULE.code
< MODULE.proper_references
< MODULE.cumulated_effects
< MODULE.proper_reductions
\end{PipsMake}
This pass summarizes the reductions candidates found in a module for
export to its callers. The summary effects should be used to restrict
attention to variable of interest in the translation?
\begin{PipsMake}
summary_reductions > MODULE.summary_reductions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_reductions
< MODULE.summary_effects
\end{PipsMake}
Some possible (simple) transformations could be added to the code to mark
reductions in loops, for latter use in the parallelization.
The following is NOT implemented. Anyway, should the cumulated\_reductions
be simply used by the prettyprinter instead?
\begin{PipsMake}
loop_reductions > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_reductions
\end{PipsMake}
\subsection{Reduction Propagation}
\begin{PipsPass}{reduction_propagation}
tries to transform
\begin{lstlisting}
{
a = b + c;
r = r + a;
}
\end{lstlisting}
into
\begin{lstlisting}
{
r = r +b ;
r = r +c ;
}
\end{lstlisting}
\end{PipsPass}
\begin{PipsMake}
reduction_propagation > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_reductions
< MODULE.dg
\end{PipsMake}
\subsection{Reduction Detection}
\begin{PipsPass}{reduction_detection}
tries to transform
\begin{lstlisting}
{
a = b + c;
b = d + a;
}
\end{lstlisting}
which hides a reduction on b
into
\begin{lstlisting}
{
b = b + c ;
b = d + b ;
}
\end{lstlisting}
when possible
\end{PipsPass}
\begin{PipsMake}
reduction_detection > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\section{Chains (Use-Def Chains)}
\label{subsection-chains}
\index{Use-Def Chains}
\index{Def-Use Chains}
\index{Use-Use Chains}
\index{Use-Def Chains}
\begin{PipsPass}{chains}
Use-def and def-use chains are a standard data structure in optimizing
compilers~\cite{ASU86}. These chains are used as a first approximation of
the dependence graph. Chains based on convex array regions (see
Section~\ref{subsection-array-regions}) are more effective for
interprocedural parallelization.
If chains based on convex array regions have been selected, the simplest dependence
test must be used because regions carry more information than any kind
of preconditions. Preconditions and loop bound information already are
included in the region predicate.
\end{PipsPass}
\subsection{Menu for Use-Def Chains}
\begin{PipsMake}
alias chains 'Use-Def Chains'
alias atomic_chains 'Standard'
alias region_chains 'Regions'
alias in_out_regions_chains 'In-Out Regions'
\end{PipsMake}
\subsection{Standard Use-Def Chains (a.k.a. Atomic Chains)}
\label{subsubsection-atomic-chains}
\index{Use-Def Chains}
\index{Atomic Chains}
\begin{PipsPass}{atomic_chains}
The algorithm used to compute use-def chains is original because it is
based on \Pips{} hierarchical control flow graph and not on a unique
control flow graph.
This algorithm generates inexistent dependencies on loop indices. These
dependence arcs appear between DO loop headers and implicit DO loops in
IO statements, or between one DO loop header and unrelated DO loop bound
expressions using that index variable. It is easy to spot the problem
because loop indices are not privatized. A prettyprint option,
\begin{center}
\PipsPropRef{PRETTYPRINT_ALL_PRIVATE_VARIABLES}
\end{center}
must be set to true to see if the loop index is privatized or
not. The problem disappears when some loop indices are renamed.
The problem is due to the internal representation of DO loops: \Pips{} has
no way to distinguish between initialization effects and increment
effects. They have to be merged as proper loop effects. To reduce the
problem, proper effects of DO loops do not include the index read effect
due to the loop incrementation.
Artificial arcs are added to... (Pierre Jouvelot, help!).
\end{PipsPass}
\begin{PipsMake}
atomic_chains > MODULE.chains
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\subsection{READ/WRITE Region-Based Chains}
\begin{PipsPass}{region_chains}
\label{subsubsection-read-write-region-based-chains}
Such chains are required for effective interprocedural parallelization. The
dependence graph is annotated with {\em proper regions}, to avoid inaccuracy
due to summarization at simple statement level (see
Section~\ref{subsection-array-regions}).
Region-based chains are only compatible with the Rice Fast Dependence Graph
option (see Section~\ref{subsubsection-menu-for-dependence-tests})
which has been extended to deal with them\footnote{When using regions,
the {\em fast} qualifier does not stand anymore, because the dependence
test involves dealing with convex systems that contain much more
constraints than when using the sole array indices.}. Other
dependence tests do not use region descriptors (their convex system),
because they cannot improve the Rice Fast Dependence test based on regions.
Regions chains are built using {\em proper regions} which are particular
\verb+READ+ and \verb+WRITE+ regions.
For simple statements (assignments, calls to intrinsic functions),
summarization is avoided to preserve accuracy.
At this inner level of the program control flow graph, the extra
amount of memory necessary to store regions without computing their convex
hull should not be too high compared to the expected gain for dependence
analysis.
For tests and loops, proper regions contain the regions associated
to the condition or the range.
And for external calls, proper regions are the {\em summary regions} of the
callee translated into the caller's name space, to which are merely appended
the regions of the expressions passed as argument
(no summarization for this step).
\end{PipsPass}
\begin{PipsMake}
region_chains > MODULE.chains
< PROGRAM.entities
< MODULE.code
< MODULE.proper_regions
\end{PipsMake}
\subsection{IN/OUT Region-Based Chains}
\begin{PipsPass}{in_out_regions_chains}
\label{subsubsection-in-out-region-based-chains}
Beware : this option is for experimental use only; resulting parallel code
may not be equivalent to input code (see the explanations below).
When \PipsPassRef{in_out_regions_chains} is selected, IN and OUT regions (see
Sections~\ref{subsubsection-in-regions} and
\ref{subsubsection-out-regions}) are used at call sites instead of
READ and WRITE regions. For all other statements, usual READ and WRITE
regions are used.
As a consequence, arrays and scalars which could be declared as local
in callees, but are exposed to callers because they are statically
allocated or are formal parameters, are ignored, increasing the
opportunities to detect parallel loops. But as the program
transformation which consists in {\em privatizing} variables in
modules is not yet implemented in \Pips{}, the code resulting from the
parallelization with \PipsPassRef{in_out_regions_chains} may not be
equivalent to the original sequential code. The privatization here is
non-standard: for instance, variables declared in commons or static
should be stack allocated to avoid conflicts.
As for region-based chains (see
Section~\ref{subsubsection-read-write-region-based-chains}), the
simplest dependence test should be selected for best results.
\end{PipsPass}
\begin{PipsMake}
in_out_regions_chains > MODULE.chains
< PROGRAM.entities
< MODULE.code
< MODULE.proper_regions
< MODULE.in_regions
< MODULE.out_regions
\end{PipsMake}
The following loop in Subroutine \verb+inout+ cannot be parallelized legally
because Subroutine \verb+foo+ uses a static variable, \verb+y+. However,
\Pips{} will display this loop as (potentially) parallel if the
\verb+in_out+ option is selected for use-def chain computation. Remember
that IN/OUT regions require MUST regions to obtain interesting results
(see Section~\ref{subsubsection-in-regions}).
\noindent
\verb! subroutine inout(a,n)!\\
\verb! real a(n)!\\
\verb! !\\
\verb! do i = 1, n!\\
\verb! call foo(a(i))!\\
\verb! enddo!\\
\verb! !\\
\verb! end!\\
\verb! !\\
\verb! subroutine foo(x)!\\
\verb! save y!\\
\verb! !\\
\verb! y = x!\\
\verb! x = x + y!\\
\verb! !\\
\verb! end!\\
\subsection{Chain Properties}
\subsubsection{Add use-use Chains}
\index{KEEP\_READ\_READ\_DEPENDENCE}
It is possible to put use-use dependence arcs in the dependence graph.
This is useful for estimation of cache memory traffic and of
communication for distributed memory machine (e.g. you can parallelize
only communication free loops). Beware of use-use dependence on scalar
variables. You might expect scalars to be broadcasted and/or replicated
on each processor but they are not handled that way by the
parallelization process unless you manage to have them
declared private with respect to all enclosing loops.
This feature is not supported by PIPS user interfaces. Results may be
hard to interpret. It is useful to print the dependence graph.
\begin{PipsProp}{KEEP_READ_READ_DEPENDENCE}
KEEP_READ_READ_DEPENDENCE FALSE
\end{PipsProp}
\subsubsection{Remove Some Chains}
\index{CHAINS\_MASK\_EFFECTS}
\index{CHAINS\_DATAFLOW\_DEPENDENCE\_ONLY}
It is possible to mask effects on local variables in loop bodies. This
is dangerous with current version of Allen \& Kennedy which assumes that
all the edges are present, the ones on private variables being
partially ignored but for loop distribution. In other words, this
property should always be set to \verb+false+.
\begin{PipsProp}{CHAINS_MASK_EFFECTS}
CHAINS_MASK_EFFECTS FALSE
\end{PipsProp}
It also is possible to keep only true data-flow (Def -- Use) dependences in
the dependence graph. This was an attempt at mimicking the effect of
direct dependence analysis and at avoiding privatization. However, {\em
direct} dependence analysis is not implemented in the standard tests and
spurious def-use dependence arcs are taken into account.
\begin{PipsProp}{CHAINS_DATAFLOW_DEPENDENCE_ONLY}
CHAINS_DATAFLOW_DEPENDENCE_ONLY FALSE
\end{PipsProp}
These last two properties are not consistent with PIPS current development
(1995/96). It is assumed that {\em all} dependence arcs are present in the
dependence graph. Phases using the latter should be able to filter out
irrelevant arcs, e.g. pertaining to privatized variables.
\section{Dependence Graph (DG)}
\label{subsection-dependence-graph}
\index{DG}
\index{Dependence Graph}
\begin{PipsPass}{dg}
The dependence graph is used primarily by the parallelization
algorithms. A dependence graph is a refinement of use-def chains
(Section~\ref{subsection-chains}). It is {\em location}-based and not
{\em value}-based.
%See Section~\ref{subsection-array-data-flow-graph}
%for information about \Pips{} value-based dependence graph, \textsc{Feautrier}'s
%DFG.
There are several ways to compute a dependence graph. Some of them are
fast (\textsc{Banerjee}'s one for instance) but provide poor results, others
might be slower (R\'emi Triolet's one for instance) but produce better
results.
Three different dependence tests are available, all based on
\textsc{Fourier}-\textsc{Motzkin} elimination improved with a
heuristics for the integer domain. The \verb+fast+ version uses
subscript expressions only (unless convex array regions were used to compute
use-def chains, in which case regions are used instead). The
\verb+full+ version uses subscript expressions and loop bounds. The
\verb+semantics+ version uses subscript expressions and preconditions
(see~\ref{subsection-semantics-analysis}).
Note that, for interprocedural parallelization, precise array regions
only are used by the fast dependence test if the proper kind of
use-def chains has been previously selected (see
Section~\ref{subsubsection-read-write-region-based-chains}).
There are several kinds of dependence graphs. Most of them share the
same overall data structure: a graph with labels on arcs and vertices.
usually, the main differences are in the labels that decorate arcs;
for instance, \textsc{Kennedy}'s algorithm requires dependence levels (which
loop actually creates the dependence) while algorithms originated from
CSRD prefer DDVs (relations between loop indices when the dependence
occurs). Dependence cones introduced in~\cite{Iri87,IT87a,IT87b,IT88}
are even more precise~\cite{YAI94}.
The computations of dependence level and dependence cone~\cite{Yan93} are
both implemented in \Pips{}. DDV's are not computed. Currently, only
dependence levels are exploited by parallelization algorithms.
The dependence graph can be printed with or without filters (see
Section~\ref{subsection-dependence-graph-file}). The standard
dependence graph includes all arcs taken into account by the
parallelization process (\textsc{Allen} \&
\textsc{Kennedy}~\cite{AK87}), except those that are due to scalar
private variables and that impact the distribution process only. The
loop carried dependence graph does not include intra-iteration
dependences and is a good basis for iteration scheduling. The whole
graph includes all arcs, but input dependence arcs.
It is possible to gather some statistics about dependences by turning
on property \PipsPropRef{RICEDG_PROVIDE_STATISTICS} (more details in the
\PROPERTIES{}). A Shell script from \Pips{} utilities,
\verb/print-dg-statistics/, can be used in combination to extract the
most relevant information for a whole program.
During the parallelization phases, is is possible to ignore arcs
related to states of the libc, such as the heap memory management,
because thread-safe libraries do perform the updates within critical
sections. But these arcs are part of the use-def chains and of the
dependence graph. If they were removed instead of being ignored,
use-def elimination would remove all \verb/free/ statements.
The main contributors for the design and development of dependence
analysis are R\'emi \textsc{Triolet}, Fran\c{c}ois \textsc{Irigoin} and Yi-qing
\textsc{Yang}~\cite{Yan93}. The code was improved by Corinne
\textsc{Ancourt} and B\'eatrice \textsc{Creusillet}.
\end{PipsPass}
\subsection{Menu for Dependence Tests}
\label{subsubsection-menu-for-dependence-tests}
\begin{PipsMake}
alias dg 'Dependence Test'
alias rice_fast_dependence_graph 'Preconditions Ignored'
alias rice_full_dependence_graph 'Loop Bounds Used'
alias rice_semantics_dependence_graph 'Preconditions Used'
alias rice_regions_dependence_graph 'Regions Used'
\end{PipsMake}
\subsection{Fast Dependence Test}
\label{subsubsection-fast-dependence-test}
\index{dependence test!fast}
\begin{PipsPass}{rice_fast_dependence_graph}
Use subscript expressions only, unless convex array regions were used to compute
use-def chains, in which case regions are used instead. {\tt
rice\_regions\_dependence\_graph} is a synonym for this rule, but emits a
warning if {\tt region\_chains} is not selected.
\end{PipsPass}
\begin{PipsMake}
rice_fast_dependence_graph > MODULE.dg
< PROGRAM.entities
< MODULE.code
< MODULE.chains
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Full Dependence Test}
\label{subsubsection-full-dependence-test}
\index{dependence test!full}
\begin{PipsPass}{rice_full_dependence_graph}
Use subscript expressions and loop bounds.
\end{PipsPass}
\begin{PipsMake}
rice_full_dependence_graph > MODULE.dg
< PROGRAM.entities
< MODULE.code
< MODULE.chains
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Semantics Dependence Test}
\label{subsubsection-semantics-dependence-test}
\index{dependence test!semantics}
\begin{PipsPass}{rice_semantics_dependence_graph}
Uses subscript expressions and preconditions
(see~\ref{subsection-semantics-analysis}).
\end{PipsPass}
\begin{PipsMake}
rice_semantics_dependence_graph > MODULE.dg
< PROGRAM.entities
< MODULE.code
< MODULE.chains
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Dependence Test with Convex Array Regions}
\label{subsubsection-regions-dependence-test}
\index{dependence test!regions}
\begin{PipsPass}{rice_regions_dependence_graph}
Synonym for {\tt rice\_fast\_dependence\_graph}, except that it emits a
warning when {\tt region\_chains} is not selected.
\end{PipsPass}
\begin{PipsMake}
rice_regions_dependence_graph > MODULE.dg
< PROGRAM.entities
< MODULE.code
< MODULE.chains
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Dependence Properties (Ricedg)}
\index{Dependence Test}
% Module code and list of called module names.
\subsubsection{Dependence Test Selection}
\index{Dependence Test}
\index{DEPENDENCE\_TEST}
This property seems to be now obsolete. The dependence test choice is
now controlled directly and only by rules in \Pipsmake{}. The procedures
called by these rules may use this property. Anyway, it is useless to
set it manually.
\begin{PipsProp}{DEPENDENCE_TEST}
DEPENDENCE_TEST "full"
\end{PipsProp}
\subsubsection{Statistics}
\index{Dependence test statistics}
\index{Statistics (Dependence test)}
\index{RICEDG\_PROVIDE\_STATISTICS\ FALSE}
\index{RICEDG\_STATISTICS\_ALL\_ARRAYS}
Provide the following counts during the dependence test. There are three
parts: numbers of dependencies and independences (fields 1-10),
dimensions of referenced arrays and dependence natures (fields 11-25)
and the same information for constant dependencies (fields 26-40),
decomposition of the dependence test in elementary steps (fields 41-49),
use and complexity of Fourier-Motzkin's pair-wise elimination (fields
50, 51 and 52-68).
\begin{itemize}
\item[1] array reference pairs, i.e. number of tests effected
(used to be the number of use-def, def-use and def-def pairs on arrays);
\item[2] number of independences found (on array reference pairs);
{\bf Note:} field 1 minus field 2 is the number of array
dependencies.
\item[3] numbers of loop independent dependences between references
in the same statement (not useful for program transformation
and parallelization if statements are preserved); it should
be subtracted from field 2 to compare results with other
parallelizers;
\item[4] numbers of constant dependences;
\item[5] numbers of exact dependences;
{\bf Note:} field 5 must be greater or equal to field 4.
\item[6] numbers of inexact dependences involved only by the
elimination of equation;
\item[7] numbers of inexact dependences involved only by the F-M
elimination;
\item[8] numbers of inexact dependences involved by both elimination of
equation and F-M elimination;
{\bf Note:} the sum of fields 5 to 8 and field 2 equals field 1
\item[9] number of dependences among scalar variables;
\item[10] numbers of dependences among loop index variables;
\item[11-40] dependence types detail table with the dimensions [5][3]
and constant dependence detail table with the
dimensions [5][3]; the first index is the array dimension
(from 0 to 4 - no larger arrays has ever been found); the
second index is the dependence nature (1: d-u, 2: u-d, 3: d-d);
both arrays are flatten according to C rule as 5 sequences of
3 natures;
{\bf Note:} the sum of fields 11 to 25 should be equal to
the sum of field 9 and 2 minus field 1.
{\bf Note:} the fields 26 to 40 must be less than or equal to
the corresponding fields 11 to 25
\item[41] numbers of independences found by the test of constant;
\item[42] numbers of independences found by the GCD test;
\item[43] numbers of independences found by the normalize test;
\item[44] numbers of independences found by the lexico-positive test
for constant Di variables;
\item[45] numbers of independences found during the projection on Di
variables by the elimination of equation;
\item[46] numbers of independences found during the projection on Di
variables by the Fourier-Motzkin's elimination;
\item[47] numbers of independences found during the test of
faisability of Di sub-system by the elimination of equation;
\item[48] numbers of independences found during the test of
faisability of Di sous-system by the Fourier-Motzkin's
elimination;
\item[49] numbers of independences found by the test of lexico-positive
for Di sub-system;
{\bf Note:} the sum of fields 41 to 49 equals field 2
\item[50] total number of Fourier-Motzkin's pair-wise eliminations
used;
\item[51] number of Fourier-Motzkin's pair-wise elimination
in which the system size doesn't augment after the elimination;
\item[52-68] complexity counter table of dimension [17]. The
complexity of one projection by F-M is the product of the
number of positive inequalities and the number of negatives
inequalities that contain the eliminated variable. This
is an histogram of the products. Products which are less than
or equal to 4
imply that the total number of inequalities does not increase.
So if no larger product exists, field 50 and 51 must be equal.
\end{itemize}
The results are stored in the current workspace in MODULE.resulttestfast,
MODULE.resultesttestfull, or MODULE.resulttestseman according to the
test selected.
\begin{PipsProp}{RICEDG_PROVIDE_STATISTICS}
RICEDG_PROVIDE_STATISTICS FALSE
\end{PipsProp}
Provide the statistics above and count all array reference pairs
including these involved in call statement.
\begin{PipsProp}{RICEDG_STATISTICS_ALL_ARRAYS}
RICEDG_STATISTICS_ALL_ARRAYS FALSE
\end{PipsProp}
\subsubsection{Algorithmic Dependences}
\index{Def-Use Chains}
\index{RICE\_DATAFLOW\_DEPENDENCE\_ONLY}
This property can be set to only take into account true flow
dependences (Def -- Use) during the computation of SCC by the
Allen\&Kennendy algorithm.
Note that this is different from the
CHAINS\_DATAFLOW\_DEPENDENCE\_ONLY property, which is set to compute a
partial data dependence graph.
Warning: if set, this property may potentially yields incorrect parallel
code because dynamic single assignment is not guaranteed.
\begin{PipsProp}{RICE_DATAFLOW_DEPENDENCE_ONLY}
RICE_DATAFLOW_DEPENDENCE_ONLY FALSE
\end{PipsProp}
\subsubsection{Optimization}
\index{COMPUTE\_ALL\_DEPENDENCES}
The default option is to compute the dependence graph only for loops
which can be parallelized using Allen \& Kennedy algorithm. However it
is possible to compute the dependences in all cases, even for loop
containing test, goto, etc... by setting this option to TRUE.
Of course, this information is not used by the parallelization phase
which is restricted to loops meeting the A\&K conditions. By the way,
the hierarchical control flow graph is not exploited either by the
parallelization phase.
\begin{PipsProp}{COMPUTE_ALL_DEPENDENCES}
COMPUTE_ALL_DEPENDENCES FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% FLINTER
\section{Flinter}
\label{subsection-flinter}
\begin{PipsPass}{flinter}
Function \PipsPassRef{flinter} performs some intra and interprocedural checks
about formal/actual argument pairs, use of COMMONs,...
\end{PipsPass}
It was developed by
Laurent \textsc{Aniort} and Fabien \textsc{Coelho}. Ronan \textsc{Keryell}
added the uninitialized variable checking.
\begin{PipsMake}
alias flinted_file 'Flint View'
flinter > MODULE.flinted_file
< PROGRAM.entities
< MODULE.code
< CALLEES.code
< MODULE.proper_effects
< MODULE.chains
\end{PipsMake}
In the past, \PipsPassRef{flinter} used to require \texttt{MODULE.summary\_effects}
to check the parameter passing modes and to make sure that no module would
attempt an assignment on an expression. However, this kind of bug is
detected by the effect analysis\dots{} which was required by flinter.
Resource \texttt{CALLEES.code} is not explicitly required but it produces the
global symbols which function \PipsPassRef{flinter} needs to check parameter lists.
\section{Loop Statistics}
Computes statistics about loops in module. It computes the number of
perfectly and imperfectly nested loops and gives their depths. And it gives
the number of nested loops which we can treat with our algorithm.
\begin{PipsMake}
loop_statistics > MODULE.stats_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Note: it does not seem to behave like a standard analysis, associating
information to the internal representation. Instead, an ASCII file
seems to be created.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% SEMANTICS
\section{Semantics Analysis}
\label{subsection-semantics-analysis}
\index{Semantics Analysis}
\index{Analysis (Semantics)}
\Pips{} semantics analysis targets mostly integer scalar variables. It is a
two-pass process, with a bottom-up pass computing \PipsPassRef{transformers}, and
a top-down pass propagating \PipsPassRef{preconditions}. Transformers and
preconditions are specially powerful case of return and jump
functions~\cite{CCK86}. They abstract relations between program states
with polyhedra and encompass most standard interprocedural constant
propagations as well as most interval analyses. It is a powerful {\em
relational} symbolic analysis.
Unlike~\cite{CH78} their computations are based on \Pips{}
Hierarchical Control Flow Graph and on syntactic constructs instead of a
standard flow graph. The best presentation of this part of \Pips{} is
in~\cite{Iri92}.
A similar analysis is available in Parafrase-2~\cite{}. It handles {\em
polynomial} equations between scalar integer variables. SUIF~\cite{}
also performs some kind of semantics analysis.
The semantics analysis part of \Pips{} was designed and developed by
Fran\c{c}ois \textsc{Irigoin}.
\subsection{Transformers}
\label{subsubsection-transformers}
\index{Transformer}
\marginpar{RK: The following is hard to read without any example for someone
that knows nothing about PIPS... FI: do you want to have everything in this documentation?}
\begin{PipsPass}{transformers}
A transformer is an approximate relation between the symbolic initial
values of scalar variables and their values after the execution of a
statement, simple or compound (see~\cite{IJT92} and~\cite{Iri92}). In abstract
interpretation terminology, a transformer is an abstract command
linking the input abstract state of a statement and its output
abstract state.
By default, only integer scalar variables are analyzed, but properties
can be set to handle boolean, string and floating point scalar
variables\footnote{Floating point values are combined exactly, which
is not correct but still useful when dead code can be eliminated
according to some parameter value.} :
\PipsPropRef{SEMANTICS_ANALYZE_SCALAR_INTEGER_VARIABLES}
\PipsPropRef{SEMANTICS_ANALYZE_SCALAR_BOOLEAN_VARIABLES}
\PipsPropRef{SEMANTICS_ANALYZE_SCALAR_STRING_VARIABLES}
\PipsPropRef{SEMANTICS_ANALYZE_SCALAR_FLOAT_VARIABLES}
\PipsPropRef{SEMANTICS_ANALYZE_SCALAR_COMPLEX_VARIABLES}
\PipsPropRef{SEMANTICS_ANALYZE_SCALAR_POINTER_VARIABLES}
\PipsPropRef{SEMANTICS_ANALYZE_CONSTANT_PATH}
Transformers can be computed intraprocedurally by looking at each
function independently or they can be computed interprocedurally
starting with the leaves of the call tree\footnote{Recursive calls are
not handled. Hopefully, they are detected by \texttt{pipsmake} to
avoid looping forever.}.
Intraprocedural algorithms use \PipsPassRef{cumulated_effects} to handle
procedure calls correctly. In some respect, they are interprocedural
since call statements are accepted. Interprocedural algorithms use the
\PipsPassRef{summary_transformer} of the called procedures.
Fast algorithms use a very primitive non-iterative transitive closure
algorithm (two possible versions: flow sensitive or flow insensitive).
Full algorithms use a transitive closure algorithm based on vector
subspace (i.e. \emph{\`a la} K{\sc arr}~\cite{Kar76}) or one based on
the discrete derivatives~\cite{Iri05,ACI10}. The iterative fix point
algorithm for transformers (i.e. H{\sc albwachs}/C{\sc
ousot}~\cite{CH78} is implemented but not used because the results
obtained with transitive closure algorithms are faster and up-to-now
sufficient. Property \PipsPropRef{SEMANTICS_FIX_POINT_OPERATOR}
is set to select the transitive closure algorithm used.
Additional information, such as array declarations and array
references, can be used to improve transformers. See the property
documentation for:
\PipsPropRef{SEMANTICS_TRUST_ARRAY_DECLARATIONS}
\PipsPropRef{SEMANTICS_TRUST_ARRAY_REFERENCES}
Within one procedure, the transformers can be computed in forward
mode, using precondition information gathered along. Transformers can
also be recomputed once the preconditions are available. In both
cases, more precise transformers are obtained because the statement
can be better modelized using precondition information. For instance,
a non-linear expression can turn out to be linear because the values
of some variables are numerically known and can be used to simplify
the initial expression. See properties:
\PipsPropRef{SEMANTICS_RECOMPUTE_EXPRESSION_TRANSFORMERS}
\PipsPropRef{SEMANTICS_COMPUTE_TRANSFORMERS_IN_CONTEXT}
\PipsPropRef{SEMANTICS_RECOMPUTE_FIX_POINTS_WITH_PRECONDITIONS}
and phase \PipsPassRef{refine_transformers}.
Unstructured control flow graphs can lead to very long transformer computations, whose results are usually not interesting. Their sizes are limited by two properties:
\PipsPropRef{SEMANTICS_MAX_CFG_SIZE2}
\PipsPropRef{SEMANTICS_MAX_CFG_SIZE1}
discussed below.
Default value were set in the early nineties to obtain results fast
enough for live demonstrations. They have not been changed to preserve the
non-regression tests. However since 2005, processors are fast enough to use
the most precise options in all cases.
A transformer map contains a transformer for each statement of a
module. It is a mapping from statements to transformers (type
\texttt{statement\_mapping}, which is not a NewGen file). Transformers maps
are stored on and retrieved from disk by {\em pipsdbm}.
\end{PipsPass}
\subsubsection{Menu for Transformers}
\begin{PipsMake}
alias transformers 'Transformers'
alias transformers_intra_fast 'Quick Intra-Procedural Computation'
alias transformers_inter_fast 'Quick Inter-Procedural Computation'
alias transformers_intra_full 'Full Intra-Procedural Computation'
alias transformers_inter_full 'Full Inter-Procedural Computation'
alias transformers_inter_full_with_points_to 'Full Inter-Procedural with points-to Computation'
alias refine_transformers 'Refine Transformers'
\end{PipsMake}
\subsubsection{Fast Intraprocedural Transformers}
\begin{PipsPass}{transformers_intra_fast}
Build the fast intraprocedural transformers.
\end{PipsPass}
\begin{PipsMake}
transformers_intra_fast > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.proper_effects
\end{PipsMake}
\subsubsection{Full Intraprocedural Transformers}
\begin{PipsPass}{transformers_intra_full}
Build the improved intraprocedural transformers.
\end{PipsPass}
\begin{PipsMake}
transformers_intra_full > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.proper_effects
\end{PipsMake}
\subsubsection{Fast Interprocedural Transformers}
\begin{PipsPass}{transformers_inter_fast}
Build the fast interprocedural transformers.
\end{PipsPass}
\begin{PipsMake}
transformers_inter_fast > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.proper_effects
< PROGRAM.program_precondition
\end{PipsMake}
\subsubsection{Full Interprocedural Transformers}
\begin{PipsPass}{transformers_inter_full}
Build the improved interprocedural transformers (This should be used
as default option.).
\end{PipsPass}
\begin{PipsMake}
transformers_inter_full > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.proper_effects
< PROGRAM.program_precondition
\end{PipsMake}
\subsubsection{Full Interprocedural Transformers with points-to}
\begin{PipsPass}{transformers_inter_full_with_points_to}
Build the improved interprocedural transformers with points-to informations
\end{PipsPass}
\begin{PipsMake}
transformers_inter_full_with_points_to > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.points_to
< MODULE.cumulated_effects
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.proper_effects
< PROGRAM.program_precondition
\end{PipsMake}
\subsubsection{Refine Full Interprocedural Transformers}
\begin{PipsPass}{refine_transformers}
Rebuild the interprocedural transformers using interprocedural
preconditions. Intraprocedural preconditions are also used to refine all
transformers.
\end{PipsPass}
\begin{PipsMake}
refine_transformers > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.proper_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.summary_precondition
< PROGRAM.program_precondition
\end{PipsMake}
\begin{PipsPass}{refine_transformers_with_points_to}
Rebuild the interprocedural transformers using interprocedural
preconditions and points-to information. Intraprocedural preconditions are also used to refine all
transformers.
\end{PipsPass}
\begin{PipsMake}
refine_transformers_with_points_to > MODULE.transformers
< PROGRAM.entities
< MODULE.code
< MODULE.points_to
< MODULE.cumulated_effects
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.proper_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.summary_precondition
< PROGRAM.program_precondition
\end{PipsMake}
\subsubsection{Summary Transformer}
\label{subsubsection-summary-transformer}
\index{Transformer (Summary)}
\index{Summary Transformer}
\begin{PipsPass}{summary_transformer}
A summary transformer is an interprocedural version of the module
statement transformer, obtained by eliminating dynamic local,
a.k.a. stack allocated, variables. The filtering is based on the
module summary effects.
\end{PipsPass}
Note: each module has a UNIQUE top-level
statement.
A \PipsPassRef{summary_transformer} is of Newgen type \texttt{transformer}.
\begin{PipsMake}
summary_transformer > MODULE.summary_transformer
< PROGRAM.entities
< MODULE.transformers
< MODULE.summary_effects
\end{PipsMake}
\subsection{Preconditions}
\label{subsubsection-preconditions}
\index{Precondition}
\begin{PipsPass}{preconditions}
A precondition for a statement $s$ in a module $m$ is a predicate true
for every state reachable from the initial state of $m$, in which $s$
is executed. A precondition is of NewGen type "transformer" (see
\Pri{}) and preconditions is of type \verb+statement_mapping+.
Option \PipsPassRef{preconditions_intra} associates a precondition to each
statement, assuming that no information is available at the module entry
point.
Inter-procedural preconditions may be computed with {\em
intra}-procedural transformers but the benefit is not
clear. Intra-procedural preconditions may be computed with {\em
inter}-procedural transformers. This is faster that a full
interprocedural analysis because there is no need for a top-down
propagation of summary preconditions. This is compatible with code
transformations like \PipsPassRef{partial_eval},
\PipsPassRef{simplify_control} and
\PipsPassRef{dead_code_elimination}.
Since these two options for transformer and precondition computations are
independent and that \PipsPassRef{transformers_inter_full} and
\PipsPassRef{preconditions_inter_full} must be both (independently) selected
to obtain the best possible results. These two options are recommended.
% Known bug: the postcondition of a loop, computed with the {\em full}
% option for transformers and preconditions is wrong because the last
% increment of the index is not performed. Besides the exit condition is
% not added (yet).
\end{PipsPass}
\subsubsection{Initial Precondition or Program Precondition}
\label{subsubsection-initial-precs}
\index{Precondition (Initial)}
\index{Initial Precondition}
All \texttt{DATA} initializations contribute to the global initial state
of the program. The contribution of each module is computed independently.
Note that variables statically initialized behave as static variables and
are preserved between calls according to Fortran standard. The module
initial states are abstracted by an initial precondition based on integer
scalar variables only.
Note: To be extended to handle C code. To be extended to handle properly
unknown modules.
\begin{PipsMake}
initial_precondition > MODULE.initial_precondition
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
All initial preconditions, including the initial precondition for the
main, are combined to define the program precondition which is an
abstraction of the program initial state.
\begin{PipsMake}
program_precondition > PROGRAM.program_precondition
< PROGRAM.entities
< ALL.initial_precondition
\end{PipsMake}
The program precondition can only be used for the initial state of the
main procedure. Although it appears below for all interprocedural analyses
and it always is computed, it only is used when a main procedure is
available.
\subsubsection{Intraprocedural Summary Precondition}
\index{Intraprocedural Summary Precondition}
\index{Precondition (Summary)}
\begin{PipsPass}{intraprocedural_summary_precondition}
A summary precondition is of type "transformer", but the argument list
must be empty as it is a simple predicate on the initial state. So in fact
it is a state predicate.
\end{PipsPass}
The intraprocedural summary precondition uses DATA statement for the main
module and is the TRUE constant for all other modules.
\begin{PipsMake}
intraprocedural_summary_precondition > MODULE.summary_precondition
< PROGRAM.entities
< MODULE.initial_precondition
\end{PipsMake}
Interprocedural summary preconditions can be requested instead. They are
not described in the same section in order to introduce the summary
precondition resource at the right place in \verb/pipsmake.rc/.
No menu is declared to select either intra- or interprocedural summary
preconditions.
\subsubsection{Interprocedural Summary Precondition}
\index{Summary Precondition}
\index{Precondition (Summary)}
By default, summary preconditions are computed intraprocedurally. The
interprocedural option must be explicitly activated.
\begin{PipsPass}{interprocedural_summary_precondition}
An interprocedural summary precondition for a module is derived from all
its call sites. Of course, preconditions must be known for all its
callers' statements. The summary precondition is the convex hull of all
call sites preconditions, translated into a proper environment which is
{\em not} necessarily the module's frame. Because of {\em invisible}
global and static variables and aliasing, it is difficult for a caller to
know which variables might be used by the caller to represent a given
memory location. To avoid the problem, the current summary precondition is
always translated into the {\em caller}'s frame. So each module must first
translate its summary precondition, when receiving it from the resource
manager ({\em pipsdbm}) before using it.
\end{PipsPass}
Note: the previous algorithm was based on a on-the-fly reduction by
convex hull. Each time a call site was encountered while computing a
module preconditions, the callee's summary precondition was updated. This
old scheme was more efficient but not compatible with program
transformations because it was impossible to know when the summary
preconditions of the modules had to be reset to the infeasible
(a.k.a. empty) precondition.
An infeasible precondition means that the module is never called although
a main is present in the workspace. If no main module is available, a TRUE
precondition is generated. Note that, in both cases, the impact of static
initializations propagated by link edition is taken into account although
this is prohibited by the Fortran Standard which requires a BLOCKDATA
construct for such initializations. In other words, a module which is
never called has an impact on the program execution and its declarations
should not be destroyed.
\begin{PipsMake}
interprocedural_summary_precondition > MODULE.summary_precondition
< PROGRAM.entities
< PROGRAM.program_precondition
< CALLERS.preconditions
< MODULE.callers
\end{PipsMake}
\begin{PipsPass}{interprocedural_summary_precondition_with_points_to}
An interprocedural summary precondition for a module is derived from all
its call sites.
\end{PipsPass}
\begin{PipsMake}
interprocedural_summary_precondition_with_points_to > MODULE.summary_precondition
< PROGRAM.entities
< PROGRAM.program_precondition
< CALLERS.preconditions
< MODULE.callers
< MODULE.points_to
\end{PipsMake}
The following rule is obsolete. It is context sensitive and its results
depends on the history of commands performed on the workspace.
\begin{PipsMake}
summary_precondition > MODULE.summary_precondition
< PROGRAM.entities
< CALLERS.preconditions
< MODULE.callers
\end{PipsMake}
\subsubsection{Menu for Preconditions}
\begin{PipsMake}
alias preconditions 'Preconditions'
alias preconditions_intra 'Intra-Procedural Analysis'
alias preconditions_inter_fast 'Quick Inter-Procedural Analysis'
alias preconditions_inter_full 'Full Inter-Procedural Analysis'
alias preconditions_intra_fast 'Fast intra-Procedural Analysis'
\end{PipsMake}
\subsubsection{Intra-Procedural Preconditions}
\begin{PipsPass}{preconditions_intra}
Only build the preconditions in a module without any interprocedural
propagation. The fast version uses a fast but crude approximation of
preconditions for unstructured code.
\end{PipsPass}
\begin{PipsMake}
preconditions_intra > MODULE.preconditions
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.summary_effects
< MODULE.summary_transformer
< MODULE.summary_precondition
< MODULE.code
\end{PipsMake}
\begin{PipsMake}
preconditions_intra_fast > MODULE.preconditions
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.summary_effects
< MODULE.summary_transformer
< MODULE.summary_precondition
< MODULE.code
\end{PipsMake}
\subsubsection{Fast Inter-Procedural Preconditions}
\begin{PipsPass}{preconditions_inter_fast}
Option \PipsPassRef{preconditions_inter_fast} uses the module own precondition
derived from its callers as initial state value and propagates it
downwards in the module statement.
The {\em fast} versions use no fix-point operations for loops.
\end{PipsPass}
\begin{PipsMake}
preconditions_inter_fast > MODULE.preconditions
< PROGRAM.entities
< PROGRAM.program_precondition
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.summary_precondition
< MODULE.summary_effects
< CALLEES.summary_effects
< MODULE.summary_transformer
\end{PipsMake}
\subsubsection{Full Inter-Procedural Preconditions}
\begin{PipsPass}{preconditions_inter_full}
Option \PipsPassRef{preconditions_inter_full} uses the module own precondition
derived from its callers as initial state value and propagates it
downwards in the module statement.
The {\em full} versions use fix-point operations for loops.
\end{PipsPass}
\begin{PipsMake}
preconditions_inter_full > MODULE.preconditions
< PROGRAM.entities
< PROGRAM.program_precondition
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.summary_precondition
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.summary_transformer
\end{PipsMake}
\begin{PipsPass}{preconditions_inter_full_with_points_to}
Option \PipsPassRef{preconditions_inter_full_with_points_to} uses the
module own precondition derived from its callers as initial state
value and propagates it downwards in the module statement.
\end{PipsPass}
\begin{PipsMake}
preconditions_inter_full_with_points_to > MODULE.preconditions
< PROGRAM.entities
< PROGRAM.program_precondition
< MODULE.code
< MODULE.points_to
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.summary_precondition
< MODULE.summary_effects
< CALLEES.summary_transformer
< MODULE.summary_transformer
\end{PipsMake}
\subsection{Total Preconditions}
\label{subsubsection-ototal-preconditions}
\index{Total Precondition}
\begin{PipsPass}{total preconditions}
Total preconditions are interesting to optimize the nominal behavior
of a terminating application. It is assumed that the application ends
in the main procedure. All other exits, aborts or stops, explicit or
implicit such as buffer overflows and zero divide and null pointer
dereferencing, are considered exceptions. This also applies at the
module level. Modules nominally return. Other control flows are
considered exceptions. Non-terminating modules have an empty total
precondition\footnote{Non-termination conditions could also be
propagated backwards to provide an over-approximation of the
conditions under which an application never terminates,
i.e. conditions for liveness.}. The standard preconditions can be
refined by anding with the total preconditions to get information
about the nominal behavior. Similar sources of increased accuracy are
the array declarations and the array references, which can be
exploited directly with properties described in
section~\ref{subsubsection:array-declarations-and-accesses}. These two
properties should be set to true whenever possible.
Hence, a total precondition for a statement $s$ in a module $m$ is a predicate true
for every state from which the final state of $m$, in which $s$
is executed, is reached. It is an over-approximation of the theoretical
total precondition. So, if the predicate is false, the final control state
cannot be reached. A total precondition is of NewGen type "transformer" (see
\Pri{}) and total\_preconditions is of type \verb+statement_mapping+.
The relationship with continuations (see
Section~\ref{subsection-continuation-conditions}) is not clear. Total
preconditions should be more general but no must version exist.
Option \PipsPassRef{total_preconditions_intra} associates a precondition to each
statement, assuming that no information is available at the module return
point.
Inter-procedural total preconditions may be computed with {\em
intra}-procedural transformers but the benefit is not
clear. Intra-procedural total preconditions may be computed with {\em
inter}-procedural transformers. This is faster than a full
interprocedural analysis because there is no need for a top-down
propagation of summary total postconditions.
Since these two options for transformer and total precondition computations are
independent, \PipsPassRef{transformers_inter_full} and
\PipsPassRef{total_preconditions_inter} must be both (independently) selected
to obtain the best possible results.
\paragraph{Status:}
This is a set of experimental passes. The intraprocedural part is
implemented. The interprocedural part is not implemented yet, waiting
for an expressed practical interest. Neither C for loops nor repeat
loops are supported.
\end{PipsPass}
\subsubsection{Menu for Total Preconditions}
\begin{PipsMake}
alias total_preconditions 'Total Preconditions'
alias total_preconditions_intra 'Total Intra-Procedural Analysis'
alias total_preconditions_inter 'Total Inter-Procedural Analysis'
\end{PipsMake}
\subsubsection{Intra-Procedural Total Preconditions}
\begin{PipsPass}{total_preconditions_intra}
Only build the total preconditions in a module without any interprocedural
propagation. No specific condition must be met when reaching a RETURN statement.
\end{PipsPass}
\begin{PipsMake}
total_preconditions_intra > MODULE.total_preconditions
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.summary_effects
< MODULE.summary_transformer
< MODULE.code
\end{PipsMake}
\subsubsection{Inter-Procedural Total Preconditions}
\begin{PipsPass}{total_preconditions_inter}
Option \PipsPassRef{total_preconditions_inter} uses the module own total postcondition
derived from its callers as final state value and propagates it
backwards in the module statement. This total module postcondition must be
true when the RETURN statement is reached.
\end{PipsPass}
\begin{PipsMake}
total_preconditions_inter > MODULE.total_preconditions
< PROGRAM.entities
< PROGRAM.program_postcondition
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.summary_total_postcondition
< MODULE.summary_effects
< CALLEES.summary_effects
< MODULE.summary_transformer
\end{PipsMake}
The program postcondition is only used for the main module.
\subsubsection{Summary Total Precondition}
\index{Summary Total Precondition}
\index{Total Precondition (Summary)}
The summary total precondition of a module is the total precondition of
its statement limited to information observable by callers, just like a
summary transformer (see Section~\ref{subsubsection-summary-transformer}).
A summary total precondition is of type "transformer".
\begin{PipsMake}
summary_total_precondition > MODULE.summary_total_precondition
< PROGRAM.entities
< CALLERS.total_preconditions
\end{PipsMake}
\subsubsection{Summary Total Postcondition}
\index{Summary Total Postcondition}
\index{Total Postcondition (Summary)}
A final postcondition for a module is derived from all its call
sites. Of course, total postconditions must be known for all its callers'
statements. The summary total postcondition is the convex hull of all call
sites total postconditions, translated into a proper environment which is {\em
not} necessarily the module's frame. Because of {\em invisible} global
and static variables and aliasing, it is difficult for a caller to know which
variables might be used by the caller to represent a given memory
location. To avoid the problem, the current summary total postcondition is
always translated into the {\em caller}'s frame. So each module must
first translate its summary total postcondition, when receiving it from the
resource manager ({\em pipsdbm}) before using it.
A summary total postcondition is of type "transformer".
\begin{PipsMake}
summary_total_postcondition > MODULE.summary_total_postcondition
< PROGRAM.entities
< CALLERS.total_preconditions
< MODULE.callers
\end{PipsMake}
\subsubsection{Final Postcondition}
\label{subsubsection-final-postcondition}
\index{Postcondition (Final)}
\index{Final Postcondition}
The program postcondition cannot be derived from the source code. It
should be defined explicitly by the user. By default, the predicate is
always true. But you might want some variables to have specific values,
e.g. \verb+KMAX==1+, or signs,\verb+KMAX>1+ or relationships
\verb+KMAX>JMAX+.
\begin{PipsMake}
program_postcondition > PROGRAM.program_postcondition
\end{PipsMake}
\subsection{Semantic Analysis Properties}
\label{subsection-semantic-analysis}
\index{Semantics}
\index{Precondition}
\index{Transformer}
\subsubsection{Value types}
\index{SEMANTICS\_ANALYZE\_SCALAR\_INTEGER\_VARIABLES}
\index{SEMANTICS\_ANALYZE\_SCALAR\_BOOLEAN\_VARIABLES}
\index{SEMANTICS\_ANALYZE\_SCALAR\_STRING\_VARIABLES}
\index{SEMANTICS\_ANALYZE\_SCALAR\_FLOAT\_VARIABLES}
\index{SEMANTICS\_ANALYZE\_SCALAR\_COMPLEX\_VARIABLES}
\index{SEMANTICS\_ANALYZE\_SCALAR\_POINTER\_VARIABLES}
\index{SEMANTICS\_ANALYZE\_CONSTANT\_PATH}
By default, the semantic analysis is restricted to scalar integer
variables as they are key variables to understand scientific code
behavior. However it is possible to analyze scalar variables with other
data types. Fortran LOGICAL variables are represented as 0/1
integers. Character string constants and floating point constants are
represented as undefined values.
The analysis is thus limited to constant propagation for character strings
and floating point values whereas integer, boolean and pointer variables are
processed with a relational analysis.
Character string constants of fixed maximal length could be translated
into integers but the benefit is not yet assessed because they are not
much used in the benchmark and commercial applications we have studied.
The risk is to increase significantly the number of overflows encountered
during the analysis.
For the pointer analysis, it's strongly recommended to activate
\PipsPassRef{proper_effects_with_points_to} before performing this analysis.
In interprocedural analysis, or in presence of formal parameter, to performe
the pointer analysis, it's strongly recommended to set
\PipsPropRef{SEMANTICS_ANALYZE_CONSTANT_PATH} at TRUE.
\PipsPropRef{SEMANTICS_ANALYZE_CONSTANT_PATH} can also serve to analyse the structures?
\begin{PipsProp}{SEMANTICS_ANALYZE_SCALAR_INTEGER_VARIABLES}
SEMANTICS_ANALYZE_SCALAR_INTEGER_VARIABLES TRUE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_ANALYZE_SCALAR_BOOLEAN_VARIABLES}
SEMANTICS_ANALYZE_SCALAR_BOOLEAN_VARIABLES FALSE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_ANALYZE_SCALAR_STRING_VARIABLES}
SEMANTICS_ANALYZE_SCALAR_STRING_VARIABLES FALSE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_ANALYZE_SCALAR_FLOAT_VARIABLES}
SEMANTICS_ANALYZE_SCALAR_FLOAT_VARIABLES FALSE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_ANALYZE_SCALAR_COMPLEX_VARIABLES}
SEMANTICS_ANALYZE_SCALAR_COMPLEX_VARIABLES FALSE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_ANALYZE_SCALAR_POINTER_VARIABLES}
SEMANTICS_ANALYZE_SCALAR_POINTER_VARIABLES FALSE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_ANALYZE_CONSTANT_PATH}
SEMANTICS_ANALYZE_CONSTANT_PATH FALSE
\end{PipsProp}
\subsubsection{Array Declarations and Accesses}
\label{subsubsection:array-declarations-and-accesses}
\index{SEMANTICS\_TRUST\_ARRAY\_DECLARATIONS}
\index{SEMANTICS\_TRUST\_ARRAY\_REFERENCES}
For every module, array declaration are assumed to be correct with respect
to the standard: the upper bound must be greater than or equal to the
lower bound. When implicit, the lower bound is one. The star upper bound
is neglected.
This property is turned off by default because it might slow down PIPS
quite a lot without adding any useful information because loop bounds are
usually different from array bounds.
\begin{PipsProp}{SEMANTICS_TRUST_ARRAY_DECLARATIONS}
SEMANTICS_TRUST_ARRAY_DECLARATIONS FALSE
\end{PipsProp}
For every module, array references are assumed to be correct with respect
to the declarations: the subscript expressions must have values lower than
or equal to the upper bound and greater than or equal to the lower bound.
This property is turned off by default because it might slow down PIPS
quite a lot without adding any useful information.
\begin{PipsProp}{SEMANTICS_TRUST_ARRAY_REFERENCES}
SEMANTICS_TRUST_ARRAY_REFERENCES FALSE
\end{PipsProp}
\subsubsection{Type Information}
\label{subsubsection:type-information}
\index{SEMANTICS\_USE\_TYPE\_INFORMATION}
Type information for integer variables is ignored by default. The
behavior of natural integer is assumed and no wrap-around is assumed
to ever happen. The properties described here could as well be named:
\texttt{SEMANTICS\_ASSUME\_NO\_INTEGER\_OVERFLOW}
Type range information is difficult to turn into useful
information. It implies some handling of wrap-around behaviors. It is
likely to cause lots of overflows with \texttt{int} and \texttt{long
int} variables. It should be used for \texttt{unsigned char} and
\texttt{unsigned short int} only with the current implementation.
This is still an experimental development. By default this property is
not set, and it should only be set by \PIPS{} developpers.
This property is turned off by default because it might slow down PIPS
quite a lot without adding any useful information. It is also turned
off because it is experimental and should only be used by developpers.
\begin{PipsProp}{SEMANTICS_USE_TYPE_INFORMATION}
SEMANTICS_USE_TYPE_INFORMATION FALSE
\end{PipsProp}
Type information can also be used only when computing transformers or
when computing preconditions:
\begin{PipsProp}{SEMANTICS_USE_TYPE_INFORMATION_IN_TRANSFORMERS}
SEMANTICS_USE_TYPE_INFORMATION_IN_TRANSFORMERS FALSE
\end{PipsProp}
\begin{PipsProp}{SEMANTICS_USE_TYPE_INFORMATION_IN_PRECONDITION}
SEMANTICS_USE_TYPE_INFORMATION_IN_PRECONDITIONS FALSE
\end{PipsProp}
It is not clear why you would like to assume overflows when computing
transformers and not when computing preconditions, but the opposite
makes sense.
Note that simple statements such as \texttt{i++} have no precise
convex transformer because of the wrap-around to 0. Assuming the type
declaration \texttt{unsigned char i}, the transformer maps the new
value of \texttt{i} to the interval \texttt{[0..256]}.
If standard transformers are used, the variable values defined by the
integer preconditions must be remapped in the type interval $\lambda$
using a modulo definition. For instance, Value v is defined as $v =
\lambda v_1 + v_2$, $v$ and $v_1$ are projected and $v_2$ is renamed
$v$.
Each time a precondition is used in to compute a transformer, it must
be normalized according to its type, even when the condition happens
to be found without precondition, as a test condition or a loop bound.
For instance, in the example below:
\begin{verbatim}
void foo(unsigned char i, unsigned char j) {
if(i MODULE.path_transformer_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
The next properties are used by Phase \texttt{path\_transformer} to
label the two statements $S_{begin}$ and $S_{end}$.
\begin{PipsProp}{PATH_TRANSFORMER_BEGIN}
PATH_TRANSFORMER_BEGIN "sb"
\end{PipsProp}
\begin{PipsProp}{PATH_TRANSFORMER_END}
PATH_TRANSFORMER_END "se"
\end{PipsProp}
The next property is used to allow an empty path or not which is necessary for the test
of dependence. If its value is false, we return an empty transformer
for an empty path. Otherwise, an identity transformer is returned.
\begin{PipsProp}{IDENTITY_EMPTY_PATH_TRANSFORMER}
IDENTITY_EMPTY_PATH_TRANSFORMER TRUE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% CONTINUATIONS
\section{Continuation conditions}
\label{subsection-continuation-conditions}
Continuation conditions are attached to each statement. They represent the
conditions under which the program will not stop in this statement. Under-
and over-approximations of these conditions are computed.
\begin{PipsMake}
continuation_conditions > MODULE.must_continuation
> MODULE.may_continuation
> MODULE.must_summary_continuation
> MODULE.may_summary_continuation
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< CALLEES.must_summary_continuation
< CALLEES.may_summary_continuation
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% COMPLEXITY
\section{Complexities}
\label{subsection-complexities}
\index{Complexity}
\begin{PipsPass}{complexities}
Complexities are symbolic approximations of the execution times of
statements. They are computed interprocedurally and based on polynomial
approximations of execution times. Non-polynomial execution times are
represented by {\em unknown} variables which are not free with respect
to the program variables. Thus non-polynomial expressions are equivalent
to polynomial expressions over a larger set of variables.
Probabilities for tests should also result in
unknown variables (still to be implemented). See~\cite{Zho94}.
A \verb+summary_complexity+ is the approximation of a module execution
times. It is translated and used at call sites.
Complexity estimation could be refined (i.e. the number of unknown
variables reduced) by using transformers to combine elementary
complexities using local states, rather than preconditions to combine
elementary complexities relatively to the module initial state. The same
options exist for region computation. The initial version~\cite{Pla90}
used the initial state for combinations. The new version~\cite{CI95}
delays evaluation of variable values as long as possible but does not
really use local states.
The first version of the complexity estimator was designed and
developed by Pierre \textsc{Berthomier}. It was restricted to intra-procedural
analysis. This first version was enlarged and validated on real code for
SPARC-2 machines by Lei Z{\sc hou}~\cite{Zho94}. Since, it has been modified
slightly by Fran\c{c}ois I{\sc rigoin}. For simple programs, complexity
estimation are strongly correlated with execution times. The estimations
can be used to see if program transformations are beneficial.
Known bugs: tests and while loops are not correctly handled because a
fixed probably of 0.5 is systematically assumed.
\end{PipsPass}
\subsection{Menu for Complexities}
\begin{PipsMake}
alias complexities 'Complexities'
alias uniform_complexities 'Uniform'
alias fp_complexities 'FLOPs'
alias any_complexities 'Any'
\end{PipsMake}
\subsection{Uniform Complexities}
\label{subsubsection-uniform-complexities}
\index{Uniform Complexity}
\index{Complexity (Uniform)}
\begin{PipsPass}{uniform_complexities}
Complexity estimation is based on a set of basic operations and fixed
execution times for these basic operation. The choice of the set is
critical but fixed. Experiments by Lei \textsc{Zhou} showed that it should be
enlarged. However, the basic times, which also are critical, are
tabulated. New sets of tables can easily be developed for new
processors.
Uniform complexity tables contain a unit execution time for all basic
operations. They nevertheless give interesting estimations for SPARC
SS-10, especially for -O2/-O3 optimized code.
\end{PipsPass}
\begin{PipsMake}
uniform_complexities > MODULE.complexities
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< CALLEES.summary_complexity
\end{PipsMake}
\subsection{Summary Complexity}
\label{subsubsection-summary-complexity}
\index{Summary Complexity}
\index{Complexity (Summary)}
\begin{PipsPass}{summary_complexity}
Local variables are eliminated from the complexity associated to the top
statement of a module in order to obtain the modules' summary complexity.
\end{PipsPass}
\begin{PipsMake}
summary_complexity > MODULE.summary_complexity
< PROGRAM.entities
< MODULE.code
< MODULE.complexities
\end{PipsMake}
\subsection{Floating Point Complexities}
\label{subsubsection-floating-point-complexities}
\index{Floating Point Complexity}
\index{Complexity (Floating Point)}
\begin{PipsPass}{fp_complexities}
Tables for floating point complexity estimation are set to 0 for
non-floating point operations, and to 1 for all floating point
operations, including intrinsics like \texttt{SIN}.
\end{PipsPass}
\begin{PipsMake}
fp_complexities > MODULE.complexities
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< CALLEES.summary_complexity
\end{PipsMake}
\begin{PipsPass}{any_complexities}
This enables the default specification within the properties to
be considered.
\end{PipsPass}
\begin{PipsMake}
any_complexities > MODULE.complexities
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< CALLEES.summary_complexity
\end{PipsMake}
\subsection{Complexity properties}
\index{Complexity}
The following properties control the static estimation of dynamic code
execution time.
\subsubsection{Debugging}
\index{Debug (Complexity)}
\index{COMPLEXITY\_TRACE\_CALLS}
\index{COMPLEXITY\_INTERMEDIATES}
\index{COMPLEXITY\_PRINT\_COST\_TABLE}
Trace the walk across a module's internal representation:
\begin{PipsProp}{COMPLEXITY_TRACE_CALLS}
COMPLEXITY_TRACE_CALLS FALSE
\end{PipsProp}
Trace all intermediate complexities:
\begin{PipsProp}{COMPLEXITY_INTERMEDIATES}
COMPLEXITY_INTERMEDIATES FALSE
\end{PipsProp}
Print the complete cost table at the beginning of the execution:
\begin{PipsProp}{COMPLEXITY_PRINT_COST_TABLE}
COMPLEXITY_PRINT_COST_TABLE FALSE
\end{PipsProp}
The cost table(s) contain machine and compiler dependent information
about basic execution times, e.g. time for a load or a store.
\subsubsection{Fine Tuning}
\index{COMPLEXITY\_PARAMETERS}
\index{COMPLEXITY\_PRINT\_STATISTICS}
It is possible to specify a list of variables which must remain
literally in the complexity formula, although their numerical values
are known (this is OK) or although they have multiple unknown and
unrelated values during any execution (this leads to an incorrect
result).
Formal parameters and imported global variables are left unevaluated.
They have relatively high priority (FI: I do not understand this comment
by Lei).
This list should be empty by default (but is not for unknown historical
reasons):
\begin{PipsProp}{COMPLEXITY_PARAMETERS}
COMPLEXITY_PARAMETERS "IMAX LOOP"
\end{PipsProp}
Controls the printing of {\em accuracy} statistics:
\begin{itemize}
\item 0: do not prettyprint any statistics with complexities (to give
the user a false sense of accuracy and/or to avoid cluttering his/her
display); this is the default value;
\item 1: prettyprint statistics only for loop/block/test/unstr.
statements and not for basic statements, since they should not cause
accuracy problems;
\item 2: prettyprint statistics for all statements
\end{itemize}
\begin{PipsProp}{COMPLEXITY_PRINT_STATISTICS}
COMPLEXITY_PRINT_STATISTICS 0
\end{PipsProp}
\subsubsection{Target Machine and Compiler Selection}
\index{COMPLEXITY\_COST\_TABLE}
This property is used to select a set of basic execution times. These
times depend on the target machine, the compiler and the compilation
options used. It is shown in \cite{Zho94} that fixed basic times can be
used to obtain accurate execution times, if enough basic times are
considered, and if the target machine has a simple RISC processor. For
instance, it is not possible to use only one time for a register
load. It is necessary to take into account the nature of the variable,
i.e. formal parameter, dynamic variable, global variable, and the nature
of the access, e.g. the dimension of an accessed array. The cache can be
ignored an replacer by an average hit ratio.
Different set of elementary cost tables are available:
\begin{itemize}
\item \verb+all_1+: each basic operation cost is 1;
\item \verb+fp_1+: only floating point operations are taken into
account and have cost unit 1; all other operations have a null cost.
\end{itemize}
In the future, we might add a sparc-2 table...
The different elementary table names are defined in
\verb+complexity-local.h+. They presently are \verb+operation+,
\verb+memory+, \verb+index+, \verb+transcend+
and \verb+trigo+.
The different tables required are to be found in
\verb+$PIPS_LIBDIR/complexity/xyz+,
%% $
where \verb+xyz+ is specified by this property:
\begin{PipsProp}{COMPLEXITY_COST_TABLE}
COMPLEXITY_COST_TABLE "all_1"
\end{PipsProp}
\subsubsection{Evaluation Strategy}
\index{COMPLEXITY\_EARLY\_EVALUATION}
For the moment, we have designed two ways to solve the complexity
combination problem. Since symbolic complexity formulae use program
variables it is necessary to specify in which store they are
evaluated. If two complexity formulae are computed relatively to two
different stores, they cannot be directly added.
The first approach, which is implemented, uses the module initial store
as universal store for all formulae (but possibly for the complexity of
elementary statements). In some way, symbolic variable are evaluated as
early as possible as soon as it is known that they won't make it in the
module summary complexity.
This first method is easy to implement when the preconditions are available
but it has at least two drawbacks:
\begin{itemize}
\item if a variable is used in different places with the same unknown
value, each occurrence will be replaced by a different unknown value
symbol (the infamous \verb+UU_xx+ symbols in formulae).
\item since variables are replaced by numerical values as soon as
possible as early as possible, the user is shown a numerical execution
time instead of a symbolic formulae which would likely be more useful
(see property \PipsPropRef{COMPLEXITY_PARAMETERS}). This is especially true
with interprocedural constant propagation.
\end{itemize}
The second approach, which is not implemented, delay variable evaluation
as late as possible. Complexities are computed and given relatively to
the stores used by each statements. Two elementary complexities are combined
together using the earliest store. The two stores are related by a {\em
transformer} (see Section~\ref{subsection-semantic-analysis}). Such an
approach is used to compute {\tt MUST} regions as precisely as possible
(see Section~\ref{subsection-regions}).
A simplified version of the late evaluation was implemented. The initial
store of the procedure is the only reference store used as with the
early evaluation, but variables are not evaluated right away. They only
are evaluated when it is necessary to do so. This not an ideal solution,
but it is easy to implement and reduces considerably the number of
unknown values which have to be put in the formulae to have correct
results.
\begin{PipsProp}{COMPLEXITY_EARLY_EVALUATION}
COMPLEXITY_EARLY_EVALUATION FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ARRAY REGIONS
\section{Convex Array Regions}
\label{subsection-array-regions}
\index{Region}
\index{Array Region}
\begin{PipsPass}{regions}
Convex array regions are functions mapping a memory store onto a convex set
of array elements. They are used to represent the memory effects of
modules or statements. Hence, they are expressed with respect to the
initial store of the module or to the store immediately preceding the
execution of the statement they are associated with. The latter is now
standard in PIPS. Comprehensive information about convex array regions
and their associated algorithms is available in Creusillet's PhD Dissertation~\cite{Cre96}.
Apart from the array name and its dimension descriptors (or
$\phi$ variables), an array region contains three additional informations:
\begin{itemize}
\item The {\em type\/} of the region: \verb+READ+ (\verb+R+) or \verb+WRITE+
(\verb+W+) to represent the effects of statements and procedures; \verb+IN+
and \verb+OUT+ to represent the flow of array elements.
\item The {\em approximation\/} of the region: \verb+EXACT+ when the region
exactly represents the requested set of array elements, or \verb+MAY+ or
\verb+MUST+ if it is an over- or under-approximation ($\text{\must}
\incluseg \text{\exact} \incluseg \text{\may}$).
Unfortunately, for historical reasons, \verb+MUST+ is still used in the
implementation instead of \verb+EXACT+, and actual \verb+MUST+ regions are
not computed. Moreover, the {\tt must\_regions} option in fact computes
exact and may regions.
\verb+MAY+ regions are flow-insensitive regions, whereas \verb+MUST+
regions are flow sensitive. Any array element touched by any execution of
a statement is in the \verb+MAY+ region of this statement. Any array
element in the \verb+MUST+ region of a statement is accessed by any
execution of this statement.
\item a convex polyhedron containing equalities and inequalities:
they link the $\phi$ variables that represent the array dimensions,
to the values of the program integer scalar variables.
For a performance purpose, this convex polyhedron is never add for scalar
variables, except for the computation of IN/OUT-Regions for loops whose
his algorithm required it.
\end{itemize}
For instance, the convex array region:
\begin{alltt}
\begin{center}
\end{center}
\end{alltt}
where the region parameters \phik{1} and \phik{2} respectively represent
the first and second dimensions of \verb+A+, corresponds to an assignment
of the element \verb+A(I,I)+.
Internally, convex array regions are of type \texttt{effect} and as such can
be used to build use-def chains (see
Section~\ref{subsubsection-read-write-region-based-chains}).
Regions chains are built using {\em proper regions} which are particular
\verb+READ+ and \verb+WRITE+ regions.
For simple statements (assignments, calls to intrinsic functions),
summarization is avoided to preserve accuracy.
At this inner level of the program control flow graph, the extra
amount of memory necessary to store regions without computing their convex
hull should not be too high compared to the expected gain for dependence
analysis.
For tests and loops, proper regions contain the regions associated
to the condition or the range.
And for external calls, proper regions are the {\em summary regions} of the
callee translated into the caller's name space, to which are merely appended
the regions of the expressions passed as argument
(no summarization for this step).
Ressource \texttt{proper\_regions} is equivalent to \texttt{proper\_effects}
(see Section~\ref{subsubsection-proper-effects}), and \texttt{regions} to
\texttt{cumlulated\_effects} (see Section~\ref{subsubsection-cumulated-effects}).
So they share some features, like LUNS present for
\texttt{regions}/\texttt{cumlulated\_effects} on return/exit/abort statements.
Together with READ/WRITE regions and IN regions are computed their
invariant versions for loop bodies (\texttt{MODULE.inv\_regions} and
\texttt{MODULE.inv\_in\_regions}). For a given loop body, they are
equal to the corresponding regions in which all variables that may be
modified by the loop body (except the current loop index) are
eliminated from the descriptors (convex polyhedron). For other
statements, they are equal to the empty list of regions.
In the following trivial example,
\begin{lstlisting}
k = 0;
for(i=0; i
// invariant regions for loop body:
//
k = k+1;
a[k] = k;
}
\end{lstlisting}
notice that the variable \lstinline|k| which is modified in the loop
body, and which appears in the loop body region polyhedron, does not appear
anymore in the invariant region polyhedron.
\verb+MAY+ \verb+READ+ and \verb+WRITE+ region analysis was first designed
by R\'emi \textsc{Triolet}~\cite{Tri84} and then revisited by Fran\c{c}ois
\textsc{Irigoin}~\cite{TIF86}. Alexis \textsc{Platonoff}~\cite{Pla90}
implemented the first version of region analysis in \Pips{}. These
regions were computed with respect to the initial stores of the
modules. Fran\c{c}ois \textsc{Irigoin} and, mainly, B\'eatrice
\textsc{Creusillet}~\cite{CI95,CI96,Cre96}, added new functionalities to
this first version as well as functions to compute \verb+MUST+
regions, and \verb+IN+ and \verb+OUT+ regions.
\label{section-useful_variables_regions}
%% see trac https://scm.cri.ensmp.fr/trac/pips/ticket/781
\verb+MAY+ and \verb+MUST+ regions also compute useful\_variables\_regions
ressource.
This ressource computes the regions used by a variable at the
memory state of is declaration.
So it associates for each entity variable of a module, a R/W regions.
It was already compute during the computation if the regions but not memorize.
The store of this ressource was added by Nelson Lossing.
Array regions for C programs are currently under development.
\end{PipsPass}
\subsection{Menu for Convex Array Regions}
\begin{PipsMake}
alias regions 'Array regions'
alias may_regions 'MAY regions'
alias must_regions 'EXACT or MAY regions'
alias useful_variables_regions 'Useful Variables regions'
\end{PipsMake}
\subsection{MAY READ/WRITE Convex Array Regions}
\label{subsubsection-may-regions}
\index{MAY Region}
\begin{PipsPass}{may_pointer_regions}
This function computes the \verb|MAY| pointer regions in a module.
\end{PipsPass}
\begin{PipsMake}
may_pointer_regions > MODULE.proper_pointer_regions
> MODULE.pointer_regions
> MODULE.inv_pointer_regions
> MODULE.useful_variables_pointer_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_pointer_regions
\end{PipsMake}
\begin{PipsPass}{may_regions}
This function computes the \verb|MAY| regions in a module.
\end{PipsPass}
\begin{PipsMake}
may_regions > MODULE.proper_regions
> MODULE.regions
> MODULE.inv_regions
> MODULE.useful_variables_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_regions
\end{PipsMake}
\subsection{MUST READ/WRITE Convex Array Regions}
\label{subsubsection-must-regions}
\index{MUST Region}
\begin{PipsPass}{must_pointer_regions}
This function computes the \verb|MUST| regions in a module.
\end{PipsPass}
\begin{PipsMake}
must_pointer_regions > MODULE.proper_pointer_regions
> MODULE.pointer_regions
> MODULE.inv_pointer_regions
> MODULE.useful_variables_pointer_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_pointer_regions
\end{PipsMake}
\begin{PipsPass}{must_pointer_regions_with_points_to}
This function computes the \verb|MUST| pointer regions in a module
using simple points\_to information to disambiguate dereferencing paths.
\end{PipsPass}
\begin{PipsMake}
must_pointer_regions_with_points_to > MODULE.proper_pointer_regions
> MODULE.pointer_regions
> MODULE.inv_pointer_regions
> MODULE.useful_variables_pointer_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.points_to
< CALLEES.summary_pointer_regions
\end{PipsMake}
\begin{PipsPass}{must_regions}
This function computes the \verb|MUST| regions in a module.
\end{PipsPass}
\begin{PipsMake}
must_regions > MODULE.proper_regions
> MODULE.regions
> MODULE.inv_regions
> MODULE.useful_variables_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_regions
\end{PipsMake}
\begin{PipsPass}{must_regions_with_points_to}
This function computes the \verb|MUST| regions in a module using
information on pointer targets given by points-to.
\end{PipsPass}
\begin{PipsMake}
must_regions_with_points_to > MODULE.proper_regions
> MODULE.regions
> MODULE.inv_regions
> MODULE.useful_variables_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.points_to
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_regions
\end{PipsMake}
\begin{PipsPass}{must_regions_with_pointer_values}
This function computes the \verb|MUST| regions in a module using
information on pointer targets given by pointer values.
\end{PipsPass}
\begin{PipsMake}
must_regions_with_pointer_values > MODULE.proper_regions
> MODULE.regions
> MODULE.inv_regions
> MODULE.useful_variables_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.simple_pointer_values
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_regions
\end{PipsMake}
\subsection{Summary READ/WRITE Convex Array Regions}
\label{subsubsection-summary-regions}
\index{Summary Region}
\index{Region (Summary)}
Module summary regions provides an approximation of the effects it's
execution has on its callers variables as well as on global and
static variables of its callees.
\begin{PipsMake}
summary_pointer_regions > MODULE.summary_pointer_regions
< PROGRAM.entities
< MODULE.code
< MODULE.pointer_regions
\end{PipsMake}
\begin{PipsMake}
summary_regions > MODULE.summary_regions
< PROGRAM.entities
< MODULE.code
< MODULE.regions
\end{PipsMake}
\subsection{IN Convex Array Regions}
\label{subsubsection-in-regions}
\index{IN Regions}
\index{Regions (IN)}
\begin{PipsPass}{in_regions}
\verb+IN+ convex array regions are flow sensitive regions. They are read regions not
covered (i.e. not previously written) by assignments in the local
hierarchical control-flow graph. There is no way with the current
pipsmake-rc and \Pipsmake{} to express the fact that \verb+IN+ (and \verb+OUT+)
regions must be calculated using \PipsPassRef{must_regions} (a new kind of
resources, \PipsPassRef{must_regions}, should be added). The user must be
knowledgeable enough to select \PipsPassRef{must_regions} first.
\end{PipsPass}
\begin{PipsMake}
in_regions > MODULE.in_regions
> MODULE.cumulated_in_regions
> MODULE.inv_in_regions
< PROGRAM.entities
< MODULE.code
< MODULE.summary_effects
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.regions
< MODULE.inv_regions
< CALLEES.in_summary_regions
\end{PipsMake}
\subsection{IN Summary Convex Array Regions}
\label{subsubsection-in-summary-regions}
\index{IN Summary Regions}
\index{Summary Regions (IN)}
\begin{PipsPass}{in_summary_regions}
This pass computes the IN convex array regions of a module. They
contain the array elements and scalars whose values impact the output
of the module.
\end{PipsPass}
\begin{PipsMake}
in_summary_regions > MODULE.in_summary_regions
< PROGRAM.entities
< MODULE.code
< MODULE.transformers
< MODULE.preconditions
< MODULE.in_regions
\end{PipsMake}
\subsection{OUT Summary Convex Array Regions}
\label{subsubsection-out-summary-regions}
\index{OUT Summary Regions}
\index{Summary Regions (OUT)}
\begin{PipsPass}{out_summary_regions}
This pass computes the OUT convex array regions of a module. They
contain the array elements and scalars whose values impact the
continuation of the module.
\end{PipsPass}
See Section~\ref{subsubsection-out-regions}.
\begin{PipsMake}
out_summary_regions > MODULE.out_summary_regions
< PROGRAM.entities
< CALLERS.out_regions
\end{PipsMake}
\subsection{OUT Convex Array Regions}
\label{subsubsection-out-regions}
\index{OUT Regions}
\index{Regions (OUT)}
\begin{PipsPass}{out_regions}
\verb+OUT+ convex array regions are also flow sensitive regions. They are downward
exposed written regions which are also used (i.e. imported) in the
continuation of the program. They are also called {\em exported\/} regions.
Unlike \verb+READ+, \verb+WRITE+ and \verb+IN+ regions, they are propagated
downward in the call graph and in the hierarchical control flow graphs of
the subroutines.
\end{PipsPass}
\begin{PipsMake}
out_regions > MODULE.out_regions
< PROGRAM.entities
< MODULE.code
< MODULE.transformers
< MODULE.preconditions
< MODULE.regions
< MODULE.inv_regions
< MODULE.summary_effects
< MODULE.cumulated_effects
< MODULE.cumulated_in_regions
< MODULE.inv_in_regions
< MODULE.out_summary_regions
\end{PipsMake}
\subsection{Properties for Convex Array Regions}
\label{subsection-regions}
\index{Array Region}
\index{Region (Array)}
\index{EXACT\_REGIONS}
\index{MUST\_REGIONS}
\index{REGIONS\_WITH\_ARRAY\_BOUNDS}
\index{DISJUNCT\_REGIONS}
\index{DISJUNCT\_IN\_OUT\_REGIONS}
\index{REGIONS\_OP\_STATISTICS}
\index{REGIONS\_TRANSLATION\_STATISTICS}
If {\tt MUST\_REGIONS} is true, then it computes convex array regions using the
algorithm described in report E/181/CRI, called {\em $T^{-1}$
algorithm}. It provides more accurate regions, and preserve MUST
approximations more often. As it is more costly, its default value
is FALSE. EXACT\_REGIONS is true for the moment for backward
compatibility only.
\begin{PipsProp}{EXACT_REGIONS}
EXACT_REGIONS TRUE
\end{PipsProp}
\begin{PipsProp}{MUST_REGIONS}
MUST_REGIONS FALSE
\end{PipsProp}
The default option is to compute regions without taking into account
declared array bounds. The next property can be turned to {\tt TRUE}
to systematically add them in the region descriptors. Both options
have their advantages and drawbacks, but the second one implies that
the \PIPS{} user is sure that her/his program is correct with respect
to array accesses. In case of doubt, you might want to run pass
\PipsPassRef{array_bound_check_bottom_up} or
\PipsPassRef{array_bound_check_top_down}.
\begin{PipsProp}{REGIONS_WITH_ARRAY_BOUNDS}
REGIONS_WITH_ARRAY_BOUNDS FALSE
\end{PipsProp}
Property \PipsPropRef{MEMORY_IN_OUT_EFFECTS_ONLY}'s default value is
set to {\tt TRUE} to avoid computing IN and OUT effects or regions on non-memory
effects, even if \PipsPropRef{MEMORY_EFFECTS_ONLY} is set to {\tt
FALSE}.
\begin{PipsProp}{MEMORY_IN_OUT_EFFECTS_ONLY}
MEMORY_IN_OUT_EFFECTS_ONLY TRUE
\end{PipsProp}
The current implementation of effects, simple effects as well as
convex array regions, relies on a generic engine which is independent
of the effect descriptor representation. The current representation
for array regions, parameterized integer convex polyhedra, allows
various patterns an provides the ability to exploit context
information at a reasonable expense. However, some very common
patterns such as nine-point stencils used in seismic computations or
red-black patterns cannot be represented. It has been a long lasting
temptation to try other representations~\cite{Cre96}.
A Complementary sections (see Section~\ref{subsection-complementary-sections})
implementation was formerly began as a set of new phases by
Manjunathaiah \textsc{Muniyappa}, but is not maintained anymore.
And Nga Nguyen more recently created two properties to switch between
regions and disjunctions of regions (she has already prepared basic
operators). For the moment, they are always {\tt FALSE}.
\begin{PipsProp}{DISJUNCT_REGIONS}
DISJUNCT_REGIONS FALSE
\end{PipsProp}
\begin{PipsProp}{DISJUNCT_IN_OUT_REGIONS}
DISJUNCT_IN_OUT_REGIONS FALSE
\end{PipsProp}
Statistics may be obtained about the computation of convex array
regions. When the next
property ({\tt REGIONS\_OP\_STATISTICS}) is set to {\tt TRUE} statistics are
provided about operators on regions (union, intersection,
projection,\dots). The second next property turns on the collection of
statistics about the interprocedural translation.
\begin{PipsProp}{REGIONS_OP_STATISTICS}
REGIONS_OP_STATISTICS FALSE
\end{PipsProp}
\begin{PipsProp}{REGIONS_TRANSLATION_STATISTICS}
REGIONS_TRANSLATION_STATISTICS FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Live Memory Access Paths
\section{Live Memory Access Paths}
\label{subsection-live-memory-paths}
\index{Live variables}
There are many cases in which it is necessary to know if a variable
may be used in the remainder of the execution of the analyzed
application. For instance, a global variable cannot be privatized, or
a global array be scalarized, if we do not know whether their values
are used afterwards, or a copy-out must be generated, which is not
currently implemented in the simplest algorithms. Similarly,
preconditions do not need to propagate information about variables
that are no longer alive.
\subsection{Live Paths}
\label{subsubsection-live-paths}
\index{Live Paths}
\index{Live In Paths}
\index{Live Out Paths}
Traditional liveness analyzes deals with scalar variables. However,
with C code, it is interesting to be able to distinguish between
different structure fields for instance, and it may also be
interesting to deal with array regions. So we have retained for these
analyzes an internal representation as \emph{effects}, thus allowing
to deal with general memory access paths, and to rely on the existing
machinery of effects/regions computations. \\
Memory access paths can be equivalent to the constant path?
~\ref{consttant_path}
For each statement or function, we compute two sets: a \emph{Live\_in}
set contains the memory paths which are alive in the store preceding
the statement execution, while a \emph{Live\_out} set contains the
memory paths alive in the store immediately following the statement
execution. For sequences of instructions, the \emph{Live\_out} set of
an instruction is equal to the \emph{Live\_in} set of the next
instruction. However, this not true for the last statement of
conditional or loop bodies and the first statements of the next
instructions.
\begin{PipsPass}{live_out_summary_paths}
\end{PipsPass}
\begin{PipsMake}
live_out_summary_paths > MODULE.live_out_summary_paths
< PROGRAM.entities
< MODULE.code
< CALLERS.live_out_paths
\end{PipsMake}
\begin{PipsPass}{live_paths}
\end{PipsPass}
\begin{PipsMake}
live_paths > MODULE.live_in_paths
> MODULE.live_out_paths
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.in_effects
< MODULE.live_out_summary_paths
\end{PipsMake}
\begin{PipsPass}{live_summary_paths}
\end{PipsPass}
\begin{PipsMake}
live_in_summary_paths > MODULE.live_in_summary_paths
< PROGRAM.entities
< MODULE.code
< MODULE.live_in_paths
\end{PipsMake}
\subsection{Live Out Regions}
\label{subsubsection-live-out-regions}
\index{Live Out Regions}
\index{Regions (Live Out)}
\begin{PipsPass}{live_out_regions}
This pass only keeps constraints on live variables of
out-regions when it's possible.
So the polyhedral constraints for a variable will be less constraint.
But we assume that if a variable is not alive, there is no
reason to appear on the constraints of the out-regions.
This pass can be usefull to have regions that wil be use to generate some code.
It has better insure to not revive a ``die'' variable.
See Section~\ref{subsubsection-out-regions} and~\ref{subsubsection-live-paths}.
Note: Only constraints with variable are considered, since regions don't have
constraints on cell (PHI MODULE.live_out_regions
< PROGRAM.entities
< MODULE.code
< MODULE.out_regions
< MODULE.live_out_paths
< MODULE.live_in_paths
\end{PipsMake}
% TODO: implementation
% \subsection{Live In Regions}
% \label{subsubsection-live-in-regions}
% \index{Live In Regions}
% \index{Regions (Live In)}
%
% \begin{PipsPass}{live_in_regions}
% Similar to live_out_regions but for in.
%
% This pass only keeps constraints on live variables of
% in-regions when it's possible.
% So the polyhedral constraints for a variable will be less constraint.
% But we assume that if a variable is not alive, there is no
% reason to appear on the constraints of the in-regions.
%
% This pass can be usefull to have regions that wil be use to generate some code.
% It has better insure to not revive a ``die'' variable.
%
% See Section~\ref{subsubsection-in-regions} and~\ref{subsubsection-live-paths}.
%
% Note: Only constraints with variable are considered, since regions don't have
% constraints on cell (PHI MODULE.live_in_regions
% < PROGRAM.entities
% < MODULE.code
% < MODULE.in_regions
% < MODULE.live_in_paths
% < MODULE.live_out_paths
% \end{PipsMake}
\subsection{Live In/Out Effect}
\label{subsubsection-live-in-effects}
\label{subsubsection-live-out-effects}
\index{Live Out Effects}
\index{Effects (Live Out)}
\index{Live In Effects}
\index{Effects (Live In)}
There is no reason to ave live IN/OUT effects, because variables in
IN/OUT effects must be present in Live IN/OUT.
If it's not the case, it must be a bug somewhere?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ALIAS
\section{Alias Analysis}
\label{subsection-alias-analysis}
\index{Alias Analysis}
\subsection{Dynamic Aliases}
\label{subsubsection-dynamic-aliases}
\index{Dynamic Aliases}
\index{Alias Classes}
Dynamic aliases are pairs (formal parameter, actual parameter) of
convex array regions
generated at call sites. An ``IN alias pair'' is generated for each IN
region of
a called module and an ``OUT alias pair'' for each OUT region. For EXACT
regions, the transitive, symmetric and reflexive closure of the dynamic
alias relation results in the creation of equivalence classes of regions
(for MAY regions, the closure is different and does not
result in an equivalence relation, but nonetheless allows us to define alias
classes). A set of alias
classes is generated for a module, based on the IN and OUT alias
pairs of all the modules below it in the callgraph. The alias classes for
the whole workspace are those of the module which is at the root of the
callgraph, if the callgraph has a unique root. As an intermediate phase
between the creation of the
IN and OUT alias pairs and the creation of the alias classes, ``alias
lists'' are created for each module. An alias list for a module is the
transitive closure of the alias pairs (IN or OUT) for a particular path
through the callgraph subtree rooted in this module.
\begin{PipsMake}
in_alias_pairs > MODULE.in_alias_pairs
< PROGRAM.entities
< MODULE.callers
< MODULE.in_summary_regions
< CALLERS.code
< CALLERS.cumulated_effects
< CALLERS.preconditions
out_alias_pairs > MODULE.out_alias_pairs
< PROGRAM.entities
< MODULE.callers
< MODULE.out_summary_regions
< CALLERS.code
< CALLERS.cumulated_effects
< CALLERS.preconditions
alias_lists > MODULE.alias_lists
< PROGRAM.entities
< MODULE.in_alias_pairs
< MODULE.out_alias_pairs
< CALLEES.alias_lists
alias_classes > MODULE.alias_classes
< PROGRAM.entities
< MODULE.alias_lists
\end{PipsMake}
\subsection{Init Points-to Analysis}
\begin{PipsPass}{init_points_to_analysis}
This phase generates synthetic points-to relations for formal
parameters. It creates synthetic sinks, i.e. stubs, for formal
parameters and provides an initial set of points-to to the
\PipsPassRef{intraprocedural_points_to_analysis}.
Currently, it assumes that no sharing exists between the formal
parameters and within the data structures pointed to by the formal
parameters. Two properties should control this behavior,
\PipsPropRef{ALIASING_ACROSS_FORMAL_PARAMETERS} and
\PipsPropRef{ALIASING_ACROSS_TYPES}. The first one supersedes the
property \PipsPropRef{ALIASING_INSIDE_DATA_STRUCTURE}.
\end{PipsPass}
\begin{PipsMake}
alias init_points_to_analysis 'Init Points To Analysis'
init_points_to_analysis > MODULE.init_points_to_list
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Interprocedural Points to Analysis}
\label{subsection-interprocedural-points-to-analysis}
\index{Interprocedural Points-to Analysis}
\begin{PipsPass}{interprocedural_points_to_analysis}
This pass is being implemented by Amira \textsc{Mensi}.
The \PipsPassRef{interprocedural_points_to_analysis} is implemented in order to
compute points-to relations in an interprocedural way, based on \textsc{Wilson} algorithm. This phase computes
both Gen and Kill sets at the level of the call site.It requires another resource which is computed by \PipsPassRef{intraprocedural_points_to_analysis}.
\end{PipsPass}
\begin{PipsMake}
alias interprocedural_points_to_analysis 'Interprocedural Points To Analysis'
interprocedural_points_to_analysis > MODULE.points_to
> MODULE.points_to_out
> MODULE.points_to_in
! SELECT.proper_effects_with_points_to
! SELECT.cumulated_effects_with_points_to
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_effects
< CALLEES.points_to_out
< CALLEES.points_to_in
\end{PipsMake}
\subsection{Fast Interprocedural Points to Analysis}
\label{subsection-fast-interprocedural-points-to-analysis}
\index{Interprocedural Points to Analysis}
\begin{PipsPass}{fast_interprocedural_points_to_analysis}
This pass is being implemented by Amira \textsc{Mensi}.
The \PipsPassRef{fast_interprocedural_points_to_analysis} is implemented in order to
compute points-to relations in an interprocedural way, based on \textsc{Wilson} algorithm. This phase computes only
Kill sets at the call site level. It requires another resource which is computed by \PipsPassRef{intraprocedural_points_to_analysis}.
\end{PipsPass}
\begin{PipsMake}
alias fast_interprocedural_points_to_analysis 'Fast Interprocedural Points To Analysis'
fast_interprocedural_points_to_analysis > MODULE.points_to
> MODULE.points_to_out
> MODULE.points_to_in
! SELECT.proper_effects_with_points_to
! SELECT.cumulated_effects_with_points_to
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_effects
< CALLEES.points_to_out
< CALLEES.points_to_in
\end{PipsMake}
\subsection{Intraprocedural Points to Analysis}
\label{subsection-intraprocedural-points-to-analysis}
\label{subsection-points-to-analysis}
\index{Intraprocedural Points-to Analysis}
\begin{PipsPass}{intraprocedural_points_to_analysis}
This function is being implemented by Amira \textsc{Mensi}. The
\PipsPassRef{intraprocedural_points_to_analysis} is implemented in
order to compute points-to relations, based on Emami
algorithm. \textsc{Emami} algorithm is a top-down analysis which
calcules the points-to relations by applying specific rules to each
assignement pattern identified. This phase requires another resource
which is \PipsPassRef{init_points_to_analysis}. Ressources
points\_to\_in and points\_to\_out will be used to compute the
transfer function later. They represent points-to relation at the
beginning of functions where sources are formal parameters or global
variables. Points\_to\_out are points-to relations at the end of
function's body, it contains return value and it's sink, formal
parameters, gloabl variables and heap allocated variables which can be
visible beyond function's scope. And using effects to compute calls
impact on points-to analysis.
\end{PipsPass}
\begin{PipsMake}
alias intraprocedural_points_to_analysis 'Intraprocedural Points To Analysis'
intraprocedural_points_to_analysis > MODULE.points_to
> MODULE.points_to_out
> MODULE.points_to_in
! SELECT.proper_effects_with_points_to
! SELECT.cumulated_effects_with_points_to
< PROGRAM.entities
< MODULE.code
< CALLEES.summary_effects
< CALLEES.points_to_out
< CALLEES.points_to_in
\end{PipsMake}
The pointer effects are useful, but they are recomputed for each
expression and subexpression by the points-to analysis.
\subsection{Initial Points-to or Program Points-to}
\label{subsubsection-initial-points-to}
\index{Points-to (Initial)}
\index{Initial Points-to}
Because no top-down points-to analysis is available, this two passes
are useless. A top-down points-to analysis would be useful to check
that the restrict assumption about formal parameters is met by the
actual parameters. It might make possible a slighlty more precise
points-to information in the functions. Hopefully, the formal context
and the points-to stubs provide enough equivalent information to the
passes that use points-to information.
\begin{PipsMake}
initial_points_to > MODULE.initial_points_to
< PROGRAM.entities
< MODULE.code
< MODULE.points_to_out
\end{PipsMake}
All initial points-to are combined to define the program points-to which is an
abstraction of the program initial state.
\begin{PipsMake}
program_points_to > PROGRAM.program_points_to
< PROGRAM.entities
< ALL.initial_points_to
\end{PipsMake}
The program points-to can only be used for the initial state of the
main procedure. Although it appears below for all interprocedural analyses
and it always is computed, it only is used when a main procedure is
available.
\subsection{Pointer Values Analyses}
\label{subsection-pointer-values}
\index{Pointer Values Analyses}
\begin{PipsPass}{initial_simple_pointer_values}
Computes the initial pointer values from the global or static declarations of the module.
\end{PipsPass}
\begin{PipsMake}
initial_simple_pointer_values > MODULE.initial_simple_pointer_values
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{program_simple_pointer_values}
Computes the initial pointer values of the program from the global
declarations and the static declarations inside the program
modules. They are computed by merging the initial pointer values of
all the modules (this may include those which do not belong to
actually realizable paths).
\end{PipsPass}
\begin{PipsMake}
program_simple_pointer_values > PROGRAM.program_simple_pointer_values
< PROGRAM.entities
< ALL.initial_simple_pointer_values
\end{PipsMake}
\begin{PipsPass}{simple_pointer_values}
Pointer values analysis is another kind of pointer analysis which tries
to gather \emph{Pointer Values} both in terms of other pointer values
but also of memory addresses. This phase is under development.
\end{PipsPass}
\begin{PipsMake}
alias simple_pointer_values 'Pointer Values Analysis'
simple_pointer_values > MODULE.simple_pointer_values
> MODULE.in_simple_pointer_values
> MODULE.out_simple_pointer_values
< PROGRAM.entities
< MODULE.code
< PROGRAM.program_simple_pointer_values
< CALLEES.in_simple_pointer_values
< CALLEES.out_simple_pointer_values
\end{PipsMake}
\subsection{Properties for pointer analyses}
The following properties are defined to ensure the safe use
of \PipsPassRef{intraprocedural_points_to_analysis}.
\subsubsection{Impact of Types}
The property \PipsPropRef{ALIASING_ACROSS_TYPES} specifies that two
pointers of different effective types can be aliased. The default and
safe value is {\tt TRUE}; when it is turned to {\tt FALSE} two
pointers of different types are never aliased.
\begin{PipsProp}{ALIASING_ACROSS_TYPES}
ALIASING_ACROSS_TYPES TRUE
\end{PipsProp}
The property \PipsPropRef{ALIASING_ACROSS_FORMAL_PARAMETERS} is used
to handle the aliasing between formal parameters and global variables
of pointer type. When it is set to {\tt TRUE}, two formal parameters or a
formal one and a global pointer or two global pointers can be
aliased. If it is turned to {\tt FALSE}, such pointers are assumed to be
unaliased for intraprocedural analysis and generally for root
module(i.e. modules without callers). The default value is {\tt
FALSE}. It is the only value currently implemented.
\begin{PipsProp}{ALIASING_ACROSS_FORMAL_PARAMETERS}
ALIASING_ACROSS_FORMAL_PARAMETERS FALSE
\end{PipsProp}
The nest property specifies that one data structure can recursively
contain two pointers pointing to the same location. If it is turned to
{\tt FALSE}, it is assumed that two different not included memory
access paths cannot point to the same memory locations. The safe value
is {\tt TRUE}, but parallelization is hindered. Often, the user can
guarantee that data structures do not exhibit any
sharing. Optimistically, {\tt FALSE} is the default value.
\begin{PipsProp}{ALIASING_INSIDE_DATA_STRUCTURE}
ALIASING_INSIDE_DATA_STRUCTURE FALSE
\end{PipsProp}
Property \PipsPropRef{ALIASING_ACROSS_IO_STREAMS} can be set to {\tt
FALSE} to specify that two io streams (two variables declared as
{\tt FILE *}) cannot be aliased, neither the locations to which they
point. The safe and default value is {\tt TRUE}
\begin{PipsProp}{ALIASING_ACROSS_IO_STREAMS}
ALIASING_ACROSS_IO_STREAMS TRUE
\end{PipsProp}
\subsubsection{Heap Modeling}
The following string property defines the lattice of maximal elements
to use when precise information is lost. Three values are possible:
"unique", "function" and "area". The first value is the default
value. A unique identifier is defined to represent any set of unknown
locations. The second value defines a separate identifier for each
function and compilation unit. Note that compilation units require
more explanation about this definition and about the conflict detection
scheme. The third value, "area", requires a separate identifier for
each area of each function or compilation unit. These abstract
lcoation lattice values are further refined if the property
\PipsPropRef{ALIASING_ACROSS_TYPES} is set to FALSE. The abstract
location API hides all these local maximal values from its
callers. Note that the dereferencing of any such top abstract location
returns the very top of all abstract locations.
% \begin{PipsProp}{ABSTRACT_LOCATION_TOP[_LATTICE]}
% ABSTRACT_LOCATION_TOP[_LATTICE] "unique"
% \end{PipsProp}
The \PipsPropRef{ABSTRACT_HEAP_LOCATIONS} specifies the modeling of
the heap. The possible values are "unique", "insensitive",
"flow-sensitive" and "context-sensitive". Each value defines
a strictly refined analysis with respect to analyses defined by
previous values [This may not be a good idea, since flow and context
sensitivity are orthogonal].
The default value, "unique", implies
that the heap is a unique array. It is enough to parallelize simple
loops containing pointer-based references such as
"p[i]".
In the "insensitive" case and all other cases, one array is
allocated in each function to modelize the heap.
In the "flow-sensitive" case, the statement numbers of the malloc()
call sites are used to subscribe this array, as well as all indices of
the surrounding loops [Two improvements in one property...]. Only the
first half of the property is implemented.
In the "context\_sensitive" case, the interprocedural translation of
memory acces paths based on the abstract heap are prefixed by the same
information regarding the call site: function containing the call
site, statement number of the call site and indices of surrounding
loops. This is not implemented.
Note that the naming of options is not fully compatible with
the usual notations in pointer analyses. Note also that the
insensitive case is redundant with context sensitive case: in the
later case, a unique heap associated to malloc() would carry exactly
the same amount of information [flow and context sensitivity are
orthogonal].
Finally, note that abstract heap arrays are distinguished according to
their types if the property \PipsPropRef{ALIASING_ACROSS_TYPES} is set
to FALSE [impact on abstract heap location API]. Else, the heap array
is of type unknown. If a heap abstract location is dereferenced
without any point-to information nor heap aliasing information, the
safe result is the top abstract location.
\begin{PipsProp}{ABSTRACT_HEAP_LOCATIONS}
ABSTRACT_HEAP_LOCATIONS "unique"
\end{PipsProp}
Property \PipsPropRef{POINTS_TO_SUCCESSFUL_MALLOC_ASSUMED} is used to
control the analysis of a malloc call. The call may return either a
unique target in the heap, or a pair of targets, one in the heap and
NULL. The default value is true for historical reasons and because the
result is shorter and correct almost all the time.
\begin{PipsProp}{POINTS_TO_SUCCESSFUL_MALLOC_ASSUMED}
POINTS_TO_SUCCESSFUL_MALLOC_ASSUMED TRUE
\end{PipsProp}
\subsubsection{Type Handling}
The property \PipsPropRef{POINTS_TO_STRICT_POINTER_TYPES}
is used to handle pointer arithmetic. According to C standard(section 6.5.6, item 8)
the following C code :
\begin{verbatim}
int *p, i;
p = \&i;
p++ ;
\end{verbatim}
is correct and p points to the same area, expressed by the points to analysis as i[*].
The default value is {\tt FALSE}, meaning that p points to an array element. When it's set to
{\tt TRUE} typing becone strict ; meaning that p points to an integer and the behavior is undefined.
So the analysis stops with a pips\_user\_error(illegal pointer arithmetic)
\begin{PipsProp}{POINTS_TO_STRICT_POINTER_TYPES}
POINTS_TO_STRICT_POINTER_TYPES FALSE
\end{PipsProp}
% no longer used {
% The following property is used to bound the length of any generic
% access path or reference. Its default value is 0. It means that no limit is set.
% \begin{PipsProp}{GAP_MAX_LENGTH}
% GAP_MAX_LENGTH 0
% \end{PipsProp}
% }
\subsubsection{Dereferenceing of Null and Undefined Pointers}
The property
\PipsPropRef{POINTS_TO_UNINITIALIZED_POINTER_DEREFERENCING} specifies
what to do when an uninitialized pointer is or may be dereferenced. The safe
value is {\tt FALSE}. The points-to analysis assumed that no undefined
pointer is ever dereferenced. So if a pointer may be undefined and is
dereferenced, the arc is considered impossible and removed from the
points-to information. If not other arc provides some value for this
pointer, the code is assumed dead and the current points-to set is
reduced to the empty set. A warning about dead code is
emitted. However the property can be set to {\tt TRUE} and the
dereferencing of an undefined pointer is accepted and results in an
anywhere location.
\begin{PipsProp}{POINTS_TO_UNINITIALIZED_POINTER_DEREFERENCING}
POINTS_TO_UNINITIALIZED_POINTER_DEREFERENCING FALSE
\end{PipsProp}
The property
\PipsPropRef{POINTS_TO_NULL_POINTER_DEREFERENCING} is very similar to the previous one. It specifies
what to do when an null pointer is or may be dereferenced. The safe
value is {\tt FALSE}. The points-to analysis assumed that no null
pointer is ever dereferenced. So if a pointer may be undefined and is
dereferenced, the arc is considered impossible and removed from the
points-to information. If not other arc provides some value for this
pointer, the code is assumed dead and the current points-to set is
reduced to the empty set. A warning about dead code is
emitted. However the property can be set to {\tt TRUE} and the
dereferencing of an undefined pointer is accepted and results in an
anywhere location.
\begin{PipsProp}{POINTS_TO_NULL_POINTER_DEREFERENCING}
POINTS_TO_NULL_POINTER_DEREFERENCING FALSE
\end{PipsProp}
The property \PipsPropRef{POINTS_TO_NULL_POINTER_INITIALIZATION}
allows the initialization of pointers that are formal parameters or
global variables to \verb/NULL/ when computing a calling context. The
most accurate property value is {\tt TRUE}, which makes sure that
generated points-to stubs are different from NULL because two arcs are
always generated: an arc towards the new points-to stub and an arc
towards the \verb/NULL/ location. Thus it prevents from dereferencing
a null pointer when dereferencing a points-to stub and it allows the
comparison of two points-to stubs when a condition such as \verb/p!=q/
is interpreted or the comparison of one points-to stub to NULL as in
\verb/p!=NULL/. This property must be set to TRUE for the points-to
analysis to return valid results since the constant path lattice used
implies that NULL is not included in points-to stubes. Also, setting
it to FALSE make any formal recursive data structures infinite since
NULL is never found by the analyzer. Basically, this property should
be removed.
\begin{PipsProp}{POINTS_TO_NULL_POINTER_INITIALIZATION}
POINTS_TO_NULL_POINTER_INITIALIZATION TRUE
\end{PipsProp}
\subsubsection{Limits of Points-to Analyses}
The integer property \PipsPropRef{POINTS_TO_OUT_DEGREE_LIMIT}
specifies the maximum number of arcs exiting a given vertex of a
poins-to graph. When the maximum out degree is reached for a given
source vertex, all the corresponding sink vertices are fused into one
new vertex, the minimal upper bound of the initial vertices according
to the abstract address lattice, and the points-to graph is updated
accordingly. New nodes are created as long as the limit is not
reached. The freeing of a list spine can generate an unbounded out
degree (see for instance Pointers/list05.c).
\begin{PipsProp}{POINTS_TO_OUT_DEGREE_LIMIT}
POINTS_TO_OUT_DEGREE_LIMIT 5
\end{PipsProp}
The integer property \PipsPropRef{POINTS_TO_PATH_LIMIT} specifies the
maximum number of occurences of an object of a given type in a
non-cyclic path generated by the points-to graph. New nodes are created as long as no such path exists. When the limit is reached, a cycle is created.
\begin{PipsProp}{POINTS_TO_PATH_LIMIT}
POINTS_TO_PATH_LIMIT 2
\end{PipsProp}
The integer property \PipsPropRef{POINTS_TO_SUBSCRIPT_LIMIT} specifies
the maximum number of subscript of an object can be generated via
pointer arithmetic. When the limit is reached, an unbounded subscript,
*, is used to model any possible subscript value.
\begin{PipsProp}{POINTS_TO_SUBSCRIPT_LIMIT}
POINTS_TO_SUBSCRIPT_LIMIT 2
\end{PipsProp}
\subsection{Menu for Alias Views}
\begin{PipsMake}
alias alias_file 'Alias View'
alias print_in_alias_pairs 'In Alias Pairs'
alias print_out_alias_pairs 'Out Alias Pairs'
alias print_alias_lists 'Alias Lists'
alias print_alias_classes 'Alias Classes'
\end{PipsMake}
\begin{PipsPass}{print_in_alias_pairs}
Display the dynamic alias pairs (formal region, actual region) for the IN
regions of the module.
\end{PipsPass}
\begin{PipsMake}
print_in_alias_pairs > MODULE.alias_file
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.in_alias_pairs
\end{PipsMake}
\begin{PipsPass}{print_out_alias_pairs}
Display the dynamic alias pairs (formal region, actual region) for the OUT
regions of the module.
\end{PipsPass}
\begin{PipsMake}
print_out_alias_pairs > MODULE.alias_file
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.out_alias_pairs
\end{PipsMake}
\begin{PipsPass}{print_alias_lists}
Display the transitive closure of the dynamic aliases for the module.
\end{PipsPass}
\begin{PipsMake}
print_alias_lists > MODULE.alias_file
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.alias_lists
\end{PipsMake}
\begin{PipsPass}{print_alias_classes}
Display the dynamic alias equivalence classes for this module and those
below it in the callgraph.
\end{PipsPass}
\begin{PipsMake}
print_alias_classes > MODULE.alias_file
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.alias_classes
\end{PipsMake}
\section{Complementary Sections}
\label{subsection-complementary-sections}
\index{Complementary Sections}
\index{Array Region}
\begin{PipsMake}
alias compsec 'Complementary Sections'
\end{PipsMake}
A new representation of array regions added in \Pips{} by
Manjunathaiah \textsc{Muniyappa}. This anlysis is not maintained
anymore.
\subsection{READ/WRITE Complementary Sections}
\label{subsubsection-complementary-sections}
\begin{PipsPass}{complementary_sections}
This function computes the complementary sections in a module.
\end{PipsPass}
\begin{PipsMake}
complementary_sections > MODULE.compsec
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< CALLEES.summary_compsec
\end{PipsMake}
\subsection{Summary READ/WRITE Complementary Sections}
\label{subsubsection-summary-complementary-sections}
\index{Summary Complementary Sections}
\index{Complementary Sections (Summary)}
\begin{PipsMake}
summary_complementary_sections > MODULE.summary_compsec
< PROGRAM.entities
< MODULE.code
< MODULE.compsec
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Dynamic Analyses (Instrumentation)}
Dynamic analyses are performed at run-time. At compile-time, the
property than can be proved or disproved are exploited, but in doubt a
run-time is added to the source code. The current dynamic analyses
implemented in \Pips are array bound checking, Fortran alias and
used-before-set analyses.
\section{Array Bound Checking}
\label{subsection-array-bound-checking}
\index{Buffer overflow}
\index{Array access}
Array bound checking refers to determining whether all array references
are within their declared range in all of their uses in a program. These
array bound checks may be analysed intraprocedurally or
interprocedurally, depending on the need for accuracy.
There are two versions of intraprocedural array bounds checking: array
bound check bottom up, array bound check top down. The first approach
relies on checking every array access and on the elimination of
redundant tests by advanced dead code elimination based on
preconditions. The second approach is based on exact convex array
regions. They are used to prove that all accessed in a compound
statement are correct.
These two dynamic analyses are implemented for Fortran. They are
described in Nga Nguyen's PhD (see~\cite{Ngu02}) and in~\cite{NI05}. They
may work for C code, but this has not been validated.
\subsection{Elimination of Redundant Tests: Bottom-Up Approach}
\label{subsection-array-bound-check_bottom_up}
\begin{PipsPass}{array_bound_check_bottom_up}
This transformation takes as input the current module, adds array range
checks (lower and upper bound checks) to every statement that has one or
more array accesses. The output is the module with those added tests.
If one test is trivial or exists already for the same statement, it is
no need to be generated in order to reduce the
number of tests. As Fortran language permits an assumed-size array
declarator with the unbounded upper bound of the last dimension, no range check is generated for this case also.
Associated with each test is a bound violation error message and in case
of real access violation, a STOP statement will be put before the current
statement.
This phase should always be followed by the
\PipsPassRef{partial_redundancy_elimination} for logical expression in
order to reduce the number of bound checks.
\end{PipsPass}
\begin{PipsMake}
alias array_bound_check_bottom_up 'Elimination of Redundant Tests'
array_bound_check_bottom_up > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Insertion of Unavoidable Tests}
\label{subsection-array-bound-check_top_down}
\begin{PipsPass}{array_bound_check_top_down}
This second implementation is based on the array region analyses phase which benefits some interesting proven properties:
\begin{enumerate}
\item If a MAY region correspond to one node in the control flow graph
that represents a block of code of program is included in the
declared dimensions of the array, no bound check is needed for this
block of code.
\item If a MUST region correspond to one node in the control
flow graph that represents a block of code of program contains elements
which are outside the declared dimensions of the array, there is
certainly bound violation in this block of code. An error can be
detected just in compilation time.
\end{enumerate}
If none of these two properties are satisfied, we consider the
approximation of region. In case of MUST region, if the exact bound checks
can be generated, they will be inserted before the block of code. If not,
like in case of MAY region, we continue to go down to the children nodes
in the control flow graph.
The main advantage
of this algorithm is that it permits to detect the sure bound violations
or to tell that there is certainly no bound violation as soon as
possible, thanks to the context given by preconditions and the top-down
analyses.
\end{PipsPass}
\begin{PipsMake}
alias array_bound_check_top_down 'Insertion of Unavoidable Tests'
array_bound_check_top_down > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.regions
\end{PipsMake}
\subsection{Interprocedural Array Bound Checking}
\label{subsection-array-bound-check_interprocedural}
\begin{PipsPass}{array_bound_check_interprocedural}
This phase checks for out of bound errors when passing arrays or array
elements as arguments in procedure call. It ensures that there is no bound
violation in every array access in the callee procedure, with respect to
the array declarations in the caller procedure.
\end{PipsPass}
\begin{PipsMake}
alias array_bound_check_interprocedural 'Interprocedural Array Bound Checking'
array_bound_check_interprocedural > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ARRAY BOUND CHECK
\subsection{Array Bound Checking Instrumentation}
\label{subsection-array-bound-check_instrumentation}
\begin{PipsPass}{array_bound_check_instrumentation}
We provide here a tool to calculate the number of dynamic bound checks
from both initial and PIPS generated code.
These transformations are implemented by Thi Viet Nga \textsc{Nguyen} (see~\cite{Ngu02}).
\end{PipsPass}
\begin{PipsMake}
alias array_bound_check_instrumentation 'Array Bound Checking Instrumentation'
array_bound_check_instrumentation > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Array bounds checking refers to determining whether all array reference
are within their declared range in all of its uses in a program. Here are
array bounds checking options for code instrumentation, in order to
compute the number of bound checks added. We can use only one property for
these two case, but the meaning is not clear. To be changed ?
\begin{PipsProp}{INITIAL_CODE_ARRAY_BOUND_CHECK_INSTRUMENTATION}
INITIAL_CODE_ARRAY_BOUND_CHECK_INSTRUMENTATION TRUE
\end{PipsProp}
\begin{PipsProp}{PIPS_CODE_ARRAY_BOUND_CHECK_INSTRUMENTATION}
PIPS_CODE_ARRAY_BOUND_CHECK_INSTRUMENTATION FALSE
\end{PipsProp}
In practice, bound violations may often occur with arrays in a common block. The
standard is violated, but programmers think that they are not dangerous
because the allocated size of the common is not reached.
The following property deals with this kind of bad programming practice. If the
array is a common variable, it checks if the reference goes beyond the
size of the common block or not.
\begin{PipsProp}{ARRAY_BOUND_CHECKING_WITH_ALLOCATION_SIZE}
ARRAY_BOUND_CHECKING_WITH_ALLOCATION_SIZE FALSE
\end{PipsProp}
The following property tells the verification phases (array bound
checking, alias checking or uninitialized variables checking) to instrument
codes with the STOP or the PRINT message. Logically, if a standard violation
is detected, the program will stop immediately. Furthermore, the STOP message gives the
partial redundancy elimination phase more information to remove
redundant tests occurred after this STOP. However, for the debugging
purposes, one may need to display all possible violations such as
out-of-bound or used-before-set errors, but not
to stop the program. In this case, a PRINT message is chosen. By default,
we use the STOP message.
\begin{PipsProp}{PROGRAM_VERIFICATION_WITH_PRINT_MESSAGE}
PROGRAM_VERIFICATION_WITH_PRINT_MESSAGE FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ALIAS
\section{Alias Verification}
\label{subsection-alias-verification}
\subsection{Alias Propagation}
\label{subsubsection-alias-propagation}
\index{Alias Propagation}
\begin{PipsPass}{alias_propagation}
\textit {Aliasing} occurs when two or more variables refer to the same
storage location at the same program point. Alias analysis is critical for
performing most optimizations correctly because we must know for certain
that we have to take into account
all the ways a location, or the value of a variable, may (or must)
be used or changed. Compile-time alias information is also important for
program verification, debugging and understanding.
In Fortran 77, parameters are passed by address in such
a way that, as long as the actual argument is associated with a named
storage location, the called subprogram can change the value of the actual
argument by assigning a value to the corresponding formal parameter. So
new aliases can be created between formal parameters if the
same actual argument is passed to two or more formal parameters, or between formal
parameters and global parameters if an actual
argument is an object in common storage which is also visible in the
called subprogram or other subprograms in the call chain below it.
Both \textit{intraprocedural} and \textit{interprocedural} alias
determinations are important for program analysis. Intraprocedural aliases
occur due to pointers in languages like LISP, C, C++ or Fortran 90,
union construct in C or \verb+EQUIVALENCE+ in Fortran. Interprocedural aliases
are generally created by parameter passing and by access to global
variables, which propagates intraprocedural aliases across procedures and
introduces new aliases.
The basic idea for computing interprocedural aliases is to follow all the
possible chains of argument-parameters and nonlocal variable-parameter
bindings at all call sites. We introduce a \textit{naming memory
locations} technique which guarantees the correctness and enhances the
precision of data-flow analysis. The technique associates sections,
offsets of actual parameters to formal parameters following a certain call
path. Precise alias information are computed for both scalar and array
variables. The analysis is called alias propagation.
This analysis is implemented by Thi Viet Nga \textsc{Nguyen} (see~\cite{Ngu02}).
\end{PipsPass}
\begin{PipsMake}
alias_propagation > MODULE.alias_associations
< PROGRAM.entities
< MODULE.code
< CALLERS.alias_associations
< CALLERS.code
\end{PipsMake}
\subsection{Alias Checking}
\label{subsubsection-alias-check}
\index{Alias Checking}
\begin{PipsPass}{alias_check}
With the call-by-reference mechanism in Fortran 77, new aliases can be
created between formal parameters if the
same actual argument is passed to two or more formal parameters, or between formal
parameters and global parameters if an actual
argument is an object in common storage which is also visible in the
called subprogram or other subprograms in the call chain below it.
Restrictions on association of entities in Fortran 77 (Section 15.9.3.6
\cite{ANSI78}) say that neither aliased formal parameters nor the variable in the
common block may become defined during execution
of the called subprogram or the others subprograms in the call chain.
This phase uses information from the \PipsPassRef{alias_propagation}
analysis and computes the definition
informations of variables in a program, and then to verify
statically if the program violates the standard restriction on alias or
not. If these informations are not known at compile-time, we instrument
the code with tests that check the violation dynamically during
execution of program.
This verification is implemented by Thi Viet Nga \textsc{Nguyen} (see~\cite{Ngu02}).
\end{PipsPass}
% Attention : will we use the preconditions, regions, effects ?
% They are may be wrong
\begin{PipsMake}
alias alias_check 'Alias Check'
alias_check > MODULE.code
< PROGRAM.entities
< MODULE.alias_associations
< MODULE.cumulated_effects
< ALL.code
\end{PipsMake}
This is a property to control whether the alias propagation and alias checking
phases use information from MAIN program or not. If the current
module is never called by the main program, we do no alias propagation
and alias checking for this module if the property is on. However, we
can do nothing with modules that have no callers at all, because this
is a top-down approach.
\begin{PipsProp}{ALIAS_CHECKING_USING_MAIN_PROGRAM}
ALIAS_CHECKING_USING_MAIN_PROGRAM FALSE
\end{PipsProp}
\section{Used Before Set}
\label{subsection-used-before_set}
\begin{PipsPass}{used_before_set}
This analysis checks if the program uses a variable or an array element
which has not been assigned a value. In this case, anything may happen:
the program may appear to run normally, or may
crash, or may behave unpredictably. We use IN regions
that give a set of read variables not previously written. Depending on the
nature of the variable: local, formal or global, we have different
cases. In principle, it
works as follows: if we have a MUST IN region at the module statement, the
corresponding variable must be used before
being defined, a STOP is inserted. Else, we insert an initialization
function and go down, insert a verification function before each MUST IN
at each sub-statements.
This is a top-down analysis that process a procedure before all its
callees. Information given by callers is used to verify if we have to
check for the formal parameters in the current module or not. In addition,
we produce information in the resource MODULE.ubs to tell if the formal
parameters of the called procedures have to be checked or not.
This verification is implemented by Thi Viet Nga \textsc{Nguyen} (see~\cite{Ngu02}).
\end{PipsPass}
\begin{PipsMake}
alias used_before_set 'Used Before Set'
used_before_set > MODULE.ubs
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< CALLERS.ubs
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Parallelization, Distribution and Code Generation}
\label{section-program-transformations-parallelization-distribution}
%% \index{Transformation}
%% \index{Program Transformation}
\index{Parallelization}
\index{Distribution}
\section{Code Parallelization}
\label{subsection-parallelization}
\index{Parallelization}
\begin{PipsPass}{parallelized_code}
\Pips{} basic parallelization function, \PipsPassRef{rice_all_dependence},
produces a new version of the Module code with DOALL loops exhibited using
A{\sc llen} \& K{\sc ennedy}'s algorithm. The DOALL syntactic construct is
non-standard but easy to understand and usual in text book like \cite{Wolfe96}.
As parallel prettyprinter option, it is possible to use Fortran~90 array
syntax (see Section~\ref{subsection-parallel-printed-files}). For C, the
loops can be output as \texttt{for}-loop decorated with OpenMP pragma.
Remember that A{\sc llen} \& K{\sc ennedy}'s algorithm can only be applied
on loops with simple bodies, i.e. sequences of assignments, because it
performs loop distribution and loop regeneration without taking control
dependencies into account. If the loop body contains tests and branches,
the coarse grain parallelization algorithm should be used (see
\ref{subsubsection-coarse-grain-parallelization}).
Loop index variables are privatized whenever possible, using a simple
algorithm. Dependence arcs related to the index variable and stemming
from the loop body must end up inside the loop body. Else, the loop
index is not privatized because its final value is likely to be needed
after the loop end and because no copy-out scheme is supported.
A better privatization algorithm for all scalar variable may be used as a
preliminary code transformation. An array privatizer is also available
(see Section~\ref{sec:scalar-and-array-privatization}). A non-standard
{\tt PRIVATE} declaration is used to specify which variables should be
allocated on stack for each loop iteration. An HPF or OpenMP format can
also be selected.
Objects of type \verb+parallelized_code+ differs from objects of type
\verb+code+ for historic reasons, to simplify the user interface and
because most algorithms cannot be applied on {\tt DOALL} loops. This used
to be true for pre-condition computation, dependence testing and so
on... It is possible neither to re-analyze parallel code, nor to re-parse
it (although it would be interesting to compute the complexity of a
parallel code) right now but it should evolves. See
\S~\ref{sec:cons-parall-code}.
\end{PipsPass}
\subsection{Parallelization properties}
\index{Parallelization}
There are few properties that control the parallelization behaviour.
\subsubsection{Properties controlling Rice parallelization}
\index{Allen\&Kennedy}
\index{GENERATE\_NESTED\_PARALLEL\_LOOPS}
\index{PARALLELIZATION\_STATISTICS}
\index{Thread-safe library}
TRUE to make all possible parallel loops, FALSE to generate real (vector,
innermost parallel?) code:
\begin{PipsProp}{GENERATE_NESTED_PARALLEL_LOOPS}
GENERATE_NESTED_PARALLEL_LOOPS TRUE
\end{PipsProp}
Show statistics on the number of loops parallelized by pips:
\begin{PipsProp}{PARALLELIZATION_STATISTICS}
PARALLELIZATION_STATISTICS FALSE
\end{PipsProp}
To select whether parallelization and loop distribution is done again for
already parallel loops:
\begin{PipsProp}{PARALLELIZE_AGAIN_PARALLEL_CODE}
PARALLELIZE_AGAIN_PARALLEL_CODE FALSE
\end{PipsProp}
The motivation is we may want to parallelize with a coarse grain method
first, and finish with a fine grain method here to try to parallelize what
has not been parallelized. When applying \emph{\`a la} Rice parallelizing
to parallelize some (still) sequential code, we may not want loop
distribution on already parallel code to preserve cache resources, etc.
Thread-safe libraries are protected by critical sections. Their
functions can be called safely from different execution threads. For
instance, a loop whose body contains calls to \verb/malloc/ can be
parallelized. The underlying state changes do no hinder
parallelization, at least if the code is not sensitive to pointer
values.
\begin{PipsProp}{PARALLELIZATION_IGNORE_THREAD_SAFE_VARIABLES}
PARALLELIZATION_IGNORE_THREAD_SAFE_VARIABLES FALSE
\end{PipsProp}
Since this property is used to mask arcs in the dependence graph, it
must be exploited by each parallelization phase independently. It is
not used to derived a simplified version of the use-def chains or of
the dependence graph to avoid wrong result with use-def elimination,
which is based on the same graph.
\subsection{Menu for Parallelization Algorithm Selection}
Entries in menu for the resource \verb/parallelized_code/ and for the
different parallelization algorithms with may be activated or
selected. Note that the nest parallelization algorithm is not debugged.
\begin{PipsMake}
alias parallelized_code 'Parallelization'
alias rice_all_dependence 'All Dependences'
alias rice_data_dependence 'True Dependences Only'
alias rice_cray 'CRAY Microtasking'
alias nest_parallelization 'Loop Nest Parallelization'
alias coarse_grain_parallelization 'Coarse Grain Parallelization'
alias internalize_parallel_code 'Consider a parallel code as a sequential one'
\end{PipsMake}
\subsection{Allen \& Kennedy's Parallelization Algorithm}
\label{subsubsection-allen-kennedy-parallelization-algorithm}
\index{Parallelization}
\index{Allen \& Kennedy Algorithm}
\begin{PipsPass}{rice_all_dependence}
Use A{\sc llen} \& K{\sc ennedy}'s algorithm and consider all
dependences.
\end{PipsPass}
\begin{PipsMake}
rice_all_dependence > MODULE.parallelized_code
< PROGRAM.entities
< MODULE.code MODULE.dg
\end{PipsMake}
\subsection{Def-Use Based Parallelization Algorithm}
\begin{PipsPass}{rice_data_dependence}
Several other parallelization functions for shared-memory target
machines are available. Function \PipsPassRef{rice_data_dependence} only takes into
account data flow dependences, a.k.a true dependences. It is of limited
interest because transitive dependences are computed. It is not
equivalent at all to performing array and scalar expansion based on direct
dependence computation (\textsc{Brandes}, \textsc{Feautrier}, \textsc{Pugh}).
It is not safe when privatization is performed before parallelization.
This phase is named after the historical classification of data
dependencies in output dependence, anti-dependence and true or data
dependence. It should not be used for standard parallelization, but
only for experimental parallelization by knowledgeable users, aware
that the output code may be illegal.
\end{PipsPass}
\begin{PipsMake}
rice_data_dependence > MODULE.parallelized_code
< PROGRAM.entities
< MODULE.code MODULE.dg
\end{PipsMake}
\subsection{Parallelization and Vectorization for Cray Multiprocessors}
\index{Cray}
\index{Vectorization}
\index{Parallelization}
\begin{PipsPass}{rice_cray}
Function \PipsPassRef{rice_cray} targets Cray vector multiprocessors. It
selects one outermost parallel loop to use multiple processors and one
innermost loop for the vector units. It uses Cray microtasking
directives. Note that a prettyprinter option must also be selected independently (see
Section~\ref{subsection-parallel-printed-files}).
\end{PipsPass}
\begin{PipsMake}
rice_cray > MODULE.parallelized_code
< PROGRAM.entities
< MODULE.code MODULE.dg
\end{PipsMake}
\subsection{Coarse Grain Parallelization}
\label{subsubsection-coarse-grain-parallelization}
\begin{PipsPass}{coarse_grain_parallelization}
Function \PipsPassRef{coarse_grain_parallelization} implements a
loop parallelization algorithm based on convex array regions. It
considers only one loop at a time, its body being abstracted by its
invariant read and write regions. No loop distribution is performed,
but any kind of loop body is acceptable whereas \textsc{Allen} \&
\textsc{Kennedy} algorithm only copes with very simple loop bodies.
\end{PipsPass}
For nasty reasons about effects that are statement addresses to effects
mapping, this pass changes the code instead of producing a
\verb|parallelized_code| resource. It is not a big deal since often we
want to modify the code again and we should use
\PipsPassRef{internalize_parallel_code} just after if its behavior
were modified.
\begin{PipsMake}
coarse_grain_parallelization > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.preconditions
< MODULE.inv_regions
\end{PipsMake}
\begin{PipsPass}{coarse_grain_parallelization_with_reduction}
Function \PipsPassRef{coarse_grain_parallelization_with_reduction} extend the
standard \PipsPassRef{coarse_grain_parallelization} by using reduction
detection informations.
\end{PipsPass}
\begin{PipsMake}
coarse_grain_parallelization_with_reduction > MODULE.reduction_parallel_loops
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.cumulated_reductions
< MODULE.proper_reductions
< MODULE.inv_regions
\end{PipsMake}
\subsection{Global Loop Nest Parallelization}
\begin{PipsPass}{nest_parallelization}
Function \PipsPassRef{nest_parallelization} is an attempt at combining loop
transformations and parallelization for perfectly nested
loops. Different parameters are computed like loop ranges and contiguous
directions for references. Loops with small ranges are fully
unrolled. Loops with large ranges are strip-mined to obtain vector and
parallel loops. Loops with medium ranges simply are parallelized. Loops
with unknown range also are simply parallelized.
For each loop direction, the amount of spatial and temporal localities
is estimated. The loop with maximal locality is chosen as innermost
loop.
This algorithm still is in the development stage. It can be tried to
check that loops are interchanged when locality can be
improved\marginpar{Internship!}. An alternative for static control
section, is to use the interface with PoCC (see Section~\ref{subsection-prettyprinter-pocc}).
\end{PipsPass}
\begin{PipsMake}
nest_parallelization > MODULE.parallelized_code
< PROGRAM.entities
< MODULE.code MODULE.dg
\end{PipsMake}
\subsection{Coerce Parallel Code into Sequential Code}
\label{sec:cons-parall-code}
\begin{PipsPass}{internalize_parallel_code}
To simplify the user interface and to display with one click a
parallelized program, programs in PIPS are {\em parallelized code}
instead of standard {\em code}.\marginpar{PV:not clear} As a consequence, parallelized
programs cannot be further analyzed and transformed because sequential
code and parallelized code do not have the same resource type. Most
pipsmake rules apply to {\em code} but not to {\em parallelized
code}. Unfortunately, improving the parallelized code with some other
transformations such as dead-code elimination is also useful. Thus
this pseudo-transformation is added to coerce a parallel code into a
classical (sequential) one. Parallelization is made an internal code
transformation in PIPS with this rule.
Although this is not the effective process, parallel loops are tagged
as parallel and loop local variables may be added in a {\em code}
resource because of a previous privatization phase.
If you display the ``generated'' code, it may not be displayed as a
parallel one if the \PipsPropRef{PRETTYPRINT_SEQUENTIAL_STYLE} is set
to a parallel output style (such as \texttt{omp}). Anyway, the information
is available in {\em code}.
Note this transformation may no be usable with some special
parallelizations in PIPS such as WP65 or HPFC that generate other resource
types that may be quite different.
\end{PipsPass}
\begin{PipsMake}
internalize_parallel_code > MODULE.code
< MODULE.parallelized_code
\end{PipsMake}
\subsection{Detect Computation Intensive Loops}
\begin{PipsPass}{computation_intensity}
Generate a pragma on each loop that seems to be computation intensive according to a simple cost model.
\end{PipsPass}
The computation intensity is derived from the complexity and the memory footprint.
It assumes the cost model:
$$execution\_time = startup\_overhead + \frac{memory\_footprint}{bandwidth} + \frac{complexity}{frequency}$$
A loop is marked with pragma \PipsPropRef{COMPUTATION_INTENSITY_PRAGMA} if the communication costs are lower
than the execution cost as given by \PipsPassRef{uniform_complexities}.
\begin{PipsMake}
computation_intensity > MODULE.code
< MODULE.code
< MODULE.regions
< MODULE.complexities
\end{PipsMake}
This correspond to the transfer startup overhead.
Time unit is the same as in complexities.
\begin{PipsProp}{COMPUTATION_INTENSITY_STARTUP_OVERHEAD}
COMPUTATION_INTENSITY_STARTUP_OVERHEAD 10
\end{PipsProp}
This corresponds to the memory bandwidth in octet per time unit.
\begin{PipsProp}{COMPUTATION_INTENSITY_BANDWIDTH}
COMPUTATION_INTENSITY_BANDWIDTH 100
\end{PipsProp}
And This is the processor frequency, in operation per time unit.
\begin{PipsProp}{COMPUTATION_INTENSITY_FREQUENCY}
COMPUTATION_INTENSITY_FREQUENCY 1000
\end{PipsProp}
This is the generated pragma.
\begin{PipsProp}{COMPUTATION_INTENSITY_PRAGMA}
COMPUTATION_INTENSITY_PRAGMA "pips intensive loop"
\end{PipsProp}
Those values have limited meaning here, only their ratio have some.
Having \PipsPropRef{COMPUTATION_INTENSITY_FREQUENCY} and \PipsPropRef{COMPUTATION_INTENSITY_BANDWIDTH}
of the same magnitude clearly limits the number of generated pragmas\dots
\subsection{Limit parallelism using complexity}
\label{sec:limit_parallelism_using_complexity}
\begin{PipsPass}{limit_parallelism_using_complexity}
Parallel loops which are considered as not complex enough are
replaced by sequential ones using a simple cost model based on
complexity (see \PipsPassRef{uniform_complexities}).
\end{PipsPass}
\begin{PipsMake}
limit_parallelism_using_complexity > MODULE.code
< MODULE.code
< MODULE.complexities
\end{PipsMake}
\subsection{Limit Parallelism in Parallel Loop Nests}
\label{sec:manage-parallel-loops}
\begin{PipsPass}{limit_nested_parallelism}
This phase restricts the parallelism of parallel do-loop nests by
limiting the number of top-level parallel do-loops to be below a given
limit. The too many innermost parallel loops are replaced by sequential
loops, if any. This is useful to keep enough coarse-grain parallelism
and respecting some hardware or optimization constraints. For example on
GPU, in CUDA there is a 2D limitation on grids of thread blocks, in
OpenCL it is limited to 3D. Of course, since the phase works onto
parallel loop nest, it might be interesting to use a parallelizing phase
such as \texttt{internalize\_parallel\_code} (see
\S~\ref{sec:cons-parall-code}) or coarse grain parallelization before
applying \texttt{limit\_nested\_parallelism}.
\end{PipsPass}
\begin{PipsMake}
limit_nested_parallelism > MODULE.code
< MODULE.code
\end{PipsMake}
PIPS relies on the property \PipsPropRef{NESTED_PARALLELISM_THRESHOLD} to
determine the desired level of nested parallelism.
\begin{PipsProp}{NESTED_PARALLELISM_THRESHOLD}
NESTED_PARALLELISM_THRESHOLD 0
\end{PipsProp}
\section{SIMDizer for SIMD Multimedia Instruction Set}
\index{Superword parallelism}
\index{Atomizer}
\index{SLP}
\index{SSE}
\index{Scalar Renaming}
The SAC project aims at generating efficient code for processors with
SIMD extension instruction set such as VMX, SSE4, etc. which are also
refered to as Superword Level Parallelism (SLP). For more information,
see \url{https://info.enstb.org/projets/sac}, or better, see Serge
Guelton's PhD dissertation.
Some phases use \PipsPropRef{ACCEL_LOAD} and \PipsPropRef{ACCEL_STORE}
to generate DMA calls and \PipsPropRef{ACCEL_WORK}.
\begin{PipsProp}{ACCEL_LOAD}
ACCEL_LOAD "SIMD_LOAD"
\end{PipsProp}
\begin{PipsProp}{ACCEL_STORE}
ACCEL_STORE "SIMD_STORE"
\end{PipsProp}
\begin{PipsProp}{ACCEL_WORK}
ACCEL_WORK "SIMD_"
\end{PipsProp}
\subsection{SIMD Atomizer}
\begin{PipsPass}{simd_atomizer}
Here is yet another atomizer, based on {\tt new\_atomizer} (see
Section~\ref{subsubsection:limited-atomizer}), used to reduce
complex statements to three-address code close to assembly
code. There are only some minor differences with respect to {\tt
new\_atomizer}, except that it does not break down {\em simple}
expressions, that is, expressions that are the sum of a reference
and a constant such as {tt i+1}. This is needed to generate code
that could potentially be efficient, whereas the original atomizer
would most of the time generate inefficient code.
\end{PipsPass}
\begin{PipsMake}
alias simd_atomizer 'SIMD Atomizer'
simd_atomizer > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Use the \PipsPropRef{SIMD_ATOMIZER_ATOMIZE_REFERENCE} property to make the SIMD Atomizer go wild: unlike other atomizer, it will break
the content of a reference.
\PipsPropRef{SIMD_ATOMIZER_ATOMIZE_LHS} can be used to tell the atomizer to atomize both lhs and rhs.
\begin{PipsProp}{SIMD_ATOMIZER_ATOMIZE_REFERENCE}
SIMD_ATOMIZER_ATOMIZE_REFERENCE FALSE
\end{PipsProp}
\begin{PipsProp}{SIMD_ATOMIZER_ATOMIZE_LHS}
SIMD_ATOMIZER_ATOMIZE_LHS FALSE
\end{PipsProp}
The \PipsPropRef{SIMD_OVERRIDE_CONSTANT_TYPE_INFERENCE} property is used by the SAC library to know if it must override C constant type inference.
In \texttt{C}, an integer constant always as the minimum size needed to hold its value, starting from an \lstinline|int|. In sac we may want to have it converted to a smaller size, in situation like \lstinline|char b;/*...*/;char a = 2 + b;|. Otherwise the result of \lstinline|2+b| is considered as an \lstinline|int|.
if \PipsPropRef{SIMD_OVERRIDE_CONSTANT_TYPE_INFERENCE} is set to \texttt{TRUE}, the result of \lstinline|2+b| will be a \lstinline|char|.
\begin{PipsProp}{SIMD_OVERRIDE_CONSTANT_TYPE_INFERENCE}
SIMD_OVERRIDE_CONSTANT_TYPE_INFERENCE FALSE
\end{PipsProp}
\subsection{Loop Unrollling for SIMD Code Generation}
\index{Loop Unroll}
\begin{PipsPass}{simdizer_auto_unroll}
Tries to unroll the code for making the simdizing process more efficient. It thus tries to compute
the optimal unroll factor, allowing to pack the most instructions together.
Sensible to \PipsPropRef{SIMDIZER_AUTO_UNROLL_MINIMIZE_UNROLL} and \PipsPropRef{SIMDIZER_AUTO_UNROLL_SIMPLE_CALCULATION}.
\end{PipsPass}
\begin{PipsMake}
alias simdizer_auto_unroll 'SIMD-Auto Unroll'
simdizer_auto_unroll > MODULE.code
< PROGRAM.simd_treematch
< PROGRAM.simd_operator_mappings
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{loop_auto_unroll}
Similiar to \PipsPassRef{simdizer_auto_unroll} but at the loop level.
\end{PipsPass}
Sensible to \PipsPropRef{LOOP_LABEL}.
\begin{PipsMake}
loop_auto_unroll > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Tiling for SIMD Code Generation}
\index{Tiling}
\index{Loop Tiling}
\begin{PipsPass}{simdizer_auto_tile}
Tries to tile the code to make the simdizing process more efficient.
\end{PipsPass}
Sensible to \PipsPropRef{LOOP_LABEL} to select the loop nest to tile.
\begin{PipsMake}
simdizer_auto_tile > MODULE.code
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.code
\end{PipsMake}
\subsection{Preprocessing of Reductions for SIMD Code Generation}
\index{Reduction}
\begin{PipsPass}{simd_remove_reductions}
This phase tries to pre-process reductions, so that they can be
vectorized efficiently by the \PipsPassRef{simdizer} phase. When multiple
reduction statements operating on the same variable with the same
operation are detected inside a loop body, each ``instance'' of the
reduction is renamed, and some code is added before and after the loop
to initialize the new variables and compute the final result.
\end{PipsPass}
\begin{PipsMake}
alias simd_remove_reductions 'SIMD Remove Reductions'
simd_remove_reductions > MODULE.code
> MODULE.callees
! MODULE.simdizer_init
< PROGRAM.entities
< MODULE.cumulated_reductions
< MODULE.code
< MODULE.dg
\end{PipsMake}
\begin{PipsProp}{SIMD_REMOVE_REDUCTIONS_PREFIX}
SIMD_REMOVE_REDUCTIONS_PREFIX "RED"
\end{PipsProp}
\begin{PipsProp}{SIMD_REMOVE_REDUCTIONS_PRELUDE}
SIMD_REMOVE_REDUCTIONS_PRELUDE ""
\end{PipsProp}
\begin{PipsProp}{SIMD_REMOVE_REDUCTIONS_POSTLUDE}
SIMD_REMOVE_REDUCTIONS_POSTLUDE ""
\end{PipsProp}
\subsection{Redundant Load-Store Elimination}
\index{Redudant Load-Store Elimination}
\begin{PipsPass}{redundant_load_store_elimination}
Remove useless load store calls (and more).
\end{PipsPass}
\begin{PipsMake}
redundant_load_store_elimination > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.out_regions
< MODULE.chains
\end{PipsMake}
If \PipsPropRef{REDUNDANT_LOAD_STORE_ELIMINATION_CONSERVATIVE} is set to false,
\PipsPassRef{redundant_load_store_elimination} will remove any statement not implied in the computation of out regions, otherwise it will not remove statement that modifies aprameters reference.
\begin{PipsProp}{REDUNDANT_LOAD_STORE_ELIMINATION_CONSERVATIVE}
REDUNDANT_LOAD_STORE_ELIMINATION_CONSERVATIVE TRUE
\end{PipsProp}
\subsection{Undo Some Atomizer Transformations (?)}
\begin{PipsPass}{deatomizer}
...
\end{PipsPass}
\begin{PipsMake}
alias deatomizer 'Deatomizer'
deatomizer > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.dg
\end{PipsMake}
\subsection{If Conversion}
\index{If Conversion}
\begin{PipsPass}{if_conversion_init}
This phase is the first phase of the if-conversion algorithm. The complete
if conversion algorithm is performed by applying the three following
phase: \PipsPassRef{if_conversion_init}, \PipsPassRef{if_conversion} and
\PipsPassRef{if_conversion_compact}.
\end{PipsPass}
Use \PipsPropRef{IF_CONVERSION_INIT_THRESHOLD} to control whether if conversion will occur or not:
beyhond this number of call, no conversion is done.
\begin{PipsProp}{IF_CONVERSION_INIT_THRESHOLD}
IF_CONVERSION_INIT_THRESHOLD 40
\end{PipsProp}
\begin{PipsMake}
alias if_conversion_init 'If-conversion init'
if_conversion_init > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.summary_complexity
\end{PipsMake}
\begin{PipsPass}{if_conversion}
This phase is the second phase of the if-conversion algorithm. The
complete if conversion algorithm is performed by applying the three
following phase: \PipsPassRef{if_conversion_init}, \PipsPassRef{if_conversion} and
\PipsPassRef{if_conversion_compact}.
\end{PipsPass}
\begin{PipsProp}{IF_CONVERSION_PHI}
IF_CONVERSION_PHI "__C-conditional__"
\end{PipsProp}
\begin{PipsMake}
alias if_conversion 'If-conversion'
if_conversion > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\begin{PipsPass}{if_conversion_compact}
This phase is the third phase of the \emph{if-conversion} algorithm. The
complete if conversion algorithm is performed by applying the three
following phase: \PipsPassRef{if_conversion_init}, \PipsPassRef{if_conversion} and
\PipsPassRef{if_conversion_compact}.
\end{PipsPass}
\begin{PipsMake}
alias if_conversion_compact 'If-conversion compact'
if_conversion_compact > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.dg
\end{PipsMake}
% +if_conversion_compact > MODULE.code
% + > MODULE.calles
% + < PROGRAM.entities
% + < MODULE.code
% + < MODULE.dg
% + < MODULE.proper_effects
\begin{PipsPass}{loop_nest_unswitching}
Converts max in loop bounds into tests. Also sets variable so that
\PipsPassRef{simplify_control} works afterwards.
\end{PipsPass}
\subsection{Loop Unswitching}
\begin{PipsPass}{loop_nest_unswitching}
This phase apply loop distribution on a loop-invariant test. So it
transforms a loop with an if/then/else inside into an if/then/else with
the loop duplicated into the ``then'' and ``else'' branches.
\end{PipsPass}
\begin{PipsMake}
loop_nest_unswitching > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Scalar Renaming}
\begin{PipsPass}{scalar_renaming}
The Scalar Renaming pass tries to minimize dependencies in the code by
renaming scalars when legal.
\end{PipsPass}
\begin{PipsMake}
scalar_renaming > MODULE.code
< PROGRAM.entities
< MODULE.dg
< MODULE.proper_effects
\end{PipsMake}
\subsection{Tree Matching for SIMD Code Generation}
\begin{PipsPass}{simd_treematcher}
This function initialize a treematch used by \PipsPassRef{simdizer} for simd-oriented pattern matching
\end{PipsPass}
\begin{PipsMake}
simd_treematcher > PROGRAM.simd_treematch
\end{PipsMake}
\begin{PipsPass}{simd_operator_mappings}
This function initialize operator matchings used by \PipsPassRef{simdizer} for simd-oriented pattern matching
\end{PipsPass}
\begin{PipsMake}
simd_operator_mappings > PROGRAM.simd_operator_mappings
\end{PipsMake}
\begin{PipsMake}
simdizer_init > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{simdizer}
Function \PipsPassRef{simdizer} is an attempt at generating SIMD code for SIMD
multimedia instruction set such as MMX, SSE2, VIS,... This
transformation performs the core vectorization, transforming sequences
of similar statements into vector operations.
\end{PipsPass}
\begin{PipsMake}
alias simdizer 'Generate SIMD code'
simdizer > MODULE.code
> MODULE.callees
> PROGRAM.entities
! MODULE.simdizer_init
< PROGRAM.simd_treematch
< PROGRAM.simd_operator_mappings
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
When set to true, following property tells the simdizer to try to padd arrays when it seems to be profitable
\begin{PipsProp}{SIMDIZER_ALLOW_PADDING}
SIMDIZER_ALLOW_PADDING FALSE
\end{PipsProp}
Skip generation of load and stores, using generic functions instead.
\begin{PipsProp}{SIMDIZER_GENERATE_DATA_TRANSFERS}
SIMDIZER_GENERATE_DATA_TRANSFERS TRUE
\end{PipsProp}
\begin{PipsPass}{simd_memory_packing}
This phase is to be called after simdization of affectation operator.
It performs type substitution from char/short array to in array
using the packing from the simdization phase
For example, four consecutive load from a char array could be a single load from an int array.
This prove to be useful for \textit{c to vhdl} compilers such as \texttt{c2h}.
\end{PipsPass}
\begin{PipsMake}
alias simd_memory_packing 'Generate Optimized Load Store'
simd_memory_packing > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{SIMD properties}
This property is used to set the target register size, expressed in
bits, for places where this is needed (for instance, auto-unroll with
simple algorithm).
\begin{PipsProp}{SAC_SIMD_REGISTER_WIDTH}
SAC_SIMD_REGISTER_WIDTH 64
\end{PipsProp}
\subsubsection{Auto-Unroll}
This property is used to control how the auto unroll phase computes
the unroll factor. By default, the minimum unroll factor is used. It
is computed by using the minimum of the optimal factor for each
statement. If the property is set to FALSE, then the maximum unroll
factor is used instead.
\begin{PipsProp}{SIMDIZER_AUTO_UNROLL_MINIMIZE_UNROLL}
SIMDIZER_AUTO_UNROLL_MINIMIZE_UNROLL TRUE
\end{PipsProp}
This property controls how the ``optimal'' unroll factor is
computed. Two algorithms can be used. By default, a simple algorithm
is used, which simply compares the actual size of the variables used
to the size of the registers to find out the best unroll factor.
If the property is set to FALSE, a more complex algorithm is used,
which takes into account the actual SIMD instructions.
\begin{PipsProp}{SIMDIZER_AUTO_UNROLL_SIMPLE_CALCULATION}
SIMDIZER_AUTO_UNROLL_SIMPLE_CALCULATION TRUE
\end{PipsProp}
\subsubsection{Memory Organisation}
This property is used by the sac library to know which elements of
multi-dimensional array are consecutive in memory. Let us consider the
three following references \lstinline|a(i,j,k)|, \lstinline|a(i,j,k+1)|
and \lstinline|a(i+1,j,k)|. Then, if \PipsPropRef{SIMD_FORTRAN_MEM_ORGANISATION}
is set to \texttt{TRUE}, it means that \lstinline|a(i,j,k)| and
\lstinline|a(i+1,j,k)| are consecutive in memory but \lstinline|a(i,j,k)|
and \lstinline|a(i,j,k+1)| are not. However, if
\PipsPropRef{SIMD_FORTRAN_MEM_ORGANISATION} is set to \texttt{FALSE},
\lstinline|a(i,j,k)| and \lstinline|a(i,j,k+1)| are consecutive in memory
but \lstinline|a(i,j,k)| and \lstinline|a(i+1,j,k)| are not.
\begin{PipsProp}{SIMD_FORTRAN_MEM_ORGANISATION}
SIMD_FORTRAN_MEM_ORGANISATION TRUE
\end{PipsProp}
\subsubsection{Pattern file}
This property is used by the sac library to know the path of the pattern definition file.
If the file is not found, the execution fails.
\begin{PipsProp}{SIMD_PATTERN_FILE}
SIMD_PATTERN_FILE "patterns.def"
\end{PipsProp}
\section{Code Distribution}
\label{subsection-code-distribution}
\index{Distribution}
\index{Automatic Distribution}
Different automatic code distribution techniques are implemented in \Pips{} for
distributed-memory machines. The first one is based on the emulation of
a shared-memory. The second one is based on HPF. A third one target
architectures with hardware coprocessors. Another one is currently
developed at IT Sud Paris that generate MPI code from OpenMP one.
\subsection{Shared-Memory Emulation}
\label{subsubsection-shared-memory-emulation}
\index{Emulated Shared Memory}
\index{Software Caching}
\index{WP65}
\WPsc{}~\cite{IA91,IA92a,IA92b} produces a new version of a module
transformed to be executed on a distributed memory machine. Each module
is transformed into two modules. One module, \texttt{wp65\_compute\_file},
performs the computations, while the other one, \texttt{wp65\_bank\_file},
emulates a shared memory.
This rule does not have data structure outputs, as the two new program
generated have computed names. This does not fit the \Pipsmake{} framework
too well, but is OK as long as nobody wishes to apply \Pips{} on the
generated code, e.g. to propagate constant or eliminate dead code.
Note that use-use dependencies are used to allocate temporary arrays in
local memory (i.e. in the software cache).
This compilation scheme was designed by Corinne \textsc{Ancourt} and Fran\c{c}ois
\textsc{Irigoin}. It uses theoretical results in~\cite{AI91}. Its input is a very
small subset of Fortran program (e.g. procedure calls are not supported).
It was implemented by the designers, with help from Lei \textsc{Zhou}.
\begin{PipsMake}
alias wp65_compute_file 'Distributed View'
alias wp65_bank_file 'Bank Distributed View'
wp65 > MODULE.wp65_compute_file
> MODULE.wp65_bank_file
! MODULE.privatize_module
< PROGRAM.entities
< MODULE.code
< MODULE.dg
< MODULE.cumulated_effects
< MODULE.chains
< MODULE.proper_effects
\end{PipsMake}
Name of the file for the target model:
\begin{PipsProp}{WP65_MODEL_FILE}
WP65_MODEL_FILE "model.rc"
\end{PipsProp}
\subsection{HPF Compiler}
\label{subsubsection-hpf-compiler}
\index{HPF}
\index{HPFC}
The \HPFcompiler{} is a project by itself, developed by Fabien
\textsc{Coelho} in the \Pips{} framework.
A whole set of rules is used by the \Pips{} \HPFcompiler{}, \HPFC{}. By
the way, the whole compiler is just a big hack according to Fabien
\textsc{Coelho}.
\subsubsection{HPFC Filter}
The first rule is used to apply a shell to put HPF-directives in an f77 parsable form.
Some shell script based on sed is used. The \PipsPassRef{hpfc_parser} must be
called to analyze the right file. This is triggered automatically by the
bang selection in the \PipsPassRef{hpfc_close} phase.
\begin{PipsPass}{hpfc_filter}
\end{PipsPass}
\begin{PipsMake}
hpfc_filter > MODULE.hpfc_filtered_file
< MODULE.source_file
\end{PipsMake}
\subsubsection{HPFC Initialization}
The second HPFC rule is used to initialize the hpfc status and other data
structures global to the compiler. The HPF compiler
status is bootstrapped. The compiler status stores (or should store) all relevant
information about the HPF part of the program (data distribution, IO
functions and so on).
\begin{PipsMake}
hpfc_init > PROGRAM.entities
> PROGRAM.hpfc_status
< PROGRAM.entities
\end{PipsMake}
\subsubsection{HPF Directive removal}
This phase removes the directives (some special calls) from the code.
The remappings (implicit or explicit) are also managed at this level,
through copies between differently shaped arrays.
To manage calls with distributed arguments, I need to apply the directive
extraction bottom-up, so that the callers will know about the callees
through the \texttt{hpfc\_status}. In order to do that, I first thought of an
intermediate resource, but there was obscure problem with my fake calls.
Thus the dependence static then dynamic directive analyses is enforced at
the bang sequence request level in the \PipsPassRef{hpfc_close} phase.
\begin{PipsPass}{hpfc_static_directives}
The \PipsPassRef{hpfc_static_directives} phase analyses static mapping directives
for the specified module.
\end{PipsPass}
\begin{PipsPass}{hpfc_dynamic_directives}
The \PipsPassRef{hpfc_dynamic_directives} phase does
manages realigns and function calls with prescriptive argument
mappings.
\end{PipsPass}
In order to do so it needs its callees' required mappings, hence
the need to analyze beforehand static directives. The code is cleaned from
the \PipsPassRef{hpfc_filter} artifacts after this phase, and all the proper
information about the HPF stuff included in the routines is stored in
\texttt{hpfc\_status}.
\begin{PipsMake}
hpfc_static_directives > MODULE.code
> PROGRAM.hpfc_status
< PROGRAM.entities
< PROGRAM.hpfc_status
< MODULE.code
hpfc_dynamic_directives > MODULE.code
> PROGRAM.hpfc_status
< PROGRAM.entities
< PROGRAM.hpfc_status
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\subsubsection{HPFC actual compilation}
This rule launches the actual compilation. Four files are generated:
\begin{enumerate}
\item the host code that mainly deals with I/Os,
\item the SPMD node code,
\item and some initialization stuff for the runtime (2 files).
\end{enumerate}
Between this phase and the previous
one, many PIPS standard analyses are performed, especially the regions and
preconditions. Then this phase will perform the actual translation of the
program into a host and SPMD node code.
\begin{PipsMake}
hpfc_compile > MODULE.hpfc_host
> MODULE.hpfc_node
> MODULE.hpfc_parameters
> MODULE.hpfc_rtinit
> PROGRAM.hpfc_status
< PROGRAM.entities
< PROGRAM.hpfc_status
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.code
< MODULE.cumulated_references
< CALLEES.hpfc_host
\end{PipsMake}
\subsubsection{HPFC completion}
\begin{PipsPass}{hpfc_close}
This rule deals with the compiler closing. It must deal with commons.
The hpfc parser selection is put here.
\end{PipsPass}
%% Maybe not a very good idea? (FC: explain! why not in \verb/hpfc_init/?)
%% I guess nobody should have to require intermediate targets such as ???. Ya!
%% \marginpar{RK: hmmm; FC?}
\begin{PipsMake}
hpfc_close > PROGRAM.hpfc_commons
! SELECT.hpfc_parser
! SELECT.must_regions
! ALL.hpfc_static_directives
! ALL.hpfc_dynamic_directives
< PROGRAM.entities
< PROGRAM.hpfc_status
< MAIN.hpfc_host
\end{PipsMake}
\subsubsection{HPFC install}
This rule performs the installation of HPFC generated files in a separate
directory. This rule is added to make hpfc usable from wpips and epips. I
got problems with the make and run rules, because it was trying to
recompute everything from scratch. To be investigated later on.
\begin{PipsMake}
hpfc_install > PROGRAM.hpfc_installation
< PROGRAM.hpfc_commons
hpfc_make
hpfc_run
\end{PipsMake}
\subsubsection{HPFC {\em High Performance Fortran Compiler} properties}
\index{HPF}
\index{HPFC\_EXPAND\_COMPUTE\_LOCAL\_INDEX}
\index{HPFC\_EXPAND\_COMPUTE\_COMPUTER}
\index{HPFC\_EXPAND\_COMPUTE\_OWNER}
\index{HPFC\_EXPAND\_CMPLID}
\index{HPFC\_NO\_WARNING}
\index{HPFC\_FILTER\_CALLEES}
\index{GLOBAL\_EFFECTS\_TRANSLATION}
\index{HPFC\_SYNCHRONIZE\_IO}
\index{HPFC\_IGNORE\_MAY\_IN\_IO}
\index{HPFC\_LAZY\_MESSAGES}
\index{HPFC\_IGNORE\_FCD\_SYNCHRO}
\index{HPFC\_IGNORE\_FCD\_TIME}
\index{HPFC\_IGNORE\_FCD\_SET}
\index{HPFC\_TIME\_REMAPPINGS}
\index{HPFC\_REDUNDANT\_SYSTEMS\_FOR\_REMAPS}
\index{HPFC\_OPTIMIZE\_REMAPPINGS}
\index{HPFC\_DYNAMIC\_LIVENESS}
\index{HPFC\_GUARDED\_TWINS}
\index{HPFC\_BUFFER\_SIZE}
\index{HPFC\_USE\_BUFFERS}
\index{HPFC\_IGNORE\_IN\_OUT\_REGIONS}
\index{HPFC\_EXTRACT\_EQUALITIES}
\index{HPFC\_EXTRACT\_LATTICE}
Debugging levels considered by HPFC:
\verb+HPFC_{,DIRECTIVES,IO,REMAPPING}_DEBUG_LEVEL+.
These booleans control whether some computations are directly
generated in the output code, or computed through calls to dedicated
runtime functions. The default is the direct expansion.
\begin{PipsProp}{HPFC_EXPAND_COMPUTE_LOCAL_INDEX}
HPFC_EXPAND_COMPUTE_LOCAL_INDEX TRUE
\end{PipsProp}
\begin{PipsProp}{HPFC_EXPAND_COMPUTE_COMPUTER}
HPFC_EXPAND_COMPUTE_COMPUTER TRUE
\end{PipsProp}
\begin{PipsProp}{HPFC_EXPAND_COMPUTE_OWNER}
HPFC_EXPAND_COMPUTE_OWNER TRUE
\end{PipsProp}
\begin{PipsProp}{HPFC_EXPAND_CMPLID}
HPFC_EXPAND_CMPLID TRUE
\end{PipsProp}
\begin{PipsProp}{HPFC_NO_WARNING}
HPFC_NO_WARNING FALSE
\end{PipsProp}
Hacks control\ldots
\begin{PipsProp}{HPFC_FILTER_CALLEES}
HPFC_FILTER_CALLEES FALSE
\end{PipsProp}
\begin{PipsProp}{GLOBAL_EFFECTS_TRANSLATION}
GLOBAL_EFFECTS_TRANSLATION TRUE
\end{PipsProp}
These booleans control the I/O generation.
\begin{PipsProp}{HPFC_SYNCHRONIZE_IO}
HPFC_SYNCHRONIZE_IO FALSE
\end{PipsProp}
\begin{PipsProp}{HPFC_IGNORE_MAY_IN_IO}
HPFC_IGNORE_MAY_IN_IO FALSE
\end{PipsProp}
Whether to use lazy or non-lazy communications
\begin{PipsProp}{HPFC_LAZY_MESSAGES}
HPFC_LAZY_MESSAGES TRUE
\end{PipsProp}
Whether to ignore FCD (Fabien Coelho Directives\ldots) or not. These
directives are used to instrument the code for testing purposes.
\begin{PipsProp}{HPFC_IGNORE_FCD_SYNCHRO}
HPFC_IGNORE_FCD_SYNCHRO FALSE
\end{PipsProp}
\begin{PipsProp}{HPFC_IGNORE_FCD_TIME}
HPFC_IGNORE_FCD_TIME FALSE
\end{PipsProp}
\begin{PipsProp}{HPFC_IGNORE_FCD_SET}
HPFC_IGNORE_FCD_SET FALSE
\end{PipsProp}
Whether to measure and display the compilation times for remappings,
and whether to generate outward redundant code for remappings. Also
whether to generate code that keeps track dynamically of live mappings.
Also whether not to send data to a twin (a processor that holds the very
same data for a given array).
\begin{PipsProp}{HPFC_TIME_REMAPPINGS}
HPFC_TIME_REMAPPINGS FALSE
\end{PipsProp}
\begin{PipsProp}{HPFC_REDUNDANT_SYSTEMS_FOR_REMAPS}
HPFC_REDUNDANT_SYSTEMS_FOR_REMAPS FALSE
\end{PipsProp}
\begin{PipsProp}{HPFC_OPTIMIZE_REMAPPINGS}
HPFC_OPTIMIZE_REMAPPINGS TRUE
\end{PipsProp}
\begin{PipsProp}{HPFC_DYNAMIC_LIVENESS}
HPFC_DYNAMIC_LIVENESS TRUE
\end{PipsProp}
\begin{PipsProp}{HPFC_GUARDED_TWINS}
HPFC_GUARDED_TWINS TRUE
\end{PipsProp}
Whether to use the local buffer management. 1 MB of buffer is allocated.
\begin{PipsProp}{HPFC_BUFFER_SIZE}
HPFC_BUFFER_SIZE 1000000
\end{PipsProp}
\begin{PipsProp}{HPFC_USE_BUFFERS}
HPFC_USE_BUFFERS TRUE
\end{PipsProp}
Whether to use in and out convex array regions for input/output compiling
\begin{PipsProp}{HPFC_IGNORE_IN_OUT_REGIONS}
HPFC_IGNORE_IN_OUT_REGIONS TRUE
\end{PipsProp}
Whether to extract more equalities from a system, if possible.
\begin{PipsProp}{HPFC_EXTRACT_EQUALITIES}
HPFC_EXTRACT_EQUALITIES TRUE
\end{PipsProp}
Whether to try to extract the underlying lattice when generating code for
systems with equalities.
\begin{PipsProp}{HPFC_EXTRACT_LATTICE}
HPFC_EXTRACT_LATTICE TRUE
\end{PipsProp}
\subsection{STEP: MPI code generation from OpenMP programs}
\label{sec:step:-mpi-code}
\index{MPI}
\index{OpenMP}
\marginpar{RK: IT SudParis : insert your documentation here; FI: or a
pointer towards you documentation}
\subsubsection{STEP Directives}
\begin{PipsPass}{step_parser}
The \PipsPassRef{step_parser} phase identifies the OpenMP
constructs. The directive semantics are stored in the
\texttt{MODULE.step\_directives} ressource.
\end{PipsPass}
\begin{PipsMake}
step_parser > MODULE.step_directives
> MODULE.code
< MODULE.code
\end{PipsMake}
\subsubsection{STEP Analysis}
\begin{PipsPass}{step_analyse_init}
The \PipsPassRef{step_analyse_init} phase init the
\texttt{PROGRAM.step\_comm} ressources
\end{PipsPass}
\begin{PipsMake}
step_analyse_init > PROGRAM.step_comm
\end{PipsMake}
\begin{PipsPass}{step_analyse}
The \PipsPassRef{step_analyse} phase triggers the convex array
regions analyses to compute SEND and RECV regions leading to MPI
messages and checks whether a given SEND region corresponding to a
directive construct is consumed by a RECV region corresponding to a
directive construct. In this case, communications can be optimized.
\end{PipsPass}
\begin{PipsMake}
step_analyse > PROGRAM.step_comm
> MODULE.step_send_regions
> MODULE.step_recv_regions
< PROGRAM.entities
< PROGRAM.step_comm
< MODULE.step_directives
< MODULE.code
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< MODULE.chains
< CALLEES.code
< CALLEES.step_send_regions
< CALLEES.step_recv_regions
\end{PipsMake}
\subsubsection{STEP code generation}
Based on the OpenMP construct and analyses, new modules are generated
to translate the original code with OpenMP directives. The default
code transformation for OpenMP construct is driven by the
\PipsPropRef{STEP_DEFAULT_TRANSFORMATION} property. The different value
allowed are :
\begin{itemize}
\item \verb+"HYBRID"+ : for OpenMP and MPI parallel code
\item \verb+"MPI"+ : for MPI parallel code
\item \verb+"OMP"+ : for OpenMP parallel code
\end{itemize}
\begin{PipsProp}{STEP_DEFAULT_TRANSFORMATION}
STEP_DEFAULT_TRANSFORMATION "HYBRID"
\end{PipsProp}
\begin{PipsPass}{step_compile}
The \PipsPassRef{step_compile} phase generates source code for OpenMP
constructs depending of the transformation desired. Each OpenMP
construct could have a specific transformation define by STEP
clauses (without specific clauses, the
\PipsPropRef{STEP_DEFAULT_TRANSFORMATION} is used).
The specific STEP clauses allowed are :
\begin{itemize}
\item \verb+"!\$step hybrid"+ : for OpenMP and MPI parallel code
\item \verb+"!\$step no\_mpi"+ : for OpenMP parallel code
\item \verb+"!\$step mpi"+ : for MPI parallel code
\item \verb+"!\$step ignore"+ : for sequential code
\end{itemize}
\end{PipsPass}
\begin{PipsMake}
step_compile > MODULE.step_file
< PROGRAM.entities
< PROGRAM.step_comm
< MODULE.step_directives
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{step_install}
The \PipsPassRef{step_install} phase copy the generated source files
in the directory specified by the \PipsPropRef{STEP_INSTALL_PATH}
property.
\end{PipsPass}
\begin{PipsMake}
step_install
< ALL.step_file
\end{PipsMake}
\begin{PipsProp}{STEP_INSTALL_PATH}
STEP_INSTALL_PATH ""
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% PHRASE
\subsection{PHRASE: high-level language transformation for partial evaluation in reconfigurable logic}
\label{subsubsection-phrase-code-distribution}
\index{Code Distribution}
\index{PHRASE}
The PHRASE project is an attempt to automatically (or semi-automatically)
transform high-level language programs into code with partial execution on
some accelerators such as reconfigurable logic (such as FPGAs) or
data-paths.
This phases allow to split the code into portions of code delimited by
PHRASE-pragma (written by the programmer) and a control program managing
them. Those portions of code are intended, after transformations, to be
executed in reconfigurable logic. In the PHRASE project, the
reconfigurable logic is synthesized with the Madeo tool that take
SmallTalk code as input. This is why we have a SmallTalk pretty-printer
(see section~\ref{subsection-prettyprinters-smalltalk}).
\subsubsection{Phrase Distributor Initialisation}
\index{Phrase Distributor Initialisation}
\begin{PipsPass}{phrase_distributor_init}
This phase is a preparation phase for the Phrase Distributor
\PipsPassRef{phrase_distributor}: the portions of code to externalize are
identified and isolated here. Comments are modified by this phase.
\end{PipsPass}
\begin{PipsMake}
alias phrase_distributor_init 'PHRASE Distributor initialization'
phrase_distributor_init > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
This phase is automatically called by the following
\PipsPassRef{phrase_distributor}.
\subsubsection{Phrase Distributor}
\index{Phrase Distributor}
\begin{PipsPass}{phrase_distributor}
The job of distribution is done here. This phase should be applied after
the initialization (Phrase Distributor Initialisation
\PipsPassRef{phrase_distributor_init}), so this one is automatically applied
first.
\end{PipsPass}
\begin{PipsMake}
alias phrase_distributor 'PHRASE Distributor'
phrase_distributor > MODULE.code
> MODULE.callees
! MODULE.phrase_distributor_init
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< MODULE.out_regions
< MODULE.dg
\end{PipsMake}
\subsubsection{Phrase Distributor Control Code}
\index{Phrase Distributor Control Code}
\begin{PipsPass}{phrase_distributor_control_code}
This phase add control code for PHRASE distribution. All calls to
externalized code portions are transformed into START and WAIT calls.
Parameters communication (send and receive) are also handled here
\end{PipsPass}
\begin{PipsMake}
alias phrase_distributor_control_code 'PHRASE Distributor Control Code'
phrase_distributor_control_code > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< MODULE.out_regions
< MODULE.dg
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% SAFESCALE
\subsection{Safescale}
\label{subsubsection_safescale_module_analysis}
\index{Safescale}
\index{Kaapi}
The Safescale project is an attempt to automatically (or semi-automatically)
transform sequential code written in C language for the Kaapi runtime.
\subsubsection{Distribution init}
\index{Distribution init}
\begin{PipsPass}{saferscale_distributor_init}
This phase is intended for the analysis of a module given with the aim of finding
blocks of code delimited by specific pragmas from it.
\end{PipsPass}
\begin{PipsMake}
alias safescale_distributor_init 'Safescale distributor init'
safescale_distributor_init > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{Statement Externalization}
\index{Statement externalization}
\begin{PipsPass}{safescale_distributor}
This phase is intended for the externalization of a block of code.
\end{PipsPass}
\begin{PipsMake}
alias safescale_distributor 'Safescale distributor'
safescale_distributor > MODULE.code
> MODULE.callees
! MODULE.safescale_distributor_init
< PROGRAM.entities
< MODULE.code
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
\end{PipsMake}
\subsection{CoMap: Code Generation for Accelerators with DMA}
\label{sec:comap:-code}
\subsubsection{Phrase Remove Dependences}
\index{Phrase Remove Dependences}
\begin{PipsMake}
alias phrase_remove_dependences 'Phrase Remove Dependences'
phrase_remove_dependences > MODULE.code
> MODULE.callees
! MODULE.phrase_distributor_init
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< MODULE.out_regions
< MODULE.dg
\end{PipsMake}
\subsubsection{Phrase comEngine Distributor}
\index{Phrase comEngine Distributor}
\begin{PipsPass}{phrase_comEngine_distributor}
This phase should be applied after the initialization (Phrase Distributor
Initialisation or \PipsPassRef{phrase_distributor_init}). The job of comEngine
distribution is done here.
\end{PipsPass}
\begin{PipsMake}
alias phrase_comEngine_distributor 'PHRASE comEngine Distributor'
phrase_comEngine_distributor > MODULE.code
> MODULE.callees
! MODULE.phrase_distributor_init
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< MODULE.out_regions
< MODULE.dg
< MODULE.summary_complexity
\end{PipsMake}
\subsubsection{PHRASE ComEngine properties}
This property is set to TRUE if we want to synthesize only one
process on the HRE.
\begin{PipsProp}{COMENGINE_CONTROL_IN_HRE}
COMENGINE_CONTROL_IN_HRE TRUE
\end{PipsProp}
This property holds the fifo size of the ComEngine.
\begin{PipsProp}{COMENGINE_SIZE_OF_FIFO}
COMENGINE_SIZE_OF_FIFO 128
\end{PipsProp}
% no longer used {
% This property holds the number of fifos in the ComEngine.
% \begin{PipsProp}{COMENGINE_NUMBER_OF_FIFO}
% COMENGINE_NUMBER_OF_FIFO 100
% \end{PipsProp}
%
% \begin{PipsProp}{COMENGINE_BUFFER_HRE_INTERFACE}
% COMENGINE_BUFFER_HRE_INTERFACE TRUE
% \end{PipsProp}
% }
\subsection{Parallelization for Terapix architecture}
\index{Terapix}
\subsubsection{Isolate Statement}
\begin{PipsPass}{isolate_statement}
Isolate the statement given in \PipsPropRef{ISOLATE_STATEMENT_LABEL} in a separated memory.
Data transfer are generated using the same DMA as \PipsPassRef{kernel_load_store}.
\end{PipsPass}
The algorithm is based on Read and write regions (no in / out yet) to compute
the data that must be copied and allocated.
Rectangular hull of regions are used to match allocator and data transfers prototypes.
If an analysis fails, definition regions are use instead.
If a sizeof is involved, \PipsPropRef{EVAL_SIZEOF} must be set to true.
\begin{PipsMake}
isolate_statement > MODULE.code
> MODULE.callees
< MODULE.code
< MODULE.regions
< PROGRAM.entities
\end{PipsMake}
\begin{PipsProp}{ISOLATE_STATEMENT_LABEL}
ISOLATE_STATEMENT_LABEL ""
\end{PipsProp}
As a side effect of isolate\_statement pass, some new variables are declared
into the function. A prefix can be used for the names of those variables
using the property \texttt{ISOLATE\_STATEMENT\_VAR\_PREFIX}. It is also possible to
insert a suffix using the property \texttt{ISOLATE\_STATEMENT\_VAR\_SUFFIX}.
The suffix will be inserted between the original variable name
and the instance number of the copy.
\begin{PipsProp}{ISOLATE_STATEMENT_VAR_PREFIX}
ISOLATE_STATEMENT_VAR_PREFIX ""
\end{PipsProp}
\begin{PipsProp}{ISOLATE_STATEMENT_VAR_SUFFIX}
ISOLATE_STATEMENT_VAR_SUFFIX ""
\end{PipsProp}
By default we cannot isolate a statement with some complex effects on
the non local memory. But if we know we can (for example ), we can override this
behaviour by setting the following property:
\begin{PipsProp}{ISOLATE_STATEMENT_EVEN_NON_LOCAL}
ISOLATE_STATEMENT_EVEN_NON_LOCAL FALSE
\end{PipsProp}
\subsubsection{GPU XML Output}
\begin{PipsPass}{gpu_xml_dump}
Dump XML for a function, intended to be used for SPEAR. Track back the
parameters that are used for the iteration space.
\end{PipsPass}
\begin{PipsMake}
gpu_xml_dump > MODULE.gpu_xml_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{Delay Communications}
\begin{PipsPass}{delay_communications_inter}
Optimize the load/store dma by delaying the stores and
performing the stores as soon as possible. Interprocedural version.
\end{PipsPass}
It uses \PipsPropRef{ACCEL_LOAD} and \PipsPropRef{ACCEL_STORE}
to distinguish loads and stores from other calls.
The communication elimination makes the assumption that a load/store pair can always be removed.
\begin{PipsMake}
delay_communications_inter > MODULE.code
> MODULE.callees
! CALLEES.delay_communications_inter
! MODULE.delay_load_communications_inter
! MODULE.delay_store_communications_inter
< PROGRAM.entities
< MODULE.code
< MODULE.regions
< MODULE.dg
\end{PipsMake}
% must do this behind the back of pipsmake because of fortran
%> COMPILATION_UNIT.code
%< COMPILATION_UNIT.code
\begin{PipsMake}
delay_load_communications_inter > MODULE.code
> MODULE.callees
> CALLERS.code
> CALLERS.callees
< PROGRAM.entities
< MODULE.code
< CALLERS.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
% must do this behind the back of pipsmake because of fortran
%> COMPILATION_UNIT.code
%< COMPILATION_UNIT.code
\begin{PipsMake}
delay_store_communications_inter > MODULE.code
> MODULE.callees
> CALLERS.code
> CALLERS.callees
< PROGRAM.entities
< MODULE.code
< CALLERS.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
\begin{PipsPass}{delay_communications_intra}
Optimize the load/store dma by delaying the stores and
performing the stores as soon as possible.
Intra Procedural version.
\end{PipsPass}
It uses \PipsPropRef{ACCEL_LOAD} and \PipsPropRef{ACCEL_STORE}
to distinguish loads and stores from other calls.
The communication elimination makes the assumption that a load/store pair can always be removed.
\begin{PipsMake}
delay_communications_intra > MODULE.code
> MODULE.callees
! MODULE.delay_load_communications_intra
! MODULE.delay_store_communications_intra
< PROGRAM.entities
< MODULE.code
< MODULE.regions
< MODULE.dg
\end{PipsMake}
% must do this behind the back of pipsmake because of fortran
%> COMPILATION_UNIT.code
%< COMPILATION_UNIT.code
\begin{PipsMake}
delay_load_communications_intra > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
% must do this behind the back of pipsmake because of fortran
%> COMPILATION_UNIT.code
%< COMPILATION_UNIT.code
\begin{PipsMake}
delay_store_communications_intra > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
\subsubsection{Hardware Constraints Solver}
\begin{PipsPass}{solve_hardware_constraints}
if \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_TYPE} is set to \textbf{VOLUME},
Given a loop label, a maximum memory footprint and an unknown entity,
try to find the best value for \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_UNKNOWN}
to make memory footprint of \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_LABEL}
reach but not exceed \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_LIMIT}.
If it is set to \textbf{NB\_PROC}, it tries to find the best value for \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_UNKNOWN}
to make the maximum range of first dimension of all regions accessed by \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_LABEL} equals to \PipsPropRef{SOLVE_HARDWARE_CONSTRAINTS_LIMIT}.
\end{PipsPass}
\begin{PipsMake}
solve_hardware_constraints > MODULE.code
< MODULE.code
< MODULE.regions
< PROGRAM.entities
\end{PipsMake}
\begin{PipsProp}{SOLVE_HARDWARE_CONSTRAINTS_LABEL}
SOLVE_HARDWARE_CONSTRAINTS_LABEL ""
\end{PipsProp}
\begin{PipsProp}{SOLVE_HARDWARE_CONSTRAINTS_LIMIT}
SOLVE_HARDWARE_CONSTRAINTS_LIMIT 0
\end{PipsProp}
\begin{PipsProp}{SOLVE_HARDWARE_CONSTRAINTS_UNKNOWN}
SOLVE_HARDWARE_CONSTRAINTS_UNKNOWN ""
\end{PipsProp}
\begin{PipsProp}{SOLVE_HARDWARE_CONSTRAINTS_TYPE}
SOLVE_HARDWARE_CONSTRAINTS_TYPE ""
\end{PipsProp}
\subsubsection{kernelize}
Bootstraps the kernel ressource
\begin{PipsMake}
bootstrap_kernels > PROGRAM.kernels
\end{PipsMake}
\begin{PipsPass}{flag_kernel}
Add a kernel to the list of kernels known to pips
\end{PipsPass}
\begin{PipsMake}
flag_kernel > PROGRAM.kernels
< PROGRAM.kernels
\end{PipsMake}
\begin{PipsPass}{kernel_load_store}
Generate unoptimized load / store information for each call to the module.
\end{PipsPass}
\begin{PipsMake}
kernel_load_store > CALLERS.code
> CALLERS.callees
> PROGRAM.kernels
< PROGRAM.kernels
< CALLERS.code
< CALLERS.regions
< CALLERS.preconditions
\end{PipsMake}
The legacy \PipsPassRef{kernel_load_store} approach is limited because it generates the DMA around a call, and \PipsPassRef{isolate_statement} engine does not perform well in interprocedural.
The following properties are used to specify the names of runtime
functions. Since they are used in Par4All, their default names begin with
\verb|P4A_|. To have an idea about their prototype, have a look to the
Par4All accelerator runtime or in
\texttt{validation/AcceleratorUtils/include/par4all.c}.
Enable/disable the scalar handling by kernel load store.
\begin{PipsProp}{KERNEL_LOAD_STORE_SCALAR}
KERNEL_LOAD_STORE_SCALAR FALSE
\end{PipsProp}
The \PipsPropRef{ISOLATE_STATEMENT_EVEN_NON_LOCAL} property can be used to
force the generation even with non local memory access. But beware it
would not solve all the issues...
The following properties can be used to customized the allocate/load/store functions:
\begin{PipsProp}{KERNEL_LOAD_STORE_ALLOCATE_FUNCTION}
KERNEL_LOAD_STORE_ALLOCATE_FUNCTION "P4A_accel_malloc"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_DEALLOCATE_FUNCTION}
KERNEL_LOAD_STORE_DEALLOCATE_FUNCTION "P4A_accel_free"
\end{PipsProp}
The following properties are used to name the \textsc{dma} functions to
use for scalars:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION}
KERNEL_LOAD_STORE_LOAD_FUNCTION "P4A_copy_to_accel"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION}
KERNEL_LOAD_STORE_STORE_FUNCTION "P4A_copy_from_accel"
\end{PipsProp}
and for 1-dimension arrays:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION_1D}
KERNEL_LOAD_STORE_LOAD_FUNCTION_1D "P4A_copy_to_accel_1d"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION_1D}
KERNEL_LOAD_STORE_STORE_FUNCTION_1D "P4A_copy_from_accel_1d"
\end{PipsProp}
and in 2 dimensions:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION_2D}
KERNEL_LOAD_STORE_LOAD_FUNCTION_2D "P4A_copy_to_accel_2d"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION_2D}
KERNEL_LOAD_STORE_STORE_FUNCTION_2D "P4A_copy_from_accel_2d"
\end{PipsProp}
and in 3 dimensions:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION_3D}
KERNEL_LOAD_STORE_LOAD_FUNCTION_3D "P4A_copy_to_accel_3d"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION_3D}
KERNEL_LOAD_STORE_STORE_FUNCTION_3D "P4A_copy_from_accel_3d"
\end{PipsProp}
and in 4 dimensions:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION_4D}
KERNEL_LOAD_STORE_LOAD_FUNCTION_4D "P4A_copy_to_accel_4d"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION_4D}
KERNEL_LOAD_STORE_STORE_FUNCTION_4D "P4A_copy_from_accel_4d"
\end{PipsProp}
and in 5 dimensions:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION_5D}
KERNEL_LOAD_STORE_LOAD_FUNCTION_5D "P4A_copy_to_accel_5d"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION_5D}
KERNEL_LOAD_STORE_STORE_FUNCTION_5D "P4A_copy_from_accel_5d"
\end{PipsProp}
and in 6 dimensions:
\begin{PipsProp}{KERNEL_LOAD_STORE_LOAD_FUNCTION_6D}
KERNEL_LOAD_STORE_LOAD_FUNCTION_6D "P4A_copy_to_accel_6d"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_STORE_FUNCTION_6D}
KERNEL_LOAD_STORE_STORE_FUNCTION_6D "P4A_copy_from_accel_6d"
\end{PipsProp}
As a side effect of kernel load store pass, some new variables are declared
into the function. A prefix can be used for the names of those variables
using the property \PipsPropRef{KERNEL_LOAD_STORE_VAR_PREFIX}. It is also possible to
insert a suffix using the property \PipsPropRef{KERNEL_LOAD_STORE_VAR_PREFIX}.
The suffix will be inserted between the original variable name
and the instance number of the copy.
\begin{PipsProp}{KERNEL_LOAD_STORE_VAR_PREFIX}
KERNEL_LOAD_STORE_VAR_PREFIX "p4a_var_"
\end{PipsProp}
\begin{PipsProp}{KERNEL_LOAD_STORE_VAR_SUFFIX}
KERNEL_LOAD_STORE_VAR_SUFFIX ""
\end{PipsProp}
\begin{PipsPass}{kernelize}
Split a parallel loop with a local index into three parts: a host side
part, a kernel part and an intermediate part.
The intermediate part simulates the parallel code to the kernel from the host
\end{PipsPass}
\begin{PipsMake}
kernelize > MODULE.code
> MODULE.callees
> PROGRAM.kernels
! MODULE.privatize_module
! MODULE.coarse_grain_parallelization
< PROGRAM.entities
< MODULE.code
< PROGRAM.kernels
\end{PipsMake}
The property \PipsPropRef{KERNELIZE_NBNODES} is used to set the number of nodes for this kernel.
\PipsPropRef{KERNELIZE_KERNEL_NAME} is used to set the name of generated kernel.
\PipsPropRef{KERNELIZE_HOST_CALL_NAME} is used to set the name of generated call to kernel (host side).
\begin{PipsProp}{KERNELIZE_NBNODES}
KERNELIZE_NBNODES 128
\end{PipsProp}
\begin{PipsProp}{KERNELIZE_KERNEL_NAME}
KERNELIZE_KERNEL_NAME ""
\end{PipsProp}
\begin{PipsProp}{KERNELIZE_HOST_CALL_NAME}
KERNELIZE_HOST_CALL_NAME ""
\end{PipsProp}
%\begin{PipsPass}{terapixify}
%Function \verb+terapixify+ targets the {\em Terapix} multiprocessor from Thales.
%This vector architecture require the generation of micro-codes (a.k.a ''kernels'' in the GPU terminology).
%A microcode is a code portion that will be executed symmetrically on all processors of the machines.
%They only work on parallel loops and can contain inner loops, but no branching.
%This pass basically picks a parallel loop, strip-mines it and apply outlining to the tiled loop.
%It then performs basic validity checks on resulting code to make sure it's a valid microcode.
%
%\textbf{Warning: this transformation should be applied to a loop nest, and the loop nest should be strip-mined before calling this}
%\end{PipsPass}
%
%\begin{PipsMake}
%terapixify > MODULE.code
% ! MODULE.kernelize
% ! MODULE.outline
% < PROGRAM.entities
% < MODULE.code
% < MODULE.cumulated_effects
%\end{PipsMake}
%
%The property \verb+OUTLINE_MODULE_NAME+ will be used as microcode name.
%If not set, it will be asked for interactively.
%The property \verb+OUTLINE_LABEL+ is used to select a statement.
%If \verb+OUTLINE_LOOP_STATEMENT+ is set to \verb+TRUE+ and \verb+OUTLINE_LABEL+ is a loop, the loop body is selected instead of the loop itself.
\begin{PipsProp}{OUTLINE_LOOP_STATEMENT}
OUTLINE_LOOP_STATEMENT FALSE
\end{PipsProp}
\begin{PipsPass}{group_constants}
Gather all constants from a module and put them in a single array.
Relevant for Terapix code generation, and maybe for other accelerators as well
\end{PipsPass}
\begin{PipsMake}
group_constants > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.regions
\end{PipsMake}
You may want to group constants only for a particular statement, in that case use \PipsPropRef{GROUP_CONSTANTS_STATEMENT_LABEL}
\begin{PipsProp}{GROUP_CONSTANTS_STATEMENT_LABEL}
GROUP_CONSTANTS_STATEMENT_LABEL ""
\end{PipsProp}
The way variables are grouped is control by \PipsPropRef{GROUP_CONSTANTS_LAYOUT},
the only relevant value as of now is \texttt{"terapix"}.
\begin{PipsProp}{GROUP_CONSTANTS_LAYOUT}
GROUP_CONSTANTS_LAYOUT ""
\end{PipsProp}
The name of the variable holding constants can be set using \PipsPropRef{GROUP_CONSTANTS_HOLDER}.
\begin{PipsProp}{GROUP_CONSTANTS_HOLDER}
GROUP_CONSTANTS_HOLDER "caillou"
\end{PipsProp}
You may want to skip loop bounds from the grouping
\begin{PipsProp}{GROUP_CONSTANTS_SKIP_LOOP_RANGE}
GROUP_CONSTANTS_SKIP_LOOP_RANGE FALSE
\end{PipsProp}
You may want to skip litterals too.
\begin{PipsProp}{GROUP_CONSTANTS_LITERAL}
GROUP_CONSTANTS_LITERAL TRUE
\end{PipsProp}
\begin{PipsPass}{normalize_microcode}
Perform various checks on a Terapix microcode to make sure it can be
synthesized.
\PipsPropRef{GROUP_CONSTANTS_HOLDER} is used to differentiate mask and image.
\end{PipsPass}
\begin{PipsMake}
normalize_microcode > MODULE.code
> CALLERS.code
> COMPILATION_UNIT.code
< PROGRAM.entities
< MODULE.code
< MODULE.callers
< MODULE.cumulated_effects
\end{PipsMake}
\begin{PipsPass}{terapix_warmup}
normalize array access in a loop nest for terapixification.
\end{PipsPass}
This pass is meaningless for any other target :(.
\begin{PipsMake}
terapix_warmup > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{terapix_remove_divide}
converts divide operator into multiply operator using formula
$a/cste = a* (1/b) \simeq a * ( 128 / cste ) / 128$
\end{PipsPass}
\begin{PipsMake}
terapix_remove_divide > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Use this property for accuracy of divide to multiply conversion.
\begin{PipsProp}{TERAPIX_REMOVE_DIVIDE_ACCURACY}
TERAPIX_REMOVE_DIVIDE_ACCURACY 4
\end{PipsProp}
\subsubsection{Communication Generation}
\begin{PipsPass}{kernel_data_mapping}
This phase computes the mapping of data on the accelarators. It records the set
of data that have to be copied on the GPU before each statement in the module,
and the set of data that have to be copied back from the GPU after the execution
of each statement.
Then according to this information, the copy-in and copy-out transfers are
generated using same set of properties as \PipsPassRef{kernel_load_store}.
This work has been described in~\cite{AIK11}\cite{ACIK11}. However, the implementation
is more complex than the published equations because of PIPS' HCFG and because
of a heuristic to generate transfers as high as possible in the HCFG.
\end{PipsPass}
\begin{PipsMake}
alias kernel_data_mapping "Kernel data mapping"
kernel_data_mapping > MODULE.kernel_copy_in
> MODULE.kernel_copy_out
< PROGRAM.entities
< PROGRAM.kernels
< MODULE.code
< MODULE.summary_effects
< MODULE.cumulated_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< MODULE.callees
< MODULE.callers
< CALLEES.kernel_copy_out
< CALLEES.kernel_copy_in
\end{PipsMake}
\begin{PipsPass}{wrap_kernel_argument}
This phase wrap argument at call site with an access function. The wrapper name
is controlled with \PipsPropRef{WRAP_KERNEL_ARGUMENT_FUNCTION_NAME}. Currently
the purpose of this is to insert call to a runtime to resolve addresses in
accelerator memory corresponding to addresses in host memory.
\begin{PipsProp}{WRAP_KERNEL_ARGUMENT_FUNCTION_NAME}
WRAP_KERNEL_ARGUMENT_FUNCTION_NAME "P4A_runtime_host_ptr_to_accel_ptr"
\end{PipsProp}
\end{PipsPass}
\begin{PipsMake}
alias wrap_kernel_argument "wrap_kernel_argument"
wrap_kernel_argument > CALLERS.code
> CALLERS.callees
< PROGRAM.entities
< CALLERS.code
< CALLERS.callees
< MODULE.callers
\end{PipsMake}
\subsection{Code Distribution on GPU}
\label{sec:code-distr-gpu}
\begin{PipsPass}{gpu_ify}
This phase generate GPU kernels from perfect parallel loop nests.
\PipsPropRef{GPU_IFY_ANNOTATE_LOOP_NESTS} property triggers automatically the
annotation of the loop nest (see \PipsPassRef{gpu_loop_nest_annotate}).
\end{PipsPass}
\begin{PipsProp}{GPU_IFY_ANNOTATE_LOOP_NESTS}
GPU_IFY_ANNOTATE_LOOP_NESTS FALSE
\end{PipsProp}
\begin{PipsMake}
alias gpu_ify 'Distribute // loop nests on GPU'
gpu_ify > MODULE.code
> MODULE.callees
> PROGRAM.entities
< MODULE.privatized
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
For example from
\begin{lstlisting}
for(i = 1; i <= 499; i += 1)
for(j = 1; j <= 499; j += 1)
save[i][j] = 0.25*(space[i-1][j]+space[i+1][j]+space[i][j-1]+space[i][j+1]);
\end{lstlisting}
it generates something like
\begin{lstlisting}
p4a_kernel_launcher_0(save, space);
[...]
void p4a_kernel_launcher_0(float_t save[501][501], float_t space[501][501])
{
int i;
int j;
for(i = 1; i <= 499; i += 1)
for(j = 1; j <= 499; j += 1)
p4a_kernel_wrapper_0(save, space, i, j);
}
void p4a_kernel_wrapper_0(float_t save[501][501], float_t space[501][501], int i, int j)
{
i = P4A_pv_0(i);
j = P4A_pv_1(j);
p4a_kernel_0(save, space, i, j);
}
void p4a_kernel_0(float_t save[501][501], float_t space[501][501], int
i, int j) {
save[i][j] = 0.25*(space[i-1][j]+space[i+1][j]+space[i][j-1]+space[i][j+1]);
}
\end{lstlisting}
The launcher, wrapper and kernel prefix names to be used during the generation:
\begin{PipsProp}{GPU_LAUNCHER_PREFIX}
GPU_LAUNCHER_PREFIX "p4a_launcher"
\end{PipsProp}
\begin{PipsProp}{GPU_WRAPPER_PREFIX}
GPU_WRAPPER_PREFIX "p4a_wrapper"
\end{PipsProp}
\begin{PipsProp}{GPU_KERNEL_PREFIX}
GPU_KERNEL_PREFIX "p4a_kernel"
\end{PipsProp}
This boolean property control wherever the outliner use the original function
name as a suffix instead of only numerical suffix.
\begin{PipsProp}{GPU_OUTLINE_SUFFIX_WITH_OWNER_NAME}
GPU_OUTLINE_SUFFIX_WITH_OWNER_NAME TRUE
\end{PipsProp}
For Fortran output you may need to have these prefix name in uppercase.
Indeed, each level of outlining can be enabled or disabled according to
the following properties:
\begin{PipsProp}{GPU_USE_LAUNCHER}
GPU_USE_LAUNCHER TRUE
\end{PipsProp}
\begin{PipsProp}{GPU_USE_WRAPPER}
GPU_USE_WRAPPER TRUE
\end{PipsProp}
\begin{PipsProp}{GPU_USE_KERNEL}
GPU_USE_KERNEL TRUE
\end{PipsProp}
Each generated function can go in its own source file according to the
following properties:
\begin{PipsProp}{GPU_USE_KERNEL_INDEPENDENT_COMPILATION_UNIT}
GPU_USE_KERNEL_INDEPENDENT_COMPILATION_UNIT FALSE
\end{PipsProp}
\begin{PipsProp}{GPU_USE_LAUNCHER_INDEPENDENT_COMPILATION_UNIT}
GPU_USE_LAUNCHER_INDEPENDENT_COMPILATION_UNIT FALSE
\end{PipsProp}
\begin{PipsProp}{GPU_USE_WRAPPER_INDEPENDENT_COMPILATION_UNIT}
GPU_USE_WRAPPER_INDEPENDENT_COMPILATION_UNIT FALSE
\end{PipsProp}
By default they are set to \texttt{FALSE} for languages like CUDA that
allow kernel and host codes mixed in a same file but for OpenCL it is not
the case.
When the original code is in Fortran it might be useful to wrap the kernel
launcher in an independent C file. The
\PipsPropRef{GPU_USE_FORTRAN_WRAPPER} can be used for that purpose. The name of
the function wrapper can be configured using the property
\PipsPropRef{GPU_FORTRAN_WRAPPER_PREFIX}. As specified before it is safe to use
prefix name in uppercase.
\begin{PipsProp}{GPU_USE_FORTRAN_WRAPPER}
GPU_USE_FORTRAN_WRAPPER FALSE
\end{PipsProp}
\begin{PipsProp}{GPU_FORTRAN_WRAPPER_PREFIX}
GPU_FORTRAN_WRAPPER_PREFIX "P4A_FORTRAN_WRAPPER"
\end{PipsProp}
The phase generates a wrapper function to get the iteration coordinate from
intrinsics functions instead of the initial loop indices. Using this kind
of wrapper is the normal behaviour but for simulation of an accelerator
code, not using a wrapper is useful.
The intrinsics function names to get an $i^{th}$ coordinate in the
iteration space are defined by this GNU \emph{\`a la} \texttt{printf}
format:
\begin{PipsProp}{GPU_COORDINATE_INTRINSICS_FORMAT}
GPU_COORDINATE_INTRINSICS_FORMAT "P4A_vp_%d"
\end{PipsProp}
where \verb|%d| is used to get the dimension number. Here \texttt{vp}
stands for \emph{virtual processor} dimension and is a reminiscence from
PompC and HyperC...
Please, do not use this feature for buffer-overflow attack...
\begin{PipsPass}{gpu_loop_nest_annotate}
Annotates loop nests with comments and guards for further generation of CUDA calls.
\end{PipsPass}
\begin{PipsMake}
alias gpu_loop_nest_annotate 'Decorate loop nests with iteration spaces and add iteration clamping'
gpu_loop_nest_annotate > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
To annotate only outer parallel loop nests, set the following variable to true:
\begin{PipsProp}{GPU_LOOP_NEST_ANNOTATE_PARALLEL}
GPU_LOOP_NEST_ANNOTATE_PARALLEL TRUE
\end{PipsProp}
\begin{PipsPass}{gpu_clear_annotations_on_loop_nest}
Clear annotation previously added by \PipsPassRef{gpu_loop_nest_annotate}.
\end{PipsPass}
\begin{PipsMake}
alias gpu_clear_annotations_on_loop_nest 'Clear annotation previously added by gpu_loop_nest_annotate'
gpu_clear_annotations_on_loop_nest > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{gpu_parallelize_annotated_loop_nest}
Parallelize annotated loop nests based on the sentinel comments.
\end{PipsPass}
\begin{PipsMake}
gpu_parallelize_annotated_loop_nest > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{one_thread_parallelize}
This phase promote a whole function body into a parallel loop with one thread.
\end{PipsPass}
\begin{PipsMake}
one_thread_parallelize > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{gpu_promote_sequential}
This phase promote sequential code in GPU kernels to avoid memory transfers.
\end{PipsPass}
\begin{PipsMake}
gpu_promote_sequential > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{gpu_qualify_pointers}
OpenCL 1.X requires function parameters to be qualified as either
\emph{local} or \emph{global}, and this information must be propagated
in local declarations within functions.
\end{PipsPass}
\begin{PipsMake}
gpu_qualify_pointers > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.callees
\end{PipsMake}
Note: this pass does mostly changes entities (parameter types,
variable types).
%%
Only casts in the code may be affected.
Whether to add qualifiers to pointer casts:
\begin{PipsProp}{GPU_QUALIFY_POINTERS_DO_CASTS}
GPU_QUALIFY_POINTERS_DO_CASTS TRUE
\end{PipsProp}
\subsection{Task code generation for StarPU runtime}
\label{subsection-stapu-taskify}
\begin{PipsPass}{taskify}
This pass outlines code parts so that every single piece of computation is
located in a function that makes no use of global or static variable.
Heuristic is trivial for now, this is an experimental work.
\PipsPassRef{TASKIFY_TASK_PREFIX}.
\end{PipsPass}
\begin{PipsMake}
taskify > MODULE.code
> MODULE.callees
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.privatized
< MODULE.regions
\end{PipsMake}
\begin{PipsProp}{TASKIFY_TASK_PREFIX}
TASKIFY_TASK_PREFIX "P4A_task"
\end{PipsProp}
\begin{PipsPass}{generate_starpu_pragma}
This pass generates pragmas for the StarPU GCC plugin. This is still
experimental, so is the GCC plugin.
\end{PipsPass}
\begin{PipsMake}
generate_starpu_pragma > MODULE.code
> MODULE.callees
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.privatized
< MODULE.regions
\end{PipsMake}
\subsection{SCALOPES: task code generation for the SCMP architecture with SESAM HAL}
\label{subsection-scalopes-project}
The SCMP architecture, an asymmetric multiprocessor system-on-chip for
dynamic applications, is described in~\cite{Ventroux2010}. SESAM is a
simulation tool built up to help the design of such architectures. It
relies on a specific programming model based on the explicit
separation of the control and computation tasks, and its HAL provides
high level memory allocation, shared memory access and synchronization
functions.
The goal of the project was to generate applications for this
architecture from sequential C code. Two different approaches were
implemented. The first tries to identify tasks but is more
specific. The second one is more general but tasks must have been
previously identified with labels; this is currently performed
manually.
\subsubsection{First approach}
The goal of the following phase is to generate SCMP tasks from C
functions. The tasks are linked and scheduled using the SCMP Hardware
Adaptation Layer (HAL). Pass \PipsPassRef{sesamify} takes as input a
module and analyzes all its callees. For instance, the 'main' module
can be submitted to sesamify after the \PipsPassRef{gpu_ify} or
\PipsPassRef{scalopragma} pass have been applied. Each analyzed module
is transformed into a SCMP task if its name begins with
\texttt{P4A\_scmp\_task}. To generate the final files for the SCMP
simulator, the pass output must be transformed by a specific python
parser.
\begin{PipsPass}{scalopragma}
This pass outlines code parts based on pragma.
It can outline blocs or loops with a \verb=#pragma scmp task= flag.
It is based on the outline pass.
\end{PipsPass}
\begin{PipsMake}
scalopragma > MODULE.code
> MODULE.callees
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\begin{PipsPass}{scalopify}
The goal of Bufferization is to generate a dataflow communication
through buffers between modules. The communication is done by
special function call generated by
\PipsPassRef{kernel_load_store}. To keep flows consistent outside
the module \PipsPassRef{scalopify} surrounds variable call with a
special function too. A C file with stubs is needed.
Note that you must also set
\PipsPropRef{KERNEL_LOAD_STORE_DEALLOCATE_FUNCTION} to
\lstinline|""| in order to have it generate relevant code.
The goal of this pass is to keep consistent flows outside the tasks.
\end{PipsPass}
\begin{PipsMake}
scalopify > MODULE.code
> MODULE.callees
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\begin{PipsPass}{sesamify}
\end{PipsPass}
\begin{PipsMake}
sesamify > MODULE.code
> MODULE.callees
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{General Solution}
This code generation flow first relies on phase
\PipsPassRef{isolate_statement} to isolate the memory spaces of tasks
identified by labels beginning by
\PipsPropRef{SCALOPES_KERNEL_TASK_PREFIX}. Then phase
\PipsPassRef{sesam_buffers_processing} generates a header file
describing how kernel and server tasks use the SESAM shared buffers. A
post-processing phase is necessary to actually generate all the tasks
of the distributed application. This is implemented in Par4All.
This solution is extensively described in~\cite{Creu11a}. A less
technical presentation can be found in~\cite{Ventroux2012}.
\begin{PipsPass}{sesam_buffers_processing}
Phase \texttt{sesam\_buffers\_processing} is to be run after
\texttt{isolate\_statement} has been applied to all tasks
statements. It then produces a header file to be included by the
future SESAM application individual tasks. This header file describes
how kernel and server tasks use the SESAM buffers.
\end{PipsPass}
\begin{PipsMake}
sesam_buffers_processing > MODULE.sesam_buffers_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
The next two properties are used by phase
\texttt{sesam\_buffers\_processing} to detect kernel tasks statements
in the input module and to generate server tasks names in the output
header file.
\begin{PipsProp}{SCALOPES_KERNEL_TASK_PREFIX}
SCALOPES_KERNEL_TASK_PREFIX "P4A_sesam_task_"
\end{PipsProp}
\begin{PipsProp}{SCALOPES_SERVER_TASK_PREFIX}
SCALOPES_SERVER_TASK_PREFIX "P4A_sesam_server_"
\end{PipsProp}
\clearpage
\section{Automatic Resource-Constrained Static Task Parallelization}
\label{subsubsection-task-parallelization}
\subsection{Sequence Dependence DAG (SDG)}
A Sequence Dependence DAG $G$ is a data dependence DAG where task vertices $\tau$ are labeled with statements, while control dependences are encoded in the abstract syntax trees of statements. Any statement $S$ can label a DAG vertex, i.e. each vertex $\tau$ contains a statement $S$, which corresponds to the code it runs when scheduled. An SDG is not built only on simple instructions, represented as $call$ statements; compound statements such as test statements (both true and false branches) and loop nests may constitute indivisible vertices of the SDG
\begin{PipsPass}{sequence_dependence_graph}
Phase \texttt{sequence\_dependence\_graph} generates the Sequence
Dependence Graph (SDG) in the dg ressource and in a dot file.
\end{PipsPass}
\begin{PipsMake}
sequence_dependence_graph > MODULE.sdg
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.dg
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< MODULE.transformers
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{BDSC-Based Hierarchical Task Parallelization (HBDSC)}
The goal of the following phase is to generate the scheduled task
graph using BDSC: A Ressource-Constrained Scheduling Algorithm for
Shared and Distributed Memory Systems, in order
to automate the task-based parallelization of sequential
applications.
\begin{PipsPass}{hbdsc_parallelization}
Phase \texttt{bdsc\_kdg\_parallelization} applies BDSC and generates
the scheduled Clustered Dependence Graph (KDG) in the dg ressource and
in a dot file.
\end{PipsPass}
\begin{PipsMake}
hbdsc_parallelization > MODULE.sdg
< PROGRAM.entities > MODULE.schedule
< MODULE.code
< MODULE.proper_effects
< MODULE.sdg
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< MODULE.complexities
< MODULE.transformers
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
The next properties are used by Phase \texttt{bdsc\_kdg\_parallelization} to
permit the user defining the number of clusters and the memory size based
on the properties of the target architecture, generating communications or not
in SPIRE code.
\begin{PipsProp}{BDSC_NB_CLUSTERS}
BDSC_NB_CLUSTERS 4
\end{PipsProp}
\begin{PipsProp}{BDSC_MEMORY_SIZE}
BDSC_MEMORY_SIZE -1
\end{PipsProp}
\begin{PipsProp}{BDSC_DISTRIBUTED_MEMORY}
BDSC_DISTRIBUTED_MEMORY TRUE
\end{PipsProp}
In order to control the granularity of parallel tasks, we introduce
this property. By default, we generate the maximum parallelism in a
code. Otherwise, i.e. COSTLY\_TASKS\_ONLY value is TRUE, only loops and call
functions are generated as parallel tasks. This is important in order
to make a trade-off between the cost of thread creation and task execution.
\begin{PipsProp}{COSTLY_TASKS_ONLY}
COSTLY_TASKS_ONLY FALSE
\end{PipsProp}
This property is used to evaluate BDSC scheduling robustness. Since
our BDSC scheduling heuristic relies on the numerical approximations
of the execution time and communication costs of tasks, one needs to
assess its sensitivity over the accuracy of these estimations. Since a
mathematical analysis of this issue is made difficult by the heuristic
nature of BDSC and, in fact, of scheduling processes in general, we
ran multiple versions of each application using various static
execution and communication cost models using a biased BDSC cost
model, where we modulated each execution time and communication cost
value randomly by at most $\Delta$\%, that is our propertu BDSC\_SENSITIVITY (the default BDSC cost model would thus correspond to $\Delta = 0$).
\begin{PipsProp}{BDSC_SENSITIVITY}
BDSC_SENSITIVITY 0
\end{PipsProp}
\begin{PipsPass}{bdsc_code_instrumentation}
We represent cost, data and time information of different tasks in
terms of polynomials. We instrument using the phase \texttt{bdsc\_code\_instrumentation} the input sequential code and run
it once in order to obtain the numerical values of the polynomials.
The instrumented code contains the initial user code plus instructions
that compute the values of the cost polynomials for each statement.
\end{PipsPass}
\begin{PipsMake}
bdsc_code_instrumentation > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.chains
< MODULE.sdg
< MODULE.regions
< MODULE.complexities
\end{PipsMake}
The next property is used also by Phase \texttt{bdsc\_kdg\_parallelization}. It
decides if cost, data and time information will be extracted from the
result of the instrumentation which is a dynamic analysis: \texttt{BDSC\_INSTRUMENTED\_FILE} file or
not, i.e, static analysis.
\begin{PipsProp}{BDSC_INSTRUMENTED_FILE}
BDSC_INSTRUMENTED_FILE ""
\end{PipsProp}
\begin{PipsPass}{dsc_code_parallelization}
We add this pass since we use in our expriments, comparison between
DSC and BDSC. In order to make this comparison automatic and simple,
we apply Phase \texttt{dsc\_code\_parallelization} that performs DSC algorithm
instead of BDSC algorithm and generates the parallel code SPIRE.
\end{PipsPass}
\begin{PipsMake}
dsc_code_parallelization > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.dg
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< MODULE.complexities
< MODULE.transformers
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{SPIRE(PIPS) generation}
The parallel code is represented using SPIRE of PIPS: A Generic
Sequential to Parallel Intermediate Representation Extension applied
to PIPS.
\begin{PipsPass}{spire_shared_unstructured_to_structured}
Phase \texttt{spire\_shared\_unstructured\_to\_structured} applies BDSC and generates the parallel code SPIRE.
\end{PipsPass}
\begin{PipsMake}
spire_shared_unstructured_to_structured > MODULE.shared_spire_code
< PROGRAM.entities > MODULE.code
< MODULE.code
< MODULE.sdg
< MODULE.schedule
\end{PipsMake}
\begin{PipsPass}{spire_distributed_unstructured_to_structured}
Phase \texttt{spire\_distributed\_unstructured\_to\_structured}
applies BDSC, generates the parallel code SPIRE (spawn and barrier
constructs) and inserts send and recv primitives.
\end{PipsPass}
\begin{PipsMake}
spire_distributed_unstructured_to_structured > MODULE.distributed_spire_code
< PROGRAM.entities > MODULE.code
< MODULE.code
< MODULE.schedule
< MODULE.sdg
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< MODULE.transformers
< MODULE.preconditions
< MODULE.proper_effects
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{SPIRE-Based Parallel Code Generation}
SPIRE is designed in such a way that it can facilitate the generation
of code for different types of parallel systems. Different parallel
languages can be mapped into SPIRE. The two following phases show how this intermediate representation simplifies the task of producing code for various languages such as OpenMP and MPI.
\begin{PipsPass}{openmp_task_generation}
Generate OpenMP task parallel code using SPIRE-based PIPS parallel
intermediate representation.
\end{PipsPass}
\begin{PipsMake}
openmp_task_generation > MODULE.parallelized_code
< PROGRAM.entities
< MODULE.shared_spire_code
\end{PipsMake}
And to output the code decorated with OpenMP (omp task)
directives, we use the existing pass print\_parallelizedOMP\_code
\begin{PipsPass}{mpi_task_generation}
Generate MPI parallel code using SPIRE-based PIPS parallel
intermediate representation.
\end{PipsPass}
\begin{PipsMake}
mpi_task_generation > MODULE.parallelized_code
< PROGRAM.entities
< MODULE.distributed_spire_code
\end{PipsMake}
\begin{PipsPass}{print_parallelizedMPI_code}
Output the code decorated with MPI instructions.
\end{PipsPass}
\begin{PipsMake}
print_parallelizedMPI_code > MODULE.parallelprinted_file
< PROGRAM.entities
< MODULE.parallelized_code
\end{PipsMake}
\subsection{MPI Code Generation}
\begin{PipsPass}{task_mapping}
taskmapping in variable of the same name with \PipsPropRef{MPI_DUPLICATE_VARIABLE_PREFIX} num proc
\end{PipsPass}
\begin{PipsMake}
task_mapping > MODULE.task
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{copy_value_of_write}
copyvalueofwrite in variable of the same name with \PipsPropRef{MPI_DUPLICATE_VARIABLE_PREFIX} num proc
\end{PipsPass}
\begin{PipsMake}
copy_value_of_write > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.code
< MODULE.task
\end{PipsMake}
% > MODULE.task
\begin{PipsPass}{copy_value_of_write_with_cumulated_regions}
copyvalueofwrite in variable of the same name with \PipsPropRef{MPI_DUPLICATE_VARIABLE_PREFIX} num proc
\end{PipsPass}
\begin{PipsMake}
copy_value_of_write_with_cumulated_regions > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.code
< MODULE.task
< MODULE.live_out_regions
\end{PipsMake}
% > MODULE.task
% < MODULE.in_regions
% < MODULE.regions
% < MODULE.out_summary_regions
% < MODULE.in_summary_regions
\begin{PipsProp}{MPI_DUPLICATE_VARIABLE_PREFIX}
MPI_DUPLICATE_VARIABLE_PREFIX "__dpvar__"
\end{PipsProp}
\begin{PipsProp}{MPI_NBR_CLUSTER}
MPI_NBR_CLUSTER 4
\end{PipsProp}
\begin{PipsProp}{MPI_LOCAL_VARIABLES_LIST}
MPI_LOCAL_VARIABLES_LIST ""
\end{PipsProp}
\begin{PipsProp}{MPI_LOCAL_PARAMETER}
MPI_LOCAL_PARAMETER TRUE
\end{PipsProp}
\begin{PipsPass}{variable_replication}
variablereplication replicate variable and declaration with same name and prefix \PipsPropRef{MPI_DUPLICATE_VARIABLE_PREFIX} and suffix num proc
\end{PipsPass}
\begin{PipsMake}
variable_replication > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.task
\end{PipsMake}
% > MODULE.task
\begin{PipsPass}{eliminate_original_variables}
eliminateoriginalvariables eliminate original variables of the code to replace them by there copy with same name and prefix \PipsPropRef{MPI_DUPLICATE_VARIABLE_PREFIX} and suffix num proc
\end{PipsPass}
\begin{PipsMake}
eliminate_original_variables > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.task
\end{PipsMake}
\begin{PipsPass}{mpi_conversion}
\end{PipsPass}
\begin{PipsMake}
mpi_conversion > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.task
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TRANSFORMATIONS
\chapter{Program Transformations}
\label{section-program-transformations}
\index{Transformation}
\index{Program Transformation}
%% Define here the documentation of the pseudo-function
%% "TheTransformations" that describes indeed the concept of
%% transformations in the user manual. This documentation is splitted
%% in two parts, one printed before the description of the various
%% transformations and another ("TheTransformationsAtEnd") afterwards
%% in the user manual:
\begin{PipsPass}{TheTransformations}
A program transformation is a special phase which takes a code as
input, modifies it, possibly using results from several different
analyses, and puts back this modified code as result.
\end{PipsPass}
%% This will be printed after the description of the transformations in
%% the user manual:
\begin{PipsPass}{TheTransformationsAtEnd}
A rule describing a program transformation will never be chosen
automatically by \Pipsmake{} to generate some code since every
transformation rule contains a cycle for the \verb+MODULE.code+
resource. Since the first rule producing code, described in this file,
is \PipsPassRef{controlizer} and since it is the only non-cyclic rule, the
internal representation always is initialized with it.
As program transformations produce nothing else, \Pipsmake{} cannot guess
when to apply these rules automatically. This is exactly what the user
want most of the time: program transformations are under explicit
control by the user. Transformations are applied when the user pushes
one of \WPIPS{} transformation buttons or when (s)he enters an {\em
apply} command when running \TPIPS{}, or by executing a
\verb+Perform+ Shell script. See the introduction for pointers to the
user interfaces.
Unfortunately, it is sometime nice to be able to chain several
transformations without any user interaction. No general macro mechanism is
available in \Pipsmake{}, but it is possible to impose some program
transformations with the '!' command.
User inputs are not well-integrated although a \verb+user_query+ rule
and a \verb+string+ resource could easily be added. User interaction
with a phase are performed directly without notifying \Pipsmake{} to be
more flexible and to allow dialogues between a transformation and the user.
\end{PipsPass}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LOOPS
\section{Loop Transformations}
\subsection{Introduction}
\index{LOOP\_LABEL}
Most loop transformations require the user to give a valid loop label to locate the loop to be transformed.
This is done interactively or by setting the following property to the valid label:
\begin{PipsProp}{LOOP_LABEL}
LOOP_LABEL ""
\end{PipsProp}
\begin{PipsPass}{flag_loops}
Put a label on unlabelled loops for further interactive processing.
Unless \PipsPropRef{FLAG_LOOPS_DO_LOOPS_ONLY} is set to false, only do loops are considered.
\end{PipsPass}
\begin{PipsMake}
flag_loops > MODULE.code
> MODULE.loops
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsProp}{FLAG_LOOPS_DO_LOOPS_ONLY}
FLAG_LOOPS_DO_LOOPS_ONLY TRUE
\end{PipsProp}
\begin{PipsPass}{print_loops}
Display label of all modules loops
\end{PipsPass}
\begin{PipsMake}
print_loops > MODULE.loops_file
< MODULE.loops
\end{PipsMake}
\subsection{Loop range Normalization}
\begin{PipsPass}{linearize_loop_range}
Use intermediate variables as loop upper and lower bound when they are
not affine.
\end{PipsPass}
\begin{PipsMake}
linearize_loop_range > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Label Elimination}
\begin{PipsPass}{clean_labels}
Clean all statement labels. No legality check is performed. This transformation is particularly useful after a sequence of loop transformations is applied on a structured code.
\end{PipsPass}
\begin{PipsMake}
clean_labels > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
If \PipsPropRef{LABEL_EXCEPTION} is set to a string, all the labels containing this string will not be eliminated.
\begin{PipsProp}{LABEL_EXCEPTION}
LABEL_EXCEPTION ""
\end{PipsProp}
\subsection{Loop Distribution}
\label{subsection-loop-distribution}
\index{Loop Distribution}
\index{Distribution (Loop)}
\index{PARTIAL\_DISTRIBUTION}
Function \PipsPassRef{distributer} is a restricted version of the
parallelization function \texttt{rice*} (see
Section~\ref{subsubsection-allen-kennedy-parallelization-algorithm}).
\begin{PipsPass}{distributer}
Distribute all the loops of the module.
Allen \& Kennedy's algorithm~\cite{AK87} is used in both cases. The only
difference is that \PipsPassRef{distributer} does not produce DOALL loops,
but just distributes loops as much as possible.
\end{PipsPass}
\begin{PipsMake}
alias distributer 'Distribute Loops'
distributer > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
Partial distribution distributes the statements of a loop nest except
the isolated statements,that have no dependences at the common level l,
are gathered in the same l-th loop.
\begin{PipsProp}{PARTIAL_DISTRIBUTION}
PARTIAL_DISTRIBUTION FALSE
\end{PipsProp}
\subsection{Statement Insertion}
\begin{PipsPass}{statement_insertion}
Check if the statement flagged by \PipsPropRef{STATEMENT_INSERTION_PRAGMA} can be safely inserted in the current control flow.
\end{PipsPass}
This pass should be reserved to internal use only, another pass should create and insert a flagged statement and then call this one to verify the validity of the insertion
\begin{PipsMake}
statement_insertion > MODULE.code
< PROGRAM.entities
< ALL.code
> ALL.code
< MODULE.regions
< MODULE.out_regions
\end{PipsMake}
\begin{PipsProp}{STATEMENT_INSERTION_PRAGMA}
STATEMENT_INSERTION_PRAGMA "pips inserted statement to check"
\end{PipsProp}
\begin{PipsProp}{STATEMENT_INSERTION_SUCCESS_PRAGMA}
STATEMENT_INSERTION_SUCCESS_PRAGMA "pips inserted statement"
\end{PipsProp}
\begin{PipsProp}{STATEMENT_INSERTION_FAILURE_PRAGMA}
STATEMENT_INSERTION_FAILURE_PRAGMA "pips inserted statement to remove"
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Loop expansion
\subsection{Loop Expansion}
\begin{PipsPass}{loop_expansion_init}
Prepare the loop expansion by creating a new statement (that may be invalid) for further processing by \PipsPassRef{statement_insertion}.
Use \PipsPropRef{STATEMENT_INSERTION_PRAGMA} to identify the created statement.
Otherwise \PipsPropRef{LOOP_LABEL} and \PipsPropRef{LOOP_EXPANSION_SIZE} have the same meaning as in \PipsPassRef{loop_expansion}
\end{PipsPass}
\begin{PipsMake}
loop_expansion_init > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{loop_expansion}
Extends the range of a loop given by \PipsPropRef{LOOP_LABEL} to fit
a size given by \PipsPropRef{LOOP_EXPANSION_SIZE}. An offset can be
set if \PipsPropRef{LOOP_EXPANSION_CENTER} is set to True.
The new loop is guarded to prevent illegal
iterations, further transformations can elaborate on this.
\end{PipsPass}
\begin{PipsMake}
loop_expansion > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\begin{PipsProp}{LOOP_EXPANSION_SIZE}
LOOP_EXPANSION_SIZE ""
\end{PipsProp}
\begin{PipsProp}{LOOP_EXPANSION_CENTER}
LOOP_EXPANSION_CENTER FALSE
\end{PipsProp}
\begin{PipsPass}{array_expansion}
Extends the dimension of all declared arrays so that no access is illegal.
\end{PipsPass}
\begin{PipsMake}
array_expansion > PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.regions
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Loop fusion
\subsection{Loop Fusion}
\label{subsection:loop-fusion}
\index{Loop fusion}
\begin{PipsPass}{loop_fusion}
This pass fuses as many loops as possible in a greedy manner. The
loops must appear in a sequence and have exactly the same loop
bounds and if possible the same loop indices. We'll always try first to fuse
loops where there is a dependence between their body. We expect that this
policy will maximize possibilities for further optimizations.
Property \PipsPropRef{LOOP_FUSION_GREEDY} allows to control whether it'll
try to fuse as many loop as possible even without any reuse. This will be done
in a second pass.
Property \PipsPropRef{LOOP_FUSION_MAXIMIZE_PARALLELISM} is used to control if
loop fusion has to preserve parallelism while fusing. If this property
is true, a parallel loop is never fused with a sequential loop.
Property \PipsPropRef{LOOP_FUSION_KEEP_PERFECT_PARALLEL_LOOP_NESTS} prevents
to lose parallelism when fusing outer loops from a loop nests without being
able to fuse inner loops.
Property \PipsPropRef{LOOP_FUSION_MAX_FUSED_PER_LOOP} limit the number of
fusion per loop. A negative value means that no limit will be enforced.
The fusion legality is checked in the standard way by comparing the
dependence graphs obtained before and after fusion.
This pass is still in the experimental stage. It may have side
effects on the source code when the fusion is attempted but not
performed in case loop index are different.
\end{PipsPass}
\begin{PipsMake}
alias Fusion 'Fusion Loops'
loop_fusion > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
\begin{PipsPass}{loop_fusion_with_regions}
This pass is the same is \PipsPassRef{loop_fusion} excepts that it uses
regions instead of dependence graph. Properties are the same as before:
\PipsPropRef{LOOP_FUSION_GREEDY},
\PipsPropRef{LOOP_FUSION_MAXIMIZE_PARALLELISM},
\PipsPropRef{LOOP_FUSION_KEEP_PERFECT_PARALLEL_LOOP_NESTS}, and
\PipsPropRef{LOOP_FUSION_MAX_FUSED_PER_LOOP} control the algorithm.
\end{PipsPass}
\begin{PipsMake}
alias Fusion 'Fusion Loops With Regions'
loop_fusion_with_regions > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.preconditions
< MODULE.inv_regions
< MODULE.dg
\end{PipsMake}
\begin{PipsProp}{LOOP_FUSION_MAXIMIZE_PARALLELISM}
LOOP_FUSION_MAXIMIZE_PARALLELISM TRUE
\end{PipsProp}
\begin{PipsProp}{LOOP_FUSION_GREEDY}
LOOP_FUSION_GREEDY FALSE
\end{PipsProp}
\begin{PipsProp}{LOOP_FUSION_KEEP_PERFECT_PARALLEL_LOOP_NESTS}
LOOP_FUSION_KEEP_PERFECT_PARALLEL_LOOP_NESTS TRUE
\end{PipsProp}
\begin{PipsProp}{LOOP_FUSION_MAX_FUSED_PER_LOOP}
LOOP_FUSION_MAX_FUSED_PER_LOOP -1
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Index Set Splitting
\subsection{Index Set Splitting}
\label{subsection-index-set-splitting}
\index{Index Set Splitting}
\begin{PipsPass}{index_set_splitting}
Index Set Splitting~\cite{GFL99} splits the loop referenced by
property \PipsPropRef{LOOP_LABEL} into two loops. The
first loop ends at an iteration designated by property
\PipsPropRef{INDEX_SET_SPLITTING_BOUND} and the second start thereafter. It
currently only works for do loops. This transformation is always
legal. Index set
splitting in combination with loop unrolling could be used to perform
loop peeling.
\end{PipsPass}
\begin{PipsMake}
alias index_set_splitting 'Index Set Splitting'
index_set_splitting > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Index Set Splitting \emph{requires} the following globals to be set :
\begin{itemize}
\item \PipsPropRef{LOOP_LABEL} is the loop label
\item \PipsPropRef{INDEX_SET_SPLITTING_BOUND} is the splitting bound
\begin{PipsProp}{INDEX_SET_SPLITTING_BOUND}
INDEX_SET_SPLITTING_BOUND ""
\end{PipsProp}
\end{itemize}
Additionnaly, \PipsPropRef{INDEX_SET_SPLITTING_SPLIT_BEFORE_BOUND} can
be used to accurately tell to split the loop before or after the bound
given in \PipsPropRef{INDEX_SET_SPLITTING_BOUND}
\begin{PipsProp}{INDEX_SET_SPLITTING_SPLIT_BEFORE_BOUND}
INDEX_SET_SPLITTING_SPLIT_BEFORE_BOUND FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LOOP UNROLLING
\subsection{Loop Unrolling}
\label{subsection-loop-unrolling}
\index{Loop Unrolling}
\subsubsection{Regular Loop Unroll}
\begin{PipsPass}{unroll}
Unroll requests a loop label and an unrolling factor from the user.
Then it unrolls the specified loop as specified. The transformation
is very general, and it is interesting to run
\PipsPassRef{partial_eval}, \PipsPassRef{simplify_control} and
\PipsPassRef{dead_code_elimination} after this transformation. When
the number of iterations cannot be proven to be a multiple of the
unrolling factor, the extra iterations can be executed first or last
(see \PipsPropRef{LOOP_UNROLL_WITH_PROLOGUE}).
Labels in the body are deleted. To unroll nested loops, start with the
innermost loop.
This transformation is always legal.
\end{PipsPass}
\begin{PipsMake}
alias unroll 'Loop Unroll'
unroll > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Use \PipsPropRef{LOOP_LABEL} and \PipsPropRef{UNROLL_RATE} if you do
not want to unroll interactively You can also set
\PipsPropRef{LOOP_UNROLL_MERGE} to use the same declarations among all
the unrolled statement (only meaningful in \texttt{C}).
\begin{PipsProp}{UNROLL_RATE}
UNROLL_RATE 0
\end{PipsProp}
\begin{PipsProp}{LOOP_UNROLL_MERGE}
LOOP_UNROLL_MERGE FALSE
\end{PipsProp}
The unrolling rate does not always divide exactly the number of
iterations. So an extra loop must be added to execute the remaining
iterations. This extra loop can be executed with the first iterations
(prologue option) or the last iterations (epilogue option). Property
\PipsPropRef{LOOP_UNROLL_WITH_PROLOGUE} can be set to \verb/FALSE/ to
use the epilogue when possible. The current implementation of the
unrolling with prologue is general, while the implementation of the
unrolling with epilogue is restricted to loops with a statically knonw
increment of one. The epilogue option may reduce misalignments.
\begin{PipsProp}{LOOP_UNROLL_WITH_PROLOGUE}
LOOP_UNROLL_WITH_PROLOGUE TRUE
\end{PipsProp}
Another option might be to require unrolling of the prologue or
epilogue loop when possible.
\subsubsection{Full Loop Unroll}
\begin{PipsPass}{full_unroll}
A loop can also be fully unrolled if the range is numerically known.
``\PPartialEval'' may be usefully applied first.
This is only useful for small loop ranges.
Unrolling can be interactively applied and the user is requested a loop
label:
\end{PipsPass}
\begin{PipsMake}
alias full_unroll 'Full Loop Unroll (Interactive)'
full_unroll > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Or directives can be inserted as comments for loops to be unrolled with:
\begin{PipsMake}
alias full_unroll_pragma 'Full Loop Unroll (Pragma)'
full_unroll_pragma > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
The directive is a comment containing the string \texttt{Cxxx} just before
a loop to fully unroll (it is reserved to Fortran right now and should be
generalized).
Full loop unrolling is applied one loop at a time by default. The user
must specify the loop label. This default feature can be turned off
and all loops with constant loop bounds and constant increment are
fully unrolled.
Use \PipsPropRef{LOOP_LABEL} to pass the desired label if you do not
want to give it interactively
% no longer used {
% \begin{PipsProp}{FULL_UNROLL_INTERACTIVELY}
% FULL_UNROLL_INTERACTIVELY TRUE
% \end{PipsProp}
% }
Property \PipsPropRef{FULL_LOOP_UNROLL_EXCEPTIONS} is used to forbid loop
unrolling when specific user functions are called in the loop
body. The function names are separated by SPACEs. The default value is
the empy set, i.e. the empry string.
\begin{PipsProp}{FULL_LOOP_UNROLL_EXCEPTIONS}
FULL_LOOP_UNROLL_EXCEPTIONS ""
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% fusion
\subsection{Loop Fusion}
\begin{PipsPass}{force_loop_fusion}
This pass applies unconditionnally a loop fusion between the loop
designated by the property \PipsPropRef{LOOP_LABEL} and the
following loop. They must have the same loop index and the same
iteration set. No legality check is performed.
\end{PipsPass}
\begin{PipsMake}
force_loop_fusion > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% STRIP MINING
\subsection{Strip-mining}
\label{subsection-strip-mining}
\index{Strip-Mining}
\begin{PipsPass}{strip_mine}
Strip-mine requests a loop label and either a chunk size or a chunk number.
Then it strip-mines the specified loop, if it is found. Note that the
DO/ENDDO construct is not compatible with such local program transformations.
\end{PipsPass}
\begin{PipsMake}
alias strip_mine 'Strip Mining'
strip_mine > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Behavior of strip mining can be controlled by the following properties:
\begin{itemize}
\item \PipsPropRef{LOOP_LABEL} selects the loop to strip mine
\item \PipsPropRef{STRIP_MINE_KIND} can be set to 0 (fixed-size chunks) or 1 (fixed number of chunks). Negative value is used for interactive prompt.
\item \PipsPropRef{STRIP_MINE_FACTOR} controls the size of the chunk or the number of chunk depending on \PipsPropRef{STRIP_MINE_KIND}. Negative value is used for interactive prompt.
\end{itemize}
\begin{PipsProp}{STRIP_MINE_KIND}
STRIP_MINE_KIND -1
\end{PipsProp}
\begin{PipsProp}{STRIP_MINE_FACTOR}
STRIP_MINE_FACTOR -1
\end{PipsProp}
\subsection{Loop Interchange}
\label{subsection-loop-interchange}
\index{Loop Interchange}
\index{General Loop Interchange}
\begin{PipsPass}{loop_interchange}
\PipsPassRef{loop_interchange} requests a loop label and exchange the outer-most loop
with this label and the inner-most one in the same loop nest, if such a
loop nest exists.
Presently, legality is not checked.
\end{PipsPass}
\begin{PipsMake}
alias loop_interchange 'Loop Interchange'
loop_interchange > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Property \PipsPropRef{LOOP_LABEL} can be set to a loop label instead of using the default interactive method.
\subsection{Hyperplane Method}
\label{subsection-hyperplane-method}
\index{Hyperplane Method}
\begin{PipsPass}{loop_hyperplane}
\PipsPassRef{loop_hyperplane} requests a loop label and a hyperplane direction
vector and applies the hyperplane method to the loop nest starting with this
loop label, if such a loop nest exists.
Presently, legality is not checked.
\end{PipsPass}
\begin{PipsMake}
alias loop_hyperplane 'Hyperplane Method'
loop_hyperplane > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Loop Nest Tiling}
\label{subsection-loop-nest-tiling}
\index{Tiling}
\begin{PipsPass}{loop_tiling}
\PipsPassRef{loop_tiling} requests from the user a numerical loop label and a
numerical partitioning matrix and applies the tiling method to the loop
nest starting with this loop label, if such a loop nest exists.
The partitioning matrix must be of dimension $n \times n$ where $n$ is the
loop nest depth. The default origin for the tiling is 0, but lower loop
bounds are used to adjust it and decrease the control overhead. For
instance, if each loop is of the usual kind, \verb+DO I = 1, N+, the
tiling origin is point (1, 1,...). The code generation is performed
according to the PPoPP'91 paper but redundancy elimination may results in
different loop bounds.
Presently, legality is not checked. There is no decision procedure to
select automatically an {\em optimal} partitioning matrix. Since the
matrix must be numerically known, it is not possible to generate a block
distribution unless all loop bounds are numerically known. It is assumed
that the loop nest is fully parallel.
Jingling \textsc{Xue} published an advanced code generation algorithm for
tiling in Parallel Processing Letters
(\url{http://cs.une.edu.au/~xue/pub.html}).
\end{PipsPass}
\begin{PipsMake}
alias loop_tiling 'Tiling'
loop_tiling > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
This transformations prompts the user for a partition matrix.
Alternatively, this matrix can be provided through the \PipsPropRef{LOOP_TILING_MATRIX} property.
The format of the matrix is a00 a01 a02,a10 a11 a12,a20 a21 a22
\begin{PipsProp}{LOOP_TILING_MATRIX}
LOOP_TILING_MATRIX ""
\end{PipsProp}
It is sometimes useful to apply a partial loop tiling, on the external loops of the loop nest for instance.
The \PipsPropRef{PARTIAL_LOOP_TILING} property should be TRUE. The \PipsPropRef{LOOP_TILING_MATRIX} information is used.
\begin{PipsProp}{PARTIAL_LOOP_TILING}
PARTIAL_LOOP_TILING FALSE
\end{PipsProp}
Likewise, one can use the \PipsPropRef{LOOP_LABEL} property to specify the targeted loop.
\begin{PipsPass}{parallel_loop_tiling}
The implementation of the parallel loop tiling transformation is ongoing. It uses the hyperplane direction to generate the code with potential parallel loops scanning tiles.
\end{PipsPass}
\begin{PipsMake}
alias parallel_loop_tiling 'Parallel Tiling'
parallel_loop_tiling > MODULE.code
< PROGRAM.entities
< MODULE.dg
< MODULE.code
\end{PipsMake}
Loop tiling is valid only if it respects data dependencies. To check the legality of the transformation application the \PipsPropRef{CHECK_TRANSFORMATION_LEGALITY} property should be TRUE. If the transformation is not legal the code does not changed.
\begin{PipsProp}{CHECK_TRANSFORMATION_LEGALITY}
CHECK_TRANSFORMATION_LEGALITY TRUE
\end{PipsProp}
Different codes can be generated after tiling, each having different behavior and performance.
\PipsPropRef{TILE_DIRECTION} and \PipsPropRef{LOCAL_TILE_DIRECTION} properties specify the chosen directions to scan respectively the tiles and the local elements into each tile.
\begin{PipsProp}{TILE_DIRECTION}
TILE_DIRECTION "TP"
\end{PipsProp}
\PipsPropRef{TILE_DIRECTION} is set to TS when the direction is colinear to the partitioning vectors. It is set to TP when the hyperplane direction associated to orthogonal directions are used.
\begin{PipsProp}{LOCAL_TILE_DIRECTION}
LOCAL_TILE_DIRECTION "LI"
\end{PipsProp}
The local elements of each tile are scanned 1) according to the partitioning vectors when \PipsPropRef{LOCAL_TILE_DIRECTION} is set LS, 2) using the hyperplane direction associated to orthogonal directions if set to LP, 3) along the original basis when set to LI.
\subsection{Symbolic Tiling}
\begin{PipsPass}{symbolic_tiling}
Tiles a loop nest using a partitioning vector that can contain symbolic values.
The tiling only works for parallelepiped tiles.
Use \PipsPropRef{LOOP_LABEL} to specify the loop to tile.
Use \PipsPropRef{SYMBOLIC_TILING_VECTOR} as a comma-separated list to specify tile sizes.
Use \PipsPropRef{SYMBOLIC_TILING_FORCE} to bypass condition checks.
Consider using \PipsPassRef{loop_nest_unswitching} if generated max
disturbs further analyses
\end{PipsPass}
\begin{PipsMake}
symbolic_tiling > MODULE.code
! MODULE.coarse_grain_parallelization
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\begin{PipsProp}{SYMBOLIC_TILING_VECTOR}
SYMBOLIC_TILING_VECTOR ""
\end{PipsProp}
\begin{PipsProp}{SYMBOLIC_TILING_FORCE}
SYMBOLIC_TILING_FORCE FALSE
\end{PipsProp}
\subsection{Loop Normalize}
\label{subsection-loop-normalize}
\index{Loop Normalize}
\begin{PipsPass}{loop_normalize}
The loop normalization consists in transforming all the loops of a given
module into a normal form. In this normal form, the lower bound and the
increment are equal to one (1).
Property \PipsPropRef{LOOP_NORMALIZE_PARALLEL_LOOPS_ONLY} control whether we
want to normalize only parallel loops or all loops.
\end{PipsPass}
If we note the initial DO loop as:
\begin{tabbing}
xxxxxx \= xx \= \kill
\> {\tt DO I = lower, upper, incre} \> \\
\> \> ... \\
\> {\tt ENDDO} \>
\end{tabbing}
the transformation gives the folowing code:
\begin{tabbing}
xxxxxx \= xx \= \kill
\> {\tt DO} \> {\tt NLC = 0, (upper - lower + incre)/incre - 1, 1} \\
\> \> {\tt I = incre*NLC + lower} \\
\> \> ... \\
\> {\tt ENDDO} \> \\
\> {\tt I =} \> {\tt ~incre * MAX((upper - lower + incre)/incre, 0) + lower}
\end{tabbing}
The normalization is done only if the initial increment is a constant
number. The normalization produces two assignment statements on the
initial loop index. The first one (at the beginning of the loop body)
assigns it to its value function of the new index and the second one
(after the end of the loop) assigns it to its final value.
\begin{PipsMake}
alias loop_normalize 'Loop Normalize'
loop_normalize > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
If the increment is 1, the loop is considered already normalized. To have
a 1-increment loop normalized too, set the following property
\begin{PipsProp}{LOOP_NORMALIZE_ONE_INCREMENT}
LOOP_NORMALIZE_ONE_INCREMENT FALSE
\end{PipsProp}
This is useful to have iteration spaces that begin at 0 for GPU for
example.
The loop normalization has been defined in some days only Fortran was
available, so having loops starting at 1 like the default for arrays too
make sense in Fortran.
Anyway, no we could generalize for C (starting at 0 is more natural) or
why not from any other value that can be chosen with the following
property:
\begin{PipsProp}{LOOP_NORMALIZE_LOWER_BOUND}
LOOP_NORMALIZE_LOWER_BOUND 1
\end{PipsProp}
If you are sure the final assignment is useless, you can skip it with the
following property.
\begin{PipsProp}{LOOP_NORMALIZE_SKIP_INDEX_SIDE_EFFECT}
LOOP_NORMALIZE_SKIP_INDEX_SIDE_EFFECT FALSE
\end{PipsProp}
\begin{PipsProp}{LOOP_NORMALIZE_PARALLEL_LOOPS_ONLY}
LOOP_NORMALIZE_PARALLEL_LOOPS_ONLY FALSE
\end{PipsProp}
\subsection{Guard Elimination and Loop Transformations}
\label{subsection-guard-elimination}
Youcef \textsc{Bouchebaba}'s implementation of unimodular loop
transformations\ldots
\begin{PipsMake}
guard_elimination > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Tiling for sequences of loop nests}
\label{subsection-tiling-for-sequences-loop-nests}
\begin{PipsPass}{tiling_sequence}
Tiling for sequences of loop nests
\end{PipsPass}
Youcef \textsc{Bouchebaba}'s implementation of tiling for sequences of
loop nests \ldots
\begin{PipsMake}
alias tiling_sequence 'Tiling sequence of loop nests'
\end{PipsMake}
\begin{PipsMake}
tiling_sequence > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
%-----------End of Loop Transformations -------------------------
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% REDUNDANCY ELIMINATION
\section{Redundancy Elimination}
\subsection{Loop Invariant Code Motion}
\label{subsection-invariant_code_motion}
\index{invariant code motion}
\begin{PipsPass}{invariant_code_motion}
This is a test to implement a loop-invariant code motion. This phase hoist
loop-invariant code out of the loop.
A side effect of this transformation is that the code is parallelized too
with some loop distribution. If you don't want this side effect, you can
check section~\ref{subsection-expression-optimizations} which does a
pretty nice job too.
The original algorithm used is described in Chapters 12, 13 and 14 of
Julien Zory's PhD dissertation~\cite{Zor99}.
\end{PipsPass}
\begin{PipsMake}
invariant_code_motion > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.code MODULE.dg
\end{PipsMake}
Note: this pass deals with loop invariant code motion while the
\verb/icm/ pass deals with expressions.
\subsection{Partial Redundancy Elimination}
\label{subsection-partial_redundancy_elimination}
\begin{PipsPass}{partial_redundancy_elimination}
In essence, a {\it partial redundancy} \cite{Muc97} is a computation that is
done more than once on some path through a flowgraph. We implement here a
partial redundancy elimination transformation for logical
expressions such as bound checks by using informations given by
precondition analyses.
This transformation is implemented by Thi Viet Nga \textsc{Nguyen}.
\end{PipsPass}
See also the transformation in \ref{sec:comm-subexpr-elim-1}, the partial
evaluation, and so on.
\begin{PipsMake}
alias partial_redundancy_elimination 'Partial Redundancy Elimination'
partial_redundancy_elimination > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
\end{PipsMake}
\subsection{Identity Elimination}
\label{subsection-identity_elimination}
\index{Identity elimination}
This pass was done by Nelson LOSSING.
\begin{PipsPass}{identity_elimination}
Function \PipsPassRef{identity_elimination} deletes identity statements like
x=x; when x is an expression without side effect.
This pass also imply that if the instruction x=x; raise an exception, this exception
disapear with the instructon.
\end{PipsPass}
\begin{PipsMake}
alias identity_elimination 'Identity Elimination'
identity_elimination > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{identity_elimination_with_points_to}
Function \PipsPassRef{identity_elimination_with_points_to} is an extension
of \PipsPassRef{identity_elimination} to also consider identity with pointer.
So we want to eliminate x=*p or *p=x, when p is a pointer who points-to x.
This extension is not implemented and only compute an \PipsPassRef{identity_elimination}.
\end{PipsPass}
\begin{PipsMake}
alias identity_elimination_with_points_to 'Identity Elimination with Points-to'
identity_elimination_with_points_to > MODULE.code
< PROGRAM.entities
< MODULE.points_to
< MODULE.proper_effects
< MODULE.code
\end{PipsMake}
%-----------End of Redundancy Elimination -------------------------
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% CONTROL FLOW TRANSFORMATIONS
\section{Control-Flow Optimizations}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% CONTROL SIMPLIFICATION
\subsection{Control Simplification (a.k.a. Dead Code Elimination)}
\label{sec:dead-code-elimination}
\index{Dead Code Elimination}
\index{Unreachable Code Elimination}
\index{If Simplification}
\index{Loop Simplification}
\index{Simplify Control}
\index{Control Simplification}
% FI: duplicate definition?
%\begin{PipsPass}{simplify_control}
%Alias for \PipsPassRef{simplify_control}.
%\end{PipsPass}
\begin{PipsPass}{simplify_control}
Function \PipsPassRef{simplify_control} is used to delete non-executed code,
such as empty loop nests or zero-trip loops, for example after
strip-mining or partial evaluation.
Preconditions are used to find always
true conditions in tests and to eliminate such tests. In some cases,
tests cannot be eliminated, but test conditions can be simplified.
%%
One-trip loops are
replaced by an index initialization and the loop body. Zero-trip loops are
replaced by an index initialization. Effects in bound computations are
preserved.
A lot of unexecuted code can simply be eliminated by testing its precondition
feasibility. A very simple and fast test may be used if the preconditions
are normalized when they are computed, but this slows down the
precondition computation. Or non-normalized preconditions are stored in
the database and an accurate and slow feasibility test must be used.
Currently, the first option is used for assignments, calls, IOs and IF
statements but a stronger feasibility test is used for loops.
FORMAT statements are suppressed because they behave like a NOP command.
They should be gathered at the beginning or at the end of the module using
property \PipsPropRef{GATHER_FORMATS_AT_BEGINNING} or
\PipsPropRef{GATHER_FORMATS_AT_END}. The property must be set before the
control flow graph of the module is computed.
The cumulated effects are used in debug mode to display information.
The \PipsPassRef{simplify_control} phase also performs some {\em If
Simplifications} and {\em Loop Simplifications}~\cite{Muc97}.
This function was designed and implemented by Ronan K{\sc eryell}.
\end{PipsPass}
\begin{PipsMake}
alias simplify_control 'Simplify Control'
simplify_control > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.preconditions
\end{PipsMake}
% < MODULE.summary_effects
\begin{PipsPass}{suppress_dead_code}
This pass is the same as \PipsPassRef{simplify_control}. It is used
under this obsolete name in some validation scripts. The name has
been preserved for backward compatibility.
\end{PipsPass}
\begin{PipsMake}
suppress_dead_code > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.preconditions
\end{PipsMake}
% < MODULE.summary_effects
\begin{PipsPass}{simplify_control_directly}
This pass is very similar to \PipsPassRef{simplify_control}, but it
does not require the preconditions. Only local information is
used. It can be useful to clean up input code with constant tests,
e.g. \verb/3>4/, and constant loop bounds. It can also be used after
\PipsPassRef{partial_eval} to avoid recomputing the preconditions
yet another time. The property
\PipsPropRef{SIMPLIFY_CONTROL_DIRECTLY_PRIVATE_LOOP_INDICES}
assert that the loop indices don't need a copy out, i.e. the value at the
exit of the loop can be forgotten.
\end{PipsPass}
\begin{PipsProp}{SIMPLIFY_CONTROL_DIRECTLY_PRIVATE_LOOP_INDICES}
SIMPLIFY_CONTROL_DIRECTLY_PRIVATE_LOOP_INDICES FALSE
\end{PipsProp}
Whether to try to simplify do/while loops (property introduced
as a special workaround for FREIA).
\begin{PipsProp}{SIMPLIFY_CONTROL_DO_WHILE}
SIMPLIFY_CONTROL_DO_WHILE TRUE
\end{PipsProp}
\begin{PipsMake}
alias simplify_control_directly 'Simplify Control Directly'
simplify_control_directly > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsubsection{Properties for Control Simplification}
\index{Dead Code}
\index{DEAD\_CODE\_DISPLAY\_STATISTICS}
It is sometimes useful to display statistics on what has been found
useless and removed in a function, this property controls the
statistics display:
\begin{PipsProp}{DEAD_CODE_DISPLAY_STATISTICS}
DEAD_CODE_DISPLAY_STATISTICS TRUE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% DEAD CODE ELIMINATION
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% USE-DEF ELIMINATION
\subsection{Dead Code Elimination (a.k.a. Use-Def Elimination)}
\label{sec:use-def-elimination}
\index{Use-Def Elimination}
\index{Dead code elimination}
\begin{PipsPass}{dead_code_elimination}
Function \PipsPassRef{dead_code_elimination} deletes statements whose def
references are all dead, i.e. are not used by later executions of
statements. It was developed by Ronan K{\sc eryell}. The algorithm compute
the set of live statements without fix-point. An initial set of live
statements is extended with new statements reached thru use-def chains,
control dependences and....
The initial set of live statements contains IO statements, RETURN, STOP, return, exit, abort...
Note that use-def chains are computed intraproceduraly and not
interproceduraly. Hence some statements may be preserved because they
update a formal parameter although this formal parameter is no longer used
by the callers.
The dependence graph may be used instead of the use-def chains, but
Ronan \textsc{Keryell}, designer and implementer of the initial
Fortran version, did not produce convincing
evidence of the benefit... The drawback is the additional CPU time
required.
This pass was extended to C by Mehdi \textsc{Amini} in 2009-2010, but
it is not yet stabilized. For C code, this pass requires that effects
are calculated with property \verb/MEMORY_EFFECTS_ONLY/ set to
\verb/FALSE/ because we need that the DG includes arcs for
declarations as these latter are separate statements now.
\PipsPassRef{clean_declarations} is automatically performed at the
end, this is why cumulated effects are needed.
The following properties are intended to force some function calls to be preserved by the
algorithm, \PipsPropRef{DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS} expect a space
separated list of function names while
\PipsPropRef{DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS_PREFIX} expect a space separated list
of prefix for function name.
\marginpar{Does it really work?}
\begin{PipsProp}{DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS}
DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS ""
\end{PipsProp}
\begin{PipsProp}{DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS_PREFIX}
DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS_PREFIX ""
\end{PipsProp}
\end{PipsPass}
\begin{PipsMake}
alias dead_code_elimination 'Dead Code Elimination'
dead_code_elimination > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.chains
\end{PipsMake}
Historical comments from Nga \textsc{Nguyen}: According
to~\cite{ASU86} p. 595, and~\cite{Muc97} p. 592, a variable is
{\it dead} if it is not used on any path from the location in the code
where it is defined to the exit point of the routine in the question;
an instruction is {\it dead} if it computes only values that are not
used on any executable path leading from the instruction.
The transformation that identifies and removes such dead code is called
dead code elimination.
So in fact, the {\em Use-def elimination} pass in PIPS is a
{\em Dead code elimination} pass and the {\em Suppress dead code} pass
(see Section~\ref{sec:dead-code-elimination}) does not have a standard name.
It could be the {\em control simplification} pass.
The wrong initial naming has been fixed, but it shows in PIPS
source code, in tpips scripts and in validation test cases.
For backward compatibility, the next pass name is preserved.
\begin{PipsMake}
alias use_def_elimination 'Use-Def elimination'
use_def_elimination > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.chains
\end{PipsMake}
\begin{PipsPass}{dead_code_elimination_with_out_regions}
\PipsPassRef{out_regions} are harder to compute than a simple data dependence
graph, but they provide some advantages over a standard dead-code elimination.
They are computed interprocedurally.
And they can be used to reduce the iteration sets.
Since \PipsPassRef{out_regions} are also flow sensitive regions,
\PipsPassRef{dead_code_elimination_with_out_regions} will also done an
equivalent simplification that \PipsPassRef{simplify_control} will do when
a standard dead-code elimination can't detect it.
\PipsPassRef{loop_bound_minimization_with_out_regions} is automatically
performed at the end (after \PipsPassRef{clean_declarations}).
It reduces the iteration sets.
The preconditions requirement comes from it.
\PipsPropRef{DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS} and
\PipsPropRef{DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS_PREFIX} doesn't work with
\PipsPassRef{dead_code_elimination_with_out_regions}.
% For this purpose, it will be nessecary to add some internal variable for
% DEAD_CODE_ELIMINATION_KEEP_FUNCTIONS and make a read on the return statements
% on main function and a read on exit/abort statements.
% And this for the computation of the OUT Regions.
An equivalent result can/must be obtain by using
\PipsPassRef{dead_code_elimination} and applying \PipsPassRef{region_chains}
to compute use-def chains for intraprocedural result, or
\PipsPassRef{in_out_regions_chains} for interprocedural result.
Except for the possible optimization to reduce the iteration sets.
(The equivalence of the results are not tested)
\end{PipsPass}
\begin{PipsMake}
alias dead_code_elimination_with_out_regions 'Dead Code Elimination with OUT Regions'
dead_code_elimination_with_out_regions > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.preconditions
< MODULE.out_regions
\end{PipsMake}
\subsection{Loop bound minimization}
\label{subsection-loop-bound-minimization}
\index{Loop bound minimization}
\begin{PipsPass}{loop_bound_minimization_with_out_regions}
\PipsPassRef{loop_bound_minimization_with_out_regions} has been implemented by
Nelson LOSSING.
Loop bound minimization tries to minimize the loop bounds by filtering the
iterations which have no effects on the code executed after the loop.
For this purpose, it needs the \PipsPassRef{out_regions} that will indicate
which part of arrays are computed in the loop and will be useful on
the loop continuation.
This pass only modifies the loop bounds when it is possible, and not the loop
body nor the loop increment.
Think to use \PipsPassRef{loop_normalize}, if you want to start at 0 or 1,
or have an increment of 1.
The new loop bounds can be expressed by variables or constants which differ
from the original bounds.
This pass can be launched successively several time and continues to make some
improvements in the code.
The refinement of an execution of this pass can provide more precise
OUT\_Regions and so allows better minimization for other loop bounds.
As a consequence one launch of this pass is not equivalent to two successive
launches.
For n loops, at most n executions of this pass should provide an optimal result.
Any aditional execution is useless.
% But it must still converge after a maximum of n launch, n corresponding to
% the number of loop in the function,
% most of time, less than this n number of loops.
No proof of this last assumption has been done.
Only work for Fortran's DO loop kind of loop.
\end{PipsPass}
\begin{PipsMake}
alias loop_bound_minimization_with_out_regions 'Loop bound minimization with out regions'
loop_bound_minimization_with_out_regions > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< MODULE.out_regions
\end{PipsMake}
\subsection{Control Restructurers}
\index{Restructurer}
\index{Control Restructurer}
% FI: we might be interested in F. Zhang and E. H. D’Hollander, “Using
% hammock graphs to structure programs,” IEEE Trans. Softw. Eng.,
% vol. 30, no. 4, pp. 231–245, 2004.
Two control restructurers are available: \PipsPassRef{unspaghettify} which is
used by default in conjunction with \PipsPassRef{controlizer} and
\PipsPassRef{restructure_control} which must be explicitly applied\footnote{A property
can be used to force the call to \texttt{restructurer} by the
\PipsPassRef{controlizer}.}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% UNSPAGHETTIFY
\subsubsection{Unspaghettify}
\label{sec:unspaghettify}
\index{Unspaghettify}
\index{UNSPAGHETTIFY\_DISPLAY\_STATISTICS}
\index{UNSPAGHETTIFY\_TEST\_RESTRUCTURING}
\index{UNSPAGHETTIFY\_RECURSIVE\_DECOMPOSITION}
\index{RESTRUCTURE\_WHILE\_RECOVER}
\begin{PipsPass}{unspaghettify}
The \emph{unspaghettifier} is a heuristic to clean up and to simplify
the control graphs of a module. It
is useful because the controlizer (see
Section~\ref{subsection-controlized-code}) or some transformation phases
can generate some {\em spaghetti} code with a lot of useless
unstructured code which can confuse some other parts of \Pips{}. Dead code
elimination, for example, uses \PipsPassRef{unspaghettify}.
This control restructuring transformation can be automatically applied
in the \PipsPassRef{controlizer} phase (see
Section~\ref{subsection-controlized-code}) if the
\PipsPropRef{UNSPAGHETTIFY_IN_CONTROLIZER}
property is true.
To add flexibility, the behavior of \PipsPassRef{unspaghettify} is
controlled by the properties
\PipsPropRef{UNSPAGHETTIFY_TEST_RESTRUCTURING}
and \PipsPropRef{UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION}
to allow more
restructuring from \PipsPassRef{restructure_control} to be added in the
\PipsPassRef{controlizer} for example.
This function was designed and implemented by Ronan \textsc{Keryell}.
\end{PipsPass}
%% Control Graph Restructuring
\begin{PipsMake}
alias unspaghettify 'Unspaghettify the Control Graph'
\end{PipsMake}
\begin{PipsMake}
unspaghettify > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
To display the statistics about \PipsPassRef{unspaghettify} and control graph
restructuring \PipsPassRef{restructure_control}.
\begin{PipsProp}{UNSPAGHETTIFY_DISPLAY_STATISTICS}
UNSPAGHETTIFY_DISPLAY_STATISTICS TRUE
\end{PipsProp}
The following option enables the use of IF/THEN/ELSE restructuring
when applying unspaghettify:
\begin{PipsProp}{UNSPAGHETTIFY_TEST_RESTRUCTURING}
UNSPAGHETTIFY_TEST_RESTRUCTURING FALSE
\end{PipsProp}
It is assumed as true for \PipsPassRef{restructure_control}.
It recursively implement TEST restructuring (replacing IF/THEN/ELSE
with GOTOs with structured IF/THEN/ELSE without any GOTOs when
possible) by applying pattern matching methods.
The following option enables the use of control graph hierarchisation
when applying unspaghettify:
\begin{PipsProp}{UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION}
UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION FALSE
\end{PipsProp}
It is assumed as true for \PipsPassRef{restructure_control}.
It implements a recursive decomposition of the control flow graph
by an interval graph partitioning method.
The restructurer can recover some while loops if this property is set:
\begin{PipsProp}{UNSPAGHETTIFY_WHILE_RECOVER}
UNSPAGHETTIFY_WHILE_RECOVER FALSE
\end{PipsProp}
\subsubsection{Restructure Control}
\begin{PipsPass}{restructure_control}
\PipsPassRef{restructure_control} is a more complete restructuring phase that
is useful to improve the accuracy of various \Pips{} phases.
It is implemented by calling \PipsPassRef{unspaghettify}
(\S~\ref{sec:unspaghettify}) with the properties
\PipsPropRef{UNSPAGHETTIFY_TEST_RESTRUCTURING} and
\PipsPropRef{UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION} set to \texttt{TRUE}.
Other restructuring methods are available in \Pips{} with the TOOLPACK's
restructurer (see
Section~\ref{subsection-control-structure-normalization-stf}).
\end{PipsPass}
\begin{PipsMake}
alias restructure_control 'Restructure the Control Graph'
restructure_control > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{DO Loop Recovery}
\label{sec:loop-recovering}
\begin{PipsPass}{recover_for_loop}
This control-flow transformation transforms while loops into DO loops
by recovering an index variable, an initial value, a final value and
an increment.
Useful to be run after transformations ?!?
\end{PipsPass}
\begin{PipsMake}
alias recover_for_loop 'Recover for-loops from while-loops'
recover_for_loop > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
This phase cannot be called from inside the control restructurer since it
needs many higher-level analysis. This is why it is in a separate phase.
\subsubsection{For Loop to DO Loop Conversion}
\label{sec:loop-do-loop}
\begin{PipsPass}{for_loop_to_do_loop}
Since in PIPS some transformations and analysis are more precise for
Fortran code, this is a transformation than try to transform the C-like
for-loops into Fortran-like do-loops.
\end{PipsPass}
Don't worry about the C-code output:
the prettyprinter output do-loop as for-loop if the C-output is selected.
The do-loop construct is interesting since the iteration set is computed
at the loop entry (for example it is not sensible to the index
modification from the inside of the loop) and this simplifies abstract
interpretation a lot.
This transformation transform for example a
\begin{lstlisting}
for (i = lb; i < ub; i += stride)
body;
\end{lstlisting}
into a
\begin{lstlisting}[language=fortran]
do i = lb, ub - 1, stride
body
end do
\end{lstlisting}
\begin{PipsMake}
alias for_loop_to_do_loop 'For-loop to do-loop transformation'
for_loop_to_do_loop > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{For Loop to While Loop Conversion}
\label{sec:loop-while-loop}
\begin{PipsPass}{for_loop_to_while_loop}
Since in PIPS some transformations and analysis may not be implemented for
C for loops but may be implemented for while loops, it is interesting to
have this for loop to while loop conversion.
\end{PipsPass}
This transformation transforms a
\begin{lstlisting}
for (init; cond; update)
body;
\end{lstlisting}
into a
\begin{lstlisting}
{
init;
while(cond) {
body;
update;
}
}
\end{lstlisting}
Since analysis are more precise on do-loops, you should apply a
\PipsPassRef{for_loop_to_do_loop} transformation first
, and only after, apply this
\PipsPassRef{for_loop_to_while_loop} transformation that will transform the
remaining for-loops into while loops.
\begin{PipsMake}
alias for_loop_to_while_loop 'For-loop to while-loop transformation'
for_loop_to_while_loop > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{Do While to While Loop Conversion}
\label{sec:do-while to while-loop}
Some transformations only work on while loops, thus it is useful to have
this transformation that transforms a
\begin{lstlisting}
do {
body;
} while (cond);
\end{lstlisting}
into a
\begin{lstlisting}
{
body;
}
while (cond) {
body;
}
\end{lstlisting}
It is a transformation useful before while loop to for loop recovery for
example (see \S~\ref{sec:loop-recovering}).
\begin{PipsMake}
alias dowhile_to_while 'Do-while to while-loop transformation'
dowhile_to_while > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% SPAGHETTIFY
\subsubsection{Spaghettify}
\label{paragraph-spaghettify}
\index{Spaghettifier}
\index{DESTRUCTURE\_TESTS}
\index{DESTRUCTURE\_LOOPS}
\index{DESTRUCTURE\_WHILELOOPS}
\index{DESTRUCTURE\_FORLOOPS}
\begin{PipsPass}{spaghettify}
\PipsPassRef{spaghettify} is used in the context of the PHRASE project while
creating ``Finite State Machine''-like code portions in order to
synthesize them in reconfigurable units.
This phases transform structured code portions (eg. loops) in
unstructured statements.
\PipsPassRef{spaghettify} transforms the module in a unstructured code with
hierarchical unstructured portions of code corresponding to the old
control flow structures.
To add flexibility, the behavior of \PipsPassRef{spaghettify} is
controlled by the properties
\begin{itemize}
\item{DESTRUCTURE\_TESTS}
\item{DESTRUCTURE\_LOOPS}
\item{DESTRUCTURE\_WHILELOOPS}
\item{DESTRUCTURE\_FORLOOPS}
\end{itemize}
to allow more or less destruction power.
\end{PipsPass}
%% Control Graph Restructuring
\begin{PipsMake}
alias spaghettify 'Spaghettify the Control Graph'
\end{PipsMake}
\begin{PipsMake}
spaghettify > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Thoses properties allow to fine tune \PipsPassRef{spaghettify} phase
\begin{PipsProp}{DESTRUCTURE_TESTS}
DESTRUCTURE_TESTS TRUE
\end{PipsProp}
\begin{PipsProp}{DESTRUCTURE_LOOPS}
DESTRUCTURE_LOOPS TRUE
\end{PipsProp}
\begin{PipsProp}{DESTRUCTURE_WHILELOOPS}
DESTRUCTURE_WHILELOOPS TRUE
\end{PipsProp}
\begin{PipsProp}{DESTRUCTURE_FORLOOPS}
DESTRUCTURE_FORLOOPS TRUE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% FULL SPAGHETTIFY
\subsubsection{Full Spaghettify}
\label{paragraph-full-spaghettify}
\begin{PipsPass}{full_spaghettify}
The \PipsPassRef{spaghettify} is used in context of PHRASE project while
creating``Finite State Machine''-like code portions in order to synthesize
them in reconfigurable units.
This phases transforms all the module in a unique flat unstructured
statement.
Whereas the \PipsPassRef{spaghettify} transforms the module in a unstructured
code with hierarchical unstructured portions of code corresponding to the
old structures, the \PipsPassRef{full_spaghettify} transform the code in a
sequence statement with a beginning statement, a unique and flattened
unstructured (all the unstructured and sequences are flattened), and a
final statement.
\end{PipsPass}
%% Control Graph Restructuring
\begin{PipsMake}
alias full_spaghettify 'Spaghettify the Control Graph for the entire module'
\end{PipsMake}
\begin{PipsMake}
full_spaghettify > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Control Flow Normalisation (STF)}
\label{subsection-control-structure-normalization-stf}
\index{STF}
\index{Control Restructurer}
This pass is now obsolete. Use \PipsPassRef{restructure_control} instead.
\begin{PipsPass}{stf}
Transformation \PipsPassRef{stf} is a C interface to a Shell script used to
restructure a Fortran program using ISTST (via the combined tool
fragment ISTLY = ISTLX/ISTYP and then ISTST) from TOOLPACK~\cite{Pol88,Ost83}.
Be careful, since TOOLPACK is written in Fortran, you need the Fortran
runtime libraries to run STF if is has not been statically compiled...
Known bug/feature: \PipsPassRef{stf} does not change resource \texttt{code} like
other transformations, but the \texttt{source} file. Transformations
applied before \PipsPassRef{stf} are lost.
% This should be changed in the near future.
This transformation is now assumed redundant with respect to the native
PIPS control restructurers, which deal with other languages too.
\end{PipsPass}
\begin{PipsMake}
alias stf 'Restructure with STF'
stf > MODULE.source_file
< MODULE.source_file
\end{PipsMake}
\subsection{Trivial Test Elimination}
\label{subsection-trivial-test-elimination}
\index{Trivial Test Elimination}
% FI->RK: what do you use this for?
\begin{PipsPass}{suppress_trivial_test}
Function \PipsPassRef{suppress_trivial_test} is used to delete the TRUE branch of
trivial test instruction. After apply \PipsPassRef{suppress_trivial_test}, the condition of the
new test instruction is the condition correspondent to the FALSE branch of
the initial test.
This function was designed and implemented by Trinh Quoc \textsc{Anh}.
\end{PipsPass}
\begin{PipsMake}
alias suppress_trivial_test 'Trivial Test Elimination'
suppress_trivial_test > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Finite State Machine Generation}
\label{subsection-fsm-generation}
\index{Finite State Machine Generation}
\index{PHRASE}
Theses phases are used for PHRASE project.
NB: The PHRASE project is an attempt to automatically (or semi-automatically)
transform high-level language for partial evaluation in reconfigurable
logic (such as FPGAs or DataPaths).
This library provides phases allowing to build and modify "Finite State
Machine"-like code portions which will be later synthesized in
reconfigurable units. This was implemented by Sylvain \textsc{Gu\'erin}.
\subsubsection{FSM Generation}
\label{paragraph-fsm-generation}
\begin{PipsPass}{fsm_generation}
This phase tries to generate finite state machine from arbitrary code by
applying rules numeroting branches of the syntax tree and using it as
state variable for the finite state machine.
This phase recursively transforms each UNSTRUCTURED statement in a
WHILE-LOOP statement controlled by a state variable, whose different
values are associated to the different statements.
To add flexibility, the behavior of \PipsPassRef{fsm_generation} is
controlled by the property
\PipsPropRef{FSMIZE_WITH_GLOBAL_VARIABLE}
which controls the fact that the same global variable (global to the
current module) must be used for each FSMized statements.
\end{PipsPass}
\begin{PipsMake}
alias fsm_generation 'FSM Generation'
fsm_generation > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
To generate a hierarchical finite state machine, apply first
\PipsPassRef{spaghettify} (\S~\ref{paragraph-spaghettify}) and then
\PipsPassRef{fsm_generation}.
To generate a flat finite state machine, apply first
\PipsPassRef{full_spaghettify} (\S~\ref{paragraph-full-spaghettify}) and then
\PipsPassRef{fsm_generation} or use the aggregate phase
\PipsPassRef{full_fsm_generation}.
\subsubsection{Full FSM Generation}
\label{paragraph-full-fsm-generation}
\begin{PipsPass}{full_fsm_generation}
This phase tries to generate a flat finite state machine from arbitrary
code by applying rules numeroting branches of the syntax tree and using it
as state variable for the finite state machine.
This phase transform all the module in a FSM-like code, which is a
WHILE-LOOP statement controlled by a state variable, whose different
values are associated to the different statements.
In fact, this phase do nothing but rely on pipsmake to apply the
succession of the 2 phases \PipsPassRef{full_spaghettify}
and \PipsPassRef{fsm_generation}
(\S~\ref{paragraph-fsm-generation})
\end{PipsPass}
\begin{PipsMake}
alias full_fsm_generation 'Full FSM Generation'
full_fsm_generation > MODULE.code
> PROGRAM.entities
! MODULE.full_spaghettify
! MODULE.fsm_generation
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{FSM Split State}
\label{paragraph-fsm-split-state}
\begin{PipsPass}{fsm_split_state}
This phase is not yet implemented and do nothing right now...
This phase transform a state of a FSM-like statement and split it into n
new states where the portion of code to execute is smaller.
NB: Phase \PipsPassRef{full_spaghettify}
must have been applied first !
\end{PipsPass}
\begin{PipsMake}
alias fsm_split_state 'FSM split state
fsm_split_state > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{FSM Merge States}
\label{paragraph-fsm-merge-states}
\begin{PipsPass}{fsm_merge_states}
This phase is not yet implemented and do nothing right now...
This phase transform 2 or more states of a FSM-like statement and merge
them into a new state where the portion of code to execute is bigger.
NB: Phase \PipsPassRef{full_spaghettify}
must have been applied first !
\end{PipsPass}
\begin{PipsMake}
alias fsm_merge_states 'FSM merge states
fsm_merge_states > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{FSM Properties}
\index{FSM Generation}
\index{FSMIZE\_WITH\_GLOBAL\_VARIABLE}
Control the fact that the same global variable (global to the
current module) must be used for each FSMized statements.
\begin{PipsProp}{FSMIZE_WITH_GLOBAL_VARIABLE}
FSMIZE_WITH_GLOBAL_VARIABLE FALSE
\end{PipsProp}
\subsection{Control Counters}
\index{Control Counters}
A code instrumentation that adds local integer counters in tests and loops
to know how many times a path is taken. This transformation may
help some semantical analyses.
\begin{PipsMake}
alias add_control_counters 'Control counters
add_control_counters > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
%\subsection{Declaration Common Addition}
%\label{subsection-declaration-common-addition}
%\index{Declaration Common Addition}%
%Function \verb+add_declaration_common+ is used to add the declarations of
%all the variables common of a whole program into each module. After apply
%\verb+add_declaration_common+, all of the old declarations common had
%insteaded by one new declaration.%
%This function was designed and implemented by Trinh Quoc Anh.
%\begin{PipsMake}
%alias add_declaration_common 'Declaration Common Addition'
%add_declaration_common > MODULE.code
% < PROGRAM.entities
% < MODULE.code
%\end{PipsMake}
%-----------End of Control-flow Optimizations -------------------------
\section{Expression Transformations}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ATOMIZER
\subsection{Atomizers}
\label{subsection-atomizers}
\index{Atomizer}
\index{Three-Address Code}
\begin{PipsPass}{atomizer}
Atomizer produces, or should produce, three-address like instructions,
in Fortran. An atomic instructions is an instruction that contains no
more than three variables, such as {\tt A = B op C}. The result is a
program in a low-level Fortran on which you are able to use all the
others passes of \Pips{}.
Atomizers are used to simplify the statement encountered by automatic
distribution phases. For instance, indirect addressing like
\verb/A(B(I)) = .../ is replaced by \verb/T=B(I);A(T) = .../.
\end{PipsPass}
\subsubsection{General Atomizer}
\begin{PipsMake}
alias atomizer 'Atomizer'
atomizer > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.dg
\end{PipsMake}
\subsubsection{Limited Atomizer}
\label{subsubsection:limited-atomizer}
\index{atomizer}
\begin{PipsPass}{simplify_subscripts}
This pass performs subscripts atomization so that they can be converted in reference
for more accruate analysis.
\end{PipsPass}
\begin{PipsMake}
simplify_subscripts > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{simplify_constant_address_expressions}
This pass evaluates expression of the form \lstinline|*"ae"| that can be
found in COLD output.
\end{PipsPass}
I doubt it can be useful elsewhere ...
\begin{PipsMake}
simplify_constant_address_expressions > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{simplify_complex}
This pass performs a conversion from complex to real.
\PipsPropRef{SIMPLIFY_COMPLEX_USE_ARRAY_OF_STRUCTS} controls the new layout
\end{PipsPass}
\begin{PipsMake}
simplify_complex > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsProp}{SIMPLIFY_COMPLEX_USE_ARRAY_OF_STRUCTS}
SIMPLIFY_COMPLEX_USE_ARRAY_OF_STRUCTS TRUE
\end{PipsProp}
\begin{PipsPass}{split_structures}
Split structures in separated variables when possible, that is remove the structure variable and replaces all fields by different variables.
\end{PipsPass}
\begin{PipsMake}
split_structures > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{new_atomizer}
Here is a new version of the atomizer using a small atomizer from
the HPF compiler (see Section~\ref{subsubsection-hpf-compiler}).
\end{PipsPass}
\begin{PipsMake}
alias new_atomizer 'New Atomizer'
new_atomizer > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
An atomizer is also used by WP65 (see
Section~\ref{subsubsection-shared-memory-emulation})
\subsubsection{Atomizer Properties}
\index{Atomization}
\index{Three Address Code}
\index{ATOMIZE\_INDIRECT\_REF\_ONLY}
\index{Common subexpression elimination}
\index{CSE}
This transformation only atomizes indirect references of array access
functions.
\begin{PipsProp}{ATOMIZE_INDIRECT_REF_ONLY}
ATOMIZE_INDIRECT_REF_ONLY FALSE
\end{PipsProp}
By default, simple array accesses such as \verb/X(I+2)/ are atomized,
although it is not necessary to generate assembly code:
\begin{PipsProp}{ATOMIZE_ARRAY_ACCESSES_WITH_OFFSETS}
ATOMIZE_ARRAY_ACCESSES_WITH_OFFSETS TRUE
\end{PipsProp}
The purpose of the default option is to maximise common subexpression
elimination.
\begin{PipsPass}{generate_two_addresses_code}
Once a code has been atomized, you can use this transformation to generate two address code only
It can be useful for asm generation
\end{PipsPass}
\begin{PipsMake}
generate_two_addresses_code > MODULE.code
< MODULE.code
< MODULE.cumulated_effects
< PROGRAM.entities
\end{PipsMake}
Set following property to false if you want to split dereferencing:
\begin{PipsProp}{GENERATE_TWO_ADDRESSES_CODE_SKIP_DEREFERENCING}
GENERATE_TWO_ADDRESSES_CODE_SKIP_DEREFERENCING TRUE
\end{PipsProp}
%\begin{PipsPass}{iterator_detection}
%convert array to pointer iterators
%\end{PipsPass}
%\begin{PipsMake}
%iterator_detection > MODULE.code
% < MODULE.code
% < PROGRAM.entities
% < MODULE.cumulated_effects
%\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% PARTIAL EVAL
\subsection{Partial Evaluation}
\label{sec:partial-evaluation}
\index{Partial Evaluation}
\begin{PipsPass}{partial_eval}
Function \PipsPassRef{partial_eval} produces code where {\em numerical} constant
expressions or subexpressions are replaced by their value. Using the
preconditions, some variables are evaluated to a integer constant, and
replaced wherever possible. They are not replaced in user function calls
because Fortran uses a call-by-reference mechanism and because they might
be updated by the function. For the same conservative reason, they are not
replaced in intrinsics calls.
Note that {\em symbolic} constants were left unevaluated because they
already are constant. However it was found unfriendly by users because the
principle of least surprise was not enforced: symbolic constants were
sometimes replaced in the middle of an expression but not when the whole
expression was a reference to a symbolic constant. Symbolic integer
constants are now replaced by their values systematically.
Transformations \PipsPassRef{simplify_control} and \PipsPassRef{dead_code_elimination} should be
performed after partial evaluation. It is sometimes important to run
more than one partial evaluation in a row, because the first partial
evaluation may linearize some initially non-linear expressions. Perfect
Club benchmark {\tt ocean} is a case in point.
Comments from Nga \textsc{Nguyen}: According to~\cite{ASU86} and~\cite{Muc97}, the
name of this optimization should be Constant-Expression Evaluation or
Constant Folding for integer values. This transformation produces well
error message at compile time indicating potential error such as division
by zero.
\end{PipsPass}
\begin{PipsMake}
alias partial_eval 'Partial Eval'
partial_eval > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.preconditions
\end{PipsMake}
\PIPS default behavior in various places is to evaluate symbolic
constants. While meaningful, this approach is not source-to-source
compliant, so one can set property
\PipsPropRef{EVAL_SYMBOLIC_CONSTANT} to FALSE to prevent some of those
evaluations.
\begin{PipsProp}{EVAL_SYMBOLIC_CONSTANT}
EVAL_SYMBOLIC_CONSTANT TRUE
\end{PipsProp}
One can also set \PipsPropRef{PARTIAL_EVAL_ALWAYS_SIMPLIFY}
to TRUE in order to force distribution, even when it does not seem profitable
\begin{PipsProp}{PARTIAL_EVAL_ALWAYS_SIMPLIFY}
PARTIAL_EVAL_ALWAYS_SIMPLIFY FALSE
\end{PipsProp}
Likewise, one can turn following property to true if he wants to use
hard-coded value for size of types. The C standard is broken down into
two parts, one is target independent, and one is target
dependent. Currently, there is no way to specify different
architecture models such as 32/32, 32/64 or 64/64, as the architecture
model is hardwired in ri-util-local.h.
\begin{PipsProp}{EVAL_SIZEOF}
EVAL_SIZEOF FALSE
\end{PipsProp}
Regardless of the modelization, the C source code generated when this
property is set to true is potentially no longer portable to other
targets. This property is also used by the semantics analysis.
This function was implemented initially by Bruno \textsc{Baron}.
\subsection{Reduction Detection}
\label{subsection-reduction-detection}
\index{Reduction Detection}
Phase \texttt{Reductions} detects generalized instructions and replaces
them by calls to a run-time library supporting parallel reductions. It was
developed by Pierre \textsc{Jouvelot} in CommonLISP, as a prototype, to show than
NewGen data structures were language-neutral. Thus it by-passes some of
\Pipsmake{}/dbm facilities.
This phase is now obsolete, although reduction detection is critical for
code restructuring and optimization... A new reduction detection phase was
implemented by Fabien \textsc{Coelho}. Have a look at \S~\ref{sec:reductions}
but it does not include a code transformation.
Its result could be prettyprinted in an HPF style (FC: implementation?).
\begin{PipsMake}
old_reductions > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Reduction Replacement}
\begin{PipsPass}{replace_reduction_with_atomic}
\PipsPassRef{replace_reduction_with_atomic} replace all reduction in loop that
are marked as parallel with reduction by
\PipsPassRef{coarse_grain_parallelization_with_reduction}.
The property \PipsPropRef{ATOMIC_OPERATION_PROFILE} control the set of atomic
operations and operand allowed. At that time only ``cuda'' is supported.
\end{PipsPass}
\begin{PipsPass}{flag_parallel_reduced_loops_with_atomic}
\PipsPassRef{flag_parallel_reduced_loops_with_atomic} flag as parallel all loops
that were detected by \PipsPassRef{coarse_grain_parallelization_with_reduction}.
The property \PipsPropRef{ATOMIC_OPERATION_PROFILE} control the set of atomic
operations and operand allowed. At that time only ``cuda'' is supported.
\end{PipsPass}
\begin{PipsProp}{ATOMIC_OPERATION_PROFILE}
ATOMIC_OPERATION_PROFILE "cuda"
\end{PipsProp}
\begin{PipsMake}
replace_reduction_with_atomic > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.reduction_parallel_loops
< MODULE.cumulated_reductions
\end{PipsMake}
\begin{PipsMake}
flag_parallel_reduced_loops_with_atomic > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.reduction_parallel_loops
< MODULE.cumulated_reductions
\end{PipsMake}
\begin{PipsPass}{flag_parallel_reduced_loops_with_openmp_directives}
Flag loops with openmp directives, taking into account reductions.
\end{PipsPass}
\begin{PipsMake}
flag_parallel_reduced_loops_with_openmp_directives > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.reduction_parallel_loops
< MODULE.cumulated_reductions
\end{PipsMake}
\subsection{Forward Substitution}
\index{Common subexpression elimination}
\index(CSE)
\index{Forward substitution}
\index{Invariant code motion}
\begin{PipsPass}{forward_substitute}
Scalars can be forward substituted. The effect is to undo already
performed optimizations such as invariant code motion and common
subexpression elimination, or manual atomization. However we hope to
do a better job automatically!
\end{PipsPass}
\begin{PipsMake}
alias forward_substitute 'Forward Substitution'
forward_substitute > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.dg
< MODULE.cumulated_effects
\end{PipsMake}
One can set \PipsPropRef{FORWARD_SUBSTITUTE_OPTIMISTIC_CLEAN} to TRUE in order to
clean (without check) forward - substituted assignments.
Use cautiously !
\begin{PipsProp}{FORWARD_SUBSTITUTE_OPTIMISTIC_CLEAN}
FORWARD_SUBSTITUTE_OPTIMISTIC_CLEAN FALSE
\end{PipsProp}
\subsection{Expression Substitution}
\begin{PipsPass}{expression_substitution}
This transformation is quickly developed to fulfill the need of a
simple pattern matcher in pips. The user provide a module name
through \PipsPropRef{EXPRESSION_SUBSTITUTION_PATTERN} property and all
expression similar to those contained in
\PipsPropRef{EXPRESSION_SUBSTITUTION_PATTERN} will be substituted to a call
to this module. It is a kind of simple outlining transformations, it
proves to be useful during simdization to recognize some idioms. Note
that the pattern must contain only a single return instruction!
This phase was developed by Serge \textsc{Guelton} during his PhD.
\end{PipsPass}
\begin{PipsMake}
alias expression_substitution 'Expression Substitution'
expression_substitution > MODULE.code
> MODULE.callee
< PROGRAM.entities
< ALL.code
\end{PipsMake}
Set \PipsPropRef{RELAX_FLOAT_ASSOCIATIVITY} to TRUE if you want to
consider all floating point operations as really
associative\footnote{Floating point computations are not associative in
real hardware because of finite precision and rounding errors. For
example $(10^{50} \ominus 10^{-60}) \oplus 1 = 1$ but $10^{50} \oplus
(-10^{-60} \oplus 1) = 0$.}:
\begin{PipsProp}{RELAX_FLOAT_ASSOCIATIVITY}
RELAX_FLOAT_ASSOCIATIVITY FALSE
\end{PipsProp}
This property is used to set the one-liner module used during
expression substitution. It must be the name of a module already
loaded in pips and containing only one return instruction (the
instruction to be matched).
\begin{PipsProp}{EXPRESSION_SUBSTITUTION_PATTERN}
EXPRESSION_SUBSTITUTION_PATTERN ""
\end{PipsProp}
\subsection{Rename Operators}
\begin{PipsPass}{rename_operator}
This transformation replaces all language operators by function calls.
\end{PipsPass}
\begin{PipsMake}
rename_operator > MODULE.code
< MODULE.code
< PROGRAM.entities
\end{PipsMake}
The function name is derived from the operator name, the operator
arguments type(s) and a common prefix. Each function name is built using
the pattern [PREFIX][OP~NAME][SUFFIX] (eg: \emph{int} + \emph{int}
will lead to \emph{op\_addi}). The replacement function must have been
declared, otherwise a warning is emited and the operator is ignored.
\vspace{5pt}
\begin{minipage}{\textwidth}
For instance, the following code:
\begin{lstlisting}
float foo(float a, float b)
{
return a + b;
}
\end{lstlisting}
\end{minipage}
\vspace{5pt}
\begin{minipage}{\textwidth}
becomes, using the default configuration:
\begin{lstlisting}
float foo(float a, float b)
{
return op_addf(a, b);
}
\end{lstlisting}
\end{minipage}
\emph{OP~NAME} is defined by the following table:
\begin{center}
\begin{tabular}{r l}
post++ & post\_inc \\
++pre & inc\_pre \\
post$--$ & post\_dec \\
$--$pre & dec\_pre \\
+ & plus \\
unary + & un\_plus \\
$-$ & minus \\
unary $-$ & un\_minus \\
\end{tabular}
\begin{tabular}{r l}
* & mul \\
/ & div \\
\% & mod \\
= & assign \\
*= & mul\_up \\
/= & div\_up \\
\%= & mod\_up \\
+= & plus\_up \\
\end{tabular}
\begin{tabular}{r l}
$-$= & minus\_up \\
$<$= & leq \\
$<$ & lt \\
$>$= & geq \\
$>$ & gt \\
== & eq \\
!= & neq \\
\end{tabular}
\end{center}
Using the property \PipsPropRef{RENAME_OPERATOR_OPS}, it is possible
to give a restrictive list of operator names on which operator
renaming should be applied. Operator that are not in this list are
ignored.
\begin{PipsProp}{RENAME_OPERATOR_OPS}
RENAME_OPERATOR_OPS "plus minus mul div mod un_plus un_minus assign mul_up div_up mod_up plus_up minus_up"
\end{PipsProp}
Assuming that all arguments of the operator have the same type. \emph{SUFFIX} is deduced using the following table:
\begin{center}
\begin{tabular}{r l}
char & c \\
short & s \\
int & i \\
\end{tabular}
\begin{tabular}{r l}
long & l \\
float & f \\
double & d \\
\end{tabular}
\begin{tabular}{r l}
\_Bool & b \\
\_Complex & C \\
\_Imaginary & I \\
\end{tabular}
\end{center}
Using the property \PipsPropRef{RENAME_OPERATOR_SUFFIXES}, it is possible to give a restrictive list of suffix on which operator renaming should be applied. Every type not listed in this list will be ignored.
\begin{PipsProp}{RENAME_OPERATOR_SUFFIXES}
RENAME_OPERATOR_SUFFIXES "f d C I"
\end{PipsProp}
The \emph{PREFIX} is a common prefix defined by the property \PipsPropRef{RENAME_OPERATOR_PREFIX} which is applied to each operators. It can be used to choose between multiple implementations of the same operator. The default value is \emph{op\_}.
\begin{PipsProp}{RENAME_OPERATOR_PREFIX}
RENAME_OPERATOR_PREFIX "op_"
\end{PipsProp}
In Pips, C For loop like \lstinline$for(i=0; i < n; i++)$ is represented by a Fortran-like range-based Do loop \lstinline$do i = 1,n-1$. Thus, the code:
\begin{lstlisting}
for(i=0; i < n; i++)
\end{lstlisting}
will be rewritten :
\begin{lstlisting}
for(i=0; i <= op_subi(n,1); i++)
\end{lstlisting}
If you want it to be rewritten :
\begin{lstlisting}
for(op_assigni(&i,0); op_leqi(i,op_subi(n,1)); op_inci(i,1))
\end{lstlisting}
you should set the property \PipsPropRef{RENAME_OPERATOR_REWRITE_DO_LOOP_RANGE} to \emph{TRUE}.
This is not the default behaviour, because in most case you don't want to rewrite For loop like this.
\begin{PipsProp}{RENAME_OPERATOR_REWRITE_DO_LOOP_RANGE}
RENAME_OPERATOR_REWRITE_DO_LOOP_RANGE FALSE
\end{PipsProp}
Some operators (=, +=, \ldots) takes a modifiable lvalue. In this case, the expected function signature for a type T is \lstinline$T (T*, T)$.
For instance, the code:
\begin{lstlisting}
float a, b;
a += b;
\end{lstlisting}
would be rewritten:
\begin{lstlisting}
float a, b;
op_add_upf(&a, b);
\end{lstlisting}
\subsection{Array to Pointer Conversion}
% FI: this should be in Section ``Declaration Transformations''... but
% it can be argued that the address expression is potentially
% simplified
\begin{PipsPass}{linearize_array}
This transformation replaces all arrays in the module by equivalent linearized
arrays.
Eventually using array/pointer equivalence.
\end{PipsPass}
\begin{PipsMake}
linearize_array > MODULE.code
> COMPILATION_UNIT.code
> CALLERS.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< COMPILATION_UNIT.code
< CALLERS.code
\end{PipsMake}
\begin{PipsPass}{linearize_array_fortran}
This transformation replaces all arrays in the module by equivalent linearized
arrays. This only makes the arrays starting their index from one.
\end{PipsPass}
\begin{PipsMake}
linearize_array_fortran > MODULE.code
> CALLERS.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< CALLERS.code
\end{PipsMake}
Use \PipsPropRef{LINEARIZE_ARRAY_USE_POINTERS} to control whether arrays are
declared as 1D arrays or pointers. Pointers are accessed using dereferencement
and arrays using subscripts. This property does not apply to the fortran case.
\begin{PipsProp}{LINEARIZE_ARRAY_USE_POINTERS}
LINEARIZE_ARRAY_USE_POINTERS FALSE
\end{PipsProp}
Use \PipsPropRef{LINEARIZE_ARRAY_MODIFY_CALL_SITE} to control whether the call site
is modified or not.
\begin{PipsProp}{LINEARIZE_ARRAY_MODIFY_CALL_SITE}
LINEARIZE_ARRAY_MODIFY_CALL_SITE TRUE
\end{PipsProp}
Use \PipsPropRef{LINEARIZE_ARRAY_CAST_AT_CALL_SITE} to control whether a cast is
inserted at call sites. Turning it on break further effects analysis, but
without the cast it might break compilation or at least generate warnings for
type mismatch. This property does not apply to the fortran case.
\begin{PipsProp}{LINEARIZE_ARRAY_CAST_AT_CALL_SITE}
LINEARIZE_ARRAY_CAST_AT_CALL_SITE FALSE
\end{PipsProp}
Use \PipsPropRef{LINEARIZE_ARRAY_SKIP_STATIC_LENGTH_ARRAYS} to skip
the array to pointer conversion for static length arrays. Linearization is
always done.
\begin{PipsProp}{LINEARIZE_ARRAY_SKIP_STATIC_LENGTH_ARRAYS}
LINEARIZE_ARRAY_SKIP_STATIC_LENGTH_ARRAYS FALSE
\end{PipsProp}
Use \PipsPropRef{LINEARIZE_ARRAY_SKIP_LOCAL_ARRAYS} to skip
the array to pointer conversion for locally declared arrays. Linearization
is always done.
\begin{PipsProp}{LINEARIZE_ARRAY_SKIP_LOCAL_ARRAYS}
LINEARIZE_ARRAY_SKIP_LOCAL_ARRAYS FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% EOLE
% FI: this subsection seems to have been emptied, but the indexes have not been moved too.
%\subsection{Expression Optimizations}
%\label{subsection-expression-optimizations}
%\index{Common subexpression elimination}
%\index{CSE}
%\index{Invariant code motion}
%\index{Optimization}
%\index{EOLE}
%\index{EOLE\_FLAGS}
%\index{EOLE\_OPTIONS}
\subsection{Expression Optimization Using Algebraic Properties}
\label{sec:expr-optim-using}
\begin{PipsPass}{optimize_expressions}
This is an experimental section developed by Julien \textsc{Zory} as PhD work~\cite{Zor99}.
%
This phase aims at optimizing Fortran expression evaluation using algebraic
properties such as associativity, commutativity, neutral elements and so
forth.
%
It is unfortunately obsolete because it relies on external pieces of
software.
This phase restructure arithmetic expressions in order (1) to decrease the
number of operations (e.g. through factorization), (2) to increase the ILP
by keeping the corresponding DAG wide enough, (3) to facilitate the
detection of composite instructions such as multiply-add, (4) to provide
additional opportunities for (4a) invariant code motion (ICM) and (4b)
common subexpression elimination (CSE).
Large arithmetic expressions are first built up via forward substitution
when the programmer has already applied ICM and CSE by hand.
The optimal restructuring of expressions depends on the target defined by
a combination of the computer architecture and the compiler. The target is
specified by a string property called \PipsPropRef{EOLE_OPTIMIZATION_STRATEGY}
which can take values such as \verb|"P2SC"| for IBM Power-2 architecture
and XLF~4.3. To activate all sub-transformations such as ICM and CSE set
it to \verb|"FULL"|. See \PROPERTIES{} for more information about values
for this property and about other properties controlling the behavior of
this phase.
The current implementation is still shaky and does not handle well
expressions of mixed types such as \verb|X+1| where \verb|1| is implictly
promoted from integer to real.
\textbf{Warning}: this phase relies on an external (and unavailable) binary.
To use it partly, you can set \PipsPropRef{EOLE_OPTIMIZATION_STRATEGY} to
\verb+"CSE"+ or \verb+"ICM"+, or even \texttt{ICMCSE} to have both.
%
This will only activate common subexpressions elimination or invariant
code motion (in fact, invariant sub-expression hoisting).
%
Since it is a quite common use case, they have been defined
as independent phases too. See~\ref{sec:comm-subexpr-elim-1}.
\end{PipsPass}
\begin{PipsMake}
alias optimize_expressions 'Optimize Expressions'
optimize_expressions > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.code
alias instruction_selection 'Select Instructions'
instruction_selection > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
EOLE: Evaluation Optimization of Loops and Expressions.
Julien Zory stuff integrated within pips~\cite{Zor99}. It relies on an external tool
named \texttt{eole}. The version and options set can be controlled from
the following properties. The status is experimental. See the
\PipsPassRef{optimize_expressions} pass for more details about the advanced
transformations performed.
\begin{PipsProp}{EOLE}
EOLE "newgen_eole"
\end{PipsProp}
\begin{PipsProp}{EOLE_FLAGS}
EOLE_FLAGS "-nfd"
\end{PipsProp}
\begin{PipsProp}{EOLE_OPTIONS}
EOLE_OPTIONS ""
\end{PipsProp}
\begin{PipsProp}{EOLE_OPTIMIZATION_STRATEGY}
EOLE_OPTIMIZATION_STRATEGY "P2SC"
\end{PipsProp}
\subsection{Common Subexpression Elimination}
\label{sec:comm-subexpr-elim-1}
\index{Common subexpression elimination}
\index{CSE}
Here are described two interesting cases of the one in
\S~\ref{sec:expr-optim-using}.
\begin{PipsPass}{common_subexpression_elimination}
Run common sub-expression elimination to factorize out some redundant
expressions in the code.
One can use \PipsPropRef{COMMON_SUBEXPRESSION_ELIMINATION_SKIP_ADDED_CONSTANT} to skip expression of the form \lstinline|a+2| and
\PipsPropRef{COMMON_SUBEXPRESSION_ELIMINATION_SKIP_LHS} to prevent elimination of left hand side of assignment.
The heuristic used for common subexpression elimination is described
in Chapter~15 of Julien Zory's PhD dissertation~\cite{Zor99}.
%
It was designed for Fortran code. Its use for C code is experimental
and flawed in general.
\end{PipsPass}
\begin{PipsMake}
alias common_subexpression_elimination 'Common Subexpression Elimination'
common_subexpression_elimination > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.code
alias icm 'Invariant Code Motion'
icm > MODULE.code
< PROGRAM.entities
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.code
\end{PipsMake}
Note: the \verb/icm/ deals with expressions while
the \verb/invariant_code_motion/ deals with loop invariant code.
The following property is used in sac to limit the subexpressions:
When set to true, only subexpressions without "+constant" terms are eligible.
\begin{PipsProp}{COMMON_SUBEXPRESSION_ELIMINATION_SKIP_ADDED_CONSTANT}
COMMON_SUBEXPRESSION_ELIMINATION_SKIP_ADDED_CONSTANT FALSE
\end{PipsProp}
\begin{PipsProp}{COMMON_SUBEXPRESSION_ELIMINATION_SKIP_LHS}
COMMON_SUBEXPRESSION_ELIMINATION_SKIP_LHS TRUE
\end{PipsProp}
\begin{PipsPass}{icm}
The icm pass performs invariant code motion over sub-expressions.
\end{PipsPass}
%-----------End of Expression Transformations -------------------------
%% Hmmm... Hardware Accelerator here is kind of an expression transformation.
\section{Hardware Accelerator}
\label{hardware-accelerator}
Generate code from a FREIA application possibly targeting hardware
accelerator, such as SPoC, Terapix, or GPGPU.
%% I could add resources for the module dags?
I'm unsure about the right granularity (now it is at the function
level) and the resource which is produced (should it be an accelerated
file?). The current choice does not allow to easily mix different
accelerators.
\subsection{FREIA Software}
\label{hwac-freia-software}
Generate code for a software FREIA implementation, by applying various
optimizations at the library API level, but without generating accelerated
functions.
\begin{PipsMake}
freia_aipo_compiler > MODULE.code
> MODULE.callees
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
The following properties are generic to all FREIA accelerator targets.
Whether to label arcs in dag dot output with the image name,
and to label nodes with the statement number, and whether to
filter out unused scalar nodes.
\begin{PipsProp}{FREIA_DAG_LABEL_ARCS}
FREIA_DAG_LABEL_ARCS FALSE
\end{PipsProp}
\begin{PipsProp}{FREIA_DAG_LABEL_NODES}
FREIA_DAG_LABEL_NODES TRUE
\end{PipsProp}
\begin{PipsProp}{FREIA_DAG_FILTER_NODES}
FREIA_DAG_FILTER_NODES TRUE
\end{PipsProp}
Whether to compile lone operations, i.e. operations which do not
belong to a sequence.
\begin{PipsProp}{FREIA_COMPILE_LONE_OPERATIONS}
FREIA_COMPILE_LONE_OPERATIONS TRUE
\end{PipsProp}
Whether to normalize some operations:
\begin{PipsProp}{FREIA_NORMALIZE_OPERATIONS}
FREIA_NORMALIZE_OPERATIONS TRUE
\end{PipsProp}
Whether to simplify the DAG using algebraic properties.
\begin{PipsProp}{FREIA_SIMPLIFY_OPERATIONS}
FREIA_SIMPLIFY_OPERATIONS TRUE
\end{PipsProp}
Whether to remove dead image operations in the DAG.
Should always be beneficial.
\begin{PipsProp}{FREIA_REMOVE_DEAD_OPERATIONS}
FREIA_REMOVE_DEAD_OPERATIONS TRUE
\end{PipsProp}
Whether to remove duplicate operations in the DAG, including
algebraic optimizations with commutators.
Should be always beneficial to terapix, but it may depend for spoc.
\begin{PipsProp}{FREIA_REMOVE_DUPLICATE_OPERATIONS}
FREIA_REMOVE_DUPLICATE_OPERATIONS TRUE
\end{PipsProp}
Whether to remove useless image copies from the expression DAG.
\begin{PipsProp}{FREIA_REMOVE_USELESS_COPIES}
FREIA_REMOVE_USELESS_COPIES TRUE
\end{PipsProp}
Whether to move image copies within an expression DAG outside
as external copies, if possible.
\begin{PipsProp}{FREIA_MOVE_DIRECT_COPIES}
FREIA_MOVE_DIRECT_COPIES TRUE
\end{PipsProp}
Whether to merge identical arguments, especially kernels, when calling
an accelerated function:
\begin{PipsProp}{FREIA_MERGE_ARGUMENTS}
FREIA_MERGE_ARGUMENTS TRUE
\end{PipsProp}
Whether to attempt to reuse initial images if possible, instead
of keeping possibly newly introduced temporary images.
\begin{PipsProp}{FREIA_REUSE_INITIAL_IMAGES}
FREIA_REUSE_INITIAL_IMAGES TRUE
\end{PipsProp}
Try to allow shuffling image pointers, but this is not allowed by
default because it may lead to wrong code as the compiler currently
ignores the information and mixes up images.
\begin{PipsProp}{FREIA_ALLOW_IMAGE_SHUFFLE}
FREIA_ALLOW_IMAGE_SHUFFLE FALSE
\end{PipsProp}
Whether to assume that casts are simple image copies.
Default is to keep a cast as cast, which is not accelerated.
\begin{PipsProp}{FREIA_CAST_IS_COPY}
FREIA_CAST_IS_COPY FALSE
\end{PipsProp}
Whether to cleanup freia returned status, as the code is assumed correct
when compiled.
\begin{PipsProp}{FREIA_CLEANUP_STATUS}
FREIA_CLEANUP_STATUS TRUE
\end{PipsProp}
Assume this pixel size in bits:
\begin{PipsProp}{FREIA_PIXEL_SIZE}
FREIA_PIXEL_SIZE 16
\end{PipsProp}
If set to a non-zero value, assume this image size when generating code.
If zero, try generic code.
In particular, the height is useful to compute a better imagelet size
when generating code for the Terapix hardware accelerator.
\begin{PipsProp}{FREIA_IMAGE_HEIGHT}
FREIA_IMAGE_HEIGHT 0
\end{PipsProp}
\begin{PipsProp}{FREIA_IMAGE_WIDTH}
FREIA_IMAGE_WIDTH 0
\end{PipsProp}
If a FREIA application uses a function to transpose a morpho kernel,
the following property can be used to store the function name.
Pips expects a function having the following signature:
\texttt{func\_name(int32\_t kernelTransposed[9], const int32\_t kernelIn[9])}
\begin{PipsProp}{FREIA_TRANSPOSE_KERNEL_FUNC}
FREIA_TRANSPOSE_KERNEL_FUNC ""
\end{PipsProp}
Ad-hoc transformation to remove particular scalar write-write dependencies
in sequences. They are introduced by the do-while to while conversion
on FREIA convergence loops. There is an underlying generic transformation
on sequences that could be implemented with more thoughts on the subject.
\begin{PipsMake}
freia_remove_scalar_ww_deps > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{FREIA SPoC}
\label{hwac-freia-spoc}
FREIA Compiler for SPoC target.
Consider applying \verb|freia_unroll_while| beforehand to unroll convergence
use with the right number of iterations to make the best use of the available
hardware. Note that the same transformation would also make sense somehow
on sequences when the do-while to while transformation as been applied, but
the unrolling factor is much harder to decide in the sequence case as it would
depend on previous operations.
\begin{PipsMake}
freia_spoc_compiler > MODULE.code
> MODULE.callees
> MODULE.spoc_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
freia_unroll_while > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Default depth of the target SPoC accelerator:
\begin{PipsProp}{HWAC_SPOC_DEPTH}
HWAC_SPOC_DEPTH 8
\end{PipsProp}
\subsection{FREIA Terapix}
\label{hwac-freia-terapix}
FREIA compiler for Terapix target.
\begin{PipsMake}
freia_terapix_compiler > MODULE.code
> MODULE.callees
> MODULE.terapix_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
Number of processing elements (PE) for the Terapix accelerator:
\begin{PipsProp}{HWAC_TERAPIX_NPE}
HWAC_TERAPIX_NPE 128
\end{PipsProp}
Default size of memory, in pixel, for the Terapix accelerator
(RAMPE is \emph{RAM} of \emph{PE}):
\begin{PipsProp}{HWAC_TERAPIX_RAMPE}
HWAC_TERAPIX_RAMPE 1024
\end{PipsProp}
Terapix DMA bandwidth. How many terapix cycles to transfer an imagelet row
(size of which is necessarily the number of pe):
\begin{PipsProp}{HWAC_TERAPIX_DMABW}
HWAC_TERAPIX_DMABW 24
\end{PipsProp}
Yes, \emph{twenty-four}, this is not a typo.
It does not seem to depend whether pixels are 8-bit or 16-bit.
The DDR tics are a little faster than the Terapix tics.
Terapix 2D global RAM (GRAM) width and height:
\begin{PipsProp}{HWAC_TERAPIX_GRAM_WIDTH}
HWAC_TERAPIX_GRAM_WIDTH 64
\end{PipsProp}
\begin{PipsProp}{HWAC_TERAPIX_GRAM_HEIGHT}
HWAC_TERAPIX_GRAM_HEIGHT 32
\end{PipsProp}
Whether and how to further cut the dag for terapix.
Expected values, by order of compilation costs, are:
\emph{none}, \emph{compute}, \emph{enumerate}.
\begin{PipsProp}{HWAC_TERAPIX_DAG_CUT}
HWAC_TERAPIX_DAG_CUT "compute"
\end{PipsProp}
Whether input and output memory transfers overlap one with the other,
that is we have a full duplex DMA.
\begin{PipsProp}{HWAC_TERAPIX_OVERLAP_IO}
HWAC_TERAPIX_OVERLAP_IO FALSE
\end{PipsProp}
Note that it is already assumed that computations overlap with
communications. This adds the information that host-accelerator
loads and stores run in parallel. This has two impacts: the
communication apparent time is reduced thanks to the overlapping,
which is good, but the imagelet memory cannot be reused for inputs
because it is still live while being stored, which is bad for
memory pressure.
Use this maximum size (height) of an imagelet if set to non-zero.
It may be useful to set this value to the image height (if known) so
that compiler generates code for smaller imagelets, so that the
runtime is not surprised. This is rather use of debug to impose
an imagelet size.
\begin{PipsProp}{HWAC_TERAPIX_IMAGELET_MAX_SIZE}
HWAC_TERAPIX_IMAGELET_MAX_SIZE 0
\end{PipsProp}
Whether to reduce graphs to subgraphs of connected components.
This should be always beneficial for Terapix, so this is the default.
This option is added as a workaround against potential issues with the runtime.
\begin{PipsProp}{HWAC_TERAPIX_REDUCE_TO_CONNECTED_COMPONENTS}
HWAC_TERAPIX_REDUCE_TO_CONNECTED_COMPONENTS TRUE
\end{PipsProp}
\subsection{FREIA OpenCL}
\label{hwac-freia-opencl}
FREIA compiler for OpenCL target, which may run on both multi-core and GPU.
\begin{PipsMake}
freia_opencl_compiler > MODULE.code
> MODULE.callees
> MODULE.opencl_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
Whether we should attempt to generate merged OpenCL image operations.
If not, the result will be simular to simple AIPO compilation,
no actual helper functions will be generated.
\begin{PipsProp}{HWAC_OPENCL_MERGE_OPERATIONS}
HWAC_OPENCL_MERGE_OPERATIONS TRUE
\end{PipsProp}
Whether to merge OpenCL constant-kernel operations.
\begin{PipsProp}{HWAC_OPENCL_MERGE_KERNEL_OPERATIONS}
HWAC_OPENCL_MERGE_KERNEL_OPERATIONS TRUE
\end{PipsProp}
Whether to generate OpenCL specialized constant-kernel operations.
\begin{PipsProp}{HWAC_OPENCL_GENERATE_SPECIAL_KERNEL_OPS}
HWAC_OPENCL_GENERATE_SPECIAL_KERNEL_OPS TRUE
\end{PipsProp}
Whether merged OpenCL image operations should include reductions as well.
Added to help debugging the code.
\begin{PipsProp}{HWAC_OPENCL_MERGE_REDUCTIONS}
HWAC_OPENCL_MERGE_REDUCTIONS TRUE
\end{PipsProp}
Whether to generate OpenCL code for one operation on its own.
It is not interesting to do so because it is just equivalent to
the already existing AIPO implementation, but it can be useful for
debug.
\begin{PipsProp}{HWAC_OPENCL_COMPILE_ONE_OPERATION}
HWAC_OPENCL_COMPILE_ONE_OPERATION FALSE
\end{PipsProp}
Whether to add an explicit synchronization in the generated codes,
before calling a kernel. This property was added for debug.
\begin{PipsProp}{HWAC_OPENCL_SYNCHRONIZE_KERNELS}
HWAC_OPENCL_SYNCHRONIZE_KERNELS FALSE
\end{PipsProp}
Whether to preload pixels before using them in generated kernels.
Should be better for GPGPU, but not necessarily for CPU implementations.
\begin{PipsProp}{HWAC_OPENCL_PRELOAD_PIXELS}
HWAC_OPENCL_PRELOAD_PIXELS TRUE
\end{PipsProp}
Tell which image dimension is handled by the first OpenCL thread dimension.
Value is either \emph{height} or \emph{width}.
\begin{PipsProp}{HWAC_OPENCL_FIRST_THREAD_DIMENSION}
HWAC_OPENCL_FIRST_THREAD_DIMENSION "height"
\end{PipsProp}
Tell which is the first loop in the kernel code: either on the image
\emph{height} or \emph{width}.
\begin{PipsProp}{HWAC_OPENCL_FIRST_KERNEL_LOOP}
HWAC_OPENCL_FIRST_KERNEL_LOOP "height"
\end{PipsProp}
Whether to generate \emph{tiled} kernels on the first thread dimension,
\begin{PipsProp}{HWAC_OPENCL_TILING}
HWAC_OPENCL_TILING FALSE
\end{PipsProp}
\subsection{FREIA Sigma-C for Kalray MPPA-256}
\label{hwac-freia-sigmac}
FREIA compiler for Kalray MPPA-256 Sigma-C target.
\begin{PipsMake}
freia_sigmac_compiler > MODULE.code
> MODULE.callees
> MODULE.sigmac_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
Minimal number of aggregated operators in a compound arithmetic agent
\begin{PipsProp}{HWAC_SIGMAC_MERGE_ARITH}
HWAC_SIGMAC_MERGE_ARITH 0
\end{PipsProp}
Generation of kernel-specific morphological operators
\begin{PipsProp}{HWAC_SIGMAC_SPECIFIC_MORPHO}
HWAC_SIGMAC_SPECIFIC_MORPHO TRUE
\end{PipsProp}
\subsection{FREIA OpenMP + Async communications for Kalray MPPA-256}
\label{hwac-freia-mppa}
FREIA compiler for Kalray MPPA-256 OpenMP + Async communications target.
\begin{PipsMake}
freia_mppa_compiler > MODULE.code
> MODULE.callees
> MODULE.mppa_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
Compute clusters shared memory avalaible slots
\begin{PipsProp}{HWAC_MPPA_MAX_SMEM_SLOTS}
HWAC_MPPA_MAX_SMEM_SLOTS 4
\end{PipsProp}
Maximum number of instructions in command structure
\begin{PipsProp}{HWAC_MPPA_MAX_INSTRS_CMD}
HWAC_MPPA_MAX_INSTRS_CMD 50
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% FUNCTIONS TRANSFORMATIONS
\section{Function Level Transformations}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% INLINING
\subsection{Inlining}
\label{subsection-inlining}
\index{Inlining}
\index{INLINING\_CALLERS}
\begin{PipsPass}{inlining}
Inlining is a well known technique. Basically, it replaces a function
call by the function body. The current implementation does not work if
the function has static declarations, access global variables \dots.
Actually it (seems to) work(s) for pure, non-recursive functions \dots
and not to work for any other kind of call.
Property \PipsPropRef{INLINING_CALLERS} can be set to define the list of
functions where the call sites have to be inlined. By default, all
call sites of the inlined function are inlined.
\end{PipsPass}
\textbf{Only for C because of pipsmake output declaration !}
\begin{PipsMake}
inlining > CALLERS.c_source_file
> PROGRAM.entities
> MODULE.callers
! MODULE.split_initializations
< PROGRAM.entities
< CALLERS.code
< CALLERS.printed_file
< MODULE.code
< MODULE.cumulated_effects
* ALL.restructure_control
* ALL.remove_useless_label
\end{PipsMake}
Use following property to control how generated variables are initialized
\begin{PipsProp}{INLINING_USE_INITIALIZATION_LIST}
INLINING_USE_INITIALIZATION_LIST TRUE
\end{PipsProp}
Use following property to control whether inlining should ignore stubs:
\begin{PipsProp}{INLINING_IGNORE_STUBS}
INLINING_IGNORE_STUBS TRUE
\end{PipsProp}
%Use following property to control whether inlining should ignore stubs:
%\begin{PipsProp}{INLINING_IGNORE_STUBS}
%INLINING_IGNORE_STUBS TRUE
%\end{PipsProp}
Set the following property to TRUE to add comments on inlined statements to
keep track of their origin.
\begin{PipsProp}{INLINING_COMMENT_ORIGIN}
INLINING_COMMENT_ORIGIN FALSE
\end{PipsProp}
\begin{PipsPass}{inlining_simple}
Same as inlining but always simulate the by-copy argument passing
\end{PipsPass}
\textbf{Only for C because of pipsmake output declaration !}
\begin{PipsMake}
inlining_simple > CALLERS.c_source_file
> PROGRAM.entities
> MODULE.callers
! MODULE.split_initializations
< PROGRAM.entities
< CALLERS.code
< CALLERS.printed_file
< MODULE.code
< MODULE.callers
* ALL.restructure_control
* ALL.remove_useless_label
\end{PipsMake}
\begin{PipsPass}{recompile_module}
Regenerate the ri from the ri ...
\end{PipsPass}
\textbf{Only for C because of pipsmake output declaration !}
\begin{PipsMake}
recompile_module > MODULE.c_source_file
< MODULE.code
\end{PipsMake}
The default behavior of inlining is to inline the given module in \textbf{all} call sites.
Use \PipsPropRef{INLINING_CALLERS} property to filter the call sites: only given module names will be considered.
\begin{PipsProp}{INLINING_CALLERS}
INLINING_CALLERS ""
\end{PipsProp}
%%%%%%%%%%
\subsection{Unfolding}
\label{subsection-unfolding}
\begin{PipsPass}{unfolding}
Unfolding is a complementary transformation of
inlining~\ref{subsection-inlining}. While inlining inlines all call
sites to a given module in other modules, unfolding inlines
recursively all call sites in a given module, thus unfolding the
content of the module. An unfolded source code does not contain
any call anymore.
If you run it recursievly, you should set \PipsPropRef{INLINING_USE_INITIALIZATION_LIST} to false.
\end{PipsPass}
\textbf{Only for C because of output declaration in pipsmake rule!}
\begin{PipsMake}
unfolding > MODULE.c_source_file
> MODULE.callees
> PROGRAM.entities
! CALLERS.split_initializations
< PROGRAM.entities
< MODULE.code
< MODULE.printed_file
< MODULE.cumulated_effects
< CALLEES.code
* ALL.restructure_control
* ALL.remove_useless_label
\end{PipsMake}
\begin{PipsPass}{unfolding_simple}
Same as unfolding, but cumulated effects are not used, and the
resulting code always simulates the by-copy argument passing.
\end{PipsPass}
\textbf{Only for C because of output declaration in pipsmake rule!}
\begin{PipsMake}
unfolding_simple > MODULE.c_source_file
> MODULE.callees
> PROGRAM.entities
! CALLERS.split_initializations
< PROGRAM.entities
< MODULE.code
< MODULE.printed_file
< CALLEES.code
* ALL.restructure_control
* ALL.remove_useless_label
\end{PipsMake}
Use \PipsPropRef{UNFOLDING_CALLEES}, to specify which modules
you want to inline in the unfolded module. The unfolding will be
performed as long as one of the module in
\PipsPropRef{UNFOLDING_CALLEES} is called. More than one module can
be specified, they are separated by blank spaces.
\begin{PipsProp}{UNFOLDING_CALLEES}
UNFOLDING_CALLEES ""
\end{PipsProp}
The default behavior of the \PipsPassRef{unfolding} pass is to
recursively inline all callees from the current module or from the
argument modules of the pass, as long as a callee remains. You can use
\PipsPropRef{UNFOLDING_FILTER} to inline all call sites to a module
not present in the space separated module list defined by the string
property:
\begin{PipsProp}{UNFOLDING_FILTER}
UNFOLDING_FILTER ""
\end{PipsProp}
By default this list is empty and hence all call sites are inlined.
\subsection{Outlining}
\label{subsection-outlining}
\index{Outlining}
\begin{PipsPass}{outline}
This documentation is a work in progress, as well as the documented
topic\marginpar{Serge? Still true? What do you mean?}.
Outlining is the opposite transformation of \PipsPassRef{inlining}.
%%
It replaces some statements in an existing module by a call site to a
new function whose execution is equivalent to the execution of the
replaced statements.
%%
The body of the new function is similar to the piece of code replaced
in the existing module.
%%
The user is prompted for various pieces of information in order to
perform the outlining:
\begin{itemize}
\item a new module name,
\item the statement number of the first outlined statement,
\item number of statements to outline.
\end{itemize}
The statements are a subset of a sequence. They are counted in the
sequence\marginpar{Serge: I invent...(FI)}.
\PipsPropRef{OUTLINE_WRITTEN_SCALAR_BY_REFERENCE} controls whether we
pass written scalar by reference or not.
%%
This property might lead to incorrect code!
\end{PipsPass}
\begin{PipsMake}
outline > MODULE.code
> PROGRAM.entities
< MODULE.privatized
< PROGRAM.entities
< MODULE.cumulated_effects
< MODULE.regions
< MODULE.code
\end{PipsMake}
The property \PipsPropRef{OUTLINE_SMART_REFERENCE_COMPUTATION} is used
to limit the number of entities passed by reference.
%%
With it, \lstinline|a[0][0]| is passed as an \lstinline|a[n][m]|
entity, without it it is passed as an \lstinline|int| or
\lstinline|int*| depending on the cumulated read/write memory effects
of the outlined statements\marginpar{Serge: but cumulated effects are
always required?}.
If you need to pass the upper bound expression of a particular loop as
a parameter, which is used in Ter@pix code generation (see Section~???), set
\PipsPropRef{OUTLINE_LOOP_BOUND_AS_PARAMETER} to the loop
label\marginpar{Serge: a few words of motivation?}.
The property \PipsPropRef{OUTLINE_MODULE_NAME} is used to specify the new module
name. The user is prompted if it is set to its default value, the
empty string.
But first the pass scans\marginpar{Serge: unconditionally?}
the code for any statement flagged with the pragma defined by the
string property \PipsPropRef{OUTLINE_PRAGMA}\marginpar{Serge: What
happens when it is set to the empty strin?}.
If set, the string property \PipsPropRef{OUTLINE_LABEL} is used to
choose the statement\marginpar{Serge: you outline a set of statements;
is it reduced to a singleton in that case?} to outline.
The boolean property \PipsPropRef{OUTLINE_ALLOW_GLOBALS} controls whether global
variables whose initial values are not used are passed as parameters or
not\marginpar{Serge: why is it called ``globals''? It seems that this
makes sense for any local variable...}. It is suggested to addressed this issue with a previous privatization pass.
Finally, the boolean property \PipsPropRef{OUTLINE_INDEPENDENT_COMPILATION_UNIT}
can be set to true to outline the new module into a newly created
compilation unit. It is named after the \PipsPropRef{OUTLINE_MODULE_NAME}.
All necessary types, global variables and functions\marginpar{Serge?}
are declared into this new compilation unit\marginpar{Serge: Consistency
betweeen properties? Name conflicts?}. All the functions brought in the
new compilation unit through the sub-callgraph are declared static and
prefixed with \PipsPropRef{OUTLINE_CALLEES_PREFIX}.
Two properties were added for R-Stream compatibility.
%%
If \PipsPropRef{OUTLINE_REMOVE_VARIABLE_RSTREAM_IMAGE} is set to True,
instead of outlining loop indexes and written scalar variables the
outliner declares them as local variables inside the outlined
function.
%%
Therefore they are not added to the effective or formal parameters.
The behavior of \PipsPropRef{OUTLINE_REMOVE_VARIABLE_RSTREAM_SCOP} is
the same as above.
%%
Except that this property only excludes loop indexes from being
outlined.
\begin{PipsProp}{OUTLINE_MODULE_NAME}
OUTLINE_MODULE_NAME ""
\end{PipsProp}
\begin{PipsProp}{OUTLINE_PRAGMA}
OUTLINE_PRAGMA "pips outline"
\end{PipsProp}
\begin{PipsProp}{OUTLINE_LABEL}
OUTLINE_LABEL ""
\end{PipsProp}
\begin{PipsProp}{OUTLINE_ALLOW_GLOBALS}
OUTLINE_ALLOW_GLOBALS FALSE
\end{PipsProp}
\begin{PipsProp}{OUTLINE_SMART_REFERENCE_COMPUTATION}
OUTLINE_SMART_REFERENCE_COMPUTATION FALSE
\end{PipsProp}
\begin{PipsProp}{OUTLINE_LOOP_BOUND_AS_PARAMETER}
OUTLINE_LOOP_BOUND_AS_PARAMETER ""
\end{PipsProp}
\begin{PipsProp}{OUTLINE_INDEPENDENT_COMPILATION_UNIT}
OUTLINE_INDEPENDENT_COMPILATION_UNIT FALSE
\end{PipsProp}
\begin{PipsProp}{OUTLINE_WRITTEN_SCALAR_BY_REFERENCE}
OUTLINE_WRITTEN_SCALAR_BY_REFERENCE TRUE
\end{PipsProp}
\begin{PipsProp}{OUTLINE_CALLEES_PREFIX}
OUTLINE_CALLEES_PREFIX ""
\end{PipsProp}
\begin{PipsProp}{OUTLINE_REMOVE_VARIABLE_RSTREAM_IMAGE}
OUTLINE_REMOVE_VARIABLE_RSTREAM_IMAGE FALSE
\end{PipsProp}
\begin{PipsProp}{OUTLINE_REMOVE_VARIABLE_RSTREAM_SCOP}
OUTLINE_REMOVE_VARIABLE_RSTREAM_SCOP FALSE
\end{PipsProp}
This pass was developped by Serge Guelton, as part of his PhD work.
\subsection{Cloning}
\index{Cloning}
\index{TRANSFORMATION\_CLONE\_ON\_ARGUMENT}
\index{Slicing}
\begin{PipsPass}{clone}
Procedures can be cloned to obtain several specialized versions. The
call sites must be updated to refer to the desired version.
Cloning can be automatic or assisted by the user. Several examples are
available in clone validation suite.
Slicing and specialization slicing have been introduced in~\cite{AHJR2014a,AHJR2014b} and are more general than cloning. For the time being, no slicing transformation is available in \PIPS since they usually do not preserve the program semantics.
\end{PipsPass}
\begin{PipsMake}
alias clone 'Manual Clone'
clone > CALLERS.code
> CALLERS.callees
< MODULE.code
< MODULE.callers
< MODULE.user_file
< CALLERS.callees
< CALLERS.code
\end{PipsMake}
\begin{PipsPass}{clone_substitute}
\end{PipsPass}
\begin{PipsMake}
alias clone_substitute 'Manual Clone Substitution'
clone_substitute > CALLERS.code
> CALLERS.callees
< MODULE.code
< MODULE.callers
< MODULE.user_file
< CALLERS.callees
< CALLERS.code
\end{PipsMake}
\begin{PipsPass}{clone_on_argument}
Cloning of a subroutine according to an integer scalar argument.
The argument is specified through integer property
\PipsPropRef{TRANSFORMATION_CLONE_ON_ARGUMENT}. If set to $0$, a user request is
performed.
\end{PipsPass}
\begin{PipsMake}
alias clone_on_argument 'Clone On Argument'
clone_on_argument > CALLERS.code
> CALLERS.callees
> MODULE.callers
< MODULE.code
< MODULE.callers
< MODULE.user_file
< CALLERS.callees
< CALLERS.preconditions
< CALLERS.code
\end{PipsMake}
\begin{PipsPass}{clone_only}
Not use assisted version of cloning
it just perform the cloning without any substitution
Use the \PipsPropRef{CLONE_NAME} property if you want a particular clone name.
It's up to another phase to perform the substitution.
\end{PipsPass}
\begin{PipsMake}
alias clone_only 'Simple Clone'
clone_only
< MODULE.code
< MODULE.user_file
\end{PipsMake}
There are two cloning properties.
Cloning on an argument. If 0, a user request is performed.
\begin{PipsProp}{TRANSFORMATION_CLONE_ON_ARGUMENT}
TRANSFORMATION_CLONE_ON_ARGUMENT 0
\end{PipsProp}
Clone name can be given using the \lstinline|CLONE_NAME| properties
Otherwise, a new one is generated
\PipsPropRef{RSTREAM_CLONE_SUFFIX} is the suffix appended to cloned function for R-Stream pre-compilation.
\begin{PipsProp}{CLONE_NAME}
CLONE_NAME ""
\end{PipsProp}
\begin{PipsProp}{RSTREAM_CLONE_SUFFIX}
RSTREAM_CLONE_SUFFIX ""
\end{PipsProp}
%-----------End of Function level transformation -------------------------
\section{Declaration Transformations}
\subsection{Declarations Cleaning}
Clean the declarations of unused variables and commons and so.
It is also a code transformation, since not only the module entity are
updated by the process, but also the declaration statements, some useless writes...
\begin{PipsPass}{clean_declarations}
Clean the declarations of unused variables and commons and so.
\end{PipsPass}
\begin{PipsMake}
alias clean_declarations 'Clean Declarations'
clean_declarations > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
In C, dynamic variables which are allocated and freed but otherwise
never used can be removed. This phase removes the calls to the
dynamic allocation functions (\emph{malloc} and \emph{free} or
user defined equivalents), and remove their declarations.
\begin{PipsPass}{clean_dynamic_variables}
Clean unused local dynamic variables by removing malloc/free calls.
\end{PipsPass}
\begin{PipsMake}
clean_unused_dynamic_variables > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
It may be a regular expression instead of a function name?
\begin{PipsProp}{DYNAMIC_ALLOCATION}
DYNAMIC_ALLOCATION "malloc"
\end{PipsProp}
\begin{PipsProp}{DYNAMIC_DEALLOCATION}
DYNAMIC_DEALLOCATION "free"
\end{PipsProp}
Detecting and forcing variables in the \texttt{register} storage class can
help subsequent analyses, as they cannot be referenced by pointers.
\begin{PipsMake}
force_register_declarations > PROGRAM.entities
> MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Whether to allow arrays to be qualified as registers:
\begin{PipsProp}{FORCE_REGISTER_ARRAY}
FORCE_REGISTER_ARRAY TRUE
\end{PipsProp}
Whether to allow pointers to be qualified as registers:
\begin{PipsProp}{FORCE_REGISTER_POINTER}
FORCE_REGISTER_POINTER TRUE
\end{PipsProp}
Whether to allow formal parameters to be qualified as registers:
\begin{PipsProp}{FORCE_REGISTER_FORMAL}
FORCE_REGISTER_FORMAL TRUE
\end{PipsProp}
\begin{PipsPass}{remove_simple_scalar_pointers}
Remove some simple cases of pointers used on scalars.
\end{PipsPass}
\begin{PipsMake}
remove_simple_scalar_pointers > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Array Resizing}
\label{subsubsection-array-resizing}
One problem of Fortran code is the unnormalized array bound
declarations. In many program, the programmer put an asterisk
(assumed-size array declarator), even 1 for every
upper bound of last dimension of array declaration. This feature affects
code quality and prevents others analyses such as array bound checking or
alias analysis. We developed in PIPS two new methods to find out
automatically the proper upper bound for the unnormalized and assumed-size
array declarations, a process we call {\em array resizing}. Both
approaches have advantages and drawbacks and maybe a combination of these
ones is needed.
To have 100\% resized arrays, we implement also the code instrumentation
task, in the top-down approach.
Different options to compute new declarations for different kinds of
arrays are described in properties-rc.tex. You can combine the two
approaches to have a better results by using these options.
How to use these approaches: after generating new declarations in the
logfile, you have to use the script
\$PIPS\_ROOT/Src/Script/misc/array\_resizing\_instrumentation.pl to replace the unnormalized
declarations and add new assignments in the source code.
\subsubsection{Top Down Array Resizing}
\begin{PipsPass}{array_resizing_top_down}
The method uses the relationship between actual and formal arguments from parameter-passing
rules. New array declarations in the called procedure are
computed with respect to the declarations in the calling procedures.
It is faster than the first one because convex array regions are not needed.
This phase is implemented by Thi Viet Nga \textsc{Nguyen} (see~\cite{Ngu02}).
\end{PipsPass}
\begin{PipsMake}
alias array_resizing_top_down 'Top Down Array Resizing'
array_resizing_top_down > MODULE.new_declarations
> PROGRAM.entities
< PROGRAM.entities
< CALLERS.code
< CALLERS.new_declarations
< CALLERS.preconditions
\end{PipsMake}
\subsubsection{Bottom Up Array Resizing}
\label{subsubsection-array_resizing_bottom_up}
\begin{PipsPass}{array_resizing_bottom_up}
The approach is based on an convex array region analysis that gives
information about the set of array elements accessed during the
execution of code. The regions READ and WRITE of each
array in each module are merged and a new value for the upper bound of the last
dimension is calculated and then it will replace the 1 or *.
This function is firstly implemented by Trinh Quoc \textsc{Anh}, and
ameliorated by Corinne \textsc{Ancourt} and Thi Viet Nga \textsc{Nguyen} (see~\cite{Ngu02}).
\end{PipsPass}
\begin{PipsMake}
alias array_resizing_bottom_up 'Bottom Up Array Resizing'
array_resizing_bottom_up > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< MODULE.regions
\end{PipsMake}
\subsubsection{Full Bottom Up Array Resizing}
\label{subsubsection-array_resizing_full_bottom_up}
% The name ``bottom_up'' come from the fact that the code is in the same folder that
% array resizing bottom up and share some function for the solver of min/max.
% ``Full'' is because all the dimension are impacted and compute lawer and upper bound.
\begin{PipsPass}{array_resizing_full_bottom_up}
This pass is base on \texttt{Useful Variables Regions}
(see \ref{section-useful_variables_regions}) that give for each variable
the read/write region for this variable for the whole program at declaration time
with his declaration memory state.
Contrary to the two previous array resizing passes, this pass was tested for
C code but may also work for Fortran (not tested).
It doesn't generate an intrumentation file that will be used to modify the code
but directly modify the code.
This pass also computes new upper AND lower bounds for the array for all
the dimension.
For language that doesn't allow array notation (a[begin:end] or a[begin:nbr\_elem]),
a shift for all the access of the array is apply depending of the lower boud.
\marginpar{Some prettyprint option may be added to allow C array notation.}
Since we modify all the dimension of the array, the data structure in the memory
are not kept.
Note : Property \PipsPropRef{ARRAY_RESIZING_ASSUMED_SIZE_ONLY} has to be set à
\texttt{FALSE} to compute something in C code.
This pass is implemented by Nelson Lossing, with the solver made by
Thi Viet Nga \textsc{Nguyen} for \texttt{Bottom Up Array Resizing}
(see previous section \ref{subsubsection-array_resizing_bottom_up}).
\end{PipsPass}
\begin{PipsMake}
alias array_resizing_full_bottom_up 'Full Bottom Up Array Resizing'
array_resizing_full_bottom_up > MODULE.code
> PROGRAM.entities
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< MODULE.useful_variables_regions
\end{PipsMake}
\subsubsection{Array Resizing Statistic}
We provide here a tool to calculate the number of pointer-type A(,1) and
assumed-size A(,*) array declarators as well as other information.
\begin{PipsMake}
alias array_resizing_statistic 'Array Resizing Statistic'
array_resizing_statistic > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsubsection{Array Resizing Properties}
This phase is firstly designed to infer automatically new array
declarations for assumed-size (A(*)) and one (A(1) or also called ugly
assumed-size) array declarators. But
it also can be used for all kinds of array : local or formal array
arguments, unnormalized or all kinds of declarations. There are two
different approaches that can be combined to have better results.
\subsubsection*{Top-down Array Resizing}
There are three different options:
\begin{itemize}
\item Using information from the MAIN program or not (1 or 0). If you use
this option, modules that are never called by the MAIN program are not
taken into account. By default, we do not use this information (0).
\item Compute new declarations for all kinds of formal array arguments,
not only assumed-size and one declarations (1 or 0). By default, we
compute for assumed-size and one only (0).
\item Compute new declarations for assumed-size array only, not for ugly
assumed-size (one) array (1 or 0). By default, we compute for both kinds
(0).
\end{itemize}
So the combination of the three above options gives us a number from 0 to
7 (binary representation : 000, 001,..., 111). You must pay attention to
the order of options. For example, if you want to use information from
MAIN program to compute new declarations for assumed-size and one array
declarations, both of them, the option is 4 (100). The default option is 0
(000).
\begin{PipsProp}{ARRAY_RESIZING_TOP_DOWN_OPTION}
ARRAY_RESIZING_TOP_DOWN_OPTION 0
\end{PipsProp}
\subsubsection*{Bottom-up Array Resizing}
There are also three different options:
\begin{itemize}
\item Infer new declarations for arrays with declarations created by the
top-down approach or not (1 or 0). This is a special option because we
want to combine the two approaches: apply top-down first and then
bottom-up on the instrumented arrays (their declarations are of from:
I\_PIPS\_MODULE\_ARRAY). By default, we do not use this option (0).
\item Compute new declarations for all kinds of array arguments,
not only assumed-size and one declarations (1 or 0). By default, we
compute for assumed-size and one only (0).
\item Compute new declarations for local array arguments or not (1 or 0). By default, we
compute for formal array arguments only (0).
\end{itemize}
So the combination of the three above options gives us a number from 0 to
7 (binary representation : 000, 001,..., 111). You must pay attention to
the order of options. There are some options that exclude others, such as
the option to compute new declarations for instrumented array
(I\_PIPS\_MODULE\_ARRAY). The default option is 0
(000).
\begin{PipsProp}{ARRAY_RESIZING_BOTTOM_UP_OPTION}
ARRAY_RESIZING_BOTTOM_UP_OPTION 0
\end{PipsProp}
\subsubsection*{Full Bottom-up Array Resizing}
There are two possibles options that correspond to the second and third
options of bottom-up Array Resizing, but explicited it.
This two options can certainly replace the bit number combinaison for previous
property?
Property \PipsPropRef{ARRAY_RESIZING_ASSUMED_SIZE_ONLY} correspond to the middle
bit of \PipsPropRef{ARRAY_RESIZING_BOTTOM_UP_OPTION}.
It has the same default value, \texttt{TRUE}, that mean computation only for
assumed-size and one declarations (* or 1 for Fortran).
But to compute C code, you have to change this value for \texttt{FALSE}.
\begin{PipsProp}{ARRAY_RESIZING_ASSUMED_SIZE_ONLY}
ARRAY_RESIZING_ASSUMED_SIZE_ONLY TRUE
\end{PipsProp}
Property \PipsPropRef{ARRAY_RESIZING_ARGUMENT} correspond to the right
bit of \PipsPropRef{ARRAY_RESIZING_BOTTOM_UP_OPTION}.
It permits to recompute bound for argument array.
By default, it's at \texttt{FALSE}.
WARNING : The \texttt{TRUE} case is not tested because it can be very dangerous
since we don't also modify the call site, and the data structure is also completly modify.
\begin{PipsProp}{ARRAY_RESIZING_ARGUMENT}
ARRAY_RESIZING_ARGUMENT FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% SCALARIZATION
\subsection{Scalarization}
\index{Scalarization}
Three scalarization pass have been developped. The first one,
\PipsPassRef{scalarization}, is based on convex array regions. The
second one, \PipsPassRef{constant_array_scalarization}, is based on
constant array references. The third one,
\PipsPassRef{quick_scalarization}, is based on proper and cumulated
effects and on the dependence graph. It is supposed equivalent to the
first one, but much faster because convex array regions may be slow to
compute.
Pass \PipsPassRef{constant_array_scalarization} intends to eliminate
array references, e.g. for VHDL generation, for scalar constant
propagations, e.g. to propagate constant arrays, and, ultimately, to
explicit the control of automata encoded with a array containing
pointers to transition functions and the next state, e.g. a protocol
controler.
The other two scalarization passes intend to reduce the number of
array accesses by replacing them with scalar accesses. Combined with
loop fusion and/or used on automatically generated code, scalarization
may eliminate intermediate arrays and improve locality.
\subsubsection{Scalarization Based on Convex Array Regions}
\begin{PipsPass}{scalarization}
Scalarization is the process of replacing array references with
references to scalar copies of the array elements wherever
appropriate. Expected benefits include lower memory footprint and
access time because registers can be used instead of temporary stack
variables or memory accesses, and hence, shorter execution times, as
long as the register pressure is not so high that spill code is
generated.
\end{PipsPass}
Scalarizing a given array reference is subject to two successive
criteria, a Legality criterion and a Profitability criterion:
\begin{itemize}
\item The Legality criterion is evaluated first. It tries and
determines if replacing the reference might lead to breaking
dependence arcs, due to hidden references to the element,
e.g. ``get(A,i)'' instead of ``A[i]''. Also, one and only one array
element must be accessed at each iteration because the algorithm
used is based on convex array regions and because their
implementation assumes only one region per array and per access
type. If these two conditions are not met, no scalarization takes
place.
\item The Profitability criterion is then evaluated, to try and
eliminate cases where scalarization would yield no satisfactory
performance gains, e.g. when a scalarized reference has to be
immediately copied back into the original reference. This is
performed at the source level and depends on the effective register
allocation and code generation.
\end{itemize}
The legality test is based on convex array regions, and not on the
dependence graph as is the Carr's
algorithm~\cite{Car92}\cite{CK94}. Currently, loop carried dependence
arcs prevent scalarization by PIPS, although some can be processed by
Carr's algorithm. See non-regression tests
Transformations/scalarization30 to 36. Procedure calls do not derail
our legality test, but Carr's benchmark does not include any procedure
call. Also, the convex array regions related to the same array are
merged in PIPS as a unique region, even when they have provably no
intersection. As a result, each array can result in at most one scalar
when Carr's algorithm can generate several ones.
This transformation is useful 1) to improve the readability of the
source code with constructs similar to {\em let x be ...}, 2) to
improve the modelizations of the execution, time or energy, by using
source instructions closer to the machine instruction, 3) to
perform an optimization at the source level because the code generator
does not include a powerful (partially) redundant load elimination,
and 4) to be a useful pass in a fully source-to-source compiler. This
transformation is useful to reduce the expansion caused by the
different atomizer passes.
The new scalar variables use the default prefix \verb/___scalar__/ and
are thus easily identified, but a new prefix can be user defined with
Property~\PipsPropRef{SCALARIZATION_PREFIX}.
%%
If\PipsPropRef{SCALARIZATION_PREFIX}
is the empty string, the names of the scalarized variables are used.
If needed according to the IN and OUT convex array regions, the new
variables are initialized, e.g. \verb/__scalar0__ = A[i]/, and/or
copied back into the initial array, e.g. \verb/A[i] = __scalar0__/.
Scalarization is currently applicable both to Fortran and C code, but
the code generation slightly differs because local declarations are
possible with C. However, this may destroy perfect loop nests required
by other passes. Property
\PipsPropRef{SCALARIZATION_PRESERVE_PERFECT_LOOP_NEST} can be used to
preserve C perfect loop nests, this property is currently not completely
implemented.
\PipsPropRef{SCALARIZATION_KEEP_PERFECT_PARALLEL_LOOP_NESTS} can be used to
preserve C perfect parallel loop nests.
Pass \PipsPassRef{scalarization} uses the read and written convex
array regions to decide if the scalarization is possible, the IN and
OUT regions to decide if it is useful to initialize the scalar copy or
to restore the value of the array element.
\begin{PipsMake}
alias scalarization 'Scalarization'
scalarization > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
< CALLEES.summary_effects
\end{PipsMake}
Since OUT regions are computed interprocedurally, strange code may
result when a small or not so small function without any real output
is scalarized. The problem can be fixed by adding a \verb/PRINT/ or a
\verb/printf/ to force an OUT region, or by setting Property
\PipsPropRef{SCALARIZATION_FORCE_OUT} to true.
Also, it may be useful to use Property
\PipsPropRef{SEMANTICS_TRUST_ARRAY_DECLARATIONS} and/or
\PipsPropRef{SEMANTICS_TRUST_ARRAY_REFERENCES} to make sure that as many loops
as possible are entered. If not, loop bounds may act like guards,
which prevents PIPS from hoisting a reference out of a loop, although
this is puzzling for programmers because they expect all loops to be
entered at least once...
As explained above, Property \PipsPropRef{SCALARIZATION_PREFIX} is
used to select the names of the new scalar variables. If it is set to
the empty string, \verb/""/, the scalarized variable name is used as
prefix, which improves readability.
\begin{PipsProp}{SCALARIZATION_PREFIX}
SCALARIZATION_PREFIX ""
\end{PipsProp}
When property \PipsPropRef{SCALARIZATION_USE_REGISTERS} is set to
\texttt{TRUE} (default value), new variables are declared with the
\texttt{register} qualifier. However, this is not always compatible with
other phases. Set it to \texttt{FALSE} to toggle off this behavior.
\begin{PipsProp}{SCALARIZATION_USE_REGISTERS}
SCALARIZATION_USE_REGISTERS TRUE
\end{PipsProp}
Also, as explained above, Property
\PipsPropRef{SCALARIZATION_PRESERVE_PERFECT_LOOP_NEST} is used to
control the way new scalar variables are declared and initialized in
C. The current default value is FALSE because the locality of
declarations is better for automatic loop parallelization, but this
could be changed as a privatization pass should do as well while
preserving perfect loop nests. Note that initializations may have to
be placed in such a way that a perfect loop nest is nevertheless
destroyed, even with this property set to true.
\begin{PipsProp}{SCALARIZATION_PRESERVE_PERFECT_LOOP_NEST}
SCALARIZATION_PRESERVE_PERFECT_LOOP_NEST FALSE
\end{PipsProp}
\begin{PipsProp}{SCALARIZATION_KEEP_PERFECT_PARALLEL_LOOP_NESTS}
SCALARIZATION_KEEP_PERFECT_PARALLEL_LOOP_NESTS FALSE
\end{PipsProp}
Property \PipsPropRef{SCALARIZATION_FORCE_OUT} forces the generation
of a copy-out statement when it is useless according to the OUT
region, for instance when dealing with a library function.
\begin{PipsProp}{SCALARIZATION_FORCE_OUT}
SCALARIZATION_FORCE_OUT FALSE
\end{PipsProp}
Numerical property \PipsPropRef{SCALARIZATION_THRESHOLD} is used to
decide profitability: the estimated complexity of the scalarized code
must be less than the initial complexity. Its minimal value is 2. It
can be set to around 5 to forbid scalarization in sequences with no
loop benefit.
\begin{PipsProp}{SCALARIZATION_THRESHOLD}
SCALARIZATION_THRESHOLD 2
\end{PipsProp}
Property \PipsPropRef{SCALARIZATION_ACROSS_CONTROL_TEST} is used to
control the place where new memory accesses are inserted.
A memory access may be moved out of a loop, which is the best case for
performance, but it then is no longer control dependent on the loop
bounds. A new access is thus added if the compiler cannot prove that
the loop is always entered. However, the burden of the proof may be
too much, if only because nothing can be proven when the loop is
sometimes entered and sometimes not. Also, the memory access may be
always perfectly legal.
The default value for \PipsPropRef{SCALARIZATION_ACROSS_CONTROL_TEST}
is \texttt{"exactness"}, allying safety to
performance. It forbids scalarization when both read and written
regions for the current piece of code are approximate regions, and, in
addition, it applies a cheap test. This is the default option.
When it is set to \texttt{"strict"}, property
\PipsPropRef{SCALARIZATION_ACROSS_CONTROL_TEST} goes for safety before
performance, allowing candidates from approximated regions, but
performing a strict test to check the validity of the
transformation.
When the property is set to \texttt{"cheap"},
memory accesses are moved outside of control structures with only the
cheapest test. Use this last value with caution, since it is unsafe in
the general case.
These properties are pretty hard to understand, as well as their
impact. See sequence06, 07, 08 and 44 in the validation suite of the
scalarization pass.
\begin{PipsProp}{SCALARIZATION_ACROSS_CONTROL_TEST}
SCALARIZATION_ACROSS_CONTROL_TEST "exactness"
\end{PipsProp}
This property tells that variables which are used with an \verb|&| (address-of)
operator (a pointer is generated which references them) should not be scalarized.
%%
\begin{PipsProp}{SCALARIZATION_SKIP_ADDRESS_OF_VARIABLES}
SCALARIZATION_SKIP_ADDRESS_OF_VARIABLES FALSE
\end{PipsProp}
This pass was designed by Fran\c{c}ois Irigoin and implemented by
Laurent Daverio and Fran\c{c}ois Irigoin.
\subsubsection{Scalarization Based on Constant Array References}
\begin{PipsPass}{constant_array_scalarization}
Similar to \PipsPassRef{scalarization}, but with a different
criterion: if an array is only accessed with numerical constant subscript
expressions, it is replaced by a set of scalars and all its
references are replaced by references to the corresponding scalars.
\end{PipsPass}
\begin{PipsMake}
constant_array_scalarization > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
This pass may be useful to make C source code more palatable to C to VHDL
converters that handle scalars better than arrays. It is also useful
to propagate constants contained in an array since the semantics passes
only analyze scalar variables.
This pass was designed and implemented by Serge Guelton.
\subsubsection{Scalarization Based on Memory Effects and Dependence Graph}
Pass \PipsPassRef{scalarization} may be costly because it relies on
array regions analyses and uses them to check its legality
criteria. The next phase alleviates these drawbacks.
\begin{PipsPass}{quick_scalarization}
This pass solely relies on proper and cumulated effets, and as such
may fail to scalarize some accesses. However, it is expected to give
good results in usual cases, especially after
\PipsPassRef{loop_fusion}.
It basically uses the same algorithm as scalar privatization, but
performs on the dependence graph rather than the chains graph for
more precision about array dependences. Several legality criteria
are then tested to ensure the safety of the transformation. In
particular, it is checked that candidate references are not accessed
through hidden references (for instance in calls), and that only one
kind of reference is scalarized in the loop.
\end{PipsPass}
\begin{PipsMake}
alias quick_scalarization 'Quick Scalarization'
quick_scalarization > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.proper_effects
< MODULE.dg
\end{PipsMake}
Pass \PipsPassRef{quick_scalarization} was implemented by B\'eatrice Creusillet.
\subsection{Induction Variable Substitution}
\begin{PipsPass}{induction_substitution}
Induction substitution is the process of replacing scalar variables
by a linear expression of the loop indices.
\end{PipsPass}
\begin{PipsMake}
alias induction_substitution 'Induction variable substitution'
induction_substitution > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.transformers
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
This pass was designed and implemented by Mehdi Amini.
\subsection{Strength Reduction}
\begin{PipsPass}{strength_reduction}
Reduce the complexity of expression computation by generating
induction variables when possible.
\end{PipsPass}
E.g.
\begin{lstlisting}
for(i=0;i MODULE.code
> PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.transformers
\end{PipsMake}
\subsection{Flatten Code}
\begin{PipsPass}{flatten_code}
The goal of this program transformation is to enlarge basic blocks as
much as possible to increase the opportunities for optimization. The
input code is assumed serial: parallel loops are declared sequential.
\end{PipsPass}
This transformation has been developed in PIPS for heterogeneous computing
and is combined with inlining to increase the size of the code
executed by an external accelerator while reducing the
externalization overhead\footnote{FREIA project}. Other
transformations, such as partial evaluation and dead code elimination
(including use-def elimination) can be applied to streamline the
resulting code further.
The transformation \PipsPassRef{flatten_code} firstly moves
declarations up in the abstract syntax tree, secondly remove useless
braces and thirdly fully unroll loops when there iteration counts are
known and the \verb/FLATTEN_CODE_UNROLL/ property is true. Unrolling
can also be controlled using Property
\PipsPropRef{FULL_LOOP_UNROLL_EXCEPTIONS}. The declarations are moved
up: some parallel loops may become sequential. To avoid inconsistency,
all loops are declared sequential by \PipsPassRef{flatten_code}.
Inlining(s), which must be performed explicitly by the user with tpips
or another PIPS interface, can be used first to create lots of
opportunities. The basic block size increase is first due to brace
removals made possible when declarations have been moved up, and
then to loop unrollings. Finally, partial evaluation, dead code elimination
and use-def based elimination can also straighten-out the code and
enlarge basic blocks by removing useless tests or assignments.
The code externalization and adaptation for a given hardware
accelerator is performed by another phase, see for instance
Section~\ref{hardware-accelerator}.
Initially developed in August 2009 by Laurent \textsc{Daverio}, with
help from Fabien \textsc{Coelho} and Fran\c{c}ois \textsc{Irigoin}.
\begin{PipsMake}
alias flatten_code 'Flatten Code'
flatten_code > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
If the following property is set, loop unrolling is applied too for loops
with static bounds.
\begin{PipsProp}{FLATTEN_CODE_UNROLL}
FLATTEN_CODE_UNROLL TRUE
\end{PipsProp}
\subsection{Split Update Operators}
\begin{PipsPass}{split_update_operator}
Split C operators such as \verb/a += b/, \verb/a *= b/, \verb/a >>= b/,
etc. into their expanded form such as \verb/a = a + b/.
\end{PipsPass}
Note that if the left hand side expression lhs implies side effects,
the transformed code is not equivalent since lhs be evaluated twice in
the transformed code. The left hand side is not checked for side
effects. The legality of the transformation is not guaranteed.
\begin{PipsMake}
split_update_operator > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
Two improvements could be used. Check the side effects with a function
such as \verb/expression_to_proper_constant_path_effects()/ and/or use a
pointer to evaluate lhs \verb/a/ once to obtain
\verb/p = &a; *p = *p +b;/.
\subsection{Split Initializations (C Code)}
\begin{PipsPass}{split_initializations}
The purpose of this transformation is to separate the initialization
part from the declaration part in C code in order to make static code
analyses simpler.
\end{PipsPass}
This transformation recurses through all variable declarations, and
creates a new statement each time an initial value is specified in the
declaration, if the initial value can be assigned and if the variable
is not static.
%%
The declarations are modified by eliminating the initial value, and a
new assignment statement with the initial value is added to the source
code.
This transformation can be used, for instance, to improve reduction
detection (see TRAC Ticket 181).
Note that C array and structure initializations, which use braces,
cannot be converted into assignments. In such cases, the initial
declaration is either left untouched or expanded into a statement list.
\begin{PipsMake}
alias split_initializations 'Split Initializations'
split_initializations > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
This transformation uses the \verb/C89_CODE_GENERATION/ property to
generate either C89 or C99 code.
This pass has been developed by Serge Guelton~\cite{Guelton11}. Its
validation suite is still too limited.
\subsection{Set Return Type}
\label{subsec:set-return-type}
\begin{PipsPass}{set_return_type_as_typedef}
The purpose of this transformation is to change the return type of a function.
The new type will be a typedef whose name is controlled by
\PipsPropRef{SET_RETURN_TYPE_AS_TYPEDEF_NEW_TYPE}. The corresponding typedef
must exist in the symbol table.
\end{PipsPass}
This transformation loops over the symbols in the symbol table, and
for each of them which is a typedef, compare the local name to the
property \PipsPropRef{SET_RETURN_TYPE_AS_TYPEDEF_NEW_TYPE}. This
approach is unsafe because there can be different typedef with the
same name in different compilation units, resulting in differents
entries in the symbol table for a same local name. The return type can
also be incoherent with the return statement, thus it is not safe to
run it on a non-void function.
% FI: the motivation could be explicited...
However this pass has been created for special need in par4all, and
considering restrictions described above, it does the job.
\begin{PipsProp}{SET_RETURN_TYPE_AS_TYPEDEF_NEW_TYPE}
SET_RETURN_TYPE_AS_TYPEDEF_NEW_TYPE "P4A_accel_kernel_wrapper"
\end{PipsProp}
\begin{PipsMake}
alias set_return_type_as_typedef 'Set return type as typedef'
set_return_type_as_typedef > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Cast Actual Parameters at Call Sites}
\begin{PipsPass}{cast_at_call_sites}
The purpose of this transformation is to cast parameters at call sites
according to the prototype, a.k.a. the signature, of the called functions.
\end{PipsPass}
% FI: any motivation? example?
\begin{PipsMake}
alias cast_at_call_sites 'Cast parameters at call sites'
cast_at_call_sites > CALLERS.code
< PROGRAM.entities
< MODULE.code
< MODULE.callers
< CALLERS.code
\end{PipsMake}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% S&A PRIVATIZATION
\subsection{Scalar and Array Privatization}
\label{sec:scalar-and-array-privatization}
\index{Privatization}
\index{Array Privatization}
Variable privatization consists in discovering variables whose values are
local to a particular scope, usually a loop iteration.
Three different privatization functions are available. The {\em quick}
privatization is restricted to loop indices and is included in the
dependence graph computation (see
Section~\ref{subsection-dependence-graph}). The scalar privatization should
be applied before any serious parallelization attempt. The array
privatization is much more expensive and is still mainly experimental.
You should keep in mind that, although they modify the internal
repesentation of the code, scalar and array privatizations are only
latent program transformations, and no actual local variable
declaration is generated. This is the responsibility of code
generation phases, which may use this information differently
depending on their target.
\subsubsection{Scalar Privatization}
\index{Scalar Privatization}
Two phases implement scalar privatization. Both detect variables which
are local to a loop nest. They differ in the way they handle global
variables: \PipsPassRef{privatize_module} privatizes only local
variables and function parameters, whereas
\PipsPassRef{privatize_module_even_globals} also tries to privatize
global variables. Both phases produce a fake resource,
\texttt{MODULE.privatized}, so that one or the other can be
activated. The default phase is \PipsPassRef{privatize_module}.
\begin{PipsPass}{privatize_module}
Privatizer detects variables that are local to a loop nest and marks
these variables as private. A variable is private to a loop if the
values assigned to this variable inside the loop cannot reach a
statement outside the loop body.
Note that illegal code, for instance code with uninitialized
variables, can lead to surprising privatizations, which are still
correct since the initial semantics is unspecified.
\end{PipsPass}
\begin{PipsMake}
alias privatize_module 'Privatize Scalars'
privatize_module > MODULE.code
> MODULE.privatized
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.chains
\end{PipsMake}
\begin{PipsPass}{privatize_module_even_globals}
This pass is similar to \PipsPassRef{privatize_module}, but it also
privatizes global scalar variables, using information from
\PipsPassRef{live_paths} analyses to avoid privatizing global
variables which are the values of which are used afterwards, and
callees \PipsPassRef{summary_effects} to ensure that global
variables are not used in callees. This last property is necessary
to keep the transformation as local as possible. If it were not
true, it would require to clone the sub call-trees.
\end{PipsPass}
\begin{PipsMake}
alias privatize_module_even_globals 'Privatize Local and Global Scalars'
privatize_module_even_globals > MODULE.code
> MODULE.privatized
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
< MODULE.chains
< MODULE.live_out_paths
< MODULE.live_in_paths
< CALLEES.summary_effects
\end{PipsMake}
The results of this phase are not always as good as expected. this
happens when global variables are also used/defined in called
modules. Requiring that \PipsPassRef{privatize_module_even_globals} is
called on callees first (by using a bang rule), is not sufficient,
because declaring variable as private does not remove the effects on
the variables. Enforcing that \PipsPassRef{localize_declaration} is
first performed on the called modules partially solves the problems,
except for loop indices of outermost loops which are not localized.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% DECLARATION LOCALIZATION
\subsubsection{Declaration Localization}
\begin{PipsPass}{localize_declaration}
Use informations from \PipsPassRef{privatize_module} to move \texttt{C}
variable declarations as close as possible to their uses.
For instance
\begin{lstlisting}
int i,j;
for(i=0;i<10;i++)
for(j=0;j<10;j++)
...
\end{lstlisting}
becomes
\begin{lstlisting}
int i;
for(i=0;i<10;i++)
{
int j;
for(j=0;j<10;j++)
...
}
\end{lstlisting}
\end{PipsPass}
\begin{PipsMake}
localize_declaration > MODULE.code
< MODULE.privatized
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsProp}{LOCALIZE_DECLARATION_SKIP_LOOP_INDICES}
LOCALIZE_DECLARATION_SKIP_LOOP_INDICES FALSE
\end{PipsProp}
% FI: we could also restitute initializations, "int p; p = 0;" -> "int p = 0;"
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ARRAY PRIVATIZATION
\subsubsection{Array Privatization}
\index{Array Privatization}
\index{Privatization}
\index{Privationzation (Array)}
\index{ARRAY\_PRIV\_FALSE\_DEP\_ONLY}
\index{ARRAY\_SECTION\_PRIV\_COPY\_OUT}
\begin{PipsPass}{array_privatizer}
Array privatization aims at privatizing whole arrays
(\PipsPassRef{array_privatizer}) or sets of array elements
(\PipsPassRef{array_section_privatizer}) instead of scalar variables
only. The algorithm, developed by B\'eatrice C{\sc reusillet}~\cite{Cre96}, is
very different from the algorithm used for solely privatizing scalar
variables and relies on IN and OUT regions analyses. Of course, it
also privatizes scalar variables, although the algorithm is much
more expensive and should be used only when necessary.
\end{PipsPass}
\begin{PipsPass}{array_section_privatizer}
{\em Array sections\/} privatization is still experimental and
should be used with great care. In particular, it is not compatible
with the next steps of the parallelization process, i.e. dependence
tests and code generation, because it does not modify the code, but
solely produces a new region resource.
\end{PipsPass}
\begin{PipsPass}{declarations_privatizer}
Another transformation, which can also be called a
\emph{privatization}, consists in declaring as \emph{local} to a
procedure or function the variables which are used only
locally. This happens quite frequently in old Fortran codes where
variables are declared as {\tt SAVE}d to avoid allocations at each
invocation of the routine. However, this prevents parallelization of
the loop surrounding the calls. The function which performs this
transformation is called \PipsPassRef{declarations_privatizer}.
\end{PipsPass}
\begin{PipsMake}
alias array_privatizer 'Privatize Scalars & Arrays'
alias array_section_privatizer 'Scalar and Array Section Privatization'
alias declarations_privatizer 'Declaration Privatization'
\end{PipsMake}
\begin{PipsMake}
array_privatizer > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
array_section_privatizer > MODULE.code
> MODULE.privatized_regions
> MODULE.copy_out_regions
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.transformers
< MODULE.preconditions
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
declarations_privatizer > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.regions
< MODULE.in_regions
< MODULE.out_regions
\end{PipsMake}
Several privatizability criterions can be applied for array
section privatization, and its not yet clear which one should be used. The
default case is to remove potential false dependences between
iterations. The first option, when set to false, removes this
constraint. It is useful for single assignment programs, to discover
what section is really local to each iteration.
When the second option is set to false, copy-out is not allowed,
which means only array regions that are not further reused in the program
continuation can be privatized.
\begin{PipsProp}{ARRAY_PRIV_FALSE_DEP_ONLY}
ARRAY_PRIV_FALSE_DEP_ONLY TRUE
\end{PipsProp}
\begin{PipsProp}{ARRAY_SECTION_PRIV_COPY_OUT}
ARRAY_SECTION_PRIV_COPY_OUT TRUE
\end{PipsProp}
\subsection{Scalar and Array Expansion}
\label{subsection-scalar-and-array-expansion}
\index{Expansion}
\index{Array Expansion}
\index{Scalar Expansion}
Variable expansion consists in adding new dimensions to a variable so as
to parallelize surrounding loops. There is no known advantage for
expansion against privatization, but expansion is used when parallel loops
must be distributed, for instance to generate SIMD code.
It is assumed that the variables to be expanded are the private
variables. So this phase only is useful if a privatization has been
performed earlier.
\subsubsection{Scalar Expansion}
\index{Scalar Expansion}
\index{Reduction Parallelization}
\begin{PipsPass}{variable_expansion}
Loop private scalar variables are expanded
\end{PipsPass}
\begin{PipsMake}
alias variable_expansion 'Expand Scalar'
variable_expansion > MODULE.code
< MODULE.privatized
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{reduction_variable_expansion}
Uses \PipsPropRef{LOOP_LABEL} to select a particular loop,
then finds all reduction in this loop and performs variable expension on all reduction variables.
\end{PipsPass}
\begin{PipsMake}
reduction_variable_expansion > MODULE.code
< PROGRAM.entities
< MODULE.cumulated_reductions
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{reduction_atomization}
A variant of atomization that splits expressions but keep as much
reduction as possible. E.g: r+=a+b becomes r+=a ; r+=b;
\end{PipsPass}
\begin{PipsMake}
reduction_atomization > MODULE.code
< PROGRAM.entities
< MODULE.cumulated_reductions
< MODULE.code
\end{PipsMake}
\subsubsection{Array Expansion}
\index{Array Expansion}
Not implemented yet.
\subsection{Variable Length Array}
\label{subsection-vla}
\index{Variable Length Array}
These passes are designed to analyze C code.
These passes verify if the length variable of a variable length array is
initialized and add some initilization if necessary.
For instance
\begin{lstlisting}
int n;
int a[n];
...
\end{lstlisting}
the pass detects that \verb+a[n]+ needs \verb+n+ and verifies that \verb+n+
is initialized.
They have been developped by Nelson Lossing.
Note: Can \PipsPassRef{used_before_set} be equivalent, but statically?
\subsubsection{Check Initialize Variable Length Array}
\label{subsection-check-initialize-vla}
\index{Check Initialize Variable Length Array}
We can check the intialization of vla using two different ways:
The first one \PipsPassRef{check_initialize_vla_with_preconditions}
uses the preconditions and verifies that the variable has a value.
The other way \PipsPassRef{check_initialize_vla_with_effects}/
\PipsPassRef{check_initialize_vla_with_regions}
uses the effects/regions to check if the variable was written before use.
\begin{PipsMake}
alias check_initialize_vla_with_preconditions 'Check Initialize Variable Length Array With Preconditions'
alias check_initialize_vla_with_effects 'Check Initialize Variable Length Array With Effects'
alias check_initialize_vla_with_regions 'Check Initialize Variable Length Array With Regions'
\end{PipsMake}
All these passes use property \PipsPropRef{ERROR_ON_UNINITIALIZE_VLA}
to generate a warning or an error when an uninitialized length variable
is detected.
Indeed, we can have some false positive due to the precision of used
ressources, especially when the length variable is itself an array
or a pointer.
% So we may want to just have warning and not error message which is the
% default behavior.
\begin{PipsProp}{ERROR_ON_UNINITIALIZE_VLA}
ERROR_ON_UNINITIALIZE_VLA FALSE
\end{PipsProp}
\begin{PipsPass}{check_initialize_vla_with_preconditions}
\PipsPassRef{check_initialize_vla_with_preconditions}
uses the preconditions to check whether the length variable is initialized.
For this purpose, it checks if the length variable has a value,
but also verifies, if it is possible, that this value is greater than or
equal to zero.
\marginpar{The norm doesn't allow array initialization with 0.
But gcc and clang allow it with a warning (-pedantic).}
It only checks if it is greater than or equal to zero because the passes
\ref{subsection-initialize-vla} initialize them at 0 by default.
It may be useful to activate \PipsPropRef{SEMANTICS_ANALYZE_CONSTANT_PATH}
and/or \PipsPropRef{SEMANTICS_ANALYZE_SCALAR_POINTER_VARIABLES} to reduce
false positive if the length variable is itself an array or a pointer.
But it does not work everytime.
(it's not implemented yet.)
%This pass is run bottom-up, but can also work top-down.
\end{PipsPass}
\begin{PipsMake}
check_initialize_vla_with_preconditions
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
\end{PipsMake}
\begin{PipsPass}{check_initialize_vla_with_effects}
\PipsPassRef{check_initialize_vla_with_effects}
is not implemented yet.
It can required to set \PipsPropRef{VLA_EFFECT_READ} as \verb+TRUE+?
Depending if cumulated effects or out effects are used.
The idea is to check for each vla declaration, if the length variable
is exactly written before the declaration
(It can correspond to an exact write, or to be present in exact out effects
with \PipsPropRef{VLA_EFFECT_READ} at \verb+TRUE+).
This method doesn't permit to verify if the length variable is positive.
This pass can only be run bottom-up.
% NL: I don't think it can have better result than using preconditions
\end{PipsPass}
\begin{PipsMake}
check_initialize_vla_with_effects
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
% < MODULE.out_effects
\begin{PipsPass}{check_initialize_vla_with_regions}
\PipsPassRef{check_initialize_vla_with_regions}
is not implemented yet.
It can required to set \PipsPropRef{VLA_EFFECT_READ} as \verb+TRUE+?
Depending if regions or out regions are used.
The idea is to check for each vla declaration, if the length variable
is exactly written before the declaration
(It can correspond to an exact write, or to be present in exact out regions
with \PipsPropRef{VLA_EFFECT_READ} at \verb+TRUE+).
This method doesn't permit to verify if the length variable is positive.
It may suppress some false positive for vla declare with an array cell as length.
This pass can only be run bottom-up.
\end{PipsPass}
\begin{PipsMake}
check_initialize_vla_with_regions
< PROGRAM.entities
< MODULE.code
< MODULE.regions
\end{PipsMake}
% < MODULE.out_regions
\subsubsection{Initialize Variable Length Array}
\label{subsection-initialize-vla}
\index{Initialize Variable Length Array}
Similarly to the check \ref{subsection-check-initialize-vla},
there is two different ways to determine the variable length to initialize:
by using the preconditions or by using the effects/regions.
%% In fact is the same functions that done these two things:
%% the check and the list to initialize.
So we have different passes to generate the initialization.
\begin{PipsMake}
alias initialize_vla_with_preconditions 'Initialize Variable Length Array With Preconditions'
alias initialize_vla_with_effects 'Initialize Variable Length Array With Effects'
alias initialize_vla_with_regions 'Initialize Variable Length Array With Regions'
\end{PipsMake}
The only thing that differs in these passes is how the list of variables
to initialize is generated, and so the PIPS dependence ressources
that will be needed.
These passes initialize length variables at declaration times for scalar.
When the length variable is a cell of another array, it is initialized just
after the declaration of the array (not implemented yet).
For instance,
\begin{lstlisting}
int n, l[1];
...
int a[n];
int b[l[0]];
...
\end{lstlisting}
becomes
\begin{lstlisting}
int n=0, l[1];
l[0]=0;
...
int a[n];
int b[l[0]];
...
\end{lstlisting}
The passes uses the propoerty \PipsPropRef{INITIALIZE_VLA_VALUE} to know the
initial value, 0 by default.
\begin{PipsProp}{INITIALIZE_VLA_VALUE}
INITIALIZE_VLA_VALUE 0
\end{PipsProp}
\begin{PipsPass}{initialize_vla_with_preconditions}
\end{PipsPass}
\begin{PipsMake}
initialize_vla_with_preconditions > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
\end{PipsMake}
\begin{PipsPass}{initialize_vla_with_effects}
\end{PipsPass}
\begin{PipsMake}
initialize_vla_with_effects > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
\end{PipsMake}
% < MODULE.out_effects
\begin{PipsPass}{initialize_vla_with_regions}
\end{PipsPass}
\begin{PipsMake}
initialize_vla_with_regions > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.regions
\end{PipsMake}
% < MODULE.out_regions
\subsection{Freeze variables}
\label{subsection-freeze-variables}
\index{freeze variables}
\index{Specialize}
\begin{PipsPass}{freeze_variables}
Function \PipsPassRef{freeze_variables} produces code where variables
interactively specified by the user are transformed into
constants. This is useful when the functionality of a code must be
reduced. For instance, a code designed for N dimensions could be
reduced to a 3-D code by setting N to 3. This is not obvious when N
changes within the code. \marginpar{CA? More information? The variable
names are requested from the PIPS user?} This is useful to specialize
a code according to specific input data\footnote{See the CHiLL tool.}.
\end{PipsPass}
\begin{PipsMake}
alias freeze_variables 'Freeze Variables'
freeze_variables > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.cumulated_effects
\end{PipsMake}
%-----------End of Declaration Transformations -------------------------
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% MISC
\section{Miscellaneous transformations}
The following warning paragraphs should not be located here, but the
whole introduction has to be updated to take into account the merger
with properties-rc.tex, the new content (the transformation section
has been exploded) and the new passes such as gpips. No time right
now. FI.
All PIPS transformations assume that the initial code is legal
according to the language standard. In other words, its semantics is
well defined. Otherwise, it is impossible to maintain a constant
semantics through program transformations. So uninitialized variables,
for instance, can lead to codes that seem wrong, because they are
likely to give different outputs than the initial code. But this does
not matter as the initial code output is undefined and could well be
the new output,
Also, remember that dead code does not impact the semantics in an
observable way. Hence dead code can be transformed in apparently weird
ways. For instance, all loops that are part of a dead code section can
be found parallel, although they are obviously sequential, because all
the references will carry an unfeasible predicate. In fact, reference
A(I), placed in a dead code section, does not reference the memory and
does not have to be part of the dependence graph.
Dead code can crop out in many modules when a whole application linked
with a library is analyzed. All unused library modules are dead for
PIPS.
On the other hand, missing source modules synthesized by PIPS may also
lead to weird results because they are integrated in the application
with empty definitions. Their call sites have no impact on the
application semantics.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TYPE CHECK
\subsection{Type Checker}
\label{subsection-type-checker}
\index{TypeChecker}
Typecheck code according to Fortran standard + double-complex.
Typechecking is performed interprocedurally for user-defined functions.
Insert type conversions where implicitly needed.
Use typed intrinsics instead of generic ones.
Precompute constant conversions if appropriate (e.g. 16 to 16.0E0).
Add comments about type errors detected in the code.
Report back how much was done.
\begin{PipsMake}
type_checker > MODULE.code
< PROGRAM.entities
< MODULE.code
< CALLEES.code
\end{PipsMake}
Here are type checker options. Whether to deal with double complex or to
refuse them. Whether to add a summary of errors, conversions and
simplifications as a comment to the routine. Whether to always show complex
constructors.
\begin{PipsProp}{TYPE_CHECKER_DOUBLE_COMPLEX_EXTENSION}
TYPE_CHECKER_DOUBLE_COMPLEX_EXTENSION FALSE
\end{PipsProp}
\begin{PipsProp}{TYPE_CHECKER_LONG_DOUBLE_COMPLEX_EXTENSION}
TYPE_CHECKER_LONG_DOUBLE_COMPLEX_EXTENSION FALSE
\end{PipsProp}
\begin{PipsProp}{TYPE_CHECKER_ADD_SUMMARY}
TYPE_CHECKER_ADD_SUMMARY FALSE
\end{PipsProp}
\begin{PipsProp}{TYPE_CHECKER_EXPLICIT_COMPLEX_CONSTANTS}
TYPE_CHECKER_EXPLICIT_COMPLEX_CONSTANTS FALSE
\end{PipsProp}
\subsection{Manual Editing}
The window interfaces let the user edit the source files, because it
is very useful to demonstrate {\tt PIPS}. As with
\PipsPassRef{stf}, editing is not integrated like other program
transformations, and previously applied transformations are lost.
Consistency is however always preserved.
A general edit facility fully integrated in \Pipsmake{} is planned
for the (not so) near future. Not so near because user demand for this
feature is low.
Since {\tt tpips} can invoque any Shell command, it is also possible
to touch and edit source files.
\subsection{Transformation Test}
\label{subsection-transformation_test}
\begin{PipsPass}{transformation_test}
This is plug to implement quickly a program transformation requested
by a user. Currently, it is a full loop distribution suggested by
Alain \textsc{Darte} to compare different implementations, namely
Nestor and PIPS.
\end{PipsPass}
\begin{PipsMake}
alias transformation_test 'Transformation Test'
transformation_test > MODULE.code
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\section{Extensions Transformations}
\label{section-extensions_transformations}
\subsection{OpenMP Pragma}
\label{subsection-open_mp_pragma}
\index{OpenMP}
\begin{PipsPass}{ompify_code}
The following transformation reads the sequential code and generates
OpenMP pragma as an extension to statements. The pragmas produced
are based on the information previously computed by differents
phases and already stores in the pips internal representation of the
sequential code. It might be interesting to use the phase
internalize\_parallel\_code (see \S~\ref{sec:cons-parall-code})
before to apply ompify\_code in order to maximize the number of
parallel information available.
\end{PipsPass}
\begin{PipsMake}
ompify_code > MODULE.code
< MODULE.code
\end{PipsMake}
As defined in the ri, the pragma can be of different types. The following
property can be set to \verb|str| or \verb|expr|. Obviously, if the
property is set to \verb|str| then pragmas would be generated as strings
otherwise pragmas would be generated as expressions.
\begin{PipsProp}{PRAGMA_TYPE}
PRAGMA_TYPE "expr"
\end{PipsProp}
\begin{PipsPass}{omp_loop_parallel_threshold_set}
The PIPS phase OMP\_LOOP\_PARALLEL\_THRESHOLD\_SET allows to add the OpenMP
\verb|if| clause to all the OpenMP pragmas. Afterwards, the number of iterations
in the loop is evaluated dynamically and compared to the defined threshold.
The loop is parallelized only if the threshold is reached.
\end{PipsPass}
\begin{PipsMake}
omp_loop_parallel_threshold_set > MODULE.code
< MODULE.code
\end{PipsMake}
The OMP\_LOOP\_PARALLEL\_THRESHOLD\_VALUE property , is used as a parameter by the
PIPS phase OMP\_LOOP\_PARALLEL\_THRESHOLD\_SET. The number of iteration of the
parallel loop will be compared to that value in an omp if clause. The OpenMP
run time will decide dynamicaly to parallelize the loop if the number of
iteration is above this threshold.
\begin{PipsProp}{OMP_LOOP_PARALLEL_THRESHOLD_VALUE}
OMP_LOOP_PARALLEL_THRESHOLD_VALUE 0
\end{PipsProp}
The OMP\_IF\_CLAUSE\_RECURSIVE property , is used as a parameter by the
PIPS phase OMP\_LOOP\_PARALLEL\_THRESHOLD\_SET. If set to TRUE the number
of iterations of the inner loops will be used to test if the threshold is
reached. Otherwise only the nunber of iteration of the processed loop will be
used.
\begin{PipsProp}{OMP_IF_CLAUSE_RECURSIVE}
OMP_IF_CLAUSE_RECURSIVE TRUE
\end{PipsProp}
\begin{PipsPass}{omp_merge_pragma}
Compiler tends to produce many parallel loops which is generally not
optimal for performance. The following transformation merges nested
omp pragma in a unique omp pragma.
\end{PipsPass}
\begin{PipsMake}
omp_merge_pragma > MODULE.code
< MODULE.code
\end{PipsMake}
PIPS merges the omp pragma on the inner or outer loop depending on the
property OMP\_MERGE\_POLICY. This string property can be set to either
\verb|outer| or \verb|inner|.
\begin{PipsProp}{OMP_MERGE_POLICY}
OMP_MERGE_POLICY "outer"
\end{PipsProp}
The OMP\_MERGE\_PRAGMA phase with the \verb|inner| mode can be used after the
phase limit\_nested\_parallelism (see \S~\ref{sec:manage-parallel-loops}).
Such a combinaison allows to fine choose the loop depth you
really want to parallelize with OpenMP.
The merging of the if clause of the omp pragma follows its own rule.
This clause can be ignore without changing the output of the program,
it only changes the program perfomances.
Then three policies are offered to manage the if clause merging. The if clause
can simply be ignored. Or the if clauses can be merged alltogether using the
boolean opertaion \verb|or| or \verb|and|. When ignored, the if clause can be
later regenerated using the appropriated PIPS phase :
OMP\_LOOP\_PARALLEL\_THRESHOLD\_SET. To summarize, remenber that the property
can be set to \verb|ignore| \verb|or| or \verb|and|
\begin{PipsProp}{OMP_IF_MERGE_POLICY}
OMP_IF_MERGE_POLICY "ignore"
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% PRETTYPRINT
\chapter{Output Files (Prettyprinted Files)}
\label{section-output-files}
\index{Prettyprinter}
\Pips{} results for any analysis and/or transformations can be
displayed in several different formats. User views are the closest one
to the initial user source code. Sequential views are obtained by
prettyprinting the \Pips{} internal representation of modules. Code
can also be displayed graphically or using Emacs facilities (through a
property). Of course, parallelized versions are available. At the
program level, call graph and interprocedural control flow graphs,
with different degrees of ellipse, provide interesting summaries.
Dependence graphs can be shown, but they are not user-friendly. No
filtering interface is available. They mainly are useful for debugging
and for teaching purposes.
\section{Parsed Printed Files (User View)}
\begin{PipsPass}{parsed_printed_file}
\label{sec:parsed_printed_files}
\label{subsection-parsed-printed-files}
These are files containing a pretty-printed version of the {\em parsed} code,
before the controlizer is applied. It is the code display closest to the
user source code, because arcs in control flow graphs do not have to be
rewritten as {\tt GOTO} statements. However, it is inconsistent with the
internal representation of the code as soon a a code transformation
has been applied.
Bug: the inconsistence between the user view and the internal code
representation presently is not detected. Solution: do not use user views.
The Fortran statements may be
decorated with preconditions or transformers or complexities or any kind
of effects, including convex array regions,... depending on the
prettyprinter selected used to produce this file.
Transformers and preconditions require cumulated effects to build the
module value basis.
\end{PipsPass}
\subsection{Menu for User Views}
\begin{PipsMake}
alias parsed_printed_file 'User View'
alias print_source 'Basic'
alias print_source_transformers 'With Transformers'
alias print_source_preconditions 'With Preconditions'
alias print_source_total_preconditions 'With Total Preconditions'
alias print_source_regions 'With Regions'
alias print_source_in_regions 'With IN Regions'
alias print_source_out_regions 'With OUT Regions'
alias print_source_complexities 'With Complexities'
alias print_source_proper_effects 'With Proper Effects'
alias print_source_cumulated_effects 'With Cumulated Effects'
alias print_source_in_effects 'With IN Effects'
alias print_source_out_effects 'With OUT Effects'
alias print_source_continuation_conditions 'With Continuation Conditions'
\end{PipsMake}
\subsection{Standard User View}
\begin{PipsPass}{print_source}
Display the code without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_source > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
\end{PipsMake}
\subsection{User View with Transformers}
\begin{PipsPass}{print_source_transformers}
Display the code decorated with the transformers.
\end{PipsPass}
\begin{PipsMake}
print_source_transformers > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{User View with Preconditions}
\begin{PipsPass}{print_source_preconditions}
Display the code decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_source_preconditions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.preconditions
< MODULE.summary_precondition
< MODULE.summary_effects
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with Total Preconditions}
\begin{PipsPass}{print_source_total_preconditions}
Display the code decorated with the total preconditions.
\end{PipsPass}
\begin{PipsMake}
print_source_total_preconditions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.total_preconditions
< MODULE.summary_precondition
< MODULE.summary_effects
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with Continuation Conditions}
\begin{PipsPass}{print_source_continuation_conditions}
Display the code decorated with the continuation conditions.
\end{PipsPass}
\begin{PipsMake}
print_source_continuation_conditions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.must_continuation
< MODULE.may_continuation
< MODULE.must_summary_continuation
< MODULE.may_summary_continuation
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with Convex Array Regions}
\begin{PipsPass}{print_source_regions}
Display the code decorated with the regions.
\end{PipsPass}
\begin{PipsMake}
print_source_regions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with Invariant Convex Array Regions}
\begin{PipsPass}{print_source_inv_regions}
Display the code decorated with the regions.
\end{PipsPass}
\begin{PipsMake}
print_source_inv_regions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.inv_regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with IN Convex Array Regions}
\begin{PipsPass}{print_source_in_regions}
Display the code decorated with the IN regions.
\end{PipsPass}
\begin{PipsMake}
print_source_in_regions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with OUT Convex Array Regions}
\begin{PipsPass}{print_source_out_regions}
Display the code decorated with the OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_source_out_regions > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{User View with Complexities}
\index{Complexity}
\begin{PipsPass}{print_source_complexities}
Display the code decorated with the complexities.
\end{PipsPass}
\begin{PipsMake}
print_source_complexities > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.complexities
< MODULE.summary_complexity
\end{PipsMake}
\subsection{User View with Proper Effects}
\begin{PipsPass}{print_source_proper_effects}
Display the code decorated with the proper effects.
\end{PipsPass}
\begin{PipsMake}
print_source_proper_effects > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.proper_effects
\end{PipsMake}
\subsection{User View with Cumulated Effects}
\begin{PipsPass}{print_source_cumulated_effects}
Display the code decorated with the cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_source_cumulated_effects > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{User View with IN Effects}
\begin{PipsPass}{print_source_in_effects}
Display the code decorated with its IN effects.
\end{PipsPass}
\begin{PipsMake}
print_source_in_effects > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.in_effects
< MODULE.in_summary_effects
\end{PipsMake}
\subsection{User View with OUT Effects}
\begin{PipsPass}{print_source_out_effects}
Display the code decorated with its OUT effects.
\end{PipsPass}
\begin{PipsMake}
print_source_out_effects > MODULE.parsed_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.out_effects
< MODULE.out_summary_effects
\end{PipsMake}
\section{Printed File (Sequential Views)}
\begin{PipsPass}{printed_file}
These are files containing a pretty-printed version of the internal
representation, \verb+code+.
The statements may be decorated with the result of any analysis,
e.g.complexities, preconditions, transformers, convex array regions,\ldots{} depending on
the pretty printer used to produce this file.
To view C programs, it is a good idea to select a C pretty printer, for
example in \texttt{tpips} with:
\begin{alltt}
setproperty PRETTYPRINT_C_CODE TRUE (obsolete, replaced by PRETTYPRINT_LANGUAGE ``C'')
\end{alltt}
Transformers and preconditions (and regions?) require cumulated effects
to build the module value basis.
\end{PipsPass}
\subsection{Html output}
This is intended to be used with PIPS IR Navigator (tm).
\begin{PipsPass}{html_prettyprint}
Produce a html version of the internal representation of a PIPS Module.
The property \PipsPropRef{HTML_PRETTYPRINT_SYMBOL_TABLE} control whether the
symbol table should be included in the output.
\end{PipsPass}
\begin{PipsMake}
html_prettyprint > MODULE.html_ir_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{html_prettyprint_symbol_table}
Produce a html version of the symbol table, it's module-independent, it'll
produce the same output for each module (the symbol table is global/unique).
\end{PipsPass}
\begin{PipsMake}
html_prettyprint_symbol_table > PROGRAM.html_ir_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsProp}{HTML_PRETTYPRINT_SYMBOL_TABLE}
HTML_PRETTYPRINT_SYMBOL_TABLE FALSE
\end{PipsProp}
\subsection{Menu for Sequential Views}
\begin{PipsMake}
alias printed_file 'Sequential View'
alias print_code 'Statements Only'
alias print_code_transformers 'Statements & Transformers'
alias print_code_complexities 'Statements & Complexities'
alias print_code_preconditions 'Statements & Preconditions'
alias print_code_total_preconditions 'Statements & Total Preconditions'
alias print_code_regions 'Statements & Regions'
alias print_code_regions 'Statements & Invariant Regions'
alias print_code_complementary_sections 'Statements & Complementary Sections'
alias print_code_in_regions 'Statements & IN Regions'
alias print_code_out_regions 'Statements & OUT Regions'
alias print_code_privatized_regions 'Statements & Privatized Regions'
alias print_code_proper_effects 'Statements & Proper Effects'
alias print_code_in_effects 'Statements & IN Effects'
alias print_code_out_effects 'Statements & OUT Effects'
alias print_code_cumulated_effects 'Statements & Cumulated Effects'
alias print_code_proper_reductions 'Statements & Proper Reductions'
alias print_code_cumulated_reductions 'Statements & Cumulated Reductions'
alias print_code_static_control 'Statements & Static Controls'
alias print_code_continuation_conditions 'Statements & Continuation Conditions'
alias print_code_proper_regions 'Statements & Proper Regions'
alias print_code_proper_references 'Statements & Proper References'
alias print_code_cumulated_references 'Statements & Cumulated References'
alias print_initial_precondition 'Initial Preconditions'
alias print_code_points_to_list 'Statements & Points To'
alias print_code_simple_pointer_values 'Statements & Simple Pointer Values'
\end{PipsMake}
\subsection{Standard Sequential View}
\label{subsubsection-standard-sequential-view}
\index{Sequential View}
\begin{PipsPass}{print_code}
Display the code without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_code > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Sequential View with Transformers}
\begin{PipsPass}{print_code_transformers}
Display the code statements decorated with their transformers, except
for loops, which are decorated with the transformer from the loop
entering states to the loop body states. The effective loop
transformer, linking the input to the output state of a loop, is
recomputed when needed and can be deduced from the precondition of the
next statement after the loop\footnote{PIPS design maps statement to
decorations. For one loop statement, we need two transformers: one
transformer to propagate the loop precondition as loop body
precondition and a second transformer to propagate the loop
precondition as loop postcondition. The second transformer can be
deduced from the first one, but not the first one from the second
one, and the second transformer is not used to compute the loop
postcondition as it is more accurate to use the body
postcondition. It is however computed to derive a compound statement
transformer, e.g. the loop is part of block, which is part of a
module statement, and then junked.}.
\end{PipsPass}
\begin{PipsMake}
print_code_transformers > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Sequential View with Initial Preconditions}
\begin{PipsMake}
print_initial_precondition > MODULE.printed_file
< MODULE.initial_precondition
< PROGRAM.entities
print_program_precondition > PROGRAM.printed_file
< PROGRAM.program_precondition
< PROGRAM.entities
\end{PipsMake}
\subsection{Sequential View with Complexities}
\begin{PipsPass}{print_code_complexities}
Display the code decorated with the complexities.
\end{PipsPass}
\begin{PipsMake}
print_code_complexities > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.complexities
< MODULE.summary_complexity
\end{PipsMake}
\subsection{Sequential View with Preconditions}
\begin{PipsPass}{print_code_preconditions}
Display the code decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_code_preconditions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< MODULE.summary_precondition
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Sequential View with Total Preconditions}
\begin{PipsPass}{print_code_total_preconditions}
Display the code decorated with the total preconditions.
\end{PipsPass}
\begin{PipsMake}
print_code_total_preconditions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.total_preconditions
< MODULE.summary_total_precondition
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Sequential View with Continuation Conditions}
\begin{PipsPass}{print_code_continuation_conditions}
Display the code decorated with the continuation preconditions.
\end{PipsPass}
\begin{PipsMake}
print_code_continuation_conditions > MODULE.printed_file
< PROGRAM.entities
< MODULE.parsed_code
< MODULE.must_continuation
< MODULE.may_continuation
< MODULE.must_summary_continuation
< MODULE.may_summary_continuation
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Sequential View with Convex Array Regions}
\subsubsection{Sequential View with Plain Pointer Regions}
\label{sec:plain-pointer-regions}
\begin{PipsPass}{print_code_pointer_regions}
Display the code decorated with the pointer regions.
\end{PipsPass}
\begin{PipsMake}
print_code_pointer_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.pointer_regions
< MODULE.summary_pointer_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with Proper Pointer Regions}
\begin{PipsPass}{print_code_proper_pointer_regions}
Display the code decorated with the proper pointer regions.
\end{PipsPass}
\begin{PipsMake}
print_code_proper_pointer_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_pointer_regions
< MODULE.summary_pointer_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with Invariant Pointer Regions}
\begin{PipsPass}{print_code_inv_pointer_regions}
Display the code decorated with the invariant read/write pointer regions.
\end{PipsPass}
\begin{PipsMake}
print_code_inv_pointer_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.inv_pointer_regions
< MODULE.summary_pointer_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with Plain Convex Array Regions}
\label{sec:plain-regions}
\begin{PipsPass}{print_code_regions}
Display the code decorated with the regions.
\end{PipsPass}
\begin{PipsMake}
print_code_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with Proper Convex Array Regions}
\begin{PipsPass}{print_code_proper_regions}
Display the code decorated with the proper regions.
\end{PipsPass}
\begin{PipsMake}
print_code_proper_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with Invariant Convex Array Regions}
\begin{PipsPass}{print_code_inv_regions}
Display the code decorated with the invariant read/write regions.
\end{PipsPass}
\begin{PipsMake}
print_code_inv_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.inv_regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with IN Convex Array Regions}
\begin{PipsPass}{print_code_in_regions}
Display the code decorated with the IN regions.
\end{PipsPass}
\begin{PipsMake}
print_code_in_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with OUT Convex Array Regions}
\begin{PipsPass}{print_code_out_regions}
Display the code decorated with the OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_code_out_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsubsection{Sequential View with Privatized Convex Array Regions}
\begin{PipsPass}{print_code_privatized_regions}
Display the code decorated with the privatized regions.
\end{PipsPass}
\begin{PipsMake}
print_code_privatized_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.privatized_regions
< MODULE.copy_out_regions
\end{PipsMake}
\subsection{Sequential View with Complementary Sections}
\begin{PipsPass}{print_code_complementary_sections}
Display the code decorated with complementary sections.
\end{PipsPass}
\begin{PipsMake}
print_code_complementary_sections > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.compsec
< MODULE.summary_compsec
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Sequential View with Proper Effects}
\begin{PipsPass}{print_code_proper_pointer_effects}
Display the code decorated with the proper pointer effects.
\end{PipsPass}
\begin{PipsMake}
print_code_proper_pointer_effects > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_pointer_effects
\end{PipsMake}
\begin{PipsPass}{print_code_proper_effects}
Display the code decorated with the proper effects.
\end{PipsPass}
\begin{PipsMake}
print_code_proper_effects > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\begin{PipsPass}{print_code_proper_references}
Display the code decorated with the proper references.
\end{PipsPass}
\begin{PipsMake}
print_code_proper_references > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_references
\end{PipsMake}
\subsection{Sequential View with Cumulated Effects}
\begin{PipsPass}{print_code_cumulated_pointer_effects}
Display the code decorated with the cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_code_cumulated_pointer_effects > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_pointer_effects
< MODULE.summary_pointer_effects
\end{PipsMake}
\begin{PipsPass}{print_code_cumulated_effects}
Display the code decorated with the cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_code_cumulated_effects > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\begin{PipsPass}{print_code_cumulated_references}
Display the code decorated with the cumulated references.
\end{PipsPass}
\begin{PipsMake}
print_code_cumulated_references > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_references
\end{PipsMake}
\subsection{Sequential View with IN Effects}
\begin{PipsPass}{print_code_in_effects}
Display the code decorated with its IN effects.
\end{PipsPass}
\begin{PipsMake}
print_code_in_effects > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.in_effects
< MODULE.in_summary_effects
\end{PipsMake}
\subsection{Sequential View with OUT Effects}
\begin{PipsPass}{print_code_out_effects}
Display the code decorated with its OUT effects.
\end{PipsPass}
\begin{PipsMake}
print_code_out_effects > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.out_effects
< MODULE.out_summary_effects
\end{PipsMake}
\subsection{Sequential View with Live Paths}
\begin{PipsPass}{print_code_live_in_paths}
Display the code decorated with the live in paths.
\end{PipsPass}
\begin{PipsMake}
print_code_live_in_paths > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.live_in_paths
< MODULE.live_in_summary_paths
\end{PipsMake}
\begin{PipsPass}{print_code_live_out_paths}
Display the code decorated with the live out paths.
\end{PipsPass}
\begin{PipsMake}
print_code_live_out_paths > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.live_out_paths
< MODULE.live_out_summary_paths
\end{PipsMake}
\begin{PipsPass}{print_code_live_out_regions}
Display the code decorated with the live out regions.
\end{PipsPass}
\begin{PipsMake}
print_code_live_out_regions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.live_out_regions
\end{PipsMake}
\subsection{Sequential View with Proper Reductions}
\begin{PipsPass}{print_code_proper_reductions}
Display the code decorated with the proper reductions.
\end{PipsPass}
\begin{PipsMake}
print_code_proper_reductions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_reductions
\end{PipsMake}
\subsection{Sequential View with Cumulated Reductions}
\begin{PipsPass}{print_code_cumulated_reductions}
Display the code decorated with the cumulated reductions.
\end{PipsPass}
\begin{PipsMake}
print_code_cumulated_reductions > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_reductions
< MODULE.summary_reductions
\end{PipsMake}
\subsection{Sequential View with Static Control Information}
\begin{PipsPass}{print_code_static_control}
Display the code decorated with the static control.
\end{PipsPass}
\begin{PipsMake}
print_code_static_control > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.static_control
\end{PipsMake}
\subsection{Sequential View with Points-To Information}
%%@UserManualDocumentation: print_code_points_to_sets
Display the code decorated with the points to information.
%%!UserManualDocumentation
\begin{PipsMake}
print_code_points_to_list > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.points_to
\end{PipsMake}
\subsection{Sequential View with Simple Pointer Values}
\begin{PipsPass}{print_code_simple_pointer_values}
Displays the code with simple pointer values relationships.
\end{PipsPass}
\begin{PipsMake}
print_code_simple_pointer_values > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.simple_pointer_values
\end{PipsMake}
\begin{PipsPass}{print_code_genkill_pointer_values}
Displays the code with simple gen pointer values and kill sets.
\end{PipsPass}
\begin{PipsMake}
print_code_simple_gen_kill_pointer_values > MODULE.printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.simple_gen_pointer_values
< MODULE.simple_kill_pointer_values
\end{PipsMake}
\subsection{Prettyprint Properties}
\index{Prettyprinter (Code)}
\index{Code Prettyprinter}
\subsubsection{Language}
\index{PRETTYPRINT\_C\_CODE}
PIPS can handle many different languages. By default the PrettyPrinter uses
the native language as an output but it is also possible to prettyprint
Fortran code as C code. Possible values for the PRETTYPRINT\_LANGUAGE property
are: \texttt{native F95 F77 C}.
\begin{PipsProp}{PRETTYPRINT_LANGUAGE}
PRETTYPRINT_LANGUAGE "native"
\end{PipsProp}
\subsubsection{Layout}
\index{Analysis}
\index{PRETTYPRINT\_LOOSE}
\index{PRETTYPRINT\_STATEMENT\_NUMBER}
\index{PRETTYPRINT\_INDENTATION}
\index{PRETTYPRINT\_LISTS\_WITH\_SPACES}
\index{Statement number}
\index{PRETTYPRINT\_ANALYSES\_WITH\_LF}
When prettyprinting semantic information (preconditions, transformers and
regions), add a line before and after each piece of information if set to
\verb+TRUE+. The resulting code is more readable, but is larger.
\begin{PipsProp}{PRETTYPRINT_LOOSE}
PRETTYPRINT_LOOSE TRUE
\end{PipsProp}
By default, each prettyprinted line of Fortran or C code is terminated by its
statement number in columns 73-80, unless no significative statement
number is available. This feature is used to trace the origin of
statements after program transformations and parallelization steps.
This feature may be inconvenient for some compilers or because it
generates large source files. It may be turned off.
Note that the statement number is equal to the line number in the
function file, that is the source file obtained after PIPS
preprocessing\footnote{PIPS preprocessing usually includes the
standard C or Fortran preprocessing phase but also breaks down user
files into compilation units and function files, a.k.a. initial files
in Fortran and source files in C.} and filtering\footnote{Filtering is
applied on Fortran files only to perform file includes. It is
implemented in Perl.}, and not the user file, which is the file
submitted by the user and which may contain several functions.
Note also that some phases in \texttt{pips} may add new statement
that are not present in the original file. In this case the number of
the statement that requires such a transformation, is used for the
added statement.
\begin{PipsProp}{PRETTYPRINT_STATEMENT_NUMBER}
PRETTYPRINT_STATEMENT_NUMBER TRUE
\end{PipsProp}
Note: this default value is overriden to FALSE by
\verb/activate_language()/ for C and Fortran~95.
The structured control structure is shown by using an indentation. The
default value is 3.
\begin{PipsProp}{PRETTYPRINT_INDENTATION}
PRETTYPRINT_INDENTATION 3
\end{PipsProp}
Some people prefer to use a space after a comma to separate items in
lists such as declaration lists or parameter lists in order to improve
readability. Other people would rather pack more information per
line. The default option is chosen for readability.
\begin{PipsProp}{PRETTYPRINT_LISTS_WITH_SPACES}
PRETTYPRINT_LISTS_WITH_SPACES TRUE
\end{PipsProp}
Depending on the user goal, it may be better to isolate comments used
to display results of PIPS analyses from the source code
statement. This is the default option.
\begin{PipsProp}{PRETTYPRINT_ANALYSES_WITH_LF}
PRETTYPRINT_ANALYSES_WITH_LF TRUE
\end{PipsProp}
These qualifiers are not parsed and the prettyprinter ignores them by default,
set the following properties for seeing them.
%%
They are set by \verb|gpu_qualify_pointers|.
\begin{PipsProp}{PRETTYPRINT_GLOBAL_QUALIFIER}
PRETTYPRINT_GLOBAL_QUALIFIER ""
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_LOCAL_QUALIFIER}
PRETTYPRINT_LOCAL_QUALIFIER ""
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_CONSTANT_QUALIFIER}
PRETTYPRINT_CONSTANT_QUALIFIER ""
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_PRIVATE_QUALIFIER}
PRETTYPRINT_PRIVATE_QUALIFIER ""
\end{PipsProp}
%%
This feature only exists for the semantics analyses.
How to prettyprint C integer types:
%%
\begin{PipsProp}{PRETTYPRINT_C_CHAR_TYPE}
PRETTYPRINT_C_CHAR_TYPE "char"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_SHORT_TYPE}
PRETTYPRINT_C_SHORT_TYPE "short"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_INT_TYPE}
PRETTYPRINT_C_INT_TYPE "int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_LONG_TYPE}
PRETTYPRINT_C_LONG_TYPE "long int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_LONGLONG_TYPE}
PRETTYPRINT_C_LONGLONG_TYPE "long long int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_INT128_TYPE}
PRETTYPRINT_C_INT128_TYPE "__int128_t"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_UCHAR_TYPE}
PRETTYPRINT_C_UCHAR_TYPE "unsigned char"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_USHORT_TYPE}
PRETTYPRINT_C_USHORT_TYPE "unsigned short"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_UINT_TYPE}
PRETTYPRINT_C_UINT_TYPE "unsigned int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_ULONG_TYPE}
PRETTYPRINT_C_ULONG_TYPE "unsigned long int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_ULONGLONG_TYPE}
PRETTYPRINT_C_ULONGLONG_TYPE "unsigned long long int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_UINT128_TYPE}
PRETTYPRINT_C_UINT128_TYPE "__uint128_t"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_SCHAR_TYPE}
PRETTYPRINT_C_SCHAR_TYPE "signed char"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_SSHORT_TYPE}
PRETTYPRINT_C_SSHORT_TYPE "signed short"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_SINT_TYPE}
PRETTYPRINT_C_SINT_TYPE "signed int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_SLONG_TYPE}
PRETTYPRINT_C_SLONG_TYPE "signed long int"
\end{PipsProp}
\begin{PipsProp}{PRETTYPRINT_C_SLONGLONG_TYPE}
PRETTYPRINT_C_SLONGLONG_TYPE "signed long long int"
\end{PipsProp}
% no longer used {
% \begin{PipsProp}{PRETTYPRINT_FREE_FORM}
% PRETTYPRINT_FREE_FORM FALSE
% \end{PipsProp}
%
% This properties control the output of the prettyprinter, if set to false it'll
% be compliant with F77 Standard (line begin on 7th column and so on), else code
% will be display on a free form basis. This property is set to FALSE by default
% for Fortran77 file, and is set to TRUE for Fortran90/95 and C files.
% }
\subsubsection{Target Language Selection}
\index{HPF}
\index{Fortran 90}
\index{CM Fortran}
\index{Cray Fortran}
\index{Fortran (Cray)}
\index{Craft}
\index{PRETTYPRINT\_PARALLEL}
\paragraph{Parallel output style}
\label{sec:parall-outp-style}
How to print, from a syntactic point of view, a parallel do loop. Possible
values are: \texttt{do doall f90 hpf cray craft cmf omp}.
\begin{PipsProp}{PRETTYPRINT_PARALLEL}
PRETTYPRINT_PARALLEL "do"
\end{PipsProp}
\paragraph{Default sequential output style}
\label{sec:sequ-outp-style}
How to print, from a syntactic point of view, a parallel do loop for a
sequential code. Of course, by default, the sequential output is
sequential by definition, so the default value is \verb/"do"/.
But we may interested to change this behaviour to display after an
application of \PipsPassRef{internalize_parallel_code} the parallel code that is
hidden in the sequential code. Possible values are: \texttt{do doall f90
hpf cray craft cmf omp}.
By default, parallel information is displayed with am OpenMP flavor since
it is widely used nowadays.
\begin{PipsProp}{PRETTYPRINT_SEQUENTIAL_STYLE}
PRETTYPRINT_SEQUENTIAL_STYLE "omp"
\end{PipsProp}
\subsubsection{Display Analysis Results}
\index{PRETTYPRINT\_EFFECTS}
\index{PRETTYPRINT\_IO\_EFFECTS}
\index{PRETTYPRINT\_MEMORY\_EFFECTS\_ONLY}
\index{PRETTYPRINT\_REVERSE\_DOALL}
\index{PRETTYPRINT\_TRANSFORMER}
\index{PRETTYPRINT\_EXECUTION\_CONTEXT}
\index{PRETTYPRINT\_REGION}
\index{PRETTYPRINT\_SCALAR\_REGIONS}
Add statement effects as comments in output; not implemented (that way) yet.
\begin{PipsProp}{PRETTYPRINT_EFFECTS}
PRETTYPRINT_EFFECTS FALSE
\end{PipsProp}
The next property, \PipsPropRef{PRETTYPRINT_IO_EFFECTS}, is used to control
the computation of implicit statement IO effects and display them as
comments in output. The implicit effects on the logical unit are
simulated by a read/write action to an element of the array
\verb/TOP-LEVEL:LUNS()/, or to the whole array when the element is not
known at compile time. This is the standard behavior for PIPS. Some
phases, e.g. hpfc, may turn this option off, but it is much more risky
than to filter out abstract effects. Furthermore, the filtering is
better because it takes into account all abstract effects, not only IO
effects on logical units. PIPS users should definitely not turn off
this property as the semantic equivalence between the inout and the
output program is no longer guaranteed.
\begin{PipsProp}{PRETTYPRINT_IO_EFFECTS}
PRETTYPRINT_IO_EFFECTS TRUE
\end{PipsProp}
To transform C source code properly, variable and type declarations as
well as variable and type references must be tracked alhtough standard
use and def information is restricted to memory loads and stores
because the optimizations are performed at a lower level. Fortran~77
analyses do not need information about variable declarations and there
is not possibility of type definition. So the added information about
variable declarations and references may be pure noise. It is possible
to get rid of it by setting this property to TRUE, which is its
default value before August 2010. For C code, it is better to set it
to FALSE. For the time being, the default value cannot depend on the
code language.
\begin{PipsProp}{PRETTYPRINT_MEMORY_EFFECTS_ONLY}
PRETTYPRINT_MEMORY_EFFECTS_ONLY FALSE
\end{PipsProp}
Transform DOALL loops into sequential loops with an opposed increment
to check validity of the parallelization on a sequential machine. This
property is not implemented.
\begin{PipsProp}{PRETTYPRINT_REVERSE_DOALL}
PRETTYPRINT_REVERSE_DOALL FALSE
\end{PipsProp}
It is possible to print statement transformers as comments in
code. This property is not intended for PIPS users, but is used
internally. Transformers can be prettyprinted by using \verb/activate/
and \verb/PRINT_CODE_TRANSFORMERS/
\begin{PipsProp}{PRETTYPRINT_TRANSFORMER}
PRETTYPRINT_TRANSFORMER FALSE
\end{PipsProp}
It is possible to print statement preconditions as comments in
code. This property is not intended for PIPS users, but is used
internally. Preconditions can be prettyprinted by using \verb/activate/
and \verb/PRINT_CODE_PRECONDITIONS/
\begin{PipsProp}{PRETTYPRINT_EXECUTION_CONTEXT}
PRETTYPRINT_EXECUTION_CONTEXT FALSE
\end{PipsProp}
It is possible to print statement with convex array region information as comments in
code. This property is not intended for PIPS users, but is used
internally. Convex array regions can be prettyprinted by using \verb/activate/
and \verb/PRINT_CODE_REGIONS/ or \verb/PRINT_CODE_PROPER_REGIONS/
\begin{PipsProp}{PRETTYPRINT_REGION}
PRETTYPRINT_REGION FALSE
\end{PipsProp}
By default, convex array regions are printed for arrays only, but the
internal representation includes scalar variables as well. The default
option can be overriden with this property.
\begin{PipsProp}{PRETTYPRINT_SCALAR_REGIONS}
PRETTYPRINT_SCALAR_REGIONS FALSE
\end{PipsProp}
\subsubsection{Display Internals for Debugging}
\index{Debug}
\index{PRETTYPRINT\_BLOCKS}
\index{PRETTYPRINT\_ALL\_C\_BLOCKS}
\index{PRETTYPRINT\_UNSTRUCTURED}
\index{PRETTYPRINT\_ALL\_EFFECTS}
\index{PRETTYPRINT\_EMPTY\_BLOCKS}
\index{PRETTYPRINT\_STATEMENT\_ORDERING}
\index{PRETTYPRINT\_ALL\_LABELS}
\index{PRETTYPRINT\_DO\_LABEL\_AS\_COMMENT}
\index{PRETTYPRINT\_ALL\_PRIVATE\_VARIABLES}
\index{PRETTYPRINT\_CHECK\_IO\_STATEMENTS}
\index{PRETTYPRINT\_INTERNAL\_RETURN}
\index{PRETTYPRINT\_FINAL\_RETURN}
\index{PRETTYPRINT\_BLOCK\_IF\_ONLY}
\index{PRETTYPRINT\_WITH\_COMMON\_NAMES}
\index{PRETTYPRINT\_ALL\_PARENTHESES}
All these debugging options should be set to FALSE for normal operation,
when the prettyprinter is expected to produce code as close as possible to
the input form.
When they are turned on, the output is closer to the PIPS internal
representation.
Sequences are implicit in Fortran and in many programming languages but
they are internally represented. It is possible to print pieces of
information gathered about sequences by turning on this property.
\begin{PipsProp}{PRETTYPRINT_BLOCKS}
PRETTYPRINT_BLOCKS FALSE
\end{PipsProp}
To print all the C blocks (the \verb|{ }| in C, you can set the following
property:
\begin{PipsProp}{PRETTYPRINT_ALL_C_BLOCKS}
PRETTYPRINT_ALL_C_BLOCKS FALSE
\end{PipsProp}
This property is a C-specialized version of \verb|PRETTYPRINT_BLOCKS|,
since in C you can represent the blocks. You can combine this property
with a \verb|PRETTYPRINT_EMPTY_BLOCKS| set to true too. Right now, the
prettyprint of the C block is done in the wrong way, so if you use this
option, you will have redundant blocks inside instructions, but you will
have all the other hidden blocks too...
To print unstructured statements:
\begin{PipsProp}{PRETTYPRINT_UNSTRUCTURED}
PRETTYPRINT_UNSTRUCTURED FALSE
\end{PipsProp}
Print all effects for all statements regardless of \PipsPropRef{PRETTYPRINT_BLOCKS}
and \PipsPropRef{PRETTYPRINT_UNSTRUCTURED}.
\begin{PipsProp}{PRETTYPRINT_ALL_EFFECTS}
PRETTYPRINT_ALL_EFFECTS FALSE
\end{PipsProp}
Print empty statement blocks (false by default):
\begin{PipsProp}{PRETTYPRINT_EMPTY_BLOCKS}
PRETTYPRINT_EMPTY_BLOCKS FALSE
\end{PipsProp}
Print statement ordering information (false by default):
\begin{PipsProp}{PRETTYPRINT_STATEMENT_ORDERING}
PRETTYPRINT_STATEMENT_ORDERING FALSE
\end{PipsProp}
The next property controls the print out of DO loops and CONTINUE
statement. The code may be prettyprinted with DO label and CONTINUE
instead of DO-ENDDO, as well as with other useless CONTINUE (This property
encompasses a virtual \texttt{PRETTYPRINT\_ALL\_CONTINUE\_STATEMENTS}). If set
to FALSE, the default option, all useless CONTINUE statements are NOT
prettyprinted (ie. all those in structured parts of the code). This mostly
is a debugging option useful to understand better what is in the internal
representation.
\paragraph{Warning:} if set to TRUE, generated code may be
wrong after some code transformations like distribution...
\begin{PipsProp}{PRETTYPRINT_ALL_LABELS}
PRETTYPRINT_ALL_LABELS FALSE
\end{PipsProp}
Print code with DO label as comment.
\begin{PipsProp}{PRETTYPRINT_DO_LABEL_AS_COMMENT}
PRETTYPRINT_DO_LABEL_AS_COMMENT FALSE
\end{PipsProp}
Print private variables without regard for their effective use. By
default, private variables are shown only for parallel DO loops.
\begin{PipsProp}{PRETTYPRINT_ALL_PRIVATE_VARIABLES}
PRETTYPRINT_ALL_PRIVATE_VARIABLES FALSE
\end{PipsProp}
Non-standard variables and tests are generated to simulate the control
effect of Fortran IO statements. If an end-of-file condition is
encountered or if an io-error is raised, a jump to relevant labels may
occur if clauses \verb|ERR=| or \verb|END=| are defined in the IO
control list. These tests are normally not printed because they could
not be compiled by a standard Fortran compiler and because they are
redundant with the IO statement itself.
\begin{PipsProp}{PRETTYPRINT_CHECK_IO_STATEMENTS}
PRETTYPRINT_CHECK_IO_STATEMENTS FALSE
\end{PipsProp}
% no longer used {
% Manage internal RETURNs correctly if set to TRUE. This results in a
% slightly ugly (but correct) prettyprint, compared to a nicer (but
% possibly incorrect) default one. Internal returns are converted by the
% parser into GO~TO's the final and unique return.
%
% \begin{PipsProp}{PRETTYPRINT_INTERNAL_RETURN}
% PRETTYPRINT_INTERNAL_RETURN TRUE
% \end{PipsProp}
% }
Print the final RETURN statement, although this is useless according to
Fortran standard. Note that comments attached to the final return are
lost if it is not printed. Note also that the final RETURN may be part
of an unstructured in which case the previous property is required.
\begin{PipsProp}{PRETTYPRINT_FINAL_RETURN}
PRETTYPRINT_FINAL_RETURN FALSE
\end{PipsProp}
The internal representation is based on a standard IF structure, known as
{\em block if} in Fortran jargon. When possible, the prettyprinter uses
the {\em logical if} syntactical form to save lines and to produce an
output assumed closer to the input. When statements are decorated,
information gathered by PIPS may be lost. This property can be turned on
to have an output closer to the internal representation. Note that edges
of the control flow graphs may still be displayed as {\em logical if}
since they never carry any useful information\footnote{Information is
carried by the vertices (i.e. nodes). A CONTINUE statement is
generated to have an attachment node when
some information must be stored and displayed.}.
\begin{PipsProp}{PRETTYPRINT_BLOCK_IF_ONLY}
PRETTYPRINT_BLOCK_IF_ONLY FALSE
\end{PipsProp}
Effects give data that may be read and written in a procedure. These data
are represented by their entity name. By default the entity name used is
the shortest nom-ambiguous one. The
\PipsPropRef{PRETTYPRINT_EFFECT_WITH_FULL_ENTITY_NAME} property can be used to
force the usage of full entity name (module name + scope + local name).
\begin{PipsProp}{PRETTYPRINT_EFFECT_WITH_FULL_ENTITY_NAME}
PRETTYPRINT_EFFECT_WITH_FULL_ENTITY_NAME FALSE
\end{PipsProp}
In order to have information on the scope of commons, we need to know the
common in which the entity is declared if any. To get this information the
\PipsPropRef {PRETTYPRINT_WITH_COMMON_NAMES} property has to set to TRUE.
\begin{PipsProp}{PRETTYPRINT_WITH_COMMON_NAMES}
PRETTYPRINT_WITH_COMMON_NAMES FALSE
\end{PipsProp}
By default, expressions are simplified according to operator
precedences. It is possible to override this prettyprinting option and to
reflect the abstract tree with redundant parentheses.
\begin{PipsProp}{PRETTYPRINT_ALL_PARENTHESES}
PRETTYPRINT_ALL_PARENTHESES FALSE
\end{PipsProp}
By default, the C prettyprinter uses a minimum of braces to improve
readability. However, gcc advocates the use of more braces to avoid
some ambiguities about else clauses. In order to run succesfully gcc
with options -Wall and -Werror, it is possible to force the print-out
of all possible braces.
\begin{PipsProp}{PRETTYPRINT_ALL_C_BRACES}
PRETTYPRINT_ALL_C_BRACES FALSE
\end{PipsProp}
The previous property leads to hard to read source code. Property
\PipsPropRef{PRETTYPRINT_GCC_C_BRACES} is used to print only a few
additional braces required by gcc to avoid {\em ambiguous else}
warning messages.
\begin{PipsProp}{PRETTYPRINT_GCC_C_BRACES}
PRETTYPRINT_GCC_C_BRACES FALSE
\end{PipsProp}
\subsubsection{Declarations}
\label{subsubsection-declarations}
\index{Declaration}
\index{PRETTYPRINT\_ALL\_DECLARATIONS}
\index{PRETTYPRINT\_HEADER\_COMMENTS}
\index{PRETTYPRINT\_COMMONS}
\index{PRETTYPRINT\_VARIABLE\_DIMENSIONS}
By default in Fortran (and not in C), module declarations are preserved as
huge strings to produce an output as close as possible to the input (see
field \verb/decls_text/ in type \verb/code/). However, large program
transformations and code generation phases, e.g. hpfc, require updated
declarations.
Regenerate all variable declarations, including those variables not
declared in the user program. By default in Fortran, when possible, the
user declaration {\em text} is used to preserve comments.
\begin{PipsProp}{PRETTYPRINT_ALL_DECLARATIONS}
PRETTYPRINT_ALL_DECLARATIONS FALSE
\end{PipsProp}
If the prettyprint of the header and the declarations are done by
PIPS, try to display the genuine comments. Unfortunately, there is no
longer order relation between the comments and the declarations since
these are sorted by PIPS. By default, do not try to display the
comments when PIPS is generating the header.
\begin{PipsProp}{PRETTYPRINT_HEADER_COMMENTS}
PRETTYPRINT_HEADER_COMMENTS FALSE
\end{PipsProp}
How to regenerate the common declarations.
It can be \emph{none}, \emph{declaration}, or \emph{include}.
\begin{PipsProp}{PRETTYPRINT_COMMONS}
PRETTYPRINT_COMMONS "declaration"
\end{PipsProp}
\verb/DATA/ declarations are partially handled presently.
\begin{PipsProp}{PRETTYPRINT_DATA_STATEMENTS}
PRETTYPRINT_DATA_STATEMENTS TRUE
\end{PipsProp}
Where to put the dimension information, which must appear once.
The default is associated to the type information. It can be associated to
The type, or preferably to the common if any, or maybe to a dimension
statement, which is not implemented.
\begin{PipsProp}{PRETTYPRINT_VARIABLE_DIMENSIONS}
PRETTYPRINT_VARIABLE_DIMENSIONS "type"
\end{PipsProp}
\subsubsection{FORESYS Interface}
\index{Foresys}
\index{PRETTYPRINT\_FOR\_FORESYS}
Print transformers, preconditions and regions in a format accepted by
Foresys and Partita. Not maintained.
\begin{PipsProp}{PRETTYPRINT_FOR_FORESYS}
PRETTYPRINT_FOR_FORESYS FALSE
\end{PipsProp}
\subsubsection{HPFC Prettyprinter}
\index{HPF}
\index{Prettyprinter (HPF)}
\index{PRETTYPRINT\_HPFC}
To deal specifically with the prettyprint for hpfc.
\begin{PipsProp}{PRETTYPRINT_HPFC}
PRETTYPRINT_HPFC FALSE
\end{PipsProp}
\subsubsection{C Internal Prettyprinter}
\index{C}
\index{C Intrinsics)}
\index{C Run Time}
To unify code generation, Fortran intrinsics such as MIN, MAX, DIV, INT and
MOD are always used. MAX and MIN are especially convenient as they are
overloaded and accept any number of arguments. The generated code can
be prettyprinted as is and C code be fixed with macroprocessing.
This does not work for MIN and MAX because of their varying number of
arguments. Some code generating passes are using them with only two
arguments, which make the code hard to read if easy to preprocess.
Another option is to let the prettyprinter deal with the issue and
generate calls to some PIPS run-time functions or macros such as
\texttt{pips\_min()} and \texttt{pips\_max}. This is the default
behavior.
However, some passes such as function cloning use the prettyprinter
and then the parser to regenerate an internal representation. To
preserve the intrinsics used and to debug \PIPS{}, the next property
must be set.
\begin{PipsProp}{PRETTYPRINT_INTERNAL_INTRINSICS}
PRETTYPRINT_INTERNAL_INTRINSICS FALSE
\end{PipsProp}
To generate correct code, some transformations such as loop tiling, need to use the floor division with negative numbers. It can be implemented as PIPS run-time function or macro such as \texttt{pips\_div()}.
The default option is to keep the Fortran and C intrinsics ``/''.
\begin{PipsProp}{PRETTYPRINT_DIV_INTRINSICS}
PRETTYPRINT_DIV_INTRINSICS TRUE
\end{PipsProp}
\subsubsection{Interface to Emacs}
\index{Emacs}
\index{PRETTYPRINT\_ADD\_EMACS\_PROPERTIES}
The following property tells PIPS to attach various Emacs properties
for interactive purpose. Used internally by the Emacs pretyyprinter and
the \EPIPS{} user interface.
\begin{PipsProp}{PRETTYPRINT_ADD_EMACS_PROPERTIES}
PRETTYPRINT_ADD_EMACS_PROPERTIES FALSE
\end{PipsProp}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ICFG PRETTY
\section{Printed Files with the Intraprocedural Control Graph}
\begin{PipsPass}{graph_printed_file}
These are files containing a pretty-printed version of code to be
displayed with its intraprocedural control graph as a graph, for example
using the \PuDrawGraph program (formerly known as daVinci) or
\textsc{dot}/\textsc{GraphViz} tools. More concretely, use some scripts
like \verb/pips_unstructured2daVinci/ or \verb/pips_unstructured2dot/ to
display graphically these \texttt{.pref-graph} files.
The statements may be decorated with complexities,
preconditions, transformers, regions,\ldots{} depending on the printer
used to produce this file.
\end{PipsPass}
\subsection{Menu for Graph Views}
\begin{PipsMake}
alias graph_printed_file 'Control Graph Sequential View'
alias print_code_as_a_graph 'Graph with Statements Only'
alias print_code_as_a_graph_transformers 'Graph with Statements & Transformers'
alias print_code_as_a_graph_complexities 'Graph with Statements & Complexities'
alias print_code_as_a_graph_preconditions 'Graph with Statements & Preconditions'
alias print_code_as_a_graph_total_preconditions 'Graph with Statements & Total Preconditions'
alias print_code_as_a_graph_regions 'Graph with Statements & Regions'
alias print_code_as_a_graph_in_regions 'Graph with Statements & IN Regions'
alias print_code_as_a_graph_out_regions 'Graph with Statements & OUT Regions'
alias print_code_as_a_graph_proper_effects 'Graph with Statements & Proper Effects'
alias print_code_as_a_graph_cumulated_effects 'Graph with Statements & Cumulated Effects'
\end{PipsMake}
\subsection{Standard Graph View}
\begin{PipsPass}{print_code_as_a_graph}
Display the code without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Graph View with Transformers}
\begin{PipsPass}{print_code_as_a_graph_transformers}
Display the code decorated with the transformers.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_transformers > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Graph View with Complexities}
\begin{PipsPass}{print_code_as_a_graph_complexities}
Display the code decorated with the complexities.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_complexities > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.complexities
< MODULE.summary_complexity
\end{PipsMake}
\subsection{Graph View with Preconditions}
\begin{PipsPass}{print_code_as_a_graph_preconditions}
Display the code decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_preconditions > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< MODULE.summary_precondition
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Graph View with Preconditions}
\begin{PipsPass}{print_code_as_a_graph_total_preconditions}
Display the code decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_total_preconditions > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.total_preconditions
< MODULE.summary_total_postcondition
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Graph View with Regions}
\begin{PipsPass}{print_code_as_a_graph_regions}
Display the code decorated with the regions.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_regions > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Graph View with IN Regions}
\begin{PipsPass}{print_code_as_a_graph_in_regions}
Display the code decorated with the IN regions.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_in_regions > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Graph View with OUT Regions}
\begin{PipsPass}{print_code_as_a_graph_out_regions}
Display the code decorated with the OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_out_regions > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Graph View with Proper Effects}
\begin{PipsPass}{print_code_as_a_graph_proper_effects}
Display the code decorated with the proper effects.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_proper_effects > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
\end{PipsMake}
\subsection{Graph View with Cumulated Effects}
\begin{PipsPass}{print_code_as_a_graph_cumulated_effects}
Display the code decorated with the cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_code_as_a_graph_cumulated_effects > MODULE.graph_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{ICFG Properties}
\label{subsection-interprocedural-control-flow-graph}
\index{ICFG}
\index{ICFG\_IFs}
\index{ICFG\_DOs}
\index{ICFG\_DV}
\index{ICFG\_CALLEES\_TOPO\_SORT}
\index{ICFG\_DECOR}
\index{ICFG\_DRAW}
\index{ICFG\_INDENTATION}
\index{ICFG\_DEBUG}
This prettyprinter is NOT a call graph prettyprinter (see
Section~\ref{subsection-call-graph}). Control flow information can be
displayed and every call site is shown, possibly with some annotation like
precondition or region
This prettyprinter uses the module codes in the workspace database to
build the ICFG.
Print IF statements controlling call sites:
\begin{PipsProp}{ICFG_IFs}
ICFG_IFs FALSE
\end{PipsProp}
Print DO loops enclosing call sites:
\begin{PipsProp}{ICFG_DOs}
ICFG_DOs FALSE
\end{PipsProp}
It is possible to print the interprocedural control flow graph as text or
as a graph using daVinci format. By default, the text output is selected.
\begin{PipsProp}{ICFG_DV}
ICFG_DV FALSE
\end{PipsProp}
To be destroyed:
\begin{PipsProp}{ICFG_CALLEES_TOPO_SORT}
ICFG_CALLEES_TOPO_SORT FALSE
\end{PipsProp}
\begin{PipsProp}{ICFG_DRAW}
ICFG_DRAW TRUE
\end{PipsProp}
ICFG default indentation when going into a function or a structure.
\begin{PipsProp}{ICFG_INDENTATION}
ICFG_INDENTATION 4
\end{PipsProp}
Debugging level (should be \verb+ICFG_DEBUG_LEVEL+ and numeric instead
of boolean!):
\begin{PipsProp}{ICFG_DEBUG}
ICFG_DEBUG FALSE
\end{PipsProp}
Effects are often much too numerous to produce a useful interprocedural
control flow graph.
The integer property \PipsPropRef{RW_FILTERED_EFFECTS} is used to specify a
filtering criterion.
\begin{itemize}
\item 0: \verb/READ_ALL/,
\item 1: \verb/WRITE_ALL/,
\item 2: \verb/READWRITE_ALL/,
\item 3: \verb/READ_END/,
\item 4: \verb/WRITE_END/,
\item 5: \verb/READWRITE_END/, .
\end{itemize}
\begin{PipsProp}{RW_FILTERED_EFFECTS}
RW_FILTERED_EFFECTS 0
\end{PipsProp}
\subsection{Graph Properties}
\subsubsection{Interface to Graphics Prettyprinters}
\index{DaVinci}
\index{PRETTYPRINT\_UNSTRUCTURED\_AS\_A\_GRAPH}
\index{PRETTYPRINT\_UNSTRUCTURED\_AS\_A\_GRAPH\_VERBOSE}
To output a code with a hierarchical view of the control graph with
markers instead of a flat one. It purposes a display with a graph
browser such as \PdaVinci{}:
\begin{PipsProp}{PRETTYPRINT_UNSTRUCTURED_AS_A_GRAPH}
PRETTYPRINT_UNSTRUCTURED_AS_A_GRAPH FALSE
\end{PipsProp}
and to have a decorated output with the hexadecimal addresses of the
control nodes:
\begin{PipsProp}{PRETTYPRINT_UNSTRUCTURED_AS_A_GRAPH_VERBOSE}
PRETTYPRINT_UNSTRUCTURED_AS_A_GRAPH_VERBOSE FALSE
\end{PipsProp}
\section{Parallel Printed Files}
\label{subsection-parallel-printed-files}
\begin{PipsPass}{parallelprinted_file}
File containing a pretty-printed version of a
\verb+parallelized_code+. Several versions are available. The first one is
based on Fortran-77, extended with a DOALL construct. The second one is
based on Fortran-90. The third one generates CRAY Research directives as
comments if and only if the correspondent parallelization option was
selected (see Section{subsection-parallelization}).
No one knows why there is no underscore between parallel and printed...
\end{PipsPass}
%The first function \PipsPassRef{print_parallelized_code} can compute either one
%depending on the property variable \verb+PRETTYPRINT_FORTRAN90+ (out of
%date). The result is stored in a file suffixed by \verb+.parf+.
\subsection{Menu for Parallel View}
\begin{PipsMake}
alias parallelprinted_file 'Parallel View'
alias print_parallelized77_code 'Fortran 77'
alias print_parallelizedHPF_code 'HPF directives'
alias print_parallelizedOMP_code 'OMP directives'
alias print_parallelized90_code 'Fortran 90'
alias print_parallelizedcray_code 'Fortran Cray'
alias print_parallelizedMPI_code 'C MPI'
\end{PipsMake}
\subsection{Fortran 77 Parallel View}
\begin{PipsPass}{print_parallelized77_code}
Output a Fortran-77 code extended with {\tt DOALL} parallel constructs.
\end{PipsPass}
\begin{PipsMake}
print_parallelized77_code > MODULE.parallelprinted_file
< PROGRAM.entities
< MODULE.parallelized_code
\end{PipsMake}
%% print_parallelized_code > MODULE.parallelprinted_file
%% < PROGRAM.entities
%% < MODULE.parallelized_code
\subsection{HPF Directives Parallel View}
\begin{PipsPass}{print_parallelizedHPF_code}
Output the code decorated with HPF directives.
\end{PipsPass}
\begin{PipsMake}
print_parallelizedHPF_code > MODULE.parallelprinted_file
< PROGRAM.entities
< MODULE.parallelized_code
\end{PipsMake}
\subsection{OpenMP Directives Parallel View}
\begin{PipsPass}{print_parallelizedOMP_code}
Output the code decorated with OpenMP (OMP) directives.
\end{PipsPass}
\begin{PipsMake}
print_parallelizedOMP_code > MODULE.parallelprinted_file
< PROGRAM.entities
< MODULE.parallelized_code
\end{PipsMake}
\subsection{Fortran 90 Parallel View}
\begin{PipsPass}{print_parallelized90_code}
Output the code with some Fortran-90 array construct style.
\end{PipsPass}
\begin{PipsMake}
print_parallelized90_code > MODULE.parallelprinted_file
< PROGRAM.entities
< MODULE.parallelized_code
\end{PipsMake}
\subsection{Cray Fortran Parallel View}
\begin{PipsPass}{print_parallelizedcray_code}
Output the code decorated with parallel Cray directives. Note that the
Cray parallelization algorithm should have been used in order to match
Cray directives for parallel vector processors.
\end{PipsPass}
\begin{PipsMake}
print_parallelizedcray_code > MODULE.parallelprinted_file
< PROGRAM.entities
< MODULE.parallelized_code
< MODULE.cumulated_effects
\end{PipsMake}
\section{Call Graph Files}
\label{subsection-call-graph-files}
\index{Call Graph}
\begin{PipsPass}{callgraph_file}
This kind of file contains the sub call graph\footnote{It is not a
graph but a tree.} of a module. Of course, the call graph associated
to the MAIN module is the program call graph.
Each module can be decorated by {\em summary} information computed by
{\em one} of \Pips{} analyses.
If one module has different callers, its sub call tree is replicated
once for each caller\footnote{In the ICFG , the replication would
occur for each call site.}.
No fun to read, but how could we avoid it with a
text output? But it is useful to check large analyses.
\end{PipsPass}
The resource defined in this section is \verb/callgraph_file/ (note
the missing underscore between call and graph in callgraph...). This
is a {\em file} resource to be displayed, which cannot be loaded in
memory by {\em pipsdbm}.
Note that the input resource lists could be reduced to one resource,
the decoration. \Pipsmake{} would deduce the other ones. There is no
need for a transitive closure, but some people like it that way to
make resource usage verification possible...\marginpar{RK:
explain... FI: no idea; we would like to display any set of resources,
but the sets are too numerous to have a phase for each.}
\subsection{Menu for Call Graphs}
Aliases for call graphs must de different from aliases for
interprocedural control flow graphs (ICFG). A simple trick, a trailing
SPACE character, is used.
\begin{PipsMake}
alias callgraph_file 'Callgraph View'
alias print_call_graph 'Calls'
alias print_call_graph_with_complexities 'Calls & Complexities'
alias print_call_graph_with_preconditions 'Calls & Preconditions'
alias print_call_graph_with_total_preconditions 'Calls & Total Preconditions'
alias print_call_graph_with_transformers 'Calls & Transformers'
alias print_call_graph_with_proper_effects 'Calls & Proper effects'
alias print_call_graph_with_cumulated_effects 'Calls & Cumulated effects'
alias print_call_graph_with_regions 'Calls & Regions'
alias print_call_graph_with_in_regions 'Calls & In Regions'
alias print_call_graph_with_out_regions 'Calls & Out regions'
\end{PipsMake}
\subsection{Standard Call Graphs}
\begin{PipsPass}{print_call_graph}
To have the call graph without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_call_graph > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
\end{PipsMake}
\subsection{Call Graphs with Complexities}
\begin{PipsPass}{print_call_graph_with_complexities}
To have the call graph decorated with the complexities.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_complexities > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.summary_complexity
< MODULE.complexities
\end{PipsMake}
\subsection{Call Graphs with Preconditions}
\begin{PipsPass}{print_call_graph_with_preconditions}
To have the call graph decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_preconditions > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.summary_precondition
< MODULE.summary_effects
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Call Graphs with Total Preconditions}
\begin{PipsPass}{print_call_graph_with_total_preconditions}
To have the call graph decorated with the total preconditions.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_total_preconditions > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.summary_total_postcondition
< MODULE.summary_effects
< MODULE.total_preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Call Graphs with Transformers}
\begin{PipsPass}{print_call_graph_with_transformers}
To have the call graph decorated with the transformers.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_transformers > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.summary_transformer
< MODULE.summary_effects
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Call Graphs with Proper Effects}
\begin{PipsPass}{print_call_graph_with_proper_effects}
To have the call graph decorated with the proper effects.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_proper_effects > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.proper_effects
\end{PipsMake}
\subsection{Call Graphs with Cumulated Effects}
\begin{PipsPass}{print_call_graph_with_cumulated_effects}
To have the call graph decorated with the cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_cumulated_effects > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Call Graphs with Regions}
\begin{PipsPass}{print_call_graph_with_regions}
To have the call graph decorated with the regions.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_regions > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Call Graphs with IN Regions}
\begin{PipsPass}{print_call_graph_with_in_regions}
To have the call graph decorated with the IN regions.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_in_regions > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Call Graphs with OUT Regions}
\begin{PipsPass}{print_call_graph_with_out_regions}
To have the call graph decorated with the OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_call_graph_with_out_regions > MODULE.callgraph_file
< PROGRAM.entities
< MODULE.code
< CALLEES.callgraph_file
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
This library is used to display the calling relationship between modules.
It is different from the interprocedural call flow graph, ICFG (see
Section~\ref{subsection-interprocedural-control-flow-graph}). For example:
if A calls B twice, in callgraph, there is only one edge between A and B;
while in ICFG (see next section)), there are two edges between A and B,
since A contains two call sites.
The call graph is derived from the modules declarations. It does not
really the parsed code per se, but the code must have been parsed to have
up-to-date declarations in the symbol table.
Because of printout limitations, the call graph is developed into a tree
before it is printed. The sub-graph of a module appears as many times as
is has callers. The resulting printout may be very long.
There is no option for the callgraph prettyprinter except
for debugging.
Debugging level (should be \verb+CALLGRAPH_DEBUG_LEVEL+ and numeric!)
\begin{PipsProp}{CALLGRAPH_DEBUG}
CALLGRAPH_DEBUG FALSE
\end{PipsProp}
\section{DrawGraph Interprocedural Control Flow Graph Files (DVICFG)}
\begin{PipsPass}{dvicfg_file}
This is the file ICFG with format of graph \PuDrawGraph (formerly
daVinci). This should be generalized to be less tool-dependent.
\end{PipsPass}
\subsection{Menu for DVICFG's}
\begin{PipsMake}
alias dvicfg_file 'DVICFG View'
alias print_dvicfg_with_filtered_proper_effects 'Graphical Calls & Filtered proper effects'
\end{PipsMake}
\subsection{Minimal ICFG with graphical filtered Proper Effects}
\begin{PipsPass}{print_dvicfg_with_filtered_proper_effects}
Display the ICFG graphically decorated with the write proper effects filtered for a variable.
\end{PipsPass}
\begin{PipsMake}
print_dvicfg_with_filtered_proper_effects > MODULE.dvicfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.dvicfg_file
< MODULE.proper_effects
< CALLEES.summary_effects
\end{PipsMake}
\section{Interprocedural Control Flow Graph Files (ICFG)}
\begin{PipsPass}{icfg_file}
This kind of file contains a more or less precise interprocedural
control graph. The graph can be restricted to call sites only, to call
sites and enclosing DO loops or to call sites, enclosing DO loops and
controlling IF tests. This abstraction option is orthogonal to the set
of decorations, but \Pipsmake{} does not support this
orthogonality. All combinations are listed below.
Each call site can be decorated by associated information computed by one
of \Pips{} analyses.
\end{PipsPass}
\subsection{Menu for ICFG's}
Note: In order to avoid conflicts with callgraph aliases, a space
character is appended at each alias shared with call graph related
functions (Guillaume \textsc{Oget}).
\begin{PipsMake}
alias icfg_file 'ICFG View'
alias print_icfg 'Calls '
alias print_icfg_with_complexities 'Calls & Complexities '
alias print_icfg_with_preconditions 'Calls & Preconditions '
alias print_icfg_with_total_preconditions 'Calls & Total Preconditions '
alias print_icfg_with_transformers 'Calls & Transformers '
alias print_icfg_with_proper_effects 'Calls & Proper effects '
alias print_icfg_with_filtered_proper_effects 'Calls & Filtered proper effects '
alias print_icfg_with_cumulated_effects 'Calls & Cumulated effects '
alias print_icfg_with_regions 'Calls & Regions '
alias print_icfg_with_in_regions 'Calls & In Regions '
alias print_icfg_with_out_regions 'Calls & Out regions '
alias print_icfg_with_loops 'Calls & Loops'
alias print_icfg_with_loops_complexities 'Calls & Loops & Complexities'
alias print_icfg_with_loops_preconditions 'Calls & Loops & Preconditions'
alias print_icfg_with_loops_total_preconditions 'Calls & Loops & Total Preconditions'
alias print_icfg_with_loops_transformers 'Calls & Loops & Transformers'
alias print_icfg_with_loops_proper_effects 'Calls & Loops & Proper effects'
alias print_icfg_with_loops_cumulated_effects 'Calls & Loops & Cumulated effects'
alias print_icfg_with_loops_regions 'Calls & Loops & Regions'
alias print_icfg_with_loops_in_regions 'Calls & Loops & In Regions'
alias print_icfg_with_loops_out_regions 'Calls & Loops & Out regions'
alias print_icfg_with_control 'Calls & Control'
alias print_icfg_with_control_complexities 'Calls & Control & Complexities'
alias print_icfg_with_control_preconditions 'Calls & Control & Preconditions'
alias print_icfg_with_control_total_preconditions 'Calls & Control & Total Preconditions'
alias print_icfg_with_control_transformers 'Calls & Control & Transformers'
alias print_icfg_with_control_proper_effects 'Calls & Control & Proper effects'
alias print_icfg_with_control_cumulated_effects 'Calls & Control & Cumulated effects'
alias print_icfg_with_control_regions 'Calls & Control & Regions'
alias print_icfg_with_control_in_regions 'Calls & Control & In Regions'
alias print_icfg_with_control_out_regions 'Calls & Control & Out regions'
\end{PipsMake}
\subsection{Minimal ICFG}
\begin{PipsPass}{print_icfg}
Display the plain ICFG, without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_icfg > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
\end{PipsMake}
\subsection{Minimal ICFG with Complexities}
\begin{PipsPass}{print_icfg_with_complexities}
Display the ICFG decorated with complexities.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_complexities > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_complexity
< MODULE.complexities
\end{PipsMake}
\subsection{Minimal ICFG with Preconditions}
\begin{PipsPass}{print_icfg_with_preconditions}
Display the ICFG decorated with preconditions. They are expressed in the
\emph{callee} name space to evaluate the interest of cloning, depending on
the information available to the callee at a given call site.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_preconditions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_precondition
< MODULE.summary_effects
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Minimal ICFG with Preconditions}
\begin{PipsPass}{print_icfg_with_total_preconditions}
Display the ICFG decorated with total preconditions. They are expressed in the
\emph{callee} name space to evaluate the interest of cloning, depending on
the information available to the callee at a given call site.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_total_preconditions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_total_postcondition
< MODULE.summary_effects
< MODULE.total_preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Minimal ICFG with Transformers}
\begin{PipsPass}{print_icfg_with_transformers}
Display the ICFG decorated with transformers.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_transformers > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Minimal ICFG with Proper Effects}
\begin{PipsPass}{print_icfg_with_proper_effects}
Display the ICFG decorated with the proper effects.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_proper_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.proper_effects
\end{PipsMake}
\subsection{Minimal ICFG with filtered Proper Effects}
\begin{PipsPass}{print_icfg_with_filtered_proper_effects}
Display the ICFG decorated with the write proper effects filtered for a variable.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_filtered_proper_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.proper_effects
< CALLEES.summary_effects
\end{PipsMake}
\subsection{Minimal ICFG with Cumulated Effects}
\begin{PipsPass}{print_icfg_with_cumulated_effects}
Display the ICFG decorated with cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_cumulated_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{Minimal ICFG with Regions}
\begin{PipsPass}{print_icfg_with_regions}
Display the ICFG decorated with regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Minimal ICFG with IN Regions}
\begin{PipsPass}{print_icfg_with_in_regions}
Display the ICFG decorated with IN regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_in_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{Minimal ICFG with OUT Regions}
\begin{PipsPass}{print_icfg_with_out_regions}
Display the ICFG decorated with OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_out_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Loops}
\begin{PipsPass}{print_icfg_with_loops}
Display the plain ICFG with loops, without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
\end{PipsMake}
\subsection{ICFG with Loops and Complexities}
\begin{PipsPass}{print_icfg_with_loops_complexities}
Display the ICFG decorated with loops and complexities.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_complexities > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_complexity
< MODULE.complexities
\end{PipsMake}
\subsection{ICFG with Loops and Preconditions}
\begin{PipsPass}{print_icfg_with_loops_preconditions}
Display the ICFG decorated with preconditions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_preconditions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_precondition
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Loops and Total Preconditions}
\begin{PipsPass}{print_icfg_with_loops_total_preconditions}
Display the ICFG decorated with total preconditions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_total_preconditions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_total_postcondition
< MODULE.total_preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Loops and Transformers}
\begin{PipsPass}{print_icfg_with_loops_transformers}
Display the ICFG decorated with transformers.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_transformers > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Loops and Proper Effects}
\begin{PipsPass}{print_icfg_with_loops_proper_effects}
Display the ICFG decorated with proper effects.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_proper_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.proper_effects
\end{PipsMake}
\subsection{ICFG with Loops and Cumulated Effects}
\begin{PipsPass}{print_icfg_with_loops_cumulated_effects}
Display the ICFG decorated with cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_cumulated_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{ICFG with Loops and Regions}
\begin{PipsPass}{print_icfg_with_loops_regions}
Display the ICFG decorated with regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Loops and IN Regions}
\begin{PipsPass}{print_icfg_with_loops_in_regions}
Display the ICFG decorated with IN regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_in_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Loops and OUT Regions}
\begin{PipsPass}{print_icfg_with_loops_out_regions}
Display the ICFG decorated with the OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_loops_out_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Control}
\begin{PipsPass}{print_icfg_with_control}
Display the plain ICFG with loops, without any decoration.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
\end{PipsMake}
\subsection{ICFG with Control and Complexities}
\begin{PipsPass}{print_icfg_with_control_complexities}
Display the ICFG decorated with the complexities.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_complexities > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_complexity
< MODULE.complexities
\end{PipsMake}
\subsection{ICFG with Control and Preconditions}
\begin{PipsPass}{print_icfg_with_control_preconditions}
Display the ICFG decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_preconditions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_precondition
< MODULE.preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Control and Total Preconditions}
\begin{PipsPass}{print_icfg_with_control_total_preconditions}
Display the ICFG decorated with the preconditions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_total_preconditions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.summary_total_postcondition
< MODULE.total_preconditions
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Control and Transformers}
\begin{PipsPass}{print_icfg_with_control_transformers}
Display the ICFG decorated with the transformers.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_transformers > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.transformers
< MODULE.summary_transformer
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Control and Proper Effects}
\begin{PipsPass}{print_icfg_with_control_proper_effects}
Display the ICFG decorated with the proper effects.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_proper_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.proper_effects
\end{PipsMake}
\subsection{ICFG with Control and Cumulated Effects}
\begin{PipsPass}{print_icfg_with_control_cumulated_effects}
Display the ICFG decorated with the cumulated effects.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_cumulated_effects > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.cumulated_effects
< MODULE.summary_effects
\end{PipsMake}
\subsection{ICFG with Control and Regions}
\begin{PipsPass}{print_icfg_with_control_regions}
Display the ICFG decorated with the regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.regions
< MODULE.summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Control and IN Regions}
\begin{PipsPass}{print_icfg_with_control_in_regions}
Display the ICFG decorated with the IN regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_in_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.in_regions
< MODULE.in_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\subsection{ICFG with Control and OUT Regions}
\begin{PipsPass}{print_icfg_with_control_out_regions}
Display the ICFG decorated with the OUT regions.
\end{PipsPass}
\begin{PipsMake}
print_icfg_with_control_out_regions > MODULE.icfg_file
< PROGRAM.entities
< MODULE.code
< CALLEES.icfg_file
< MODULE.out_regions
< MODULE.out_summary_regions
< MODULE.preconditions
< MODULE.transformers
< MODULE.cumulated_effects
\end{PipsMake}
\section{Data Dependence Graph File}
\label{subsection-dependence-graph-file}
\index{FDG}
\index{Data Dependence Graph}
\begin{PipsPass}{dg_file}
This file contains the data dependence graph.
Known bug: there is no precise relationship between the dependence graph
seen by the parallelization algorithms selected and any of its many views...
\end{PipsPass}
Two text formats are available: the default format which includes
dependence cone and a SRU format which packs all information about one
arc on one line and which replaces the dependence cone by the
dependence direction vector (DDV). The line numbers given with this
format are in fact relative (approximatively...) to the statement line
in the \Pips{} output.
The SRU format was defined with researchers at Slippery Rock
University (PA). The property
\begin{center}
\PipsPropRef{PRINT_DEPENDENCE_GRAPH_USING_SRU_FORMAT}
\end{center}
is set to FALSE by default.
Two graph format, daVinci and GraphViz, are also available.
\subsection{Menu For Dependence Graph Views}
\begin{PipsMake}
alias dg_file 'Dependence Graph View'
alias print_effective_dependence_graph 'Default'
alias print_loop_carried_dependence_graph 'Loop Carried Only'
alias print_whole_dependence_graph 'All arcs'
alias print_filtered_dependence_graph 'Filtered Arcs'
alias print_filtered_dependence_daVinci_graph 'Filtered Arcs Output to uDrawGraph'
alias impact_check 'Check alias impact'
alias print_chains_graph 'Chains'
alias print_dot_chains_graph 'Chains (for dot)'
alias print_dot_dependence_graph 'Dependence graph (for dot)'
\end{PipsMake}
\subsection{Effective Dependence Graph View}
\begin{PipsPass}{print_effective_dependence_graph}
Display dependence levels for loop-carried and non-loop-carried dependence
arcs due to non-privatized variables. Do not display dependence cones.
\end{PipsPass}
\begin{PipsMake}
print_effective_dependence_graph > MODULE.dg_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\subsection{Loop-Carried Dependence Graph View}
\begin{PipsPass}{print_loop_carried_dependence_graph}
Display dependence levels for loop-carried dependence arcs only. Ignore
arcs labeled by private variables and do not print dependence cones.
\end{PipsPass}
\begin{PipsMake}
print_loop_carried_dependence_graph > MODULE.dg_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\subsection{Whole Dependence Graph View}
\begin{PipsPass}{print_whole_dependence_graph}
Display dependence levels and dependence polyhedra/cones for all
dependence arcs, whether they are loop carried or not, whether they are
due to a private variable (and ignored by parallelization algorithms) or
not. Dependence cones labeling arcs are printed too.
\end{PipsPass}
\begin{PipsMake}
print_whole_dependence_graph > MODULE.dg_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\subsection{Filtered Dependence Graph View}
\begin{PipsPass}{print_filtered_dependence_graph}
Same as \PipsPassRef{print_whole_dependence_graph} but it's filtered by
some variables. Variables to filter is a comma separated list set by
user via property ``EFFECTS\_FILTER\_ON\_VARIABLE''.
\end{PipsPass}
\begin{PipsMake}
print_filtered_dependence_graph > MODULE.dg_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\subsection{Filtered Dependence daVinci Graph View}
\begin{PipsPass}{print_filtered_dependence_daVinci_graph}
Same as \PipsPassRef{print_filtered_dependence_graph} but its output is
\PuDrawGraph format.
\end{PipsPass}
\begin{PipsMake}
print_filtered_dependence_daVinci_graph > MODULE.dvdg_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\subsection{Impact Check}
\begin{PipsPass}{impact_check}
Check impact of alias on the dependance graph.\marginpar{RK: What is
that? FI: Maybe, we should sign our contributions? See validation?}
\end{PipsPass}
Note: the signature of the pass implies that it is a transformation
pass, not a display pass. The location of its description is wrong.
\begin{PipsMake}
impact_check > MODULE.code
< PROGRAM.entities
< MODULE.alias_associations
< MODULE.cumulated_effects
< MODULE.summary_effects
< MODULE.proper_effects
< MODULE.preconditions
< MODULE.summary_precondition
< MODULE.dg
< ALL.code
\end{PipsMake}
\subsection{Chains Graph View}
\begin{PipsPass}{print_chains_graph}
Display the def-use or chains graph in a textual format. The following
properties control the output:
\PipsPropRef{PRINT_DEPENDENCE_GRAPH}
\PipsPropRef{PRINT_DEPENDENCE_GRAPH_WITHOUT_PRIVATIZED_DEPS}
\PipsPropRef{PRINT_DEPENDENCE_GRAPH_WITHOUT_NOLOOPCARRIED_DEPS}
\PipsPropRef{PRINT_DEPENDENCE_GRAPH_WITH_DEPENDENCE_CONES}
\PipsPropRef{PRINT_DEPENDENCE_GRAPH_USING_SRU_FORMAT}
\end{PipsPass}
\begin{PipsMake}
print_chains_graph > MODULE.dg_file
< PROGRAM.entities
< MODULE.code
< MODULE.chains
\end{PipsMake}
\subsection{Chains Graph Graphviz Dot View}
\begin{PipsPass}{print_dot_chains_graph}
Display the chains graph in graphviz dot format.
\end{PipsPass}
\begin{PipsMake}
print_dot_chains_graph > MODULE.dotdg_file
< PROGRAM.entities
< MODULE.code
< MODULE.chains
\end{PipsMake}
\subsection{Data Dependence Graph Graphviz Dot View}
\begin{PipsPass}{print_dot_dependence_graph}
Display the dependence graph in graphviz dot format.
Using pyps, some convenient functions are provide, for instance :
\begin{lstlisting}[language=python]
import pypsex
w = workspace(...)
w.fun.my_function_name.view_dg()
\end{lstlisting}
\noindent
which generate in the current directory a file named my\_function\_name.png.
\end{PipsPass}
\begin{PipsMake}
print_dot_dependence_graph > MODULE.dotdg_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\subsubsection{Properties Used to Select Arcs to Display}
\index{Data Dependence Graph}
\index{Prettyprinter (DDG)}
\index{DDG Prettyprinter}
\index{PRINT\_DEPENDENCE\_GRAPH}
\index{PRINT\_DEPENDENCE\_GRAPH\_WITHOUT\_PRIVATIZED\_DEPS}
\index{PRINT\_DEPENDENCE\_GRAPH\_WITHOUT\_NOLOOPCARRIED\_DEPS}
\index{PRINT\_DEPENDENCE\_GRAPH\_WITH\_DEPENDENCE\_CONES}
\index{PRINT\_DEPENDENCE\_GRAPH\_USING\_SRU\_FORMAT}
Here are the properties used to control the printing of dependence
graphs in a file called {\em module\_name}.{\tt dg}. These properties
should not be used explicitly because they are set implicitly by the
different print-out procedures available in \verb/pipsmake.rc/. However,
not all combinations are available from \verb/pipsmake.rc/.
\begin{PipsProp}{PRINT_DEPENDENCE_GRAPH}
PRINT_DEPENDENCE_GRAPH FALSE
\end{PipsProp}
To print the dependence graph without the dependences on privatized
variables
\begin{PipsProp}{PRINT_DEPENDENCE_GRAPH_WITHOUT_PRIVATIZED_DEPS}
PRINT_DEPENDENCE_GRAPH_WITHOUT_PRIVATIZED_DEPS FALSE
\end{PipsProp}
To print the dependence graph without the non-loop-carried dependences:
\begin{PipsProp}{PRINT_DEPENDENCE_GRAPH_WITHOUT_NOLOOPCARRIED_DEPS}
PRINT_DEPENDENCE_GRAPH_WITHOUT_NOLOOPCARRIED_DEPS FALSE
\end{PipsProp}
To print the dependence graph with the dependence cones:
\begin{PipsProp}{PRINT_DEPENDENCE_GRAPH_WITH_DEPENDENCE_CONES}
PRINT_DEPENDENCE_GRAPH_WITH_DEPENDENCE_CONES FALSE
\end{PipsProp}
To print the dependence graph in a computer friendly format defined by
Deborah Whitfield (SRU):
\begin{PipsProp}{PRINT_DEPENDENCE_GRAPH_USING_SRU_FORMAT}
PRINT_DEPENDENCE_GRAPH_USING_SRU_FORMAT FALSE
\end{PipsProp}
\subsection{Properties for Dot output}
Here are the properties available to tune the Dot output, read dot
documentation for available colors, style, shape, etc.
\begin{PipsProp}{PRINT_DOTDG_STATEMENT}
PRINT_DOTDG_STATEMENT TRUE
\end{PipsProp}
Print statement code and not only ordering inside nodes.
\begin{PipsProp}{PRINT_DOTDG_TOP_DOWN_ORDERED}
PRINT_DOTDG_TOP_DOWN_ORDERED TRUE
\end{PipsProp}
Add a constraint on top-down ordering for node instead of free dot placement.
\begin{PipsProp}{PRINT_DOTDG_CENTERED}
PRINT_DOTDG_CENTERED FALSE
\end{PipsProp}
Should dot produce a centered graph ?
\begin{PipsProp}{PRINT_DOTDG_TITLE}
PRINT_DOTDG_TITLE ""
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_TITLE_POSITION}
PRINT_DOTDG_TITLE_POSITION "b"
\end{PipsProp}
Title and title position (t for top and b for bottom) for the graph.
\begin{PipsProp}{PRINT_DOTDG_BACKGROUND}
PRINT_DOTDG_BACKGROUND "white"
\end{PipsProp}
Main Background.
\begin{PipsProp}{PRINT_DOTDG_NODE_SHAPE}
PRINT_DOTDG_NODE_SHAPE "box"
\end{PipsProp}
Shape for statement nodes.
\begin{PipsProp}{PRINT_DOTDG_NODE_SHAPE_COLOR}
PRINT_DOTDG_NODE_SHAPE_COLOR "black"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_NODE_FILL_COLOR}
PRINT_DOTDG_NODE_FILL_COLOR "white"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_NODE_FONT_COLOR}
PRINT_DOTDG_NODE_FONT_COLOR "black"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_NODE_FONT_SIZE}
PRINT_DOTDG_NODE_FONT_SIZE "18"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_NODE_FONT_FACE}
PRINT_DOTDG_NODE_FONT_FACE "Times-Roman"
\end{PipsProp}
Color for the shape, background, and font of each node.
\begin{PipsProp}{PRINT_DOTDG_FLOW_DEP_COLOR}
PRINT_DOTDG_FLOW_DEP_COLOR "red"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_ANTI_DEP_COLOR}
PRINT_DOTDG_ANTI_DEP_COLOR "green"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_OUTPUT_DEP_COLOR}
PRINT_DOTDG_OUTPUT_DEP_COLOR "blue"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_INPUT_DEP_COLOR}
PRINT_DOTDG_INPUT_DEP_COLOR "black"
\end{PipsProp}
Color for each type of dependence
\begin{PipsProp}{PRINT_DOTDG_FLOW_DEP_STYLE}
PRINT_DOTDG_FLOW_DEP_STYLE "solid"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_ANTI_DEP_STYLE}
PRINT_DOTDG_ANTI_DEP_STYLE "solid"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_OUTPUT_DEP_STYLE}
PRINT_DOTDG_OUTPUT_DEP_STYLE "solid"
\end{PipsProp}
\begin{PipsProp}{PRINT_DOTDG_INPUT_DEP_STYLE}
PRINT_DOTDG_INPUT_DEP_STYLE "dashed"
\end{PipsProp}
Style for each type of dependence
\subsection{Loop Nest Dependence Cone}
\begin{PipsPass}{print_loopnest_dependence_cone}
Before applying a loop transformation, information on the loop nest dependencies can help to check its legality.
This pass enumerates the elements of the dependence cone that represent dependencies inside the loop nest.
Loop label should be given.
\end{PipsPass}
\begin{PipsMake}
alias dc_file 'Loopnest Dependence Cone'
print_loopnest_dependence_cone > MODULE.dc_file
< PROGRAM.entities
< MODULE.code
< MODULE.dg
\end{PipsMake}
\section{Fortran to C prettyprinter}
\begin{PipsPass}{print_crough}
A basic and experimental C dumper to output a Fortran program in C
code. It is not the same as the default pretty printer that is normaly used
to pretty print C code in C. This pass is mainly use inside PIPS
and Par4All to be able to generate call to CUDA kernels from a fortran code.
The kernel is supposed not to use I/O intrinsics (such as WRITE, READ),
they are not handle at the moment (and not usefull in the CUDA context)
by the crough printer. However it is still possible to print the C code with
the name of the fortran intrinsic using the property
CROUGH\_PRINT\_UNKNOWN\_INTRINSIC.
\end{PipsPass}
\begin{PipsMake}
print_crough > MODULE.crough
< PROGRAM.entities
< MODULE.code
< MODULE.summary_effects
\end{PipsMake}
\begin{PipsPass}{print_c_code}
Display the crough output of a fortran function.
\end{PipsPass}
\begin{PipsMake}
print_c_code > MODULE.c_printed_file
< MODULE.crough
\end{PipsMake}
\begin{PipsPass}{print_interface}
Once C version of fortran code has been generated, ones might like to call this
C functions from fortran code. A convenient way to do this is to use an
interface in the fortran code. PIPS can generate the interface module for any
function using the following pass.
\end{PipsPass}
\begin{PipsMake}
print_interface > MODULE.interface
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\subsection{Properties for Fortran to C prettyprinter}
By default the crough pass fails if it encounters a fortran intrinsic that
cannot be translated to C. However it is still possible to print the C code
with the name of the fortran intrinsic using the following property.
\begin{PipsProp}{CROUGH_PRINT_UNKNOWN_INTRINSIC}
CROUGH_PRINT_UNKNOWN_INTRINSIC FALSE
\end{PipsProp}
By default the crough pass tries to match the best C type for any Fortran
type. Here is the matches between Fortran and C variables:
\begin{itemize}
\item INTEGER is matched to int.
\item INTEGER*4 is matched to int.
\item INTEGER*8 is matched to long long int.
\item REAL is matched to float.
\item REAL*4 is matched to float.
\item REAL*8 is matched to double.
\end{itemize}
However, many Fortran compilers (ifort, gfortran) allow to change
the type size at compile time. It is possible to do the same by setting the
property CROUGH\_USER\_DEFINED\_TYPE to TRUE. In such a case the include file
specified by the property CROUGH\_INCLUDE\_FILE is included by any file
generated using crough. It has to define (using \#define or
typedef) the two types defined by the properties CROUGH\_INTEGER\_TYPE and
CROUGH\_REAL\_TYPE. Obviously those types are used in the generated C file to
declare variables that has the types INTEGER or REAL in the original Fortan
file. When choosing that solution all INTEGER and REAL (including INTEGER*4,
INTEGER*8, REAL*4 and REAL*8) variables will be set
to the same user defined types.
\begin{PipsProp}{CROUGH_USER_DEFINED_TYPE}
CROUGH_USER_DEFINED_TYPE FALSE
\end{PipsProp}
\begin{PipsProp}{CROUGH_INCLUDE_FILE}
CROUGH_INCLUDE_FILE "p4a_crough_types.h"
\end{PipsProp}
\begin{PipsProp}{CROUGH_INTEGER_TYPE}
CROUGH_INTEGER_TYPE "p4a_int"
\end{PipsProp}
\begin{PipsProp}{CROUGH_REAL_TYPE}
CROUGH_REAL_TYPE "p4a_real"
\end{PipsProp}
Is is possible to prettyprint function parameters that are arrays as pointers
using the property CROUGH\_ARRAY\_PARAMETER\_AS\_POINTER
\begin{PipsProp}{CROUGH_ARRAY_PARAMETER_AS_POINTER}
CROUGH_ARRAY_PARAMETER_AS_POINTER FALSE
\end{PipsProp}
When PRETTYPRINT\_C\_FUNCTION\_NAME\_WITH\_UNDERSCORE is set to TRUE, an
underscore is added at the end of the module name. This is needed when
translating only some part of a Fortran Program to C. This property must be
used with great care, so that only interface function names are changed : the
function names in subsequent calls are not modified. An other solution to call
a C function from a fortran program is to use/declare an interface in the
fortran source code (This feature is part of the Fortran 2003 standard
but many Fortran95 compilers support it). The property
CROUGH\_FORTRAN\_USES\_INTERFACE can be set to TRUE when the Fotran code
integrates interfaces. In such a case, the unmodified scalar function
parameters (by the function or any of its callees) are expected to be passed by
values, the other parameters are passed by pointers. Finally when using
interfaces it is also possible to pass all the scalar variables by values using
the propety CROUGH\_SCALAR\_BY\_VALUE\_IN\_FCT\_DECL. Now, let's talk about function
called from the fortran code PIPS has to print in C. The problem on
how to pass scalars (by value or by pointer) also exists. At the moment PIPS
is less flexible for function call. One of the solution has to be choosen
using the property CROUGH\_SCALAR\_BY\_VALUE\_IN\_FCT\_CALL.
\begin{PipsProp}{PRETTYPRINT_C_FUNCTION_NAME_WITH_UNDERSCORE}
PRETTYPRINT_C_FUNCTION_NAME_WITH_UNDERSCORE FALSE
\end{PipsProp}
\begin{PipsProp}{CROUGH_FORTRAN_USES_INTERFACE}
CROUGH_FORTRAN_USES_INTERFACE FALSE
\end{PipsProp}
\begin{PipsProp}{CROUGH_SCALAR_BY_VALUE_IN_FCT_DECL}
CROUGH_SCALAR_BY_VALUE_IN_FCT_DECL FALSE
\end{PipsProp}
\begin{PipsProp}{CROUGH_SCALAR_BY_VALUE_IN_FCT_CALL}
CROUGH_SCALAR_BY_VALUE_IN_FCT_CALL FALSE
\end{PipsProp}
If the property DO\_RETURN\_TYPE\_AS\_TYPEDEF is set to TRUE the crough
phase additionaly does the same thing that the phase
set\_return\_type\_as\_typedef does (cf section ~\ref{chapter-global-options}).
In such a case the same property SET\_RETURN\_TYPE\_AS\_TYPEDEF\_NEW\_TYPE is
taken into account. This is only posible for the SUBROUTINES and the FUNCTIONS
but not for the PROGRAMS
\begin{PipsProp}{DO_RETURN_TYPE_AS_TYPEDEF}
DO_RETURN_TYPE_AS_TYPEDEF FALSE
\end{PipsProp}
Using the property INCLUDE\_FILES\_LIST, it is possible to insert some
\#include statement before to output the code. The INCLUDE\_FILES\_LIST
is a string interpreted as coma (and/or blank) separated list of files.
\begin{PipsProp}{CROUGH_INCLUDE_FILE_LIST}
CROUGH_INCLUDE_FILE_LIST ""
\end{PipsProp}
\section{Prettyprinters Smalltalk}
\label{subsection-prettyprinters-smalltalk}
\index{Prettyprinters Smalltalk}
\index{PHRASE}
This pass is used by the \textsc{phrase} project, which is an attempt to
automatically (or semi-automatically) transform high-level language
application into control code with reconfigurable logic accelerators (such
as \textsc{fpga}s or data-paths with \textsc{alu}).
\begin{PipsPass}{print_code_smalltalk}
This pass is used in context of PHRASE project for synthetisation of
reconfigurable logic for a portion of initial code. This function can
be viewed as a SmallTalk pretty-printer of a subset of Fortran or C.
It is used as input for the Madeo synthesis tools from UBO/AS that is
written in SmallTalk and take circuit behaviour in SmallTalk.
\end{PipsPass}
It is an interesting language fusion...
\begin{PipsMake}
alias print_code_smalltalk 'Smalltalk Pretty-Printer'
print_code_smalltalk > MODULE.smalltalk_code_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\section{Prettyprinter for the Polyhderal Compiler Collection (PoCC)}
\label{subsection-prettyprinter-pocc}
\index{Prettyprinter PoCC}
\index{OpenGPU}
\index{PoCC}
\begin{PipsPass}{pocc_prettyprinter}
This pass is used for printing pragmas \verb/scop/ and
\verb/endscop/ which delimit the static control parts (SCoP) of the
code. Instrumented code can be an input for any PoCC compiler.
\end{PipsPass}
\begin{PipsMake}
alias pocc_prettyprinter 'pocc_prettyprinter'
pocc_prettyprinter > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.static_control
\end{PipsMake}
For the outlining of the control static parts, function prefix names to
be used during the generation:
\begin{PipsProp}{SCOP_PREFIX}
SCOP_PREFIX "SCoP"
\end{PipsProp}
\begin{PipsProp}{STATIC_CONTROLIZE_ACROSS_USER_CALLS}
STATIC_CONTROLIZE_ACROSS_USER_CALLS TRUE
\end{PipsProp}
Because user function calls are not allowed in PoCC static control
parts, whereas they are generally accepted in PIPS (see Arnauld
Leservot's PhD), we introduce a property to control the impact of user
calls. This property could be called \verb/POCC_COMPATIBILITY/ if
there were a set of limiting rules to apply for PoCC, but user calls
are the only current issue\footnote{The PLUTO compiler does not
support intrinsics calls either, althoug it is part of the PoCC
collection.} So the property is called
\PipsPropRef{STATIC_CONTROLIZE_ACROSS_USER_CALLS} and its default
value is TRUE.
%\begin{PipsProp}{POCC_COMPATIBILITY}
%POCC_COMPATIBILITY FALSE
%\end{PipsProp}
\subsection{Rstream interface}
\begin{PipsPass}{rstream_interface}
Detect non-SCoP of the code. Based on R-Stream constraints.
Must be preceded by the pocc\_prettyprinter phase.
\end{PipsPass}
\begin{PipsMake}
alias rstream_interface 'rstream_interface'
rstream_interface > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.static_control
\end{PipsMake}
\section{Regions to loops}
\begin{PipsPass}{regions_to_loops}
This phase is designed to replace the body of a function by simple assignments.
The new body is representative of the regions described by the old body.
When \PipsPropRef{PSYSTEME_TO_LOOPNEST_FOR_RSTREAM} is set to True, the function
in charge of computing loop nests from systems chooses the constant values rather
than the symbolic values for loop ranges.
\end{PipsPass}
\begin{PipsMake}
alias regions_to_loops 'regions_to_loops'
regions_to_loops > MODULE.code
< PROGRAM.entities
< MODULE.code
< MODULE.summary_regions
\end{PipsMake}
\begin{PipsProp}{PSYSTEME_TO_LOOPNEST_FOR_RSTREAM}
PSYSTEME_TO_LOOPNEST_FOR_RSTREAM FALSE
\end{PipsProp}
\section{Prettyprinter for CLAIRE}
\label{subsection-prettyprinter-claire}
\index{Prettyprinter Claire}
\index{DREAM-UP}
This pass is used for the DREAM-UP project. The internal representation of
a C or Fortran program is dumped as CLAIRE objects, either
\texttt{DATA\_ARRAY} or \texttt{TASK}. CLAIRE is an object-oriented
language used to develop constraint solvers.
The only type constructor is array. Basic types must be storable on a
fixed number of bytes.
The code structure must be a sequence of loop nests. Loops must be
perfectly nested and parallel. Each loop body must be a single array
assignment. The right-hand side expression must be a function call.
If the input code does not meet these conditions, a user error is generated.
\begin{PipsPass}{print_xml_code}
This pass is used for the specification input and transformation in the XML format which can further be used by number of application as input. This function can be viewed as a XML pretty-printer of a subset of C and Fortran programs.
\end{PipsPass}
\begin{PipsMake}
alias print_xml_code 'XML Pretty-Printer'
print_xml_code > MODULE.xml_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.complexities
< MODULE.preconditions
< MODULE.regions
\end{PipsMake}
\begin{PipsPass}{print_xml_code_with_explicit_motif}
This phase was developped for the DREAM-UP/Ter@ops project to generate models
of functions used for automatic mapping by APOTRES \cite{}. It
generates XML code like the \textsc{print\_xml\_code} pass, but the
input contains explicitly loops to scan motifs. It is useless for
other purposes. \marginpar{RK: gnih? FI: to be deleted? CA: more to say?}
\end{PipsPass}
\begin{PipsMake}
alias print_xml_code_with_explicit_motif 'XML Pretty-Printer with explicit motif'
print_xml_code_with_explicit_motif > MODULE.xml_printed_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{print_claire_code}
This pass is used in the DREAM-UP project for module specification
input and transformation (?)~\cite{}. This function can be viewed as a
CLAIRE pretty-printer of a subset of Fortran.
\end{PipsPass}
\begin{PipsMake}
alias print_claire_code 'Claire Pretty-Printer'
print_claire_code > MODULE.claire_printed_file
< PROGRAM.entities
< MODULE.code
< MODULE.preconditions
< MODULE.regions
\end{PipsMake}
\begin{PipsPass}{print_claire_code_with_explicit_motif}
This pass generates CLAIRE code like the \textsc{print\_claire\_code}
pass, but the input contains explicitly loops to scan motifs.
\end{PipsPass}
\begin{PipsMake}
alias print_claire_code_with_explicit_motif 'Claire Pretty-Printer with explicit motif'
print_claire_code_with_explicit_motif > MODULE.claire_printed_file
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
\begin{PipsPass}{print_xml_application}
This pass was developped for the Ter@ops project to generate models
of functions and application used for automatic mapping by SPEAR.
It generates XML code. There are two versions: one using points-to analysis information and the second one without points-to analyses.
\end{PipsPass}
\begin{PipsProp}{XML_APPLICATION_MAIN}
XML_APPLICATION_MAIN "main"
\end{PipsProp}
%% the CALLEES.spear_code_file dependence is not directly used,
%% but is necessary so that the final spear application generation
%% find all required data.
\begin{PipsMake}
alias print_xml_application 'Spear XML Pretty-Printer'
print_xml_application > MODULE.spear_code_file
> MODULE.task_variable_changed_by
< PROGRAM.entities
< MODULE.code
< MODULE.proper_effects
< MODULE.preconditions
< MODULE.regions
< MODULE.dg
< CALLEES.code
< CALLEES.summary_effects
< CALLEES.spear_code_file
\end{PipsMake}
\begin{PipsMake}
alias print_xml_application_with_points_to 'Spear XML Pretty-Printer (with pt)'
print_xml_application_with_points_to > MODULE.spear_code_file
> MODULE.task_variable_changed_by
< PROGRAM.entities
< MODULE.code
< MODULE.points_to
< MODULE.proper_effects
< MODULE.preconditions
< MODULE.regions
< MODULE.dg
< CALLEES.code
< CALLEES.summary_effects
< CALLEES.spear_code_file
\end{PipsMake}
\begin{PipsMake}
print_xml_application_main > MODULE.spear_app_file
< PROGRAM.entities
< MODULE.code
< MODULE.points_to
< MODULE.proper_effects
< MODULE.preconditions
< MODULE.regions
< MODULE.dg
< MODULE.spear_code_file
< MODULE.task_variable_changed_by
< CALLEES.summary_effects
\end{PipsMake}
\chapter{Feautrier Methods (a.k.a. Polyhedral Method)}
\label{section-feautrier-methods}
This part of \Pips{} was implemented at Centre d'\'Etudes Atomiques,
Limeil-Br\'evannes, by Beno\^it de \textsc{Dinechin}, Arnauld
\textsc{Leservot} and Alexis \textsc{Platonoff}.
Unfortunately, this part is no longer used in PIPS right now because of
some typing issues in the code. To be fixed when somebody needs it.
%%
%% PAF-related code
%%
\section{Static Control Detection}
\label{subsection-static-control-detection}
\begin{PipsPass}{static_controlize}
\PipsPassRef{static_controlize} transforms all the loops in order to have steps
equal to one. Only loops with constant step different than one are
normalized. Normalized loop counters are instantiated as a new kind of
entity: \verb+NLC+. This entity is forwarded in the inner
statements. It also gets the structural parameters and makes new ones
when it is possible (``NSP''). It detects enclosing loops, enclosing
tests and the \verb+static_control+ property for each statement. Those
three informations are mapped on statements. Function
\PipsPassRef{static_controlize} also modifies code (\verb+> MODULE.code+). It
is not specified here for implementation bug purpose.
The definition of a static control program is given in~\cite{Fea91}.
\end{PipsPass}
\begin{PipsMake}
alias static_controlize 'Static Controlize'
static_controlize > MODULE.static_control
< PROGRAM.entities
< MODULE.code
\end{PipsMake}
See the alias \PipsPassRef{print_code_static_control} and function
\PipsPassRef{print_code_static_control} in
Section~\ref{sec:parsed_printed_files} and so on.
%\section{Array Data Flow Graph}
%\label{subsection-array-data-flow-graph}
%\index{DFG}
%\index{Array Data Flow Graph}
%
%Function \PipsPassRef{array_dfg} computes an Array Data Flow Graph, according to
%Feautrier's methods (see~\cite{Fea91}). This method can only be applied
%on static-control code, otherwise an error occurs.
%%Function \PipsPassRef{print_array_dfg} prints the Data Flow Graph.
%
%In the ouput produced by the array DFG analysis,
%each statement is renamed ``\texttt{ins\_}'' followed by the statement number it had in the original
%program and by a digit representing its position among the different
%statements coming from the same statement of the original program.
%
%The following describes the output of an Array DFG analysis:
%
%\begin{description}
%\item[\texttt{W}:] Statement examined. It can be ``ENTRY''
%\item[\texttt{Execution domain}:] The conditions on the surrouding loop
% counters for which W is executed at least once
%\item[\texttt{-{}-{}-{}-Def-Use- > R}:] Statement reading a value produced by
% an execution of W
%\item[\texttt{Reference}:] Expression of the variable read at statement
% R.
%\item[\texttt{Transformation}:] Transformation that must be applied on
% the loop counters of R to find those of W for which there is dependence
%\item[\texttt{Governing predicate}:] Conditions on the loop counters of
% the loops surrounding R for which there is a dependence
%\item[\texttt{Execution domain}:] Conditions on the loop counters for
% which there is an execution of R.
%\end{description}
%Known bug: what happens if the input is not a static control program?
% \begin{PipsMake}
% array_dfg > MODULE.adfg
% < PROGRAM.entities
% < MODULE.code
% < MODULE.static_control
% < MODULE.dg
% < MODULE.preconditions
% \end{PipsMake}
% \begin{PipsMake}
% alias adfg_file 'Array Data Flow Graph'
% print_array_dfg > MODULE.adfg_file
% < PROGRAM.entities
% < MODULE.code
% < MODULE.adfg
% \end{PipsMake}
\section{Scheduling}
\label{subsection-scheduling}
\index{Scheduling}
Function \texttt{scheduling} computes a schedule, called {\em Base De
Temps} in French, for each assignment instruction of the program. This
computation is based on the Array Data Flow Graph (see~\cite{Fea92a,Fea92b}).
The output of the scheduling is of the following form:
(the statements are named in the same manner as in the array DFG)
\begin{description}
\item[\texttt{W}:] Statement examined
\item[\texttt{pred}:] Conditions for which the following schedule is
valid
\item[\texttt{dims}:] Time at which the execution of W is schedule, in function of
the loop counters of the surrounding loops.
\end{description}
% \begin{PipsMake}
% scheduling > MODULE.bdt
% < PROGRAM.entities
% < MODULE.code
% < MODULE.static_control
% < MODULE.adfg
% \end{PipsMake}
% \begin{PipsMake}
% alias bdt_file 'Time stamps'
% print_bdt > MODULE.bdt_file
% < PROGRAM.entities
% < MODULE.code
% < MODULE.bdt
% \end{PipsMake}
%\section{Mapping (a.k.a. Placement)}
%
%Function \PipsPassRef{prgm_mapping} computes one mapping for
%each assignment instruction of the program. Each iteration of the
%assignment is mapped onto a processor. The set of processors is a grid,
%as in HPF.
%
%These mappings are computed from the array data flow graph and the timing
%function. The implementation contains the extensions developed by Alexis
%Platonoff (see~\cite{Fea93,Pla95b}), who also implemented this analysis.
%
%The output of the placement is:
%(the statements are named in the same manner as in the array DFG)
%
%\begin{description}
%\item[S:] Statement examined
%\item[(..,..,..)] Coordinates of the execution of the statement on a
% processor grid, in function of the loop counters of the surrounding
% loops.
%\end{description}
% \begin{PipsMake}
% prgm_mapping > MODULE.plc
% < PROGRAM.entities
% < MODULE.code
% < MODULE.static_control
% < MODULE.adfg
% < MODULE.bdt
% \end{PipsMake}
% \begin{PipsMake}
% alias plc_file 'Placement'
% print_plc > MODULE.plc_file
% < PROGRAM.entities
% < MODULE.code
% < MODULE.plc
% \end{PipsMake}
\section{Code Generation for Affine Schedule}
Function \texttt{reindexing} transforms the code using the schedule
(\texttt{bdt}) and the mapping (\texttt{plc}) (see~\cite{Col93,Pla95a}). The
result is a new resource named \verb/reindexed_code/.
% \begin{PipsMake}
% reindexing > MODULE.reindexed_code
% < PROGRAM.entities
% < MODULE.code
% < MODULE.static_control
% < MODULE.adfg
% < MODULE.bdt
% < MODULE.plc
% \end{PipsMake}
\section{Prettyprinters for CM Fortran}
How to get a pretty-printed version of \verb+reindexed_code+ ? Two
prettyprinters are available. The first one produces CM Fortran and the
result is stored in a file suffixed by \verb+.fcm+. The second one
produces CRAFT Fortran and the result is stored in a file suffixed by
\verb+.craft+.
% \begin{PipsMake}
% alias print_parallelizedCMF_code 'CM Fortran'
% alias print_parallelizedCRAFT_code 'CRAFT Fortran'
% \end{PipsMake}
\begin{PipsPass}{print_parallelizedCMF_code}
Use the polyhedric method to parallelize the code and display the
reindexed code in a CMF (parallel Fortran extension from TMC, Thinking
Machine Corporation) style.
\end{PipsPass}
% \begin{PipsMake}
% print_parallelizedCMF_code > MODULE.parallelprinted_file
% < PROGRAM.entities
% < MODULE.adfg
% < MODULE.bdt
% < MODULE.plc
% < MODULE.reindexed_code
% \end{PipsMake}
\begin{PipsPass}{print_parallelizedCRAFT_code}
Use the polyhedric method to parallelize the code and display the
reindexed code in a CRAFT (parallel Fortran used on the Cray T3 serie)
style.
\end{PipsPass}
% \begin{PipsMake}
% print_parallelizedCRAFT_code > MODULE.parallelprinted_file
% < PROGRAM.entities
% < MODULE.adfg
% < MODULE.bdt
% < MODULE.plc
% < MODULE.reindexed_code
% \end{PipsMake}
\chapter{User Interface Menu Layouts}
\label{sec:menu_layout}
\label{section-user-interface-menu-layouts}
For presentation issues, it is useful to select only the features that
are needed by a user and to display them in a comprehensive order. For
that purpose, a layout description mechanism is used here to pick
among the \Pips{} phases described above.
For each menu, the left part before the arrow, \verb|->|, is the menu
item title and the right part is the \Pips{} procedure to be called when
the item is selected. For the view menu (section~\ref{sec:view_menu},
there is two display methods to view resources separated by a comma,
the first one is the method for \WPIPS, the second one is the one
used in \EPIPS, followed by the icon to use.
Use a blank line to insert a menu separator.
\section{View Menu}
\label{sec:view_menu}
The view menu is displayed according to the following layout and
methods (\WPIPS{} method, \EPIPS{} method, icon name for the frame):
\begin{PipsMenu}{View}
printed_file -> wpips_display_plain_file,epips-display-fortran-file,sequential
parsed_printed_file -> wpips_display_plain_file,epips-display-fortran-file,user
alias_file -> wpips_display_plain_file,epips-display-plain-file,-
graph_printed_file -> wpips_display_graph_file_display,epips-display-graph-file,-
dg_file -> wpips_display_plain_file,epips-display-plain-file,DG
adfg_file -> wpips_display_plain_file,epips-display-plain-file,-
bdt_file -> wpips_display_plain_file,epips-display-plain-file,-
plc_file -> wpips_display_plain_file,epips-display-plain-file,-
callgraph_file -> wpips_display_plain_file,epips-display-xtree-file,callgraph
dvcg_file -> wpips_display_graph_file_display,epips-display-graph-file,callgraph
icfg_file -> wpips_display_plain_file,epips-display-plain-file,ICFG
wp65_compute_file -> wpips_display_WP65_file,epips-display-distributed-file,WP65_PE
parallelprinted_file -> wpips_display_plain_file,epips-display-fortran-file,parallel
flinted_file -> wpips_display_plain_file,epips-display-plain-file,-
\end{PipsMenu}
\section{Transformation Menu}
\label{sec:transformation_menu}
The transformation menu is displayed as here:
\begin{PipsMenu}{Transformations}
distributer
full_unroll
unroll
loop_interchange
loop_normalize
strip_mine
loop_tiling
tiling_sequence
privatize_module
array_privatizer
declarations_privatizer
restructure_control
unspaghettify
simplify_control
simplify_control_directly
partial_eval
dead_code_elimination
stf
freeze_variables
partial_redundancy_elimination
array_bound_check_bottom_up
array_bound_check_top_down
array_bound_check_interprocedural
array_resizing_bottom_up
array_resizing_top_down
alias_check
atomizer
new_atomizer
clone
clone_substitute
clone_on_argument
clean_declarations
unsplit
static_controlize
\end{PipsMenu}
%% optimize_expressions
At the end of this menu is added a special entry in \WPIPS, the ``Edit'' line
that allows the user to edit the original file. It is seen as a very
special transformation, since the user can apply whatever
transformation (s)he wants...
\chapter{Conclusion}
New functionalities can easily be added to \Pips{}. The new pass names
must be declared somewhere in this file as well as the resources required
and produced. Then, {\tt make} must be run in the {\tt Documentation}
directory and the \Pipsmake{} library must be recompiled and \Pips{}
interfaces (\textsc{pips}, \textsc{tpips}, \textsc{wpips}) linked with the
new C modules.
It is much more difficult to add a new type of resources, because \Pips{}
database manager, \texttt{pipsdbm}, is not as automatized as
\Pipsmake{}. This is explained in~\cite{Iri94}.
\chapter{Known Problems}
\begin{enumerate}
\item {\em pipsmake} behavior may be erratic if files are accessed across
a \textsc{nfs} network of non-synchronized workstations (see for
instance UNIX \texttt{rdate} command or better \textsc{ntp} daemon).
\item \texttt{STOP} statements in subroutines (i.e. control effects and
control dependencies) are not taken into account when parallelizing the
caller.
\end{enumerate}
%% BIBLIOGRAPHY
% \bibliographystyle{latex8}
\bibliographystyle{acm}
\bibliography{../pips}
\newpage
% Cross-references for points and keywords
\printindex
\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% ispell-local-dictionary: "american"
%%% End:
% vim: spell spelllang=en