README

   1 Requirements:
   2
   3 - automake, autoconf, libtool
   4         (not needed when compiling a release)
   5 - pkg-config (http://www.freedesktop.org/wiki/Software/pkg-config)
   6         (not needed when compiling a release using the included isl and pet)
   7 - gmp (http://gmplib.org/)
   8 - libyaml (http://pyyaml.org/wiki/LibYAML)
   9         (only needed if you want to compile the pet executable)
  10 - LLVM/clang libraries, 2.9 or higher (http://clang.llvm.org/get_started.html)
  11         Unless you have some other reasons for wanting to use the svn version,
  12         it is best to install the latest release (3.8).
  13         For more details, see pet/README.
  14
  15 If you are installing on Ubuntu, then you can install the following packages:
  16
  17 automake autoconf libtool pkg-config libgmp3-dev libyaml-dev libclang-dev llvm
  18
  19 Note that you need at least version 3.2 of libclang-dev (ubuntu raring).
  20 Older versions of this package did not include the required libraries.
  21 If you are using an older version of ubuntu, then you need to compile and
  22 install LLVM/clang from source.
  23
  24
  25 Preparing:
  26
  27 Grab the latest release and extract it or get the source from
  28 the git repository as follows.  This process requires autoconf,
  29 automake, libtool and pkg-config.
  30
  31         git clone git://repo.or.cz/ppcg.git
  32         cd ppcg
  33         ./get_submodules.sh
  34         ./autogen.sh
  35
  36
  37 Compilation:
  38
  39         ./configure
  40         make
  41         make check
  42
  43 If you have installed any of the required libraries in a non-standard
  44 location, then you may need to use the --with-gmp-prefix,
  45 --with-libyaml-prefix and/or --with-clang-prefix options
  46 when calling "./configure".
  47
  48
  49 Using PPCG to generate CUDA or OpenCL code
  50
  51 To convert a fragment of a C program to CUDA, insert a line containing
  52
  53         #pragma scop
  54
  55 before the fragment and add a line containing
  56
  57         #pragma endscop
  58
  59 after the fragment.  To generate CUDA code run
  60
  61         ppcg --target=cuda file.c
  62
  63 where file.c is the file containing the fragment.  The generated
  64 code is stored in file_host.cu and file_kernel.cu.
  65
  66 To generate OpenCL code run
  67
  68         ppcg --target=opencl file.c
  69
  70 where file.c is the file containing the fragment.  The generated code
  71 is stored in file_host.c and file_kernel.cl.
  72
  73
  74 Specifying tile, grid and block sizes
  75
  76 The iterations space tile size, grid size and block size can
  77 be specified using the --sizes option.  The argument is a union map
  78 in isl notation mapping kernels identified by their sequence number
  79 in a "kernel" space to singleton sets in the "tile", "grid" and "block"
  80 spaces.  The sizes are specified outermost to innermost.
  81
  82 The dimension of the "tile" space indicates the (maximal) number of loop
  83 dimensions to tile.  The elements of the single integer tuple
  84 specify the tile sizes in each dimension.
  85
  86 The dimension of the "grid" space indicates the (maximal) number of block
  87 dimensions in the grid.  The elements of the single integer tuple
  88 specify the number of blocks in each dimension.
  89
  90 The dimension of the "block" space indicates the (maximal) number of thread
  91 dimensions in the grid.  The elements of the single integer tuple
  92 specify the number of threads in each dimension.
  93
  94 For example,
  95
  96     { kernel[0] -> tile[64,64]; kernel[i] -> block[16] : i != 4 }
  97
  98 specifies that in kernel 0, two loops should be tiled with a tile
  99 size of 64 in both dimensions and that all kernels except kernel 4
 100 should be run using a block of 16 threads.
 101
 102 Since PPCG performs some scheduling, it can be difficult to predict
 103 what exactly will end up in a kernel.  If you want to specify
 104 tile, grid or block sizes, you may want to run PPCG first with the defaults,
 105 examine the kernels and then run PPCG again with the desired sizes.
 106 Instead of examining the kernels, you can also specify the option
 107 --dump-sizes on the first run to obtain the effectively used default sizes.
 108
 109
 110 Compiling the generated CUDA code with nvcc
 111
 112 To get optimal performance from nvcc, it is important to choose --arch
 113 according to your target GPU.  Specifically, use the flag "--arch sm_20"
 114 for fermi, "--arch sm_30" for GK10x Kepler and "--arch sm_35" for
 115 GK110 Kepler.  We discourage the use of older cards as we have seen
 116 correctness issues with compilation for older architectures.
 117 Note that in the absence of any --arch flag, nvcc defaults to
 118 "--arch sm_13". This will not only be slower, but can also cause
 119 correctness issues.
 120 If you want to obtain results that are identical to those obtained
 121 by the original code, then you may need to disable some optimizations
 122 by passing the "--fmad=false" option.
 123
 124
 125 Compiling the generated OpenCL code with gcc
 126
 127 To compile the host code you need to link against the file
 128 ocl_utilities.c which contains utility functions used by the generated
 129 OpenCL host code.  To compile the host code with gcc, run
 130
 131   gcc -std=c99 file_host.c ocl_utilities.c -lOpenCL
 132
 133 Note that we have experienced the generated OpenCL code freezing
 134 on some inputs (e.g., the PolyBench symm benchmark) when using
 135 at least some version of the Nvidia OpenCL library, while the
 136 corresponding CUDA code runs fine.
 137 We have experienced no such freezes when using AMD, ARM or Intel
 138 OpenCL libraries.
 139
 140 By default, the compiled executable will need the _kernel.cl file at
 141 run time.  Alternatively, the option --opencl-embed-kernel-code may be
 142 given to place the kernel code in a string literal.  The kernel code is
 143 then compiled into the host binary, such that the _kernel.cl file is no
 144 longer needed at run time.  Any kernel include files, in particular
 145 those supplied using --opencl-include-file, will still be required at
 146 run time.
 147
 148
 149 Function calls
 150
 151 Function calls inside the analyzed fragment are reproduced
 152 in the CUDA or OpenCL code, but for now it is left to the user
 153 to make sure that the functions that are being called are
 154 available from the generated kernels.
 155
 156 In the case of OpenCL code, the --opencl-include-file option
 157 may be used to specify one or more files to be #include'd
 158 from the generated code.  These files may then contain
 159 the definitions of the functions being called from the
 160 program fragment.  If the pathnames of the included files
 161 are relative to the current directory, then you may need
 162 to additionally specify the --opencl-compiler-options=-I.
 163 to make sure that the files can be found by the OpenCL compiler.
 164 The included files may contain definitions of types used by the
 165 generated kernels.  By default, PPCG generates definitions for
 166 types as needed, but these definitions may collide with those in
 167 the included files, as PPCG does not consider the contents of the
 168 included files.  The --no-opencl-print-kernel-types will prevent
 169 PPCG from generating type definitions.
 170
 171
 172 GNU extensions
 173
 174 By default, PPCG may print out macro definitions that involve
 175 GNU extensions such as __typeof__ and statement expressions.
 176 Some compilers may not support these extensions.
 177 In particular, OpenCL 1.2 beignet 1.1.1 (git-6de6918)
 178 has been reported not to support __typeof__.
 179 The use of these extensions can be turned off with the
 180 --no-allow-gnu-extensions option.
 181
 182
 183 Processing PolyBench
 184
 185 When processing a PolyBench/C 3.2 benchmark, you should always specify
 186 -DPOLYBENCH_USE_C99_PROTO on the ppcg command line.  Otherwise, the source
 187 files are inconsistent, having fixed size arrays but parametrically
 188 bounded loops iterating over them.
 189 However, you should not specify this define when compiling
 190 the PPCG generated code using nvcc since CUDA does not support VLAs.
 191
 192
 193 CUDA and function overloading
 194
 195 While CUDA supports function overloading based on the arguments types,
 196 no such function overloading exists in the input language C.  Since PPCG
 197 simply prints out the same function name as in the original code, this
 198 may result in a different function being called based on the types
 199 of the arguments.  For example, if the original code contains a call
 200 to the function sqrt() with a float argument, then the argument will
 201 be promoted to a double and the sqrt() function will be called.
 202 In the transformed (CUDA) code, however, overloading will cause the
 203 function sqrtf() to be called.  Until this issue has been resolved in PPCG,
 204 we recommend that users either explicitly call the function sqrtf() or
 205 explicitly cast the argument to double in the input code.
 206
 207
 208 Contact
 209
 210 For bug reports, feature requests and questions,
 211 contact http://groups.google.com/group/isl-development
 212
 213 Whenever you report a bug, please mention the exact version of PPCG
 214 that you are using (output of "./ppcg --version").  If you are unable
 215 to compile PPCG, then report the git version (output of "git describe")
 216 or the version number included in the name of the tarball.
 217
 218
 219 Citing PPCG
 220
 221 If you use PPCG for your research, you are invited to cite
 222 the following paper.
 223
 224 @article{Verdoolaege2013PPCG,
 225     author = {Verdoolaege, Sven and Juega, Juan Carlos and Cohen, Albert and
 226                 G\'{o}mez, Jos{\'e} Ignacio and Tenllado, Christian and
 227                 Catthoor, Francky},
 228     title = {Polyhedral parallel code generation for CUDA},
 229     journal = {ACM Trans. Archit. Code Optim.},
 230     issue_date = {January 2013},
 231     volume = {9},
 232     number = {4},
 233     month = jan,
 234     year = {2013},
 235     issn = {1544-3566},
 236     pages = {54:1--54:23},
 237     doi = {10.1145/2400682.2400713},
 238     acmid = {2400713},
 239     publisher = {ACM},
 240     address = {New York, NY, USA},
 241 }