diff --git a/dpctl/__init__.py b/dpctl/__init__.py index 3412040d2d..0287c9783b 100644 --- a/dpctl/__init__.py +++ b/dpctl/__init__.py @@ -1,43 +1,43 @@ +##===----------------- _memory.pyx - dpctl module -------*- Cython -*------===## +## +## Data Parallel Control (dpCtl) +## +## Copyright 2020 Intel Corporation +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +##===----------------------------------------------------------------------===## +## +## \file +## This top-level dpctl module. +## +##===----------------------------------------------------------------------===## ''' - Python Data Parallel Processing Library (PyDPPL) + Data Parallel Control (dpCtl) - PyDPPL provides a lightweight Python abstraction over DPC++/SYCL and + dpCtl provides a lightweight Python abstraction over DPC++/SYCL and OpenCL runtime objects. The DPC++ runtime wrapper objects can be accessed by importing dpctl. The OpenCL runtime wrapper objects can be accessed by importing dpctl.ocldrv. The library is in an early-beta stage of development and not yet ready for production usage. - PyDPPL's intended usage is as a common SYCL interoperability layer for + dpCtl's intended usage is as a common SYCL interoperability layer for different Python libraries and applications. The OpenCL support inside PyDPPL is slated to be deprecated and then removed in future releases of the library. Currently, only a small subset of DPC++ runtime objects are exposed - through the dpctl module. The main API classes inside the dpctl module are: - - Runtime: The class stores a global SYCL queue and a stack of - currently activated queues. Runtime provides a special getter - method to retrieve the currently activated SYCL queue - as a Py_capsule. - - A single global thread local instance of the Runtime class - is created on loading the dpctl module for the first time. - - DeviceArray: A DeviceArray object encapsulates a one-dimensional - cl::sycl::buffer object. A DeviceArray object can be - created using a NumPy ndarray. The initial implementation - of DeviceArray follows NumPy's recommended design to create - a custom array container. DeviceArray does not implement - the __array_function__ and the __array_ufunc__ interfaces. - Therefore, DeviceArray does not support NumPy Universal - functions (ufuncs). The design decision to not support - ufuncs can be revisited later if we have a need for such - functionality. For the time being, the class is only meant - as a data exchange format between Python libraries that - use SYCL. - - Global data members: - runtime - An instance of the Runtime class. + through the dpctl module. The main API classes are defined in the _sycl_core.pyx file. Please use `pydoc dpctl._sycl_core` to look at the current API for dpctl. diff --git a/dpctl/_memory.pyx b/dpctl/_memory.pyx index c790ea17ce..3edd8732bc 100644 --- a/dpctl/_memory.pyx +++ b/dpctl/_memory.pyx @@ -1,3 +1,33 @@ +##===--------------- _memory.pyx - dpctl module --------*- Cython -*-------===## +## +## Data Parallel Control (dpCtl) +## +## Copyright 2020 Intel Corporation +## +## Licensed under the Apache License, Version 2.0 (the "License"); +## you may not use this file except in compliance with the License. +## You may obtain a copy of the License at +## +## http://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, software +## distributed under the License is distributed on an "AS IS" BASIS, +## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +## See the License for the specific language governing permissions and +## limitations under the License. +## +##===----------------------------------------------------------------------===## +## +## \file +## This file implements Python buffer protocol using Sycl USM shared and host +## allocators. The USM device allocator is also exposed through this module for +## use in other Python modules. +## +##===----------------------------------------------------------------------===## + +# distutils: language = c++ +# cython: language_level=3 + import dpctl from dpctl.backend cimport * from ._sycl_core cimport SyclContext, SyclQueue diff --git a/dpctl/_sycl_core.pxd b/dpctl/_sycl_core.pxd index cb0c238318..caa18814d8 100644 --- a/dpctl/_sycl_core.pxd +++ b/dpctl/_sycl_core.pxd @@ -1,6 +1,6 @@ -##===------------- sycl_core.pxd - DPPL interface ------*- Cython -*-------===## +##===------------- sycl_core.pxd - dpctl module --------*- Cython -*-------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,9 +19,11 @@ ##===----------------------------------------------------------------------===## ## ## \file -## This file defines the Cython interface for the Sycl API of PyDPPL. +## This file declares the extension types and functions for the Cython API +## implemented in sycl_core.pyx. ## ##===----------------------------------------------------------------------===## + # distutils: language = c++ # cython: language_level=3 diff --git a/dpctl/backend.pxd b/dpctl/backend.pxd index 3584cf2e28..f15f51b529 100644 --- a/dpctl/backend.pxd +++ b/dpctl/backend.pxd @@ -1,6 +1,6 @@ -##===------------- backend.pyx - DPPL interface ------*- Cython -*-------===## +##===------------- backend.pyx - dpctl module -------*- Cython -*----------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,9 +19,11 @@ ##===----------------------------------------------------------------------===## ## ## \file -## This file defines the Cython interface for the backend API of PyDPPL. +## This file defines the Cython extern types for the functions and opaque data +## types defined by dpctl's C API. ## ##===----------------------------------------------------------------------===## + # distutils: language = c++ # cython: language_level=3 diff --git a/dpctl/ocldrv.py b/dpctl/ocldrv.py index 904a933568..82461069df 100644 --- a/dpctl/ocldrv.py +++ b/dpctl/ocldrv.py @@ -1,6 +1,6 @@ -##===---------- ocldrv.py - dpctl.ocldrv interface -----*- Python -*-----===## +##===------------- ocldrv.py - dpctl.ocldrv module ------*- Python -*------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -20,7 +20,7 @@ ### ### \file ### This file exposes Python classes for different OpenCL classes that are -### exposed by the _dppl_binding CFFI extension module. +### exposed by the _opencl_core CFFI extension module. ##===----------------------------------------------------------------------===## ''' The dpctl.ocldrv module contains a set of Python wrapper classes for OpenCL objects. The module has wrappers for cl_context, cl_device, diff --git a/dpctl/opencl_core.py b/dpctl/opencl_core.py index 327de08122..cef6b9bcc5 100644 --- a/dpctl/opencl_core.py +++ b/dpctl/opencl_core.py @@ -1,6 +1,6 @@ -##===--------- opencl_core.py - dpctl.ocldrv interface -----*- Python -*----===## +##===--------- opencl_core.py - dpctl.ocldrv interface -----*- Python -*---===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data paraller Control (dpctl) ## ## Copyright 2020 Intel Corporation ## diff --git a/dpctl/sycl_core.pyx b/dpctl/sycl_core.pyx index a74917bb62..5510309fcd 100644 --- a/dpctl/sycl_core.pyx +++ b/dpctl/sycl_core.pyx @@ -1,6 +1,6 @@ -##===------------- sycl_core.pyx - DPPL interface ------*- Cython -*-------===## +##===------------- sycl_core.pyx - dpctl module -------*- Cython -*--------===## ## -## Python Data Parallel Processing Library (PyDPPL) +## Data Parallel Control (dpCtl) ## ## Copyright 2020 Intel Corporation ## @@ -19,7 +19,7 @@ ##===----------------------------------------------------------------------===## ## ## \file -## This file implements the Cython interface for the Sycl API of PyDPPL. +## This file implements a sub-set of Sycl's interface using dpctl's CAPI. ## ##===----------------------------------------------------------------------===##