Add compatibility with HIP

[csbnw]

Description

Add support for HIP, C++ Heterogeneous-Compute Interface for Portability. From the user's perspective, a few API breaking changes related to the cu::Context class had to be made when using cudawrappers in CUDA mode (which is the default). To enable the HIP mode, set CUDAWRAPPERS_BACKEND=HIP.

This PR is still a draft, as some minor things still need to be cleaned up and/or added. Also, the documentation and changelog still needs to be updated. Moreover, we may want to test integration with existing applications in more detail and make changes if needed.

Related issues:

• Add HIP backend #242
• HIP context support #283

Instructions to review the pull request

• Check that CHANGELOG.md has been updated if necessary

[csbnw]

I have updated cuda-pcie to support the current state of this branch.

This repository serves as an example of how HIP support can be added to a repository that previously only supported CUDA (using cudawrappers).

First, add a CMake option to the project:

option(BUILD_HIP "Build using HIP" OFF)

You set the CUDAWRAPPERS_BACKEND and enable HIP in CMake:

if(BUILD_HIP)
  set(CUDAWRAPPERS_GIT_TAG "add-hip") # temporary, until !289 is merged
  set(CUDAWRAPPERS_BACKEND "HIP")
  enable_language(HIP)
else()
  set(CUDAWRAPPERS_GIT_TAG "main")
endif()

Maybe the enable_language(HIP) could be inherited from cudawrappers, but I didn't find a way to achieve this.

Getting cudawrappers is the same as before, but for now, we choose the add-hip branch:

include(FetchContent)
FetchContent_Declare(
  cudawrappers
  GIT_REPOSITORY https://github.com/nlesc-recruit/cudawrappers
  GIT_TAG ${CUDAWRAPPERS_GIT_TAG})
FetchContent_MakeAvailable(cudawrappers)

Let's assume we build a simple example, which is linked to cudawrappers:

add_executable(main main.cpp)
target_link_libraries(main cudawrappers::cu)

The only thing left to do is to make sure that HIP is enabled for main.cpp as it includes <cudawrappers/cu.hpp>:

if(BUILD_HIP)
  set_source_files_properties(main.cpp PROPERTIES LANGUAGE HIP)
endif()

There doesn't seem to be a way to set language properties to targets so inheriting from cudawrappers::cu doesn't seem possible.

To me, this is about as user-friendly as it gets. No changes are needed to main.cpp at all! Of course, for more exotic CUDA stuff that isn't supported in HIP, you must add some #if defined(__HIP__) guards.

@loostrum and @john-romein, do you agree that this is the way we want to support HIP compatibility (initially)?

[loostrum]

Very nice overview, I think this is indeed the way to go for now.

[loostrum]

There are now some function in the cu::Context class that are only compiled with CUDA. How about adding the [[deprecated]] attribute to them? This would however also require updating to C++14. This is probably problematic for Catch2, so it could also be done in a later PR.

I think it's a good idea to add [[deprecated]], but indeed let's first see if we can update to C++14 in a separate PR.