1. To reuse C/C++ functions in MATLAB.

2. For increased speed.

3. For endless custom extensions

• To configure MATLAB for c-mex programming.

• To make the simplest c-mex example, Hello, c-mex.

• To configure CUDA for MATLAB.

• To make simple CUDA examples for MATLAB.

2.2.1 Checklists

MATLAB Executable (MEX) is intended to directly use C/C++ and FORTRAN codes within the MATLAB environment to accomplish higher executing speed and avoid application bottlenecks. We call C-MEX for the C/C++ MEX, and focus on C-MEX only in this book for the purpose of deploying a GPU device. Since c-mex requires building C/C++ executable and CUDA requires hardware-specific (NVIDIA GPU) codes, we need extra installation steps in addition to a standard MATLAB installation. We first check the C/C++ compiler installation followed by CUDA installation.

2.2.2 Compiler Selection

We begin by selecting our C compiler from MATLAB. In MATLAB command window, run mex -setup. Once you are greeted with the welcome message, continue by pressing [y] to let mex locate the installed compilers (Figure 2.1).

In this example, two Microsoft Visual C++ compilers are available; we choose Microsoft Visual C++ 2010 as our C++ compiler by selecting [1]. MATLAB asks you to verify your choice. Confirm it by pressing y. Once MATLAB updates the option files, we are done with our compiler selection. The updated c-mex option file contains information about which C++ compiler we use and how we compile and link our C++ codes.

This option file was actually generated and updated from the template that is supported by mex. All the template options files supported by mex are located in the MATLABrootinwin32mexopts or the MATLABrootinwin64mexopts on Windows, or MATLABroot/bin folder on UNIX systems. Figure 2.2 shows an actual example session on c-mex setup in MATLAB command window.

MATLAB uses the one from the built-in templates for the chosen compiler. MATLAB provides a list of compilers supported by the given MATLAB version. The final option file stores all the compiler-specific compilation and linking options to be used for a c-mex compilation. You can edit this option file for specific compilation needs, such as warning and debugging options.

You can find the local copy of the option file, for example, at

If you open this option file in Mac, you also can specify what SDK you would like to use for the compiler. You simply edit SDKROOT and save (Figure 2.3).

The supported compilers for MATLAB vary from operation system to operation system and different MATLAB versions. Again, you have to make sure your installed compiler is supported by the version of MATLAB installed in your system.

Step 1. First, create an empty working directory, for example, at
c:junkMatlabMeetsCudaHello.

Step 2. Now, open MATLAB and set the working directory as our current folder in the MATLAB toolbar, as shown in the Figure 2.4.

Step 3. Open the MATLAB editor and create a new script by choosing File>New>Script from the menu. Then, save this new script as helloMex.cpp in the editor (Figure 2.5).

Step 4. Type the following codes into the editor window and save the file by choosing File>Save:
1 #include "mex.h"
2
3 void mexFunction(int nlhs,
4  mxArray *plhs[],
5    int nrhs,
6    const mxArray *prhs[])
7 {
8  mexPrintf("Hello, mex! ");
9 }
The mexPrintf(..) is equivalent to printf(..) in C/C++. Unlike printing to stdout in pritnf, this prints your formatted message in the MATLAB command window. You will find its usage is same as printf.

Step 5. Go back to the MATLAB. MATLAB now shows our newly created file, helloMex.cpp in the MATLAB current folder. We then compile this code by running the following command in the command window,
>> mex helloMex.cpp
The c-mex invokes our selected compiler to compile, link, and finally generate the binary, which we can call in our normal MATLAB session.

Step 6. On success, this will create a new mex file, hello.mexw64 (or hello.mexw32) on Windows system, in the same directory (Figure 2.6).

Step 7. Now, it is time to say hello to our c-mex by entering the command in the command window (Figure 2.7).
>> helloMex
With just a couple of lines, we have just created our first C-MEX function!

2.4.1 Preparing CUDA Settings

Before we move to adding CUDA codes, it is a good idea to check if our CUDA has been installed properly. The CUDA Toolkit is installed by default to

If properly installed, you should be able to enter command nvcc using a “system” command from the MATLAB console:

>> system(‘nvcc’)

If we run this, we get an error message, “nvcc : fatal error : No input files specified; use option --help for more information.” As the message indicates, we sure got the error since we did not specify which input file we want to compile. However, if MATLAB complains with a message, “nvcc is not recognized as an internal or external command, operable program or batch file”, then it indicates that our CUDA has not been properly installed. You will most likely want to refer to http://docs.nvidia.com/cuda/index.html to make sure your CUDA is properly installed on your system before taking the next step.

Here are some tips as to how to make sure the CUDA environment is configured properly.

In Windows, check your path by entering path at the command prompt.

C:> path

You should see the NVIDIA compiler path in the PATH variable as follows

