[SYCL][COMPAT] SYCLcompat dim and defs headers (intel#9976)

This is an implementation of SYCLcompat, the stand alone library
proposed in intel#9646.
Please, find the documentation there.

SYCLcompat has two primary goals:

- Improve the adoption of SYCL. This library is designed to provide a
familiar programming interface that resembles other popular
heterogeneous programming models. By reducing the learning curve, it
enables developers to leverage SYCL's power and features more easily.
- Source-to-Source Translation Support. SYCLcompat is also designed to
facilitate automatic source-to-source translation from other
heterogeneous programming models to SYCL and offer a more standardized
and consistent programming interface. This feature can significantly
streamline the migration and integration of existing codebases into the
SYCL ecosystem

The PR also includes tests. We were advised to include the tests as part
of `sycl/unittests`, so we added a different mechanism to build them
using `clang`.

As we stated in the docs PR, we are open to any suggestions, concerns,
or improvements you may have, so please, let us know if you have any.

---------

Co-authored-by: Gordon Brown <[email protected]>
Co-authored-by: Joe Todd <[email protected]>
Co-authored-by: Pietro Ghiglio <[email protected]>
Co-authored-by: Ruyman Reyes <[email protected]>
Co-authored-by: tomflinda <[email protected]>

Author: 6 people

sycl/CMakeLists.txt

@@ -193,37 +193,48 @@ include(AddBoostMp11Headers)
 file(GLOB_RECURSE HEADERS_IN_SYCL_DIR CONFIGURE_DEPENDS "${sycl_inc_dir}/sycl/*")
 file(GLOB_RECURSE HEADERS_IN_CL_DIR CONFIGURE_DEPENDS "${sycl_inc_dir}/CL/*")
 file(GLOB_RECURSE HEADERS_IN_STD_DIR CONFIGURE_DEPENDS "${sycl_inc_dir}/std/*")
+file(GLOB_RECURSE HEADERS_IN_SYCLCOMPAT_DIR CONFIGURE_DEPENDS "${sycl_inc_dir}/syclcompat/*" "${sycl_inc_dir}/syclcompat.hpp")
+
 string(REPLACE "${sycl_inc_dir}" "${SYCL_INCLUDE_BUILD_DIR}"
   OUT_HEADERS_IN_SYCL_DIR "${HEADERS_IN_SYCL_DIR}")
 string(REPLACE "${sycl_inc_dir}/CL" "${SYCL_INCLUDE_BUILD_DIR}/sycl/CL"
   OUT_HEADERS_IN_CL_DIR "${HEADERS_IN_CL_DIR}")
 string(REPLACE "${sycl_inc_dir}" "${SYCL_INCLUDE_BUILD_DIR}"
   OUT_HEADERS_IN_STD_DIR "${HEADERS_IN_STD_DIR}")
+string(REPLACE "${sycl_inc_dir}" "${SYCL_INCLUDE_BUILD_DIR}"
+  OUT_HEADERS_IN_SYCLCOMPAT_DIR "${HEADERS_IN_SYCLCOMPAT_DIR}")
 
 # Copy SYCL headers from sources to build directory
 add_custom_target(sycl-headers
   DEPENDS ${OUT_HEADERS_IN_SYCL_DIR}
           ${OUT_HEADERS_IN_CL_DIR}
           ${OUT_HEADERS_IN_STD_DIR}
+          ${OUT_HEADERS_IN_SYCLCOMPAT_DIR}
           boost_mp11-headers)
 
 add_custom_command(
   OUTPUT  ${OUT_HEADERS_IN_SYCL_DIR}
           ${OUT_HEADERS_IN_CL_DIR}
           ${OUT_HEADERS_IN_STD_DIR}
+          ${OUT_HEADERS_IN_SYCLCOMPAT_DIR}
   DEPENDS ${HEADERS_IN_SYCL_DIR}
           ${HEADERS_IN_CL_DIR}
           ${HEADERS_IN_STD_DIR}
+          ${HEADERS_IN_SYCLCOMPAT_DIR}
   COMMAND ${CMAKE_COMMAND} -E copy_directory ${sycl_inc_dir}/sycl ${SYCL_INCLUDE_BUILD_DIR}/sycl
   COMMAND ${CMAKE_COMMAND} -E copy_directory ${sycl_inc_dir}/CL ${SYCL_INCLUDE_BUILD_DIR}/sycl/CL
   COMMAND ${CMAKE_COMMAND} -E copy_directory ${sycl_inc_dir}/std ${SYCL_INCLUDE_BUILD_DIR}/std
+  COMMAND ${CMAKE_COMMAND} -E copy_directory ${sycl_inc_dir}/syclcompat ${SYCL_INCLUDE_BUILD_DIR}/syclcompat
+  COMMAND ${CMAKE_COMMAND} -E copy ${sycl_inc_dir}/syclcompat.hpp ${SYCL_INCLUDE_BUILD_DIR}/syclcompat.hpp
   COMMENT "Copying SYCL headers ...")
 
 # Copy SYCL headers from source to install directory
 install(DIRECTORY "${sycl_inc_dir}/sycl" DESTINATION ${SYCL_INCLUDE_DIR} COMPONENT sycl-headers)
 install(DIRECTORY "${sycl_inc_dir}/CL" DESTINATION ${SYCL_INCLUDE_DIR}/sycl COMPONENT sycl-headers)
 install(DIRECTORY "${sycl_inc_dir}/std" DESTINATION ${SYCL_INCLUDE_DIR} COMPONENT sycl-headers)
 install(DIRECTORY ${BOOST_MP11_DESTINATION_DIR} DESTINATION ${SYCL_INCLUDE_DIR}/sycl/detail COMPONENT boost_mp11-headers)
+install(DIRECTORY "${sycl_inc_dir}/syclcompat" DESTINATION ${SYCL_INCLUDE_DIR}/syclcompat COMPONENT sycl-headers)
+install(FILES "${sycl_inc_dir}/syclcompat.hpp" DESTINATION ${SYCL_INCLUDE_DIR} COMPONENT sycl-headers)
 
 if (WIN32)
   set(SYCL_RT_LIBS sycl${SYCL_MAJOR_VERSION})

sycl/cmake/modules/AddSYCLExecutable.cmake

@@ -36,7 +36,10 @@ macro(add_sycl_executable ARG_TARGET_NAME)
     COMMAND_EXPAND_LISTS)
   add_dependencies(${ARG_TARGET_NAME}_exec sycl-toolchain)
   foreach(_lib ${ARG_LIBRARIES})
