From 919478982bc5eec0c3fa861dc2f1fbeb4ff2cd6f Mon Sep 17 00:00:00 2001 From: Tom Deakin Date: Thu, 28 Mar 2024 22:22:42 +0000 Subject: [PATCH 1/5] Add anatomy example to index page People new to SYCL might want to see a simple SYCL program so that they can then investigate the APIs further in the rest of this reference page, so I've included the anatomy example from the SYCL 2020 spec on the main page --- source/anatomy.cpp | 39 +++++++++++++++++++++++++++++++++++++++ source/conf.py | 3 +++ source/index.rst | 8 ++++++++ 3 files changed, 50 insertions(+) create mode 100644 source/anatomy.cpp diff --git a/source/anatomy.cpp b/source/anatomy.cpp new file mode 100644 index 00000000..29c8c586 --- /dev/null +++ b/source/anatomy.cpp @@ -0,0 +1,39 @@ +// Copyright (c) 2011-2024 The Khronos Group, Inc. +// SPDX-License-Identifier: Apache-2.0 + +#include +#include +using namespace sycl; // (optional) avoids need for "sycl::" before SYCL names + +int main() { + int data[1024]; // Allocate data to be worked on + + // Create a default queue to enqueue work to the default device + queue myQueue; + + // By wrapping all the SYCL work in a {} block, we ensure + // all SYCL tasks must complete before exiting the block, + // because the destructor of resultBuf will wait + { + // Wrap our data variable in a buffer + buffer resultBuf { data, range<1> { 1024 } }; + + // Create a command group to issue commands to the queue + myQueue.submit([&](handler& cgh) { + // Request write access to the buffer without initialization + accessor writeResult { resultBuf, cgh, write_only, no_init }; + + // Enqueue a parallel_for task with 1024 work-items + cgh.parallel_for(1024, [=](id<1> idx) { + // Initialize each buffer element with its own rank number starting at 0 + writeResult[idx] = idx; + }); // End of the kernel function + }); // End of our commands for this queue + } // End of scope, so we wait for work producing resultBuf to complete + + // Print result + for (int i = 0; i < 1024; i++) + std::cout << "data[" << i << "] = " << data[i] << std::endl; + + return 0; +} diff --git a/source/conf.py b/source/conf.py index 368ab81b..9c9bdd4f 100644 --- a/source/conf.py +++ b/source/conf.py @@ -86,6 +86,9 @@ def make_ref(ref_str, ref_view, ref_sufix): prolog_template = string.Template( make_ref( + "SYCL_SPEC_ANATOMY", "Section 3.2", "#sec:anatomy" + ) + + make_ref( "SYCL_SPEC_HEADER_FILES", "Section 4.3", "#sec:headers-and-namespaces" ) + make_ref( diff --git a/source/index.rst b/source/index.rst index b5f243f7..5e9d424c 100644 --- a/source/index.rst +++ b/source/index.rst @@ -23,6 +23,14 @@ you see something wrong, something that could be better, or want to contribute examples or descriptions, feel free to use the buttons at the top right to file an issue on GitHub or suggest an edit. +A basic SYCL program, taken from the SYCL 2020 specification, looks like this: + +[source,,linenums] +---- +include::anatomy.cpp[lines=4..-1] +---- +.. seealso:: |SYCL_SPEC_ANATOMY| + .. toctree:: :maxdepth: 1 From f20bd53643bcbbed59ad6df00372ce476a4654b8 Mon Sep 17 00:00:00 2001 From: Tom Deakin Date: Fri, 5 Apr 2024 14:53:48 -0500 Subject: [PATCH 2/5] Move anatomy to examples dir and include in CMake for testing --- source/examples/CMakeLists.txt | 2 ++ source/{ => examples}/anatomy.cpp | 0 2 files changed, 2 insertions(+) rename source/{ => examples}/anatomy.cpp (100%) diff --git a/source/examples/CMakeLists.txt b/source/examples/CMakeLists.txt index 7f312d25..877c3c4a 100644 --- a/source/examples/CMakeLists.txt +++ b/source/examples/CMakeLists.txt @@ -29,3 +29,5 @@ set_tests_properties(gpu-platform PROPERTIES LABELS gpu) add_example(queue-parallel) add_example(queue-single-task) add_example(usm-implicit-data-movement) +add_example(anatomy) + diff --git a/source/anatomy.cpp b/source/examples/anatomy.cpp similarity index 100% rename from source/anatomy.cpp rename to source/examples/anatomy.cpp From 96e49650dd25042950694337a4fb9b667c9b84ad Mon Sep 17 00:00:00 2001 From: Tom Deakin Date: Fri, 5 Apr 2024 14:58:23 -0500 Subject: [PATCH 3/5] update anatomy example copyright notice to use SPDX form --- source/examples/anatomy.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/examples/anatomy.cpp b/source/examples/anatomy.cpp index 29c8c586..69c61859 100644 --- a/source/examples/anatomy.cpp +++ b/source/examples/anatomy.cpp @@ -1,5 +1,5 @@ -// Copyright (c) 2011-2024 The Khronos Group, Inc. // SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: 2024 The Khronos Group Inc. #include #include From 28f7f9fde88c78796dc12c7798bd015ebfebd253 Mon Sep 17 00:00:00 2001 From: Tom Deakin Date: Fri, 5 Apr 2024 15:16:31 -0500 Subject: [PATCH 4/5] clang-format as part of pre-commit --- source/conf.py | 4 +--- source/examples/CMakeLists.txt | 1 - source/examples/anatomy.cpp | 6 +++--- 3 files changed, 4 insertions(+), 7 deletions(-) diff --git a/source/conf.py b/source/conf.py index 9c9bdd4f..2c048769 100644 --- a/source/conf.py +++ b/source/conf.py @@ -85,9 +85,7 @@ def make_ref(ref_str, ref_view, ref_sufix): prolog_template = string.Template( - make_ref( - "SYCL_SPEC_ANATOMY", "Section 3.2", "#sec:anatomy" - ) + make_ref("SYCL_SPEC_ANATOMY", "Section 3.2", "#sec:anatomy") + make_ref( "SYCL_SPEC_HEADER_FILES", "Section 4.3", "#sec:headers-and-namespaces" ) diff --git a/source/examples/CMakeLists.txt b/source/examples/CMakeLists.txt index 877c3c4a..ec50eca5 100644 --- a/source/examples/CMakeLists.txt +++ b/source/examples/CMakeLists.txt @@ -30,4 +30,3 @@ add_example(queue-parallel) add_example(queue-single-task) add_example(usm-implicit-data-movement) add_example(anatomy) - diff --git a/source/examples/anatomy.cpp b/source/examples/anatomy.cpp index 69c61859..3b8bc280 100644 --- a/source/examples/anatomy.cpp +++ b/source/examples/anatomy.cpp @@ -16,12 +16,12 @@ int main() { // because the destructor of resultBuf will wait { // Wrap our data variable in a buffer - buffer resultBuf { data, range<1> { 1024 } }; + buffer resultBuf{data, range<1>{1024}}; // Create a command group to issue commands to the queue - myQueue.submit([&](handler& cgh) { + myQueue.submit([&](handler &cgh) { // Request write access to the buffer without initialization - accessor writeResult { resultBuf, cgh, write_only, no_init }; + accessor writeResult{resultBuf, cgh, write_only, no_init}; // Enqueue a parallel_for task with 1024 work-items cgh.parallel_for(1024, [=](id<1> idx) { From b19f90b80e8e8a504264df2772bf4ecf17d4e6f1 Mon Sep 17 00:00:00 2001 From: Tom Deakin Date: Fri, 5 Apr 2024 15:28:14 -0500 Subject: [PATCH 5/5] update index to include anatomy example in rst --- source/index.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/index.rst b/source/index.rst index 5e9d424c..42295458 100644 --- a/source/index.rst +++ b/source/index.rst @@ -25,10 +25,9 @@ the top right to file an issue on GitHub or suggest an edit. A basic SYCL program, taken from the SYCL 2020 specification, looks like this: -[source,,linenums] ----- -include::anatomy.cpp[lines=4..-1] ----- +.. literalinclude:: /examples/anatomy.cpp + :lines: 5- + :linenos: .. seealso:: |SYCL_SPEC_ANATOMY|