oneapi-src / oneapi-spec Goto Github PK

View Code? Open in Web Editor NEW

171.0 25.0 100.0 23.81 MB

oneAPI Specification source files

Home Page: https://spec.oneapi.com

License: Other

Shell 0.01% CSS 0.04% JavaScript 0.09% HTML 0.07% Python 82.07% C++ 17.19% C 0.42% Makefile 0.05% Batchfile 0.05%

accelerator parallel-programming linear-algebra video-processing analytics sycl deep-learning oneapi

oneapi-spec's Introduction

oneAPI Specifications

This repository contains the sources for the oneAPI Specification. For the latest build from main branch, see HTML and PDF.

For more information about oneAPI, see oneapi.io. For information about future releases of the oneAPI specification, see the roadmap. To be notified about new releases, become a release-only watcher of this repo.

The document is written using reStructuredText and built with Sphinx using a theme provided by Read the Docs.

License

The oneAPI specification is licensed under the Creative Commons Attribution 4.0 International License.

See LICENSE for more information.

Contribute

See CONTRIBUTING for more information.

Build the Specification

To build the specification document locally, clone this repository to your local system and follow the setup and build instructions. The setup and build steps make use of scripts/oneapi.py, a helper script for maintenance tasks. You can also look at the source if you want to see how to do the same task manually.

Setup

Install Python 3, Doxygen (>= 1.8.17), LaTeX, etc. To install on Ubuntu:

sudo scripts/install.sh

Create and activate a Python virtual environment with all required tools:

python scripts/oneapi.py spec-venv
source spec-venv/bin/activate

To install directly with pip:

pip install -r requirements.txt

To install on Windows:

python scripts\oneapi.py spec-venv
spec-venv\Scripts\activate

Build the Docs

To build the HTML document, use the following command:

python scripts/oneapi.py html

The document is organized as a book with chapters. Each element of oneAPI is its own chapter and can be built separately. For example, to build the oneVPL chapter, use the following command:

python scripts/oneapi.py html source/elements/oneVPL

To view the HTML docs, visit build/html/index.html in your browser using a file:// URL.

Build the pdf version wit the following command:

python scripts/oneapi.py latexpdf

The generated PDF will be located at build/latexpdf/oneAPI-spec.pdf.

Spell check:

python oneapi.doc. --verbose spelling

CI

We use GitHub actions. See .github/workflows/ci.yml.

PR's trigger the CI to build the document and save it as an artifact. If you are working in a fork on GitHub, commits to the main branch will build and publish the document in the GitHub pages associated with the repository.

Adding licenses to files

Use the reuse tool

Code examples:

reuse addheader --copyright "Constributors to the oneapi-spec project" --license MIT source/examples/host-task.cpp

Doc sources:

reuse addheader --copyright "Constributors to the oneapi-spec project" --license CC-BY-4.0 source/index.rst

Making a Release

Update:
- oneapi-doc.json
- releases/index.rst
Tag it.
Publish with oneAPI doc repo

oneapi-spec's People

Contributors

Stargazers

Watchers

Forkers

rsdubtso napetrov mshiryaev akukanov outoftardis rlnx michael-smirnov mkrainiuk mkinsner rscohn2 jianhui-li amgrigoriev aregm xhaihao krisdale emfomenk spencerpatty unterumarmung mikedvorskiy vepifanov sbogusev alexey-katranov gbuella ivankochin dut3062796s omalyshe aleksei-fedotov jjfumero petercad dsmertin pokhodenkosa mgouicem aelizaro mvincerx ericlars michaelvincerra onenos-com hdelassus furongzhang szha iliamish kboyarinov anton-potapov lql341 baeseung-intel jedippold igorbelyakovintel akwrobel isaevil katanaeta ddabek-i sbalint98 aaronjohnson vance423 wuxun-zhang jamesreinders vlserov rachelertl victorget tletnes huichengpeng andrewtbarker samzhangss abhilegend isabella232 mmeterel svlima6669 gitamohr gmlueck lukaszstolarczuk pavelkumbrasev b-shi valentinakats brunom sknepper jzc jonrecker rarutyun stefanbruens sudhirverma michralpeters be-secure ireshbanagar gggneo rfoo444 hjabird paveldyakov hassan20990 imartyan aepanchi jiexin-zheng gajanan-choudhary adlinke raphael-egan dantegpt rbiessy aidanbeltons andreyfe1 gyusang

