CUDA by Example

-------------------------------------------------------------------------------- -------------------------------------------------------------------------------- CUDA by Example: An Introduction to General-Purpose GPU Programming README.txt -------------------------------------------------------------------------------- -------------------------------------------------------------------------------- July 2010 Copyright (C) 2010 NVIDIA Corp. Distribution Contents ---------------------------------------------------- The end user license (license.txt) Code examples from chapters 3-11 of "CUDA by Example: An Introduction to General-Purpose GPU Programming" Common code shared across examples This README file (README.txt) Compiling the Examples ---------------------------------------------------- The vast majority of these code examples can be compiled quite easily by using NVIDIA's CUDA compiler driver, nvcc. To compile a typical example, say "example.cu," you will simply need to execute: > nvcc example.cu The compilation will produce an executable, a.exe on Windows and a.out on Linux. To have nvcc produce an output executable with a different name, use the -o <output-name> option. To learn about additional nvcc options, run > nvcc --help Compiling Examples for Compute Capabilities > 1.0 ---------------------------------------------------- The examples from Chapter 9, hist_gpu_gmem_atomics.cu and hist_gpu_shmem_atomics.cu, both require GPUs with compute capabilities greater than 1.0. Likewise, the examples from Appendix A, dot.cu and hashtable_gpu.cu, also require a GPU with compute capability greater than 1.0. Accordingly, these examples also require an additional argument in order to compile and run correctly. Since hist_gpu_gmem_atomics.cu requires compute capability 1.1 to function properly, the easiest way to compile this example is, > nvcc -arch=sm_11 hist_gpu_gmem_atomics.cu Similarly, hist_gpu_shmem_atomics.cu relies on features of compute capability 1.2, so it can be compiled as follows: > nvcc -arch=sm_12 hist_gpu_shmem_atomics.cu Compiling Examples with OpenGL and GLUT Dependencies ---------------------------------------------------- The following examples use OpenGL and GLUT (GL Utility Toolkit) in order to display their results: Chapter 4 Chapter 7 julia_cpu.cu heat.cu julia_gpu.cu heat_2d.cu Chapter 5 Chapter 8 ripple.cu basic.cu shared_bitmap.cu basic2.cu heat.cu Chapter 6 ripple.cu ray.cu ray_noconst.cu To build with OpenGL and GLUT, some additions will need to be made to the nvcc command-line. These instructions are different on Linux and Windows operating systems. Linux ----------------------- On Linux, you will first need to ensure that you have a version of GLUT installed. One method for determining whether GLUT is correctly installed is simply attempting to build an example that relies on GLUT. To do this, one needs to add -lglut to the nvcc line, indicating that the example needs to be linked against libglut. For example: > nvcc -lglut julia_gpu.cu If you get an error about missing GL/glut.h or a link error similar to the following, GLUT is not properly installed: /usr/bin/ld: cannot find -lglut If you need to install GLUT, we recommend using freeglut on Linux systems. As always with Linux, there exist a variety of ways to install this package, including downloading and building a source package from http://freeglut.sourceforge.net/ The easiest method involves exploiting the package managers available with many Linux distributions. Two common methods are given here: > yum install freeglut-devel > apt-get install freeglut-dev Windows ----------------------- This distribution includes both 32-bit and 64-bit versions of GLUT, pre-built for Windows. You are free to ignore these, but using them will be your quickest method to get up and running. For example, to compile the heat transfer simulation in Chapter 7, we will need to explicitly tell nvcc where to find the GLUT library. If we are in the directory where we've extracted this distribution, we can add the argument -Llib to tell nvcc to look in .\lib for additional libraries. > nvcc -Llib chapter07\heat.cu When we proceed to run the resulting a.exe, we will also need to ensure that glut32.dll (on 32-bit Windows) or glut64.dll (on 64-bit Windows) can be found on our PATH (or that there's a copy in the directory containing a.exe). These files are located in the bin\ directory of the distribution. In the Linux-specific instructions, we recommended freeglut. Note that freeglut is also available for Windows platforms, so you should feel free to download and use the Windows freeglut. However, if you choose to do so, the rest of these instructions will not be useful. Windows Notes ------------- o To compile from the command-line on Windows, it is recommended that you use the command-line shortcut installed by Visual Studio. On 64-bit systems with non-Express Editions of Visual Studio, this shortcut will be named: "Visual Studio <version> x64 Win64 Command Prompt." On 32-bit systems or on 64-bit systems with Visual Studio Express Edition, this shortcut will be named, "Visual Studio <version> Command Prompt." o If you are using a 64-bit system with Visual Studio Express Edition, you will need an additional command-line argument to nvcc in order to compile 32-bit executables. This is a consequence of the Express Edition not containing 64-bit compilation tools. Without the -m32 command-line argument, nvcc defaults to 64-bit builds when it detects a 64-bit system (which fails to link because Visual Studio Express Edition only contains 32-bit runtime libraries). For example, to compile Chapter 3's "Hello, World!" example: > nvcc -m32 hello_world.cu o Individual kernels are limited to a 2-second runtime by Windows Vista and Windows 7. Kernels that run for longer than 2 seconds will trigger the Timeout Detection and Recovery (TDR) mechanism. For more information, see http://www.microsoft.com/whdc/device/display/wddm_timeout.mspx. This issue may specifically be a problem on slower GPUs when running the gmem histogram example in Chapter 9 or the GPU hashtable example in Appendix A. To work around this issue, try running these examples with a smaller value for SIZE.