Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS]Update new backend guide to support the latest develop #593

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 20 additions & 5 deletions docs/create_new_backend.rst
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,13 @@ If there is no need for multiple wrappers only ``<domain>`` 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

Expand All @@ -61,17 +61,31 @@ 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_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 <oneapi::mkl::backend backend>
static inline void asum(sycl::queue &queue, std::int64_t n, sycl::buffer<std::complex<float>, 1> &x,
std::int64_t incx, sycl::buffer<float, 1> &result);

Code snippet of the generated header file ``include/oneapi/mkl/blas/detail/newlib/blas_ct.hpp``

.. code-block:: cpp
Expand Down Expand Up @@ -124,6 +138,7 @@ Below you can see structure of oneMKL top-level include directory:
<other backends>/
<other domains>/

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MIght as well use the rST note role:

.. note::
   The actual structure…

…

To integrate the new third-party library to a oneMKL header-based part, following files from this structure should be updated:

Expand Down Expand Up @@ -402,7 +417,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++ <https://oneapi-src.github.io/oneMKL/building_the_project_with_dpcpp.html>`_)

.. code-block:: bash

Expand Down Expand Up @@ -499,7 +514,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++ <https://oneapi-src.github.io/oneMKL/building_the_project_with_dpcpp.html>`_).

.. code-block:: bash

Expand Down