diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst index 115749b3da..98f5292b99 100644 --- a/docs/docfiles/intro.rst +++ b/docs/docfiles/intro.rst @@ -1,17 +1,31 @@ Welcome to Data-parallel Control (dpctl)'s documentation! ========================================================= -The data-parallel control (dpctl) library provides C and Python bindings for +`Data-parallel control `_ (dpctl) is a +runtime library for Python applications and libraries to execute a compute +kernel on a device that supports a data-parallel mode of execution. Using +dpctl's API a library or an application can query a system to identify +data-parallel devices, allocate memory on those devices, and schedule execution +of compute kernels on the devices. Dpctl's role is only to facilitate the +scheduling of compute kernels, the library plays no role in +the definition of the kernels themselves. It is up to the users of dpctl to +define the kernels. As an example, the +`numba-dppy `_ +package uses an OpenCL-like abstraction to define kernels directly in Python +and JIT compiles them to native binary. Numba-dppy then schedules the kernels on +devices using dpctl. Another example is the +`dpnp `_ package, a NumPy-like +library of pre-compiled kernels written in the +`SYCL language `_. Dpnp too +uses dpctl to schedule and execute the kernels it provides. + +Dpctl uses SYCL as the underlying low-level runtime layer and implements +Python bindings for a subset of the runtime classes defined in `SYCL 2020 `_. -The SYCL 2020 features supported by dpctl are limited to those included by -Intel's DPCPP compiler and specifically cover the SYCL runtime classes described -in `Section 4.6 `_ -of the SYCL 2020 specification. Apart from the bindings for these runtime -classes, dpctl includes bindings for SYCL USM memory allocators and -deallocators. Dpctl's Python API provides classes that implement -`Python buffer protocol `_ -using SYCL USM memory; making it possible to create Python objects that are -backed by SYCL USM memory. +Currently, only Intel(R)'s `DPC++ `_ is the only +supported SYCL implementation. Refer the User Guide and API documentation for a +comprehensive list of SYCL features exposed by dpctl. + +.. todo:: -Dpctl also supports the DPCPP ``ONEAPI::filter_selector`` extension and has -experimental support for SYCL's ``kernel`` and ``program`` classes. + A paragraph on dpctl.tensor diff --git a/docs/docfiles/user_guides/UserManual.rst b/docs/docfiles/user_guides/UserManual.rst new file mode 100644 index 0000000000..f6e6be63ab --- /dev/null +++ b/docs/docfiles/user_guides/UserManual.rst @@ -0,0 +1,17 @@ +.. _user_manual: + +########### +User Manual +########### + +.. toctree:: + :maxdepth: 2 + + manual/intro + manual/platforms + manual/devices + manual/contexts + manual/queues + manual/submitting_kernels + manual/events + manual/profiling diff --git a/docs/docfiles/user_guides/manual/devices.rst b/docs/docfiles/user_guides/manual/devices.rst new file mode 100644 index 0000000000..69f67d9d1d --- /dev/null +++ b/docs/docfiles/user_guides/manual/devices.rst @@ -0,0 +1,35 @@ +.. _querying_platforms: + +.. contents:: + :local: + :backlinks: none + :depth: 1 + +Listing devices +~~~~~~~~~~~~~~~ + +.. todo:: + + Get a list of devices + +Selecting a device +~~~~~~~~~~~~~~~~~~ + +.. todo:: + + Demonstrate all the ways we can select devices. + +Query device properties +~~~~~~~~~~~~~~~~~~~~~~~ + +.. todo:: + + Demonstrate how to query a device's various aspects and properties. + + +Creating a sub-device +~~~~~~~~~~~~~~~~~~~~~ + +.. todo:: + + Talk about sub-device creation diff --git a/docs/docfiles/user_guides/manual/intro.rst b/docs/docfiles/user_guides/manual/intro.rst new file mode 100644 index 0000000000..3068027420 --- /dev/null +++ b/docs/docfiles/user_guides/manual/intro.rst @@ -0,0 +1,9 @@ +.. _user_manual_intro: + +Introduction +------------ + +.. todo:: + + Introduce the basic concepts of Platforms, Devices, Contexts, Queues, + Events, and USM. diff --git a/docs/docfiles/user_guides/manual/platforms.rst b/docs/docfiles/user_guides/manual/platforms.rst new file mode 100644 index 0000000000..ccef6792db --- /dev/null +++ b/docs/docfiles/user_guides/manual/platforms.rst @@ -0,0 +1,8 @@ +.. _querying_platforms: + +Querying Platforms +------------------ + +.. todo:: + + Demonstrate use of ``lsplatform`` diff --git a/docs/index_doxyrest.rst.in b/docs/index_doxyrest.rst.in index 51e55562f9..b461b90cb0 100644 --- a/docs/index_doxyrest.rst.in +++ b/docs/index_doxyrest.rst.in @@ -1,14 +1,20 @@ .. include:: ./docfiles/intro.rst + +How-to Guides +============= + .. toctree:: :maxdepth: 1 - :caption: User Guides docfiles/user_guides/QuickStart + docfiles/user_guides/UserManual + +API Documentation +================= .. toctree:: :maxdepth: 1 - :caption: API Documentation docfiles/dpctl_pyapi @DOXYREST_OUTPUT_DIR_NAME@/index diff --git a/docs/index_no_doxyrest.rst.in b/docs/index_no_doxyrest.rst.in index fffbf63cb4..da69805e64 100644 --- a/docs/index_no_doxyrest.rst.in +++ b/docs/index_no_doxyrest.rst.in @@ -1,14 +1,19 @@ .. include:: ./docfiles/intro.rst +How-to Guides +============= + .. toctree:: :maxdepth: 1 - :caption: User Guides docfiles/user_guides/QuickStart + docfiles/user_guides/UserManual + +API Documentation +================= .. toctree:: :maxdepth: 1 - :caption: API Documentation docfiles/dpctl_pyapi