From 856a8ab6a2f140b1a7eaf0d60135e5f6fc219315 Mon Sep 17 00:00:00 2001 From: "Malia, Viraj" Date: Mon, 14 Oct 2024 11:19:17 +0530 Subject: [PATCH 1/3] [DOCS]Update new backend guide to support the latest main branch --- docs/README.md | 4 +++- docs/create_new_backend.rst | 11 ++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 040d22aac..5120b33c8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,9 @@ This folder contains oneMKL documentation in reStructuredText (rST) format. The documentation build step is skipped by default. To enable building documentation from the main build, set `-DBUILD_DOC=ON`. -For more information see [Building with CMake](../README.md#building-with-cmake). + +Make sure you have Sphinx installed: +`pip install sphinx` To build documentation only, use the following commands from the current folder: ```bash diff --git a/docs/create_new_backend.rst b/docs/create_new_backend.rst index 8f25bda33..63e7df37f 100644 --- a/docs/create_new_backend.rst +++ b/docs/create_new_backend.rst @@ -38,13 +38,13 @@ If there is no need for multiple wrappers only ```` and ``<3rd-party lib For each new backend library, you should create the following two header files: * Header file with a declaration of entry points to the new third-party library wrappers -* Compiler-time dispatching interface (see `oneMKL Usage Models <../README.md#supported-usage-models>`_) for new third-party libraries +* Compile-time dispatching interface (see `oneMKL Usage Models <../README.md#supported-usage-models>`_) for new third-party libraries **Header File Example**: command to generate the header file with a declaration of BLAS entry points in the oneapi::mkl::newlib namespace .. code-block:: bash - python scripts/generate_backend_api.py include/oneapi/mkl/blas.hpp \ # Base header file + python scripts/generate_backend_api.py include/oneapi/mkl/blas.hxx \ # Base header file include/oneapi/mkl/blas/detail/newlib/onemkl_blas_newlib.hpp \ # Output header file oneapi::mkl::newlib # Wrappers namespace @@ -65,7 +65,7 @@ Code snippet of the generated header file ``include/oneapi/mkl/blas/detail/newli .. code-block:: bash - python scripts/generate_ct_instant.py include/oneapi/mkl/blas/detail/blas_ct_templates.hpp \ # Base header file + python scripts/generate_ct_instant.py include/oneapi/mkl/blas/detail/blas_ct_backends.hxx \ # Base header file include/oneapi/mkl/blas/detail/newlib/blas_ct.hpp \ # Output header file include/oneapi/mkl/blas/detail/newlib/onemkl_blas_newlib.hpp \ # Header file with declaration of entry points to wrappers newlib \ # Library name @@ -124,6 +124,7 @@ Below you can see structure of oneMKL top-level include directory: / / +Note: The actual structure may be different than what is shown here. To ensure your addition of a new backend is correct, verify that the above scripts correctly generate sample header files from the new files you have added. To integrate the new third-party library to a oneMKL header-based part, following files from this structure should be updated: @@ -402,7 +403,7 @@ Here is the list of files that should be created/updated to integrate the new wr + PUBLIC ONEMKL::NEWLIB::NEWLIB ) -Now you can build the backend library for ``newlib`` to make sure the third-party library integration was completed successfully (for more information, see `Build with cmake <../README.md#building-with-cmake>`_) +Now you can build the backend library for ``newlib`` to make sure the third-party library integration was completed successfully (for more information, see `Building the Project with DPC++ `_) .. code-block:: bash @@ -499,7 +500,7 @@ Update the following files to enable the new third-party library for unit tests: + devices.push_back(sycl::device(sycl::host_selector())); + #endif -Now you can build and run functional testing for enabled third-party libraries (for more information see `Build with cmake <../README.md#building-with-cmake>`_). +Now you can build and run functional testing for enabled third-party libraries (for more information see `Building the Project with DPC++ `_). .. code-block:: bash From 6723241cdb2c85141c82e3ee29f3e7f49c189542 Mon Sep 17 00:00:00 2001 From: "Malia, Viraj" Date: Tue, 15 Oct 2024 10:57:06 +0530 Subject: [PATCH 2/3] Add steps to generate CT header template --- docs/create_new_backend.rst | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/create_new_backend.rst b/docs/create_new_backend.rst index 63e7df37f..ec69cdcea 100644 --- a/docs/create_new_backend.rst +++ b/docs/create_new_backend.rst @@ -61,17 +61,30 @@ Code snippet of the generated header file ``include/oneapi/mkl/blas/detail/newli -**Compile-time Dispatching Interface Example**: command to generate the compile-time dispatching interface template instantiations for ``newlib`` and supported device ``newdevice`` +**Compile-time Dispatching Interface Example**: commands to generate the compile-time dispatching interface template instantiations for ``newlib`` and supported device ``newdevice`` .. code-block:: bash + python scripts/generate_ct_templates.py include/oneapi/mkl/blas.hxx \ # Base header file + include/oneapi/mkl/blas/detail/blas_ct_templates.hpp # Output header file - python scripts/generate_ct_instant.py include/oneapi/mkl/blas/detail/blas_ct_backends.hxx \ # Base header file + python scripts/generate_ct_instant.py include/oneapi/mkl/blas/detail/blas_ct_templates.hpp \ # Base header file include/oneapi/mkl/blas/detail/newlib/blas_ct.hpp \ # Output header file include/oneapi/mkl/blas/detail/newlib/onemkl_blas_newlib.hpp \ # Header file with declaration of entry points to wrappers newlib \ # Library name newdevice \ # Backend name oneapi::mkl::newlib # Wrappers namespace +Code snippet of the generated template header file ``include/oneapi/mkl/blas/detail/blas_ct_templates.hpp`` + +.. code-block:: cpp + + #include "oneapi/mkl/types.hpp" + #include "oneapi/mkl/detail/backends.hpp" + + template + static inline void asum(sycl::queue &queue, std::int64_t n, sycl::buffer, 1> &x, + std::int64_t incx, sycl::buffer &result); + Code snippet of the generated header file ``include/oneapi/mkl/blas/detail/newlib/blas_ct.hpp`` .. code-block:: cpp From 5e528960e263f8f3958a0df7e7346aea62329f9f Mon Sep 17 00:00:00 2001 From: "Malia, Viraj" Date: Tue, 15 Oct 2024 11:04:49 +0530 Subject: [PATCH 3/3] Fix code-formatting --- docs/create_new_backend.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/create_new_backend.rst b/docs/create_new_backend.rst index ec69cdcea..1eaaf3562 100644 --- a/docs/create_new_backend.rst +++ b/docs/create_new_backend.rst @@ -64,6 +64,7 @@ Code snippet of the generated header file ``include/oneapi/mkl/blas/detail/newli **Compile-time Dispatching Interface Example**: commands to generate the compile-time dispatching interface template instantiations for ``newlib`` and supported device ``newdevice`` .. code-block:: bash + python scripts/generate_ct_templates.py include/oneapi/mkl/blas.hxx \ # Base header file include/oneapi/mkl/blas/detail/blas_ct_templates.hpp # Output header file