[SYCL] Deprecate old OpenCL interop APIs in SYCL 2020 mode (#3194)

These warnings can be suppressed by `SYCL2020_DISABLE_DEPRECATION_WARNINGS` macro or by setting `-sycl-std=2017` or `-sycl-std=1.2.1`.

Also a new macro `SYCL_DISABLE_DEPRECATION_WARNINGS` is introduced, to disable all deprecation warnings completely (including SYCL 1.2.1 deprecation warnings).

Author: Alexander Batashev

sycl/doc/PreprocessorMacros.md

@@ -19,6 +19,15 @@ This behavior is not following the SYCL spec since `constant_ptr` conversions to
 the underlying pointer types return pointers without any additional qualifiers
 so it's disabled by default.
 
+### SYCL2020_DISABLE_DEPRECATION_WARNINGS
+
+Disables warnings coming from usage of SYCL 1.2.1 APIs, that are deprecated in
+SYCL 2020.
+
+### SYCL_DISABLE_DEPRECATION_WARNINGS
+
+Disables all deprecation warnings in SYCL runtime headers, including SYCL 1.2.1 deprecations.
+
 ### Version macros
 
 - `__LIBSYCL_MAJOR_VERSION` is set to SYCL runtime library major version.

sycl/include/CL/sycl/buffer.hpp

@@ -224,6 +224,7 @@ class buffer {
   }
 
   template <int N = dimensions, typename = EnableIfOneDimension<N>>
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   buffer(cl_mem MemObject, const context &SyclContext,
          event AvailableEvent = {})
       : Range{0} {

sycl/include/CL/sycl/context.hpp

@@ -148,6 +148,7 @@ class __SYCL_EXPORT context {
   ///
   /// \param ClContext is an instance of OpenCL cl_context.
   /// \param AsyncHandler is an instance of async_handler.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   context(cl_context ClContext, async_handler AsyncHandler = {});
 
   /// Queries this SYCL context for information.
@@ -187,6 +188,7 @@ class __SYCL_EXPORT context {
   /// The OpenCL cl_context handle is retained on return.
   ///
   /// \return a valid instance of OpenCL cl_context.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   cl_context get() const;
 
   /// Checks if this context is a SYCL host context.

sycl/include/CL/sycl/detail/defines_elementary.hpp

@@ -39,13 +39,26 @@
 #endif
 
 #ifndef __SYCL_DEPRECATED
+#ifndef SYCL_DISABLE_DEPRECATION_WARNINGS
 #ifdef _WIN32
 #define __SYCL_DEPRECATED(message) __declspec(deprecated(message))
 #else
 #define __SYCL_DEPRECATED(message) __attribute__((deprecated(message)))
 #endif
+#else // SYCL_DISABLE_DEPRECATION_WARNINGS
+#define __SYCL_DEPRECATED(message)
+#endif // SYCL_DISABLE_DEPRECATION_WARNINGS
 #endif // __SYCL_DEPRECATED
 
+#ifndef __SYCL2020_DEPRECATED
+#if SYCL_LANGUAGE_VERSION >= 202001 &&                                         \
+    !defined(SYCL2020_DISABLE_DEPRECATION_WARNINGS)
+#define __SYCL2020_DEPRECATED(message) __SYCL_DEPRECATED(message)
+#else
+#define __SYCL2020_DEPRECATED(message)
+#endif
+#endif // __SYCL2020_DEPRECATED
+
 #ifndef __SYCL_INLINE_CONSTEXPR
 // inline constexpr is a C++17 feature
 #if __cplusplus >= 201703L

sycl/include/CL/sycl/device.hpp

@@ -40,6 +40,7 @@ class __SYCL_EXPORT device {
   /// in accordance with the requirements described in 4.3.1.
   ///
   /// \param DeviceId is OpenCL device represented with cl_device_id
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   explicit device(cl_device_id DeviceId);
 
   /// Constructs a SYCL device instance using the device selected
@@ -64,6 +65,7 @@ class __SYCL_EXPORT device {
   ///
   /// \return a valid cl_device_id instance in accordance with the requirements
   /// described in 4.3.1.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   cl_device_id get() const;
 
   /// Check if device is a host device

sycl/include/CL/sycl/event.hpp

@@ -41,6 +41,7 @@ class __SYCL_EXPORT event {
   ///
   /// \param ClEvent is a valid instance of OpenCL cl_event.
   /// \param SyclContext is an instance of SYCL context.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   event(cl_event ClEvent, const context &SyclContext);
 
   event(const event &rhs) = default;
@@ -58,6 +59,7 @@ class __SYCL_EXPORT event {
   /// Returns a valid OpenCL event interoperability handle.
   ///
   /// \return a valid instance of OpenCL cl_event.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   cl_event get() const;
 
   /// Checks if this event is a SYCL host event.

sycl/include/CL/sycl/image.hpp

@@ -220,6 +220,7 @@ class image {
         PropList);
   }
 
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   image(cl_mem ClMemObject, const context &SyclContext,
         event AvailableEvent = {}) {
     impl = std::make_shared<detail::image_impl<Dimensions>>(

sycl/include/CL/sycl/platform.hpp

@@ -39,6 +39,7 @@ class __SYCL_EXPORT platform {
   /// construction.
   ///
   /// \param PlatformId is an OpenCL cl_platform_id instance.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   explicit platform(cl_platform_id PlatformId);
 
   /// Constructs a SYCL platform instance using device selector.
@@ -65,6 +66,7 @@ class __SYCL_EXPORT platform {
   /// Returns an OpenCL interoperability platform.
   ///
   /// \return an instance of OpenCL cl_platform_id.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   cl_platform_id get() const;
 
   /// Checks if platform supports specified extension.

sycl/include/CL/sycl/queue.hpp

@@ -142,6 +142,7 @@ class __SYCL_EXPORT queue {
   /// \param ClQueue is a valid instance of OpenCL queue.
   /// \param SyclContext is a valid SYCL context.
   /// \param AsyncHandler is a SYCL asynchronous exception handler.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   queue(cl_command_queue ClQueue, const context &SyclContext,
         const async_handler &AsyncHandler = {});
 
@@ -159,6 +160,7 @@ class __SYCL_EXPORT queue {
 
   /// \return a valid instance of OpenCL queue, which is retained before being
   /// returned.
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   cl_command_queue get() const;
 
   /// \return an associated SYCL context.

sycl/include/CL/sycl/sampler.hpp

@@ -68,6 +68,7 @@ class __SYCL_EXPORT sampler {
           addressing_mode addressingMode, filtering_mode filteringMode,
           const property_list &propList = {});
 
+  __SYCL2020_DEPRECATED("OpenCL interop APIs are deprecated")
   sampler(cl_sampler clSampler, const context &syclContext);
 
   sampler(const sampler &rhs) = default;

sycl/source/CMakeLists.txt

@@ -61,6 +61,8 @@ function(add_sycl_rt_library LIB_NAME)
     endif()
   endif()
 
+  target_compile_definitions(${LIB_OBJ_NAME} PRIVATE SYCL2020_DISABLE_DEPRECATION_WARNINGS)
+
   target_include_directories(
     ${LIB_OBJ_NAME}
     PRIVATE

sycl/test/warnings/sycl_2020_deprecations.cpp

@@ -0,0 +1,54 @@
+// RUN: %clangxx -fsycl -sycl-std=2020 -Xclang -verify -Xclang -verify-ignore-unexpected=note %s -o %t.out
+// RUN: %clangxx -fsycl -Xclang -verify -Xclang -verify-ignore-unexpected=note %s -o %t.out
+// RUN: %clangxx -fsycl -sycl-std=2017 -Werror %s -o %t.out
+// RUN: %clangxx -fsycl -sycl-std=1.2.1 -Werror %s -o %t.out
+
+#include <CL/sycl.hpp>
+
+int main() {
+  cl_context ClCtx;
+  // expected-warning@+1 {{'context' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::context Ctx{ClCtx};
+  // expected-warning@+1 {{'get' is deprecated: OpenCL interop APIs are deprecated}}
+  (void)Ctx.get();
+
+  cl_mem Mem;
+  // expected-warning@+1 {{'buffer' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::buffer<int, 1> Buf{Mem, Ctx};
+  (void)Buf;
+
+  cl_device_id DevId;
+  // expected-warning@+1 {{'device' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::device Device{DevId};
+  // expected-warning@+1 {{'get' is deprecated: OpenCL interop APIs are deprecated}}
+  (void)Device.get();
+
+  cl_event ClEvent;
+  // expected-warning@+1 {{'event' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::event Evt{ClEvent, Ctx};
+  // expected-warning@+1 {{'get' is deprecated: OpenCL interop APIs are deprecated}}
+  (void)Evt.get();
+
+  // expected-warning@+1 {{'image' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::image<1> Img{Mem, Ctx};
+  (void)Img;
+
+  cl_platform_id ClPlatform;
+  // expected-warning@+1 {{'platform' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::platform Platform{ClPlatform};
+  // expected-warning@+1 {{'get' is deprecated: OpenCL interop APIs are deprecated}}
+  (void)Platform.get();
+
+  cl_command_queue ClQueue;
+  // expected-warning@+1 {{'queue' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::queue Queue{ClQueue, Ctx};
+  // expected-warning@+1 {{'get' is deprecated: OpenCL interop APIs are deprecated}}
+  (void)Queue.get();
+
+  cl_sampler ClSampler;
+  // expected-warning@+1 {{'sampler' is deprecated: OpenCL interop APIs are deprecated}}
+  sycl::sampler Sampler{ClSampler, Ctx};
+  (void)Sampler;
+
+  return 0;
+}

sycl/unittests/kernel-and-program/Cache.cpp

@@ -6,6 +6,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+#define SYCL2020_DISABLE_DEPRECATION_WARNINGS
+
 #include "CL/sycl/detail/pi.h"
 #include "detail/context_impl.hpp"
 #include "detail/kernel_program_cache.hpp"