diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst index 892e66af72..3c7d1b86b8 100644 --- a/docs/docfiles/intro.rst +++ b/docs/docfiles/intro.rst @@ -12,5 +12,5 @@ deallocators. Dpctl's Python API provides classes that implement using SYCL USM memory; making it possible to create Python objects that are backed by SYCL USM memory. -Dpctl also supports the DPCPP ``ONEAPI::filter_selector`` extension and has +Dpctl also supports the DPCPP :oneapi_filter_selection:`oneapi::filter_selector <>` extension and has experimental support for SYCL's ``kernel`` and ``program`` classes. diff --git a/docs/docfiles/urls.json b/docs/docfiles/urls.json index 3e0906fc41..0e7fa81c40 100644 --- a/docs/docfiles/urls.json +++ b/docs/docfiles/urls.json @@ -2,7 +2,9 @@ "dpcpp_envar": "https://github.com/intel/llvm/blob/sycl/sycl/doc/EnvironmentVariables.md", "numa_domain": "https://en.wikipedia.org/wiki/Non-uniform_memory_access", "oneapi": "https://www.oneapi.io/", - "oneapi_filter_selection": "https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/FilterSelector/FilterSelector.adoc", + "oneapi_filter_selection": "https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/supported/sycl_ext_oneapi_filter_selector.asciidoc", + "oneapi_default_context": "https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/supported/sycl_ext_oneapi_default_context.asciidoc", + "oneapi_enqueue_barrier": "https://github.com/intel/llvm/blob/sycl/sycl/doc/extensions/supported/sycl_ext_oneapi_enqueue_barrier.asciidoc", "sycl_aspects": "https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#table.device.aspect", "sycl_context": "https://sycl.readthedocs.io/en/latest/iface/context.html", "sycl_device": "https://sycl.readthedocs.io/en/latest/iface/device.html", diff --git a/docs/docfiles/user_guides/UserManual.rst b/docs/docfiles/user_guides/UserManual.rst index 9b955f1b0c..1fd2069fb4 100644 --- a/docs/docfiles/user_guides/UserManual.rst +++ b/docs/docfiles/user_guides/UserManual.rst @@ -4,6 +4,9 @@ User Manual ########### +Table of contents ++++++++++++++++++ + .. toctree:: :maxdepth: 3 diff --git a/docs/docfiles/user_guides/manual/dpctl/intro.rst b/docs/docfiles/user_guides/manual/dpctl/intro.rst index 327178919e..341a75f8e8 100644 --- a/docs/docfiles/user_guides/manual/dpctl/intro.rst +++ b/docs/docfiles/user_guides/manual/dpctl/intro.rst @@ -26,13 +26,12 @@ The user guide introduces the core features of dpctl and the underlying concepts. The guide is meant primarily for users of the Python package. Library and native extension developers should refer to the programmer's guide. -Table of contents -+++++++++++++++++ - .. toctree:: :maxdepth: 2 + :caption: Table of Contents basic_concepts device_selection platforms devices + queues diff --git a/docs/docfiles/user_guides/manual/dpctl/platforms.rst b/docs/docfiles/user_guides/manual/dpctl/platforms.rst index bf9c0ed981..c774847658 100644 --- a/docs/docfiles/user_guides/manual/dpctl/platforms.rst +++ b/docs/docfiles/user_guides/manual/dpctl/platforms.rst @@ -1,4 +1,4 @@ -.. _querying_platforms: +.. _platforms: ######## Platform diff --git a/docs/docfiles/user_guides/manual/dpctl/queues.rst b/docs/docfiles/user_guides/manual/dpctl/queues.rst new file mode 100644 index 0000000000..6afce0ec71 --- /dev/null +++ b/docs/docfiles/user_guides/manual/dpctl/queues.rst @@ -0,0 +1,106 @@ +.. _queues: + +##### +Queue +##### + +A queue is needed to schedule execution of any computation or data copying on a +device. Queue construction requires specifying a device and a context targeting +that device as well as additional properties, such as whether profiling +information should be collected or whether submitted tasks are executed in the +order in which they were submitted. + +The :class:`dpctl.SyclQueue` class represents a queue and abstracts the +:sycl_queue:`sycl::queue <>` SYCL runtime class. + +Types of Queues +--------------- + +SYCL has a task-based execution model. The order in which a SYCL runtime +executes a task on a target device is specified by a sequence of events which +must be complete before execution of the task is allowed. Submission of a task +returns an event which can be used to further grow the graph of computational +tasks. A SYCL queue stores the needed data to manage the scheduling operations. + +Unless specified otherwise during constriction of a queue, a SYCL runtime +executes tasks whose dependencies were met in an unspecified order, with +possibility for some of the tasks to be execute concurrently. Such queues are +said to be 'out-of-order'. + +SYCL queues can be specified to indicate that runtime must execute tasks in the +order in which they were submitted. In this case, tasks submitted to such a +queue, called 'in-order' queues, are never executed concurrently. + +Creating a New Queue +-------------------- + +:class:`dpctl.SyclQueue(ctx, dev, property=None)` creates a new queue instance +for the given compatible context and device. Keyword parameter `property` can be +set to `"in_order"` to create an 'in-order' queue and to `"enable_profiling"` to +dynamically collect task execution statistics in the returned event once the +associated task completes. + +.. _fig-constructing-queue-context-device-property: + +.. literalinclude:: ../../../../../examples/python/sycl_queue.py + :language: python + :lines: 17-19, 72-89 + :caption: Constructing SyclQueue from context and device + :linenos: + +A possible output for the example +:ref:`fig-constructing-queue-context-device-property:` may be: + +.. program-output:: python ../examples/python/sycl_queue.py -r create_queue_from_subdevice_multidevice_context + +When a context is not specified the :sycl_queue:`sycl::queue <>` constructor +from a device instance is called. Instead of an instance of +:class:`dpctl.SyclDevice` the argument `dev` can be a valid filter selector +string. In this case, the :sycl_queue:`sycl::queue <>` constructor with the +corresponding :oneapi_filter_selection:`sycl::ext::oneapi::filter_selector <>` +is called. + +.. _fig-constructing-queue-filter-selector: + +.. literalinclude:: ../../../../../examples/python/sycl_queue.py + :language: python + :lines: 17-19, 27-37 + :caption: Constructing SyclQueue from filter selector + :linenos: + +A possible output for the example :ref:`fig-constructing-queue-filter-selector` +may be: + +.. program-output:: python ../examples/python/sycl_queue.py -r create_queue_from_filter_selector + + +Profiling a Task Submitted to a Queue +------------------------------------- + +The result of scheduling execution of a task on a queue is an event. An event +has several uses: it can be queried for the status of the task execution, it can +be used to order execution of the future tasks after it is complete, it can be +used to wait for execution to complete, and it can carry information to profile +of the task execution. The profiling information is only populated if the queue +used was created with the "enable_profiling" property and only becomes available +after the task execution is complete. + +The class :class:`dpctl.SyclTimer` implements a Python context manager that can +be used to collect cumulative profiling information for all the tasks submitted +to the queue of interest by functions executed within the context: + +.. code-block:: python + :caption: Example of timing execution + + import dpctl import dpctl.tensor as dpt + + q = dpctl.SyclQueue(property="enable_profiling") timer_ctx = + dpctl.SyclTimer() with timer_ctx(q): + X = dpt.arange(10**6, dtype=float, sycl_queue=q) + + host_dt, device_dt = timer_ctx.dt + +The timer leverages :oneapi_enqueue_barrier:`oneAPI enqueue_barrier SYCL +extension <>` and submits a barrier at context entrance and a barrier at context +exit and records associated events. The elapsed device time is computed as +``e_exit.profiling_info_start - e_enter.profiling_info_end``.