Get Started with Intel® DPC++ Compatibility Tool
Intel® DPC++ Compatibility Tool assists in the migration of your existing CUDA* code to SYCL* code. The tool ports CUDA language kernels and library API calls, migrating 90%-95% of CUDA code to SYCL code. The tool additionally inserts inline warnings to help you complete the migration and tune your code.
Intel® DPC++ Compatibility Tool supports migrating programs implemented with CUDA versions 8.0, 9.x, 10.x, 11.x, 12.0-12.1. The list of supported languages and versions may be extended in the future.
For additional information about the tool, visit the Intel® DPC++ Compatibility Tool Developer Guide and Reference.
For the most up-to-date information and information about known issues, visit the Release Notes.
For detailed information about migration workflow, refer to Migration Workflow Guidelines.
Before You Begin
Install the tool.
Intel® DPC++ Compatibility Tool is included in the Intel® oneAPI Base Toolkit. If you have not installed the Intel® oneAPI Base Toolkit, follow the instructions in the Installation Guide.
The Intel® DPC++ Compatibility Tool is also available as a stand-alone download. Download the stand-alone tool.
Make sure CUDA headers are accessible to the tool.
Certain CUDA header files (specific to your project) may need to be accessible to Intel® DPC++ Compatibility Tool. The tool looks for these CUDA header files in the following default locations:
/usr/local/cuda/include
/usr/local/cuda-x.y/include, where x.y is one of these values: 8.0, 9.x, 10.x, 11.x, 12.0-12.1.
NOTE:If your CUDA installation is from a source other than NVIDIA, your header files may be in a different location. Locate your header files and use the --cuda-include-path=<path/to/cuda/include> option to specify the location when you run the tool.The CUDA include path should not be the same as, or a child path of, the directory where the source code (that needs to be migrated) is located.
Install a compiler that supports the DPC++ -specific extensions used in code migrated by Intel® DPC++ Compatibility Tool.
Set environment variables using the setvars script.
Optional: If your program targets GPUs, install the appropriate GPU drivers or plug-ins to compile your program to run on Intel, AMD*, or NVIDIA* GPUs.
To use an Intel GPU, install the latest Intel GPU drivers.
To use an AMD GPU, install the oneAPI for AMD GPUs plugin.
To use an NVIDIA GPU, install the oneAPI for NVIDIA GPUs plugin.
Run the Tool
You can run Intel® DPC++ Compatibility Tool from the command line and provide migration instructions using the tool’s command-line options. The general command syntax is:
dpct [options] [<source0>... <sourceN>]
To see the list of the language parser (Clang*) options, pass -help as the Clang option:
dpct -- -help
For a complete list of command-line options, refer to the Command Line Options Reference.
Specify Files to Migrate
If no directory or file is specified for migration, the tool will try to migrate source files found in the current directory. The default output directory is dpct_output. Use the --out-root option to specify an output directory.
You can optionally provide file paths for source files that should be migrated. The paths can be found in the compilation database. The following examples show ways to specify a file or directory for migration.
Migrate a single source file:
dpct source.cpp
Migrate all files available in the compilation database:
dpct -p=<path to the location of compilation database file>
Migrate one file in the compilation database:
dpct -p=<path to the location of compilation database file> source.cpp
Migrate source files in the directory specified by the --in-root option and place generated files in the directory specified by the --out-root option:
dpct --in-root=foo --out-root=bar
Understand Emitted Warnings
During file migration, Intel® DPC++ Compatibility Tool identifies the places in the code that may require your attention to make the code SYCL-compliant or correct.
Warnings are inserted into the generated source files and displayed as warnings in the output. For example:
/path/to/file.hpp:26:1: warning: DPCT1003:0: Migrated API does not return error code. (*,0) is inserted. You may need to rewrite this code.
// source code line for which warning was generated
^
For more details on what a specific warning means, refer to the Diagnostic Reference.
Get Code Samples
Use the Intel® DPC++ Compatibility Tool code samples to get familiar with the migration process and tool features.
To access the samples:
Use the oneAPI CLI Samples Browser to select a sample from the Intel® DPC++ Compatibility Tool category. For detailed information on downloading samples using the oneAPI CLI Samples Browser, as well as using an IDE to run the sample, refer to
Download the sample from GitHub*.
Each sample README provides detailed instructions for how to migrate the sample code.
Sample Project |
Description |
---|---|
The Vector Add sample shows how to migrate a simple program from CUDA* to SYCL*. You can use this sample to verify that your development environment is set up correctly to use Intel® DPC++ Compatibility Tool. |
|
The Folder Options sample shows how to migrate more complex projects and use tool options. |
|
The Rodinia Needleman-Wunsch sample demonstrates how to migrate a Make/CMake* project from CUDA to SYCL. |
Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub). These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.
Migrate the Vector Add Sample
The Vector Add sample shows how to migrate a simple CUDA program to SYCL-compliant code. The simple program adds two vectors of [1..N] and prints the result. The program is intended for CPU.
The following steps show how to migrate the Vector Add sample using Intel® DPC++ Compatibility Tool:
Download the Vector Add sample.
Navigate to the root of the Vector Add sample. The sample contains a single CUDA file, vector_add.cu, located in the src folder.
From the root folder of the sample project, run Intel® DPC++ Compatibility Tool:
dpct --in-root=. src/vector_add.cu
The --in-root option specifies the root location of the program sources that should be migrated. Only files and folders within the --in-root directory will be considered for migration by the tool. Files outside the --in-root directory will not be migrated, even if they are included by a source file within the --in-root directory. By default, the migrated files are created in a new folder named dpct_output.
As a result of the migration command, you should see the new SYCL source file in the output folder:
dpct_output └── src └── vector_add.dp.cpp
The relative paths of the migrated files are maintained.
Inspect the migrated source code and address any DPCT warnings generated by the too.
This sample should generate the following warning:
warning: DPCT1003:0: Migrated API does not return error code. (*, 0) is inserted. You may need to rewrite this code.
Look up the DPCT1003 warning in the Diagnostic Reference.
The reference explains that SYCL uses exceptions to report errors instead of error codes. In this instance, the tool removed the conditional statement to exit on failure and instead wrapped the code in a try block. The tool retained the error status variable from the original code and changed the source to always assign an error code of 0 to the variable.
The reference provides suggestions for how to fix this warning. In this sample, manually resolve the issue by removing the variable status, since it is not needed.
Compile the migrated code:
icpx -fsycl -I<install_dir>/include src/vector_add.dp.cpp
where <install_dir> is the Intel® DPC++ Compatibility Tool installation directory.
Run the migrated program:
NOTE:The Vector Add sample is for CPU. Make sure to target your CPU by using the ONEAPI_DEVICE_SELECTOR environment variable:ONEAPI_DEVICE_SELECTOR=*:cpu
./vector_add
You should see a block of even numbers, indicating the result of adding two vectors: [1..N] + [1..N].
For detailed information about migration workflow, refer to Migration Workflow Guidelines.
Find More
Content |
Description |
---|---|
Intel® DPC++ Compatibility Tool Developer Guide and Reference |
Detailed overview of Intel® DPC++ Compatibility Tool features, workflow, and use. |
On-Demand Webinar: Migrating Your Existing CUDA Code to DPC++ Code |
|
|
|
|
|
The SYCL 2020 Specification PDF. |
|
An overview of SYCL provided by the Khronos Group. |
|
Description of CUDA support in clang. |
|
Proposed extensions to the SYCL specification. |
|
Add oneAPI components to a Yocto project build using the meta-intel layers. |
* SYCL is a registered trademark of the Kronos Group, Inc.