-    add_dependencies(${ARG_TARGET_NAME}_exec _lib)
+    # Avoid errors when linking external targets such as dl
+    if(TARGET ${_lib})
+      add_dependencies(${ARG_TARGET_NAME}_exec ${_lib})
+    endif()
   endforeach()
 
   foreach(_dep ${ARG_DEPENDANTS})

sycl/cmake/modules/AddSYCLLibraryUnitTest.cmake

@@ -0,0 +1,91 @@
+# add_sycl_library_unittest(test_suite_name sycl_extra_flags
+#                           file1.cpp file2.cpp ...)
+#
+# sycl_extra_flags: Clang extra compiler flags, e.g.
+#                   "-fsycl-unnamed-lambdas;-fsycl-device-code-split"
+#
+# Will compile the list of files together using clang.
+# Produces a single binary using all the .cpp files
+# named 'test_suite_name' at ${CMAKE_CURRENT_BINARY_DIR}.
+macro(add_sycl_library_unittest test_suite_name)
+  cmake_parse_arguments(ARG
+    ""
+    ""
+    "SYCL_EXTRA_FLAGS;SOURCES"
+    ${ARGN})
+
+  set(CXX_COMPILER clang++)
+  if(MSVC)
+    set(CXX_COMPILER clang-cl.exe)
+  endif()
+
+  set(DEVICE_COMPILER_EXECUTABLE ${LLVM_RUNTIME_OUTPUT_INTDIR}/${CXX_COMPILER})
+  set(_OUTPUT_BIN ${CMAKE_CURRENT_BINARY_DIR}/${test_suite_name}Tests)
+  set(_TESTS_TARGET ${test_suite_name}Tests)
+  set(_BIN_TARGET ${_TESTS_TARGET}_bin)
+  set(_LLVM_TARGET_DEPENDENCIES
+    "llvm_gtest_main;llvm_gtest;LLVMTestingSupport;LLVMSupport;LLVMDemangle")
+
+  foreach(_lib ${_LLVM_TARGET_DEPENDENCIES})
+    list(APPEND _LIBRARIES $<TARGET_LINKER_FILE:${_lib}>)
+  endforeach()
+
+  # Enable exception handling on Windows
+  # Appends extra libraries not available in LIBPATH
+  if(WIN32)
+    set(_INTERNAL_LINKER_FLAGS /link /SUBSYSTEM:CONSOLE)
+    list(APPEND _INTERNAL_EXTRA_FLAGS "/EHs")
+    list(APPEND _LIBRARIES $<TARGET_LINKER_FILE:sycl>)
+    list(APPEND _LIBRARIES ${LLVM_LIBRARY_OUTPUT_INTDIR}/sycl-devicelib-host.lib)
+  endif()
+
+  if(UNIX)
+    foreach(_lib "pthread" "dl" "ncurses")
+      list(APPEND _LIBRARIES "-l${_lib}")
+    endforeach()
+  endif()
+
+  get_target_property(GTEST_INCLUDES llvm_gtest INCLUDE_DIRECTORIES)
+  foreach(_dir ${GTEST_INCLUDES})
+    # Avoid -I when _dir contains an empty generator expression.
+    list(APPEND INCLUDE_COMPILER_STRING "$<$<BOOL:${_dir}>:-I${_dir}>")
+  endforeach()
+
+  add_custom_target(${_BIN_TARGET}
+    COMMAND ${DEVICE_COMPILER_EXECUTABLE} -fsycl ${ARG_SOURCES}
+      -o ${_OUTPUT_BIN}
+      ${ARG_SYCL_EXTRA_FLAGS}
+      ${_INTERNAL_EXTRA_FLAGS}
+      ${INCLUDE_COMPILER_STRING}
+      ${_LIBRARIES}
+      ${_INTERNAL_LINKER_FLAGS}
+    BYPRODUCTS ${CMAKE_CURRENT_BINARY_DIR}/${_TESTS_TARGET}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMAND_EXPAND_LISTS)
+
+  add_dependencies(${_BIN_TARGET} sycl)
+  foreach(_lib ${ARG_LIBRARIES})
+    add_dependencies(${_BIN_TARGET} ${_TARGET_DEPENDENCIES})
+  endforeach()
+
+  add_dependencies(SYCLUnitTests ${_BIN_TARGET})
+
+  add_executable(${_TESTS_TARGET} IMPORTED GLOBAL)
+  set_target_properties(${_TESTS_TARGET} PROPERTIES
+    IMPORTED_LOCATION ${CMAKE_CURRENT_BINARY_DIR})
+
+  # Check target for Linux
+  if (UNIX)
+    add_custom_target(check-${test_suite_name}
+      ${CMAKE_COMMAND} -E
+      env LD_LIBRARY_PATH="${CMAKE_BINARY_DIR}/lib"
+      env SYCL_CONFIG_FILE_NAME=null.cfg
+      env SYCL_DEVICELIB_NO_FALLBACK=1
+      env SYCL_CACHE_DIR="${CMAKE_BINARY_DIR}/sycl_cache"
+      ${CMAKE_CURRENT_BINARY_DIR}/${_TESTS_TARGET}
+    )
+    add_dependencies(check-${test_suite_name} ${_BIN_TARGET})
+    add_dependencies(check-sycl-unittests-libs check-${test_suite_name})
+  endif()
+
+endmacro()

