Alphabetical Option List#

The following table lists SYCLomatic command line options in alphabetical order.

Option

Description

--always-use-async-handler

Use async exception handler when creating new sycl::queue with dpct::create_queue in addition to default dpct::get_default_queue. Default: off.

--analysis-mode

Only generate a report for porting effort. Default: off.

--analysis-mode-output-file

Specify the file where the analysis mode report is saved. Default: Output to stdout.

--analysis-scope-path=<dir>

The directory path for the analysis scope of the source tree that needs to be migrated. Default: the value of --in-root.

--assume-nd-range-dim=<value>

Provide a hint to the tool on the dimensionality of nd_range to use in generated code. The values are:

  • =1: Generate kernel code assuming 1D nd_range where possible, and 3D in other cases.

  • =3: Generate kernel code assuming 3D nd_range (default).

--build-script-file=<file>

Specify the name of generated makefile for migrated file(s). Default name: Makefile.dpct.

--change-cuda-files-extension-only

Limit extension change to .cu and .cuh files only. Default: off.

--check-unicode-security

Enable detection and warnings about Unicode constructs that can be exploited by using bi-directional formatting codes and homoglyphs in identifiers. Default: off.

--comments

Insert comments explaining the generated code. Default: off.

--compilation-database=<dir>

The directory path for the compilation database (compile_commands.json) for the files to be migrated. Paths and build options described in the project file are used to guide the migration.

When no path is specified, a search for compile_commands.json is attempted through all parent directories of the first input source file.

Same as -p.

--cuda-include-path=<dir>

The directory path of the CUDA* header files.

--enable-codepin

EXPERIMENTAL: Generate instrumented CUDA and SYCL code for debug and verification purposes in the directory <dir>_codepin_cuda and <dir>_codepin_sycl, where <dir> is specified by --out-root option.

--enable-ctad

Use a C++17 class template argument deduction (CTAD) in your generated code.

--enable-profiling

Enable SYCL* queue profiling in helper functions. Default: auto (when set to auto, the enable-profiling option will only be used if the tool deduces that profiling is required during migration).

--extra-arg=<string>

Specify additional arguments to append to the migration command line. The option accepts a comma-separated list of extra arguments and may be used multiple times in a command. For example:

dpct xx.cu --extra-arg="-I /path, -I /path2" --extra-arg="-I /path/to/header"

Use the dpct -- -help command to find options that can be passed as extra arguments for the migration command.

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

--gen-build-script

Generate makefile for migrated file(s) in -out-root directory. Default: off.

--gen-helper-function

Generate helper function files in the --out-root directory. Default: off.

--help

Display available options.

--helper-function-dir

Print the installation directory for helper function header files.

--helper-function-preference=<value>

The preference of helper function usage in migration. Value:

  • =no-queue-device: Call SYCL API to get queue and device instead of calling helper function.

--intercept-build

Intercept build tool to generate a compilation database.

--in-root=<dir>

The directory path for the root of the source tree that needs to be migrated. Only files under this root are migrated. Default:

  • The current directory, if the input source files are not provided.

  • The directory of the first input source file, if the input source files are provided.

Details:

  • Any source within the directory specified by --in-root (at any nesting level) may be migrated.

  • Any header file within the directory specified by --in-root (at any nesting level) that is included by the source or header file which is being migrated, is also migrated.

  • Files from outside the --in-root directory will not be migrated even if they are included by any of the program source files.

--in-root-exclude=<dir|file>

Exclude the specified directory or file from processing.

--keep-original-code

Keep the original code in the comments of generated SYCL files. Default: off.

--migrate-build-script=<value>

EXPERIMENTAL: Migrate build script(s).

  • =CMake: Migrate the CMake file(s).

--migrate-build-script-only

EXPERIMENTAL: Only migrate the build script(s). Default: off.

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

--no-dry-pattern

Do not use a Don’t Repeat Yourself (DRY) pattern when functions from the dpct namespace are inserted. Default: off.

--no-incremental-migration

Tell the tool to not perform an incremental migration. Default: off (incremental migration happens).

--optimize-migration

Generate SYCL code applying more aggressive assumptions that potentially may alter the semantics of your program. Default: off.

--out-root=<dir>

The directory path for root of generated files. A directory is created if it does not exist. Default: dpct_output.

The relative paths for the generated files are maintained. By default, file extensions are changed as follows:

  • *.cu → *.dp.cpp

  • *.cpp → *.cpp.dp.cpp

  • *.cc → *.cc.dp.cpp

  • *.cxx → *.cxx.dp.cpp

  • *.C → *.C.dp.cpp

  • *.cuh → *.dp.hpp

  • *.h *.hpp *.hxx → extensions are kept the same