PATH=C:Program FilesNVIDIA GPU Computing ToolkitCUDAv#.#in;C:WINDOWSsystem32;C:WINDOWS;C:WINDOWSSystem32Wbem;C:Program FilesMATLABR2010bin;C:Program FilesTortoiseSVNin;

Or, open Control Panel>All Control Panel Items>System>Advanced System Settings (Figure 2.8). Further information for Windows can be found at http://docs.nvidia.com/cuda/cuda-getting-started-guide-for-microsoft-windows/index.html.

In Mac OS X, open the Terminal application in the Finder by going to /Application/Utilities. In the shell, enter as

imac:bin $ echo $PATH

/Developer/NVIDIA/CUDA-5.0/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin

You find path where your CUDA is installed. Further information for Mac OSX can be found at http://docs.nvidia.com/cuda/cuda-getting-started-guide-for-mac-os-x/index.html.

In Linux, in bash, for example, enter as

[user@linux_bash ~]$ echo $PATH

/usr/java/default/bin: /opt/CollabNet_Subversion/bin:/bin:/sbin:/usr:/usr/bin:/usr/sbin:/opt/openoffice.org3/program:/usr/local/cuda/bin:/usr/java/default/bin:/usr/local/bin:/bin:/usr/bin:

And look for the nvcc path. In this case, nvcc was installed at /usr/local/cuda/bin. Further information for Linux can be found at http://docs.nvidia.com/cuda/cuda-getting-started-guide-for-linux/index.html.

Step 1. Create AddVectors.h in the working directory. Enter the following codes and save:
1 #ifndef __ADDVECTORS_H__
2 #define __ADDVECTORS_H__
3
4 extern void addVectors(float* A, float* B, float* C, int size);
5
6 #endif // __ADDVECTORS_H__
In this header file, we declare our vector addition function prototype which we will use in our mex function. extern indicates that our function is implemented in some other file.

Step 2. We now implement our addVectors function in AddVectors.cu. The file extension.cu represents the CUDA file. Create a new file in the MATLAB editor. Enter the following codes and save it as AddVectors.cu:
1 #include "AddVectors.h"
2 #include "mex.h"
3
4 __global__ void addVectorsMask(float* A, float* B, float* C, int size)
5 {
6 int i=blockIdx.x;
7 if (i >= size)
8  return;
9
10 C[i]=A[i]+B[i];
11 }
12
13 void addVectors(float* A, float* B, float* C, int size)
14 {
15 float *devPtrA=0, *devPtrB=0, *devPtrC=0;
16
17 cudaMalloc(&devPtrA, sizeof(float) * size);
18 cudaMalloc(&devPtrB, sizeof(float) * size);
19 cudaMalloc(&devPtrC, sizeof(float) * size);
20
21 cudaMemcpy(devPtrA, A, sizeof(float) * size, cudaMemcpyHostToDevice);
22 cudaMemcpy(devPtrB, B, sizeof(float) * size, cudaMemcpyHostToDevice);
23
24 addVectorsMask<<<size, 1>>>(devPtrA, devPtrB, devPtrC, size);
25
26 cudaMemcpy(C, devPtrC, sizeof(float) * size, cudaMemcpyDeviceToHost);
27
28 cudaFree(devPtrA);
29 cudaFree(devPtrB);
30 cudaFree(devPtrC);
31 }

Step 3. In this step, we compile the simple CUDA codes using the -c option into the object file, which we then use later for linking to our mex code. To build an object file from this code, enter the following command in the MATLAB command window.
>> system('nvcc -c AddVectors.cu')
On success, you see a message similar to the following message coming from nvcc in the command window:
AddVectors.cu
tmpxft_00000dc0_00000000-5_AddVectors.cudafe1.gpu
tmpxft_00000dc0_00000000-10_AddVectors.cudafe2.gpu
AddVectors.cu
tmpxft_00000dc0_00000000-5_AddVectors.cudafe1.cpp
tmpxft_00000dc0_00000000-15_AddVectors.ii
ans =
 0
If, however, you get the error message, “‘nvcc’ is not recognized as an internal or external command, operable program or batch file” in the Command Window, this means the C++ compiler path is not set in your system. You can add the C++ compiler path to your system environment or pass it explicitly by using –ccbin option:
>> system('nvcc -c AddVectors.cu -ccbin "C:Program FilesMicrosoft Visual Studio 10.0VCin"')

Step 4. You now notice that we just created the object file in the same working directory in the MATLAB current folder window (Figure 2.9).

