diff --git a/clang/test/dpct/help_option_check/help_advanced.txt b/clang/test/dpct/help_option_check/help_advanced.txt new file mode 100644 index 000000000000..0aca8449d71f --- /dev/null +++ b/clang/test/dpct/help_option_check/help_advanced.txt @@ -0,0 +1,71 @@ +USAGE: dpct [options] [ ... ] + +OPTIONS: Advanced +Advanced DPCT options + + --format-range= - 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= - Set the formatting style. + The values are: + =custom - Use the coding style defined in the .clang-format file (default). + =llvm - Use the LLVM coding style. + =google - Use the Google coding style. + --migrate-build-script= - EXPERIMENTAL: A comma-separated list of build script type(s) to be migrated. + By default, no build script is migrated. + The values are: + =CMake - Migrate the CMake file(s). + =Python - Migrate the python build script file(s) of PyTorch based project. + --no-dpcpp-extensions= - 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. + =device_info - Disable the Intel extensions for device information, if supported by the compiler and the backend. + =enqueued_barriers - Disable the enqueued barriers extension. + =peer_access - Disable the peer access extension. + =assert - Disable the assert extension. + =queue_empty - Disable the queue empty extension. + =all - Disable all extensions listed in this option. + --rule-file= - Specify the rule file path that contains rules used for migration. + --use-dpcpp-extensions= - 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(R) 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. + =intel_device_math - Use sycl::ext::intel::math functions from the libdevice library (provided by Intel(R) oneAPI + DPC++/C++ Compiler) to migrate functions which have no mapping in the SYCL standard. + =all - Enable all DPC++ extensions listed in this option. + --use-experimental-features= - 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: + =free-function-queries - Experimental extension that allows getting 'id', 'item', 'nd_item', 'group', and + 'sub_group' instances globally. + =local-memory-kernel-scope-allocation - Experimental extension that allows allocation of local memory objects at the kernel + functor scope + =logical-group - Experimental helper function used to logically group work-items. + =root-group - Experimental extension that allows use of root group class and relative API. + =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. + =user-defined-reductions - Experimental extension that allows user-defined reductions. + =masked-sub-group-operation - Experimental helper function used to execute sub-group operation with mask. + =dpl-experimental-api - Experimental extension that allows use of experimental oneDPL APIs. + =occupancy-calculation - Experimental helper function used to calculate occupancy. + =matrix - Experimental extension that allows use of matrix extension like class joint_matrix. + =bfloat16_math_functions - Experimental extension that allows use of bfloat16 math functions. + =bindless_images - Experimental extension that allows use of bindless images APIs. + =graph - Experimental extension that allows use of SYCL Graph APIs. + =non-uniform-groups - Experimental extension that allows use of non-uniform groups. + =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. + =virtual_mem - Experimental extension that allows map an address range onto multiple allocations of physical memory. + =in_order_queue_events - Experimental extension that allows get the event from the last command submission into the queue and set an external event as an implicit dependence on the next command submitted to the queue. + =non-stdandard-sycl-builtins - Experimental extension that allows to use non standard SYCL builtin functions. + =prefetch - Experimental extension that allows use of SYCL prefetch APIs. + =all - Enable all experimental extensions listed in this option. + + ... Paths of input source files. These paths are looked up in the compilation database. + +See Diagnostics Reference to resolve warnings and complete the migration: +https://oneapi-src.github.io/SYCLomatic/dev_guide/reference/diagnostics-reference.html diff --git a/clang/test/dpct/help_option_check/help_advanced_win.txt b/clang/test/dpct/help_option_check/help_advanced_win.txt new file mode 100644 index 000000000000..d6149e2df537 --- /dev/null +++ b/clang/test/dpct/help_option_check/help_advanced_win.txt @@ -0,0 +1,71 @@ +USAGE: dpct.exe [options] [ ... ] + +OPTIONS: Advanced +Advanced DPCT options + + --format-range= - 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= - Set the formatting style. + The values are: + =custom - Use the coding style defined in the .clang-format file (default). + =llvm - Use the LLVM coding style. + =google - Use the Google coding style. + --migrate-build-script= - EXPERIMENTAL: A comma-separated list of build script type(s) to be migrated. + By default, no build script is migrated. + The values are: + =CMake - Migrate the CMake file(s). + =Python - Migrate the python build script file(s) of PyTorch based project. + --no-dpcpp-extensions= - 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. + =device_info - Disable the Intel extensions for device information, if supported by the compiler and the backend. + =enqueued_barriers - Disable the enqueued barriers extension. + =peer_access - Disable the peer access extension. + =assert - Disable the assert extension. + =queue_empty - Disable the queue empty extension. + =all - Disable all extensions listed in this option. + --rule-file= - Specify the rule file path that contains rules used for migration. + --use-dpcpp-extensions= - 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(R) 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. + =intel_device_math - Use sycl::ext::intel::math functions from the libdevice library (provided by Intel(R) oneAPI + DPC++/C++ Compiler) to migrate functions which have no mapping in the SYCL standard. + =all - Enable all DPC++ extensions listed in this option. + --use-experimental-features= - 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: + =free-function-queries - Experimental extension that allows getting 'id', 'item', 'nd_item', 'group', and + 'sub_group' instances globally. + =local-memory-kernel-scope-allocation - Experimental extension that allows allocation of local memory objects at the kernel + functor scope + =logical-group - Experimental helper function used to logically group work-items. + =root-group - Experimental extension that allows use of root group class and relative API. + =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. + =user-defined-reductions - Experimental extension that allows user-defined reductions. + =masked-sub-group-operation - Experimental helper function used to execute sub-group operation with mask. + =dpl-experimental-api - Experimental extension that allows use of experimental oneDPL APIs. + =occupancy-calculation - Experimental helper function used to calculate occupancy. + =matrix - Experimental extension that allows use of matrix extension like class joint_matrix. + =bfloat16_math_functions - Experimental extension that allows use of bfloat16 math functions. + =bindless_images - Experimental extension that allows use of bindless images APIs. + =graph - Experimental extension that allows use of SYCL Graph APIs. + =non-uniform-groups - Experimental extension that allows use of non-uniform groups. + =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. + =virtual_mem - Experimental extension that allows map an address range onto multiple allocations of physical memory. + =in_order_queue_events - Experimental extension that allows get the event from the last command submission into the queue and set an external event as an implicit dependence on the next command submitted to the queue. + =non-stdandard-sycl-builtins - Experimental extension that allows to use non standard SYCL builtin functions. + =prefetch - Experimental extension that allows use of SYCL prefetch APIs. + =all - Enable all experimental extensions listed in this option. + + ... Paths of input source files. These paths are looked up in the compilation database. + +See Diagnostics Reference to resolve warnings and complete the migration: +https://oneapi-src.github.io/SYCLomatic/dev_guide/reference/diagnostics-reference.html diff --git a/clang/test/dpct/help_option_check/help_all.txt b/clang/test/dpct/help_option_check/help_all.txt new file mode 100644 index 000000000000..c60519abf06a --- /dev/null +++ b/clang/test/dpct/help_option_check/help_all.txt @@ -0,0 +1,246 @@ +USAGE: dpct [options] [ ... ] + +OPTIONS: +All DPCT options + + --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= - 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= - 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= - 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. + --codepin-report - Call codepin-report.py to generate CodePin report by parsing execution log files generated by instrumented CUDA and SYCL code. + --comments - Insert comments explaining the generated code. Default: off. + --compilation-database= - 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= - 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 _codepin_cuda and _codepin_sycl, where is specified by --out-root option. + --enable-ctad - Use a C++17 class template argument deduction (CTAD) in your generated code. + Default: off. + --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= - Additional argument to append to the migration command line, example: + --extra-arg="-I /path/to/header". The options that can be passed this way can + be found with the dpct -- -help command. + --format-range= - 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= - Set the formatting style. + The values are: + =custom - Use the coding style defined in the .clang-format file (default). + =llvm - Use the LLVM coding style. + =google - Use the Google coding style. + --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. + --help= - Display available options. + =basic - List options for basic migration. + =advanced - List options for advanced migration. + =code-gen - List options to customize how code is migrated. + =report-gen - List option(s) to control report generation during migration. + =build-script - List options to migrate build script(s). + =query-api - List options to query API mapping support. + =warnings - List options to manage warnings generated by the tool. + =help-info - List options to display tool information. + =intercept-build - List options of intercept-build tool. + =examples - List examples of common DPCT options usage. + --helper-function-dir - Print the installation directory for helper function header files. + --helper-function-preference= - The preference of helper function usage in migration. + =no-queue-device - Call SYCL API to get queue and device instead of calling helper function. + --in-root= - The directory path for the root of the source tree that needs to be migrated. + Only files under this root are migrated. Default: Current directory, if input + source files are not provided. If input source files are provided, the directory + of the first input source file is used. + --in-root-exclude= - Exclude the specified directory or file from processing. + --intercept-build - Intercept build tool to generate a compilation database. + --keep-original-code - Keep the original code in comments of generated SYCL files. Default: off. + --migrate-build-script= - EXPERIMENTAL: A comma-separated list of build script type(s) to be migrated. + By default, no build script is migrated. + The values are: + =CMake - Migrate the CMake file(s). + =Python - Migrate the python build script file(s) of PyTorch based project. + --migrate-build-script-only - EXPERIMENTAL: Only migrate the build script(s). Default: off. + --no-dpcpp-extensions= - 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. + =device_info - Disable the Intel extensions for device information, if supported by the compiler and the backend. + =enqueued_barriers - Disable the enqueued barriers extension. + =peer_access - Disable the peer access extension. + =assert - Disable the assert extension. + =queue_empty - Disable the queue empty extension. + =all - Disable all extensions listed in this option. + --no-dry-pattern - Do not use DRY (do not repeat yourself) pattern when functions from 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= - The directory path for root of generated files. A directory is created if it + does not exist. Default: dpct_output. + --output-file= - Redirect the stdout/stderr output to in the output directory specified + by the --out-root option. + --output-verbosity= - 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 dpct. + =silent - Only messages from clang. + -p - Alias for --compilation-database. + --process-all - Migrate or copies all files, except hidden, from the --in-root directory + to the --out-root directory. The --in-root option should be explicitly specified. + Default: off. + --query-api-mapping= - Query functionally compatible SYCL API to migrate CUDA API. + --report-file-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: .apis.csv or .stats.log. If this option is not + specified, the report will go to stdout. The report files are created in the + directory, specified by -out-root. + --report-format= - Specify the format of the migration reports: + =csv - Output will be lines of comma-separated values. The report file name extension will + be .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= - 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 will have .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= - 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= - A comma separated list of migration warnings to suppress. Valid warning IDs range + from 1000 to 1135. 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= - 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= - 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(R) 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. + =intel_device_math - Use sycl::ext::intel::math functions from the libdevice library (provided by Intel(R) oneAPI + DPC++/C++ Compiler) to migrate functions which have no mapping in the SYCL standard. + =all - Enable all DPC++ extensions listed in this option. + --use-experimental-features= - 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: + =free-function-queries - Experimental extension that allows getting 'id', 'item', 'nd_item', 'group', and + 'sub_group' instances globally. + =local-memory-kernel-scope-allocation - Experimental extension that allows allocation of local memory objects at the kernel + functor scope + =logical-group - Experimental helper function used to logically group work-items. + =root-group - Experimental extension that allows use of root group class and relative API. + =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. + =user-defined-reductions - Experimental extension that allows user-defined reductions. + =masked-sub-group-operation - Experimental helper function used to execute sub-group operation with mask. + =dpl-experimental-api - Experimental extension that allows use of experimental oneDPL APIs. + =occupancy-calculation - Experimental helper function used to calculate occupancy. + =matrix - Experimental extension that allows use of matrix extension like class joint_matrix. + =bfloat16_math_functions - Experimental extension that allows use of bfloat16 math functions. + =bindless_images - Experimental extension that allows use of bindless images APIs. + =graph - Experimental extension that allows use of SYCL Graph APIs. + =non-uniform-groups - Experimental extension that allows use of non-uniform groups. + =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. + =virtual_mem - Experimental extension that allows map an address range onto multiple allocations of physical memory. + =in_order_queue_events - Experimental extension that allows get the event from the last command submission into the queue and set an external event as an implicit dependence on the next command submitted to the queue. + =non-stdandard-sycl-builtins - Experimental extension that allows to use non standard SYCL builtin functions. + =prefetch - Experimental extension that allows use of SYCL prefetch APIs. + =all - Enable all experimental extensions listed in this option. + --use-explicit-namespace= - Define the namespaces to use explicitly in generated code. The is a comma + separated list. Default: dpct/syclcompat, sycl. + Possible values are: + =dpct - Generate code with dpct:: 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. + =syclcompat - Generate code with syclcompat:: namespace. + --use-syclcompat - Use SYCLcompat header-only library (syclcompat:: namespace) to assist the migration of input source code. + Default: off. + --usm-level= - Set the Unified Shared Memory (USM) level to use in source code generation. + =none - Uses helper functions from DPCT header files for memory management migration. + =restricted - Uses USM API for memory management migration. (default) + --version - Show the version of the tool. + + ... Paths of input source files. These paths are looked up in the compilation database. + +EXAMPLES: + + Prepare for Migration + ===================== + + Generate a compilation database of the project files used to guide migration + $ dpct --intercept-build make + $ dpct --intercept-build --parse-build-log + + Migrate src code with SYCLcompat header-only library (syclcompat:: namespace) + $ dpct --use-syclcompat source.cu + + Migrate your code + ================= + + Migrate a single source file + $ dpct source.cu + $ dpct --keep-original-code source.cu # Keep original code + $ dpct --cuda-include-path=/path/to/cuda/include source.cu # Specify the path to CUDA headers + $ dpct --extra-arg="-std=c++11" source.cu # With extra options + $ dpct --extra-arg="-I /path/to/extra/include" source.cu # With additional app args + $ dpct -p=/path/to/compilation-database source.cu # With compilation database + $ dpct --gen-build-script source.cu # Migrate src code and generate Makefile script + + Migrate an entire project + $ dpct -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # With compilation database + $ dpct --process-all --in-root=/path/to/project --out-root=/path/to/migrated-project # Without compilation database + $ dpct -in-root=/path/to/project --in-root-exclude=/path/to/project/dir1 # Exclude migration of a dir or file + + Migrate/generate build scripts for migrated SYCL code + $ dpct --migrate-build-script=CMake -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # Migrate src code and CMake scripts + $ dpct --migrate-build-script-only -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # Migrate build script only + $ dpct --gen-build-script -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # Migrate src code and generate Makefile script + + Utils to assist migration + ========================= + + Estimate the migration efforts to complete a migration + $ dpct --analysis-mode source.cu --analysis-mode-output-file= + + Query functionally compatible SYCL API for a CUDA API + $ dpct --query-api-mapping=cudaMalloc + + Generate instrumented CUDA and SYCL code and CodePin summary report for debugging + $ dpct --enable-codepin source.cu + $ dpct --codepin-report --instrumented-cuda-log cuda.json --instrumented-sycl-log sycl.json # cuda.json and sycl.json are generated by running instrumented CUDA and SYCL code + + Generate helper function files in the out-root directory + $ dpct --gen-helper-function + + Display the folder of helper function files + $ dpct --helper-function-dir + +See Diagnostics Reference to resolve warnings and complete the migration: +https://oneapi-src.github.io/SYCLomatic/dev_guide/reference/diagnostics-reference.html diff --git a/clang/test/dpct/help_option_check/help_all_win.txt b/clang/test/dpct/help_option_check/help_all_win.txt new file mode 100644 index 000000000000..5c173b64ef61 --- /dev/null +++ b/clang/test/dpct/help_option_check/help_all_win.txt @@ -0,0 +1,248 @@ +USAGE: dpct.exe [options] [ ... ] + +OPTIONS: +All DPCT options + + --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= - 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= - 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= - 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. + --codepin-report - Call codepin-report.py to generate CodePin report by parsing execution log files generated by instrumented CUDA and SYCL code. + --comments - Insert comments explaining the generated code. Default: off. + --compilation-database= - 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= - 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 _codepin_cuda and _codepin_sycl, where is specified by --out-root option. + --enable-ctad - Use a C++17 class template argument deduction (CTAD) in your generated code. + Default: off. + --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= - Additional argument to append to the migration command line, example: + --extra-arg="-I /path/to/header". The options that can be passed this way can + be found with the dpct -- -help command. + --format-range= - 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= - Set the formatting style. + The values are: + =custom - Use the coding style defined in the .clang-format file (default). + =llvm - Use the LLVM coding style. + =google - Use the Google coding style. + --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. + --help= - Display available options. + =basic - List options for basic migration. + =advanced - List options for advanced migration. + =code-gen - List options to customize how code is migrated. + =report-gen - List option(s) to control report generation during migration. + =build-script - List options to migrate build script(s). + =query-api - List options to query API mapping support. + =warnings - List options to manage warnings generated by the tool. + =help-info - List options to display tool information. + =intercept-build - List options of intercept-build tool. + =examples - List examples of common DPCT options usage. + --helper-function-dir - Print the installation directory for helper function header files. + --helper-function-preference= - The preference of helper function usage in migration. + =no-queue-device - Call SYCL API to get queue and device instead of calling helper function. + --in-root= - The directory path for the root of the source tree that needs to be migrated. + Only files under this root are migrated. Default: Current directory, if input + source files are not provided. If input source files are provided, the directory + of the first input source file is used. + --in-root-exclude= - Exclude the specified directory or file from processing. + --keep-original-code - Keep the original code in comments of generated SYCL files. Default: off. + --migrate-build-script= - EXPERIMENTAL: A comma-separated list of build script type(s) to be migrated. + By default, no build script is migrated. + The values are: + =CMake - Migrate the CMake file(s). + =Python - Migrate the python build script file(s) of PyTorch based project. + --migrate-build-script-only - EXPERIMENTAL: Only migrate the build script(s). Default: off. + --no-dpcpp-extensions= - 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. + =device_info - Disable the Intel extensions for device information, if supported by the compiler and the backend. + =enqueued_barriers - Disable the enqueued barriers extension. + =peer_access - Disable the peer access extension. + =assert - Disable the assert extension. + =queue_empty - Disable the queue empty extension. + =all - Disable all extensions listed in this option. + --no-dry-pattern - Do not use DRY (do not repeat yourself) pattern when functions from 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= - The directory path for root of generated files. A directory is created if it + does not exist. Default: dpct_output. + --output-file= - Redirect the stdout/stderr output to in the output directory specified + by the --out-root option. + --output-verbosity= - 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 dpct. + =silent - Only messages from clang. + -p - Alias for --compilation-database. + --process-all - Migrate or copies all files, except hidden, from the --in-root directory + to the --out-root directory. The --in-root option should be explicitly specified. + Default: off. + --query-api-mapping= - Query functionally compatible SYCL API to migrate CUDA API. + --report-file-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: .apis.csv or .stats.log. If this option is not + specified, the report will go to stdout. The report files are created in the + directory, specified by -out-root. + --report-format= - Specify the format of the migration reports: + =csv - Output will be lines of comma-separated values. The report file name extension will + be .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= - 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 will have .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= - 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= - A comma separated list of migration warnings to suppress. Valid warning IDs range + from 1000 to 1135. 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= - 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= - 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(R) 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. + =intel_device_math - Use sycl::ext::intel::math functions from the libdevice library (provided by Intel(R) oneAPI + DPC++/C++ Compiler) to migrate functions which have no mapping in the SYCL standard. + =all - Enable all DPC++ extensions listed in this option. + --use-experimental-features= - 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: + =free-function-queries - Experimental extension that allows getting 'id', 'item', 'nd_item', 'group', and + 'sub_group' instances globally. + =local-memory-kernel-scope-allocation - Experimental extension that allows allocation of local memory objects at the kernel + functor scope + =logical-group - Experimental helper function used to logically group work-items. + =root-group - Experimental extension that allows use of root group class and relative API. + =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. + =user-defined-reductions - Experimental extension that allows user-defined reductions. + =masked-sub-group-operation - Experimental helper function used to execute sub-group operation with mask. + =dpl-experimental-api - Experimental extension that allows use of experimental oneDPL APIs. + =occupancy-calculation - Experimental helper function used to calculate occupancy. + =matrix - Experimental extension that allows use of matrix extension like class joint_matrix. + =bfloat16_math_functions - Experimental extension that allows use of bfloat16 math functions. + =bindless_images - Experimental extension that allows use of bindless images APIs. + =graph - Experimental extension that allows use of SYCL Graph APIs. + =non-uniform-groups - Experimental extension that allows use of non-uniform groups. + =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. + =virtual_mem - Experimental extension that allows map an address range onto multiple allocations of physical memory. + =in_order_queue_events - Experimental extension that allows get the event from the last command submission into the queue and set an external event as an implicit dependence on the next command submitted to the queue. + =non-stdandard-sycl-builtins - Experimental extension that allows to use non standard SYCL builtin functions. + =prefetch - Experimental extension that allows use of SYCL prefetch APIs. + =all - Enable all experimental extensions listed in this option. + --use-explicit-namespace= - Define the namespaces to use explicitly in generated code. The is a comma + separated list. Default: dpct/syclcompat, sycl. + Possible values are: + =dpct - Generate code with dpct:: 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. + =syclcompat - Generate code with syclcompat:: namespace. + --use-syclcompat - Use SYCLcompat header-only library (syclcompat:: namespace) to assist the migration of input source code. + Default: off. + --usm-level= - Set the Unified Shared Memory (USM) level to use in source code generation. + =none - Uses helper functions from DPCT header files for memory management migration. + =restricted - Uses USM API for memory management migration. (default) + --vcxprojfile= - 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. + + ... Paths of input source files. These paths are looked up in the compilation database. + +EXAMPLES: + + Prepare for Migration + ===================== + + Generate a compilation database of the project files used to guide migration + $ dpct --intercept-build --parse-build-log + + Migrate src code with SYCLcompat header-only library (syclcompat:: namespace) + $ dpct --use-syclcompat source.cu + + Migrate your code + ================= + + Migrate a single source file + $ dpct source.cu + $ dpct --keep-original-code source.cu # Keep original code + $ dpct --cuda-include-path=/path/to/cuda/include source.cu # Specify the path to CUDA headers + $ dpct --extra-arg="-std=c++11" source.cu # With extra options + $ dpct --extra-arg="-I /path/to/extra/include" source.cu # With additional app args + $ dpct -p=/path/to/compilation-database source.cu # With compilation database + $ dpct --gen-build-script source.cu # Migrate src code and generate Makefile script + + Migrate an entire project + $ dpct -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # With compilation database + $ dpct --process-all --in-root=/path/to/project --out-root=/path/to/migrated-project # Without compilation database + $ dpct -vcxprojfile=/path/to/vcproject/file --in-root=/path/to/project --out-root=/path/to/migrated-project # With VS project file + $ dpct -in-root=/path/to/project --in-root-exclude=/path/to/project/dir1 # Exclude migration of a dir or file + + Migrate/generate build scripts for migrated SYCL code + $ dpct --migrate-build-script=CMake -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # Migrate src code and CMake scripts + $ dpct --migrate-build-script-only -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # Migrate build script only + $ dpct --gen-build-script -p=/path/to/compilation-database --in-root=/path/to/project --out-root=/path/to/migrated-project # Migrate src code and generate Makefile script + + Utils to assist migration + ========================= + + Estimate the migration efforts to complete a migration + $ dpct --analysis-mode source.cu --analysis-mode-output-file= + + Query functionally compatible SYCL API for a CUDA API + $ dpct --query-api-mapping=cudaMalloc + + Generate instrumented CUDA and SYCL code and CodePin summary report for debugging + $ dpct --enable-codepin source.cu + $ dpct --codepin-report --instrumented-cuda-log cuda.json --instrumented-sycl-log sycl.json # cuda.json and sycl.json are generated by running instrumented CUDA and SYCL code + + Generate helper function files in the out-root directory + $ dpct --gen-helper-function + + Display the folder of helper function files + $ dpct --helper-function-dir + +See Diagnostics Reference to resolve warnings and complete the migration: +https://oneapi-src.github.io/SYCLomatic/dev_guide/reference/diagnostics-reference.html diff --git a/clang/test/dpct/help_option_check/help_basic.txt b/clang/test/dpct/help_option_check/help_basic.txt new file mode 100644 index 000000000000..a563ca6d9d1a --- /dev/null +++ b/clang/test/dpct/help_option_check/help_basic.txt @@ -0,0 +1,27 @@ +USAGE: dpct [options] [ ... ] + +OPTIONS: Basic +Basic DPCT options + + --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= - The directory path for the analysis scope of the source tree that needs to be migrated. + Default: the value of --in-root. + --cuda-include-path= - The directory path of the CUDA header files. + --in-root= - The directory path for the root of the source tree that needs to be migrated. + Only files under this root are migrated. Default: Current directory, if input + source files are not provided. If input source files are provided, the directory + of the first input source file is used. + --in-root-exclude= - Exclude the specified directory or file from processing. + --migrate-build-script-only - EXPERIMENTAL: Only migrate the build script(s). Default: off. + --out-root= - The directory path for root of generated files. A directory is created if it + does not exist. Default: dpct_output. + --process-all - Migrate or copies all files, except hidden, from the --in-root directory + to the --out-root directory. The --in-root option should be explicitly specified. + Default: off. + --stop-on-parse-err - Stop migration and generation of reports if parsing errors happened. Default: off. + + ... Paths of input source files. These paths are looked up in the compilation database. + +See Diagnostics Reference to resolve warnings and complete the migration: +https://oneapi-src.github.io/SYCLomatic/dev_guide/reference/diagnostics-reference.html diff --git a/clang/test/dpct/help_option_check/help_basic_win.txt b/clang/test/dpct/help_option_check/help_basic_win.txt new file mode 100644 index 000000000000..7d8d78d8ca55 --- /dev/null +++ b/clang/test/dpct/help_option_check/help_basic_win.txt @@ -0,0 +1,27 @@ +USAGE: dpct.exe [options] [ ... ] + +OPTIONS: Basic +Basic DPCT options + + --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= - The directory path for the analysis scope of the source tree that needs to be migrated. + Default: the value of --in-root. + --cuda-include-path= - The directory path of the CUDA header files. + --in-root= - The directory path for the root of the source tree that needs to be migrated. + Only files under this root are migrated. Default: Current directory, if input + source files are not provided. If input source files are provided, the directory + of the first input source file is used. + --in-root-exclude= - Exclude the specified directory or file from processing. + --migrate-build-script-only - EXPERIMENTAL: Only migrate the build script(s). Default: off. + --out-root= - The directory path for root of generated files. A directory is created if it + does not exist. Default: dpct_output. + --process-all - Migrate or copies all files, except hidden, from the --in-root directory + to the --out-root directory. The --in-root option should be explicitly specified. + Default: off. + --stop-on-parse-err - Stop migration and generation of reports if parsing errors happened. Default: off. + + ... Paths of input source files. These paths are looked up in the compilation database. + +See Diagnostics Reference to resolve warnings and complete the migration: +https://oneapi-src.github.io/SYCLomatic/dev_guide/reference/diagnostics-reference.html diff --git a/clang/test/dpct/help_option_check/help_option_check_lin.cpp b/clang/test/dpct/help_option_check/help_option_check_lin.cpp new file mode 100644 index 000000000000..a381080c0e28 --- /dev/null +++ b/clang/test/dpct/help_option_check/help_option_check_lin.cpp @@ -0,0 +1,17 @@ +// REQUIRES: system-linux + +// RUN: rm -rf %T/help_option_check && mkdir -p %T/help_option_check +// RUN: cd %T/help_option_check + +// RUN: echo "begin" > %T/diff.txt +// RUN: dpct --help > output.txt +// RUN: diff --strip-trailing-cr %S/help_all.txt %T/help_option_check/output.txt >> %T/diff.txt +// RUN: dpct --help=basic > output.txt +// RUN: diff --strip-trailing-cr %S/help_basic.txt %T/help_option_check/output.txt >> %T/diff.txt +// RUN: dpct --help=advanced > output.txt +// RUN: diff --strip-trailing-cr %S/help_advanced.txt %T/help_option_check/output.txt >> %T/diff.txt +// RUN: echo "end" >> %T/diff.txt + +// RUN: cat %T/diff.txt | FileCheck %s +// CHECK: begin +// CHECK-NEXT: end diff --git a/clang/test/dpct/help_option_check/help_option_check_win.cpp b/clang/test/dpct/help_option_check/help_option_check_win.cpp new file mode 100644 index 000000000000..a82a6b394def --- /dev/null +++ b/clang/test/dpct/help_option_check/help_option_check_win.cpp @@ -0,0 +1,17 @@ +// REQUIRES: system-windows + +// RUN: rm -rf %T/help_option_check && mkdir -p %T/help_option_check +// RUN: cd %T/help_option_check + +// RUN: echo "begin" > %T/diff.txt +// RUN: dpct --help > output.txt +// RUN: diff --strip-trailing-cr %S/help_all_win.txt %T/help_option_check/output.txt >> %T/diff.txt +// RUN: dpct --help=basic > output.txt +// RUN: diff --strip-trailing-cr %S/help_basic_win.txt %T/help_option_check/output.txt >> %T/diff.txt +// RUN: dpct --help=advanced > output.txt +// RUN: diff --strip-trailing-cr %S/help_advanced_win.txt %T/help_option_check/output.txt >> %T/diff.txt +// RUN: echo "end" >> %T/diff.txt + +// RUN: cat %T/diff.txt | FileCheck %s +// CHECK: begin +// CHECK-NEXT: end