Using hipify-clang

hipify-clang is a Clang-based tool for translating NVIDIA CUDA sources into HIP sources.

It translates CUDA source into an Abstract Syntax Tree (AST), which is traversed by transformation matchers. After applying all the matchers, the output HIP source is produced.

Advantages:

• hipify-clang is a translator. It parses complex constructs successfully or reports an error.

• It supports Clang options such as -I, -D, and –cuda-path.

• The support for new CUDA versions is seamless, as the Clang front-end is statically linked into hipify-clang and does all the syntactical parsing of a CUDA source to HIPIFY.

• It is very well supported as a compiler extension.

Disadvantages:

• You must ensure that the input CUDA code is correct as incorrect code can’t be translated to HIP.

• You must install CUDA, and in case of multiple installations specify the needed version using --cuda-path option.

• You must provide all the includes and defines to successfully translate the code.

Release Dependencies

hipify-clang requires:

• CUDA, the latest supported version is 12.8.1, but requires at least version 7.0.

• LLVM+Clang version is determined at least partially by the CUDA version you are using, as shown in the table below. The recommended Clang release is the latest stable release 20.1.8, or at least version 4.0.0.

CUDA version	supported LLVM release versions	Windows	Linux
12.9.0	21.0.0git	✅	✅
12.8.11	20.1.0, 20.1.1, 20.1.2, 20.1.3, 20.1.4, 20.1.5, 20.1.6, 20.1.7, 20.1.81	✅	✅
12.6.3	19.1.0, 19.1.1, 19.1.2, 19.1.3, 19.1.4, 19.1.5, 19.1.6, 19.1.7	✅	✅
12.3.2	17.0.1, 17.0.2, 17.0.3, 17.0.4, 17.0.5, 17.0.6, 18.1.0, 18.1.1, 18.1.2, 18.1.3, 18.1.4, 18.1.5, 18.1.6, 18.1.7, 18.1.8	✅	✅
12.2.2	16.0.0, 16.0.1, 16.0.2, 16.0.3, 16.0.4, 16.0.5, 16.0.6	✅	✅
11.8.0	14.0.5, 14.0.6, 15.0.0, 15.0.1, 15.0.2, 15.0.3, 15.0.4, 15.0.5, 15.0.6, 15.0.7	✅	✅
11.7.1	14.0.0, 14.0.1, 14.0.2, 14.0.3, 14.0.4	Works only with patch due to Clang bug 54609 patch for 14.0.0 2 patch for 14.0.1 2 patch for 14.0.2 2 patch for 14.0.3 2 patch for 14.0.4 2	✅
11.5.1	12.0.0, 12.0.1, 13.0.0, 13.0.1	✅	✅
11.2.2	11.0.1, 11.1.0	✅	✅
11.0.1, 11.1.0, 11.1.1	11.0.0	Works only with patch due to Clang bug 47332 patch for 11.0.0 3	Works only with patch due to Clang bug 47332 patch for 11.0.0 3
11.0.0	11.0.0	✅	✅
11.0.1, 11.1.0, 11.1.1	10.0.0, 10.0.1	Works only with patch due to Clang bug 47332 patch for 10.0.0 3 patch for 10.0.1 3	Works only with patch due to Clang bug 47332 patch for 10.0.0 3 patch for 10.0.1 3
11.0.0	10.0.0, 10.0.1	✅	✅
10.1	9.0.0, 9.0.1	✅	✅
10.0	8.0.0, 8.0.1	Works only with patch due to Clang bug 38811 patch for 8.0.0 2 patch for 8.0.1 2	✅
9.2	7.0.0, 7.0.1, 7.1.0	Works only with patch due to Clang bug 38811 patch for 7.0.0 2 patch for 7.0.1 2 patch for 7.1.0 2	❌ due to Clang bug 36384
9.0	6.0.0, 6.0.1	✅	✅
8.0	4.0.0, 4.0.1, 5.0.0, 5.0.1, 5.0.2	✅	✅
7.5	3.8.0 4, 3.8.1 4, 3.9.0 4, 3.9.1 4	✅	✅

¹ Represents the latest supported and recommended configuration.

² Download the patch and unpack it into your LLVM distributive directory. This overwrites a few header files. You don’t need to rebuild LLVM.

³ Download the patch and unpack it into your LLVM source directory. This overwrites the Cuda.cpp file. You need to rebuild LLVM.

⁴ LLVM 3.x is no longer supported (but might still work).

