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 for migration. Also, reference the predefined rules in the extensions directory in the root folder of the tool.

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.

  • =virtual_mem: Experimental extension that allows for mapping of an address range onto multiple allocations of physical memory.

  • =in_order_queue_events: Experimental extension that allows getting the event from the last command submission into the queue and setting an external event as an implicit dependence on the next command submitted to the queue.

  • =non-standard-sycl-builtins: Experimental extension that allows use of non standard SYCL builtin functions.

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

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