A prototype CUDA-to-OpenCL source-to-source translator, built on the Clang compiler framework
C++ Cuda CMake Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
testCases
.gitignore
CMakeLists.txt Removed CMakeList.txt's dependence on the removed RewriteCUDA.cpp Nov 13, 2014
LICENSE Merge branch 'master' of ssh://charon.cs.vt.edu/repos/git/cu2cl-public Jun 7, 2016
README
cu2cl_libTooling.cpp
install.sh Updated licensing model, now injects LGPL comment into utility files Jun 13, 2016

README

CU2CL Beta Release (0.7.0b)
========================================
Welcome to the CU2CL (CUDA-to-OpenCL) source-to-source translator project. CU2CL is a work-in progress academic prototype translator that endeavors to provide translation of many of the most frequently used CUDA features. However, CUDA is a large, moving target and CU2CL may not support all syntax and API elements of the current CUDA specification.

Currently it targets OpenCL 1.0 as the output standard. Further it aims to provide an easily-maintained translated source by preserving formatting and developer comments from the original CUDA, as well as injecting searchable comment tags for untranslated structures. (These are intended to aid manual post-translation intervention.)

The tool translated both host- and device-side code, generating separate families of output files suitable for a standard C++ compiler (*-cl.cpp/h files), as well as an OpenCL kernel compiler (*-cl.cl files). The majority of supported translations are focused on core Runtime API calls for memory, device, thread, stream, and event management as well as the CUDA C-style kernel invocation and full kernel function translation.

Additionally, the 0.7.0b release has added a range of new features to support global translation of large, multi-file codebases. Please see ReleaseNotes.txt for more information. 

This release currently has limited or no support for several features including (but not limited to):

    CUDA Textures and Surfaces
    CUDA/OpenGL Interoperability
    C++ Templates in kernel code
    CUDA Driver API
    CUDA Runtime API features newer than 3.2
    CUDA Kernel features newer than 3.2
    Precompiled CUDA libraries

We have endeavored to provide translation-time warnings for as many of these cases as possible, but the tool is undergoing active development and the CUDA specification is a moving target so there are likely cases we've missed. There is also a potential for the translator to produce small mistranslations in the presence of atypical usage of CUDA syntax. There will be bugs, and we'd love to hear about them so that we can improve the tool. Contact us at cu2cl-info@cs.vt.edu.

Installation from Source
========================================
Currently only tested and officially supported on 64-bit variants of Ubuntu Linux (10.04 and later). (But likely to work on other 64-bit Debian variants.)

Dependencies:

    make
    cmake >= 2.8
    wget
    CUDA Runtime >=3.2
    GNU C Library (glibc) >= 2.11.1

Ensure you have internet access as the install process will download the LLVM/Clang tarballs necessary to build the CU2CL binary.

Unpack this tarball, and invoke the install.sh BASH script to start the install process. The script will use wget to download the necessary revision of the LLVM/Clang source, and unpack it to subdirectory llvm-3.4 and create the build directory llvm-build. It will then configure cmake and build the LLVM/Clang binaries required by CU2CL. Compiling Clang can take some time, so by default the installation script is configured to use two make jobs for compilation. To change this behavior, edit line 23 of the script "make -j2" to reflect the desired number of jobs.

The script then symbolically links a small number of include files generated during the LLVM/Clang build file so they are locatable my the CU2CL build process. It then configures cmake to build CU2CL and performs the build. CU2CL is a single source tool, so no threaded make is necessary for this step.

After compiling LLVM/Clang and CU2CL, the installation should be complete. The binary "cu2cl-tool" in directory "cu2cl-build" can now be used to perform translations. Do not remove the "llvm-build" directory as CU2CL needs access to libclang.so.3.4. (If you have a local packaged install of this library, you may be able to use that, however this is untested.) 


Usage
========================================
Once built, the "cu2cl-tool" binary can be used to translate sets of CUDA source files, along with any *.cu or *.cuh source files they include. However, it will not provide translation of any included headers specified with the system include "<...>" syntax. After successful translation, CU2CL will output *-cl.cpp, *-cl.cl, and *-cl.h files as appropriate for host, device, and header code. (*-cl.h headers will only be generated from *-.cuh input.)

In order to run the tool the following syntax must be used:
./cu2cl_tool <CUDA source files> -- <Compiler options>

Where <CUDA source files> is an unordered list of any source files which contain CUDA C, CUDA kernel code, or CUDA API calls, and collectively make up a complete binary. (Either by compiling to separate *.o files, and later linking, or specifying all sources to a combined compile+link step.) The important part is making sure all files that would be linked together are translated in the same invocation, so that global OpenCL state can be appropriately generated and shared between separate compilations. (CUDA files which are #included with local-include "*.cuh" syntax will automatically be included in the translation.)

And <Compiler options> are any standard build options that may need to be passed, such as command-line #defines (-D arguments) or include directories (-I arguments).

So a sample invocation would look like:

./cu2cl_tool fooRuntimeMain.cpp fooKernels.cu -- -DGPU_ON -I ./fooIncludes

Which would generate fooRuntimeMain.cpp-cl.cpp, fooRuntimeMain.cpp-cl.cl, fooKernels.cu-cl.cpp, fooKernels.cu-cl.cl, and any associated translated header files.

Additionally, a set of CU2CL utility functions will be generated in cu2cl_util.c/h/cl. cu2cl_util.c must be compiled and linked into the finished executable for the linking to succeed, as it includes requisite initialization, cleanup, and other OpenCL utility functions. 

It will not attempt to translate any *.c *.h, *.cpp, *.hpp or other included source file types, regardless of whether they contain CUDA syntax (variables, runtime function calls, or special syntax) or not, ONLY *.cu or *.cuh. It will also not attempt to translate any includes specified with the #include <...> syntax reserved for system headers - project headers should use the #include "..." syntax. Finally, it does not support the CUDA SDK Samples' shrUtils or cutils, and will likely emit malformed source code if they are present. Please manually refactor your code to handle these constraints before attempting translation. 

Please visit http://chrec.cs.vt.edu/cu2cl for answers to other frequently asked questions.


Acknowledgements
========================================
	CU2CL has been supported in part by NSF I/UCRC IIP-0804155 via the NSF Center for High-Performance Reconfigurable Computing.



License
========================================
Please refer to the LGPLv2.1 LICENSE file included with this tarball.

If you have any questions or need for correspondence regarding this license or wish to negotiate other licensing terms, please contact Virginia Tech Intellectual Property at vtiplicensing@vtip.org with a carbon copy (CC) to cu2cl-info@cs.vt.edu