mexcuda

Compile MEX functions or PTX files for GPU computation

Syntax

mexcuda filenames

mexcuda option1 ... optionN filenames

Description

mexcuda filenames compiles and links source files into a shared library called a MEX file, executable from within MATLAB^®. The function compiles MEX files written using the CUDA^® C++ framework with the NVIDIA^® nvcc compiler, allowing the files to define and launch GPU kernels. In addition, the mexcuda function exposes the GPU MEX API to allow the MEX file to read and write GPU arrays.

mexcuda is an extension of the MATLAB mex function. Only a subset of the compilers supported by the mex function are supported by mexcuda. For more information, see Supported Host Compilers.

mexcuda option1 ... optionN filenames builds with the specified build options. The option1 ... optionN arguments supplement or override the default mexcuda build configuration. You can use the most of the options available in mex with mexcuda.

Examples

Compile Simple MEX Function

Compile a simple MEX function to create the function myMexFunction from a CUDA C++ source file.

mexcuda myMexFunction.cu

An example source file is available at matlabroot/toolbox/parallel/gpu/extern/src/mex/mexGPUExample.cu.

Compile a PTX file

Compile a PTX file from a CUDA C++ source file. (since R2023a)

mexcuda -ptx myMexFunction.cu

Before R2023a: Use the nvcc compiler in the NVIDIA CUDA Toolkit to compile a PTX file instead of the mexcuda function.

Display Detailed Build and Troubleshooting Information

Use verbose mode to display the compile and link commands and other information useful for troubleshooting.

mexcuda -v myMexFunction.cu

Compile and Link Multiple Source Files

Compile and link multiple source files with one command.

mexcuda myMexFunction.cu otherSource1.cpp otherSource2.cpp

Compile and Link in Two Stages

First compile, then link to create a function.

mexcuda -c myMexFunction.cu
mexcuda myMexFunction.obj

The first line compiles to myMexFunction.obj (Windows^®) or myMexFunction.o (UNIX^®), and the second links to create the function myMexFunction.

Compile with Dynamic Parallelism

Compile code that uses dynamic parallelism, defining kernels that launch other kernels.

mexcuda -dynamic myMexFunction.cu

Link to Third-Party Library

Compile a MEX function that makes use of the CUDA image primitives library, npp, which is installed at C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5\lib\x64\nppi.lib.

mexcuda '-LC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5\lib\x64' -lnppi myMexFunction.cu 

Input Arguments

filenames — One or more file names

character vector

One or more file names, including name and file extension, specified as a character vector. If the file is not in the current folder, specify the full path to the file. File names can be any combination of:

• C or C++ language source files

• object files

• library files

The first source code file listed in filenames is the name of the binary MEX file. To override this naming convention, use the '-output' option.

Data Types: char

option1 ... optionN — One or more build options

character vectors corresponding to valid option flags

One or more build options, specified as one of these values. Options can appear in any order on any platform, except where indicated.

Most options available for the mex function are supported. In addition, the following options are also available.

Option	Description
-dynamic	Dynamic parallelism: compiles MEX files that define kernels that launch other kernels.
-ptx (since R2023a)	Generate a parallel thread execution file (.ptx). The generated PTX file can be used with CUDAKernel to run kernels directly from MATLAB. Does not compile a MEX file.
-G	Generate debug information for device code. This makes it possible to step through kernel code line by line in one of NVIDIA's debugging applications (NSight or cuda-gdb). To enable debugging of host code use -g.

The following mex function option is not supported.

Option	Reason
-compatibleArrayDims	Use of the MATLAB large-array-handling API is implicit, and cannot be overridden.

All other options for mex are supported for mexcuda. See the documentation for mex for details.

Tips

• The CUDA toolkit installed with MATLAB does not contain all libraries that are available in the CUDA toolkit. If you want to use a specific library that is not installed with MATLAB, install the CUDA toolkit. You can check which CUDA toolkit version MATLAB supports using gpuDevice. For more information about the CUDA Toolkit, see Install CUDA Toolkit (Optional).

• If the CUDA toolkit is not detected or is not a supported version, mexcuda compiles the CUDA code using the NVIDIA nvcc compiler installed with MATLAB. To check which compiler mexcuda is using, use the -v flag for verbose output in the mexcuda command.

• If you have installed the CUDA toolkit in a non-default location, you can specify the location of nvcc on your system by storing it in the environment variable MW_NVCC_PATH. You can set this variable using the MATLAB setenv command. For example,

  setenv("MW_NVCC_PATH","/usr/local/CUDA/bin")

Version History

Introduced in R2015b