Get Started with the Intel® DPC++ Compatibility Tool

Get Started

  • 2021.2
  • 03/26/2021
  • Public Content
Contents

Get Started with the Intel® DPC++ Compatibility Tool

The Intel® DPC++ Compatibility Tool assists in the migration of a developer’s program that is written in CUDA* to a program written in Data Parallel C++ (DPC++), which is based on modern C++ and incorporates portable industry standards such as SYCL*.
Visit the Intel® DPC++ Compatibility Tool Developer Guide and Reference for additional information about the tool. Visit the Release Notes for known issues and the most up-to-date information.
Use of the Intel® DPC++ Compatibility Tool will result in a project that is not entirely migrated. Additional work, as outlined by the output of the Intel® DPC++ Compatibility Tool, is required to complete the migration.

Before You Begin

The 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.
Certain CUDA header files (specific to your project) may need to be accessible to the Intel® DPC++ Compatibility Tool. The Intel® DPC++ Compatibility Tool looks for these CUDA header files in the default locations:
  • /usr/local/cuda/include
  • /usr/local/cuda-x.y/include
    , where
    x.y
     is one of these values: 8.0, 9.0, 9.1, 9.2, 10.0, 10.1, 10.2, 11.0, or 11.1
You can reference custom locations by pointing to them with the
--cuda-include-path=<path/to/cuda/include>
 option in the Intel® DPC++ Compatibility Tool command line.
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.
Currently, the Intel® DPC++ Compatibility Tool supports the migration of programs implemented with CUDA versions 8.0, 9.0, 9.1, 9.2, 10.0, 10.1, 10.2, 11.0, or 11.1. The list of supported languages and versions may be extended in the future.
To set up the Intel® DPC++ Compatibility Tool environment, run the following:
  • On Linux (sudo):
    source /opt/intel/oneapi/setvars.sh
  • On Linux (user):
    source ~/intel/oneapi/setvars.sh
  • On Windows:
    Drive:\Program Files (x86)\Intel\oneAPI\setvars.bat
The general invocation syntax from the operating system shell is:
dpct [options] [<source0>... <sourceN>]
Built-in Usage Information
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

Emitted Warnings

The Intel® DPC++ Compatibility Tool notes the places in the code that may require your attention during the migration of the files in order to make the code DPC++ compliant or correct. Comments are inserted into the generated source files and displayed as warnings in the output. For more details on what a particular warning means, see the Diagnostic Reference. An example is below:
/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
^

Migrate a Simple Test Project

The Intel® DPC++ Compatibility Tool comes with several different samples to allow you to explore the tool and familiarize yourself with how it functions. The samples are outlined in the table below.
Access the samples in one of the following ways, then navigate to the root of the sample project:
  • Use the oneapi-cli utility to select a sample from the Intel® DPC++ Compatibility Tool category.
  • Download from GitHub*.
For more detailed information on how to download and access the samples, visit the Intel® oneAPI Base Toolkit Get Started Guides:
For more detailed information on the purpose and usage of the test samples, locate the README file provided for each sample.
Test Samples
Description
Vector Add DPCT
  • vector_add.cu
This sample demonstrates how to migrate a simple program from CUDA to Data Parallel C++. Vector Add provides an easy way to verify that your development environment is setup correctly to use the Intel® DPC++ Compatibility Tool (dpct).
Folder Options DPCT
  • main.cu
  • bar/util.cu
  • bar/util.h
This sample provides an example of how to migrate more complex projects and use options.
Rodinia NW DPCT
  • needle.cu
  • needle.h
  • needle_kernel.cu
This sample demonstrates how to migrate a Make/CMake project from CUDA to Data Parallel C++ using the Intel® DPC++ Compatibility Tool.
Example
The example provided uses the Vector Add sample.
Basic Invocation on the Command Line
Use the steps below to migrate the Vector Add DPCT sample.
  1. Download the
    vector_add.cu
     sample.
  2. Run the Intel® DPC++ Compatibility Tool from the sample root directory:
    dpct --in-root=. src/vector_add.cu
    The
    vector_add.dp.cpp
     file should appear in the
    dpct_output
     directory. Use:
    cd dpct_output
    The file is now a DPC++ source file.
  3. Verify the generated source code and fix the code that the Intel® DPC++ Compatibility Tool was unable to migrate. (The code used in this example is simple. In this instance, manual changes may not be needed). For the most accurate and detailed instructions on addressing warnings, see the
    Addressing Warnings in the Migrated Code
     section of the README files.
    You must add
    -I<dpct_root_folder>/include
     for the compilation of the migrated sample.
    For more complex sample instructions, see the Migrate a Project section of the Intel® DPC++ Compatibility Tool Developer Guide and Reference.

Find More

Content
Description and Links
Intel® DPC++ Compatibility Tool Developer Guide and Reference
On-Demand Webinar: Migrating Your Existing CUDA Code to DPC++ Code
Installation Guides for Intel® oneAPI Toolkits
SYCL specification version 1.2.1 PDF
Khronos* SYCL overview site
An overview of SYCL: https://www.khronos.org/sycl/
CUDA support in Clang
Proposed extensions to the SYCL specification

Notices and Disclaimers

Intel technologies may require enabled hardware, software or service activation.
No product or component can be absolutely secure.
Your costs and results may vary.
© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.
No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.
The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.