Repository files navigation

This repository provides materials that can be used for teaching SYCL. Thematerials are provided using the "Creative Commons Attribution Share Alike 4.0International" license.

If you're not familiar with SYCL or would like some further resources forlearning about SYCL below are a list of useful resources:

• Read a description of SYCL on theKhronos website SYCL page.
• Go to the Khronos website to finda list of SYCL resources.
• Check out theSYCL 2020 reference guide.
• Browse SYCL news, blog posts, videos, projects and more on thesycl.tech community website
• Get a list of theavailable SYCL implementations

To use these materials simply clone this repository including the required submodules.

git clone --recursive https://github.com/codeplaysoftware/syclacademy.git

The lectures are written in reveal.js, and can be found inLesson_Materials,in the sub-directory for each topic. To view them simply open theindex.htmlfile in your browser. Your browser will have a "Full Screen" mode that can beused to run the presentation, use the right and left cursors to move forward andbackward in the presentation.

The exercises can be found inCode_Exercises in the sub-directory for eachtopic. Each exercise has a markdown document instructing what to do in theexercise, a source file to start with and a solution file to provide anexample implementation to compare against.

Contributions to the materials are very gratefully received and this can be doneby submitting a Pull Request with any changes. If you can, follow theinstructionshere to generate a pdf file forany lecture slides you change. Please limit the scope of eachPull Request so that they can be reviewed and merged in a timely manner.

Codeplay Software Ltd., Heidelberg University, Intel, Xilinx and University of Bristol.

Abertay University, Universidad de Concepcion, TU Dresden, University ofEdinburgh, Federal University of Sao Carlos, University of Glasgow, Heriot WattUniversity, Universitat Innsbruck, Universidad de Málaga, University of Salernoand University of the West of Scotland.

The SYCL Academy curriculum is divided up into a number of short lessonsconsisting of slides for presenting the material and a more detailed write-up,each accompanied by a tutorial for getting hands on experience with the subjectmatter.

Each of the lessons are designed to be self contained modules in order tosupport both academic and training style teaching environments.

A playlist of video content isalso available. Though note that theseslides and exercises may have changed since these videos were created so theymay not match completely.

The exercises can be built for DPC++ and AdaptiveCpp.

Below is a list of the supported platforms and devices for each SYCL implementations,please check this before deciding which SYCL implementation to use.Make sure to also install the specified version to ensure that you can buildall of the exercises.

* Supported in open source project only

** Seehere for the official list of GPUs supported by AMD forROCm. We do not recommend using GPUs earlier than gfx9 (Vega 10 and Vega 20chips).

First you'll need to install your chosen SYCL implementation and anydependencies they require.

To set up DPC++ follow thegetting started instructions.

You can also use aDocker* image.

If you are using theIntel DevCloud then the latest version of DPC++ willalready be installed and available in the path.

You will need a AdaptiveCpp (formerly hipSYCL) build from September 2021 or newer. Refer to theAdaptiveCpp installation instructions for details on how to install AdaptiveCpp.

Before building the exercises you'll need:

• One of the platforms in the support matrix above, depending on which SYCLimplementation you are wishing to build for.
• A C++17 or above tool-chain.
• An appropriate build system for the platform you are targeting (CMake, Ninja,Make, Visual Studio).

Clone this repository, there are some additional dependencies configured as gitsub-modules so make sure to clone those as well. Then simply invoke CMake asfollows:

mkdir buildcd buildcmake ../ -G<cmake_generator> -A<cmake_arch> -D<sycl_implementation>=ON

For<cmake_generator> /<cmake_arch> we recommend:

• Visual Studio 16 2019 / x64 (Windows)
• Ninja / NA (Windows or Linux)
• Make / NA (Linux) i.e. "-GUnix Makefiles"

Forsycl_implementation this can be one of:

• SYCL_ACADEMY_USE_ADAPTIVECPP
• SYCL_ACADEMY_USE_DPCPP

You can also specify the additional optional options:

-DSYCL_ACADEMY_INSTALL_ROOT=<path_to_sycl_impl_install_root>

For<path_to_sycl_impl_install_root> we recommend you specify the path to theroot directory of your SYCL implementation installation, though this may notalways be required.

-DSYCL_ACADEMY_ENABLE_SOLUTIONS=ON

This will enable building the solutions for each exercise as well as the sourcefiles. This is disabled by default.

-DCMAKE_BUILD_TYPE=Release

The build configuration for all exercises defaults to a debug build if this option is not specified.

-DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx

This SYCL Academy CMake configuration uses the Intel oneAPI IntelSYCL CMake module package to assist it in its configuration. These command line arguments must be used to initiate this configuration correctly.

When building with AdaptiveCpp, cmake will additionally require you to specify thetarget platform using-DACPP_TARGETS=<target specification>.<target specification> is a list of compilation flows to enable and devices to target, for example-DACPP_TARGETS="omp;generic" compiles for CPUs using OpenMP and GPUs using the generic single-pass compiler.

Available compilation flows are:

• omp - OpenMP CPU backend
• generic - Generic single-pass compiler. Generates a binary that runs on AMD, NVIDIA and Intel GPUs using runtime compilation
• cuda - CUDA backend for NVIDIA GPUs. Requires specification of targets of the form sm_XY, e.g. sm_70 for Volta, sm_60 for Pascal
• hip - HIP backend for AMD GPUs. Requires specification of targets of the form gfxXYZ, e.g. gfx906 for Vega 20, gfx900 for Vega 10

When in doubt, use-DACPP_TARGETS=omp;generic.

Invoking CMake from the command line example usage:

  cmake .. "-GUnix Makefiles" -DSYCL_ACADEMY_USE_DPCPP=ON -DSYCL_ACADEMY_ENABLE_SOLUTIONS=ON -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx

First you have to ensure that your environment is configured to use DPC++ (noteif you are using the Intel DevCloud then you don't need to do this step).

On Linux simply call thesetvars.sh which is available in/opt/intel/oneapifor sudo or root users and ~/intel/oneapi/ when installed as a normal user.

For root or sudo installations:source /opt/intel/oneapi/setvars.sh

For normal user installations:source ~/intel/oneapi/setvars.sh

On Windows the script is located in<dpc++_install_root>\setvars.bat

Where<dpc++_install_root> is wherever theoneAPI directory is installed.

Once that's done you can invoke the DPC++ compiler as follows:

icpx -fsycl -I<syclacademy_root>/External/Catch2/single_include -o a.out source.cpp

Where<syclacademy_root> is the path to the root directory of where you clonedthis repository. Note that on Windows you need to add the option /EHsc to avoid exception handling error.

The CMake configuration can also be used to build the exercises, see the sectionConfiguring using CMake above.

Once you have a working SYCL compiler, you are ready to start writing some SYCL code. To find the first exercise:

cd Code_Exercises/Exercise_01_Compiling_with_SYCL/

And read the README.md for further instructions.

Each exercise directory contains:

• README.md, which contains instructions of how to complete a given exercise, as well as directions for compilation.
• source.cpp, a placeholder file where your code implementation should be written.
• solution.cpp, where a solution has been implemented in advance.

Once you have completed any given exercise make sure to compare your implementation against the correspondingsolution.cpp.

Hosted by tech.io, thisSYCL Introduction tutorial introduces the concepts of SYCL. The website also provides the ability to compile and execute SYCL code from your web browser.

SYCL and the SYCL logo are trademarks of the Khronos Group Inc.