sycl/include/syclcompat.hpp

@@ -0,0 +1,25 @@
+/***************************************************************************
+ *
+ *  Copyright (C) Codeplay Software Ltd.
+ *
+ *  Part of the LLVM Project, under the Apache License v2.0 with LLVM
+ *  Exceptions. See https://llvm.org/LICENSE.txt for license information.
+ *  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  SYCLcompat
+ *
+ *  syclcompat.hpp
+ *
+ *  Description:
+ *    Main include header for SYCLcompat
+ **************************************************************************/
+
+#pragma once
+
+#include <syclcompat/syclcompat.hpp>

sycl/include/syclcompat/defs.hpp

@@ -0,0 +1,43 @@
+/***************************************************************************
+ *
+ *  Copyright (C) Codeplay Software Ltd.
+ *
+ *  Part of the LLVM Project, under the Apache License v2.0 with LLVM
+ *  Exceptions. See https://llvm.org/LICENSE.txt for license information.
+ *  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  SYCLcompat
+ *
+ *  defs.hpp
+ *
+ *  Description:
+ *    helper aliases and definitions for SYCLcompat
+ *
+ **************************************************************************/
+
+// The original source was under the license below:
+//==---- dpct.hpp ---------------------------------*- C++ -*----------------==//
+//
+// Copyright (C) Intel Corporation
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+// See https://llvm.org/LICENSE.txt for license information.
+//
+//===----------------------------------------------------------------------===//
+
+#pragma once
+
+template <class... Args> class sycl_compat_kernel_name;
+template <int Arg> class sycl_compat_kernel_scalar;
+
+#define __sycl_compat_align__(n) alignas(n)
+#define __sycl_compat_inline__ __inline__ __attribute__((always_inline))
+
+#define __sycl_compat_noinline__ __attribute__((noinline))
+
+#define SYCL_COMPAT_COMPATIBILITY_TEMP (600)