In most cases, you can get a suitable version of LLVM+Clang with your package manager. However, you can also download a release archive and build or install it. In case of multiple versions of LLVM installed, set CMAKE_PREFIX_PATH so that CMake can find the desired version of LLVM. For example, -DCMAKE_PREFIX_PATH=D:\LLVM\20.1.8\dist.

Usage

Note

For additional details on the following hipify-clang command options, see hipify-clang command

To process a file, hipify-clang needs access to the same headers that are required to compile it with Clang:

./hipify-clang square.cu --cuda-path=/usr/local/cuda-12.8 -I /usr/local/cuda-12.8/samples/common/inc

hipify-clang arguments are supplied first, followed by a separator -- and the arguments to be passed to Clang for compiling the input file:

./hipify-clang cpp17.cu --cuda-path=/usr/local/cuda-12.8 -- -std=c++17

hipify-clang also supports the hipification of multiple files that can be specified in a single command with absolute or relative paths:

./hipify-clang cpp17.cu ../../square.cu /home/user/cuda/intro.cu --cuda-path=/usr/local/cuda-12.8 -- -std=c++17

To use a specific version of LLVM during hipification, specify the hipify-clang option --clang-resource-directory= to point to the Clang resource directory, which is the parent directory for the include folder that contains __clang_cuda_runtime_wrapper.h and other header files used during the hipification process:

./hipify-clang square.cu --cuda-path=/usr/local/cuda-12.8 --clang-resource-directory=/usr/llvm/20.1.8/dist/lib/clang/20

For more information, refer to the Clang manual for compiling CUDA.

Using JSON compilation database

For some hipification automation (starting from Clang 8.0.0), you can provide a Compilation Database in JSON format in the compile_commands.json file:

-p <folder containing compile_commands.json>
- or -
-p=<folder containing compile_commands.json>

You can provide the compilation database in the compile_commands.json file or generate using Clang based on CMake. You can specify multiple source files as well.

To provide Clang options, use compile_commands.json file, whereas to provide hipify-clang options, use the hipify-clang command line.

Note

Don’t use the options separator -- to avoid compilation error caused due to the hipify-clang options being provided before the separator.

Here’s an example demonstrating the compile_commands.json usage:

[
  {
    "directory": "<test dir>",
    "command": "hipify-clang \"<CUDA dir>\" -I./include -v",
    "file": "cd_intro.cu"
  }
]

Hipification statistics

The options --print-stats and --print-stats-csv provide an overview of what is hipified and what is not, as well as the hipification statistics. Use the --print-stats command to return the statistics as text to the terminal, or the --print-stats-csv command to create a CSV file to open in a spreadsheet.

Note

When multiple source files are specified on the command-line, the statistics are provided per file and in total.

Print statistics

hipify-clang intro.cu -cuda-path="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.8" --print-stats

[HIPIFY] info: file 'intro.cu' statistics:
CONVERTED refs count: 40
UNCONVERTED refs count: 0
CONVERSION %: 100.0
REPLACED bytes: 604
[HIPIFY] info: file 'intro.cu' statistics:
  CONVERTED refs count: 40
  UNCONVERTED refs count: 0
  CONVERSION %: 100.0
  REPLACED bytes: 604
  TOTAL bytes: 5794
  CHANGED lines of code: 34
  TOTAL lines of code: 174
  CODE CHANGED (in bytes) %: 10.4
  CODE CHANGED (in lines) %: 19.5
  TIME ELAPSED s: 0.41
[HIPIFY] info: CONVERTED refs by type:
  error: 2
  device: 2
  memory: 16
  event: 9
  thread: 1
  include_cuda_main_header: 1
  type: 2
  numeric_literal: 7
[HIPIFY] info: CONVERTED refs by API:
  CUDA Driver API: 1
  CUDA RT API: 39
[HIPIFY] info: CONVERTED refs by names:
  cuda.h: 1
  cudaDeviceReset: 1
  cudaError_t: 1
  cudaEventCreate: 2
  cudaEventElapsedTime: 1
  cudaEventRecord: 3
  cudaEventSynchronize: 3
  cudaEvent_t: 1
  cudaFree: 4
  cudaFreeHost: 3
  cudaGetDeviceCount: 1
  cudaGetErrorString: 1
  cudaGetLastError: 1
  cudaMalloc: 3
  cudaMemcpy: 6
  cudaMemcpyDeviceToHost: 3
  cudaMemcpyHostToDevice: 3
  cudaSuccess: 1
  cudaThreadSynchronize: 1

Print CSV statistics

hipify-clang intro.cu -cuda-path="C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.8" --print-stats-csv

This generates intro.cu.csv file with statistics: