diff --git a/docs/_include_files/before_begin_intro_dgr.rst b/docs/_include_files/before_begin_intro_dgr.rst index 911fefa9d572..bf2eadd88f3d 100644 --- a/docs/_include_files/before_begin_intro_dgr.rst +++ b/docs/_include_files/before_begin_intro_dgr.rst @@ -1,2 +1 @@ -Install and set up |tool_name|. Refer to :ref:`get_started` for installation -and setup information. +Refer to :ref:`get_started` for installation and setup information. diff --git a/docs/_include_files/prereq_mig_flow.rst b/docs/_include_files/prereq_mig_flow.rst new file mode 100644 index 000000000000..f258b2253303 --- /dev/null +++ b/docs/_include_files/prereq_mig_flow.rst @@ -0,0 +1,7 @@ + +* Install |tool_name|. The latest prebuild of |tool_name| is available from + https://github.com/oneapi-src/SYCLomatic/releases. + + You can also review the repo README for build and installation instructions. +* Set up the tool environment. Refer to :ref:`get_started` for setup + instructions. \ No newline at end of file diff --git a/docs/_include_files/run_migration.rst b/docs/_include_files/run_migration.rst new file mode 100644 index 000000000000..ddb7aeb037f0 --- /dev/null +++ b/docs/_include_files/run_migration.rst @@ -0,0 +1,2 @@ + +You can run the tool from the command line. \ No newline at end of file diff --git a/docs/_include_files/variables.txt b/docs/_include_files/variables.txt index 137dc414e774..0a12b5eff3ce 100644 --- a/docs/_include_files/variables.txt +++ b/docs/_include_files/variables.txt @@ -31,3 +31,29 @@ .. |dpcpp_compiler| replace:: Intel® oneAPI DPC++/C++ Compiler .. _dpcpp_compiler: https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-compiler.html +.. |oneapi_dpcpp_compiler| replace:: oneAPI DPC++ Compiler +.. _oneapi_dpcpp_compiler: https://github.com/intel/llvm + +.. |compiler_dev_guide| replace:: Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference +.. _compiler_dev_guide: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/current/overview.html + +.. |vtune| replace:: Intel® VTune™ Profiler +.. _vtune: https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler.html + +.. |advisor| replace:: Intel® Advisor +.. _advisor: https://www.intel.com/content/www/us/en/developer/tools/oneapi/advisor.html + +.. |base_kit_long| replace:: Intel® oneAPI Base Toolkit (Base Kit) +.. _base_kit_long: https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit.html + +.. |base_kit| replace:: Base Kit + +.. |convo_sep_sample| replace:: convolutionSeparable Sample +.. _convo_sep_sample: https://github.com/oneapi-src/oneAPI-samples/tree/master/DirectProgramming/C%2B%2BSYCL/guided_convolutionSeparable_SYCLmigration + +.. |conc_kern_sample| replace:: Concurrent Kernels Sample +.. _conc_kern_sample: https://github.com/oneapi-src/oneAPI-samples/tree/master/DirectProgramming/C%2B%2BSYCL/guided_concurrentKernels_SYCLMigration + +.. |sycl_forum| replace:: Migrating to SYCL forum +.. _sycl_forum: https://community.intel.com/t5/Migrating-to-SYCL/bd-p/migrating-sycl + diff --git a/docs/dev_guide/reference/api-mapping-status.rst b/docs/dev_guide/api-mapping-status.rst similarity index 100% rename from docs/dev_guide/reference/api-mapping-status.rst rename to docs/dev_guide/api-mapping-status.rst diff --git a/docs/dev_guide/reference/api-mapping-status/ASM_API_migration_status.csv b/docs/dev_guide/api-mapping-status/ASM_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/ASM_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/ASM_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/CUB_API_migration_status.csv b/docs/dev_guide/api-mapping-status/CUB_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/CUB_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/CUB_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/NCCL_API_migration_status.csv b/docs/dev_guide/api-mapping-status/NCCL_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/NCCL_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/NCCL_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/NVML_API_migration_status.csv b/docs/dev_guide/api-mapping-status/NVML_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/NVML_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/NVML_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/Runtime_and_Driver_API_migration_status.csv b/docs/dev_guide/api-mapping-status/Runtime_and_Driver_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/Runtime_and_Driver_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/Runtime_and_Driver_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/cuBLAS_API_migration_status.csv b/docs/dev_guide/api-mapping-status/cuBLAS_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/cuBLAS_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/cuBLAS_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/cuDNN_API_migration_status.csv b/docs/dev_guide/api-mapping-status/cuDNN_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/cuDNN_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/cuDNN_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/cuFFT_API_migration_status.csv b/docs/dev_guide/api-mapping-status/cuFFT_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/cuFFT_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/cuFFT_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/cuRAND_API_migration_status.csv b/docs/dev_guide/api-mapping-status/cuRAND_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/cuRAND_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/cuRAND_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/cuSOLVER_API_migration_status.csv b/docs/dev_guide/api-mapping-status/cuSOLVER_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/cuSOLVER_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/cuSOLVER_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/cuSPARSE_API_migration_status.csv b/docs/dev_guide/api-mapping-status/cuSPARSE_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/cuSPARSE_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/cuSPARSE_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/nvGRAPH_API_migration_status.csv b/docs/dev_guide/api-mapping-status/nvGRAPH_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/nvGRAPH_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/nvGRAPH_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/nvJPEG_API_migration_status.csv b/docs/dev_guide/api-mapping-status/nvJPEG_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/nvJPEG_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/nvJPEG_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/thrust_API_migration_status.csv b/docs/dev_guide/api-mapping-status/thrust_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/thrust_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/thrust_API_migration_status.csv diff --git a/docs/dev_guide/reference/api-mapping-status/wmma_API_migration_status.csv b/docs/dev_guide/api-mapping-status/wmma_API_migration_status.csv similarity index 100% rename from docs/dev_guide/reference/api-mapping-status/wmma_API_migration_status.csv rename to docs/dev_guide/api-mapping-status/wmma_API_migration_status.csv diff --git a/docs/dev_guide/migration.rst b/docs/dev_guide/migration.rst index 29bec6d92260..fd6ae720578b 100644 --- a/docs/dev_guide/migration.rst +++ b/docs/dev_guide/migration.rst @@ -3,47 +3,44 @@ Migration ========= -.. toctree:: - :hidden: - - migration/generate-compilation-db - migration/incremental-migration - migration/migration-rules - migration/API-Mapping-query-guide - +This section contains information about migration workflow, planning a migration, +and migration tool features. -|tool_name| ports CUDA\* language kernels and library API calls to -SYCL\* for the |dpcpp_compiler|_. Typically, 90%-95% of CUDA code automatically -migrates to SYCL. The tool inserts inline comments during migration to -help you complete the remaining code migration. +Migration Workflow +------------------ -**CUDA‡ to SYCL‡ Code Migration & Development Workflow** +The migration workflow guidelines describe the CUDA* to SYCL* code migration workflow, with +detailed information about how to prepare your code for migration, how to use +tool features to configure your migration, and how to build and optimize your +migrated code. -.. figure:: /_images/cuda-sycl-migration-workflow.png +Review :ref:`mig_workflow`. -The |tool_name| migration workflow follows four high-level steps: +Features to Support Migration +----------------------------- -#. **Prepare your CUDA source for migration** +|tool_name| provides multiple features to aid migration preparation and customization. - Start with a running CUDA project that can be built and run. |tool_name| - looks for CUDA headers, so make sure the headers are accessible to the tool. +* :ref:`gen_comp_db` +* :ref:`inc_mig` +* :ref:`migration_rules` +* :ref:`debug_codepin` -#. **Migrate your project** - Run |tool_name| with the original source as input to the tool to generate - annotated SYCL code. +Query CUDA to SYCL API Mapping +------------------------------ - You can use file-to-file migration for simple projects or a - :ref:`compilation database ` for more complex projects. +You can query which SYCL\* API is functionally compatible with a specified CUDA\* API. -#. **Review the converted code** +Learn how to :ref:`query_map`. - Output files contain annotations to mark code that could not be automatically - migrated. Review the annotations and manually convert any unmigrated code. - Also look for potential code improvements. - -#. **Build your project** +.. toctree:: + :hidden: - To make sure your newly migrated project compiles successfully, build the - project with the |dpcpp_compiler|_. + migration/migration-workflow + migration/generate-compilation-db + migration/incremental-migration + migration/migration-rules + migration/debug-with-codepin + migration/API-Mapping-query-guide diff --git a/docs/dev_guide/migration/API-Mapping-query-guide.rst b/docs/dev_guide/migration/API-Mapping-query-guide.rst index d057869024f5..7f8d6924318d 100644 --- a/docs/dev_guide/migration/API-Mapping-query-guide.rst +++ b/docs/dev_guide/migration/API-Mapping-query-guide.rst @@ -1,3 +1,5 @@ +.. _query_map: + Query CUDA* to SYCL* API Mapping ================================ diff --git a/docs/dev_guide/migration/debug-with-codepin.rst b/docs/dev_guide/migration/debug-with-codepin.rst index c9dbef7e1d7f..e01d7b98f7df 100644 --- a/docs/dev_guide/migration/debug-with-codepin.rst +++ b/docs/dev_guide/migration/debug-with-codepin.rst @@ -1,28 +1,41 @@ -CodePin -=============== +.. _debug_codepin: -There are some cases where the migrated SYCL program may have runtime behavior that differs from the original CUDA program. Reasons for this inconsistency include: +Debug Migrated Code: Runtime Behavior +===================================== + +In some cases, the migrated SYCL\* program may have runtime behavior that differs +from the original CUDA\* program. Reasons for this inconsistency may include: * Difference in arithmetic precision between hardware * Semantic difference between the CUDA and SYCL APIs * Errors introduced during the automatic migration -CodePin is introduced as a sub-feature of |tool_name| in order to reduce the effort of debugging such inconsistencies in runtime behavior. -When CodePin is enabled, |tool_name| will migrate the CUDA program to SYCL, but will also generate an instrumented version of the CUDA program. +CodePin is feature of |tool_name| that helps reduce the effort of debugging such +inconsistencies in runtime behavior. When CodePin is enabled, |tool_name| will +migrate the CUDA program to SYCL, but will also generate an instrumented version +of the CUDA program. + +The instrumented code will dump the data of related variables, before and after +selected API or kernel calls, into a report. Compare the reports generated from +the CUDA and SYCL programs to help identify the source of divergent runtime behavior. -The instrumented code will dump the data of related variables, before/after selected API or kernel calls, into a report. -Comparing the reports generated from the CUDA and SYCL program can help identify the source of divergent runtime behavior. +Enable CodePin +-------------- -Command Line Option ----------------------------- -CodePin can be enabled with |tool_name| command line option ``–enable-codepin``. -If ``–out-root`` is specified, the instrumented CUDA program will be put into a -folder with ``_debug`` postfix beside the out-root folder. Otherwise, the -instrumented CUDA program will be put in the default folder ``dpct_output_debug``. +Enable CodePin with the ``–enable-codepin`` option. If ``–out-root`` is specified, +the instrumented CUDA program will be put into a folder with a ``_debug`` postfix +beside the out-root folder. Otherwise, the instrumented CUDA program will be put +in the default folder ``dpct_output_debug``. Example ----------------------------- -The following example demonstrates how CodePin works. +------- + +The following example CUDA code has an issue in the cudaMemcpy() before the +vectorAdd kernel call: the size to be copied is hard coded as ``vectorSize * 12`` +instead of ``vectorSize * sizeof(int3)``, which causes incorrect behavior of the +migrated SYCL program. This is because ``int3`` will be migrated to ``sycl::int3`` +and the size of ``sycl::int3`` is 16 bytes, not 12 bytes. + .. code-block:: c++ @@ -71,18 +84,14 @@ The following example demonstrates how CodePin works. Result[3]: (2, 3, 4) */ -The example CUDA code has an issue in the cudaMemcpy() before the vectorAdd kernel call: -the size to be copied is hard coded as ``vectorSize * 12`` instead of ``vectorSize * sizeof(int3)`` -, which causes incorrect behavior of the migrated SYCL program. This is because ``int3`` will be -migrated to ``sycl::int3`` and the size of ``sycl::int3`` is 16 bytes, not 12 bytes. -To debug the issue, the user can migrate the CUDA program with CodePin enabled. +To debug the issue, the migrate the CUDA program with CodePin enabled: .. code-block:: bash dpct example.cu --enable-codepin -After the migration, there will be 2 files ``dpct_output/example.dp.cpp`` and ``dpct_output_debug/example.cu``. +After migration, there will be two files: ``dpct_output/example.dp.cpp`` and ``dpct_output_debug/example.cu``. .. code-block:: bash @@ -230,8 +239,57 @@ After the migration, there will be 2 files ``dpct_output/example.dp.cpp`` and `` Result[3]: (2, 3, 4) */ -After building and executing ``dpct_output/example.dp.cpp`` and ``dpct_output_debug/example.cu``, the following report will be generated. - -.. figure:: /_images/codepin_example_report.png - -The report helps the user to identify where the runtime behavior of the CUDA and the SYCL version start to diverge from one another. \ No newline at end of file +After building and executing ``dpct_output/example.dp.cpp`` and ``dpct_output_debug/example.cu``, the following reports will be generated. Line number 13 shows the point of divergence. + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Report for the instrumented CUDA program + - Report for the instrumented migrated SYCL program + * - .. code-block:: + :linenos: + + { + "example.cu:23:3:0": { + "d_a[0]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_a[1]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_a[2]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_a[3]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_result[0]": { + "m_Data": "00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00" + }, + ... + + - .. code-block:: + :linenos: + + { + "example.cu:23:3(SYCL):0": { + "d_a[0]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_a[1]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_a[2]": { + "m_Data": "01, 00, 00, 00, 02, 00, 00, 00, 03, 00, 00, 00" + }, + "d_a[3]": { + "m_Data": "00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00" + }, + "d_result[0]": { + "m_Data": "00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00, 00" + }, + ... + +The report helps identify where the runtime behavior of the CUDA and the SYCL +programs start to diverge from one another. \ No newline at end of file diff --git a/docs/dev_guide/migration/generate-compilation-db.rst b/docs/dev_guide/migration/generate-compilation-db.rst index 0ce493eab15b..9804b7972b0a 100644 --- a/docs/dev_guide/migration/generate-compilation-db.rst +++ b/docs/dev_guide/migration/generate-compilation-db.rst @@ -132,6 +132,8 @@ Setuptools is a package development library in Python for facilitating packaging intercept-build -–parse-build-log build.log +.. _gen_db_other_sys: + Generate a Compilation Database with Other Build Systems -------------------------------------------------------- diff --git a/docs/dev_guide/migration/incremental-migration.rst b/docs/dev_guide/migration/incremental-migration.rst index e6508cb5843d..fd0472d5f24b 100644 --- a/docs/dev_guide/migration/incremental-migration.rst +++ b/docs/dev_guide/migration/incremental-migration.rst @@ -1,6 +1,10 @@ +.. _inc_mig: + Incremental Migration ===================== +.. _inc-mig-intro: + |tool_name| provides incremental migration, which automatically merges the results from multiple migrations into a single migrated project. @@ -13,6 +17,8 @@ Incremental migration can be used to Incremental migration is enabled by default. Disable incremental migration using the ``--no-incremental-migration`` option. +.. _inc-mig-intro-end: + Example 1: Migrate a File with Conditional Compilation Code ----------------------------------------------------------- diff --git a/docs/dev_guide/migration/migration-rules.rst b/docs/dev_guide/migration/migration-rules.rst index 0c2706f44528..6c150d07531d 100644 --- a/docs/dev_guide/migration/migration-rules.rst +++ b/docs/dev_guide/migration/migration-rules.rst @@ -1,3 +1,5 @@ +.. _migration_rules: + Migration Rules =============== diff --git a/docs/dev_guide/migration/migration-workflow.rst b/docs/dev_guide/migration/migration-workflow.rst new file mode 100644 index 000000000000..c3983f41bcf0 --- /dev/null +++ b/docs/dev_guide/migration/migration-workflow.rst @@ -0,0 +1,406 @@ +.. _mig_workflow: + +Migration Workflow Guidelines +============================= + +Overview +-------- + +The CUDA* to SYCL* code migration workflow consists of the following high-level +stages: + +* `Stage 1: Prepare for Migration`_. Prepare your project and configure the tool for + a successful migration. +* `Stage 2: Migrate Your Code`_. Review tool options and migrate your code with the + tool. +* `Stage 3: Review the Migrated Code`_. Review and manually convert any unmigrated code. +* `Stage 4: Build and Validate the New SYCL Code Base`_. Build your project with the + migrated code. + +This document describes the steps in each stage with general recommendations and +optional steps. + +Prerequisites +------------- + +.. include:: /_include_files/prereq_mig_flow.rst + +Stage 1: Prepare for Migration +------------------------------ + +Before migrating your CUDA code to SYCL, prepare your CUDA source code for the +migration process. + +Prepare Your CUDA Project +************************* + +Before migration, it is recommended to prepare your CUDA project to minimize errors +during migration: + +#. Make sure your CUDA source code has no syntax errors. +#. Make sure your CUDA source code is Clang compatible. + +Fix Syntax Errors +~~~~~~~~~~~~~~~~~ + +If your original CUDA source code has syntax errors, it may result in unsuccessful +migration. + +Before you start migration, make sure that your original CUDA source code builds +and runs correctly: + +#. Compile your original source code using the compiler defined for your original + CUDA project. +#. Run your compiled application and verify that it functions as expected. + +When your code compiles with no build errors and you have verified that your +application works as expected, your CUDA project is ready for migration. + +Clang Compatibility +~~~~~~~~~~~~~~~~~~~ + +|tool_name| uses the latest version of the Clang* parser to analyze your CUDA source +code during migration. The Clang parser isn’t always compatible with the NVIDIA* +CUDA compiler driver (nvcc). The tool will provide errors about incompatibilities +between nvcc and Clang during migration. + +In some cases, additional manual edits to the CUDA source may be needed before +migration. For example: + +* The Clang parser may need namespace qualification in certain usage scenarios + where nvcc does not require them. +* The Clang parser may need additional forward class declarations where nvcc + does not require them. + + Space within the triple brackets of kernel invocation is tolerated by nvcc but + not Clang. For example, ``cuda_kernel<< > >(args…)`` + is ok for nvcc, but the Clang parser requires the spaces to be removed. + +If you run the migration tool on CUDA source code that has unresolved +incompatibilities between nvcc and Clang parsers, you will get a mixture of errors +in the migration results: + +* Clang errors, which must be resolved in the CUDA source code +* DPCT warnings, which must be resolved in the migrated SYCL code + +For detailed information about dialect differences between Clang and nvcc, refer to llvm.org's +`Compiling CUDA with clang `_ page. + +Configure the Tool +****************** + +CUDA header files used by your project must be accessible to the tool. If you have +not already done so, configure the tool and ensure header files are available. + +.. include:: /_include_files/before_begin_intro_dgr.rst + +Record Compilation Commands +*************************** + + +Use ``intercept-build`` to :ref:`gen_comp_db` to capture the detailed +build options for your project. The migration tool uses build information from +the database (such as header file paths, include paths, macro definitions, compiler +options, and the original compiler) to guide the migration of your CUDA code. + +If your development environment prevents you from using intercept-build, use the +alternate method described in :ref:`gen_db_other_sys`. + +.. note:: + + If you need to re-run your migration after the original migration and the CUDA + build script has changed, you need to either + + #. re-run intercept-build to get an updated compilation database to use in your + migration or + #. manually update the compilation database to capture the changes from the + updated CUDA build script. + +Set Up Revision Control +*********************** + +After migration, the recommendation is to maintain and develop your migrated +application in SYCL to avoid vendor lock-in, though you may choose to continue +your application development in CUDA. Continuing to develop in CUDA will result +in the need to migrate from CUDA to SYCL again. + +Revision control allows comparison between versions of migrated code, which can +help you decide what previous manual changes to the SYCL code you want to merge +into the newly migrated code. + +Make sure to have revision control for your original CUDA source before the first +migration. After the first migration, be sure to place the migrated SYCL code, +with all subsequent manual SYCL changes, under revision control as well. + +Run Analysis Mode +***************** + +You can use Analysis Mode [link to new analysis mode page] to generate a report +before migration that will indicate how much of your code will be migrated, how +much will be partially migrated, and an estimate of the manual effort needed to +complete migration after you have run the tool. This can be helpful to estimate +the work required for your migration. + +Stage 2: Migrate Your Code +-------------------------- + +Plan Your Migration +******************* + +Before executing your migration, review the available tool features and options +that can be used to plan your specific migration. + +Migration Rules +~~~~~~~~~~~~~~~ + +The tool uses a default set of migration rules for all migrations. If default +rules do not give the migration results you need, you can define custom rules for +your migration. This is helpful in multiple scenarios, for example: + +* After migration, you discover multiple instances of similar or identical CUDA + source code that were not migrated, and you know how the CUDA source code should + be migrated to SYCL. In this case, you can define a custom rule and re-run the + migration for better results. This is useful for :ref:`inc_mig` or scenarios + where you may run multiple migrations over time. + +* You know before migration that some code patterns in your original CUDA source + will not be accurately migrated to SYCL using the built-in rules. In this case, + you can define a custom migration rule to handle specific patterns in our CUDA + source during migration. + +For detailed information about defining custom rules, refer to :ref:`migration_rules`. + +For working examples of custom rules, refer to the optional predefined rules +located in the ``extensions/opt_rules`` folder on the installation path of the tool. + +Incremental Migration +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: incremental-migration.rst + :start-after: inc-mig-intro: + :end-before: inc-mig-intro-end: + +For detailed information and examples of incremental migration, refer to :ref:`inc_mig`. + +Command-Line Options +~~~~~~~~~~~~~~~~~~~~ + +|tool_name| provides many command-line options to direct your migration. +Command-line options provide control to + +* Configure your migration with :ref:`basic ` and :ref:`advanced ` options +* :ref:`Control code generation ` +* :ref:`Generate migration reports ` +* :ref:`Migrate build scripts ` +* :ref:`Control warnings ` +* :ref:`Query API mapping ` + +Refer to the :ref:`alpha_opt` for a full list of all available command-line +options. + +What to Expect in Migrated Code +******************************* + +When the tool migrates CUDA code to SYCL code, it inserts diagnostic messages as +comments in the migrated code. The DPCT diagnostic messages are logged as comments +in the migrated source files and output as warnings to the console during migration. +These messages identify areas in the migrated code that may require your attention +to make the code SYCL compliant or correct. This step is detailed in +`Stage 3: Review the Migrated Code`_. + +The migrated code also uses DPCT helper functions to provide utility support for +the generated SYCL code. The helper functions use the ``dpct:: namespace``. Helper +function source files are located at ``/latest/include/dpct``. +DPCT helper functions can be left in migrated code but should not be used in new +SYCL code. Use standard SYCL and C++ when writing new code. For information about +the DPCT namespace, refer to the :ref:`dpct_name_ref`. + +Run Migration +************* + +After reviewing the available migration tool functionality and options, run your +migration. + +.. include:: /_include_files/run_migration.rst + +If your project uses a Makefile or CMake file, use the corresponding option to +automatically migrate the file to work with the migrated code: + +* To migrate a Makefile, use the ``--gen-build-scripts`` option. +* To migrate a CMake file, use the ``--migrate-build-script`` or + ``--migrate-build-script-only`` option. (Note that these options are experimental.) + +For example: + +.. code-block:: + + c2s -p compile_commands.json --in-root ../../.. --gen-helper-function --gen-build-scripts + +This example migrate command: + +* uses the tool alias ``c2s``. ``dpct`` can also be used. +* uses a compilation database, specified with the ``-p`` option +* specifies the source to be migrated with the ``--in-root`` option +* instructs the tool to generate helper function files with the ``--gen-helper-function`` option +* instructs the tool to migrate the Makefile using the ``--gen-build-scripts`` option + +The following samples show migrations of CUDA code using the tool and targets Intel and NVIDIA* hardware: + +* |convo_sep_sample|_ +* |conc_kern_sample|_ + +Stage 3: Review the Migrated Code +--------------------------------- + +After running |tool_name|, manual editing is usually required before the migrated +SYCL code can be compiled. DPCT warnings are logged as comments in the migrated +source files and output to the console during migration. These warnings identify +the portions of code that require manual intervention. Review these comments and +make the recommended changes to ensure the migrated code is consistent with the +original logic. + +.. include:: ../reference/diagnostic_ref/dpct1009.rst + :start-after: example_dpct: + :end-before: example_dpct_end: + +Note the :ref:`DPCT1009` warning inserted where additional review is needed. + +For a detailed explanation of the comments, including suggestions to fix the issues, +refer to the :ref:`diag_ref`. + +At this stage, you may observe that the same DPCT warnings were generated repeatedly +in your code or that the same manual edits were needed in multiple locations to fix +a specific pattern in your original source code. Consider defining the manual edits +needed to fix repeated DPCT warnings as a +:ref:`user-defined migration rule `. This allows +you to save your corrections and automatically apply them to a future migration of +your CUDA source. + +.. note:: + + CUDA* API migration support is broad but not complete. If you encounter CUDA + APIs that were not migrated due to a lack of tool support, please report it + to the |sycl_forum|_ or + `priority support `_. + Alternatively, `submit an issue `_ or + `contribute to the SYCLomatic project `_. + This helps prioritize which CUDA APIs will be supported in future releases. + +Stage 4: Build and Validate the New SYCL Code Base +-------------------------------------------------- + +After you have completed any manual migration steps, build your converted code +and validate your new code base. + +Install New SYCL Code Base Dependencies +*************************************** + +Converted code makes use of oneAPI library APIs and Intel SYCL extensions. Before +compiling, install the appropriate oneAPI libraries and a compiler that supports +the Intel SYCL extensions. + + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - If your CUDA source uses ... + - ... install this oneAPI library + * - cuBLAS, cuFFT, cuRAND, cuSolver, cuSparse + - Intel® oneAPI Math Kernel Library (oneMKL) + * - Thrust, CUB + - Intel® oneAPI DPC++ Library (oneDPL) + * - cuDNN + - Intel® oneAPI Deep Neural Network Library (oneDNN) + * - NCCL + - Intel® oneAPI Collective Communications Library (oneCCL) + +The following compilers support Intel SYCL extensions: + +* |dpcpp_compiler|_ +* |oneapi_dpcpp_compiler|_ + +Most libraries and the |dpcpp_compiler| are included in the |base_kit_long|_. Libraries +and the compiler are also available as stand-alone downloads. + +Compile for Intel CPU and GPU +***************************** + +If your program targets Intel GPUs, install the latest Intel GPU drivers before +compiling. + +* `Linux GPU Drivers `_ +* `Windows GPU Drivers `_ + +Use your updated Makefile or CMake file to build your program, or compile it +manually at the command line using a compiler that supports the Intel SYCL extensions. +Make sure that all linker and compilation commands use the ``-fsycl`` compiler +option with the C++ driver. For example: + +.. code-block:: + + icpx -fsycl migrated-file.cpp + +For detailed information about compiling with the |dpcpp_compiler|, refer to the +|compiler_dev_guide|_. + +Compile for AMD* or NVIDIA* GPU +******************************* + +If your program targets AMD* or NVIDIA GPUs, install the appropriate Codeplay* +plugin for the target GPU before compiling. Instructions for installing the AMD +and NVIDIA GPU plugins, as well as how to compile for those targets, can be found +in the Codeplay plugin documentation: + +* `Install the oneAPI for AMD GPUs plugin `_ from Codeplay. +* `Install the oneAPI for NVIDIA GPUs plugin `_ from Codeplay. + +Optimize Your Code +------------------ + +Optimize your migrated code for Intel GPUs using Intel® tools such as +|vtune|_ and |advisor|_. These tools help identify areas of +code to improve for optimizing your application performance. + +Additional hardware- or library-specific optimization information is available: + +* For detailed information about optimizing your code for Intel GPUs, refer to + the `oneAPI GPU Optimization Guide `_. +* For detailed information about optimizing your code for AMD GPUs, refer to the + `Codeplay AMD GPU Performance Guide `_. +* For detailed information about optimizing your code for NVIDIA GPUS, refer to + the `Codeplay NVIDIA GPU Performance Guide `_. + + +Find More +--------- + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Content + - Description + * - |compiler_dev_guide|_ + - Developer guide and reference for the Intel® oneAPI DPC++/C++ Compiler. + * - `SYCL 2020 Specification `_ + - The SYCL 2020 Specification PDF. + * - |dpcpp_compiler|_ + - Intel branded C++ compiler built from the open-source oneAPI DPC++ Compiler, with additional Intel hardware optimization. + * - |oneapi_dpcpp_compiler|_ + - Open-source Intel LLVM-based compiler project that implements compiler and runtime support for the SYCL* language. + * - `Basic migration samples `_ + - Sample CUDA projects with instructions on migrating to SYCL using the tool. + * - Guided migration samples + - Guided migration of two sample NVIDIA CUDA projects: + + * |convo_sep_sample|_ + * |conc_kern_sample|_ + * - `Jupyter notebook samples `_ + - A Jupyter* Notebook that guides you through the migration of a simple example and four step-by-step sample migrations from CUDA to SYCL. + * - `CUDA* to SYCL* Catalog `_ + - Catalog of CUDA projects that have been migrated to SYCL. + * - |sycl_forum|_ + - Forum to get assistance when migrating your CUDA code to SYCL. + * - `Intel® oneAPI Math Kernel Library Link Line Advisor `_ + - Intel® oneAPI Math Kernel Library tool to help determine how to include oneMKL libraries for your specific use case. \ No newline at end of file diff --git a/docs/dev_guide/reference.rst b/docs/dev_guide/reference.rst index 5a9ebd351657..608f213bfcf0 100644 --- a/docs/dev_guide/reference.rst +++ b/docs/dev_guide/reference.rst @@ -11,7 +11,6 @@ mapping CUDA* concepts and APIs to SYCL*. reference/command-line-options-reference reference/diagnostics-reference reference/dpct-namespace-reference - reference/api-mapping-status reference/compare-prog-models reference/term-mapping-quick-ref diff --git a/docs/dev_guide/reference/command-line-options-ref/help-info.rst b/docs/dev_guide/reference/command-line-options-ref/help-info.rst index 2f6dfbf23e38..176493c3ad08 100644 --- a/docs/dev_guide/reference/command-line-options-ref/help-info.rst +++ b/docs/dev_guide/reference/command-line-options-ref/help-info.rst @@ -5,6 +5,8 @@ Query API Mapping, Tool Warning, and Help Options The following tables list command line options to query API mapping support, manage warnings generated by the tool, and to display tool information. +.. _query_api_opt: + Query API Mapping Options ------------------------- @@ -21,6 +23,8 @@ Query API Mapping Options :start-after: desc-query-api-map: :end-before: end-query-api-map: +.. _warn_opt: + Tool Warning Options -------------------- diff --git a/docs/dev_guide/reference/diagnostic_ref/dpct1009.rst b/docs/dev_guide/reference/diagnostic_ref/dpct1009.rst index c28f44bb3936..2b08acf7ef04 100644 --- a/docs/dev_guide/reference/diagnostic_ref/dpct1009.rst +++ b/docs/dev_guide/reference/diagnostic_ref/dpct1009.rst @@ -28,6 +28,8 @@ Suggestions to Fix You may need to rewrite this code. +.. _example_dpct: + For example, this original CUDA\* code: .. code-block:: cpp @@ -56,6 +58,8 @@ results in the following migrated SYCL code: "cudaGetErrorString is not supported" /*cudaGetErrorString(err)*/); } +.. _example_dpct_end: + which is rewritten to: .. code-block:: cpp diff --git a/docs/dev_guide/reference/dpct-namespace-reference.rst b/docs/dev_guide/reference/dpct-namespace-reference.rst index 696ffc93f2e2..946ba6d4486b 100644 --- a/docs/dev_guide/reference/dpct-namespace-reference.rst +++ b/docs/dev_guide/reference/dpct-namespace-reference.rst @@ -1,3 +1,5 @@ +.. _dpct_name_ref: + DPCT Namespace Reference ======================== diff --git a/docs/dev_guide/tool-setup.rst b/docs/dev_guide/tool-setup.rst index 76881616e134..e013ad4159af 100644 --- a/docs/dev_guide/tool-setup.rst +++ b/docs/dev_guide/tool-setup.rst @@ -4,6 +4,8 @@ Tool Setup and Basic Use Before You Begin ---------------- +Install and set up |tool_name|. + .. include:: /_include_files/before_begin_intro_dgr.rst diff --git a/docs/index.rst b/docs/index.rst index f8d4dd836ca2..a70167f01c52 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,5 +17,6 @@ Use |tool_name| to help port CUDA\* language kernels and library API calls to |d dev_guide/tool-setup dev_guide/migration dev_guide/reference + dev_guide/api-mapping-status dev_guide/frequently-asked-questions-faq