README

   1 #
   2 # Pluto README
   3 #
   4 # Uday Bondhugula
   5 # uday@csa.iisc.ernet.in
   6 #
   7
   8 LICENSE
   9
  10 Pluto is available under GPL v3, and libpluto is available under LGPL v2.1.
  11
  12 INSTALLING PLUTO
  13
  14 PREREQUISITES
  15
  16 A Linux distribution. Pluto has been tested on x86 and x86-64 machines
  17 running Fedora, Ubuntu, and RedHat Enterprise Server.  Solaris should also
  18 be fine if you have GNU utilities. In order to use the development version
  19 from Pluto's git repository, automatic build system tools including
  20 autoconf, automake, and libtool are needed. GMP (GNU multi precision
  21 arithmetic library) is needed by ISL (one of the included libraries). If
  22 it's not already on your system, it can be installed easily with, for
  23 eg., eg., 'sudo yum -y install gmp gmp-devel' on a Fedora. It is also
  24 recommended astyle and indent be installed if a user wishes to browse
  25 through generated code.
  26
  27 Pluto includes all polyhedral libraries that it depends on.
  28
  29
  30 BUILDING PLUTO
  31
  32 Stable release
  33
  34 $ tar zxvf pluto-0.11.4.tar.gz
  35 $ cd pluto-0.11.4/
  36 $ ./configure
  37 $ make
  38 $ make test
  39
  40 configure can be provided --with-isl-prefix=<isl install location> to
  41 build with another isl, otherwise the bundled isl is used.
  42
  43 Development version from Git
  44
  45 $ git clone git://repo.or.cz/pluto.git
  46 $ cd pluto/
  47 $ git submodule init
  48 $ git submodule update
  49 $ ./autogen.sh
  50 $ ./configure [--enable-debug] [--with-isl-prefix=<isl install location>]
  51 $ make
  52 $ make test
  53
  54 * --with-isl-prefix=<location> to compile and link with an already installed
  55 isl. By default, the version of isl bundled with Pluto will be used.
  56
  57 'polycc' is the wrapper script around src/pluto (core transformer) and all
  58 other components. 'polycc' runs all of these in sequence on an input C
  59 program (with the section to  parallelize/optimize marked) and is what a
  60 user should use on input. Output generated is OpenMP parallel C code that
  61 can be readily compiled and run on shared-memory parallel machines like
  62 general-purpose multicores. libpluto.{so,a} is also built and can be found
  63 in src/.libs/. 'make install' will install it.
  64
  65
  66 TRYING A NEW CODE
  67
  68 - Use '#pragma scop' and '#pragma endscop' around the section of code
  69   you want to parallelize/optimize.
  70
  71 - Then, just run
  72
  73     ./polycc <C source file> --parallel --tile
  74
  75   The transformation is also printed out, and test.par.c will have the
  76   parallelized code. If you want to see intermediate files, like the
  77   .cloog file generated (.opt.cloog, .tiled.cloog, or .par.cloog
  78   depending on command-line options provided), use --debug on command
  79   line.
  80
  81 - Tile sizes can be specified in a file 'tile.sizes', otherwise default
  82   sizes will be set. See doc/DOC.txt on how to specify the sizes.
  83
  84 To run a good number of experiments on a code, it is best to use the setup
  85 created for example codes in the examples/ directory.  If you do not have
  86 ICC (Intel C compiler), uncomment line 7 and comment line
  87 8 of examples/common.mk to use GCC.
  88
  89 - Just copy one of the sample directories in examples/, edit Makefile (SRC =
  90   )
  91
  92 - do a make (this will build all executables; 'orig' is the original code
  93   compiled with the native compiler, 'tiled' is the tiled code, 'par' is the
  94   OpenMP parallelized+locality optimized code, 'lbpar' with diamond tiling
  95   when possible. One could do 'make <target>' where target can be orig,
  96   orig_par, opt, tiled, par, lbpar, etc. (see examples/common.mk for full
  97   list)
  98
  99 - 'make test' to test for correctness, 'make perf', 'make lbperf' to compare
 100 performance
 101
 102
 103 COMMAND-LINE OPTIONS
 104
 105 Run
 106
 107 ./polycc -h
 108
 109 or see documentation (doc/DOC.txt) for details
 110
 111
 112 TRYING ANY INCLUDED EXAMPLE CODE
 113
 114 Lets say we are trying the 2-d gauss seidel kernel. In examples/seidel, do
 115 'make par'; this will generate seidel.par.c from seidel.c and also compile
 116 it to generate 'par'.  Likewise, 'make tiled' for 'tiled' and 'make orig'
 117 for 'orig'.
 118
 119 $ cd examples/seidel
 120
 121 seidel.c: This is the original code (the kernel in this code is extracted).
 122 'orig' is the corresponding executable when compiled with the native
 123 compiler (gcc or icc for eg.) with optimization flags, 'orig_par' with the
 124 native compiler's auto-parallelization enabled.
 125
 126 seidel.opt.c: This is the transformed code without tiling (this is of not
 127 much use, except for seeing benefits of fusion in some cases). 'opt' is the
 128 corresponding executable.
 129
 130 seidel.tiled.c: This is Pluto generated code optimized for locality with
 131 tiling and other transformations, but not not parallelized - this should be
 132 used for sequential execution. 'tiled' is the corresponding executable.
 133
 134 seidel.par.c: This is Pluto parallelized code optimized for locality and
 135 parallelism  with tiling and other transformations. This code has OpenMP
 136 pragmas. 'par' is the corresponding executable.
 137
 138 - To change any of the flags used for an example, edit the top section of
 139   examples/common.mk or the Makefile in the example directory
 140
 141 - To manually specify tile sizes, create tile.sizes; see examples/matmul/
 142    for example or doc/DOC.txt for more information on setting tile sizes.
 143
 144 The executables already have timers; you just have to run them and that will
 145 print execution time for the core part of the computation as well.
 146
 147 To run the Pluto parallelized version:
 148
 149 $ OMP_NUM_THREADS=4; ./par
 150
 151 To run native compiler optimized/auto-parallelized version:
 152
 153 $ OMP_NUM_THREADS=4; ./orig_par
 154
 155 To run the original unparallelized code:
 156
 157 $ ./orig
 158
 159 To run the locality optimized version generated by Pluto:
 160
 161 $ ./tiled
 162
 163 - 'make clean' in the particular example's directory removes all executables
 164     as well as generated codes
 165
 166 To launch a complete verification that compares output of tiled, par
 167 with orig for all examples, in examples/, run 'make test'.
 168
 169 [examples/ ]$ make test
 170
 171
 172
 173 MORE INFO
 174
 175 * See doc/DOC.txt for an overview of the system and details on all
 176 command-line options.
 177
 178 * For specifying custom tile sizes through 'tile.sizes' file, see
 179 doc/DOC.txt
 180
 181 * For specifying custom fusion structure through '.fst' file, see
 182 doc/DOC.txt
 183
 184
 185 CONTACT
 186
 187 Please send all bugs reports and comments to Uday Bondhugula
 188 <uday@csa.iisc.ernet.in> or post of pluto-development@googlegroups.com.