sycl/include/syclcompat/dims.hpp

@@ -0,0 +1,72 @@
+/***************************************************************************
+ *
+ *  Copyright (C) Codeplay Software Ltd.
+ *
+ *  Part of the LLVM Project, under the Apache License v2.0 with LLVM
+ *  Exceptions. See https://llvm.org/LICENSE.txt for license information.
+ *  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  SYCLcompat
+ *
+ *  dims.hpp
+ *
+ *  Description:
+ *    dim3 functionality for SYCLcompat
+ **************************************************************************/
+
+#pragma once
+
+#include <tuple>
+
+#include <sycl/range.hpp>
+
+namespace syclcompat {
+
+class dim3 {
+public:
+  const size_t x, y, z;
+
+  dim3(const sycl::range<3> &r) : x(r[2]), y(r[1]), z(r[0]) {}
+
+  dim3(const sycl::range<2> &r) : x(r[1]), y(r[0]), z(1) {}
+
+  dim3(const sycl::range<1> &r) : x(r[0]), y(1), z(1) {}
+
+  constexpr dim3(size_t x, size_t y = 1, size_t z = 1) : x(x), y(y), z(z) {}
+
+  constexpr size_t size() const { return x * y * z; }
+
+  operator sycl::range<3>() const { return sycl::range<3>(z, y, x); }
+  operator sycl::range<2>() const {
+    if (z != 1)
+      throw std::invalid_argument(
+          "Attempting to convert a 3D dim3 into sycl::range<2>");
+    return sycl::range<2>(y, x);
+  }
+  operator sycl::range<1>() const {
+    if (z != 1 || y != 1)
+      throw std::invalid_argument(
+          "Attempting to convert a 2D or 3D dim3 into sycl::range<1>");
+    return sycl::range<1>(x);
+  }
+}; // namespace dim3
+
+inline dim3 operator*(const dim3 &a, const dim3 &b) {
+  return dim3{a.x * b.x, a.y * b.y, a.z * b.z};
+}
+
+inline dim3 operator+(const dim3 &a, const dim3 &b) {
+  return dim3{a.x + b.x, a.y + b.y, a.z + b.z};
+}
+
+inline dim3 operator-(const dim3 &a, const dim3 &b) {
+  return dim3{a.x - b.x, a.y - b.y, a.z - b.z};
+}
+
+} // namespace syclcompat

sycl/include/syclcompat/syclcompat.hpp

@@ -0,0 +1,26 @@
+/***************************************************************************
+ *
+ *  Copyright (C) Codeplay Software Ltd.
+ *
+ *  Part of the LLVM Project, under the Apache License v2.0 with LLVM
+ *  Exceptions. See https://llvm.org/LICENSE.txt for license information.
+ *  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  SYCLcompat
+ *
+ *  syclcompat.hpp
+ *
+ *  Description:
+ *    Main include internal header for SYCLcompat
+ **************************************************************************/
+
+#pragma once
+
+#include <syclcompat/defs.hpp>
+#include <syclcompat/dims.hpp>

sycl/unittests/CMakeLists.txt

@@ -56,3 +56,9 @@ if (NOT WIN32)
   add_subdirectory(xpti_trace)
 endif()
 
+# Library unit testing
+include(AddSYCLLibraryUnitTest)
+add_custom_target(check-sycl-unittests-libs)
+add_dependencies(check-sycl-unittests check-sycl-unittests-libs)
+
+add_subdirectory(syclcompat)

sycl/unittests/syclcompat/CMakeLists.txt

@@ -0,0 +1,33 @@
+#
+# Copyright (C) Codeplay Software Ltd.
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# SYCLcompat
+#
+
+set(SYCL_EXTRA_FLAGS "-fsycl-unnamed-lambda;-fsycl-device-code-split=per_kernel")
+
+if (UNIX)
+  add_custom_target(check-syclcompat)
+  add_dependencies(check-sycl-unittests check-syclcompat)
+endif()
+
+add_sycl_library_unittest(syclcompat-base
+  SYCL_EXTRA_FLAGS
+    ${SYCL_EXTRA_FLAGS}
+  SOURCES
+    Dim.cpp
+    Defs.cpp)
+
+if (UNIX)
+  add_dependencies(check-syclcompat check-syclcompat-base)
+endif()