How rocm/hipify works
Project Type and Purpose
• HIPIFY is a command-line translation toolchain (CLI utility) that automatically converts NVIDIA CUDA C/C++ source into portable HIP C++ using two main implementations:
a. A C++-based tool (“hipify-clang”) built on LLVM/Clang libraries.
b. A Perl-based tool (“hipify-perl”) invoked via shell scripts.
• It includes:
• Core translation engine (C++).
• Auxiliary scripts (bash, Perl) in bin/.
• Test harness (LLVM Lit tests).
• Documentation in docs/.
• Packaging scripts for installers (RPM, Debian) in packaging/.
• CI pipelines (.azuredevops, .github/workflows).
Main Components
• CLI Front-end
• Entry points: src/main.cpp (hipify-clang), bin/hipify-perl and bin/hipconvertinplace-perl.sh.
• Argument parser (ArgParse.cpp/h).
• Translation Engine
• HIPifyAction and ReplacementsFrontendActionFactory (src/HipifyAction.* and related).
• Modular rule sets: CUDA2HIP_*.cpp/h for each API domain (BLAS, DNN, Device, etc.).
• String/Statistics/LLVMCompat utilities.
• Clang/LLVM Integration
• Uses libclang API for AST parsing, rewriting, semantic checks.
• Rewrites in-memory AST → source patches → output files.
• I/O Subsystem
• Reads input CUDA files (.cu, .cuh).
• Emits transformed HIP files or in-place edits.
• Packaging & Distribution
• CMakeLists.txt + packaging/ scripts → installers, postinst/prerm hooks.
• Documentation Generator
• Sphinx sources under docs/ + build instructions.
• “hipify-clang --md/--csv” to generate API reference tables.
• Test Infrastructure
• tests/unit_tests run under LLVM Lit driver.
• CI workflows (.yml) invoke builds, run tests on Linux/macOS.
Relationships and Interactions
• User → CLI Front-end → ArgParse → Translation Engine → Clang AST API → Rewriter → Output.
• CLI Front-end invokes either C++ engine or Perl scripts.
• Translation Engine modules (each API domain) register callbacks with Clang; collaborate to produce correct substitutions.
• Packaging system consumes build artifacts from CMake.
• CI pipelines trigger CMake build → run unit tests → build docs → produce packages.
Architectural Patterns & Design Principles
• Modular plugin pattern: each CUDA API domain encapsulated in its own source file set.
• Visitor pattern via Clang FrontendAction (HipifyAction) to traverse AST.
• Separation of concerns:
• Argument handling (ArgParse)
• Core logic (CUDA2HIP modules)
• I/O & file management
• Packaging & docs
• Test-driven design: comprehensive per-domain unit tests under tests/.