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.3).
  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         git submodule init
  34         git submodule update
  35         ./autogen.sh
  36
  37
  38 Compilation:
  39
  40         ./configure
  41         make
  42         make check
  43
  44 If you have installed any of the required libraries in a non-standard
  45 location, then you may need to use the --with-gmp-prefix,
  46 --with-libyaml-prefix and/or --with-clang-prefix options
  47 when calling "./configure".
  48
  49
  50 Using PPCG to generate CUDA or OpenCL code
  51
  52 To convert a fragment of a C program to CUDA, insert a line containing
  53
  54         #pragma scop
  55
  56 before the fragment and add a line containing
  57
  58         #pragma endscop
  59
  60 after the fragment.  To generate CUDA code run
  61
  62         ppcg --target=cuda file.c
  63
  64 where file.c is the file containing the fragment.  The generated
  65 code is stored in file_host.cu and file_kernel.cu.
  66
  67 To generate OpenCL code run
  68
  69         ppcg --target=opencl file.c
  70
  71 where file.c is the file containing the fragment.  The generated code
  72 is stored in file_host.c and file_kernel.cl.
  73
  74
  75 Specifying tile, grid and block sizes
  76
  77 The iterations space tile size, grid size and block size can
  78 be specified using the --sizes option.  The argument is a union map
  79 in isl notation mapping kernels identified by their sequence number
  80 in a "kernel" space to singleton sets in the "tile", "grid" and "block"
  81 spaces.  The sizes are specified outermost to innermost.
  82
  83 The dimension of the "tile" space indicates the (maximal) number of loop
  84 dimensions to tile.  The elements of the single integer tuple
  85 specify the tile sizes in each dimension.
  86
  87 The dimension of the "grid" space indicates the (maximal) number of block
  88 dimensions in the grid.  The elements of the single integer tuple
  89 specify the number of blocks in each dimension.
  90
  91 The dimension of the "block" space indicates the (maximal) number of thread
  92 dimensions in the grid.  The elements of the single integer tuple
  93 specify the number of threads in each dimension.
  94
  95 For example,
  96
  97     { kernel[0] -> tile[64,64]; kernel[i] -> block[16] : i != 4 }
  98
  99 specifies that in kernel 0, two loops should be tiled with a tile
 100 size of 64 in both dimensions and that all kernels except kernel 4
 101 should be run using a block of 16 threads.
 102
 103 Since PPCG performs some scheduling, it can be difficult to predict
 104 what exactly will end up in a kernel.  If you want to specify
 105 tile, grid or block sizes, you may want to run PPCG first with the defaults,
 106 examine the kernels and then run PPCG again with the desired sizes.
 107
 108
 109 Compiling the generated CUDA code with nvcc
 110
 111 To get optimal performance from nvcc, it is important to choose --arch
 112 according to your target GPU.  Specifically, use the flag "--arch sm_20"
 113 for fermi, "--arch sm_30" for GK10x Kepler and "--arch sm_35" for
 114 GK110 Kepler.  We discourage the use of older cards as we have seen
 115 correctness issues with compilation for older architectures.
 116 Note that in the absence of any --arch flag, nvcc defaults to
 117 "--arch sm_13". This will not only be slower, but can also cause
 118 correctness issues.
 119 If you want to obtain results that are identical to those obtained
 120 by the original code, then you may need to disable some optimizations
 121 by passing the "--fmad=false" option.
 122
 123
 124 Compiling the generated OpenCL code with gcc
 125
 126 To compile the host code you need to link against the file
 127 ocl_utilities.c which contains utility functions used by the generated
 128 OpenCL host code.  To compile the host code with gcc, run
 129
 130   gcc -std=c99 file_host.c ocl_utilities.c -lOpenCL
 131
 132 Note that we have experienced the generated OpenCL code freezing
 133 on some inputs (e.g., the PolyBench symm benchmark) when using
 134 at least some version of the Nvidia OpenCL library, while the
 135 corresponding CUDA code runs fine.
 136 We have experienced no such freezes when using AMD, ARM or Intel
 137 OpenCL libraries.
 138
 139
 140 Processing PolyBench
 141
 142 When processing a PolyBench/C 3.2 benchmark, you should always specify
 143 -DPOLYBENCH_USE_C99_PROTO on the ppcg command line.  Otherwise, the source
 144 files are inconsistent, having fixed size arrays but parametrically
 145 bounded loops iterating over them.
 146
 147
 148 CUDA and function overloading
 149
 150 While CUDA supports function overloading based on the arguments types,
 151 no such function overloading exists in the input language C.  Since PPCG
 152 simply prints out the same function name as in the original code, this
 153 may result in a different function being called based on the types
 154 of the arguments.  For example, if the original code contains a call
 155 to the function sqrt() with a float argument, then the argument will
 156 be promoted to a double and the sqrt() function will be called.
 157 In the transformed (CUDA) code, however, overloading will cause the
 158 function sqrtf() to be called.  Until this issue has been resolved in PPCG,
 159 we recommend that users either explicitly call the function sqrtf() or
 160 explicitly cast the argument to double in the input code.
 161
 162
 163 Additional variables in generated code
 164
 165 The generated code may contain additional variables with names
 166 that match /^[bthsgc][0-d]+$/.  These variables may shadow or
 167 conflict with variables in the input program.  Until this issue
 168 has been resolved in PPCG, you should avoid such variable names
 169 in your input program.
 170
 171
 172 Citing PPCG
 173
 174 If you use PPCG for your research, you are invited do cite
 175 the following paper.
 176
 177 @article{Verdoolaege2013PPCG,
 178     author = {Verdoolaege, Sven and Juega, Juan Carlos and Cohen, Albert and
 179                 G\'{o}mez, Jos{\'e} Ignacio and Tenllado, Christian and
 180                 Catthoor, Francky},
 181     title = {Polyhedral parallel code generation for CUDA},
 182     journal = {ACM Trans. Archit. Code Optim.},
 183     issue_date = {January 2013},
 184     volume = {9},
 185     number = {4},
 186     month = jan,
 187     year = {2013},
 188     issn = {1544-3566},
 189     pages = {54:1--54:23},
 190     doi = {10.1145/2400682.2400713},
 191     acmid = {2400713},
 192     publisher = {ACM},
 193     address = {New York, NY, USA},
 194 }