├── .github └── workflows │ └── checks.yml ├── .gitignore ├── .pre-commit-config.yaml ├── .reuse └── dep5 ├── CODE_OF_CONDUCT.rst ├── COPYING.rst ├── LICENSE.rst ├── LICENSES ├── Apache-2.0.txt └── CC-BY-4.0.txt ├── Makefile ├── README.rst ├── doc8.ini ├── readthedocs.yml ├── reference └── headers │ ├── Readme.txt │ ├── accessMode.h │ ├── accessTarget.h │ ├── accessorBuffer.h │ ├── accessorImage.h │ ├── accessorLocal.h │ ├── atomic.h │ ├── atomicoperations.h │ ├── buffer.h │ ├── commandGroup.h │ ├── commandGroupHandler.h │ ├── common-byval.h │ ├── common-reference.h │ ├── context.h │ ├── contextInfo.h │ ├── device.h │ ├── deviceEvent.h │ ├── deviceInfo.h │ ├── deviceSelector.h │ ├── deviceSelectorInterface.h │ ├── event.h │ ├── eventInfo.h │ ├── exception.h │ ├── group.h │ ├── hitem.h │ ├── id.h │ ├── image.h │ ├── item.h │ ├── kernelInfo.h │ ├── kernelWIP.h │ ├── multipointer.h │ ├── ndRange.h │ ├── nditem.h │ ├── openclcInterop.h │ ├── parallelFor.h │ ├── paramTraits.h │ ├── platform.h │ ├── platformInfo.h │ ├── pointer.h │ ├── priv.h │ ├── programInfo.h │ ├── programWIP.h │ ├── properties.h │ ├── queue.h │ ├── queueInfo.h │ ├── range.h │ ├── sampler.h │ ├── stlclasses.h │ ├── stream.h │ ├── synchronization.h │ └── vec.h ├── requirements.txt ├── source ├── _static │ ├── Khronos_Group_SYCL_logo.pdf │ ├── Khronos_Group_SYCL_logo.svg │ ├── custom.css │ └── favicon.png ├── backends.rst ├── built-in-functions.rst ├── class-availability.rst ├── common.rst ├── conf.py ├── data-types.rst ├── data.rst ├── error.rst ├── examples │ ├── CMakeLists.txt │ ├── async-handler.cpp │ ├── async-handler.out │ ├── atomic.cpp │ ├── atomic.out │ ├── context.cpp │ ├── context.out │ ├── creating-sub-buffers.cpp │ ├── creating-sub-buffers.out │ ├── def_kernels_lambda.cpp │ ├── def_kernels_named_function_obj.cpp │ ├── def_kernels_named_function_obj.out │ ├── event-elapsed-time.cpp │ ├── event-elapsed-time.out │ ├── exception-handling.cpp │ ├── exception-handling.out │ ├── get-platforms.cpp │ ├── get-platforms.out │ ├── get_devices.cpp │ ├── get_devices.out │ ├── gpu-platform.cpp │ ├── gpu-selector.cpp │ ├── gpu-selector.out │ ├── handler-copy.cpp │ ├── handler-copy.out │ ├── host-task.cpp │ ├── host-task.out │ ├── private_memory_example.cpp │ ├── private_memory_example.out │ ├── queue-parallel.cpp │ ├── queue-parallel.out │ ├── queue-single-task.cpp │ ├── queue-single-task.out │ ├── reduce-alg-lib.cpp │ ├── reduce-alg-lib.out │ ├── specialization-constants.cpp │ ├── specialization-constants.out │ ├── std-vector.cpp │ ├── std-vector.out │ ├── stream.cpp │ ├── stream.out │ ├── usm-device.cpp │ ├── usm-implicit-data-movement.cpp │ ├── usm-implicit-data-movement.out │ └── usm-shared.cpp ├── generic-and-non-generic.rst ├── header-file.rst ├── host-task.rst ├── iface │ ├── accessor-concept.rst │ ├── accessors.rst │ ├── address-space.rst │ ├── async_handler.rst │ ├── atomic-types.rst │ ├── atomic_ref.rst │ ├── backend_interop.rst │ ├── barriers-and-fences.rst │ ├── buffer.rst │ ├── command-accessor.rst │ ├── command-group-handler.rst │ ├── common-byval.rst │ ├── common-functions.rst │ ├── common-reference.rst │ ├── context.rst │ ├── defining-kernels.rst │ ├── device-selector.rst │ ├── device.rst │ ├── device_event.rst │ ├── device_image.rst │ ├── error-handling-rules.rst │ ├── event.rst │ ├── exception.rst │ ├── function-objects.rst │ ├── geometric-functions.rst │ ├── group-algorithms-library.rst │ ├── group-functions.rst │ ├── group.rst │ ├── h_item.rst │ ├── half-prec-math-func.rst │ ├── host-allocation.rst │ ├── host-task-add-to-handler.rst │ ├── host-task-basic.rst │ ├── host_accessor.rst │ ├── id.rst │ ├── image-sampler.rst │ ├── image.rst │ ├── integer-functions.rst │ ├── interaction-with-host-code.rst │ ├── interop_handle.rst │ ├── item-classes.rst │ ├── item.rst │ ├── kernel-bundles.rst │ ├── kernel.rst │ ├── local_accessor.rst │ ├── math-array-types.rst │ ├── math-functions.rst │ ├── native-prec-math-func.rst │ ├── nd_item.rst │ ├── nd_range.rst │ ├── platform.rst │ ├── private_memory.rst │ ├── properties.rst │ ├── queue.rst │ ├── range.rst │ ├── ranges.rst │ ├── reduction-variables.rst │ ├── relational-functions.rst │ ├── sampled-image-accessor.rst │ ├── scalar-types.rst │ ├── specialization-constants.rst │ ├── stream.rst │ ├── stream_manipulator.rst │ ├── sub_group.rst │ ├── synchronization-primitives.rst │ ├── unsampled-image-accessor.rst │ ├── usm_allocations.rst │ ├── usm_basic_concept.rst │ ├── usm_pointer_queries.rst │ └── vector-types.rst ├── index.rst ├── io.rst ├── namespaces.rst ├── parallelism.rst ├── runtime.rst ├── spelling_wordlist.txt ├── synchronization.rst └── usm.rst └── updates ├── descriptions.rst └── update-1.2.1.rst /.github/workflows/checks.yml: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: Apache-2.0 4 | 5 | name: Checks 6 | 7 | on: 8 | push: 9 | branches: 10 | - main 11 | 12 | pull_request: 13 | 14 | jobs: 15 | checks: 16 | runs-on: ubuntu-latest 17 | steps: 18 | - uses: actions/checkout@v4 19 | - uses: actions/setup-python@v5 20 | with: 21 | python-version: '3.12' 22 | cache: 'pip' 23 | - run: pip install -r requirements.txt 24 | - name: Checks 25 | uses: pre-commit/action@v3.0.1 26 | - uses: actions/upload-artifact@v4 27 | if: always() 28 | with: 29 | name: docs 30 | path: build 31 | 32 | icpx: 33 | runs-on: ubuntu-latest 34 | env: 35 | CXX: icpx 36 | steps: 37 | - uses: actions/checkout@v4 38 | - uses: rscohn2/setup-oneapi@v0 39 | with: 40 | components: | 41 | icx@2023.2.1 42 | - name: Build Examples 43 | run: | 44 | source /opt/intel/oneapi/setvars.sh 45 | cd source/examples 46 | cmake -B build 47 | make -j 2 -C build 48 | ctest --test-dir build --label-exclude gpu 49 | 50 | # Upload the HTML output from the build as a GitHub Pages artifact 51 | # This does not publish the artifact to GitHub Pages, it just gets it ready. 52 | upload-pages: 53 | runs-on: ubuntu-latest 54 | # Run only after checks are successful. 55 | # Run only when commits are pushed to the main branch 56 | # (not when a PR is opened). 57 | needs: [checks, icpx] 58 | if: ${{ github.event_name == 'push' }} 59 | steps: 60 | - uses: actions/download-artifact@v4 61 | with: 62 | name: docs 63 | - uses: actions/upload-pages-artifact@v3 64 | with: 65 | path: html 66 | 67 | # Publish the GitHub Pages artifact on GitHub Pages 68 | publish-pages: 69 | runs-on: ubuntu-latest 70 | needs: upload-pages 71 | # These permissions are required by "actions/deploy-pages". 72 | permissions: 73 | pages: write 74 | id-token: write 75 | # Do not allow two jobs to publish simultaneously. 76 | concurrency: 77 | group: "pages" 78 | cancel-in-progress: false 79 | environment: 80 | name: github-pages 81 | url: ${{ steps.deployment.outputs.page_url }} 82 | steps: 83 | - uses: actions/deploy-pages@v4 84 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Copyright 2024 The Khronos Group Inc. 2 | # SPDX-License-Identifier: Apache-2.0 3 | 4 | *~ 5 | *.log 6 | *.diff 7 | /build 8 | # python virtual environment 9 | /venv 10 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: Apache-2.0 4 | 5 | # See https://pre-commit.com for more information 6 | # See https://pre-commit.com/hooks.html for more hooks 7 | 8 | exclude: reference|LICENSES 9 | 10 | repos: 11 | - repo: https://github.com/pre-commit/mirrors-clang-format 12 | rev: v16.0.6 13 | hooks: 14 | - id: clang-format 15 | 16 | - repo: https://github.com/ambv/black 17 | rev: 23.7.0 18 | hooks: 19 | - id: black 20 | args: ['--line-length=79'] 21 | 22 | - repo: https://github.com/pre-commit/pre-commit-hooks 23 | rev: v4.4.0 24 | hooks: 25 | - id: trailing-whitespace 26 | - id: end-of-file-fixer 27 | - id: mixed-line-ending 28 | - id: check-xml 29 | - id: check-yaml 30 | - id: check-case-conflict 31 | - id: check-toml 32 | - id: check-json 33 | - id: check-added-large-files 34 | args: ['--maxkb=800'] 35 | 36 | - repo: https://github.com/pycqa/flake8 37 | rev: 6.1.0 38 | hooks: 39 | - id: flake8 40 | 41 | - repo: https://github.com/pycqa/doc8 42 | rev: v1.1.1 43 | hooks: 44 | - id: doc8 45 | 46 | - repo: https://github.com/pycqa/isort 47 | rev: 5.12.0 48 | hooks: 49 | - id: isort 50 | 51 | - repo: https://github.com/fsfe/reuse-tool 52 | rev: v2.1.0 53 | hooks: 54 | - id: reuse 55 | 56 | - repo: https://github.com/cheshirekow/cmake-format-precommit 57 | rev: v0.6.13 58 | hooks: 59 | - id: cmake-format 60 | 61 | - repo: local 62 | hooks: 63 | - id: sphinx 64 | name: sphinx 65 | entry: make spelling html linkcheck 66 | language: system 67 | pass_filenames: false 68 | always_run: true 69 | -------------------------------------------------------------------------------- /.reuse/dep5: -------------------------------------------------------------------------------- 1 | Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ 2 | Upstream-Name: SYCL Reference 3 | Upstream-Contact: Robert Cohn 4 | Source: 5 | 6 | # Sample paragraph, commented out: 7 | # 8 | # Files: src/* 9 | # Copyright: $YEAR $NAME <$CONTACT> 10 | # License: ... 11 | 12 | Files: source/_static/Khronos_Group_SYCL_logo.* source/_static/favicon.png 13 | Copyright: 2024 The Khronos Group Inc. 14 | License: CC-BY-4.0 15 | 16 | Files: ubuntu-packages.txt reference/headers/* 17 | Copyright: 2024 The Khronos Group Inc. 18 | License: Apache-2.0 19 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.rst: -------------------------------------------------------------------------------- 1 | .. SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | .. 3 | .. SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ================= 6 | Code of Conduct 7 | ================= 8 | 9 | A reminder that this issue tracker is managed by the Khronos Group. 10 | Interactions here should follow the `Khronos Code of Conduct 11 | `__ which 12 | prohibits aggressive or derogatory language. Please keep the 13 | discussion friendly and civil. 14 | -------------------------------------------------------------------------------- /COPYING.rst: -------------------------------------------------------------------------------- 1 | ============================================== 2 | COPYING file for KhronosGroup/SYCL_Reference 3 | ============================================== 4 | 5 | Licenses 6 | ======== 7 | 8 | * The source files (in rST and other formats) for the SYCL reference 9 | are licensed under the Creative Commons Attribution 4.0 10 | International License (SPDX license identifier “CC-BY-4.0”). 11 | 12 | * The code examples used in the the SYCL reference and support scripts 13 | are licensed under the Apache License, Version 2.0 (SPDX license 14 | identifier “Apache-2.0”). 15 | 16 | * The ref directory contains copies of header file from the SYCL 17 | specification and SYCL implementations. They are not used to build 18 | the document. I look at the header files to see the interface. They 19 | have their own licenses. 20 | -------------------------------------------------------------------------------- /LICENSE.rst: -------------------------------------------------------------------------------- 1 | ========================================================== 2 | LICENSE file for the KhronosGroup/SYCL_Reference project 3 | ========================================================== 4 | 5 | Files in this repository fall under one of these licenses: 6 | 7 | * SPDX license identifier: "`CC-BY-4.0`" 8 | 9 | * Creative Commons Attribution 4.0 International 10 | * For document sources 11 | 12 | * SPDX license identifier: "`Apache-2.0`" 13 | 14 | * Apache License 2.0 15 | * For code examples and scripts 16 | 17 | Full license text of these licenses is available at: 18 | 19 | * Apache-2.0: https://opensource.org/licenses/Apache-2.0 20 | * CC-BY-4.0: https://creativecommons.org/licenses/by/4.0/legalcode 21 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Copyright 2024 The Khronos Group Inc. 2 | # SPDX-License-Identifier: Apache-2.0 3 | 4 | # Minimal makefile for Sphinx documentation 5 | # 6 | 7 | # You can set these variables from the command line, and also 8 | # from the environment for the first two. 9 | SPHINXOPTS ?= -W -n -N 10 | SPHINXBUILD ?= sphinx-build 11 | SOURCEDIR = source 12 | BUILDDIR = build 13 | 14 | 15 | # Put it first so that "make" without argument is like "make help". 16 | help: 17 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 18 | 19 | .PHONY: help Makefile 20 | 21 | # Catch-all target: route all unknown targets to Sphinx using the new 22 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 23 | %: Makefile 24 | LATEXOPTS="-interaction=nonstopmode -halt-on-error" LATEXMKOPTS=--silent $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 25 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ========================== 6 | SYCL Language Reference 7 | ========================== 8 | 9 | .. image:: https://github.com/KhronosGroup/SYCL_Reference/actions/workflows/checks.yml/badge.svg 10 | :target: https://github.com/KhronosGroup/SYCL_Reference/actions/workflows/checks.yml 11 | 12 | This document is incomplete and inconsistent in the current state, as 13 | work is ongoing to update it. Please do not use as a reference or 14 | propose bug fixes at the moment, since the content is being updated 15 | and is known to be in an inconsistent state. See `SYCL specification`_ 16 | for reference documentation for SYCL. 17 | 18 | Resolving Errors When Submitting a PR 19 | ===================================== 20 | 21 | The ``checks`` job in GitHub Actions runs some static tests with the 22 | ``pre-commit`` python package. You can resolve issues faster by 23 | running the checks locally before submitting the PR. 24 | 25 | Run pre-commit checks:: 26 | 27 | pre-commit run --all 28 | 29 | Do pre-commit testing as part of ``git commit``:: 30 | 31 | pre-commit install 32 | 33 | To do a commit without running checks:: 34 | 35 | git commit -n -m 'Commit message' 36 | 37 | To skip a single test, e.g. sphinx:: 38 | 39 | SKIP=sphinx pre-commit run --all 40 | 41 | ``pre-commit`` will automatically fix most issues. After 42 | ``pre-commit`` finds and fixes issues, do a ``git add`` to add the 43 | changes and run ``pre-commit`` or ``git commit`` again. You must 44 | manually fix spelling errors, broken links, and long lines. 45 | 46 | To resolve spelling errors, you can manually run the spell checker:: 47 | 48 | make spelling 49 | 50 | Unrecognized words ``spelling_wordlist.txt``. If the spell checker is 51 | warning about code, it means you have not properly delimited the code 52 | in the rst. Do not add it to ``spelling_wordlist.txt`` add, back 53 | quotes or other delimeters so it will be ignored. 54 | 55 | .. _`SYCL specification`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html 56 | -------------------------------------------------------------------------------- /doc8.ini: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: Apache-2.0 4 | 5 | [doc8] 6 | 7 | ignore-path=reference,LICENSES,build,updates 8 | -------------------------------------------------------------------------------- /readthedocs.yml: -------------------------------------------------------------------------------- 1 | # Copyright 2024 The Khronos Group Inc. 2 | # SPDX-License-Identifier: Apache-2.0 3 | 4 | # .readthedocs.yml 5 | # Read the Docs configuration file 6 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 7 | 8 | # Required 9 | version: 2 10 | 11 | # Optionally build your docs in additional formats such as PDF 12 | formats: all 13 | 14 | # Optionally set the version of Python and requirements required to build your docs 15 | python: 16 | install: 17 | - requirements: requirements.txt 18 | -------------------------------------------------------------------------------- /reference/headers/Readme.txt: -------------------------------------------------------------------------------- 1 | SYCL headers 2 | ------------- 3 | 4 | These headers are provided as part of the specification document, for the purpose of provinding 5 | a common interface for the SYCL system. -------------------------------------------------------------------------------- /reference/headers/accessMode.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace access { 18 | enum class mode { 19 | read = 1024, 20 | write, 21 | read_write, 22 | discard_write, 23 | discard_read_write, 24 | atomic 25 | }; 26 | } // namespace access 27 | } // namespace sycl 28 | } // namespace cl 29 | -------------------------------------------------------------------------------- /reference/headers/accessTarget.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace access { 18 | enum class target { 19 | global_buffer = 2014, 20 | constant_buffer, 21 | local, 22 | image, 23 | host_buffer, 24 | host_image, 25 | image_array 26 | }; 27 | 28 | } // namespace access 29 | } // namespace sycl 30 | } // namespace cl 31 | -------------------------------------------------------------------------------- /reference/headers/accessorImage.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 20 | class accessor { 21 | public: 22 | using value_type = dataT; 23 | using reference = dataT &; 24 | using const_reference = const dataT &; 25 | 26 | /* Available only when: accessTarget == access::target::host_image */ 27 | template 28 | accessor(image &imageRef, 29 | const property_list &propList = {}); 30 | 31 | /* Available only when: accessTarget == access::target::image */ 32 | template 33 | accessor(image &imageRef, 34 | handler &commandGroupHandlerRef, const property_list &propList = {}); 35 | 36 | /* Available only when: accessTarget == access::target::image_array && 37 | dimensions < 3 */ 38 | template 39 | accessor(image &imageRef, 40 | handler &commandGroupHandlerRef, const property_list &propList = {}); 41 | 42 | /* -- common interface members -- */ 43 | 44 | /* -- property interface members -- */ 45 | 46 | size_t get_count() const; 47 | 48 | /* Available only when: (accessTarget != 49 | access::target::image_array) */ 50 | range get_range() const; 51 | 52 | /* Available only when: (accessTarget == 53 | access::target::image_array) */ 54 | range get_range() const; 55 | 56 | /* Available only when: (accessTarget == access::target::image && 57 | accessMode == access::mode::read) || (accessTarget == 58 | access::target::host_image && (accessMode == access::mode::read || 59 | accessMode == access::mode::read_write)) */ 60 | template 61 | dataT read(const coordT &coords) const; 62 | 63 | /* Available only when: (accessTarget == access::target::image && 64 | accessMode == access::mode::read) || (accessTarget == 65 | access::target::host_image && (accessMode == access::mode::read || 66 | accessMode == access::mode::read_write)) */ 67 | template 68 | dataT read(const coordT &coords, const sampler &smpl) const; 69 | 70 | /* Available only when: (accessTarget == access::target::image && 71 | (accessMode == access::mode::write || accessMode == access::mode::discard_write)) || 72 | (accessTarget == access::target::host_image && (accessMode == access::mode::write || 73 | accessMode == access::mode::discard_write || accessMode == access::mode::read_write)) */ 74 | template 75 | void write(const coordT &coords, const dataT &color) const; 76 | 77 | /* Available only when: accessTarget == access::target::image_array && 78 | dimensions < 3 */ 79 | __image_array_slice__ operator[](size_t index) const 80 | }; 81 | } // namespace sycl 82 | } // namespace cl 83 | -------------------------------------------------------------------------------- /reference/headers/accessorLocal.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 20 | class accessor { 21 | public: 22 | using value_type = dataT; 23 | using reference = dataT &; 24 | using const_reference = const dataT &; 25 | 26 | /* Available only when: dimensions == 0 */ 27 | accessor(handler &commandGroupHandlerRef, 28 | const property_list &propList = {}); 29 | 30 | /* Available only when: dimensions > 0 */ 31 | accessor(range allocationSize, handler &commandGroupHandlerRef, 32 | const property_list &propList = {}); 33 | 34 | /* -- common interface members -- */ 35 | 36 | /* -- property interface members -- */ 37 | 38 | size_t get_size() const; 39 | 40 | size_t get_count() const; 41 | 42 | range get_range() const; 43 | 44 | /* Available only when: accessMode == access::mode::read_write && dimensions == 0) */ 45 | operator dataT &() const; 46 | 47 | /* Available only when: accessMode == access::mode::read_write && dimensions > 0) */ 48 | dataT &operator[](id index) const; 49 | 50 | /* Available only when: accessMode == access::mode::read_write && dimensions == 1) */ 51 | dataT &operator[](size_t index) const; 52 | 53 | /* Available only when: accessMode == access::mode::atomic && dimensions == 54 | 0 */ 55 | operator atomic () const; 56 | 57 | /* Available only when: accessMode == access::mode::atomic && dimensions > 58 | 0 */ 59 | atomic operator[]( 60 | id index) const; 61 | 62 | /* Available only when: accessMode == access::mode::atomic && dimensions == 63 | 1 */ 64 | atomic operator[]( 65 | size_t index) const; 66 | 67 | /* Available only when: dimensions > 1 */ 68 | __unspecified__ &operator[](size_t index) const; 69 | 70 | /* Available only when: accessTarget == access::target::local */ 71 | local_ptr get_pointer() const; 72 | }; 73 | } // namespace sycl 74 | } // namespace cl 75 | -------------------------------------------------------------------------------- /reference/headers/atomic.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | enum class memory_order : int { 18 | relaxed 19 | }; 20 | 21 | template 23 | class atomic { 24 | public: 25 | template 26 | atomic(multi_ptr ptr); 27 | 28 | void store(T operand, memory_order memoryOrder = 29 | memory_order::relaxed); 30 | 31 | T load(memory_order memoryOrder = memory_order::relaxed) const; 32 | 33 | T exchange(T operand, memory_order memoryOrder = 34 | memory_order::relaxed); 35 | 36 | /* Available only when: T != float */ 37 | bool compare_exchange_strong(T &expected, T desired, 38 | memory_order successMemoryOrder = memory_order::relaxed, 39 | memory_order failMemoryOrder = memory_order::relaxed); 40 | 41 | /* Available only when: T != float */ 42 | T fetch_add(T operand, memory_order memoryOrder = 43 | memory_order::relaxed); 44 | 45 | /* Available only when: T != float */ 46 | T fetch_sub(T operand, memory_order memoryOrder = 47 | memory_order::relaxed); 48 | 49 | /* Available only when: T != float */ 50 | T fetch_and(T operand, memory_order memoryOrder = 51 | memory_order::relaxed); 52 | 53 | /* Available only when: T != float */ 54 | T fetch_or(T operand, memory_order memoryOrder = 55 | memory_order::relaxed); 56 | 57 | /* Available only when: T != float */ 58 | T fetch_xor(T operand, memory_order memoryOrder = 59 | memory_order::relaxed); 60 | 61 | /* Available only when: T != float */ 62 | T fetch_min(T operand, memory_order memoryOrder = 63 | memory_order::relaxed); 64 | 65 | /* Available only when: T != float */ 66 | T fetch_max(T operand, memory_order memoryOrder = 67 | memory_order::relaxed); 68 | }; 69 | } // namespace sycl 70 | } // namespace cl 71 | -------------------------------------------------------------------------------- /reference/headers/atomicoperations.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | void atomic_store(atomic object, T operand, memory_order memoryOrder = 19 | memory_order::relaxed); 20 | 21 | template 22 | T atomic_load(atomic object, memory_order memoryOrder = 23 | memory_order::relaxed); 24 | 25 | template 26 | T atomic_exchange(atomic object, T operand, memory_order memoryOrder = 27 | memory_order::relaxed); 28 | 29 | template 30 | bool atomic_compare_exchange_strong(atomic object, T &expected, T desired, 31 | memory_order successMemoryOrder = memory_order::relaxed, 32 | memory_order failMemoryOrder = memory_order::relaxed); 33 | 34 | template 35 | T atomic_fetch_add(atomic object, T operand, memory_order memoryOrder = 36 | memory_order::relaxed); 37 | 38 | template 39 | T atomic_fetch_sub(atomic object, T operand, memory_order memoryOrder = 40 | memory_order::relaxed); 41 | 42 | template 43 | T atomic_fetch_and(atomic object, T operand, memory_order memoryOrder = 44 | memory_order::relaxed); 45 | 46 | template 47 | T atomic_fetch_or(atomic object, T operand, memory_order memoryOrder = 48 | memory_order::relaxed); 49 | 50 | template 51 | T atomic_fetch_xor(atomic object, T operand, memory_order memoryOrder = 52 | memory_order::relaxed); 53 | 54 | template 55 | T atomic_fetch_min(atomic object, T operand, memory_order memoryOrder = 56 | memory_order::relaxed); 57 | 58 | template 59 | T atomic_fetch_max(atomic object, T operand, memory_order memoryOrder = 60 | memory_order::relaxed); 61 | } // namespace sycl 62 | } // namespace cl 63 | -------------------------------------------------------------------------------- /reference/headers/buffer.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace property { 18 | namespace buffer { 19 | class use_host_ptr { 20 | public: 21 | use_host_ptr() = default; 22 | }; 23 | 24 | class use_mutex { 25 | public: 26 | use_mutex(mutex_class &mutexRef); 27 | 28 | mutex_class *get_mutex_ptr() const; 29 | }; 30 | 31 | class context_bound { 32 | public: 33 | context_bound(context boundContext); 34 | 35 | context get_context() const; 36 | }; 37 | } // namespace buffer 38 | } // namespace property 39 | 40 | template 42 | class buffer { 43 | public: 44 | using value_type = T; 45 | using reference = value_type &; 46 | using const_reference = const value_type &; 47 | using allocator_type = AllocatorT; 48 | 49 | buffer(const range &bufferRange, 50 | const property_list &propList = {}); 51 | 52 | buffer(const range &bufferRange, AllocatorT allocator, 53 | const property_list &propList = {}); 54 | 55 | buffer(T *hostData, const range &bufferRange, 56 | const property_list &propList = {}); 57 | 58 | buffer(T *hostData, const range &bufferRange, 59 | AllocatorT allocator, const property_list &propList = {}); 60 | 61 | buffer(const T *hostData, const range &bufferRange, 62 | const property_list &propList = {}); 63 | 64 | buffer(const T *hostData, const range &bufferRange, 65 | AllocatorT allocator, const property_list &propList = {}); 66 | 67 | buffer(const shared_ptr_class &hostData, 68 | const range &bufferRange, AllocatorT allocator, 69 | const property_list &propList = {}); 70 | 71 | buffer(const shared_ptr_class &hostData, 72 | const range &bufferRange, 73 | const property_list &propList = {}); 74 | 75 | template 76 | buffer(InputIterator first, InputIterator last, AllocatorT allocator, 77 | const property_list &propList = {}); 78 | 79 | template 80 | buffer(InputIterator first, InputIterator last, 81 | const property_list &propList = {}); 82 | 83 | buffer(buffer b, const id &baseIndex, 84 | const range &subRange); 85 | 86 | /* Available only when: dimensions == 1. */ 87 | buffer(cl_mem clMemObject, const context &syclContext, 88 | event availableEvent = {}); 89 | 90 | /* -- common interface members -- */ 91 | 92 | /* -- property interface members -- */ 93 | 94 | range get_range() const; 95 | 96 | size_t get_count() const; 97 | 98 | size_t get_size() const; 99 | 100 | AllocatorT get_allocator() const; 101 | 102 | template 103 | accessor get_access( 104 | handler &commandGroupHandler); 105 | 106 | template 107 | accessor get_access(); 108 | 109 | template 110 | accessor get_access( 111 | handler &commandGroupHandler, range accessRange, 112 | id accessOffset = {}); 113 | 114 | template 115 | accessor get_access( 116 | range accessRange, id accessOffset = {}); 117 | 118 | template 119 | void set_final_data(Destination finalData = nullptr); 120 | 121 | void set_write_back(bool flag = true); 122 | 123 | bool is_sub_buffer() const; 124 | 125 | template 126 | buffer 127 | reinterpret(range reinterpretRange) const; 128 | 129 | }; 130 | } // namespace sycl 131 | } // namespace cl 132 | -------------------------------------------------------------------------------- /reference/headers/commandGroup.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class command_group { 18 | public: 19 | template 20 | command_group(queue &primaryQueue, const functorT &lambda); 21 | 22 | template 23 | command_group(queue &primaryQueue, queue &secondaryQueue, 24 | const functorT &lambda); 25 | 26 | ~command_group(); 27 | 28 | event start_event(); 29 | 30 | event kernel_event(); 31 | 32 | event complete_event(); 33 | }; 34 | } // namespace sycl 35 | } // namespace cl 36 | -------------------------------------------------------------------------------- /reference/headers/commandGroupHandler.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | class handler { 19 | private: 20 | 21 | // implementation defined constructor 22 | handler(___unspecified___); 23 | 24 | public: 25 | 26 | template 28 | void require(accessor acc); 30 | 31 | //----- OpenCL interoperability interface 32 | // 33 | template 34 | void set_arg(int argIndex, T && arg); 35 | 36 | template 37 | void set_args(Ts &&... args); 38 | 39 | //------ Kernel dispatch API 40 | // 41 | // Note: In all Kernel dispatch functions, 42 | // when using a functor with a globally visible name 43 | // the template parameter:"typename kernelName" can be ommitted 44 | // and the kernelType can be used instead. 45 | // 46 | template 47 | void single_task(KernelType kernelFunc); 48 | 49 | template 50 | void parallel_for(range numWorkItems, KernelType kernelFunc); 51 | 52 | template 53 | void parallel_for(range numWorkItems, 54 | id workItemOffset, KernelType kernelFunc); 55 | 56 | template 57 | void parallel_for(nd_range executionRange, KernelType kernelFunc); 58 | 59 | template 60 | void parallel_for_work_group(range numWorkGroups, 61 | WorkgroupFunctionType kernelFunc); 62 | 63 | template 64 | void parallel_for_work_group(range numWorkGroups, 65 | range workGroupSize, 66 | WorkgroupFunctionType kernelFunc); 67 | 68 | void single_task(kernel syclKernel); 69 | 70 | template 71 | void parallel_for(range numWorkItems, kernel syclKernel); 72 | 73 | template 74 | void parallel_for(range numWorkItems, 75 | id workItemOffset, kernel syclKernel); 76 | 77 | template 78 | void parallel_for(nd_range ndRange, kernel syclKernel); 79 | 80 | //------ Explicit memory operation APIs 81 | // 82 | template 84 | void copy(accessor src, 85 | shared_ptr_class dest); 86 | 87 | template 89 | void copy(shared_ptr_class src, 90 | accessor dest); 91 | 92 | template 94 | void copy(accessor src, 95 | T_dest *dest); 96 | 97 | template 99 | void copy(const T_src *src, 100 | accessor dest); 101 | 102 | template 104 | void copy(accessor src, 105 | accessor dest); 106 | 107 | template 108 | void update_host(accessor acc); 109 | 110 | template 111 | void fill(accessor dest, const T& src); 112 | 113 | }; 114 | } // namespace sycl 115 | } // namespace cl 116 | -------------------------------------------------------------------------------- /reference/headers/common-byval.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | class T { 19 | ... 20 | 21 | public: 22 | // If any of the following five special member functions are not 23 | // public, inline or defaulted, then all five of them should be 24 | // explicitly declared (see rule of five). 25 | // Otherwise, none of them should be explicitly declared 26 | // (see rule of zero). 27 | 28 | // T(const T &rhs); 29 | 30 | // T(T &&rhs); 31 | 32 | // T &operator=(const T &rhs); 33 | 34 | // T &operator=(T &&rhs); 35 | 36 | // ~T(); 37 | 38 | ... 39 | 40 | friend bool operator==(const T &lhs, const T &rhs) { /* ... */ } 41 | 42 | friend bool operator!=(const T &lhs, const T &rhs) { /* ... */ } 43 | 44 | ... 45 | }; 46 | } // namespace sycl 47 | } // namespace cl 48 | -------------------------------------------------------------------------------- /reference/headers/common-reference.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | class T { 19 | ... 20 | 21 | public: 22 | T(const T &rhs); 23 | 24 | T(T &&rhs); 25 | 26 | T &operator=(const T &rhs); 27 | 28 | T &operator=(T &&rhs); 29 | 30 | ~T(); 31 | 32 | ... 33 | 34 | friend bool operator==(const T &lhs, const T &rhs) { /* ... */ } 35 | 36 | friend bool operator!=(const T &lhs, const T &rhs) { /* ... */ } 37 | 38 | ... 39 | }; 40 | } // namespace sycl 41 | } // namespace cl 42 | -------------------------------------------------------------------------------- /reference/headers/context.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class context { 18 | public: 19 | explicit context(const property_list &propList = {}); 20 | 21 | context(async_handler asyncHandler, 22 | const property_list &propList = {}); 23 | 24 | context(const device &dev, const property_list &propList = {}); 25 | 26 | context(const device &dev, async_handler asyncHandler, 27 | const property_list &propList = {}); 28 | 29 | context(const platform &plt, const property_list &propList = {}); 30 | 31 | context(const platform &plt, async_handler asyncHandler, 32 | const property_list &propList = {}); 33 | 34 | context(const vector_class &deviceList, 35 | const property_list &propList = {}); 36 | 37 | context(const vector_class &deviceList, 38 | async_handler asyncHandler, const property_list &propList = {}); 39 | 40 | context(cl_context clContext, async_handler asyncHandler = {}); 41 | 42 | /* -- common interface members -- */ 43 | 44 | /* -- property interface members -- */ 45 | 46 | cl_context get() const; 47 | 48 | bool is_host() const; 49 | 50 | platform get_platform() const; 51 | 52 | vector_class get_devices() const; 53 | 54 | template 55 | typename info::param_traits::return_type get_info() const; 56 | }; 57 | } // namespace sycl 58 | } // namespace cl 59 | -------------------------------------------------------------------------------- /reference/headers/contextInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | enum class context : int { 19 | reference_count, 20 | platform, 21 | devices 22 | }; 23 | } // info 24 | } // sycl 25 | } // cl 26 | -------------------------------------------------------------------------------- /reference/headers/device.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class device { 18 | public: 19 | device(); 20 | 21 | explicit device(cl_device_id deviceId); 22 | 23 | explicit device(const device_selector &deviceSelector); 24 | 25 | /* -- common interface members -- */ 26 | 27 | cl_device_id get() const; 28 | 29 | bool is_host() const; 30 | 31 | bool is_cpu() const; 32 | 33 | bool is_gpu() const; 34 | 35 | bool is_accelerator() const; 36 | 37 | platform get_platform() const; 38 | 39 | template 40 | typename info::param_traits::return_type 41 | get_info() const; 42 | 43 | bool has_extension(const string_class &extension) const; 44 | 45 | // Available only when prop == info::partition_property::partition_equally 46 | template 47 | vector_class create_sub_devices(size_t nbSubDev) const; 48 | 49 | // Available only when prop == info::partition_property::partition_by_counts 50 | template 51 | vector_class create_sub_devices(const vector_class &counts) const; 52 | 53 | // Available only when prop == info::partition_property::partition_by_affinity_domain 54 | template 55 | vector_class create_sub_devices(info::affinity_domain affinityDomain) const; 56 | 57 | static vector_class get_devices( 58 | info::device_type deviceType = info::device_type::all); 59 | }; 60 | } // namespace sycl 61 | } // namespace cl 62 | -------------------------------------------------------------------------------- /reference/headers/deviceEvent.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class device_event { 18 | 19 | device_event(__unspecified__); 20 | 21 | public: 22 | void wait(); 23 | }; 24 | } // namespace sycl 25 | } // namespace cl 26 | -------------------------------------------------------------------------------- /reference/headers/deviceInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | 19 | enum class device : int { 20 | device_type, 21 | vendor_id, 22 | max_compute_units, 23 | max_work_item_dimensions, 24 | max_work_item_sizes, 25 | max_work_group_size, 26 | preferred_vector_width_char, 27 | preferred_vector_width_short, 28 | preferred_vector_width_int, 29 | preferred_vector_width_long, 30 | preferred_vector_width_float, 31 | preferred_vector_width_double, 32 | preferred_vector_width_half, 33 | native_vector_width_char, 34 | native_vector_width_short, 35 | native_vector_width_int, 36 | native_vector_width_long, 37 | native_vector_width_float, 38 | native_vector_width_double, 39 | native_vector_width_half, 40 | max_clock_frequency, 41 | address_bits, 42 | max_mem_alloc_size, 43 | image_support, 44 | max_read_image_args, 45 | max_write_image_args, 46 | image2d_max_height, 47 | image2d_max_width, 48 | image3d_max_height, 49 | image3d_max_width, 50 | image3d_max_depth, 51 | image_max_buffer_size, 52 | image_max_array_size, 53 | max_samplers, 54 | max_parameter_size, 55 | mem_base_addr_align, 56 | half_fp_config, 57 | single_fp_config, 58 | double_fp_config, 59 | global_mem_cache_type, 60 | global_mem_cache_line_size, 61 | global_mem_cache_size, 62 | global_mem_size, 63 | max_constant_buffer_size, 64 | max_constant_args, 65 | local_mem_type, 66 | local_mem_size, 67 | error_correction_support, 68 | host_unified_memory, 69 | profiling_timer_resolution, 70 | is_endian_little, 71 | is_available, 72 | is_compiler_available, 73 | is_linker_available, 74 | execution_capabilities, 75 | queue_profiling, 76 | built_in_kernels, 77 | platform, 78 | name, 79 | vendor, 80 | driver_version, 81 | profile, 82 | version, 83 | opencl_c_version, 84 | extensions, 85 | printf_buffer_size, 86 | preferred_interop_user_sync, 87 | parent_device, 88 | partition_max_sub_devices, 89 | partition_properties, 90 | partition_affinity_domains, 91 | partition_type_property, 92 | partition_type_affinity_domain, 93 | reference_count 94 | }; 95 | 96 | enum class device_type : unsigned int { 97 | cpu, // Maps to OpenCL CL_DEVICE_TYPE_CPU 98 | gpu, // Maps to OpenCL CL_DEVICE_TYPE_GPU 99 | accelerator, // Maps to OpenCL CL_DEVICE_TYPE_ACCELERATOR 100 | custom, // Maps to OpenCL CL_DEVICE_TYPE_CUSTOM 101 | automatic, // Maps to OpenCL CL_DEVICE_TYPE_DEFAULT 102 | host, 103 | all // Maps to OpenCL CL_DEVICE_TYPE_ALL 104 | }; 105 | 106 | enum class partition_property : int { 107 | no_partition, 108 | partition_equally, 109 | partition_by_counts, 110 | partition_by_affinity_domain 111 | }; 112 | 113 | enum class partition_affinity_domain : int { 114 | not_applicable, 115 | numa, 116 | L4_cache, 117 | L3_cache, 118 | L2_cache, 119 | L1_cache, 120 | next_partitionable 121 | }; 122 | 123 | enum class local_mem_type : int { none, local, global }; 124 | 125 | enum class fp_config : int { 126 | denorm, 127 | inf_nan, 128 | round_to_nearest, 129 | round_to_zero, 130 | round_to_inf, 131 | fma, 132 | correctly_rounded_divide_sqrt, 133 | soft_float 134 | }; 135 | 136 | enum class global_mem_cache_type : int { none, read_only, read_write }; 137 | 138 | enum class execution_capability : unsigned int { 139 | exec_kernel, 140 | exec_native_kernel 141 | }; 142 | 143 | } // namespace info 144 | } // namespace sycl 145 | } // namespace cl 146 | -------------------------------------------------------------------------------- /reference/headers/deviceSelector.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class default_selector : public device_selector { 18 | public: 19 | default_selector(); 20 | 21 | virtual ~default_selector(); 22 | 23 | virtual int operator()(const device &device) const; 24 | }; 25 | 26 | class opencl_selector : public device_selector { 27 | public: 28 | opencl_selector(); 29 | 30 | virtual ~opencl_selector(); 31 | 32 | virtual int operator()(const device &device) const; 33 | }; 34 | 35 | class cpu_selector : public device_selector { 36 | public: 37 | cpu_selector(); 38 | 39 | virtual ~cpu_selector(); 40 | 41 | virtual int operator()(const device &device) const; 42 | }; 43 | 44 | class gpu_selector : public device_selector { 45 | public: 46 | gpu_selector(); 47 | 48 | virtual ~gpu_selector(); 49 | 50 | virtual int operator()(const device &device) const; 51 | }; 52 | 53 | class host_selector : public device_selector { 54 | public: 55 | host_selector(); 56 | 57 | virtual ~host_selector(); 58 | 59 | virtual int operator()(const device &device) const; 60 | }; 61 | 62 | } // namespace sycl 63 | } // namespace cl 64 | -------------------------------------------------------------------------------- /reference/headers/deviceSelectorInterface.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class device_selector { 18 | public: 19 | device_selector(); 20 | 21 | device_selector(const device_selector &rhs); 22 | 23 | device_selector &operator=(const device_selector &rhs); 24 | 25 | virtual ~device_selector(); 26 | 27 | device select_device() const; 28 | 29 | virtual int operator()(const device &device) const = 0; 30 | }; 31 | } // namespace sycl 32 | } // namespace cl 33 | -------------------------------------------------------------------------------- /reference/headers/event.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | class event { 19 | public: 20 | event(); 21 | 22 | event(cl_event clEvent, const context& syclContext); 23 | 24 | /* -- common interface members -- */ 25 | 26 | cl_event get() const; 27 | 28 | bool is_host() const; 29 | 30 | vector_class get_wait_list(); 31 | 32 | void wait(); 33 | 34 | static void wait(const vector_class &eventList); 35 | 36 | void wait_and_throw(); 37 | 38 | static void wait_and_throw(const vector_class &eventList); 39 | 40 | template 41 | typename info::param_traits::return_type get_info() const; 42 | 43 | template 44 | typename info::param_traits::return_type get_profiling_info() const; 45 | }; 46 | 47 | } // namespace sycl 48 | } // namespace cl 49 | -------------------------------------------------------------------------------- /reference/headers/eventInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | enum class event: int { 19 | command_execution_status, 20 | reference_count 21 | }; 22 | 23 | enum class event_command_status : int { 24 | submitted, 25 | running, 26 | complete 27 | }; 28 | 29 | enum class event_profiling : int { 30 | command_submit, 31 | command_start, 32 | command_end 33 | }; 34 | } // namespace info 35 | } // namespace sycl 36 | } // namespace cl 37 | -------------------------------------------------------------------------------- /reference/headers/exception.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | using async_handler = function_class; 19 | 20 | class exception { 21 | public: 22 | const char *what() const; 23 | 24 | bool has_context() const; 25 | 26 | context get_context() const; 27 | 28 | cl_int get_cl_code() const; 29 | }; 30 | 31 | class exception_list { 32 | // Used as a container for a list of asynchronous exceptions 33 | public: 34 | using value_type = exception_ptr_class; 35 | using reference = value_type&; 36 | using const_reference = const value_type&; 37 | using size_type = std::size_t; 38 | using iterator = /*unspecified*/; 39 | using const_iterator = /*unspecified*/; 40 | 41 | size_type size() const; 42 | iterator begin() const; // first asynchronous exception 43 | iterator end() const; // refer to past-the-end last asynchronous exception 44 | }; 45 | 46 | class runtime_error : public exception; 47 | 48 | class kernel_error : public runtime_error; 49 | 50 | class accessor_error : public runtime_error; 51 | 52 | class nd_range_error : public runtime_error; 53 | 54 | class event_error : public runtime_error; 55 | 56 | class invalid_parameter_error : public runtime_error; 57 | 58 | class device_error : public exception; 59 | 60 | class compile_program_error : public device_error; 61 | 62 | class link_program_error : public device_error; 63 | 64 | class invalid_object_error : public device_error; 65 | 66 | class memory_allocation_error : public device_error; 67 | 68 | class platform_error : public device_error; 69 | 70 | class profiling_error : public device_error; 71 | 72 | class feature_not_supported : public device_error; 73 | 74 | } // namespace sycl 75 | } // namespace cl 76 | -------------------------------------------------------------------------------- /reference/headers/group.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class group { 19 | public: 20 | 21 | /* -- common interface members -- */ 22 | 23 | id get_id() const; 24 | 25 | size_t get_id(int dimension) const; 26 | 27 | range get_global_range() const; 28 | 29 | size_t get_global_range(int dimension) const; 30 | 31 | range get_local_range() const; 32 | 33 | size_t get_local_range(int dimension) const; 34 | 35 | range get_group_range() const; 36 | 37 | size_t get_group_range(int dimension) const; 38 | 39 | size_t operator[](int dimension) const; 40 | 41 | size_t get_linear_id() const; 42 | 43 | template 44 | void parallel_for_work_item(workItemFunctionT func) const; 45 | 46 | template 47 | void parallel_for_work_item(range logicalRange, 48 | workItemFunctionT func) const; 49 | 50 | template 51 | void mem_fence(access::fence_space accessSpace = 52 | access::fence_space::global_and_local) const; 53 | 54 | template 55 | device_event async_work_group_copy(local_ptr dest, 56 | global_ptr src, size_t numElements) const; 57 | 58 | template 59 | device_event async_work_group_copy(global_ptr dest, 60 | local_ptr src, size_t numElements) const; 61 | 62 | template 63 | device_event async_work_group_copy(local_ptr dest, 64 | global_ptr src, size_t numElements, size_t srcStride) const; 65 | 66 | template 67 | device_event async_work_group_copy(global_ptr dest, 68 | local_ptr src, size_t numElements, size_t destStride) const; 69 | 70 | template 71 | void wait_for(eventTN... events) const; 72 | }; 73 | } // sycl 74 | } // cl 75 | -------------------------------------------------------------------------------- /reference/headers/hitem.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class h_item { 19 | public: 20 | h_item() = delete; 21 | 22 | /* -- common interface members -- */ 23 | 24 | item get_global() const; 25 | 26 | item get_local() const; 27 | 28 | item get_logical_local() const; 29 | 30 | item get_physical_local() const; 31 | 32 | range get_global_range() const; 33 | 34 | size_t get_global_range(int dimension) const; 35 | 36 | id get_global_id() const; 37 | 38 | size_t get_global_id(int dimension) const; 39 | 40 | range get_local_range() const; 41 | 42 | size_t get_local_range(int dimension) const; 43 | 44 | id get_local_id() const; 45 | 46 | size_t get_local_id(int dimension) const; 47 | 48 | range get_logical_local_range() const; 49 | 50 | size_t get_logical_local_range(int dimension) const; 51 | 52 | id get_logical_local_id() const; 53 | 54 | size_t get_logical_local_id(int dimension) const; 55 | 56 | range get_physical_local_range() const; 57 | 58 | size_t get_physical_local_range(int dimension) const; 59 | 60 | id get_physical_local_id() const; 61 | 62 | size_t get_physical_local_id(int dimension) const; 63 | 64 | }; 65 | } // namespace sycl 66 | } // namespace cl 67 | -------------------------------------------------------------------------------- /reference/headers/id.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class id { 19 | public: 20 | id(); 21 | 22 | /* The following constructor is only available in the id class 23 | * specialization where: dimensions==1 */ 24 | id(size_t dim0); 25 | /* The following constructor is only available in the id class 26 | * specialization where: dimensions==2 */ 27 | id(size_t dim0, size_t dim1); 28 | /* The following constructor is only available in the id class 29 | * specialization where: dimensions==3 */ 30 | id(size_t dim0, size_t dim1, size_t dim2); 31 | 32 | /* -- common interface members -- */ 33 | 34 | id(const range &range); 35 | id(const item &item); 36 | 37 | size_t get(int dimension) const; 38 | size_t &operator[](int dimension); 39 | size_t operator[](int dimension) const; 40 | 41 | // OP is: +, -, *, /, %, <<, >>, &, |, ^, &&, ||, <, >, <=, >= 42 | friend id operatorOP(const id &lhs, const id &rhs) { /* ... */ } 43 | friend id operatorOP(const id &lhs, const size_t &rhs) { /* ... */ } 44 | 45 | // OP is: +=, -=, *=, /=, %=, <<=, >>=, &=, |=, ^= 46 | friend id &operatorOP(id &lhs, const id &rhs) { /* ... */ } 47 | friend id &operatorOP(id &lhs, const size_t &rhs) { /* ... */ } 48 | 49 | // OP is: +, -, *, /, %, <<, >>, &, |, ^, &&, ||, <, >, <=, >= 50 | friend id operatorOP(const size_t &lhs, const id &rhs) { /* ... */ } 51 | 52 | }; 53 | 54 | } // namespace sycl 55 | } // namespace cl 56 | -------------------------------------------------------------------------------- /reference/headers/item.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class item { 19 | public: 20 | item() = delete; 21 | 22 | /* -- common interface members -- */ 23 | 24 | id get_id() const; 25 | 26 | size_t get_id(int dimension) const; 27 | 28 | size_t operator[](int dimension) const; 29 | 30 | range get_range() const; 31 | 32 | size_t get_range(int dimension) const; 33 | 34 | // only available if with_offset is true 35 | id get_offset() const; 36 | 37 | // only available if with_offset is false 38 | operator item() const; 39 | 40 | size_t get_linear_id() const; 41 | }; 42 | } // namespace sycl 43 | } // namespace cl 44 | -------------------------------------------------------------------------------- /reference/headers/kernelInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | enum class kernel: int { 19 | function_name, 20 | num_args, 21 | context, 22 | program, 23 | reference_count, 24 | attributes 25 | }; 26 | 27 | enum class kernel_work_group: int { 28 | global_work_size, 29 | work_group_size, 30 | compile_work_group_size, 31 | preferred_work_group_size_multiple, 32 | private_mem_size 33 | }; 34 | 35 | } // namespace info 36 | } // namespace sycl 37 | } // namespace cl 38 | -------------------------------------------------------------------------------- /reference/headers/kernelWIP.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class kernel { 18 | private: 19 | friend class program; 20 | 21 | // The default object is not valid because there is no 22 | // program or cl_kernel associated with it 23 | kernel(); 24 | 25 | public: 26 | 27 | kernel(cl_kernel clKernel, const context& syclContext); 28 | 29 | /* -- common interface members -- */ 30 | 31 | cl_kernel get() const; 32 | 33 | bool is_host() const; 34 | 35 | context get_context() const; 36 | 37 | program get_program() const; 38 | 39 | template 40 | typename info::param_traits::return_type 41 | get_info() const; 42 | 43 | template 44 | typename info::param_traits::return_type 45 | get_work_group_info(const device &dev) const; 46 | }; 47 | } // namespace sycl 48 | } // namespace cl 49 | -------------------------------------------------------------------------------- /reference/headers/ndRange.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class nd_range { 19 | public: 20 | 21 | /* -- common interface members -- */ 22 | 23 | nd_range(range globalSize, range localSize, 24 | id offset = id()); 25 | 26 | range get_global_range() const; 27 | range get_local_range() const; 28 | range get_group_range() const; 29 | id get_offset() const; 30 | }; 31 | } // namespace sycl 32 | } // namespace cl 33 | -------------------------------------------------------------------------------- /reference/headers/nditem.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class nd_item { 19 | public: 20 | nd_item() = delete; 21 | 22 | /* -- common interface members -- */ 23 | 24 | id get_global_id() const; 25 | 26 | size_t get_global_id(int dimension) const; 27 | 28 | size_t get_global_linear_id() const; 29 | 30 | id get_local_id() const; 31 | 32 | size_t get_local_id(int dimension) const; 33 | 34 | size_t get_local_linear_id() const; 35 | 36 | group get_group() const; 37 | 38 | size_t get_group(int dimension) const; 39 | 40 | size_t get_group_linear_id() const; 41 | 42 | range get_group_range() const; 43 | 44 | size_t get_group_range(int dimension) const; 45 | 46 | range get_global_range() const; 47 | 48 | size_t get_global_range(int dimension) const; 49 | 50 | range get_local_range() const; 51 | 52 | size_t get_local_range(int dimension) const; 53 | 54 | id get_offset() const; 55 | 56 | nd_range get_nd_range() const; 57 | 58 | void barrier(access::fence_space accessSpace = 59 | access::fence_space::global_and_local) const; 60 | 61 | template 62 | void mem_fence(access::fence_space accessSpace = 63 | access::fence_space::global_and_local) const; 64 | 65 | template 66 | device_event async_work_group_copy(local_ptr dest, 67 | global_ptr src, size_t numElements) const; 68 | 69 | template 70 | device_event async_work_group_copy(global_ptr dest, 71 | local_ptr src, size_t numElements) const; 72 | 73 | template 74 | device_event async_work_group_copy(local_ptr dest, 75 | global_ptr src, size_t numElements, size_t srcStride) const; 76 | 77 | template 78 | device_event async_work_group_copy(global_ptr dest, 79 | local_ptr src, size_t numElements, size_t destStride) const; 80 | 81 | template 82 | void wait_for(eventTN... events) const; 83 | }; 84 | } // namespace sycl 85 | } // namespace cl 86 | -------------------------------------------------------------------------------- /reference/headers/openclcInterop.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | extern "C" cl::sycl::global_ptr::pointer_t my_func( 16 | cl::sycl::cl_float4::vector_t x, cl::sycl::cl_double y); 17 | -------------------------------------------------------------------------------- /reference/headers/parallelFor.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | void single_task(kernel *syclKernel); 16 | 17 | void parallel_for(nd_range ndRange, kernel *k); 18 | 19 | void parallel_for(range range kernel *syclKernel); 20 | 21 | 22 | template 23 | void single_task(KernelType); 24 | 25 | template 26 | void parallel_for(range num_work_items, KernelType); 27 | 28 | 29 | template 30 | void parallel_for(range numWorkItems, 31 | id workItemOffset, KernelType); 32 | 33 | template 34 | void parallel_for(nd_range ndRange, KernelType); 35 | 36 | template 37 | void parallel_for_work_group(range numWorkGroups, 38 | WorkgroupFunctionType); 39 | 40 | template 41 | void parallel_for_work_group(range numWorkGroups, 42 | range workGroupSize, 43 | WorkgroupFunctionType); 44 | 45 | template 46 | void single_task(KernelType); 47 | 48 | template 49 | void parallel_for(range numWorkItems, KernelType); 50 | 51 | 52 | template 53 | void parallel_for(range numWorkItems, 54 | id workItemOffset, KernelType); 55 | 56 | template 57 | void parallel_for(nd_range ndRange, KernelType); 58 | 59 | template 60 | void parallel_for(nd_range numWorkItems, 61 | id workItemOffset, KernelType); 62 | 63 | 64 | template 65 | void parallel_for_work_group(range numWorkGroups, 66 | WorkgroupFunctionType); 67 | 68 | template 69 | void parallel_for_work_group(range numWorkGroups, 70 | range workGroupSize, 71 | WorkgroupFunctionType); 72 | -------------------------------------------------------------------------------- /reference/headers/paramTraits.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | template 19 | class param_traits { 20 | public: 21 | 22 | using return_type = __return_type__; 23 | 24 | }; 25 | } // namespace info 26 | } // namespace sycl 27 | } // namespace cl 28 | -------------------------------------------------------------------------------- /reference/headers/platform.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class platform { 18 | public: 19 | platform(); 20 | 21 | explicit platform(cl_platform_id platformID); 22 | 23 | explicit platform(const device_selector &deviceSelector); 24 | 25 | /* -- common interface members -- */ 26 | 27 | cl_platform_id get() const; 28 | 29 | vector_class get_devices( 30 | info::device_type = info::device_type::all) const; 31 | 32 | template 33 | typename info::param_traits::return_type get_info() const; 34 | 35 | bool has_extension(const string_class &extension) const; 36 | 37 | bool is_host() const; 38 | 39 | static vector_class get_platforms(); 40 | }; 41 | } // namespace sycl 42 | } // namespace cl 43 | -------------------------------------------------------------------------------- /reference/headers/platformInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | enum class platform : unsigned int { 19 | profile, 20 | version, 21 | name, 22 | vendor, 23 | extensions 24 | }; 25 | } // namespace info 26 | } // namespace sycl 27 | } // namespace cl 28 | -------------------------------------------------------------------------------- /reference/headers/pointer.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | template 19 | class multi_ptr; 20 | 21 | // Template specialization aliases for different pointer address spaces 22 | 23 | template 24 | using global_ptr = multi_ptr; 25 | 26 | template 27 | using local_ptr = multi_ptr; 28 | 29 | template 30 | using constant_ptr = 31 | multi_ptr; 32 | 33 | template 34 | using private_ptr = 35 | multi_ptr; 36 | 37 | } // namespace sycl 38 | } // namespace cl 39 | -------------------------------------------------------------------------------- /reference/headers/priv.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class private_memory { 19 | public: 20 | // Construct based directly off the number of work-items 21 | private_memory(const group &); 22 | 23 | // Access the instance for the current work-item 24 | T &operator()(const h_item &id); 25 | }; 26 | } 27 | } 28 | -------------------------------------------------------------------------------- /reference/headers/programInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | enum class program: int { 19 | context, 20 | devices, 21 | reference_count 22 | }; 23 | } // namespace info 24 | } // namespace sycl 25 | } // namespace cl 26 | -------------------------------------------------------------------------------- /reference/headers/programWIP.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | enum class program_state { 18 | none, 19 | compiled, 20 | linked 21 | }; 22 | 23 | class program { 24 | public: 25 | program() = delete; 26 | 27 | explicit program(const context &context, 28 | const property_list &propList = {}); 29 | 30 | program(const context &context, vector_class deviceList, 31 | const property_list &propList = {}); 32 | 33 | program(vector_class &programList, 34 | const property_list &propList = {}); 35 | 36 | program(vector_class &programList, string_class linkOptions, 37 | const property_list &propList = {}); 38 | 39 | program(const context &context, cl_program clProgram); 40 | 41 | /* -- common interface members -- */ 42 | 43 | /* -- property interface members -- */ 44 | 45 | cl_program get() const; 46 | 47 | bool is_host() const; 48 | 49 | template 50 | void compile_with_kernel_type(string_class compileOptions = ""); 51 | 52 | void compile_with_source(string_class kernelSource, 53 | string_class compileOptions = ""); 54 | 55 | template 56 | void build_with_kernel_type(string_class buildOptions = ""); 57 | 58 | void build_with_source(string_class kernelSource, 59 | string_class buildOptions = ""); 60 | 61 | void link(string_class linkOptions = ""); 62 | 63 | template 64 | bool has_kernel() const; 65 | 66 | bool has_kernel(string_class kernelName) const; 67 | 68 | template 69 | kernel get_kernel() const; 70 | 71 | kernel get_kernel(string_class kernelName) const; 72 | 73 | template 74 | typename info::param_traits::return_type 75 | get_info() const; 76 | 77 | vector_class> get_binaries() const; 78 | 79 | context get_context() const; 80 | 81 | vector_class get_devices() const; 82 | 83 | string_class get_compile_options() const; 84 | 85 | string_class get_link_options() const; 86 | 87 | string_class get_build_options() const; 88 | 89 | program_state get_state() const; 90 | }; 91 | } // namespace sycl 92 | } // namespace cl 93 | -------------------------------------------------------------------------------- /reference/headers/properties.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | template 19 | struct is_property; 20 | 21 | template 22 | struct is_property_of; 23 | 24 | class T { 25 | ... 26 | 27 | template 28 | bool has_property() const; 29 | 30 | template 31 | propertyT get_property() const; 32 | 33 | ... 34 | }; 35 | 36 | class property_list { 37 | public: 38 | template 39 | property_list(propertyTN... props); 40 | }; 41 | } // namespace sycl 42 | } // namespace cl 43 | -------------------------------------------------------------------------------- /reference/headers/queue.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | class queue { 18 | public: 19 | explicit queue(const property_list &propList = {}); 20 | 21 | explicit queue(const async_handler &asyncHandler, 22 | const property_list &propList = {}); 23 | 24 | explicit queue(const device_selector &deviceSelector, 25 | const property_list &propList = {}); 26 | 27 | explicit queue(const device_selector &deviceSelector, 28 | const async_handler &asyncHandler, const property_list &propList = {}); 29 | 30 | explicit queue(const device &syclDevice, const property_list &propList = {}); 31 | 32 | explicit queue(const device &syclDevice, const async_handler &asyncHandler, 33 | const property_list &propList = {}); 34 | 35 | explicit queue(const context &syclContext, const device_selector &deviceSelector, 36 | const property_list &propList = {}); 37 | 38 | explicit queue(const context &syclContext, const device_selector &deviceSelector, 39 | const async_handler &asyncHandler, const property_list &propList = {}); 40 | 41 | explicit queue(const context &syclContext, const device &syclDevice, 42 | const property_list &propList = {}); 43 | 44 | explicit queue(const context &syclContext, const device &syclDevice, 45 | const async_handler &asyncHandler, const property_list &propList = {}); 46 | 47 | explicit queue(cl_command_queue clQueue, const context& syclContext, 48 | const async_handler &asyncHandler = {}); 49 | 50 | /* -- common interface members -- */ 51 | 52 | /* -- property interface members -- */ 53 | 54 | cl_command_queue get() const; 55 | 56 | context get_context() const; 57 | 58 | device get_device() const; 59 | 60 | bool is_host() const; 61 | 62 | template 63 | typename info::param_traits::return_type get_info() const; 64 | 65 | template 66 | event submit(T cgf); 67 | 68 | template 69 | event submit(T cgf, const queue &secondaryQueue); 70 | 71 | void wait(); 72 | 73 | void wait_and_throw(); 74 | 75 | void throw_asynchronous(); 76 | }; 77 | } // namespace sycl 78 | } // namespace cl 79 | -------------------------------------------------------------------------------- /reference/headers/queueInfo.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace info { 18 | enum class queue : int { 19 | context, 20 | device, 21 | reference_count 22 | }; 23 | } // namespace info 24 | } // namespace sycl 25 | } // namespace cl 26 | -------------------------------------------------------------------------------- /reference/headers/range.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | template 18 | class range { 19 | public: 20 | /* The following constructor is only available in the range class specialization where: dimensions==1 */ 21 | range(size_t dim0); 22 | /* The following constructor is only available in the range class specialization where: dimensions==2 */ 23 | range(size_t dim0, size_t dim1); 24 | /* The following constructor is only available in the range class specialization where: dimensions==3 */ 25 | range(size_t dim0, size_t dim1, size_t dim2); 26 | 27 | /* -- common interface members -- */ 28 | 29 | size_t get(int dimension) const; 30 | size_t &operator[](int dimension); 31 | size_t operator[](int dimension) const; 32 | 33 | size_t size() const; 34 | 35 | // OP is: +, -, *, /, %, <<, >>, &, |, ^, &&, ||, <, >, <=, >= 36 | friend range operatorOP(const range &lhs, const range &rhs) { /* ... */ } 37 | friend range operatorOP(const range &lhs, const size_t &rhs) { /* ... */ } 38 | 39 | // OP is: +=, -=, *=, /=, %=, <<=, >>=, &=, |=, ^= 40 | friend range & operatorOP(const range &lhs, const range &rhs) { /* ... */ } 41 | friend range & operatorOP(const range &lhs, const size_t &rhs) { /* ... */ } 42 | 43 | // OP is: +, -, *, /, %, <<, >>, &, |, ^, &&, ||, <, >, <=, >= 44 | friend range operatorOP(const size_t &lhs, const range &rhs) { /* ... */ } 45 | 46 | }; 47 | 48 | } // sycl 49 | } // cl 50 | -------------------------------------------------------------------------------- /reference/headers/sampler.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | enum class addressing_mode: unsigned int { 19 | mirrored_repeat, 20 | repeat, 21 | clamp_to_edge, 22 | clamp, 23 | none 24 | }; 25 | 26 | enum class filtering_mode: unsigned int { 27 | nearest, 28 | linear 29 | }; 30 | 31 | enum class coordinate_normalization_mode : unsigned int { 32 | normalized, 33 | unnormalized 34 | }; 35 | 36 | class sampler { 37 | public: 38 | sampler(coordinate_normalization_mode normalizationMode, 39 | addressing_mode addressingMode, filtering_mode filteringMode, 40 | const property_list &propList = {}); 41 | 42 | sampler(cl_sampler clSampler, const context &syclContext); 43 | 44 | /* -- common interface members -- */ 45 | 46 | /* -- property interface members -- */ 47 | 48 | addressing_mode get_addressing_mode() const; 49 | 50 | filtering_mode get_filtering_mode() const; 51 | 52 | coordinate_normalization_mode get_coordinate_normalization_mode() const; 53 | }; 54 | } // namespace sycl 55 | } // namespace cl 56 | -------------------------------------------------------------------------------- /reference/headers/stlclasses.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | #include 16 | #include 17 | #include 18 | #include 19 | #include 20 | #include 21 | 22 | namespace cl { 23 | namespace sycl { 24 | 25 | template < class T, class Alloc = std::allocator > 26 | using vector_class = std::vector; 27 | 28 | using string_class = std::string; 29 | 30 | template 31 | using function_class = std::function; 32 | 33 | using mutex_class = std::mutex; 34 | 35 | template 36 | using shared_ptr_class = std::shared_ptr; 37 | 38 | template 39 | using unique_ptr_class = std::unique_ptr; 40 | 41 | template 42 | using weak_ptr_class = std::weak_ptr; 43 | 44 | template 45 | using hash_class = std::hash; 46 | 47 | using exception_ptr_class = std::exception_ptr; 48 | 49 | } // sycl 50 | } // cl 51 | 52 | #include 53 | -------------------------------------------------------------------------------- /reference/headers/stream.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | 18 | enum class stream_manipulator { 19 | flush, 20 | dec, 21 | hex, 22 | oct, 23 | noshowbase, 24 | showbase, 25 | noshowpos, 26 | showpos, 27 | endl, 28 | fixed, 29 | scientific, 30 | hexfloat, 31 | defaultfloat 32 | }; 33 | 34 | 35 | const stream_manipulator flush = stream_manipulator::flush; 36 | 37 | const stream_manipulator dec = stream_manipulator::dec; 38 | 39 | const stream_manipulator hex = stream_manipulator::hex; 40 | 41 | const stream_manipulator oct = stream_manipulator::oct; 42 | 43 | const stream_manipulator noshowbase = stream_manipulator::noshowbase; 44 | 45 | const stream_manipulator showbase = stream_manipulator::showbase; 46 | 47 | const stream_manipulator noshowpos = stream_manipulator::noshowpos; 48 | 49 | const stream_manipulator showpos = stream_manipulator::showpos; 50 | 51 | const stream_manipulator endl = stream_manipulator::endl; 52 | 53 | const stream_manipulator fixed = stream_manipulator::fixed; 54 | 55 | const stream_manipulator scientific = stream_manipulator::scientific; 56 | 57 | const stream_manipulator hexfloat = stream_manipulator::hexfloat; 58 | 59 | const stream_manipulator defaultfloat = stream_manipulator::defaultfloat; 60 | 61 | __precision_manipulator__ setprecision(int precision); 62 | 63 | __width_manipulator__ setw(int width); 64 | 65 | class stream { 66 | public: 67 | 68 | stream(size_t totalBufferSize, size_t workItemBufferSize, handler& cgh); 69 | 70 | /* -- common interface members -- */ 71 | 72 | size_t get_size() const; 73 | 74 | size_t get_work_item_buffer_size() const; 75 | 76 | /* get_max_statement_size() has the same functionality as get_work_item_buffer_size(), 77 | and is provided for backward compatibility. get_max_statement_size() is a deprecated 78 | query. */ 79 | size_t get_max_statement_size() const; 80 | }; 81 | 82 | template 83 | const stream& operator<<(const stream& os, const T &rhs); 84 | 85 | } // namespace sycl 86 | } // namespace cl 87 | -------------------------------------------------------------------------------- /reference/headers/synchronization.h: -------------------------------------------------------------------------------- 1 | // Copyright (c) 2011-2020 The Khronos Group, Inc. 2 | // 3 | // Licensed under the Apache License, Version 2.0 (the License); 4 | // you may not use this file except in compliance with the License. 5 | // You may obtain a copy of the License at 6 | // 7 | // http://www.apache.org/licenses/LICENSE-2.0 8 | // 9 | // Unless required by applicable law or agreed to in writing, software 10 | // distributed under the License is distributed on an AS IS BASIS, 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | // See the License for the specific language governing permissions and 13 | // limitations under the License. 14 | 15 | namespace cl { 16 | namespace sycl { 17 | namespace access { 18 | enum class fence_space : char { 19 | local_space, 20 | global_space, 21 | global_and_local 22 | }; // enum class fence_space 23 | } // namepaces access 24 | } // namespace sycl 25 | } // namespace cl 26 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | # Copyright 2024 The Khronos Group Inc. 2 | # SPDX-License-Identifier: Apache-2.0 3 | 4 | pre-commit 5 | reuse 6 | Sphinx 7 | sphinx-book-theme 8 | sphinxcontrib-spelling 9 | -------------------------------------------------------------------------------- /source/_static/Khronos_Group_SYCL_logo.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KhronosGroup/SYCL_Reference/46bda728f9bf58c317c88e4a6a0ca0a602d8683a/source/_static/Khronos_Group_SYCL_logo.pdf -------------------------------------------------------------------------------- /source/_static/custom.css: -------------------------------------------------------------------------------- 1 | /* 2 | * SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 3 | * 4 | * SPDX-License-Identifier: Apache-2.0 5 | */ 6 | 7 | .wy-side-nav-search, .wy-nav-top { 8 | background: #4308E5; 9 | } 10 | 11 | .eqno { 12 | margin-left: 5px; 13 | float: right; 14 | } 15 | .math .headerlink { 16 | display: none; 17 | visibility: hidden; 18 | } 19 | .math:hover .headerlink { 20 | display: inline-block; 21 | visibility: visible; 22 | margin-right: -0.7em; 23 | } 24 | 25 | /* A workaround for https://github.com/readthedocs/sphinx_rtd_theme/issues/647 26 | * Override display for function signatures so that there is spacing between 27 | * types and arguments */ 28 | .rst-content dl:not(.docutils) dt { 29 | display: table-cell !important; 30 | } 31 | .rst-content dl:not(.docutils) dd { 32 | margin-top: 6px; 33 | } 34 | 35 | /* override table width restrictions 36 | * https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ 37 | @media screen and (min-width: 767px) { 38 | 39 | .wy-table-responsive table td { 40 | /* !important prevents the common CSS stylesheets from overriding 41 | this as on RTD they are loaded after this stylesheet */ 42 | white-space: normal !important; 43 | } 44 | 45 | .wy-table-responsive { 46 | overflow: visible !important; 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /source/_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KhronosGroup/SYCL_Reference/46bda728f9bf58c317c88e4a6a0ca0a602d8683a/source/_static/favicon.png -------------------------------------------------------------------------------- /source/backends.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ******** 6 | Backends 7 | ******** 8 | 9 | The SYCL backends that can be supported by a SYCL implementation 10 | are identified using the ``enum class backend``. 11 | 12 | ================= 13 | ``sycl::backend`` 14 | ================= 15 | 16 | :: 17 | 18 | class backend; 19 | 20 | The ``enum class backend`` is implementation-defined and must be 21 | populated with a unique identifier for each SYCL backend that the 22 | SYCL implementation can support. Note that the SYCL backends listed 23 | in the ``enum class backend`` are not guaranteed to be available 24 | in a given installation. 25 | 26 | Each named SYCL backend enumerated in the ``enum class backend`` 27 | must be associated with a SYCL backend specification. Many sections 28 | of this specification will refer to the associated SYCL 29 | backend specification. 30 | 31 | ============== 32 | Backend macros 33 | ============== 34 | 35 | As the identifiers defined in ``enum class backend`` are 36 | implementation-defined, and the associated backends not 37 | guaranteed to be available, a SYCL implementation must also 38 | define a preprocessor macro for each of these identifiers. 39 | If the SYCL backend is defined by the Khronos SYCL group, the 40 | name of the macro has the form ``SYCL_BACKEND_``, 41 | where backend_name is the associated identifier from ``backend`` 42 | in all upper-case. 43 | 44 | For the name of the macro if the vendor defines the SYCL backend 45 | outside of the Khronos SYCL group, see the following: 46 | 47 | .. seealso:: |SYCL_SPEC_EXTENSIONS| 48 | 49 | If a backend listed in the ``enum class backend`` is not available, 50 | the associated macro must be left undefined. 51 | -------------------------------------------------------------------------------- /source/built-in-functions.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _built-in-functions: 6 | 7 | =========================================== 8 | Built-in functions for SYCL host and device 9 | =========================================== 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | iface/function-objects 15 | iface/group-functions 16 | iface/group-algorithms-library 17 | iface/math-functions 18 | iface/native-prec-math-func 19 | iface/half-prec-math-func 20 | iface/integer-functions 21 | iface/common-functions 22 | iface/geometric-functions 23 | iface/relational-functions 24 | -------------------------------------------------------------------------------- /source/class-availability.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ****************** 6 | Class availability 7 | ****************** 8 | 9 | In SYCL some SYCL runtime classes are available to 10 | the SYCL application, some are available within a 11 | SYCL kernel function and some are available on both 12 | and can be passed as arguments to a SYCL kernel function. 13 | 14 | Each of the following SYCL runtime classes must be 15 | available to the host application: :ref:`buffer`, 16 | ``sycl::buffer_allocator``, :ref:`context`, :ref:`device`, 17 | :ref:`device_image`, :ref:`event`, `exception`, :ref:`handler`, 18 | :ref:`host_accessor`, :ref:`host_sampled_image_accessor`, 19 | :ref:`host_unsampled_image_accessor`, :ref:`id`, ``sycl::image_allocator``, 20 | :ref:`kernel`, ``sycl::kernel_id``, `marray`, `kernel_bundle`, 21 | :ref:`nd_range`, :ref:`platform`, :ref:`queue`, :ref:`range`, 22 | :ref:`sampled_image`, :ref:`image_sampler`, :ref:`stream`, 23 | :ref:`unsampled_image` and `vec`. 24 | 25 | Each of the following SYCL runtime classes must be available 26 | within a SYCL kernel function: :ref:`command-accessor`, :ref:`atomic_ref`, 27 | ``sycl::device_event``, :ref:`group`, :ref:`h_item`, :ref:`id`, :ref:`item`, 28 | :ref:`local_accessor`, `marray`, :ref:`multi_ptr`, :ref:`nd_item`, 29 | :ref:`range`, `reducer`, :ref:`sampled_image_accessor`, :ref:`stream`, 30 | :ref:`sub_group`, :ref:`unsampled_image_accessor` and `vec`. 31 | 32 | .. seealso:: |SYCL_SPEC_CLASS_AVLBL| 33 | -------------------------------------------------------------------------------- /source/common.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _common-interface: 6 | 7 | ================== 8 | Common Interface 9 | ================== 10 | 11 | In this section, we define methods that are common to multiple classes. 12 | 13 | .. toctree:: 14 | :maxdepth: 1 15 | 16 | iface/common-byval 17 | iface/common-reference 18 | iface/properties 19 | iface/backend_interop 20 | -------------------------------------------------------------------------------- /source/data-types.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ========== 6 | Data types 7 | ========== 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | iface/scalar-types 13 | iface/vector-types 14 | iface/math-array-types 15 | -------------------------------------------------------------------------------- /source/data.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _data-access: 6 | 7 | ============= 8 | Data access 9 | ============= 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | iface/buffer 15 | iface/host-allocation 16 | iface/accessors 17 | iface/synchronization-primitives 18 | iface/address-space 19 | iface/private_memory 20 | iface/image 21 | iface/image-sampler 22 | -------------------------------------------------------------------------------- /source/error.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _error-handling: 6 | 7 | ============== 8 | Error handling 9 | ============== 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | iface/exception 15 | iface/async_handler 16 | iface/error-handling-rules 17 | -------------------------------------------------------------------------------- /source/examples/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: Apache-2.0 4 | 5 | cmake_minimum_required(VERSION 3.13) 6 | project(SYCL_Reference) 7 | 8 | enable_testing() 9 | 10 | add_compile_options(-fsycl -Wall -Wextra -Werror) 11 | add_link_options(-fsycl) 12 | 13 | function(add_example name) 14 | add_executable(${name} ${name}.cpp) 15 | add_test(NAME ${name} COMMAND ${name}) 16 | endfunction(add_example) 17 | 18 | add_example(atomic) 19 | add_example(host-task) 20 | add_example(gpu-platform) 21 | add_example(std-vector) 22 | add_example(event-elapsed-time) 23 | add_example(exception-handling) 24 | add_example(get-platforms) 25 | add_example(get_devices) 26 | add_example(stream) 27 | add_example(gpu-selector) 28 | set_tests_properties(gpu-platform PROPERTIES LABELS gpu) 29 | add_example(queue-parallel) 30 | add_example(queue-single-task) 31 | add_example(usm-implicit-data-movement) 32 | -------------------------------------------------------------------------------- /source/examples/async-handler.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | auto async_handler_object = [](sycl::exception_list exceptions) { 8 | for (auto e : exceptions) { 9 | try { 10 | std::rethrow_exception(e); 11 | } catch (sycl::exception const &e) { 12 | std::cout << "Caught asynchronous SYCL exception:\n" 13 | << e.what() << std::endl; 14 | } 15 | } 16 | }; 17 | 18 | class async_error_example {}; 19 | 20 | int main() { 21 | // Create a queue with asynchronous handler 22 | sycl::queue myQueue{async_handler_object}; 23 | 24 | myQueue.submit([&](sycl::handler &cgh) { 25 | // Throw sycl::exception for async_handler_object to catch 26 | cgh.host_task([]() { 27 | throw sycl::exception(std::error_code{}, "Example exception!"); 28 | }); 29 | }); 30 | 31 | // Invocation of sycl::async_handler is triggered here 32 | myQueue.wait_and_throw(); 33 | } 34 | -------------------------------------------------------------------------------- /source/examples/async-handler.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Caught asynchronous SYCL exception: 6 | Example exception 7 | -------------------------------------------------------------------------------- /source/examples/atomic.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | #include 9 | 10 | const int lsize = 10; 11 | 12 | // Allows concurrent push or concurrent pop, but not both 13 | struct List { 14 | // Points to free spot on list 15 | int *top; 16 | int *data; 17 | 18 | sycl::atomic_ref 20 | atomic_top; 21 | 22 | List(sycl::queue q, int size) : atomic_top(top) { 23 | data = sycl::malloc_shared(size, q); 24 | top = data; 25 | }; 26 | 27 | bool empty() { return top == data; }; 28 | 29 | void push(int val) { 30 | // Allocate space by moving top pointer to right 31 | int *old_top = atomic_top.fetch_add(1); 32 | *old_top = val; 33 | }; 34 | 35 | auto pop() { 36 | // Deallocate space by moving top pointer to left 37 | int *old_top = atomic_top.fetch_add(-1); 38 | return *(old_top - 1); 39 | }; 40 | }; 41 | 42 | int main() { 43 | sycl::queue q; 44 | 45 | auto in = new (sycl::malloc_shared(1, q)) List(q, lsize); 46 | auto out = new (sycl::malloc_shared(1, q)) List(q, lsize); 47 | 48 | q.parallel_for(lsize, [=](auto idx) { in->push(idx); }).wait(); 49 | 50 | q.parallel_for(lsize, [=](auto idx) { 51 | out->push(idx * 100 + in->pop()); 52 | }).wait(); 53 | 54 | std::cout << "Out:\n" << std::setfill('0'); 55 | while (!out->empty()) 56 | std::cout << std::setw(3) << out->pop() << "\n"; 57 | } 58 | -------------------------------------------------------------------------------- /source/examples/atomic.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Out: 6 | 900 7 | 801 8 | 702 9 | 603 10 | 504 11 | 405 12 | 306 13 | 207 14 | 108 15 | 009 16 | -------------------------------------------------------------------------------- /source/examples/context.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | sycl::context context; 9 | auto devices = context.get_info(); 10 | for (auto device : devices) { 11 | std::cout << device.get_info() << std::endl; 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /source/examples/context.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Intel(R) Iris(R) Xe Graphics [0x9a49] 6 | -------------------------------------------------------------------------------- /source/examples/creating-sub-buffers.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | 9 | int main() { 10 | 11 | // Create 2-d buffer with 8x8 ints 12 | sycl::buffer parent_buffer{sycl::range<2>{8, 8}}; 13 | 14 | try { 15 | // OK: Contiguous region from middle of buffer 16 | sycl::buffer sub_buf1{parent_buffer, 17 | /*offset*/ sycl::range<2>{2, 0}, 18 | /*size*/ sycl::range<2>{2, 8}}; 19 | 20 | std::cout << "sub_buf1 created successfully" << std::endl; 21 | } catch (const sycl::exception &e) { 22 | std::cerr << "Exception while creating sub_buf1: " << e.what() << std::endl; 23 | } 24 | 25 | try { 26 | // invalid exception: Non-contiguous regions of 2-d buffer 27 | sycl::buffer sub_buf2{parent_buffer, 28 | /*offset*/ sycl::range<2>{2, 0}, 29 | /*size*/ sycl::range<2>{2, 2}}; 30 | 31 | std::cout << "sub_buf2 created successfully" << std::endl; 32 | } catch (const sycl::exception &e) { 33 | std::cerr << "Exception while creating sub_buf2: " << e.what() << std::endl; 34 | } 35 | 36 | try { 37 | // invalid exception: Non-contiguous regions of 2-d buffer 38 | sycl::buffer sub_buf3{parent_buffer, 39 | /*offset*/ sycl::range<2>{2, 2}, 40 | /*size*/ sycl::range<2>{2, 6}}; 41 | 42 | std::cout << "sub_buf3 created successfully" << std::endl; 43 | } catch (const sycl::exception &e) { 44 | std::cerr << "Exception while creating sub_buf3: " << e.what() << std::endl; 45 | } 46 | 47 | try { 48 | // invalid exception: Out-of-bounds size 49 | sycl::buffer sub_buf4{parent_buffer, 50 | /*offset*/ sycl::range<2>{2, 2}, 51 | /*size*/ sycl::range<2>{2, 8}}; 52 | 53 | std::cout << "sub_buf4 created successfully" << std::endl; 54 | } catch (const sycl::exception &e) { 55 | std::cerr << "Exception while creating sub_buf4: " << e.what() << std::endl; 56 | } 57 | 58 | return 0; 59 | } 60 | -------------------------------------------------------------------------------- /source/examples/creating-sub-buffers.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | sub_buf1 created successfully 6 | Exception while creating sub_buf2: Requested sub-buffer region is not contiguous -30 (PI_ERROR_INVALID_VALUE) 7 | Exception while creating sub_buf3: Requested sub-buffer region is not contiguous -30 (PI_ERROR_INVALID_VALUE) 8 | Exception while creating sub_buf4: Requested sub-buffer size exceeds the size of the parent buffer -30 (PI_ERROR_INVALID_VALUE) 9 | -------------------------------------------------------------------------------- /source/examples/def_kernels_lambda.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | // Explicit kernel names can be optionally forward declared at namespace scope 8 | class MyForwardDeclName; 9 | 10 | template class MyTemplatedKernelName; 11 | 12 | // Define and launch templated kernel 13 | template void templatedFunction() { 14 | sycl::queue myQueue; 15 | 16 | // Launch A: No explicit kernel name 17 | myQueue.submit([&](sycl::handler &h) { 18 | h.single_task([=] { 19 | // [kernel code that depends on type T] 20 | }); 21 | }); 22 | 23 | // Launch B: Name the kernel when invoking (this is optional) 24 | myQueue.submit([&](sycl::handler &h) { 25 | h.single_task>([=] { 26 | // The provided kernel name (MyTemplatedKernelName) depends on T 27 | // because the kernel does. T must also be forward declarable at 28 | // namespace scope. 29 | 30 | // [kernel code that depends on type T] 31 | }); 32 | }); 33 | } 34 | 35 | int main() { 36 | sycl::queue myQueue; 37 | 38 | myQueue.submit([&](sycl::handler &h) { 39 | // Declare MyKernel within this kernel invocation. Legal because 40 | // forward declaration at namespace scope is optional 41 | h.single_task([=] { 42 | // [kernel code] 43 | }); 44 | }); 45 | 46 | myQueue.submit([&](sycl::handler &h) { 47 | // Use kernel name that was forward declared at namespace scope 48 | h.single_task([=] { 49 | // [kernel code] 50 | }); 51 | }); 52 | 53 | templatedFunction(); // OK 54 | 55 | templatedFunction>(); // Launch A is OK, Launch B illegal 56 | // because std::complex is not forward declarable according to C++, and was 57 | // used in an explicit kernel name which must be forward declarable. 58 | } 59 | -------------------------------------------------------------------------------- /source/examples/def_kernels_named_function_obj.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | #include 9 | 10 | class RandomFiller { 11 | public: 12 | RandomFiller(sycl::accessor ptr) : ptr_{ptr} { 13 | std::random_device hwRand; 14 | std::uniform_int_distribution<> r{1, 100}; 15 | randomNum_ = r(hwRand); 16 | } 17 | void operator()(sycl::item<1> item) const { 18 | ptr_[item.get_id()] = get_random(); 19 | } 20 | int get_random() const { return randomNum_; } 21 | 22 | private: 23 | sycl::accessor ptr_; 24 | int randomNum_; 25 | }; 26 | 27 | void workFunction(sycl::buffer &b, sycl::queue &q, 28 | const sycl::range<1> r) { 29 | q.submit([&](sycl::handler &cgh) { 30 | sycl::accessor ptr{b, cgh}; 31 | RandomFiller filler{ptr}; 32 | 33 | cgh.parallel_for(r, filler); 34 | }); 35 | } 36 | 37 | int main() { 38 | sycl::range<1> buffRange(10); 39 | sycl::buffer myBuff(buffRange); 40 | sycl::queue myQueue; 41 | 42 | workFunction(myBuff, myQueue, buffRange); 43 | 44 | auto acc = myBuff.get_host_access(); 45 | 46 | for (auto a : acc) { 47 | std::cout << a << ' '; 48 | } 49 | 50 | return 0; 51 | } 52 | -------------------------------------------------------------------------------- /source/examples/def_kernels_named_function_obj.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | 81 81 81 81 81 81 81 81 81 81 6 | -------------------------------------------------------------------------------- /source/examples/event-elapsed-time.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | #include 9 | 10 | int main() { 11 | sycl::property_list properties{sycl::property::queue::enable_profiling()}; 12 | auto q = sycl::queue(sycl::default_selector_v, properties); 13 | 14 | std::cout 15 | << " Platform: " 16 | << q.get_device().get_platform().get_info() 17 | << std::endl; 18 | 19 | const int num_ints = 1024 * 1024; 20 | const size_t num_bytes = num_ints * sizeof(int); 21 | const int alignment = 8; 22 | 23 | // Alloc memory on host 24 | auto src = std::aligned_alloc(alignment, num_bytes); 25 | std::memset(src, 1, num_bytes); 26 | 27 | // Alloc memory on device 28 | auto dst = sycl::malloc_device(num_ints, q); 29 | q.memset(dst, 0, num_bytes).wait(); 30 | 31 | // Copy from host to device 32 | auto event = q.memcpy(dst, src, num_bytes); 33 | event.wait(); 34 | 35 | auto end = 36 | event.get_profiling_info(); 37 | auto start = 38 | event.get_profiling_info(); 39 | 40 | std::cout << "Elapsed time: " << (end - start) / 1.0e9 << " seconds\n"; 41 | 42 | sycl::free(dst, q); 43 | } 44 | -------------------------------------------------------------------------------- /source/examples/event-elapsed-time.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Platform: Intel(R) OpenCL 6 | Elapsed time: 0.0003652 seconds 7 | -------------------------------------------------------------------------------- /source/examples/exception-handling.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | 9 | auto exception_handler = [](sycl::exception_list exceptions) { 10 | for (const std::exception_ptr &e : exceptions) { 11 | try { 12 | std::rethrow_exception(e); 13 | } catch (const sycl::exception &e) { 14 | std::cout << "Caught asynchronous SYCL exception:\n" 15 | << e.what() << std::endl; 16 | } 17 | } 18 | }; 19 | 20 | auto q = sycl::queue(sycl::default_selector_v, exception_handler); 21 | 22 | try { 23 | q.submit([&](sycl::handler &cgh) { 24 | cgh.parallel_for( 25 | // Local size (second parameter) cannot be larger than global size 26 | // This will throw an intentional asynchronous exception 27 | sycl::nd_range<1>(sycl::range<1>(1), sycl::range<1>(30)), 28 | [=](sycl::nd_item<1>) { 29 | // ... 30 | }); 31 | }); 32 | q.wait_and_throw(); 33 | } catch (const sycl::exception &e) { 34 | std::cout << "Caught synchronous SYCL exception:\n" 35 | << e.what() << std::endl; 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /source/examples/exception-handling.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Caught asynchronous SYCL exception: 6 | Error: Work-group size is invalid (Local size exceeds the global work group size) 7 | -------------------------------------------------------------------------------- /source/examples/get-platforms.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | auto platforms = sycl::platform::get_platforms(); 9 | 10 | for (auto &platform : platforms) { 11 | std::cout << "Platform: " << platform.get_info() 12 | << std::endl; 13 | 14 | auto devices = platform.get_devices(); 15 | for (auto &device : devices) { 16 | std::cout << " Device: " << device.get_info() 17 | << std::endl; 18 | } 19 | } 20 | 21 | return 0; 22 | } 23 | -------------------------------------------------------------------------------- /source/examples/get-platforms.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Platform: Intel(R) FPGA Emulation Platform for OpenCL(TM) 6 | Device: Intel(R) FPGA Emulation Device 7 | Platform: Intel(R) OpenCL 8 | Device: 11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz 9 | Platform: Intel(R) OpenCL 10 | Device: 11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz 11 | Platform: Intel(R) OpenCL HD Graphics 12 | Device: Intel(R) Iris(R) Xe Graphics [0x9a49] 13 | Platform: Intel(R) Level-Zero 14 | Device: Intel(R) Iris(R) Xe Graphics [0x9a49] 15 | -------------------------------------------------------------------------------- /source/examples/get_devices.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | for (auto device : sycl::device::get_devices(sycl::info::device_type::gpu)) { 9 | std::cout << " Device: " << device.get_info() 10 | << std::endl; 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /source/examples/get_devices.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Device: Intel(R) Iris(R) Xe Graphics 6 | -------------------------------------------------------------------------------- /source/examples/gpu-platform.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | // Select a platform with a GPU 9 | auto p = sycl::platform(sycl::gpu_selector_v); 10 | std::cout << "Platform: " << p.get_info() << "\n"; 11 | // Enumerate all the GPUs 12 | for (auto &d : p.get_devices()) { 13 | std::cout << " Device: " << d.get_info() 14 | << std::endl; 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /source/examples/gpu-selector.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | sycl::device d; 9 | 10 | try { 11 | d = sycl::device(sycl::gpu_selector_v); 12 | } catch (sycl::exception const &e) { 13 | std::cout << "Cannot select a GPU\n" << e.what() << "\n"; 14 | std::cout << "Using a CPU device\n"; 15 | d = sycl::device(sycl::cpu_selector_v); 16 | } 17 | 18 | std::cout << "Using " << d.get_info(); 19 | } 20 | -------------------------------------------------------------------------------- /source/examples/gpu-selector.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Cannot select a GPU 6 | No device of requested type 'info::device_type::gpu' available. -1 (PI_ERROR_DEVICE_NOT_FOUND) 7 | Using a CPU device 8 | Using Intel(R) Core(TM) i7-7700K CPU @ 4.20GHz 9 | -------------------------------------------------------------------------------- /source/examples/handler-copy.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | const size_t nElems = 10u; 9 | 10 | // Create a vector and fill it with values 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 11 | std::vector vec(nElems); 12 | for (size_t i = 0; i < nElems; i++) 13 | vec[i] = i; 14 | 15 | std::cout << "vec: "; 16 | for (int i = 0; i < nElems; i++) 17 | std::cout << vec[i] << " "; 18 | std::cout << std::endl; 19 | 20 | // Create a buffer with no associated user storage 21 | sycl::buffer buf{sycl::range<1>(nElems)}; 22 | 23 | // Create a queue 24 | sycl::queue myQueue; 25 | 26 | myQueue 27 | .submit([&](sycl::handler &cgh) { 28 | // Retrieve a ranged write accessor to a global buffer with access to 29 | // the first half of the buffer 30 | sycl::accessor acc{buf, cgh, sycl::range<1>(nElems / 2), sycl::id<1>(0), 31 | sycl::write_only}; 32 | 33 | // Copy the first five elements of the vector into the buffer associated 34 | // with the accessor 35 | cgh.copy(vec.data(), acc); 36 | }) 37 | .wait(); 38 | 39 | auto h_acc = buf.get_host_access(sycl::read_only); 40 | std::cout << "buf: "; 41 | for (int i = 0; i < nElems; i++) 42 | std::cout << h_acc[i] << " "; 43 | std::cout << std::endl; 44 | } 45 | -------------------------------------------------------------------------------- /source/examples/handler-copy.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | vec: 0 1 2 3 4 5 6 7 8 9 6 | buf: 0 1 2 3 4 0 0 0 0 0 7 | -------------------------------------------------------------------------------- /source/examples/host-task.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | 9 | int main() { 10 | const int n = 10; 11 | sycl::queue q; 12 | 13 | int *data = sycl::malloc_shared(n + 1, q); 14 | memset(data, 0, sizeof(*data) * n); 15 | 16 | sycl::event e; 17 | for (int i = 1; i < n; i += 2) { 18 | e = q.submit([&](sycl::handler &h) { 19 | // wait for previous device task 20 | e.wait(); 21 | auto device_task = [=]() { data[i] = data[i - 1] + 1; }; 22 | h.single_task(device_task); 23 | }); 24 | 25 | q.submit([&](sycl::handler &h) { 26 | // wait for device task to complete 27 | e.wait(); 28 | auto host_task = [=]() { data[i + 1] = data[i] + 1; }; 29 | h.host_task(host_task); 30 | }); 31 | } 32 | for (int i = 0; i < n; i++) 33 | std::cout << i << ": " << data[i] << "\n"; 34 | 35 | sycl::free(data, q); 36 | } 37 | -------------------------------------------------------------------------------- /source/examples/host-task.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | 0: 0 6 | 1: 1 7 | 2: 2 8 | 3: 3 9 | 4: 4 10 | 5: 1 11 | 6: 2 12 | 7: 3 13 | 8: 4 14 | 9: 1 15 | -------------------------------------------------------------------------------- /source/examples/private_memory_example.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | 9 | int main() { 10 | sycl::queue myQueue; 11 | 12 | myQueue.submit([&](sycl::handler &cgh) { 13 | sycl::stream out(256, 256, cgh); 14 | 15 | // Issue 8 work-groups of 8 work-items each 16 | cgh.parallel_for_work_group( 17 | sycl::range<3>(2, 2, 2), sycl::range<3>(2, 2, 2), 18 | [=](sycl::group<3> myGroup) { 19 | //[workgroup code] 20 | 21 | // this variable is shared between workitems 22 | int myLocal; 23 | 24 | // this variable will be instantiated for each work-item separately 25 | sycl::private_memory myPrivate(myGroup); 26 | 27 | // Issue parallel work-items. The number issued per work-group is 28 | // determined by the work-group size range of parallel_for_work_group. 29 | // In this case, 8 work-items will execute the parallel_for_work_item 30 | // body for each of the 8 work-groups, resulting in 64 executions 31 | // globally/total. 32 | myGroup.parallel_for_work_item([&](sycl::h_item<3> myItem) { 33 | //[work-item code] 34 | sycl::id<3> myItemId = myItem.get_local_id(); 35 | myPrivate(myItem) = myItemId[0] + myItemId[1] + myItemId[2]; 36 | }); 37 | 38 | // Implicit work-group barrier 39 | 40 | // Carry private value across loops 41 | myGroup.parallel_for_work_item([&](sycl::h_item<3> myItem) { 42 | //[work-item code] 43 | out << myPrivate(myItem) << ' '; 44 | }); 45 | out << sycl::stream_manipulator::endl; 46 | 47 | //[workgroup code] 48 | }); 49 | }); 50 | } 51 | -------------------------------------------------------------------------------- /source/examples/private_memory_example.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | 0 1 1 2 1 2 2 3 6 | 0 1 1 2 1 2 2 3 7 | 0 1 1 2 1 2 2 3 8 | 0 1 1 2 1 2 2 3 9 | 0 1 1 2 1 2 2 3 10 | 0 1 1 2 1 2 2 3 11 | 0 1 1 2 1 2 2 3 12 | 0 1 1 2 1 2 2 3 13 | -------------------------------------------------------------------------------- /source/examples/queue-parallel.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | #include 7 | 8 | constexpr int count = 10; 9 | 10 | int main() { 11 | 12 | // Data initialized to zeros. 13 | int data[count] = {0}; 14 | 15 | auto q = sycl::queue(sycl::default_selector_v); 16 | { 17 | sycl::buffer data_buffer(data, sycl::range<1>(count)); 18 | 19 | q.submit([&](sycl::handler &cgh) { 20 | sycl::accessor data_accessor{data_buffer, cgh}; 21 | 22 | cgh.parallel_for(sycl::range<1>(count), 23 | [=](sycl::item<1> item) { 24 | auto index = item.get_id(0); 25 | data_accessor[index] += 5; 26 | }); 27 | }); 28 | q.wait(); 29 | } 30 | 31 | for (auto e : data) 32 | std::cout << e << " "; 33 | std::cout << std::endl; 34 | } 35 | -------------------------------------------------------------------------------- /source/examples/queue-parallel.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | 5 5 5 5 5 5 5 5 5 5 6 | -------------------------------------------------------------------------------- /source/examples/queue-single-task.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | 9 | auto q = sycl::queue(sycl::default_selector_v); 10 | 11 | q.submit([&](sycl::handler &cgh) { 12 | auto os = sycl::stream{128, 128, cgh}; 13 | cgh.single_task([=] { os << "Hello World!\n"; }); 14 | }); 15 | q.wait(); 16 | } 17 | -------------------------------------------------------------------------------- /source/examples/queue-single-task.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Hello World! 6 | -------------------------------------------------------------------------------- /source/examples/reduce-alg-lib.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | #include 9 | 10 | int main() { 11 | sycl::queue myQueue; 12 | 13 | sycl::buffer inputBuf{1024}; 14 | sycl::buffer outputBuf{2}; 15 | { 16 | // Initialize buffer on the host with 0, 1, 2, 3, ..., 1023 17 | sycl::host_accessor a{inputBuf}; 18 | std::iota(a.begin(), a.end(), 0); 19 | } 20 | 21 | myQueue.submit([&](sycl::handler &cgh) { 22 | sycl::accessor inputValues{inputBuf, cgh, sycl::read_only}; 23 | sycl::accessor outputValues{outputBuf, cgh, sycl::write_only, 24 | sycl::no_init}; 25 | 26 | cgh.parallel_for( 27 | sycl::nd_range<1>(sycl::range<1>(16), sycl::range<1>(16)), 28 | [=](sycl::nd_item<1> it) { 29 | // Apply a group algorithm to any number of values, described by an 30 | // iterator range. The work-group reduces all inputValues and each 31 | // work-item works on part of the range. 32 | const int *first = 33 | inputValues.get_multi_ptr() 34 | .get_raw(); 35 | const int *last = first + 1024; 36 | int sum = 37 | sycl::joint_reduce(it.get_group(), first, last, sycl::plus<>()); 38 | outputValues[0] = sum; 39 | 40 | // Apply a group algorithm to a set of values held directly by 41 | // work-items. The work-group reduces a number of values equal to the 42 | // size of the group and each work-item provides one value. 43 | int partial_sum = sycl::reduce_over_group( 44 | it.get_group(), inputValues[it.get_global_linear_id()], 45 | sycl::plus<>()); 46 | outputValues[1] = partial_sum; 47 | }); 48 | }); 49 | 50 | { 51 | sycl::host_accessor a{outputBuf}; 52 | std::cout << "sum: " << a[0] << std::endl; 53 | std::cout << "partial_sum: " << a[1] << std::endl; 54 | } 55 | 56 | return 0; 57 | } 58 | -------------------------------------------------------------------------------- /source/examples/reduce-alg-lib.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | sum: 523776 6 | partial_sum: 120 7 | -------------------------------------------------------------------------------- /source/examples/specialization-constants.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | using coeff_t = std::array, 3>; 8 | 9 | // Identify the specialization constant. 10 | constexpr sycl::specialization_id coeff_id; 11 | 12 | // Function to get coefficients (in this case, a simple example) 13 | coeff_t get_coefficients() { 14 | // Read coefficients from somewhere or generate them 15 | return {{{1.0f, 2.0f, 1.0f}, {0.0f, 0.0f, 0.0f}, {-1.0f, -2.0f, -1.0f}}}; 16 | } 17 | 18 | // Convolution kernel function 19 | void do_conv(sycl::buffer &in, sycl::buffer &out, 20 | coeff_t coefficients) { 21 | sycl::property_list properties{sycl::property::queue::enable_profiling()}; 22 | auto myQueue = sycl::queue(sycl::default_selector_v, properties); 23 | 24 | myQueue.submit([&](sycl::handler &cgh) { 25 | sycl::accessor in_acc{in, cgh, sycl::read_only}; 26 | sycl::accessor out_acc{out, cgh, sycl::write_only}; 27 | 28 | // Set the coefficient of the convolution as constant. 29 | // This will build a specific kernel the coefficient available as literals. 30 | cgh.set_specialization_constant(get_coefficients()); 31 | 32 | cgh.parallel_for( 33 | in.get_range(), [=](sycl::item<2> item_id, sycl::kernel_handler h) { 34 | float acc = 0; 35 | coeff_t coeff = h.get_specialization_constant(); 36 | for (int i = -1; i <= 1; i++) { 37 | if (item_id[0] + i < 0 || item_id[0] + i >= in_acc.get_range()[0]) 38 | continue; 39 | for (int j = -1; j <= 1; j++) { 40 | if (item_id[1] + j < 0 || item_id[1] + j >= in_acc.get_range()[1]) 41 | continue; 42 | // The underlying JIT can see all the values of the array returned 43 | // by coeff.get(). 44 | acc += 45 | coeff[i + 1][j + 1] * in_acc[item_id[0] + i][item_id[1] + j]; 46 | } 47 | } 48 | out_acc[item_id] = acc; 49 | }); 50 | }); 51 | 52 | myQueue.wait(); 53 | } 54 | 55 | void printResults(sycl::buffer &input_buf, 56 | sycl::buffer &output_buf, 57 | const coeff_t &coefficients, size_t width, size_t height) { 58 | auto accessorIn = input_buf.get_access(); 59 | auto accessorOut = output_buf.get_access(); 60 | 61 | std::cout << "Input:" << std::endl; 62 | for (size_t y = 0; y < height; ++y) { 63 | for (size_t x = 0; x < width; ++x) { 64 | std::cout << accessorIn[x][y] << " "; 65 | } 66 | std::cout << std::endl; 67 | } 68 | 69 | std::cout << "\nOutput after convolution:" << std::endl; 70 | for (size_t y = 0; y < height; ++y) { 71 | for (size_t x = 0; x < width; ++x) { 72 | std::cout << accessorOut[x][y] << " "; 73 | } 74 | std::cout << std::endl; 75 | } 76 | 77 | std::cout << "\nCoefficients:" << std::endl; 78 | for (const auto &row : coefficients) { 79 | for (const auto &value : row) { 80 | std::cout << value << " "; 81 | } 82 | std::cout << std::endl; 83 | } 84 | } 85 | 86 | int main() { 87 | constexpr size_t width = 10; 88 | constexpr size_t height = 10; 89 | 90 | // Create input and output buffers 91 | sycl::buffer input_buf(sycl::range<2>(width, height)); 92 | sycl::buffer output_buf(sycl::range<2>(width, height)); 93 | 94 | // Get coefficients 95 | coeff_t coefficients = get_coefficients(); 96 | 97 | // Call convolution function 98 | do_conv(input_buf, output_buf, coefficients); 99 | 100 | // Print input, output, and coefficients using printResults function 101 | printResults(input_buf, output_buf, coefficients, width, height); 102 | 103 | return 0; 104 | } 105 | -------------------------------------------------------------------------------- /source/examples/specialization-constants.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Input: 6 | 0 0 9.69007e-38 9.69894e-38 0 0 9.69061e-38 9.69894e-38 0 0 7 | 0 0 0 0 0 0 0 0 0 0 8 | 0 9.68996e-38 9.69894e-38 0 0 9.6905e-38 9.69894e-38 0 0 9.69104e-38 9 | 0 0 0 0 0 0 0 0 0 0 10 | 9.68986e-38 9.69894e-38 0 0 9.69039e-38 9.69894e-38 0 0 9.69093e-38 9.69894e-38 11 | 0 0 0 0 0 0 0 0 0 0 12 | 9.69894e-38 0 0 9.69029e-38 9.69894e-38 0 0 9.69082e-38 9.69894e-38 0 13 | 0 0 0 0 0 0 0 0 0 0 14 | 0 0 9.69018e-38 9.69894e-38 0 0 9.69072e-38 9.69894e-38 0 0 15 | 0 0 0 0 0 0 0 0 0 0 16 | 17 | Output after convolution: 18 | 0 -1.93801e-37 -1.93979e-37 1.93801e-37 1.93979e-37 -1.93812e-37 -1.93979e-37 1.93812e-37 1.93979e-37 0 19 | -9.68996e-38 -1.9389e-37 -8.97728e-41 1.9389e-37 8.43918e-41 -1.93895e-37 -8.43918e-41 1.93895e-37 7.90108e-41 0 20 | -1.93799e-37 -1.93979e-37 1.93799e-37 1.93979e-37 -1.9381e-37 -1.93979e-37 1.9381e-37 1.93979e-37 -1.93821e-37 0 21 | -1.93889e-37 -9.0849e-41 1.93889e-37 8.5468e-41 -1.93894e-37 -8.5468e-41 1.93894e-37 8.0087e-41 -1.939e-37 9.69093e-38 22 | -1.93979e-37 1.93797e-37 1.93979e-37 -1.93808e-37 -1.93979e-37 1.93808e-37 1.93979e-37 -1.93819e-37 -1.93979e-37 1.93819e-37 23 | -9.69894e-38 1.93888e-37 8.65442e-41 -1.93893e-37 -8.65442e-41 1.93893e-37 8.11632e-41 -1.93899e-37 -8.11632e-41 1.93899e-37 24 | 0 1.93979e-37 -1.93806e-37 -1.93979e-37 1.93806e-37 1.93979e-37 -1.93816e-37 -1.93979e-37 1.93816e-37 1.93979e-37 25 | 0 8.76204e-41 -1.93892e-37 -8.76204e-41 1.93892e-37 8.22394e-41 -1.93898e-37 -8.22394e-41 1.93898e-37 9.69894e-38 26 | 0 -1.93804e-37 -1.93979e-37 1.93804e-37 1.93979e-37 -1.93814e-37 -1.93979e-37 1.93814e-37 1.93979e-37 0 27 | 0 -9.69018e-38 -9.69894e-38 9.69018e-38 9.69894e-38 -9.69072e-38 -9.69894e-38 9.69072e-38 9.69894e-38 0 28 | 29 | Coefficients: 30 | 1 2 1 31 | 0 0 0 32 | -1 -2 -1 33 | -------------------------------------------------------------------------------- /source/examples/std-vector.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | 9 | constexpr int size = 10; 10 | 11 | int main() { 12 | sycl::queue q; 13 | 14 | // USM allocator for data of type int in shared memory 15 | typedef sycl::usm_allocator vec_alloc; 16 | // Create allocator for device associated with q 17 | vec_alloc myAlloc(q); 18 | // Create std vectors with the allocator 19 | std::vector a(size, myAlloc), b(size, myAlloc), 20 | c(size, myAlloc); 21 | 22 | // Get pointer to vector data for access in kernel 23 | auto A = a.data(); 24 | auto B = b.data(); 25 | auto C = c.data(); 26 | 27 | for (int i = 0; i < size; i++) { 28 | a[i] = i; 29 | b[i] = i; 30 | c[i] = i; 31 | } 32 | 33 | q.submit([&](sycl::handler &h) { 34 | h.parallel_for(sycl::range<1>(size), 35 | [=](sycl::id<1> idx) { C[idx] = A[idx] + B[idx]; }); 36 | }).wait(); 37 | 38 | for (int i = 0; i < size; i++) 39 | std::cout << c[i] << std::endl; 40 | return 0; 41 | } 42 | -------------------------------------------------------------------------------- /source/examples/std-vector.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | 0 6 | 2 7 | 4 8 | 6 9 | 8 10 | 10 11 | 12 12 | 14 13 | 16 14 | 18 15 | -------------------------------------------------------------------------------- /source/examples/stream.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | int main() { 8 | sycl::queue q; 9 | 10 | q.submit([&](sycl::handler &cgh) { 11 | // Setup sycl::stream class to print standard output from 12 | // the device code 13 | auto out = sycl::stream(1024, 768, cgh); 14 | 15 | cgh.single_task([=]() { out << "In a task\n"; }); 16 | }); 17 | 18 | q.wait(); 19 | } 20 | -------------------------------------------------------------------------------- /source/examples/stream.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | In a task 6 | -------------------------------------------------------------------------------- /source/examples/usm-device.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | 9 | int main() { 10 | // Create a default queue to enqueue work to the default device 11 | sycl::queue myQueue; 12 | 13 | // Allocate shared memory bound to the device and context associated to the 14 | // queue 15 | int *data = sycl::malloc_device(1024, myQueue); 16 | 17 | myQueue.parallel_for(1024, [=](sycl::id<1> idx) { 18 | // Initialize each buffer element with its own rank number starting at 0 19 | data[idx] = idx; 20 | }); // End of the kernel function 21 | 22 | // Explicitly wait for kernel execution since there is no accessor involved 23 | myQueue.wait(); 24 | 25 | // Create an array to receive the device content 26 | int hostData[1024]; 27 | // Receive the content from the device 28 | myQueue.memcpy(hostData, data, 1024 * sizeof(int)); 29 | // Wait for the copy to complete 30 | myQueue.wait(); 31 | 32 | // Print result 33 | for (int i = 0; i < 1024; i++) 34 | std::cout << "hostData[" << i << "] = " << hostData[i] << std::endl; 35 | 36 | return 0; 37 | } 38 | -------------------------------------------------------------------------------- /source/examples/usm-implicit-data-movement.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | constexpr int N = 42; 8 | 9 | int main() { 10 | sycl::property_list properties{sycl::property::queue::enable_profiling()}; 11 | auto q = sycl::queue(sycl::default_selector_v, properties); 12 | 13 | std::cout 14 | << " Platform: " 15 | << q.get_device().get_platform().get_info() 16 | << std::endl; 17 | 18 | int *host_array = sycl::malloc_host(N, q); 19 | int *shared_array = sycl::malloc_shared(N, q); 20 | 21 | for (int i = 0; i < N; i++) { 22 | // Initialize hostArray on host 23 | host_array[i] = i; 24 | } 25 | 26 | q.submit([&](sycl::handler &h) { 27 | h.parallel_for(N, [=](sycl::id<1> i) { 28 | // access sharedArray and hostArray on device 29 | shared_array[i] = host_array[i] + 1; 30 | }); 31 | }); 32 | q.wait(); 33 | 34 | for (int i = 0; i < N; i++) { 35 | // access sharedArray on host 36 | host_array[i] = shared_array[i]; 37 | } 38 | 39 | sycl::free(shared_array, q); 40 | sycl::free(host_array, q); 41 | 42 | return 0; 43 | } 44 | -------------------------------------------------------------------------------- /source/examples/usm-implicit-data-movement.out: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: CC-BY-4.0 4 | 5 | Platform: Intel(R) Level-Zero 6 | -------------------------------------------------------------------------------- /source/examples/usm-shared.cpp: -------------------------------------------------------------------------------- 1 | // SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | // 3 | // SPDX-License-Identifier: Apache-2.0 4 | 5 | #include 6 | 7 | #include 8 | 9 | int main() { 10 | // Create a default queue to enqueue work to the default device 11 | sycl::queue myQueue; 12 | 13 | // Allocate shared memory bound to the device and context associated to the 14 | // queue Replacing malloc_shared with malloc_host would yield a correct 15 | // program that allocated device-visible memory on the host. 16 | int *data = sycl::malloc_shared(1024, myQueue); 17 | 18 | myQueue.parallel_for(1024, [=](sycl::id<1> idx) { 19 | // Initialize each buffer element with its own rank number starting at 0 20 | data[idx] = idx; 21 | }); // End of the kernel function 22 | 23 | // Explicitly wait for kernel execution since there is no accessor involved 24 | myQueue.wait(); 25 | 26 | // Print result 27 | for (int i = 0; i < 1024; i++) 28 | std::cout << "data[" << i << "] = " << data[i] << std::endl; 29 | 30 | return 0; 31 | } 32 | -------------------------------------------------------------------------------- /source/generic-and-non-generic.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | *************************** 6 | Generic vs non-generic SYCL 7 | *************************** 8 | 9 | The SYCL programming API is split into two categories; generic SYCL 10 | and non-generic SYCL. Almost everything in the SYCL programming API 11 | is considered generic SYCL. However any usage of the 12 | ``enum class backend`` is considered non-generic SYCL and should only 13 | be used for SYCL backend specialized code paths, as the identifiers 14 | defined in ``backend`` are implementation-defined. 15 | 16 | In any non-generic SYCL application code where the ``backend`` enum 17 | class is used, the expression must be guarded with a preprocessor 18 | ``#ifdef`` guard using the associated preprocessor macro to ensure 19 | that the SYCL application will compile even if the SYCL implementation 20 | does not support that SYCL backend being specialized for. 21 | -------------------------------------------------------------------------------- /source/header-file.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ============== 6 | Header Files 7 | ============== 8 | 9 | SYCL provides a single standard header file: 10 | 11 | :: 12 | 13 | #include 14 | 15 | which needs to be included in every translation unit that uses the SYCL 16 | programming API. 17 | 18 | For compatibility with the earlier version; SYCL 1.2.1, SYCL also provides 19 | another header file: 20 | 21 | :: 22 | 23 | #include 24 | 25 | which can be used in place of ``sycl/sycl.hpp``, providing all of the same SYCL 26 | programming API, though it is recommended to use ``sycl/sycl.hpp``. 27 | 28 | Extension headers are available in ``sycl/ext/`` include paths and backend- 29 | specific headers are available in ``sycl/backend/`` include paths. 30 | 31 | .. seealso:: |SYCL_SPEC_HEADER_FILES| 32 | -------------------------------------------------------------------------------- /source/host-task.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ========= 6 | Host task 7 | ========= 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | iface/host-task-basic 13 | iface/interop_handle 14 | iface/host-task-add-to-handler 15 | -------------------------------------------------------------------------------- /source/iface/accessors.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-accessors: 6 | 7 | ========= 8 | Accessors 9 | ========= 10 | 11 | An accessor provides access to the data managed by a buffer or image, 12 | or to shared local memory allocated by the runtime. 13 | 14 | .. toctree:: 15 | :maxdepth: 1 16 | 17 | accessor-concept 18 | command-accessor 19 | host_accessor 20 | local_accessor 21 | unsampled-image-accessor 22 | sampled-image-accessor 23 | -------------------------------------------------------------------------------- /source/iface/async_handler.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-async-error-handler: 6 | 7 | ************************** 8 | Asynchronous error handler 9 | ************************** 10 | 11 | :: 12 | 13 | namespace sycl { 14 | 15 | using async_handler = std::function; 16 | 17 | } // namespace sycl 18 | 19 | The :ref:`queue` and :ref:`context` classes can optionally take 20 | an asynchronous handler object ``sycl::async_handler`` on construction, 21 | which is a callable such as a `function class` or `lambda`, with 22 | an ``sycl::exception_list`` as a parameter. Invocation of an 23 | ``sycl::async_handler`` may be triggered by the queue member functions 24 | ``sycl::queue::wait_and_throw()`` or ``sycl::queue::throw_asynchronous()``, 25 | by the ``sycl::event`` member function ``sycl::event::wait_and_throw()``, 26 | or automatically on destruction of a :ref:`queue` or :ref:`context` that 27 | contains unconsumed asynchronous errors. When invoked, an 28 | ``sycl::async_handler`` is called and receives an ``sycl::exception_list`` 29 | argument containing a list of exception objects representing any unconsumed 30 | asynchronous errors associated with the :ref:`queue` or :ref:`context`. 31 | 32 | When an asynchronous error instance has been passed to an 33 | ``sycl::async_handler``, then that instance of the error 34 | has been consumed for handling and is not reported on any 35 | subsequent invocations of the ``sycl::async_handler``. 36 | 37 | The ``sycl::async_handler`` may be a named function object type, a 38 | lambda function or a ``std::function``. The ``sycl::exception_list`` object 39 | passed to the ``sycl::async_handler`` is constructed by the SYCL runtime. 40 | 41 | .. seealso:: 42 | 43 | |SYCL_SPEC_ASYNC_ERR_HAND| 44 | 45 | :ref:`iface-error-handling-rules` 46 | 47 | :ref:`iface-exceptions` 48 | 49 | .. _behavior-without-async_hand: 50 | 51 | =========================================== 52 | Behavior without an ``sycl::async_handler`` 53 | =========================================== 54 | 55 | If an asynchronous error occurs in a :ref:`queue` or :ref:`context` that 56 | has no user-supplied asynchronous error handler object ``sycl::async_handler``, 57 | then an implementation-defined default ``sycl::async_handler`` is called to 58 | handle the error in the same situations that a user-supplied 59 | ``sycl::async_handler`` would be, as defined in section above. 60 | 61 | The default ``sycl::async_handler`` must in some way report all errors 62 | passed to it, when possible, and must then invoke ``std::terminate`` 63 | or equivalent. 64 | 65 | .. _async_handler_example: 66 | 67 | ========= 68 | Example 1 69 | ========= 70 | 71 | Below is example of implementing an ``sycl::async_handler`` as lambda 72 | function and passing it to the :ref:`queue`. 73 | 74 | .. literalinclude:: /examples/async-handler.cpp 75 | :lines: 5- 76 | :linenos: 77 | 78 | Output: 79 | 80 | .. literalinclude:: /examples/async-handler.out 81 | :lines: 5- 82 | -------------------------------------------------------------------------------- /source/iface/barriers-and-fences.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-barriers-and-fences: 6 | 7 | ******************* 8 | Barriers and fences 9 | ******************* 10 | 11 | :: 12 | 13 | namespace sycl { 14 | 15 | void atomic_fence(sycl::memory_order order, sycl::memory_scope scope); 16 | 17 | } // namespace sycl 18 | 19 | A group barrier or memory-fence provides memory ordering semantics 20 | over both the local address space and global address space. 21 | 22 | A memory-fence provides control over the re-ordering of memory load 23 | and store operations, subject to the associated memory ``order`` and 24 | memory ``scope``, when paired with synchronization through an atomic 25 | object. 26 | 27 | The effects of a call to ``sycl::atomic_fence`` depend on the value 28 | of the ``order`` parameter: 29 | 30 | * ``sycl::memory_order::relaxed``: No effect. 31 | 32 | * ``sycl::memory_order::acquire``: Acquire fence. 33 | 34 | * ``sycl::memory_order::release``: Release fence. 35 | 36 | * ``sycl::memory_order::acq_rel``: Both an acquire fence and a release fence. 37 | 38 | * ``sycl::memory_order::seq_cst``: A sequentially consistent acquire 39 | and release fence. 40 | 41 | A group barrier acts as both an acquire fence and a release fence: all 42 | work-items in the group execute a release fence prior to synchronizing 43 | at the barrier, and all work-items in the group execute an acquire 44 | fence afterwards. 45 | 46 | A group barrier provides implicit atomic synchronization as if through 47 | an internal atomic object, such that the acquire and release fences 48 | associated with the barrier synchronize with each other, without an 49 | explicit atomic operation being required on an atomic object to 50 | synchronize the fences. 51 | 52 | .. seealso:: |SYCL_SPEC_BARRIERS_FENCES| 53 | -------------------------------------------------------------------------------- /source/iface/common-byval.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _common-byval: 6 | 7 | ************************* 8 | Common By-value Semantics 9 | ************************* 10 | 11 | Each of the following SYCL runtime classes: 12 | :ref:`id`, :ref:`range`, :ref:`item`, :ref:`nd_item`, 13 | :ref:`h_item`, :ref:`group`, :ref:`sub_group`, and :ref:`nd_range` 14 | must obey the following statements, where ``T`` is the 15 | runtime class type: 16 | 17 | * ``T`` must be default copy constructible and copy assignable 18 | in the host application (in the case where ``T`` is available on 19 | the host) and within SYCL kernel functions. 20 | * ``T`` must be default destructible in the host application 21 | (in the case where ``T`` is available on the host) and 22 | within SYCL kernel functions. 23 | * ``T`` must be default move constructible and default move 24 | assignable in the host application (in the case where ``T`` 25 | is available on the host) and within SYCL kernel functions. 26 | * ``T`` must be equality comparable in the host application 27 | (in the case where ``T`` is available on the host) and 28 | within SYCL kernel functions. Equality between two 29 | instances of ``T`` (i.e. ``a == b``) must be true if the 30 | value of all members are equal and non-equality between 31 | two instances of ``T`` (i.e. ``a != b``) must be true 32 | if the value of any members are not equal, unless either 33 | instance has become invalidated by a move operation. 34 | By extension of the requirements above, equality on ``T`` 35 | must guarantee to be reflexive (i.e. ``a == a``), 36 | symmetric (i.e. ``a == b`` implies ``b == a`` and ``a != b`` 37 | implies ``b != a``) and transitive (i.e. ``a == b 38 | && b == c`` implies ``c == a``). 39 | 40 | Some SYCL runtime classes will have additional behavior 41 | associated with copy, movement, assignment or destruction 42 | semantics. If these are specified they are in addition 43 | to those specified above unless stated otherwise. 44 | 45 | Each of the runtime classes mentioned above must provide 46 | a common interface of special member functions, member functions, 47 | and friend functions in order to fulfill the copy, move, destruction 48 | and equality requirements, following the *rule of five* 49 | and the *rule of zero*. 50 | 51 | :: 52 | 53 | namespace sycl { 54 | 55 | class T { 56 | ... 57 | 58 | public: 59 | 60 | // If any of the following five special member functions are not 61 | // public, inline or defaulted, then all five of them should be 62 | // explicitly declared (see rule of five). 63 | // Otherwise, none of them should be explicitly declared 64 | // (see rule of zero). 65 | 66 | // T(const T &rhs); 67 | 68 | // T(T &&rhs); 69 | 70 | // T &operator=(const T &rhs); 71 | 72 | // T &operator=(T &&rhs); 73 | 74 | // ~T(); 75 | 76 | ... 77 | 78 | friend bool operator==(const T& lhs, const T& rhs) { /* ... */ } 79 | 80 | friend bool operator!=(const T& lhs, const T& rhs) { /* ... */ } 81 | 82 | ... 83 | }; 84 | 85 | } // namespace sycl 86 | 87 | .. seealso:: |SYCL_SPEC_COMMON_BYVAL| 88 | 89 | .. _byval_special_member_func: 90 | 91 | ====================================================== 92 | Common special member functions for by-value semantics 93 | ====================================================== 94 | 95 | 96 | .. list-table:: 97 | :header-rows: 1 98 | 99 | * - Special member function 100 | - Description 101 | * - ``T(const T& rhs);`` 102 | - Copy constructor. 103 | * - ``T(T&& rhs);`` 104 | - Move constructor. 105 | * - ``T& operator=(const T& rhs);`` 106 | - Copy assignment operator. 107 | * - ``T& operator=(T&& rhs);`` 108 | - Move assignment operator. 109 | * - ``~T();`` 110 | - Destructor. 111 | 112 | .. _byval_hidden_friend_func: 113 | 114 | ===================================================== 115 | Common hidden friend functions for by-value semantics 116 | ===================================================== 117 | 118 | .. list-table:: 119 | :header-rows: 1 120 | 121 | * - Hidden friend function 122 | - Description 123 | * - :: 124 | 125 | friend bool operator!=(const T& lhs, const T& rhs); 126 | 127 | - Returns ``true`` if this LHS SYCL ``T`` is equal to the 128 | RHS SYCL ``T`` in accordance with the requirements set 129 | out above, otherwise returns ``false``. 130 | * - :: 131 | 132 | friend bool operator!=(const T& lhs, const T& rhs); 133 | 134 | - Returns ``true`` if this LHS SYCL ``T`` is not equal to the 135 | RHS SYCL ``T`` in accordance with the requirements set out 136 | above, otherwise returns ``false``. 137 | -------------------------------------------------------------------------------- /source/iface/device-selector.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _device-selectors: 6 | .. _device_selector: 7 | 8 | **************** 9 | Device selectors 10 | **************** 11 | 12 | Device selectors allow the SYCL runtime to choose the device. 13 | 14 | A device selector can be passed to :ref:`queue`, :ref:`platform`, and 15 | other constructors to control the selection of a device. A program may 16 | use `Built-in Device Selectors`_ or define its own device selector for 17 | full control. 18 | 19 | The interface for a device selector is any object that meets the C++ named 20 | requirement ``Callable`` taking a ``const`` :ref:`device` reference and 21 | returning a value implicitly convertible to a ``int``. 22 | 23 | At any point where the SYCL runtime needs to select a SYCL device using 24 | a device selector, the system queries all root devices from all SYCL 25 | backends in the system, calls the device selector on each device and 26 | selects the one which returns the highest score. If the highest 27 | value is strictly negative no device is selected. 28 | 29 | In places where only one device has to be picked and the high score is 30 | obtained by more than one device, then one of the tied devices will be 31 | returned, but which one is not defined and may depend on enumeration 32 | order, for example, outside the control of the SYCL runtime. 33 | 34 | 35 | .. _built-in-device-selectors: 36 | 37 | ========================= 38 | Built-in Device Selectors 39 | ========================= 40 | 41 | Standard device selectors included with all SYCL implementations: 42 | 43 | .. list-table:: 44 | 45 | * - ``sycl::default_selector_v`` 46 | - Select a SYCL device from any supported SYCL backend based on an implementation-defined 47 | heuristic. Since all implementations must support at least one device, this selector must always return a device. 48 | * - ``sycl::gpu_selector_v`` 49 | - Select a SYCL device from any supported SYCL backend for which the device type is ``info::device_type::gpu``. 50 | * - ``sycl::accelerator_selector_v`` 51 | - Select a SYCL device from any supported SYCL backend for which the device type is ``info::device_type::accelerator``. 52 | * - ``sycl::cpu_selector_v`` 53 | - Select a SYCL device from any supported SYCL backend for which the device type is ``info::device_type::cpu``. 54 | * - :: 55 | 56 | __unspecified_callable__ 57 | sycl::aspect_selector(const std::vector& aspectList, 58 | const std::vector& denyList = {}); 59 | 60 | template 61 | __unspecified_callable__ 62 | sycl::aspect_selector(AspectList... aspectList); 63 | 64 | template 65 | __unspecified_callable__ sycl::aspect_selector(); 66 | 67 | - The free function ``sycl::aspect_selector`` has several overloads, each of which returns a selector object that selects a SYCL 68 | device from any supported SYCL backend which contains all the requested aspects. 69 | If no aspects are passed in, the generated selector behaves like ``sycl::default_selector``. 70 | 71 | Required aspects can be passed in as a vector, as function arguments, or as template parameters, depending on the 72 | function overload. The function overload that takes ``aspectList`` as a vector takes another vector argument ``denyList`` 73 | where the user can specify all the aspects that have to be avoided. 74 | 75 | The SYCL class constructor using ``sycl::gpu_selector_v``, 76 | ``sycl::accelerator_selector_v``, ``sycl::cpu_selector_v``, 77 | or ``sycl::aspect_selector`` must throw an exception with 78 | the ``sycl::errc::runtime`` error code if no device matching 79 | the requirement can be found. 80 | 81 | .. _device-selector-SYCL121: 82 | 83 | ============================== 84 | Device Selectors in SYCL 1.2.1 85 | ============================== 86 | 87 | In SYCL 1.2.1 the predefined device selectors were 88 | types that had to be instantiated to be used. 89 | 90 | To simplify porting code using the old type instantiations, a 91 | backward-compatible API is still provided, such as ``sycl::default_selector``. 92 | 93 | The new predefined device selectors have their new names appended 94 | with "_v" to avoid conflicts, thus following the naming style used by 95 | traits in the C++ standard library. 96 | 97 | .. seealso:: |SYCL_SPEC_DEVICE_SELECTORS| 98 | 99 | .. _device-selector-example: 100 | 101 | ========= 102 | Example 1 103 | ========= 104 | 105 | .. literalinclude:: /examples/gpu-selector.cpp 106 | :lines: 5- 107 | :linenos: 108 | 109 | Output on a system without a GPU: 110 | 111 | .. literalinclude:: /examples/gpu-selector.out 112 | :lines: 5- 113 | -------------------------------------------------------------------------------- /source/iface/device_event.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _device_event: 6 | 7 | ********************** 8 | ``sycl::device_event`` 9 | ********************** 10 | 11 | :: 12 | 13 | namespace sycl { 14 | 15 | class device_event { 16 | device_event(__unspecified__); 17 | 18 | public: 19 | void wait() noexcept; 20 | }; 21 | 22 | } // namespace sycl 23 | 24 | The ``sycl::device_event`` class encapsulates a single SYCL 25 | device event which is available only within SYCL kernel 26 | functions and can be used to wait for asynchronous operations 27 | within a SYCL kernel function to complete. 28 | 29 | All member functions of the ``sycl::device_event`` class must 30 | not throw a ``sycl::exception``. 31 | 32 | .. seealso:: |SYCL_SPEC_DEVICE_EVENT| 33 | 34 | ============== 35 | (constructors) 36 | ============== 37 | 38 | :: 39 | 40 | device_event(___unspecified___); 41 | 42 | Unspecified implementation-defined constructor. 43 | 44 | ================ 45 | Member functions 46 | ================ 47 | 48 | ``wait`` 49 | ======== 50 | 51 | :: 52 | 53 | void wait() noexcept; 54 | 55 | Waits for the asynchronous operation associated with this 56 | ``sycl::device_event`` to complete. 57 | -------------------------------------------------------------------------------- /source/iface/device_image.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _device_image: 6 | 7 | ********************** 8 | ``sycl::device_image`` 9 | ********************** 10 | 11 | :: 12 | 13 | template 14 | class device_image; 15 | 16 | .. seealso:: |SYCL_SPEC_DEVICE_IMAGE| 17 | 18 | (constructors) 19 | ============== 20 | 21 | :: 22 | 23 | bool has_kernel(const sycl::kernel_id& kernelId) const noexcept; // (1) 24 | 25 | bool has_kernel(const sycl::kernel_id& kernelId, 26 | const sycl::device& dev) const noexcept; // (2) 27 | 28 | There is no public constructor for this class. 29 | 30 | 1. Returns: ``true`` only if the device image contains the kernel 31 | identified by ``kernelId``. 32 | 33 | 2. Returns: ``true`` only if the device image contains the kernel 34 | identified by ``kernelId`` and if that kernel 35 | is compatible with the device ``dev``. 36 | 37 | A synopsis of the ``sycl::device_image`` class is shown below. 38 | 39 | :: 40 | 41 | namespace sycl { 42 | 43 | template 44 | class device_image { 45 | public: 46 | device_image() = delete; 47 | 48 | bool has_kernel(const sycl::kernel_id& kernelId) const noexcept; 49 | 50 | bool has_kernel(const sycl::kernel_id& kernelId, 51 | const sycl::device& dev) const noexcept; 52 | }; 53 | 54 | } // namespace sycl 55 | -------------------------------------------------------------------------------- /source/iface/function-objects.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _function-objects: 6 | 7 | **************** 8 | Function objects 9 | **************** 10 | 11 | SYCL provides a number of function objects in the ``sycl`` namespace on 12 | host and device. All function objects obey C++ conversion and promotion 13 | rules. Each function object is additionally specialized for ``void`` as 14 | a transparent function object that deduces its parameter types and 15 | return type. 16 | 17 | .. seealso:: |SYCL_SPEC_FUNCTION_OBJECTS|. 18 | 19 | :: 20 | 21 | namespace sycl { 22 | 23 | template struct plus { 24 | T operator()(const T& x, const T& y) const; 25 | }; 26 | 27 | template struct multiplies { 28 | T operator()(const T& x, const T& y) const; 29 | }; 30 | 31 | template struct bit_and { 32 | T operator()(const T& x, const T& y) const; 33 | }; 34 | 35 | template struct bit_or { 36 | T operator()(const T& x, const T& y) const; 37 | }; 38 | 39 | template struct bit_xor { 40 | T operator()(const T& x, const T& y) const; 41 | }; 42 | 43 | template struct logical_and { 44 | T operator()(const T& x, const T& y) const; 45 | }; 46 | 47 | template struct logical_or { 48 | T operator()(const T& x, const T& y) const; 49 | }; 50 | 51 | template struct minimum { 52 | T operator()(const T& x, const T& y) const; 53 | }; 54 | 55 | template struct maximum { 56 | T operator()(const T& x, const T& y) const; 57 | }; 58 | 59 | } // namespace sycl 60 | 61 | ================ 62 | Member functions 63 | ================ 64 | 65 | ``sycl::plus`` 66 | ============== 67 | 68 | :: 69 | 70 | T operator()(const T& x, const T& y) const 71 | 72 | Returns the sum of its arguments, equivalent to ``x + y``. 73 | 74 | ``sycl::multiplies`` 75 | ==================== 76 | 77 | :: 78 | 79 | T operator()(const T& x, const T& y) const 80 | 81 | Returns the product of its arguments, equivalent to ``x * y``. 82 | 83 | ``sycl::bit_and`` 84 | ================= 85 | 86 | :: 87 | 88 | T operator()(const T& x, const T& y) const 89 | 90 | Returns the bitwise AND of its arguments, equivalent to ``x & y``. 91 | 92 | ``sycl::bit_or`` 93 | ================ 94 | 95 | :: 96 | 97 | T operator()(const T& x, const T& y) const 98 | 99 | Returns the bitwise OR of its arguments, equivalent to ``x | y``. 100 | 101 | ``sycl::bit_xor`` 102 | ================= 103 | 104 | :: 105 | 106 | T operator()(const T& x, const T& y) const 107 | 108 | Returns the bitwise XOR of its arguments, equivalent to ``x ^ y``. 109 | 110 | ``sycl::logical_and`` 111 | ===================== 112 | 113 | :: 114 | 115 | T operator()(const T& x, const T& y) const 116 | 117 | Returns the logical AND of its arguments, equivalent to ``x && y``. 118 | 119 | ``sycl::logical_or`` 120 | ==================== 121 | 122 | :: 123 | 124 | T operator()(const T& x, const T& y) const 125 | 126 | Returns the logical OR of its arguments, equivalent to ``x || y``. 127 | 128 | ``sycl::minimum`` 129 | ================= 130 | 131 | :: 132 | 133 | T operator()(const T& x, const T& y) const 134 | 135 | Returns the smaller value. Returns the first argument 136 | when the arguments are equivalent. 137 | 138 | ``sycl::maximum`` 139 | ================= 140 | 141 | :: 142 | 143 | T operator()(const T& x, const T& y) const 144 | 145 | Returns the larger value. Returns the first argument 146 | when the arguments are equivalent. 147 | -------------------------------------------------------------------------------- /source/iface/group-functions.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _group-functions: 6 | 7 | *************** 8 | Group functions 9 | *************** 10 | 11 | SYCL provides a number of functions that expose functionality tied to 12 | groups of work-items (such as group barriers and collective operations). 13 | These group functions act as synchronization points and must be 14 | encountered in converged control flow by all work-items in the group. 15 | If one work-item in a group calls a group function, then all work-items 16 | in that group must call exactly the same function under the same set of 17 | conditions --- calling the same function under different conditions 18 | (e.g. in different iterations of a loop, or different branches of a 19 | conditional statement) results in undefined behavior. Additionally, 20 | restrictions may be placed on the arguments passed to each function 21 | in order to ensure that all work-items in the group agree on the 22 | operation that is being performed. Any such restrictions on the arguments 23 | passed to a function are defined within the descriptions of those 24 | functions. Violating these restrictions results in undefined behavior. 25 | 26 | Using a group function inside of a kernel may introduce additional 27 | limits on the resources available to user code inside the same kernel. 28 | The behavior of these limits is implementation-defined, but must be 29 | reflected by calls to kernel querying functions 30 | (such as ``sycl::kernel::get_info``) as described 31 | in |SYCL_SPEC_QUERIES|. 32 | 33 | It is undefined behavior for any group function to be invoked within 34 | a ``sycl::parallel_for_work_group`` 35 | or ``sycl::parallel_for_work_item`` context. 36 | 37 | ==================== 38 | ``Group type trait`` 39 | ==================== 40 | 41 | :: 42 | 43 | namespace sycl { 44 | template struct is_group; 45 | 46 | template inline constexpr bool is_group_v = is_group::value; 47 | } // namespace sycl 48 | 49 | The ``sycl::is_group`` type trait is used to determine which types 50 | of groups are supported by group functions, and to control when group 51 | functions participate in overload resolution. 52 | 53 | ``sycl::is_group`` inherits from ``std::true_type`` if T is the type of 54 | a standard SYCL group (``sycl::group`` or ``sycl::sub_group``) and 55 | it inherits from ``std::false_type`` otherwise. A SYCL implementation may 56 | introduce additional specializations of ``sycl::is_group`` for 57 | implementation-defined group types, if the interface of those types supports 58 | all member functions and static members common to the ``sycl::group`` 59 | and ``sycl::sub_group`` classes. 60 | 61 | ========================= 62 | ``sycl::group_broadcast`` 63 | ========================= 64 | 65 | The ``sycl::group_broadcast`` function communicates a value held by 66 | one work-item to all other work-items in the group. 67 | 68 | :: 69 | 70 | template 71 | T sycl::group_broadcast(Group g, T x); // (1) 72 | 73 | template 74 | T sycl::group_broadcast(Group g, T x, Group::linear_id_type local_linear_id); // (2) 75 | 76 | template 77 | T group_broadcast(Group g, T x, Group::id_type local_id); // (3) 78 | 79 | 1.Constraints: Available only if ``sycl::is_group_v>`` 80 | is true and ``T`` is a trivially copyable type. 81 | 82 | Returns: The value of ``x`` from the work-item with the smallest 83 | linear id within group ``g``. 84 | 85 | 2.Constraints: Available only if ``sycl::is_group_v>`` 86 | is true and ``T`` is a trivially copyable type. 87 | 88 | Preconditions: ``local_linear_id`` must be the same for all work-items in 89 | the group and must be in the range ``[0, sycl::get_local_linear_range())``. 90 | 91 | Returns: The value of ``x`` from the work-item with the specified 92 | linear id within group ``g``. 93 | 94 | 3.Constraints: Available only if ``sycl::is_group_v>`` 95 | is true and ``T`` is a trivially copyable type. 96 | 97 | Preconditions: ``local_id`` must be the same for all work-items in the group, 98 | and its dimensionality must match the dimensionality of the group. The value 99 | of ``local_id`` in each dimension must be greater than or equal to 0 and less 100 | than the value of ``sycl::get_local_range()`` in the same dimension. 101 | 102 | Returns: The value of ``x`` from the work-item with the 103 | specified id within group ``g``. 104 | 105 | ======================= 106 | ``sycl::group_barrier`` 107 | ======================= 108 | 109 | The ``sycl::group_barrier`` function synchronizes all work-items in a 110 | group, using a group barrier. 111 | 112 | :: 113 | 114 | template 115 | void sycl::group_barrier(Group g, 116 | sycl::memory_scope fence_scope = Group::fence_scope); // (1) 117 | 118 | 1.Constraints: Available only if 119 | ``sycl::is_group_v>`` is true. 120 | 121 | Effects: Synchronizes all work-items in group ``g``. The current work-item 122 | will wait at the barrier until all work-items in group ``g`` have reached 123 | the barrier. In addition, the barrier performs ``mem-fence`` operations 124 | ensuring that memory accesses issued before the barrier are not re-ordered 125 | with those issued after the barrier: all work-items in group ``g`` execute 126 | a release fence prior to synchronizing at the barrier, all work-items in 127 | group ``g`` execute an acquire fence afterwards, and there is an implicit 128 | synchronization of these fences as if provided by an explicit atomic 129 | operation on an atomic object. 130 | 131 | By default, the scope of these fences is set to the narrowest scope 132 | including all work-items in group ``g`` (as reported by 133 | ``Group::fence_scope``). This scope may be optionally overridden with 134 | a wider scope, specified by the ``fence_scope`` argument. 135 | -------------------------------------------------------------------------------- /source/iface/host-task-add-to-handler.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ********************************** 6 | Additions to the ``sycl::handler`` 7 | ********************************** 8 | 9 | This section describes member functions in the command group handler 10 | class that are used with host tasks. 11 | 12 | :: 13 | 14 | class handler { 15 | ... 16 | 17 | public: 18 | template 19 | void host_task(T&& hostTaskCallable); // (1) 20 | 21 | ... 22 | }; 23 | 24 | Effects: Enqueues an implementation-defined command to the SYCL runtime 25 | to invoke ``hostTaskCallable`` exactly once. The scheduling of the 26 | invocation of ``hostTaskCallable`` in relation to other commands 27 | enqueued to the SYCL runtime must be in accordance with the dependency 28 | model described in |SYCL_SPEC_MEM_MODEL|. Initializes an 29 | ``interop_handle`` object and passes it to ``hostTaskCallable`` 30 | when it is invoked if ``std::is_invocable_v`` 31 | evaluates to true, otherwise invokes ``hostTaskCallable`` 32 | as a nullary function. 33 | 34 | .. seealso:: 35 | 36 | |SYCL_SPEC_ADDITION_TO_HANDLER| 37 | 38 | :ref:`handler` 39 | -------------------------------------------------------------------------------- /source/iface/host-task-basic.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _host_task-basic: 6 | 7 | ***************** 8 | Host task concept 9 | ***************** 10 | 11 | A host task is a native C++ callable which is scheduled by the SYCL runtime. 12 | A host task is submitted to a :ref:`queue` via a command group by 13 | a host task command. 14 | 15 | When a host task command is submitted to a :ref:`queue` it is scheduled 16 | based on its data dependencies with other commands including kernel 17 | invocation commands and asynchronous copies, resolving any requisites 18 | created by accessors attached to the command group 19 | as defined in |SYCL_SPEC_MEM_MODEL|. 20 | 21 | Since a host task is invoked directly by the SYCL runtime rather than being 22 | compiled as a SYCL kernel function, it does not have the same restrictions as 23 | a SYCL kernel function, and can therefore contain any arbitrary C++ code. 24 | 25 | Capturing accessors in a host task is allowed, however, capturing or using any 26 | other SYCL class that has reference semantics 27 | (see |SYCL_SPEC_COMMON_REFERENCE|) is undefined behavior. 28 | 29 | A host task can be enqueued on any :ref:`queue` and the callable will be 30 | invoked directly by the SYCL runtime, regardless of which :ref:`device` 31 | the queue is associated with. 32 | 33 | A host task is enqueued on a :ref:`queue` via the ``sycl::host_task`` member 34 | function of the ``sycl::handler`` class. The event returned by the 35 | submission of the associated command group enters the completed state 36 | (corresponding to a status of ``sycl::info::event_command_status::complete``) 37 | once the invocation of the provided C++ callable has returned. Any uncaught 38 | exception thrown during the execution of a host task will be turned 39 | into an asynchronous error that can be handled 40 | as described in |SYCL_SPEC_ASYNC_ERR_HAND|. 41 | 42 | A host task can optionally be used to interoperate with the native backend 43 | objects associated with the :ref:`queue` executing the host task, 44 | the context that the :ref:`queue` is associated with, the :ref:`device` 45 | that the :ref:`queue` is associated with and the accessors that have been 46 | captured in the callable, via an optional ``sycl::interop_handle`` parameter. 47 | 48 | This allows host tasks to be used for two purposes: either as a task which 49 | can perform arbitrary C++ code within the scheduling of the SYCL runtime or 50 | as a task which can perform interoperability at a point within the scheduling 51 | of the SYCL runtime. 52 | 53 | For the former use case, construct a buffer accessor with 54 | ``sycl::target::host_task`` or an image accessor with 55 | ``sycl::image_target::host_task``. This makes the buffer 56 | or image available on the host during execution of the host task. 57 | 58 | For the latter case, construct a buffer accessor with 59 | ``sycl::target::device`` or ``sycl::target::constant_buffer``, 60 | or construct an image accessor with ``sycl::image_target::device``. 61 | This makes the buffer or image available on the :ref:`device` that 62 | is associated with the :ref:`queue` used to submit the host task, 63 | so that it can be accessed via interoperability member functions 64 | provided by the ``sycl::interop_handle`` class. 65 | 66 | .. seealso:: |SYCL_SPEC_HOST_TASKS| 67 | -------------------------------------------------------------------------------- /source/iface/image-sampler.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ************** 6 | Image samplers 7 | ************** 8 | 9 | .. seealso:: |SYCL_SPEC_IMAGE_SAMPLER| 10 | 11 | .. _image_sampler: 12 | 13 | ======================= 14 | ``sycl::image_sampler`` 15 | ======================= 16 | 17 | :: 18 | 19 | namespace sycl { 20 | 21 | struct image_sampler { 22 | addressing_mode addressing; 23 | coordinate_normalization_mode coordinate; 24 | filtering_mode filtering; 25 | }; 26 | 27 | } // namespace sycl 28 | 29 | The ``sycl::image_sampler`` struct contains a configuration 30 | for sampling a :ref:`sampled_image`. 31 | 32 | The members of this struct are defined by the following tables. 33 | 34 | ========================= 35 | ``sycl::addressing_mode`` 36 | ========================= 37 | 38 | :: 39 | 40 | namespace sycl { 41 | 42 | enum class addressing_mode : /* unspecified */ { 43 | mirrored_repeat, 44 | repeat, 45 | clamp_to_edge, 46 | clamp, 47 | none 48 | }; 49 | 50 | } // namespace sycl 51 | 52 | .. list-table:: 53 | :header-rows: 1 54 | 55 | * - Addressing mode 56 | - Description 57 | * - ``sycl::addressing_mode::mirrored_repeat`` 58 | - Out of range coordinates will be flipped at every integer junction. 59 | 60 | This addressing mode can only be used with normalized coordinates. 61 | If normalized coordinates are not used, this addressing mode may 62 | generate image coordinates that are undefined. 63 | * - ``sycl::addressing_mode::repeat`` 64 | - Out of range image coordinates are wrapped to the valid range. 65 | 66 | This addressing mode can only be used with normalized coordinates. 67 | If normalized coordinates are not used, this addressing mode may 68 | generate image coordinates that are undefined. 69 | * - ``sycl::addressing_mode::clamp_to_edge`` 70 | - Out of range image coordinates are clamped to the extent. 71 | * - ``sycl::addressing_mode::clamp`` 72 | - Out of range image coordinates will return a border color. 73 | * - ``sycl::addressing_mode::none`` 74 | - For this addressing mode the programmer guarantees that 75 | the image coordinates used to sample elements of the 76 | image refer to a location inside the image; otherwise 77 | the results are undefined. 78 | 79 | ======================== 80 | ``sycl::filtering_mode`` 81 | ======================== 82 | 83 | :: 84 | 85 | namespace sycl { 86 | 87 | enum class filtering_mode : /* unspecified */ { 88 | nearest, 89 | linear 90 | }; 91 | 92 | } //namespace sycl 93 | 94 | .. list-table:: 95 | :header-rows: 1 96 | 97 | * - Filtering mode 98 | - Description 99 | * - ``sycl::filtering_mode::nearest`` 100 | - Chooses a color of nearest pixel. 101 | * - ``sycl::filtering_mode::linear`` 102 | - Performs a linear sampling of adjacent pixels. 103 | 104 | ======================================= 105 | ``sycl::coordinate_normalization_mode`` 106 | ======================================= 107 | 108 | :: 109 | 110 | namespace sycl { 111 | 112 | enum class coordinate_normalization_mode : /* unspecified */ { 113 | normalized, 114 | unnormalized 115 | }; 116 | 117 | } // namespace sycl 118 | 119 | .. list-table:: 120 | :header-rows: 1 121 | 122 | * - Coordinate normalization mode 123 | - Description 124 | * - ``sycl::coordinate_normalization_mode::normalized`` 125 | - Normalizes image coordinates. 126 | * - ``sycl::coordinate_normalization_mode::unnormalized`` 127 | - Does not normalize image coordinates. 128 | -------------------------------------------------------------------------------- /source/iface/interaction-with-host-code.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _interaction_with_host_code: 6 | 7 | ************************** 8 | Interaction with host code 9 | ************************** 10 | 11 | When a kernel runs on a device that has either 12 | ``sycl::aspect::usm_atomic_host_allocations`` or 13 | ``sycl::aspect::usm_atomic_shared_allocations``, the 14 | device code and the host code can concurrently access 15 | the same memory. This has a ramification on the atomic 16 | operations because it is possible for device code and 17 | host code to perform atomic operations on the same 18 | object `M` in this shared memory. It also has a ramification 19 | on the fence operations because the C++ core language defines 20 | the semantics of these fence operations in relation to atomic 21 | operations on some shared object `M`. The following paragraphs 22 | specify the guarantees that the SYCL implementation provides 23 | when the application performs atomic or fence operations in 24 | device code using the memory scope ``sycl::memory_scope::system``. 25 | 26 | * Atomic operations in device code using ``sycl::atomic_ref`` on 27 | an object `M` are guaranteed to be atomic with respect to atomic 28 | operations in host code using ``std::atomic_ref`` on that same 29 | object `M`. 30 | * Fence operations in device code using ``sycl::atomic_fence`` 31 | synchronize with fence operations in host code using 32 | ``std::atomic_thread_fence`` if the fence operations shared the 33 | same atomic object `M` and follow the rules for fence synchronization 34 | defined in the C++ core language. 35 | * Fence operations in device code using ``sycl::atomic_fence`` 36 | synchronize with atomic operations in host code using 37 | ``std::atomic_ref`` if the operations share the same atomic 38 | object `M` and follow the rules for fence synchronization 39 | defined in the C++ core language. 40 | * Atomic operations in device code using ``sycl::atomic_ref`` 41 | synchronize with fence operations in host code using 42 | ``std::atomic_thread_fence`` if the operations share the same 43 | atomic object `M` and follow the rules for fence synchronization 44 | defined in the C++ core language. 45 | 46 | .. seealso:: |SYCL_SPEC_INT_W_HOST_CODE| 47 | -------------------------------------------------------------------------------- /source/iface/item-classes.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-item-classes: 6 | 7 | ************ 8 | Item Classes 9 | ************ 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | item 15 | h_item 16 | nd_item 17 | -------------------------------------------------------------------------------- /source/iface/item.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _item: 6 | 7 | ************** 8 | ``sycl::item`` 9 | ************** 10 | 11 | :: 12 | 13 | template 14 | class item; 15 | 16 | .. rubric:: Template parameters 17 | 18 | =============== === 19 | ``Dimensions`` Number of dimensions in the index space. 20 | ``WithOffset`` ``true`` if item has offset, otherwise ``false``. 21 | =============== === 22 | 23 | ``sycl::item`` identifies an instance of the function object 24 | executing at each point in a :ref:`range`. It is passed to a 25 | ``parallel_for`` call or returned by member functions of :ref:`h_item`. 26 | 27 | It encapsulates enough information to identify the work-item's 28 | range of possible values and its :ref:`id` in that range. 29 | 30 | .. note:: 31 | 32 | It can optionally carry the offset of the range if provided to the ``parallel_for``. 33 | 34 | This is deprecated in SYCL 2020. 35 | 36 | Instances of the ``sycl::item`` class are not user-constructible 37 | and are passed by the runtime to each instance of the function object. 38 | So the interface of the ``sycl::item`` does not expose a constructor. 39 | 40 | The ``sycl::item`` class template provides the :ref:`common-byval`. 41 | 42 | .. seealso:: |SYCL_SPEC_ITEM| 43 | 44 | ================ 45 | Member functions 46 | ================ 47 | 48 | ``get_id`` 49 | ========== 50 | 51 | .. rubric:: Overload 1 52 | 53 | :: 54 | 55 | sycl::id get_id() const; 56 | 57 | Return the constituent :ref:`id` representing the 58 | work-item's position in the iteration space. 59 | 60 | .. rubric:: Overload 2 61 | 62 | :: 63 | 64 | size_t get_id(int dimension) const; 65 | 66 | Return the same value as ``get_id()[dimension]``. 67 | 68 | 69 | ``get_range`` 70 | ============= 71 | 72 | .. rubric:: Overload 1 73 | 74 | :: 75 | 76 | sycl::range get_range() const; 77 | 78 | Returns a :ref:`range` representing the dimensions of 79 | the range of possible values of the ``sycl::item``. 80 | 81 | .. rubric:: Overload 2 82 | 83 | :: 84 | 85 | size_t get_range(int dimension) const; 86 | 87 | Return the same value as ``get_range().get(dimension)``. 88 | 89 | 90 | ``get_offset`` 91 | ============== 92 | 93 | :: 94 | 95 | sycl::id get_offset() const; 96 | 97 | .. note:: 98 | 99 | Deprecated in SYCL 2020. 100 | 101 | Returns an :ref:`id` representing the n-dimensional offset 102 | provided to the ``parallel_for`` and that is added by the 103 | runtime to the global-ID of each work-item, if this item 104 | represents a global range. 105 | 106 | For an item converted from an item with no offset this 107 | will always return an :ref:`id` of all 0 values. 108 | 109 | This member function is only available if 110 | ``WithOffset`` is ``true``. 111 | 112 | 113 | ``get_linear_id`` 114 | ================= 115 | 116 | :: 117 | 118 | size_t get_linear_id() const; 119 | 120 | Return the id as a linear index value. 121 | 122 | Calculating a linear address from the 123 | multi-dimensional index follows |SYCL_SPEC_LINEARIZATION|. 124 | 125 | 126 | ``operator[]`` 127 | ============== 128 | 129 | :: 130 | 131 | size_t operator[](int dimension) const; 132 | 133 | Return the same value as ``get_id(dimension)``. 134 | 135 | ========================= 136 | Type conversion functions 137 | ========================= 138 | 139 | ``operator size_t`` 140 | =================== 141 | 142 | :: 143 | 144 | operator size_t() const; 145 | 146 | Available only when: ``Dimensions == 1``. 147 | 148 | Returns the same value as ``get_id(0)``. 149 | 150 | 151 | ``operator item`` 152 | ================= 153 | 154 | :: 155 | 156 | operator item() const; 157 | 158 | Available only when: ``WithOffset == false``. 159 | 160 | Returns a ``sycl::item`` representing the same information as 161 | the object holds but also includes the offset set to 0. 162 | 163 | This conversion allow users to seamlessly write code that 164 | assumes an offset and still provides an offset-less ``sycl::item``. 165 | -------------------------------------------------------------------------------- /source/iface/nd_range.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _nd_range: 6 | 7 | ****************** 8 | ``sycl::nd_range`` 9 | ****************** 10 | 11 | :: 12 | 13 | template 14 | class nd_range; 15 | 16 | .. rubric:: Template parameters 17 | 18 | ================ === 19 | ``Dimensions`` Number of dimensions in the ``sycl::nd_range``. 20 | ================ === 21 | 22 | The ``sycl::nd_range`` class defines the iteration domain of both 23 | the work-groups and the overall dispatch. 24 | 25 | A ``sycl::nd_range`` comprises two 26 | :ref:`range` parameters: the whole range over which 27 | the kernel is to be executed, and the range of each work group. 28 | 29 | The ``sycl::nd_range`` class template provides the :ref:`common-byval`. 30 | 31 | .. seealso:: |SYCL_SPEC_ND_RANGE| 32 | 33 | ============== 34 | (constructors) 35 | ============== 36 | 37 | :: 38 | 39 | nd_range( 40 | sycl::range globalSize, 41 | sycl::range localSize, 42 | sycl::id offset = sycl::id()); 43 | 44 | Construct an ``sycl::nd_range`` from the local 45 | and global constituent :ref:`range`. 46 | 47 | Supplying the option offset is deprecated in SYCL 2020. 48 | If the offset is not provided it will default to no offset. 49 | 50 | .. rubric:: Parameters 51 | 52 | ================== === 53 | ``globalSize`` Dimensions of the entire index space. 54 | ``localSize`` Dimensions of the work group. 55 | ``offset`` Origin of the index space. [deprecated in SYCL 2020] 56 | ================== === 57 | 58 | 59 | ================ 60 | Member functions 61 | ================ 62 | 63 | ``get_global_range`` 64 | ==================== 65 | 66 | :: 67 | 68 | sycl::range get_global_range() const; 69 | 70 | Return the constituent global :ref:`range`. 71 | 72 | ``get_local_range`` 73 | =================== 74 | 75 | :: 76 | 77 | sycl::range get_local_range() const; 78 | 79 | Return the constituent local :ref:`range`. 80 | 81 | ``get_group_range`` 82 | =================== 83 | 84 | :: 85 | 86 | sycl::range get_group_range() const; 87 | 88 | Returns a :ref:`range` representing the number of 89 | groups in each dimension. 90 | 91 | This range would result from ``globalSize``/``localSize`` 92 | as provided on construction. 93 | 94 | 95 | ``get_offset`` 96 | ============== 97 | 98 | :: 99 | 100 | sycl::id get_offset() const; 101 | 102 | Deprecated in SYCL 2020. 103 | 104 | Returns a :ref:`id` defining the offset. 105 | -------------------------------------------------------------------------------- /source/iface/private_memory.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _private_memory: 6 | 7 | ************************ 8 | ``sycl::private_memory`` 9 | ************************ 10 | 11 | :: 12 | 13 | template 14 | class private_memory; 15 | 16 | 17 | .. warning:: 18 | 19 | Based on developer and implementation feedback, the hierarchical 20 | data parallel kernel feature is undergoing improvements to better 21 | align with the frameworks and patterns prevalent in modern programming. 22 | 23 | As this is a key part of the SYCL API and we expect to make changes to 24 | it, we temporarily recommend that new codes refrain from using this 25 | feature until the new API is finished in a near-future version of the 26 | SYCL specification, when full use of the updated feature will be 27 | recommended for use in new code. 28 | 29 | Existing codes using this feature will of course be supported by 30 | conformant implementations of this specification. 31 | 32 | The ``sycl::private_memory`` class simply constructs private data 33 | for a given group across the entire group. The ``id`` of the 34 | current work-item is passed to any access to grab the correct data. 35 | 36 | It is used to wrap the data, which guarantees use of private 37 | per-work-item memory in the 38 | :ref:`hierarchical parallel_for invoke `. 39 | 40 | Private memory is allocated per underlying work-item, not per 41 | iteration of the ``parallel_for_work_item`` loop. 42 | 43 | The number of instances of a private memory object is 44 | only under direct control if a work-group size is passed 45 | to the ``parallel_for_work_group`` call. 46 | If the underlying work-group size is chosen by the runtime, 47 | the number of private memory instances is opaque to the program. 48 | 49 | Explicit private memory declarations should therefore be used 50 | with care and with a full understanding of which instances of 51 | a ``parallel_for_work_item`` loop will share the same 52 | underlying variable. 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | .. seealso:: 62 | 63 | :ref:`parallel_for_hierarchical` 64 | 65 | |SYCL_SYNC_PARALLEL_FOR_HIERARCHICAL| 66 | 67 | 68 | ============== 69 | (constructors) 70 | ============== 71 | 72 | :: 73 | 74 | private_memory(const sycl::group&); 75 | 76 | Place an object of type ``T`` in the underlying private 77 | memory of each work-items. The type ``T`` must be default 78 | constructible. 79 | 80 | The underlying constructor will be called for each work-item. 81 | 82 | ================ 83 | Member functions 84 | ================ 85 | 86 | :: 87 | 88 | T& operator()(const sycl::h_item& id) 89 | 90 | Retrieve a reference to the object for the work-items. 91 | 92 | ========= 93 | Example 1 94 | ========= 95 | 96 | Example of usage of the ``sycl::private_memory``: 97 | 98 | .. literalinclude:: /examples/private_memory_example.cpp 99 | :lines: 5- 100 | :linenos: 101 | 102 | Output example: 103 | 104 | .. literalinclude:: /examples/private_memory_example.out 105 | :lines: 5- 106 | -------------------------------------------------------------------------------- /source/iface/ranges.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-ranges: 6 | 7 | ************* 8 | Range Classes 9 | ************* 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | range 15 | nd_range 16 | -------------------------------------------------------------------------------- /source/iface/scalar-types.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _scalar-types: 6 | 7 | ************ 8 | Scalar types 9 | ************ 10 | 11 | The fundamental C++ data types which are supported in ``SYCL`` are 12 | described in |SYCL_SPEC_FUND_DATA_TYPE|. Note these types are 13 | fundamental and therefore do not exist within the ``sycl`` namespace. 14 | 15 | Additional scalar data types which are supported by SYCL 16 | within the ``sycl`` namespace are described below : 17 | 18 | ================= 19 | Scalar data types 20 | ================= 21 | 22 | ``sycl::byte`` 23 | ============== 24 | 25 | An unsigned 8-bit integer. This is deprecated in SYCL 2020 26 | since C++17 ``std::byte`` can be used instead. 27 | 28 | ``sycl::half`` 29 | ============== 30 | 31 | A 16-bit floating-point type. The half data type must conform to the 32 | IEEE 754-2008 half precision storage format. This type is only supported 33 | on devices that have ``aspect::fp16``. ``std::numeric_limits`` 34 | must be specialized for the half data type. 35 | -------------------------------------------------------------------------------- /source/iface/stream_manipulator.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-stream_manipulators: 6 | 7 | ******************* 8 | Stream manipulators 9 | ******************* 10 | 11 | .. seealso:: 12 | 13 | |SYCL_SPEC_STREAM_CLASS| 14 | 15 | :ref:`stream` 16 | 17 | .. _stream_manipulator: 18 | 19 | ============================ 20 | ``sycl::stream_manipulator`` 21 | ============================ 22 | 23 | :: 24 | 25 | namespace sycl { 26 | 27 | enum class stream_manipulator : /* unspecified */ { 28 | flush, 29 | dec, 30 | hex, 31 | oct, 32 | noshowbase, 33 | showbase, 34 | noshowpos, 35 | showpos, 36 | endl, 37 | fixed, 38 | scientific, 39 | hexfloat, 40 | defaultfloat 41 | }; 42 | 43 | } // namespace sycl 44 | 45 | ========================== 46 | Stream manipulator aliases 47 | ========================== 48 | 49 | :: 50 | 51 | namespace sycl { 52 | 53 | const sycl::stream_manipulator flush = sycl::stream_manipulator::flush; 54 | const sycl::stream_manipulator dec = sycl::stream_manipulator::dec; 55 | const sycl::stream_manipulator hex = sycl::stream_manipulator::hex; 56 | const sycl::stream_manipulator oct = sycl::stream_manipulator::oct; 57 | const sycl::stream_manipulator noshowbase = sycl::stream_manipulator::noshowbase; 58 | const sycl::stream_manipulator showbase = sycl::stream_manipulator::showbase; 59 | const sycl::stream_manipulator noshowpos = sycl::stream_manipulator::noshowpos; 60 | const sycl::stream_manipulator showpos = sycl::stream_manipulator::showpos; 61 | const sycl::stream_manipulator endl = sycl::stream_manipulator::endl; 62 | const sycl::stream_manipulator fixed = sycl::stream_manipulator::fixed; 63 | const sycl::stream_manipulator scientific = sycl::stream_manipulator::scientific; 64 | const sycl::stream_manipulator hexfloat = sycl::stream_manipulator::hexfloat; 65 | const sycl::stream_manipulator defaultfloat = sycl::stream_manipulator::defaultfloat; 66 | __precision_manipulator__ setprecision(int precision); 67 | __width_manipulator__ setw(int width); 68 | 69 | } // namespace sycl 70 | 71 | .. list-table:: 72 | :header-rows: 1 73 | 74 | * - Stream manipulator 75 | - Description 76 | * - ``sycl::flush`` 77 | - Triggers a flush operation, which synchronizes the 78 | work-item stream buffer with the global stream buffer, 79 | and then empties the work-item stream buffer. After a 80 | flush, the full ``workItemBufferSize`` is available 81 | again for subsequent streaming within the work-item. 82 | * - ``sycl::endl`` 83 | - Outputs a new-line character and then triggers a flush operation. 84 | * - ``sycl::dec`` 85 | - Outputs any subsequent values in the current statement 86 | in decimal base. 87 | * - ``sycl::hex`` 88 | - Outputs any subsequent values in the current statement 89 | in hexadecimal base. 90 | * - ``sycl::oct`` 91 | - Outputs any subsequent values in the current statement 92 | in octal base. 93 | * - ``sycl::noshowbase`` 94 | - Outputs any subsequent values without the base prefix. 95 | * - ``sycl::showbase`` 96 | - Outputs any subsequent values with the base prefix. 97 | * - ``sycl::noshowpos`` 98 | - Outputs any subsequent values without a plus sign if 99 | the value is positive. 100 | * - ``sycl::showpos`` 101 | - Outputs any subsequent values with a plus sign if 102 | the value is positive. 103 | * - ``sycl::setw(int)`` 104 | - Sets the field width of any subsequent values 105 | in the current statement. 106 | * - ``sycl::setprecision(int)`` 107 | - Sets the precision of any subsequent values in 108 | the current statement. 109 | * - ``sycl::fixed`` 110 | - Outputs any subsequent floating-point values in the 111 | current statement in fixed notation. 112 | * - ``sycl::scientific`` 113 | - Outputs any subsequent floating-point values in the 114 | current statement in scientific notation. 115 | * - ``sycl::hexfloat`` 116 | - Outputs any subsequent floating-point values in the 117 | current statement in hexadecimal notation. 118 | * - ``sycl::defaultfloat`` 119 | - Outputs any subsequent floating-point values in the 120 | current statement in the default notation. 121 | -------------------------------------------------------------------------------- /source/iface/sub_group.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _sub_group: 6 | 7 | ******************* 8 | ``sycl::sub_group`` 9 | ******************* 10 | 11 | :: 12 | 13 | class sub_group; 14 | 15 | The ``sycl::sub_group`` class encapsulates all functionality 16 | required to represent a particular sub-group within a 17 | parallel execution. It is not user-constructible. 18 | 19 | .. warning:: 20 | 21 | Based on developer and implementation feedback, the hierarchical 22 | data parallel kernel feature is undergoing improvements to better 23 | align with the frameworks and patterns prevalent in modern programming. 24 | 25 | As this is a key part of the SYCL API and we expect to make changes to 26 | it, we temporarily recommend that new codes refrain from using this 27 | feature until the new API is finished in a near-future version of the 28 | SYCL specification, when full use of the updated feature will be 29 | recommended for use in new code. 30 | 31 | Existing codes using this feature will of course be supported by 32 | conformant implementations of this specification. 33 | 34 | .. seealso:: |SYCL_SPEC_SUB_GROUP| 35 | 36 | ================ 37 | Member functions 38 | ================ 39 | 40 | ``get_group_id`` 41 | ================ 42 | 43 | :: 44 | 45 | id get_group_id() const 46 | 47 | Return an id representing the index of the sub-group within the work-group. 48 | Since the work-items that compose a sub-group are chosen in an 49 | implementation defined way, the returned sub-group id cannot be used to 50 | identify a particular work-item in the global ``nd-range``. Rather, the 51 | returned sub-group id is merely an abstract identifier of 52 | the sub-group containing this work-item. 53 | 54 | ``get_local_id`` 55 | ================ 56 | 57 | :: 58 | 59 | id<1> get_local_id() const 60 | 61 | Return a SYCL ``id`` representing the calling work-item’s 62 | position within the sub-group. 63 | 64 | ``get_local_range`` 65 | =================== 66 | 67 | :: 68 | 69 | sycl::range<1> get_local_range() const 70 | 71 | Return a ``sycl::range`` representing the size of the sub-group. 72 | This size may be less than the value returned by 73 | ``get_max_local_range()``, depending on the position of the 74 | sub-group within its parent work-group and the manner in which 75 | sub-groups are constructed by the implementation. 76 | 77 | ``get_group_range`` 78 | =================== 79 | 80 | :: 81 | 82 | sycl::range<1> get_group_range() const 83 | 84 | Return a ``sycl::range`` representing the number of 85 | sub-groups in the work-group. 86 | 87 | ``get_max_local_range`` 88 | ======================= 89 | 90 | :: 91 | 92 | sycl::range<1> get_max_local_range() const 93 | 94 | Return a ``sycl::range`` representing the maximum number of 95 | work-items permitted in a sub-group for the executing kernel. 96 | This value may have been chosen by the programmer via an attribute, 97 | or chosen by the device compiler. 98 | 99 | ``get_group_linear_id`` 100 | ======================= 101 | 102 | :: 103 | 104 | uint32_t get_group_linear_id() const 105 | 106 | Return the same value as ``get_group_id()[0]``. 107 | 108 | ``get_group_linear_range`` 109 | ========================== 110 | 111 | :: 112 | 113 | uint32_t get_group_linear_range() const 114 | 115 | Return the same value as ``get_group_range()[0]``. 116 | 117 | ``get_local_linear_id`` 118 | ======================= 119 | 120 | :: 121 | 122 | uint32_t get_local_linear_id() const 123 | 124 | Return the same value as ``get_local_id()[0]``. 125 | 126 | ``get_local_linear_range`` 127 | ========================== 128 | 129 | :: 130 | 131 | uint32_t get_local_linear_range() const 132 | 133 | Return the same value as ``get_local_range()[0]``. 134 | 135 | ``leader`` 136 | ========== 137 | 138 | :: 139 | 140 | bool leader() const 141 | 142 | Return true for exactly one work-item in the sub-group, if the calling 143 | work-item is the leader of the sub-group, and false for all other 144 | work-items in the sub-group. 145 | 146 | The leader of the sub-group is determined during construction of the 147 | sub-group, and is invariant for the lifetime of the sub-group. 148 | The leader of the sub-group is guaranteed to be the 149 | work-item with a local id of 0. 150 | -------------------------------------------------------------------------------- /source/iface/synchronization-primitives.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _syncronization-primitives: 6 | 7 | ************************** 8 | Synchronization primitives 9 | ************************** 10 | 11 | When the user wants to use a :ref:`buffer` simultaneously 12 | in the SYCL runtime and their own code (e.g. a multi-threaded 13 | mechanism) and wants to use manual synchronization without 14 | using a :ref:`host_accessor`, a ``std::mutex`` can be passed 15 | to the :ref:`buffer` constructor through a property. 16 | 17 | The runtime promises to lock the mutex whenever the data is 18 | in use and unlock it when it no longer needs it: 19 | 20 | :: 21 | 22 | { 23 | std::mutex m; 24 | auto shD = std::make_shared(42) 25 | sycl::buffer b { shD, { sycl::property::buffer::use_mutex { m } } }; 26 | { 27 | std::lock_guard lck { m }; 28 | 29 | // User accesses the data 30 | do_something(shD); 31 | 32 | /* m is unlocked when lck goes out of scope, by normal end of this 33 | block but also if an exception is thrown for example */ 34 | } 35 | } 36 | 37 | When the runtime releases the ``std::mutex`` the user is guaranteed that the 38 | data was copied back to the ``std::shared_pointer``, unless the final data 39 | destination has been changed using the member function ``set_final_data()``. 40 | 41 | .. seealso:: |SYCL_SYNC_PRIMITIVES| 42 | -------------------------------------------------------------------------------- /source/iface/usm_pointer_queries.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _usm-pointer_queries: 6 | 7 | ******************* 8 | USM Pointer Queries 9 | ******************* 10 | 11 | Since USM pointers look like raw C++ pointers, users 12 | cannot deduce what kind of USM allocation a given 13 | pointer may be from by examining its type. 14 | 15 | Two functions are defined that let users query the 16 | type of a USM allocation and, if applicable, the 17 | :ref:`device` on which it was allocated. 18 | 19 | .. note:: 20 | 21 | These query functions are only supported on the host. 22 | 23 | .. seealso:: |SYCL_USM_POINTER_QUERIES| 24 | 25 | ======================= 26 | Pointer query functions 27 | ======================= 28 | 29 | ``sycl::get_pointer_type`` 30 | ========================== 31 | 32 | :: 33 | 34 | sycl::usm::alloc get_pointer_type(const void* ptr, const sycl::context& syclContext); 35 | 36 | Returns the USM allocation type for ``ptr`` if ``ptr`` falls 37 | inside a valid USM allocation for the context ``syclContext``. 38 | 39 | Returns ``sycl::usm::alloc::unknown`` if ``ptr`` does 40 | not point within a valid USM allocation from ``syclContext``. 41 | 42 | 43 | ``sycl::get_pointer_device`` 44 | ============================ 45 | 46 | :: 47 | 48 | sycl::device get_pointer_device(const void* ptr, const sycl::context& syclContext); 49 | 50 | Returns the :ref:`device` associated with the USM allocation. 51 | 52 | If ``ptr`` points within a device USM allocation or 53 | a shared USM allocation for the context ``syclContext``, 54 | returns the same device that was passed when allocating the memory. 55 | 56 | If ``ptr`` points within a host USM allocation for the 57 | context ``syclContext``, returns the first device in ``syclContext``. 58 | 59 | .. rubric:: Exceptions 60 | 61 | ``sycl::errc::invalid`` 62 | If ``ptr`` does not point within a valid 63 | USM allocation from ``syclContext``. 64 | -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ============== 6 | SYCL Reference 7 | ============== 8 | 9 | Welcome to the SYCL Reference! This document is intended to be a handy 10 | reference for: 11 | 12 | * looking SYCL classes member functions, their arguments 13 | * sharing links to SYCL functions/types with other developers 14 | * finding usage examples 15 | 16 | The reference supplements the |SYCL_SPEC| and has the same overall 17 | structure. 18 | 19 | The document is a work-in-progress, and we are publishing now with 20 | the hope that the community will make it better. We want to have a 21 | document that is up-to-date and accurate, with many usage examples. If 22 | you see something wrong, something that could be better, or want to 23 | contribute examples or descriptions, feel free to use the buttons at 24 | the top right to file an issue on GitHub or suggest an edit. 25 | 26 | 27 | .. toctree:: 28 | :maxdepth: 1 29 | 30 | header-file 31 | namespaces 32 | generic-and-non-generic 33 | class-availability 34 | common 35 | runtime 36 | data 37 | usm 38 | parallelism 39 | host-task 40 | error 41 | data-types 42 | synchronization 43 | backends 44 | io 45 | built-in-functions 46 | -------------------------------------------------------------------------------- /source/io.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ======= 6 | Streams 7 | ======= 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | 12 | iface/stream 13 | iface/stream_manipulator 14 | -------------------------------------------------------------------------------- /source/namespaces.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | ========== 6 | Namespaces 7 | ========== 8 | 9 | All SYCL classes, constants, types and functions are available in the 10 | ``sycl::`` namespace, unless the ``CL/sycl.hpp`` header is used in which case 11 | they are all available in the ``cl::sycl::`` namespace. 12 | 13 | All SYCL backend-specific functionality is made available in the 14 | namespace ``sycl::`` where ```` is the 15 | name of the SYCL backend as defined in the SYCL backend specification. 16 | 17 | .. seealso:: |SYCL_SPEC_HEADER_FILES| 18 | -------------------------------------------------------------------------------- /source/parallelism.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _expressing-parallelism: 6 | 7 | ====================== 8 | Expressing parallelism 9 | ====================== 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | iface/defining-kernels 15 | iface/ranges 16 | iface/id 17 | iface/item-classes 18 | iface/group 19 | iface/sub_group 20 | iface/command-group-handler 21 | iface/specialization-constants 22 | iface/kernel-bundles 23 | iface/kernel 24 | iface/device_image 25 | iface/reduction-variables 26 | -------------------------------------------------------------------------------- /source/runtime.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _runtime-classes: 6 | 7 | ================= 8 | Runtime Classes 9 | ================= 10 | 11 | .. toctree:: 12 | :maxdepth: 1 13 | 14 | iface/device-selector 15 | iface/platform 16 | iface/context 17 | iface/device 18 | iface/queue 19 | iface/event 20 | -------------------------------------------------------------------------------- /source/spelling_wordlist.txt: -------------------------------------------------------------------------------- 1 | # SPDX-FileCopyrightText: 2024 The Khronos Group Inc. 2 | # 3 | # SPDX-License-Identifier: Apache-2.0 4 | 5 | accessor 6 | accessors 7 | adaptor 8 | allocator 9 | Allocators 10 | allocators 11 | amongst 12 | atomics 13 | backend 14 | backends 15 | bitshift 16 | Bitwise 17 | bitwise 18 | conformant 19 | constantness 20 | constructible 21 | copyable 22 | deallocated 23 | Deallocates 24 | deallocation 25 | dereference 26 | dereferences 27 | dereferencing 28 | descendent 29 | destructor 30 | dimensionality 31 | DirectX 32 | endian 33 | enqueue 34 | enqueued 35 | enqueueing 36 | Enqueues 37 | enqueuing 38 | extensibility 39 | genericness 40 | incompletion 41 | instantiations 42 | interoperate 43 | interoperating 44 | interoperation 45 | invocable 46 | Khronos 47 | linearized 48 | linearizes 49 | Migratable 50 | moveable 51 | Multipointer 52 | mutex 53 | namespace 54 | Namespaces 55 | NaN 56 | nullary 57 | partitionable 58 | performant 59 | pinnable 60 | pointee 61 | postfix 62 | prefetch 63 | Prefetches 64 | preprocessor 65 | preprocessor 66 | representable 67 | runtime 68 | runtimes 69 | significand 70 | specializable 71 | STL 72 | subdevices 73 | substring 74 | supernormal 75 | templated 76 | templating 77 | th 78 | timebase 79 | Todo 80 | typename 81 | ulps 82 | unary 83 | undecorated 84 | unsampled 85 | USM 86 | variadic 87 | -------------------------------------------------------------------------------- /source/synchronization.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | =========================== 6 | Synchronization and atomics 7 | =========================== 8 | 9 | The available features are: 10 | 11 | * **Accessor classes**: Accessor classes specify acquisition 12 | and release of buffer and image data structures to provide 13 | points at which underlying queue synchronization primitives 14 | must be generated. 15 | * **Atomic operations**: SYCL devices support a restricted 16 | subset of C++ atomics and SYCL uses the library syntax 17 | from the next C++ specification to make this available. 18 | * **Fences**: Fence primitives are made available to order 19 | loads and stores. They are exposed through the 20 | ``sycl::atomic_fence`` function. Fences can have acquire 21 | semantics, release semantics or both. 22 | * **Barriers**: Barrier primitives are made available to 23 | synchronize sets of work-items within individual groups. 24 | They are exposed through the ``sycl::group_barrier`` 25 | function. 26 | * **Hierarchical parallel dispatch**: In the hierarchical 27 | parallelism model of describing computations, 28 | synchronization within the work-group is made explicit through 29 | multiple instances of the ``parallel_for_work_item()`` function 30 | call, rather than through the use of explicit work-group barrier 31 | operations. 32 | * **Device event**: they are used inside SYCL kernel functions to 33 | wait for asynchronous operations within a SYCL kernel function 34 | to complete. 35 | 36 | 37 | 38 | .. toctree:: 39 | :maxdepth: 1 40 | 41 | iface/barriers-and-fences 42 | iface/device_event 43 | iface/atomic_ref 44 | iface/atomic-types 45 | iface/interaction-with-host-code 46 | -------------------------------------------------------------------------------- /source/usm.rst: -------------------------------------------------------------------------------- 1 | .. 2 | Copyright 2024 The Khronos Group Inc. 3 | SPDX-License-Identifier: CC-BY-4.0 4 | 5 | .. _iface-usm: 6 | 7 | =========================== 8 | Unified shared memory (USM) 9 | =========================== 10 | 11 | 12 | .. toctree:: 13 | :maxdepth: 1 14 | 15 | iface/usm_basic_concept 16 | iface/usm_allocations 17 | iface/usm_pointer_queries 18 | --------------------------------------------------------------------------------