Skip to content

Commit 695cd06

Browse files
author
Diptorup Deb
committed
Stubs for user manual.
1 parent 309aa1f commit 695cd06

File tree

7 files changed

+110
-16
lines changed

7 files changed

+110
-16
lines changed

‎docs/docfiles/intro.rst

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,31 @@
11
Welcome to Data-parallel Control (dpctl)'s documentation!
22
=========================================================
33

4-
The data-parallel control (dpctl) library provides C and Python bindings for
4+
`Data-parallel control <https://github.com/IntelPython/dpctl>`_ (dpctl) is a
5+
runtime library for Python applications and libraries to execute a compute
6+
kernel on a device that supports a data-parallel mode of execution. Using
7+
dpctl's API a library or an application can query a system to identify
8+
data-parallel devices, allocate memory on those devices, and schedule execution
9+
of compute kernels on the devices. Dpctl's role is only to facilitate the
10+
scheduling of compute kernels, the library plays no role in
11+
the definition of the kernels themselves. It is up to the users of dpctl to
12+
define the kernels. As an example, the
13+
`numba-dppy <https://intelpython.github.io/numba-dppy/latest/index.html>`_
14+
package uses an OpenCL-like abstraction to define kernels directly in Python
15+
and JIT compiles them to native binary. Numba-dppy then schedules the kernels on
16+
devices using dpctl. Another example is the
17+
`dpnp <https://intelpython.github.io/dpnp/>`_ package, a NumPy-like
18+
library of pre-compiled kernels written in the
19+
`SYCL language <https://sycl.readthedocs.io/en/latest/index.html>`_. Dpnp too
20+
uses dpctl to schedule and execute the kernels it provides.
21+
22+
Dpctl uses SYCL as the underlying low-level runtime layer and implements
23+
Python bindings for a subset of the runtime classes defined in
524
`SYCL 2020 <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html>`_.
6-
The SYCL 2020 features supported by dpctl are limited to those included by
7-
Intel's DPCPP compiler and specifically cover the SYCL runtime classes described
8-
in `Section 4.6 <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>`_
9-
of the SYCL 2020 specification. Apart from the bindings for these runtime
10-
classes, dpctl includes bindings for SYCL USM memory allocators and
11-
deallocators. Dpctl's Python API provides classes that implement
12-
`Python buffer protocol <https://docs.python.org/3/c-api/buffer.html>`_
13-
using SYCL USM memory; making it possible to create Python objects that are
14-
backed by SYCL USM memory.
25+
Currently, only Intel(R)'s `DPC++ <https://intel.ly/3wwjEsd>`_ is the only
26+
supported SYCL implementation. Refer the User Guide and API documentation for a
27+
comprehensive list of SYCL features exposed by dpctl.
28+
29+
.. todo::
1530

16-
Dpctl also supports the DPCPP ``ONEAPI::filter_selector`` extension and has
17-
experimental support for SYCL's ``kernel`` and ``program`` classes.
31+
A paragraph on dpctl.tensor

‎docs/docfiles/user_guides/UserManual.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. _user_manual:
2+
3+
###########
4+
User Manual
5+
###########
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
manual/intro
11+
manual/platforms
12+
manual/devices
13+
manual/contexts
14+
manual/queues
15+
manual/submitting_kernels
16+
manual/events
17+
manual/profiling

‎docs/docfiles/user_guides/manual/devices.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _querying_platforms:
2+
3+
.. contents::
4+
:local:
5+
:backlinks: none
6+
:depth: 1
7+
8+
Listing devices
9+
~~~~~~~~~~~~~~~
10+
11+
.. todo::
12+
13+
Get a list of devices
14+
15+
Selecting a device
16+
~~~~~~~~~~~~~~~~~~
17+
18+
.. todo::
19+
20+
Demonstrate all the ways we can select devices.
21+
22+
Query device properties
23+
~~~~~~~~~~~~~~~~~~~~~~~
24+
25+
.. todo::
26+
27+
Demonstrate how to query a device's various aspects and properties.
28+
29+
30+
Creating a sub-device
31+
~~~~~~~~~~~~~~~~~~~~~
32+
33+
.. todo::
34+
35+
Talk about sub-device creation

‎docs/docfiles/user_guides/manual/intro.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _user_manual_intro:
2+
3+
Introduction
4+
------------
5+
6+
.. todo::
7+
8+
Introduce the basic concepts of Platforms, Devices, Contexts, Queues,
9+
Events, and USM.

‎docs/docfiles/user_guides/manual/platforms.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. _querying_platforms:
2+
3+
Querying Platforms
4+
------------------
5+
6+
.. todo::
7+
8+
Demonstrate use of ``lsplatform``

‎docs/index_doxyrest.rst.in

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
11
.. include:: ./docfiles/intro.rst
22

3+
4+
How-to Guides
5+
=============
6+
37
.. toctree::
48
:maxdepth: 1
5-
:caption: User Guides
69

710
docfiles/user_guides/QuickStart
11+
docfiles/user_guides/UserManual
12+
13+
API Documentation
14+
=================
815

916
.. toctree::
1017
:maxdepth: 1
11-
:caption: API Documentation
1218

1319
docfiles/dpctl_pyapi
1420
@DOXYREST_OUTPUT_DIR_NAME@/index

‎docs/index_no_doxyrest.rst.in

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
.. include:: ./docfiles/intro.rst
22

3+
How-to Guides
4+
=============
5+
36
.. toctree::
47
:maxdepth: 1
5-
:caption: User Guides
68

79
docfiles/user_guides/QuickStart
10+
docfiles/user_guides/UserManual
11+
12+
API Documentation
13+
=================
814

915
.. toctree::
1016
:maxdepth: 1
11-
:caption: API Documentation
1217

1318
docfiles/dpctl_pyapi
1419

0 commit comments

Comments
 (0)