HIPIFY: translating CUDA source into portable HIP C++

A source translator, not a compatibility layer

HIPIFY is described as a set of tools that you can use to automatically translate CUDA source code into portable HIP C++. The word portable is the whole point of the exercise, and the mechanism is source rewriting rather than anything that happens at run time.

That distinction sets expectations correctly. HIPIFY reads your CUDA source and emits HIP source. It does not load CUDA libraries, it does not shim kernel launches at run time, and it does not decide whether an algorithm that ran on an NVIDIA GPU will run acceptably on an AMD one. What it does is replace the API calls, the types and the intrinsic names in your code with their HIP equivalents, which turns a porting project from a rewrite into a review.

The tool lives inside ROCm, AMD's open source compute stack, and the project is not a single binary. The topic list names two front ends, hipify-clang and hipify-perl, alongside the cuda2hip tag that names the mapping the tools produce. The top-level tree backs up the multi-tool picture, with src/ for the sources, bin/ for the built binaries, tests/ for the test suite, packaging/ for the distribution artefacts, and CMakeLists.txt for the build.

The documentation is published separately from the code, at the HIPIFY pages under rocm.docs.amd.com, and the source files for it live in the HIPIFY/docs folder of this same repository, which means the docs are versioned with the tool rather than drifting away from it.

The same tool that translates code also documents coverage

The most interesting thing about HIPIFY is that hipify-clang does double duty, and the documentation makes that explicit. To build the CUDA2HIP documentation, which is the list of CUDA APIs supported by HIP, you run the hipify-clang command:

hipify-clang --md --doc-format=full --doc-roc=joint

# Alternatively, you can use:

hipify-clang --md --doc-format=full --doc-roc=separate

The built content is the same as the supported CUDA APIs page in the repository, at docs/reference/supported_apis.md. So the coverage table in the documentation is not maintained by hand; it is a build artefact of the translation tool itself. That is the single most useful property of the project for an adopter, because a coverage table that is generated cannot drift away from the behaviour of the tool.

The two --doc-roc modes answer different questions. The joint mode puts ROCm and HIP information in one combined table, which is what you want when you are reading it as a single ecosystem. The separate mode splits them, which is what you want when you need to see at a glance which side of the mapping a given API belongs to. Reading the same data in both shapes is a cheap way to understand whether a gap in the table means the API is missing or simply reported in the other section.

The same applies to the output format. The --md option produces markdown, and the --csv option produces the same data as CSV, which is what you want if you intend to filter it. And the doc format itself has three settings, full, strict and compact, where strict and compact are narrower renderings of the same content.

Discovering the option set is a documentation step, not a guess

The published documentation for a tool like this is inevitably a summary, and the project handles that gap by pointing you at the tool itself. To see all available options, use the --help or --help-hidden hipify-clang option.

The split between those two flags is the interesting detail. --help gives you the ordinary surface, and --help-hidden gives you the rest, the options that are there but not advertised in the short listing. For a source rewriting tool that touches every call site in a file, that difference matters: a conversion run with a non-default option can change the shape of the output substantially, and the only complete inventory of what is available is the hidden help.

The practical pattern this suggests is to check the option list before running the tool over a large tree, rather than discovering a flag afterwards. The documentation gives you the vocabulary of the tool, the --doc flags for the coverage table, the --help and --help-hidden flags for the full option inventory, and the docs pages for the conceptual documentation. A tool that rewrites source is a tool whose configuration you want to understand before pointing it at code you care about.

The other two documented commands are of a different kind. Building the documentation locally needs Sphinx, and the instructions are explicit:

cd docs

pip3 install -r .sphinx/requirements.txt

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

Those flags are the ones to read for what they imply. -T drops the theme, so the output is plain HTML. -E ignores the environment, so the cached build state does not hide changes. The rest is the standard html builder with the doctree cache and the English language set. A -T flag on a docs build is unusual, and it is there because the ROCm docs are published with a themed pipeline that the local build does not need to reproduce.

Where the source lives in the repository

The top-level entries describe how the project is put together, and a few of them say more than the file names suggest.

There is src/ for the sources, tests/ for the test suite, and a CMakeLists.txt for the build. There is bin/, which is where the built binaries land. There is packaging/, which is where the distribution artefacts are assembled, and that directory is a signal in itself: HIPIFY is meant to be distributed as a package that a developer installs rather than built by hand on a workstation.