oneapi-spec's Issues

DPCPP: Update extension table for 1.0

get github access for other editors

DAL: roadmap defined

TBB: Integrate sources into oneapi-spec repo

README links to staging server need to be updated

VPL: Roadmap defined

in roadmap.rst

DPL: control over sequencing by accessing buffers

In SYCL, you control sequencing when using buffers by creating accessors and declaring if they are used read-only or read-write.
It seems like dpstd::begin should be able to express the same sequencing control, but there is no discussion in the text. Is dpstd::begin always creating a read/write accessor internally? Does a for_each wait on the queue when done? What happens when I intermix accessors and dpstd::begin?

Fix github link on https://spec.oneapi.com/versions/latest/introduction.html#contribution-guidelines

DPL: USM & PSTL?

Needs some discussion of how USM & PSTL interact.
I should be able to do pass an iterator for data in USM to a for_each. I am not clear on how you would do sequencing for PSTL/PSTL as well as PSTL/direct SYCL access

DPL: roadmap defined

Add standard header to elements

Something like this, but simpler: https://w3c.github.io/manifest/

Move notices to inside cover of pdf

Error page is not being pushed to staging server

DPCPP: Update extensions table for 0.9

L0: Integrate sources into oneapi-spec repo

notices link in footer is broken

Notices link in the footer always looks in the current directory. I could find a way to make it reference top of tree. There is always a notices link in the bottom left in the contents so I will delete it instead.

Configure S3/Akamai for error page

MKL: spec refers to product manual

Check that these links are appropriate. In general, we should not refer to product docs.

./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-commit.rst:66: Functions <https://software.intel.com/en-us/onemkl-developer-refer\
ence-c-status-checking-functions>__ ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-computebackward-typename-iotype.rst:45: transform <https://software.intel.com/en\
-us/onemkl-developer-reference-c-fourier-transform-functions#FORMULA>__ ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-computebackward-typename-iotype.rst:61: C/C++ <https://software.intel.com/en-us/o\ nemkl-developer-reference-c-configuring-and-computing-an-fft-in-c-c>.
./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-computebackward-typename-iotype.rst:66: Functions <https://software.intel.com/en-\
us/onemkl-developer-reference-c-status-checking-functions>__ ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-computeforward-typename-iotype.rst:44: transform <https://software.intel.com/en-\
us/onemkl-developer-reference-c-fourier-transform-functions#FORMULA>__ ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-computeforward-typename-iotype.rst:60: C/C++ <https://software.intel.com/en-us/on\ emkl-developer-reference-c-configuring-and-computing-an-fft-in-c-c>.
./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-computeforward-typename-iotype.rst:65: Functions <https://software.intel.com/en-u\
s/onemkl-developer-reference-c-status-checking-functions>__ ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-getvalue.rst:44: DftiGetValue <https://software.intel.com/en-us/onemkl-developer\
-reference-c-dftigetvalue#BC7944B8-F01C-40C4-8EAA-6C3422C9C838>__ ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-getvalue.rst:58: Functions <https://software.intel.com/en-us/onemkl-developer-ref\ erence-c-status-checking-functions>__
./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-setvalue.rst:44: Params <https://software.intel.com/en-us/onemkl-developer-refere\
nce-c-dftisetvalue>__. ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-setvalue.rst:78: DftiSetValue <https://software.intel.com/en-us/onemkl-developer\
-reference-c-dftisetvalue#7E6778F1-D80D-4CED-82F4-90CF4600FA57>__. ./elements/oneMKL/source/domains/dft/mkl-dft-descriptor-mkl-dft-precision-mkl-dft-domain-setvalue.rst:83: Functions <https://software.intel.com/en-us/onemkl-developer-ref\ erence-c-status-checking-functions>__