Step 5. In this step, we create our mex function, which we call our AddVectors function. Just like our helloMex function, we start with mexFunction. Create a new file in the MATLAB editor. Enter the following codes and save it as AddVectorsCuda.cpp:
1 #include "mex.h"
2 #include "AddVectors.h"
3
4 void mexFunction(int nlhs, mxArray *plhs[], int nrhs, mxArray *prhs[])
5 {
6 if (nrhs != 2)
7  mexErrMsgTxt("Invaid number of input arguments");
8
9 if (nlhs != 1)
10  mexErrMsgTxt("Invalid number of outputs");
11
12 if (!mxIsSingle(prhs[0]) && !mxIsSingle(prhs[1]))
13  mexErrMsgTxt("input vector data type must be single");
14
15 int numRowsA=(int)mxGetM(prhs[0]);
16 int numColsA=(int)mxGetN(prhs[0]);
17 int numRowsB=(int)mxGetM(prhs[1]);
18 int numColsB=(int)mxGetN(prhs[1]);
19
20 if (numRowsA != numRowsB || numColsA != numColsB)
21  mexErrMsgTxt("Invalid size. The sizes of two vectors must be same");
22
23 int minSize=(numRowsA<numColsA) ? numRowsA : numColsA;
24 int maxSize=(numRowsA>numColsA) ? numRowsA : numColsA;
25
26 if (minSize != 1)
27  mexErrMsgTxt("Invalid size. The vector must be one dimentional");
28
29 float* A=(float*)mxGetData(prhs[0]);
30 float* B=(float*)mxGetData(prhs[1]);
31
32 plhs[0]=mxCreateNumericMatrix(numRowsA, numColsB, mxSINGLE_CLASS, mxREAL);
33 float* C=(float*)mxGetData(plhs[0]);
34
35 addVectors(A, B, C, maxSize);
36 }
From line 6 to 13, we make sure that our inputs support data type and correct vector size. We then acquire the size of the input vectors. In line 32, we create the output vector that will hold the result of the two-vector addition. In line 35, we call our CUDA based function to add two input vectors.

Step 6. To compile our mex and link to the CUDA object file we created, enter the following command in the MATLAB command window. For a 64-bit Windows system and CUDA v5.0,
>> mex AddVectorsCuda.cpp AddVectors.obj -lcudart -L"C:Program FilesNVIDIA GPU Computing ToolkitCUDAv5.0libx64"
If you have CUDA v4.0, replace v5.0 with v4.0. For 32-bit Windows, replace x64 with Win32; for example,
>> mex AddVectorsCuda.cpp AddVectors.obj -lcudart -L"C:Program FilesNVIDIA GPU Computing ToolkitCUDAv4.0libWin32"
The -lcudart tells mex that we are using CUDA runtime libraries. The -L"C:Program FilesNVIDIA GPU Computing ToolkitCUDAv5.0libx64" tells the location of those CUDA runtime libraries.
For Mac OS X,
>> mex AddVectorsCuda.cpp AddVectors.obj -lcudart -L"/Developer/NVIDIA/CUDA-5.0/lib"
And, for Linux Distributions,
>> mex AddVectorsCuda.cpp AddVectors.obj -lcudart -L"/usr/local/cuda/lib"

Step 7. On success, a new mex file, AddVectorsCuda.mexw64, is created in the same working directory (Figure 2.10).

Step 8. Now, it is time to run our new mex function in the MATLAB. In the command window, run
>> A=single([1 2 3 4 5 6 7 8 9 10]);
>> B=single([10 9 8 7 6 5 4 3 2 1]);
>> C=AddVectorsCuda(A, B);

Step 9. Verify the result stored in the vector C. When you add each vector element, you get 11 in the resulting vector C:
>> C
C =
11   11   11   11   11   11   11   11   11   11
You can run this whole process using runAddVectors.m, as follows:

2.6 Example with Image Convolution

We now try to create a more complex example. First of all, we define our mex function. We read one sample image from MATLAB and pass it onto our mex function which then does simple two-dimensional convolution using a 3×3 mask. The result is returned to MATLAB. It will be interesting to show how we do this in three cases:

In this section, we focus on how we do this in each case with sample codes. For all cases, we use the same image (Figure 2.12), whose date type is single and the same 3×3 mask of single data type. The example mask follows:

>> quaters = (single)imread('eight.tif'),

>> mask = single([1 2 1; 0 0 0; -1 -2 -1]);

>> H2 = conv2Mex(quarters, mask);

>> imagesc(H2);

>> colormap(gray);

>> tic; H1 = conv2(quaters, mask); toc;

Elapsed time is 0.001292 seconds.

>> tic; H1 = conv2(quaters, mask); toc;

Elapsed time is 0.001225 seconds.

>> tic; H2 = conv2Mex(quaters, mask); toc;

Elapsed time is 0.001244 seconds.

>> tic; H2 = conv2Mex(quaters, mask); toc;

Elapsed time is 0.001118 seconds.

>> tic; H3 = conv2MexCuda(quaters, mask); toc;

>> tic; H3 = conv2MexCuda(quaters, mask); toc;

Elapsed time is 0.035877 seconds.

2.7 Summary

As we did in AddVectors, we put CUDA-related functions in conv2Mex.cu (Figure 2.14). The file conv2Mex.h contains the function definition that our mex function, conv2MexCuda.cpp, calls within its gateway routine. Once we compile CUDA code into an object file, we use the mex command to compile our mex code and link it to the CUDA object file.