The infrastructure directories show what kind of project this is. There is a .github/ directory for the GitHub side, a .azuredevops/ directory for the Azure Pipelines side, and a .readthedocs.yaml file for the documentation hosting. A project of this size that runs continuous integration on two different platforms is one where the conversion output is checked continuously, which is the only way to keep a rewrite tool honest about its behaviour.

Then there are the files that describe how the repository itself is written. A .mdlrc file and a matching mdlrc-style.rb Ruby file configure the markdown linter, and a .gitignore and .gitattributes sit alongside. CHANGELOG.md is present at the root, and docs/ holds the documentation sources, including the generated supported_apis.md that the tool itself writes.

The custom files are worth noting because the tool is a source transformer and its own source style matters: the linter configuration and the formatting rules apply to the code that decides how everyone else's code is rewritten.

Release naming, branch layout and the licence question

The repository's default branch is amd-develop, which is where the work lands rather than master. The recent release list is also unconventional: the tags are therock-10.1, therock-7.14.1 and therock-10.0, and they are not version numbers in the usual sense. They are named after TheRock, the package manager ROCm uses to distribute its components, so a HIPIFY version is identified by the package channel it ships through rather than by a semver string of its own.

That is worth understanding before you plan an upgrade, because it changes what a version number means. A therock tag tells you which ROCm package stream the release belongs to, and the compatibility between HIPIFY and the rest of ROCm is what you are really pinning when you pin that tag. The therock-7.14.1 tag is a different stream from therock-10.0 and therock-10.1, and mixing a HIPIFY from one with a ROCm from another is the kind of thing that produces a confusing error rather than a clean one.

The repository is not archived, and the last push was on 2026-10-16, with the most recent release tag dated 2026-10-05, so the branch is moving ahead of the tags.

On the licence, the metadata records something other than a standard open source identifier, and the tree carries a LICENSE.txt file, so the terms are there to read but are not one of the usual short grants. For a project that AMD builds as part of ROCm, the terms of a component you are redistributing inside a product are worth reading rather than assuming.

Where HIPIFY is the wrong tool

The first limit is the one the tool's own framing implies. A source translator produces a candidate port, not a verified one. The CUDA2HIP coverage table tells you which APIs have a mapping, and a green row means a call site was rewritten, not that the rewritten program behaves identically on the target hardware. Kernel launch configuration, occupancy assumptions, memory hierarchy expectations and numerical differences between vendors are outside what any call-by-call translation can address. A team that reads the tool as producing a correct port will be disappointed; a team that reads it as producing a reviewable diff will be right.

The second limit is coverage gaps. The existence of a supported APIs document with strict and compact formats implies that the mapping is not total, and that the table is the authoritative statement of what is covered. A codebase that leans on an unmapped API will not be converted cleanly, and finding out which ones means reading the generated table rather than reading the source of the translator.

The third is that this is a ROCm project. The target platform is AMD hardware, and the output is HIP C++ compiled with ROCm's toolchain. It does not go the other way, it does not generate CUDA from HIP, and it does not address the NVIDIA side of a heterogeneous fleet.

The fourth is the workflow fit. HIPIFY is a command line tool with a large option surface, and it does its work on files. A team with a large multi-platform codebase that uses HIP headers conditionally will find that the source it feeds in is not the source it compiles, which means the conversion has to be maintained as a separate branch or a separate translation step in the build, not applied once and forgotten. The published documentation covers the tool thoroughly; it does not describe a project layout for keeping a converted tree in sync with the original, so that part is yours to design.

Editorial conclusion

HIPIFY is the right starting point for a team that has to move CUDA sources to AMD hardware and would rather spend its review time on semantics than on rewriting thousands of API calls, because the translation is mechanical, repeatable, and its coverage is published as a generated document rather than a claim. It is the wrong tool if you need a finished, correct port, since the output is a translation of call sites and not a validation that the resulting program behaves the same on different hardware. Before you run it across a repository, check the three things the documentation actually supports: the CUDA2HIP supported APIs list, which is generated by the same tool that does the translation and tells you which calls are covered, which are not, and what the HIP equivalent is; the --doc-roc joint and separate modes, because a single joint table and two separate tables answer different questions about partial coverage; and the option list itself, through --help and --help-hidden, since the tool exposes a lot of behaviour that the published documentation does not enumerate.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. ROCm/HIPIFY on GitHub