Update |*_full_name| for all components to include oneAPI

Currently all names mentioned without oneAPI prefix. So it’s not matching correct legal name and require addition of oneAPI in each case.
Suggest to implement this for 0.8 version

Local memory

With the current DPC++, in order to use local memory in a device function called inside a kernel, we have to pass it as argument to the device function. Could DPC++ support static local memory (e.g., something like __local__ a[256]) anywhere in device code? Could it also support dynamic local memory (e.g., something like extern __local__ a[]) with the amount of local memory specified at runtime during kernel launch?

Level Zero: Roadmap Defined

In roadmap.rst

Add versions link

Link should always point to latest instead of current doc

Global variables

Could DPC++ support global variables in device memory and USM, and a memcpy function for copying data from host to the global variable?

DNN: sphinx warnings

python ../../../scripts/element.py html

Ignore the RemovedInSphinx30 warnings, but please fix these or let me know if you would rather I look at them.

/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneDNN/source/index.rst:100: WARNING: Duplicate declaration, dnnl::me\ mory::undef /localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneDNN/source/index.rst:100: WARNING: Duplicate declaration, dnnl::un\ def /localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneDNN/source/index.rst:100: WARNING: Duplicate declaration, dnnl::un\ def /localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneDNN/source/index.rst:100: WARNING: Duplicate declaration, dnnl::un\ def /localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneDNN/source/index.rst:100: WARNING: Duplicate declaration, dnnl::en\ gine

MKL: roadmap milestones

Populate roadmap.rst with some milestones. For example 1st drop of API descriptions in RST. Final drop.

Add Level Zero spec

Subgroup size for subgroup primitives

Querying sycl::info::device::sub_group_size gives several numbers. For example, we get 8, 16 and 32 for Gen9. We would like to specify the sub group size and this feature is supported. All three sizes seem to work except that subgroup primitives such as shuffle_down do not work for all sizes. By try and error, we have found that shuffle_down works for 16. Could oneAPI provide a query function for returning the "primitive" subgroup size?

DPCPP: Update extension table for 0.7

MKL: markup for classes is not correct

onemkl::rng::wichmann_hill
==========================


.. container::


   Wichmann-Hill pseudorandom number generator (a set of 273 basic
   generators) from NAG Numerical Libraries [NAG].


   .. container:: section
      :name: GUID-753F13BA-A3C7-4F24-90F1-14B6279BD95C


      .. rubric:: Syntax
         :class: sectiontitle


      .. container:: dlsyntaxpara


         .. cpp:function::  class wichmann_hill :         internal::engine_base<wichmann_hill>{

         .. cpp:function::  public:

         .. cpp:function::  wichmann_hill (cl::sycl::queue& queue,         std::uint32_t seed, std::uint32_t engine_idx)

         .. cpp:function::  wichmann_hill (cl::sycl::queue& queue,         std::initializer_list<std::uint32_t> seed, std::uint32_t         engine_idx)

         .. cpp:function::  wichmann_hill (const wichmann_hill& other)

         .. cpp:function::  wichmann_hill& operator=(const wichmann_hill&         other)

         .. cpp:function::  ~wichmann_hill()

         .. cpp:function::  }

         .. rubric:: Include Files

Update css

Long lines of text do not wrap properly in a table, and the reader has to scroll to see content:

There are 2 css files with identical content:

It seems that the second one should be removed.

DPL: Description of 'Specific API'

Can you write some text to describe algorithms for 'Specific API of oneDPL' If there is a product manual, you can copy from it.

From Timmie:

Yes, I can add that to the section. The description is where I'll also describe the optional parameters to the algorithms, e.g., initial values, comparators, etc. that @akukanov suggested earlier this week to reduce the number of functions we list in this section.

MKL: Malformed tables

localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/lapack/trtrs.rst:111: WARNING: Insufficient data supplied (1 row(s)); no data remaining for table body, required b\
y "list-table" directive.

.. list-table::
   :header-rows: 1

   * -     b

/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/clear_status.rst:36: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bul\
let list expected, but row 2 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * -  Status
     -  Description
   * -  Successful Execution
   * -  ``status::success``
     -  VM function execution completed successfully
   * -  ``status::not_defined``

/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/create_error_handler.rst:113: WARNING: Error parsing content block for the "list-table" directive: uniform two-\
level bullet list expected, but row 2 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * -  Status
     -  Description
   * -  Successful Execution
   * -  ``status::success``
     -  VM function execution completed successfully
   * -  ``status::not_defined``

localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/get_mode.rst:33: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet \
list expected, but row 2 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * -  Value of mode
     -  Description
   * -  Accuracy Control
   * -  ``mode::ha``
     -  High accuracy versions of VM functions.
   * -  ``mode::la``

/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/get_status.rst:34: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bulle
t list expected, but row 2 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * -  Status
     -  Description
   * -  Successful Execution
   * -  ``status::success``
     -  VM function execution completed successfully
   * -  ``status::not_defined``
     -  VM status not define

/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/set_status.rst:36: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bulle
t list expected, but row 2 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * -  Status
     -  Description
   * -  Successful Execution
   * -  ``status::success``
     -  VM function execution completed successfully
   * -  ``status::not_defined``
     -  VM status not defined
   * -  Warnings
   * -  ``status::accuracy_warning``

localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/setmode.rst:50: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet l\
ist expected, but row 2 does not contain the same number of items as row 1 (1 vs 2).

.. list-table::
   :header-rows: 1

   * -  Value of mode
     -  Description
   * -  Accuracy Control
   * -  ``mode::ha``
     -  High accuracy versions of VM functions.
   * -  ``mode::la``

TBB: Roadmap defined

in roadmap.rst

DPCPP: Update extension table for 0.8

DPC++ roadmap defined

Broken link in README

In more reading section of your README the link to the style guide is broken.

CCL: Roadmap defined

in roadmap.rst

CI Deployment to AWS bucket

Option to be less OOP in DPC++

Request to provide access to thread id, group id, memory fence, barrier functions, etc. without using an nd_item like object

Add redirect for /oneAPI/

CI in forks trying to deploy to S3

In #68 i see that corresponding fix have been created, however looks it doesn't work in some cases:

example
https://github.com/napetrov/oneapi-spec/runs/490630546

Should we use different method to validate for forks?

TBB: Roadmap defined

MKL: add exclude to mkl conf.py

mkl conf.py is not set to ignore inc.rst
Copy patter from to level conf.py

localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/vector_math.inc.rst:47: WARNING: toctree contains reference to nonexisting document 'domains/vm/vm/special-valu\
e-notations'
/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/vector_math.inc.rst:47: WARNING: toctree contains reference to nonexisting document 'domains/vm/vm/vm-mathemati\
cal-functions'
/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/vector_math.inc.rst:47: WARNING: toctree contains reference to nonexisting document 'domains/vm/vm/vm-service-f\
unctions'
/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/vector_math.inc.rst:47: WARNING: toctree contains reference to nonexisting document 'domains/vm/vm/miscellaneou\
s-vm-functions'
/localdisk/work/rscohn1/Projects/spec/oneapi-spec/source/elements/oneMKL/source/domains/vm/vector_math.inc.rst:47: WARNING: toctree contains reference to nonexisting document 'domains/vm/vm/bibliography\
'
/localdisk/work/rscohn1/Projects/spec/oneapi-sp

MKL: remove :name: with GUID

The :name: with GUID are introduced by conversion from DITA, but are not used
.. container:: section
:name: GUID-753F13BA-A3C7-4F24-90F1-14B6279BD95C

DPL: note SYCL C++ limitations

If you are doing a for_each with an execution policy that maps to sycl, the function will inherit the SYCL/DPC++ limitations for kernels. We should note that by referring to the DPC++ spec.

