[SYCLomatic][DOC] Add migration workflow (#1757)

* Initial commit for migration workflow. Initial commit of the new migration workflow topic. Signed-off-by: krisdale <[email protected]> * Update migration workflow with includes Update migration workflow to use includes needed to support 2 versions of content. Add codepin to migration toc to resolve build warning. Update code pin (editorial) for clarity and consistency, convert report image to text example. Signed-off-by: krisdale <[email protected]> * Move Migration Support Move CUDA API Migration Support back to top level nav in dev guide. Signed-off-by: krisdale <[email protected]> --------- Signed-off-by: krisdale <[email protected]>
oneapi-src · Mar 6, 2024 · 6b16932 · 6b16932
1 parent 30e7d4b
commit 6b16932
Show file tree

Hide file tree

Showing 33 changed files with 579 additions and 60 deletions.
diff --git 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
@@ -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.
diff --git a/docs/_include_files/run_migration.rst b/docs/_include_files/run_migration.rst
@@ -0,0 +1,2 @@
+
+You can run the tool from the command line.
diff --git 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/...ev_guide/reference/api-mapping-status.rst → docs/dev_guide/api-mapping-status.rst b/...ev_guide/reference/api-mapping-status.rst → docs/dev_guide/api-mapping-status.rst
diff --git a/...pping-status/ASM_API_migration_status.csv → ...pping-status/ASM_API_migration_status.csv b/...pping-status/ASM_API_migration_status.csv → ...pping-status/ASM_API_migration_status.csv
diff --git a/...pping-status/CUB_API_migration_status.csv → ...pping-status/CUB_API_migration_status.csv b/...pping-status/CUB_API_migration_status.csv → ...pping-status/CUB_API_migration_status.csv
diff --git a/...ping-status/NCCL_API_migration_status.csv → ...ping-status/NCCL_API_migration_status.csv b/...ping-status/NCCL_API_migration_status.csv → ...ping-status/NCCL_API_migration_status.csv
diff --git a/...ping-status/NVML_API_migration_status.csv → ...ping-status/NVML_API_migration_status.csv b/...ping-status/NVML_API_migration_status.csv → ...ping-status/NVML_API_migration_status.csv
diff --git a/...ntime_and_Driver_API_migration_status.csv → ...ntime_and_Driver_API_migration_status.csv b/...ntime_and_Driver_API_migration_status.csv → ...ntime_and_Driver_API_migration_status.csv
diff --git a/...ng-status/cuBLAS_API_migration_status.csv → ...ng-status/cuBLAS_API_migration_status.csv b/...ng-status/cuBLAS_API_migration_status.csv → ...ng-status/cuBLAS_API_migration_status.csv
diff --git a/...ing-status/cuDNN_API_migration_status.csv → ...ing-status/cuDNN_API_migration_status.csv b/...ing-status/cuDNN_API_migration_status.csv → ...ing-status/cuDNN_API_migration_status.csv
diff --git a/...ing-status/cuFFT_API_migration_status.csv → ...ing-status/cuFFT_API_migration_status.csv b/...ing-status/cuFFT_API_migration_status.csv → ...ing-status/cuFFT_API_migration_status.csv
diff --git a/...ng-status/cuRAND_API_migration_status.csv → ...ng-status/cuRAND_API_migration_status.csv b/...ng-status/cuRAND_API_migration_status.csv → ...ng-status/cuRAND_API_migration_status.csv
diff --git a/...-status/cuSOLVER_API_migration_status.csv → ...-status/cuSOLVER_API_migration_status.csv b/...-status/cuSOLVER_API_migration_status.csv → ...-status/cuSOLVER_API_migration_status.csv
diff --git a/...-status/cuSPARSE_API_migration_status.csv → ...-status/cuSPARSE_API_migration_status.csv b/...-status/cuSPARSE_API_migration_status.csv → ...-status/cuSPARSE_API_migration_status.csv
diff --git a/...g-status/nvGRAPH_API_migration_status.csv → ...g-status/nvGRAPH_API_migration_status.csv b/...g-status/nvGRAPH_API_migration_status.csv → ...g-status/nvGRAPH_API_migration_status.csv
diff --git a/...ng-status/nvJPEG_API_migration_status.csv → ...ng-status/nvJPEG_API_migration_status.csv b/...ng-status/nvJPEG_API_migration_status.csv → ...ng-status/nvJPEG_API_migration_status.csv
diff --git a/...ng-status/thrust_API_migration_status.csv → ...ng-status/thrust_API_migration_status.csv b/...ng-status/thrust_API_migration_status.csv → ...ng-status/thrust_API_migration_status.csv
diff --git a/...ping-status/wmma_API_migration_status.csv → ...ping-status/wmma_API_migration_status.csv b/...ping-status/wmma_API_migration_status.csv → ...ping-status/wmma_API_migration_status.csv
diff --git 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 <gen_comp_db>` 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
@@ -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
@@ -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.
+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.
diff --git 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
@@ -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
@@ -1,3 +1,5 @@
+.. _migration_rules:
+
 Migration Rules
 ===============
-Original file line number
+Diff line change
@@ Expand Up @@
            intercept-build -–parse-build-log build.log
+    .. _gen_db_other_sys:
     Generate a Compilation Database with Other Build Systems
     --------------------------------------------------------
@@ Expand Down @@