Get Started with the Intel® DPC++ Compatibility Tool

ID 768915
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

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.

Before You Begin

  1. 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.

  2. 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.

  3. Install a compiler that supports the DPC++ -specific extensions used in code migrated by Intel® DPC++ Compatibility Tool.

  4. Set environment variables using the setvars script.

  5. 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.

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>]
NOTE:
c2s is an alias to the dpct command and may be used in its place.

To see the list of Intel® DPC++ Compatibility Tool–specific options, use --help:

dpct --help

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:

Each sample README provides detailed instructions for how to migrate the sample code.

Sample Project

Description

Vector Add

  • vector_add.cu

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.

Folder Options

  • main.cu

  • bar/util.cu

  • bar/util.h

The Folder Options sample shows how to migrate more complex projects and use tool options.

Rodinia needleman-wunsch

  • needle.cu

  • needle.h

  • needle_kernel.cu

The Rodinia needleman-wunsch sample demonstrates how to migrate a Make/CMake* project from CUDA to SYCL.

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:

  1. Download the Vector Add sample.

  2. Navigate to the root of the Vector Add sample. The sample contains a single CUDA file, vector_add.cu, located in the src folder.

  3. 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.

  4. 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.

  5. 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.

  6. 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 more complex sample instructions, refer to the Migrate a Project section of the Intel® DPC++ Compatibility Tool Developer Guide and Reference.

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

How to migrate CUDA code to Data Parallel C++ (DPC++) using Intel® DPC++ Compatibility Tool,

a one-time migration engine that ports both kernels and API calls.

Installation Guides for Intel® oneAPI Toolkits

Detailed instructions on how to get and install Intel® oneAPI packages

using different installer modes and package managers.

SYCL specification version 1.2.1 PDF

The SYCL Specification PDF. Explains how SYCL integrates OpenCL devices

with modern C++.

SYCL 2020 Specification

The SYCL 2020 Specification PDF.

Khronos* SYCL overview

An overview of SYCL provided by the Khronos Group.

Compiling CUDA with clang

Description of CUDA support in clang.

Intel LLVM SYCL extensions

Proposed extensions to the SYCL specification.

Layers for Yocto* Project

Add oneAPI components to a Yocto project build using the meta-intel layers.

* SYCL is a registered trademark of the Kronos Group, Inc.