Recursive device function

Currently DPC++ does not support recursive function calls on device. Is it possible to add this support? It's very important for our ECP WarpX code (https://github.com/ECP-WarpX/WarpX/).

Integrate akamai purge into publishing

Host callback

Could DPC++ support adding host back functions to an ordered queue for device?

VPL: Clear doxygen warnings

Please try to clear all the doxygen warnings.
cd source/elements/oneVPL
doxygen Doxyfile /build/source/elements/oneVPL/include/vplmemory/vplm.h:339: warning: explicit link request to 'vplm_mem' could not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:339: warning: explicit link request to 'vplm_mem' could not be resolved /build/source/elements/oneVPL/include/vpl/vpl.hpp:30: warning: argument 'optional' of command @param is not found in the argument list \ of vpl::Decode::Decode(VplFourCC src_format, VplTargetDevice device=VPL_TARGET_DEVICE_DEFAULT) /build/source/elements/oneVPL/include/vpl/vpl.hpp:35: warning: The following parameter of vpl::Decode::Decode(VplFourCC src_format, Vpl\ TargetDevice device=VPL_TARGET_DEVICE_DEFAULT) is not documented: parameter 'device' /build/source/elements/oneVPL/include/vplmemory/vplm.h:339: warning: explicit link request to 'vplm_mem' could not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:339: warning: explicit link request to 'vplm_mem' could not be resolved /build/source/elements/oneVPL/include/vpl/vpl.hpp:30: warning: argument 'optional' of command @param is not found in the argument list \ of vpl::Decode::Decode(VplFourCC src_format, VplTargetDevice device=VPL_TARGET_DEVICE_DEFAULT) /build/source/elements/oneVPL/include/vpl/vpl.hpp:35: warning: The following parameter of vpl::Decode::Decode(VplFourCC src_format, Vpl\ TargetDevice device=VPL_TARGET_DEVICE_DEFAULT) is not documented: parameter 'device' /build/source/elements/oneVPL/include/vplmemory/vplm.h:294: warning: explicit link request to 'vplm_on_destroy_cb' could not be resolve\ d /build/source/elements/oneVPL/include/vplmemory/vplm.h:45: warning: explicit link request to '_vplm_status' could not be resolved <unknown>:1: warning: explicit link request to 'vplm_mem' could not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:319: warning: explicit link request to 'info' could not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:320: warning: explicit link request to 'info' could not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:324: warning: explicit link request to 'vplm_create_from_cpu_image' could not be\ resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:368: warning: explicit link request to 'vplm_unref' could not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm.h:380: warning: explicit link request to 'VPLM_PROPERTY_CALLBACK_ON_DESTROY' could\ not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm_opencl.h:102: warning: explicit link request to 'vplm_cl_begin_image_access' could\ not be resolved /build/source/elements/oneVPL/include/vplmemory/vplm_opencl.h:102: warning: explicit link request to 'vplm_cl_end_image_access' could n\ ot be resolved /build/source/elements/oneVPL/include/vplmemory/vplm_vaapi.h:59: warning: explicit link request to 'vplm_cl_begin_image_access' could n\ ot be resolved /build/source/elements/oneVPL/include/vplmemory/vplm_vaapi.h:59: warning: explicit link request to 'vplm_cl_end_image_access' could not\ be resolved

DPL: dpstd::begin

Can you write a sentence or 2 about why you need dpstd::begin vs standard C++ iterators? I think the answer is that by using buffers+dpstd::begin, data can live on the device between invocations. Also, I incorrectly assumed that you could not use C++ iterators so that would be clearer if you explained dpstd::begin.

oneapi-src / oneapi-spec Goto Github PK

oneapi-spec's Introduction

oneAPI Specifications

License

Contribute

Build the Specification

Setup

Build the Docs

CI

Adding licenses to files

Making a Release

oneapi-spec's People

Contributors

Stargazers

Watchers

Forkers

oneapi-spec's Issues

Recommend Projects

Recommend Topics

Recommend Org