PIPS High-Level Software Interface Pipsmake Configuration
Total Page:16
File Type:pdf, Size:1020Kb
PIPS High-Level Software Interface Pipsmake Configuration R´emiTriolet, Fran¸coisIrigoin and many other contributors MINES ParisTech Math´ematiqueset Syst`emes Centre de Recherche en Informatique 77305 Fontainebleau Cedex France Id: pipsmake-rc.tex 23481 2018-08-22 19:35:27Z ancourt You can get a printable version of this document on http://www.cri.ensmp.fr/pips/pipsmake-rc.htdoc/ pipsmake-rc.pdf and a HTML version on http://www.cri.ensmp.fr/pips/pipsmake-rc.htdoc. Chapter 1 Introduction This paper describes high-level objects and functions that are potentially user- visible in a PIPS 1 [33] interactive environment. It defines the internal 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 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: tpips2, the tty style interface which is currently recommended, pips3 [11], the old batch interface, improved by many shell scripts4, wpips and epips, the X-Window System interfaces. The epips interface is an extension of wpips which uses 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 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 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 make. The rule interpretor is called pipsmake6 and described in [10]. Its key concepts are the phase, which correspond to a PIPS function made user-visible, for instance, a parser, the resources, which correspond to objects used or defined by the phases, for instance, a source file or an AST (parsed code), and the virtual 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 CALLERS or CALLEES can be used in virtual rules. They are expanded at execution to obtain an effective rule with the precise resources needed. 1http://www.cri.ensmp.fr/pips 2http://www.cri.ensmp.fr/pips/line-interface.html 3http://www.cri.ensmp.fr/pips/batch-interface.html 4Manual pages are available for Init, Select, Perform, Display, and Delete, and pips5. 6http://www.cri.ensmp.fr/pips/pipsmake.html 1 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 properties.rc file located in the current directory. Properties can also be redefined from the user interfaces, for example with the command setproperty when the tpips interface is used. As far as their static structures are concerned, most object types are de- scribed in more details in PIPS Internal Representation of Fortran and C code7. 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 interpro- cedurality? Resources produced by several rules and their associated rule must be given alias names when they should be explicitly computed or activated by an inter- active interface. This is otherwise not relevant. The alias names are used to FI: I do not generate automatically header files and/or test files used by PIPS interfaces. understand. No more than one resource should be produced per line of rule because different files are automatically extracted from this one8. Another caveat is that all resources whose names are suffixed with _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 PipsMake areas, a very simple literate programming environment... For instance alias information is used to generate automatically menus for window-based interfaces such as wpips or 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, phases.h. Object suffixes are used to derive a header file, resources.h, with all resource names. Parts of this file are also extracted to generate on-line information for wpips and automatic completion for tpips. The behavior of PIPS can be slightly tuned by using properties and some environment variables. Most properties are linked to a particular phase, for instance to prettyprint, but some are linked to PIPS infrastructure and are presented in Chapter 2. 1.1 Informal Pipsmake Syntax To understand and to be able to write new rules for pipsmake, a few things need to be known. 1.1.1 Example The rule: proper_references > MODULE.proper_references 7http://www.cri.ensmp.fr/pips/newgen/ri.htdoc 8See the local Makefile: pipsmake-rc, and alias file: wpips-rc. 2 < PROGRAM.entities < MODULE.code < CALLEES.summary_effects means that the method proper_references is used to generate the proper_references resource of a given MODULE. But to generate this resource, the method needs access to the resource holding the symbole table, entities, of the PROGRAM cur- rently analyzed, the code resource (the instructions) of the given MODULE and the summary_effects 6.2.4 resource (the side effects on the memory) of the functions and procedures called by the given MODULE, the CALLEES. Properties are also declared in this file. For instance ABORT_ON_USER_ERROR FALSE 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 PIPS. But for non-regression tests, it may be better to turn on this property. 1.1.2 Pipsmake variables The following variables are defined to handle interprocedurality: PROGRAM: the whole application currently analyzed; MODULE: the current MODULE (a procedure or function); ALL: all the MODULEs of the current PROGRAM, functions and compilation units; ALLFUNC: all the MODULEs of the current PROGRAM that are functions; CALLEES: all the MODULEs called in the given MODULE; CALLERS: all the MODULEs that call the given MODULE. These variables are used in the rule definitions and instantiated before pipsmake infers which resources are pre-requisites for a rule. The environment variable 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 export PIPS_IGNORE_FUNCTION_RX='!__bswap_' 1.2 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 properties. Properties have an ASCII name and can have boolean, integer or string values. 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 3 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 properties.rc in their local directory. Of course, they cannot declare new properties, since they would not be recognized by the PIPS system. The local property file is read after the default property file, $PIPS_ROOT/etc/properties.rc. 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 properties.rc. It is derived automatically from this documentation, Documentation/pipsmake-rc.tex. PIPS behavior can also be altered by Shell environment variables. Their generic names is XXXX_DEBUG_LEVEL, where XXXX is a library or a phase or an interface name (of course, there are exceptions). Theoretically these environ- ment 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, NEWGEN_MAX_TABULATED_ELEMENTS, is useful to analyze large programs. Its default value is 12,000 but it is not un- common 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 PIPS infrastructure are presented first. Section 2.3 contains information about properties related to infrastructure, external and user interface libraries. Properties for analyses are grouped in Chapter 6.