Merge remote-tracking branch 'origin/sycl' into private/abatashe/user_docs

* origin/sycl:
  [XPTI][Framework] Reference implementation of the Xpti framework to be used with instrumentation in SYCL (#1557)
  [SYCL] Initial ABI checks implementation (#1528)
  [SYCL] Support connection with multiple plugins (#1490)
  [SYCL] Add a new header file with the reduction class definition (#1558)
  [SYCL] Add test for SYCL kernels with accessor and spec constant (#1536)

Author: Alexander Batashev

clang/test/SemaSYCL/Inputs/sycl.hpp

@@ -194,6 +194,12 @@ class handler {
   }
 };
 
+namespace experimental {
+
+template <typename T, typename ID = T>
+class spec_constant {};
+} // namespace experimental
+
 } // namespace sycl
 } // namespace cl
 

clang/test/SemaSYCL/spec_const_and_accesor_crash.cpp

@@ -0,0 +1,19 @@
+// RUN: %clang_cc1 -fsycl -fsycl-is-device -fsyntax-only -I %S/Inputs -ast-dump %s | FileCheck %s
+// The test checks that Clang doesn't crash if a specialization constant gets
+// into the kernel capture list before an accessor
+
+#include <sycl.hpp>
+
+template <typename name, typename Func>
+__attribute__((sycl_kernel)) void kernel(Func kernelFunc) {
+  kernelFunc();
+}
+
+int main() {
+  cl::sycl::experimental::spec_constant<char, class MyInt32Const> spec_const;
+  cl::sycl::accessor<int, 1, cl::sycl::access::mode::read_write> accessor;
+  // CHECK: FieldDecl {{.*}} implicit referenced 'cl::sycl::experimental::spec_constant<char, class MyInt32Const>'
+  // CHECK: FieldDecl {{.*}} implicit referenced 'cl::sycl::accessor<int, 1, cl::sycl::access::mode::read_write>'
+  kernel<class MyKernel>([spec_const, accessor]() {});
+  return 0;
+}

sycl/doc/ABIPolicyGuide.md

@@ -0,0 +1,91 @@
+# ABI Policy Guide
+
+## Intro
+
+Application Binary Interface is a contract between binary modules, that defines
+how structures and routines are accessed in machine code. Changing the ABI may
+break backwards compatibility of user application with the DPC++ runtime library
+for user-developed applications, resulting in need to rebuild such applications.
+The goal of this document is to provide guidelines for maintaining the current
+ABI of the DPC++ runtime library and mechanisms of notifying users about ABI
+changes.
+
+All ABI changes can be divided into two large groups: breaking and non-breaking.
+A breaking change means that the new binary is incompatible with the previous
+version (i.e. it can not be used as a drop-in replacement). A non-breaking
+change means that the forward compatibility is broken (i.e. the old library
+can be replaced with newer version, but not vice versa).
+
+The following non-exhaustive list contains changes that are considered to be
+breaking:
+
+1. Changing the size of exported symbol (for example, adding new member field
+   to the exported class).
+1. Removing the exported symbol (that includes both changing the signature of
+   exported routine and removing it).
+1. Changing the alignment of exported symbol.
+1. Changing the layout of exported symbol (for example, reordering class field
+   members).
+1. Adding or removing base classes.
+
+Adding a new exported symbol is considered to be non-breaking change.
+
+## ABI Versioning Policy
+
+TBD
+
+## `__SYCL_EXPORT` Macro
+
+The `__SYCL_EXPORT` provides facilities for fine-grained control over exported
+symbols. Mark symbols that are supposed to be accessible by the user and that
+are implemented in the SYCL Runtime library with this macro. Template
+specializations also must be explicitly marked with `__SYCL_EXPORT` macro.
+Symbols not marked `__SYCL_EXPORT` have internal linkage.
+
+A few examples of when it is necessary to mark symbols with the macro:
+
+* The `device` class:
+  - It is defined as API by the SYCL spec.
+  - It is implemented in `device.cpp` file.
+* The `SYCLMemObjT` class:
+  - It is not defined in the SYCL spec, but it is an implementation detail that
+    is accessible by the user (buffer and image inherit from this class).
+  - It has symbols that are implemented in the Runtime library.
+
+When it is not necessary to mark symbols with `__SYCL_EXPORT`:
+* The `buffer` class:
+  - It is defined by the SYCL spec, but it is fully implemented in the headers.
+* The `ProgramManager` class:
+  - It is an implementation detail.
+  - It is not accessed from the header files that are available to users.
+
+## Automated ABI Changes Testing
+
+> The automated tests deal with the most commonly occurring problems, but they
+> may not catch some corner cases. If you believe your PR breaks ABI, but the
+> test does not indicate that, please, notify the reviewers.
+
+There is a set of tests to help identifying ABI changes:
+
+* `test/abi/sycl_symbols_*.dump` contains dump of publicly available symbols.
+  If you add a new symbol, it is considered non-breaking change. When the test
+  reports missing symbols, it means you have either changed or remove some of
+  existing API methods. In both cases you need to adjust the dump file. You
+  can do it either manually, or by invoking the following command:
+  ```shell
+  python3 sycl/tools/abi_check.py --mode dump_symbols --output path/to/output.dump path/to/sycl.so(.dll)
+  ```
+* `test/abi/layout*` and `test/abi/symbol_size*` are a group of tests to check
+  the internal layout of some classes. The layout tests check Clang AST for
+  changes, while symbol_size check `sizeof` for objects. Changing the class
+  layout is a breaking change.
+
+## Breaking ABI
+
+Whenever you need to change the existing ABI, please, follow these steps:
+
+1. Adjust you PR description to reflect (non-)breaking ABI changes. Make sure
+   it is clear, why breaking ABI is necessary.
+2. Fix failing ABI tests in your Pull Request. Use aforementioned techniques to
+   update test files.
+3. Update the library version according to the policies.

sycl/doc/EnvironmentVariables.md

@@ -11,8 +11,8 @@ subject to change. Do not rely on these variables in production code.
 
 | Environment variable | Values | Description |
 | -------------------- | ------ | ----------- |
-| SYCL_PI_TRACE | Any(\*) | Force tracing of PI calls to stderr. |
-| SYCL_BE | PI_OPENCL, PI_CUDA, PI_OTHER | When SYCL RT is built with PI, this controls which plugin is used by the default device selector. Default value is PI_OPENCL. |
+| SYCL_PI_TRACE | Described [below](#sycl_pi_trace-options)  | Enable specified level of tracing for PI. |
+| SYCL_BE | PI_OPENCL, PI_CUDA | Force SYCL RT to consider only devices of the specified backend during the device selection. |
 | SYCL_DEVICE_TYPE | One of: CPU, GPU, ACC, HOST | Force SYCL to use the specified device type. If unset, default selection rules are applied. If set to any unlisted value, this control has no effect. If the requested device type is not found, a `cl::sycl::runtime_error` exception is thrown. If a non-default device selector is used, a device must satisfy both the selector and this control to be chosen. This control only has effect on devices created with a selector. |
 | SYCL_PROGRAM_COMPILE_OPTIONS | String of valid OpenCL compile options | Override compile options for all programs. |
 | SYCL_PROGRAM_LINK_OPTIONS | String of valid OpenCL link options | Override link options for all programs. |
@@ -39,3 +39,12 @@ SYCL_PRINT_EXECUTION_GRAPH can accept one or more comma separated values from th
 | after_addHostAcc | print graph after addHostAccessor method |
 | always | print graph before and after each of the above methods |
 
+### SYCL_PI_TRACE Options
+
+SYCL_PI_TRACE accepts a bit-mask. Supported tracing levels are in the table below
+
+| Option | Description |
+| ------ | ----------- |
+| 1 | Enable basic tracing, which is tracing of PI plugins/devices discovery |
+| 2 | Enable tracing of the PI calls |
+| -1 | Enable all levels of tracing |

sycl/doc/index.rst

@@ -25,4 +25,4 @@ Developing oneAPI DPC++ Compiler
    CompilerAndRuntimeDesign
    EnvironmentVariables
    PluginInterface
-
+   ABIPolicyGuide

sycl/include/CL/sycl.hpp

@@ -26,6 +26,7 @@
 #include <CL/sycl/intel/builtins.hpp>
 #include <CL/sycl/intel/function_pointer.hpp>
 #include <CL/sycl/intel/group_algorithm.hpp>
+#include <CL/sycl/intel/reduction.hpp>
 #include <CL/sycl/intel/sub_group.hpp>
 #include <CL/sycl/item.hpp>
 #include <CL/sycl/kernel.hpp>

sycl/include/CL/sycl/detail/pi.hpp

@@ -13,6 +13,7 @@
 
 #pragma once
 
+#include <CL/sycl/backend_types.hpp>
 #include <CL/sycl/detail/common.hpp>
 #include <CL/sycl/detail/export.hpp>
 #include <CL/sycl/detail/os_util.hpp>
@@ -43,6 +44,17 @@ enum class PiApiKind {
 class plugin;
 namespace pi {
 
+// The SYCL_PI_TRACE sets what we will trace.
+// This is a bit-mask of various things we'd want to trace.
+enum TraceLevel {
+  PI_TRACE_BASIC = 0x1,
+  PI_TRACE_CALLS = 0x2,
+  PI_TRACE_ALL = -1
+};
+
+// Return true if we want to trace PI related activities.
+bool trace(TraceLevel level);
+
 #ifdef SYCL_RT_OS_WINDOWS
 #define OPENCL_PLUGIN_NAME "pi_opencl.dll"
 #define CUDA_PLUGIN_NAME "pi_cuda.dll"
@@ -111,13 +123,6 @@ void *loadOsLibrary(const std::string &Library);
 // library, implementation is OS dependent.
 void *getOsLibraryFuncAddress(void *Library, const std::string &FunctionName);
 
-// For selection of SYCL RT back-end, now manually through the "SYCL_BE"
-// environment variable.
-enum Backend { SYCL_BE_PI_OPENCL, SYCL_BE_PI_CUDA, SYCL_BE_PI_OTHER };
-
-// Check for manually selected BE at run-time.
-bool useBackend(Backend Backend);
-
 // Get a string representing a _pi_platform_info enum
 std::string platformInfoToString(pi_platform_info info);
 

sycl/include/CL/sycl/intel/functional.hpp

@@ -53,6 +53,9 @@ template <> struct maximum<void> {
 #endif
 
 template <typename T = void> using plus = std::plus<T>;
+template <typename T = void> using bit_or = std::bit_or<T>;
+template <typename T = void> using bit_xor = std::bit_xor<T>;
+template <typename T = void> using bit_and = std::bit_and<T>;
 
 } // namespace intel