Intel® DPC++ Compatibility Tool Developer Guide and Reference

Developer Guide and Reference

  • 2022.1
  • 04/11/2022
  • Public Content
Contents

Incremental Migration

The Intel® DPC++ Compatibility Tool provides incremental migration, which automatically merges the results from multiple migrations into a single migrated project.
Incremental migration can be used to
  • migrate a CUDA* project incrementally, for example 10 files at a time
  • migrate new CUDA files into an already migrated project
  • migrate multiple code paths
Incremental migration is enabled by default. Disable incremental migration using the
--no-incremental-migration
 option.

Example 1: Migrate a File with Conditional Compilation Code

This example shows incremental migration for a file
sample1.cu
 that contains conditional compilation code. Content of
sample1.cu
:
      #ifndef MACRO_A
      ... code path 1 ...
      #elif MACRO_A == 1
      ... code path 2 ...
      #else
      ... code path 3 ...
      #endif
Incrementally migrate
sample1.cu
 by executing the
dpct
 command in the same working directory as the file:
  1. Generate
    sample1.dp.cpp
    , which contains migrated code for code path 1:
    dpct sample1.cu --out-root=out
  2. Generate
    sample1.dp.cpp
    , which contains migrated code for code path 1 and code path 2:
    dpct sample1.cu --out-root=out --extra-arg=”-DMACRO_A=1”
  3. Generate
    sample1.dp.cpp
    , which contains migrated code for code path 1, code path 2, and code path 3:
    dpct sample1.cu --out-root=out --extra-arg=”-DMACRO_A=2”
The result contains migrated code for each code path.

Example 2: Migrate a Header File Used by Multiple Source Files

This example shows the use of incremental migration for a header file that is included in several source files, each with a different macro definition.
Content of header file
sample_inc.h
:
     #ifdef MACRO_A
     ... code path 1...
     #else
     ... code path 2...
     #endif
Content of source file
sample2.cu
:
     #define MACRO_A
     #include “sample_inc.h”
     #undef MACRO_A
Content of source file
sample3.cu
:
     #include “sample_inc.h”
Incrementally migrate the files by executing the
dpct
 command in the same working directory as the files:
  1. Generate
    sample2.dp.cpp
     and
    sample_inc.h
    , which contains migrated code for code path 1:
    dpct sample2.cu --out-root=out
  2. Generate
    sample3.dp.cpp
     and
    sample_inc.h
    , which contains migrated code for code path 1 and code path 2:
    dpct sample3.cu --out-root=out
The result contains migrated code for each code path.

Limitations

Incremental migration will not be triggered in the following conditions:
  1. Intel® DPC++ Compatibility Tool option
    --no-incremental-migration
     is specified.
  2. Different versions of the Intel® DPC++ Compatibility Tool are used across multiple migration invocations.
  3. Different options of the Intel® DPC++ Compatibility Tool are used across multiple migration invocations. If the Intel® DPC++ Compatibility Tool detects that a previous migration used a different option-set, the Intel® DPC++ Compatibility Tool will stop migration and exit.
The following options direct the Intel® DPC++ Compatibility Tool to generate different migrated code and may break incremental migration. Use the same values for these options across migration invocations to keep incremental migration working.
  • --always-use-async-handler
  • --assume-nd-range-dim
  • --comments
  • --custom-helper-name
  • --enable-ctad
  • --keep-original-code
  • --no-cl-namespace-inline
  • --no-dpcpp-extensions
  • --no-dry-pattern
  • --optimize-migration
  • -p
  • --process-all
  • --sycl-named-lambda
  • --use-experimental-features
  • --use-explicit-namespace
  • --usm-level
  • --vcxprojfile

Product and Performance Information

1

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