Advanced Migration Options#

The following tables list advanced options to control migrated source, generate reports, and query API mapping.

Options to Format Migrated Code#

Option

Description

--format-range=<value>

Set the range of formatting.

The values are:

  • =all: Format all code.

  • =migrated: Only format the migrated code (default).

  • =none: Do not format any code.

--format-style=<value>

Set the formatting style.

The values are:

  • =custom: Use the coding style defined in the .clang-format file (default).

  • =google: Use the Google* coding style.

  • =llvm: Use the LLVM coding style.

Example for the .clang-format file content:

BasedOnStyle:
LLVM IndentWidth: 4
TabWidth: 4
UseTab: ForIndentation

Options to Specify Additional Migration Rules#

Option

Description

--rule-file=<file>

Specify the rule file path that contains rules used for migration.

Options to Control SYCL Extensions and Experimental Features#

Option

Description

--no-dpcpp-extensions=<value>

A comma-separated list of extensions not to be used in migrated code. By default, these extensions are used in migrated code.

The values are:

  • =bfloat16: Disable the SYCL extensions for bfloat16. See more details.

  • =device_info: Disable the Intel extensions for device information, if supported by the compiler and the backend. See more details.

  • =enqueued_barriers: Disable the enqueued barriers extension. See more details.

  • =peer_access: Disable the peer access extension. See more details.

  • =assert: Disable the assert extension. See more details.

  • =queue_empty: Disable the queue empty extension. See more details.

  • =all: Disable all extensions listed in this option.

--use-dpcpp-extensions=<value>

A comma-separated list of extensions to be used in migrated code. By default, these extensions are not used in migrated code.

  • =c_cxx_standard_library: Use std functions from the libdevice library (provided by Intel® oneAPI DPC++/C++ Compiler) and C/C++ Standard Library to migrate functions which have no mapping in the SYCL standard. If this value is used together with intel_device_math, the intel_device_math functions take precedence. See more details.

  • =intel_device_math: Use sycl::ext::intel::math functions from the libdevice library (provided by Intel® oneAPI DPC++/C++ Compiler) to migrate functions which have no mapping in the SYCL standard. See more details.

  • all: Enable all DPC++ extensions listed in this option.

--use-experimental-features=<value>

A comma-separated list of experimental features to be used in migrated code. By default, experimental features will not be used in migrated code.

The values are:

  • =bfloat16_math_functions: Experimental extension that allows use of bfloat16 math functions. See more details.

  • =bindless_images: Experimental extension that allows use of bindless images APIs. See more details.

  • =dpl-experimental-api: Experimental extension that allows use of experimental oneDPL APIs. See more details.

  • =free-function-queries: Experimental extension that allows getting id, item, nd_item, group, and sub_group instances globally. See more details.

  • =local-memory-kernel-scope-allocation: Experimental extension that allows allocation of local memory objects at the kernel functor scope. See more details.

  • =logical-group: Experimental helper function used to logically group work-items. See more details in dpct::experimental::logical_group in header file util.hpp.

  • =masked-sub-group-operation: Experimental helper function used to execute sub-group operation with mask. See more details in dpct::experimental::select_from_sub_group, dpct::experimental::shift_sub_group_left, dpct::experimental::shift_sub_group_right and dpct::experimental::shift_sub_group_right in header file util.hpp.

  • =matrix: Experimental extension that allows use of matrix extension like class joint_matrix. See more details.

  • =nd_range_barrier: DEPRECATED. Experimental helper function used to help cross-group synchronization during migration. Please use the following option instead: --use-experimental-features=root-group

  • =root-group: Experimental extension that allows use of root group class and relative API.

  • =graph: Experimental extension that allows use of SYCL Graph APIs.

  • =occupancy-calculation: Experimental helper function used to calculate occupancy. See more details in dpct::experimental::calculate_max_active_wg_per_xecore and dpct::experimental::calculate_max_potential_wg in header file util.hpp.

  • =user-defined-reductions: Experimental extension that allows user-defined reductions. See more details.

  • =non-uniform-groups: Experimental extension that allows use of non-uniform groups. See more details.

  • =device_global: Experimental extension that allows device scoped memory allocations into SYCL that can be accessed within a kernel using syntax similar to C++ global variables. See more details.

  • =all: Enable all experimental extensions listed in this option.