To limit file extension changes to .cu and .cuh files only, use the --change-cuda-files-extension-only option.

--output-file=<file>

Redirect the stdout/stderr output to <file> in the output directory specified by the --out-root option.

--output-verbosity=<value>

Set the output verbosity level:

  • =detailed: ‘normal’ and messages about which file is being processed.

  • =diagnostics: ‘detailed’ and information about the detected conflicts and crashes (default).

  • =normal: ‘silent’ and warnings, errors, and notes from SYCLomatic.

  • =silent: Only messages from clang.

-p

Alias for --compilation-database.

--process-all

Migrate or copy all files, except hidden, from the --in-root directory to the --out-root directory. The --in-root option should be explicitly specified. Default: off.

Details:

If --process-all and --in-root options are specified, but no input files are provided, the tool migrates or copies all files, except hidden, from the --in-root directory to the output directory.

  • If there is a compilation database:

    • Files from the compilation database are migrated with the options specified in the compilation database

    • Files with the .cu extension that are not listed in the compilation database are migrated as standalone

    • Remaining files are copied to the –out-root directory

  • If there is no compilation database:

    • Files with the .cu extension are migrated as standalone

    • Remaining files are copied to the -out-root directory

--process-all is ignored if input files are provided on the command line.

-query-api-mapping=<api>

Query functionally-compatible SYCL API to migrate CUDA API.

--report-file-prefix=<prefix>

Specify the prefix for the migration report file names. The full file name will have a suffix derived from the report-type, and an extension derived from the report-format. For example: <prefix>.apis.csv or <prefix>.stats.log. If this option is not specified, the report goes to stdout. The report files are created in the directory, specified by -out-root.

--report-format=<value>

Specify the format of the reports:

  • =csv: Output will be lines of comma-separated values. The report file name extension will .csv (default).

  • =formatted: Output will be formatted for easier readability. Report file name extension will be log.

--report-only

Generate migration reports only. No SYCL code will be generated. Default: off.

--report-type=<value>

Specify the type of migration report. Values are:

  • =all: All of the migration reports.

  • =apis: Information about API signatures that need migration and the number of times they were encountered. The report file name has the .apis suffix added.

  • =stats: High level migration statistics: Lines Of Code (LOC) that are migrated to SYCL, LOC migrated to SYCL with helper functions, LOC not needing migration, LOC needing migration but are not migrated. The report file name has the .stats suffix added (default).

--rule-file=<file>

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

--stop-on-parse-err

Stop migration and generation of reports if parsing errors happened. Default: off.

--suppress-warnings=<value>

A comma-separated list of migration warnings to suppress. Valid warning IDs range from 1000 to 1132. Hyphen-separated ranges are also allowed. For example: -suppress-warnings=1000-1010,1011.

--suppress-warnings-all

Suppress all migration warnings. Default: off.

--sycl-file-extension=<value>

Specify the extension of migrated source file(s). The values are:

  • =dp-cpp: Use extension ‘.dp.cpp’ and ‘.dp.hpp’ (default).

  • =sycl-cpp: Use extension ‘.sycl.cpp’ and ‘.sycl.hpp’.

  • =cpp: Use extension ‘.cpp’ and ‘.hpp’.

--sycl-named-lambda

Generate kernels with the kernel name. Default: off.

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

--use-explicit-namespace=<value>

Define the namespaces to use explicitly in generated code. The value is a comma-separated list. Default: dpct/syclcompat, sycl.

Possible values are:

  • =dpct: Generate code with dpct:: namespace.

  • =syclcompat: Generate code with syclcompat:: namespace.

  • =none: Generate code without any namespaces. Cannot be used with other values.

  • =sycl: Generate code with sycl:: namespace. Cannot be used with cl or sycl-math values.

  • =sycl-math: Generate code with sycl:: namespace, applied only for SYCL math functions. Cannot be used with cl or sycl values.

--use-syclcompat

Use SYCLcompat header-only library (syclcompat:: namespace) to assist the migration of input source code. Default: off.

--usm-level=<value>

Set the Unified Shared Memory (USM) level to use in source code generation:

  • =none: Uses helper functions from SYCLomatic header files for memory management migration.

  • =restricted: Uses USM API for memory management migration. (default).

--vcxprojfile=<file>

The directory path for the C++ project file vcxproj of the Visual Studio project to migrate. Paths and build options described in the project file are used to guide the migration.

--version

Show the version of the tool.