# rocm/hipify architecture

> Architecture diagram of the GitHub repository rocm/hipify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rocm/hipify
- Repository: https://github.com/rocm/hipify

## Overview

##### 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/.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Layer 1: Actors and CI
    subgraph "Layer 1: Entry Points" 
        direction TB
        User(["User"]):::external
        CI(["CI Pipelines"]):::scripts
    end

    %% Layer 2: CLI Front-ends
    subgraph "Layer 2: CLI Front-ends" 
        direction TB
        HipifyClang["hipify-clang\n(src/main.cpp)"]:::frontend
        HipifyPerl["hipify-perl\n(bin/hipify-perl)"]:::scripts
        HipConvertInPlace["hipconvertinplace-perl.sh\n(bin/hipconvertinplace-perl.sh)"]:::scripts
        ArgParse["ArgParse\n(src/ArgParse.cpp/h)"]:::frontend
    end

    %% Layer 3: Translation Engine
    subgraph "Layer 3: Translation Engine" 
        direction TB
        CUDA2HIPCore["Core Engine\n(src/CUDA2HIP.cpp/h)"]:::core
        HipifyAction["HipifyAction\n(src/HipifyAction.cpp/h)"]:::core
        ReplFactory["ReplacementsFrontendActionFactory\n(src/ReplacementsFrontendActionFactory.h)"]:::core
        subgraph "Modular Rule Sets" 
            direction TB
            BLAS_Funcs["BLAS Functions\n(src/CUDA2HIP_BLAS_API_functions.cpp)"]:::core
            BLAS_Types["BLAS Types\n(src/CUDA2HIP_BLAS_API_types.cpp)"]:::core
            DNN_Funcs["DNN Functions\n(src/CUDA2HIP_DNN_API_functions.cpp)"]:::core
            DNN_Types["DNN Types\n(src/CUDA2HIP_DNN_API_types.cpp)"]:::core
            Device_Funcs["Device Functions\n(src/CUDA2HIP_Device_functions.cpp)"]:::core
            Device_Types["Device Types\n(src/CUDA2HIP_Device_types.cpp)"]:::core
            Runtime_Funcs["Runtime Functions\n(src/CUDA2HIP_Runtime_API_functions.cpp)"]:::core
            Runtime_Types["Runtime Types\n(src/CUDA2HIP_Runtime_API_types.cpp)"]:::core
        end
        subgraph "Utilities"
            direction TB
            StringUtils["StringUtils\n(src/StringUtils.cpp/h)"]:::core
            Statistics["Statistics\n(src/Statistics.cpp/h)"]:::core
            LLVMCompat["LLVMCompat\n(src/LLVMCompat.cpp/h)"]:::core
        end
        ScriptingSupport["Scripting Support\n(src/CUDA2HIP_Perl.cpp,\nsrc/CUDA2HIP_Python.cpp,\nsrc/CUDA2HIP_Scripting.h)"]:::core
        LLVM["LLVM/Clang\n(AST & Rewriter)"]:::external
    end

    %% Layer 4: I/O
    subgraph "Layer 4: I/O & Output" 
        direction TB
        InputFiles["CUDA Files\n(.cu, .cuh)"]:::storage
        OutputFiles["HIP Files / In-place"]:::storage
    end

    %% Layer 5: Packaging & Docs & Tests
    subgraph "Layer 5: Packaging & Documentation & Tests"
        direction TB
        CMake["CMakeLists.txt"]:::pack
        Packaging["packaging/"]:::pack
        Docs["docs/"]:::docs
        Tests["Test Harness\n(tests/, LLVM Lit)"]:::scripts
    end

    %% Connections
    User -->|"invokes"| HipifyClang
    User -->|"invokes"| HipifyPerl
    User -->|"invokes"| HipConvertInPlace

    CI -->|"triggers build/test"| CMake
    CI -->|"runs tests"| Tests
    CI -->|"builds docs"| Docs
    CI -->|"produces packages"| Packaging

    HipifyClang -->|"parses args"| ArgParse
    HipifyClang -->|"calls engine"| CUDA2HIPCore
    HipifyPerl -->|"runs script"| ScriptingSupport
    HipConvertInPlace -->|"runs script"| ScriptingSupport

    ArgParse -->|"configures"| CUDA2HIPCore
    CUDA2HIPCore -->|"registers action"| HipifyAction
    CUDA2HIPCore -->|"uses factory"| ReplFactory
    CUDA2HIPCore -->|"loads modules"| BLAS_Funcs
    CUDA2HIPCore -->|"loads modules"| BLAS_Types
    CUDA2HIPCore -->|"loads modules"| DNN_Funcs
    CUDA2HIPCore -->|"loads modules"| DNN_Types
    CUDA2HIPCore -->|"loads modules"| Device_Funcs
    CUDA2HIPCore -->|"loads modules"| Device_Types
    CUDA2HIPCore -->|"loads modules"| Runtime_Funcs
    CUDA2HIPCore -->|"loads modules"| Runtime_Types

    HipifyAction -->|"traverses AST"| LLVM
    LLVM -->|"rewrites"| HipifyAction
    HipifyAction -->|"emits patches"| ReplFactory

    ReplFactory -->|"applies patches"| OutputFiles
    CUDA2HIPCore -->|"reads"| InputFiles
    ScriptingSupport -->|"reads/writes"| InputFiles
    ScriptingSupport -->|"produces"| OutputFiles

    CMake -->|"installs artifacts"| Packaging
    CMake -->|"configures build"| CUDA2HIPCore
    CMake -->|"configures build"| HipifyAction

    Docs -->|"sources Sphinx"| Docs
    HipifyClang -->|"--md/--csv"| Docs

    Tests -->|"executes"| CUDA2HIPCore
    Tests -->|"verifies modules"| BLAS_Funcs

    %% Click Events
    click HipifyClang "https://github.com/rocm/hipify/blob/amd-develop/src/main.cpp"
    click HipifyPerl "https://github.com/rocm/hipify/tree/amd-develop/bin/hipify-perl"
    click HipConvertInPlace "https://github.com/rocm/hipify/blob/amd-develop/bin/hipconvertinplace-perl.sh"
    click ArgParse "https://github.com/rocm/hipify/blob/amd-develop/src/ArgParse.cpp"
    click ArgParse "https://github.com/rocm/hipify/blob/amd-develop/src/ArgParse.h"
    click CUDA2HIPCore "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP.cpp"
    click CUDA2HIPCore "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP.h"
    click BLAS_Funcs "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_BLAS_API_functions.cpp"
    click BLAS_Types "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_BLAS_API_types.cpp"
    click DNN_Funcs "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_DNN_API_functions.cpp"
    click DNN_Types "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_DNN_API_types.cpp"
    click Device_Funcs "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Device_functions.cpp"
    click Device_Types "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Device_types.cpp"
    click Runtime_Funcs "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Runtime_API_functions.cpp"
    click Runtime_Types "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Runtime_API_types.cpp"
    click HipifyAction "https://github.com/rocm/hipify/blob/amd-develop/src/HipifyAction.cpp"
    click HipifyAction "https://github.com/rocm/hipify/blob/amd-develop/src/HipifyAction.h"
    click ReplFactory "https://github.com/rocm/hipify/blob/amd-develop/src/ReplacementsFrontendActionFactory.h"
    click StringUtils "https://github.com/rocm/hipify/blob/amd-develop/src/StringUtils.cpp"
    click StringUtils "https://github.com/rocm/hipify/blob/amd-develop/src/StringUtils.h"
    click Statistics "https://github.com/rocm/hipify/blob/amd-develop/src/Statistics.cpp"
    click Statistics "https://github.com/rocm/hipify/blob/amd-develop/src/Statistics.h"
    click LLVMCompat "https://github.com/rocm/hipify/blob/amd-develop/src/LLVMCompat.cpp"
    click LLVMCompat "https://github.com/rocm/hipify/blob/amd-develop/src/LLVMCompat.h"
    click ScriptingSupport "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Perl.cpp"
    click ScriptingSupport "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Python.cpp"
    click ScriptingSupport "https://github.com/rocm/hipify/blob/amd-develop/src/CUDA2HIP_Scripting.h"
    click CMake "https://github.com/rocm/hipify/blob/amd-develop/CMakeLists.txt"
    click Packaging "https://github.com/rocm/hipify/tree/amd-develop/packaging/"
    click Docs "https://github.com/rocm/hipify/tree/amd-develop/docs/"
    click Tests "https://github.com/rocm/hipify/tree/amd-develop/tests/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef scripts fill:#FFF8E1,stroke:#FF8F00,color:#FF8F00
    classDef storage fill:#ECEFF1,stroke:#37474F,color:#37474F
    classDef pack fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef docs fill:#EDE7F6,stroke:#4527A0,color:#4527A0
```
