Add HIP Graph API tutorial

.github/workflows/build_hip_documentation.yml

@@ -9,7 +9,7 @@ on:
   pull_request:
     branches: [ amd-staging, amd-mainline, release/** ]
     paths:
-      - 'HIP-Programmin-Guide/**'
+      - 'HIP-Doc/**'
       - '.github/workflows/**'
 
 env:
@@ -29,7 +29,7 @@ jobs:
             run: |
                   apt-get update -qq &&
                   apt-get install -y build-essential g++ glslang-tools \
-                    python3 python3-pip libglfw3-dev libvulkan-dev locales wget
+                    python3 python3-pip libglfw3-dev libvulkan-dev locales wget git libtiff-dev
                   python3 -m pip install --upgrade pip
                   python3 -m pip install cmake
           - name: Install ROCm Dev
@@ -38,7 +38,7 @@ jobs:
                   wget https://repo.radeon.com/amdgpu-install/${{ env.ROCM_VERSION }}/ubuntu/jammy/amdgpu-install_${{ env.AMDGPU_INSTALLER_VERSION }}_all.deb
                   apt-get -y install ./amdgpu-install_${{ env.AMDGPU_INSTALLER_VERSION }}_all.deb &&
                   apt-get update -qq &&
-                  apt-get -y install rocm-dev rocm-llvm-dev
+                  apt-get -y install rocm-dev rocm-llvm-dev hipfft-dev
                   echo "/opt/rocm/bin" >> $GITHUB_PATH
                   echo "ROCM_PATH=/opt/rocm" >> $GITHUB_ENV
                   echo "LD_LIBRARY_PATH=/opt/rocm/lib:${LD_LIBRARY_PATH}" >> $GITHUB_ENV

.github/workflows/build_hip_documentation_cuda.yml

@@ -30,7 +30,7 @@ jobs:
             run: |
                   apt-get update -qq &&
                   apt-get install -y build-essential g++ glslang-tools \
-                    python3 python3-pip locales wget
+                    python3 python3-pip locales wget git libtiff-dev
                   python3 -m pip install --upgrade pip
                   python3 -m pip install cmake
 
@@ -40,13 +40,13 @@ jobs:
               wget https://repo.radeon.com/amdgpu-install/${{ env.ROCM_VERSION }}/ubuntu/jammy/amdgpu-install_${{ env.AMDGPU_INSTALLER_VERSION }}_all.deb
               apt-get -y install ./amdgpu-install_${{ env.AMDGPU_INSTALLER_VERSION }}_all.deb &&
               apt-get update -qq &&
-              apt-get install -y hip-dev hipify-clang
+              apt-get install -y hip-dev hipify-clang hipfft-dev
 
           - name: Configure and Build
             shell: bash
             # The CMAKE_POLICY_VERSION_MINIMUM environment variable can be removed once the CMake updates from ROCm 7.0 are available
             run: |
               cd HIP-Doc && mkdir build && cd build
               export CMAKE_POLICY_VERSION_MINIMUM="3.5"
-              cmake -DGPU_RUNTIME=CUDA ..
+              cmake -DROCM_EXAMPLES_GPU_LANGUAGE=CUDA -DHIP_PLATFORM=nvidia ..
               cmake --build . -j

HIP-Doc/CMakeLists.txt

@@ -27,6 +27,7 @@ include(CTest)
 
 add_subdirectory(Programming-Guide)
 add_subdirectory(Reference)
+add_subdirectory(Tutorials)
 
 include("${CMAKE_CURRENT_LIST_DIR}/../Common/HipPlatform.cmake")
 select_gpu_language()

HIP-Doc/Makefile

@@ -22,7 +22,8 @@
 
 SUBDIRECTORIES := \
 	Programming-Guide \
-	Reference
+	Reference \
+	Tutorials
 
 all: $(SUBDIRECTORIES)
 

HIP-Doc/Tutorials/CMakeLists.txt

@@ -0,0 +1,28 @@
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+cmake_minimum_required(VERSION 3.21 FATAL_ERROR)
+project(HIP-Doc-Tutorials LANGUAGES CXX)
+
+include(CTest)
+
+add_subdirectory(graph_api)

HIP-Doc/Tutorials/graph_api/CMakeLists.txt

@@ -0,0 +1,48 @@
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+cmake_minimum_required(VERSION 3.21)
+
+project(hip_graph_api_tutorial LANGUAGES CXX)
+
+include("${CMAKE_CURRENT_LIST_DIR}/../../../Common/HipPlatform.cmake")
+select_gpu_language()
+enable_language(${ROCM_EXAMPLES_GPU_LANGUAGE})
+select_hip_platform()
+
+if(CMAKE_SYSTEM_NAME MATCHES "Windows")
+    set(ROCM_ROOT
+        "$ENV{HIP_PATH}"
+        CACHE PATH
+        "Root directory of the ROCm installation"
+    )
+else()
+    set(ROCM_ROOT
+        "/opt/rocm"
+        CACHE PATH
+        "Root directory of the ROCm installation"
+    )
+endif()
+
+list(APPEND CMAKE_PREFIX_PATH "${ROCM_ROOT}")
+
+add_subdirectory(src)

HIP-Doc/Tutorials/graph_api/README.md

@@ -0,0 +1,151 @@
+# HIP-Doc HIP Graph API tutorial
+
+## Description
+
+This example demonstrates how to port an existing stream-based application to a graph-based application. For more
+information on this topic, please refer to the
+[HIP Documentation](https://rocm.docs.amd.com/projects/HIP/en/latest/tutorial/graph_api.html).
+
+### Prerequisites
+
+On Windows, this example can only be built by CMake and the Ninja generator. Visual Studio generators are not supported.
+
+### Application flow
+
+#### Stream variant
+
+1. The number of asynchronous engines on the device is queried.
+2. A phantom volume is created and forward projections are created from it.
+3. The required data buffers, hipFFT plans, etc. are set up.
+4. The forward projections are processed in batches. The batch size is equal to the number of asynchronous engines. Each
+   batch item is processed in its own stream. Each projection is processed in the following way:
+    1. All pixels in the projection are normalized, i.e. transformed from a 12-bit unsigned integer value to a 32-bit
+       floating-point value in the range [0, 1].
+    2. The projection is log transformed.
+    3. The projection is weighted.
+    4. The projection is transformed into Fourier space.
+    5. The projection is filtered in Fourier space.
+    6. The filtered projection is transformed into real space.
+    7. The filtered projection is back-projected.
+5. The resulting volume is saved to disk.
+6. The data is cleaned up.
+
+#### Capturing variant
+
+1. The number of asynchronous engines on the device is queried.
+2. A phantom volume is created and forward projections are created from it.
+3. The required data buffers, hipFFT plans, etc. are set up.
+4. The forward projections are processed in batches. The batch size is equal to the number of asynchronous engines. Each
+   batch item is processed in its own stream. All processing streams are captured into a HIP graph template.
+   Each projection is processed in the following way:
+    1. All pixels in the projection are normalized, i.e. transformed from a 12-bit unsigned integer value to a 32-bit
+       floating-point value in the range [0, 1].
+    2. The projection is log transformed.
+    3. The projection is weighted.
+    4. The projection is transformed into Fourier space.
+    5. The projection is filtered in Fourier space.
+    6. The filtered projection is transformed into real space.
+    7. The filtered projection is back-projected.
+5. The resulting graph template is instantiated and launched on a stream.
+6. The resulting volume is saved to disk.
+7. The data is cleaned up.
+
+#### Manual creation variant
+
+1. The number of asynchronous engines on the device is queried.
+2. A phantom volume is created and forward projections are created from it.
+3. The required data buffers, hipFFT plans, etc. are set up.
+4. The forward projections are processed in batches. The batch size is equal to the number of asynchronous engines. Each
+   batch item represents a branch in the graph template, and each branch consists of the following steps where each step
+   represents a node in the graph:
+    1. All pixels in the projection are normalized, i.e. transformed from a 12-bit unsigned integer value to a 32-bit
+       floating-point value in the range [0, 1].
+    2. The projection is log transformed.
+    3. The projection is weighted.
+    4. The projection is transformed into Fourier space.
+    5. The projection is filtered in Fourier space.
+    6. The filtered projection is transformed into real space.
+    7. The filtered projection is back-projected.
+5. The resulting graph template is instantiated and launched on a stream.
+6. The resulting volume is saved to disk.
+7. The data is cleaned up.
+
+## Demonstrated API calls
+
+### HIP Runtime
+
+#### Device symbols
+
+* `atomicAdd`
+* `blockIdx`
+* `blockDim`
+* `cosf`
+* `expf`
+* `fabsf`
+* `floorf`
+* `fmaxf`
+* `fminf`
+* `logf`
+* `max`
+* `min`
+* `roundf`
+* `sinf`
+* `sqrtf`
+* `tex2D`
+* `threadIdx`
+
+#### Host symbols
+
+* `hipCreateChannelDesc`
+* `hipCreateTextureObject`
+* `hipDestroyTextureObject`
+* `hipDeviceSynchronize`
+* `hipEventCreate`
+* `hipEventDestroy`
+* `hipEventRecord`
+* `hipFree`
+* `hipFreeHost`
+* `hipGetDeviceProperties`
+* `hipGetErrorString`
+* `hipGraphAddKernelNode`
+* `hipGraphAddMemcpyNode`
+* `hipGraphAddMemsetNode`
+* `hipGraphCreate`
+* `hipGraphDebugDotPrint`
+* `hipGraphDestroy`
+* `hipGraphExecDestroy`
+* `hipGraphExecUpdate`
+* `hipGraphGetNodes`
+* `hipGraphInstantiate`
+* `hipGraphLaunch`
+* `hipGraphNodeGetDependentNodes`
+* `hipHostMalloc`
+* `hipLaunchHostFunc`
+* `hipMalloc`
+* `hipMalloc3D`
+* `hipMallocPitch`
+* `hipMemcpy2DAsync`
+* `hipMemcpy3DAsync`
+* `hipMemGetInfo`
+* `hipMemset2DAsync`
+* `hipMemset3D`
+* `hipStreamBeginCapture`
+* `hipStreamBeginCaptureToGraph`
+* `hipStreamCreate`
+* `hipStreamEndCapture`
+* `hipStreamDestroy`
+* `hipStreamSynchronize`
+* `hipStreamWaitEvent`
+* `make_hipExtent`
+* `make_hipPitchedPtr`
+* `make_hipPos`
+
+### hipFFT library symbols
+
+* `hipfftCreate`
+* `hipfftExecC2R`
+* `hipfftExecR2C`
+* `hipfftDestroy`
+* `hipfftMakePlanMany`
+* `hipfftPlan1d`
+* `hipfftSetStream`

HIP-Doc/Tutorials/graph_api/src/.gitignore

@@ -0,0 +1,5 @@
+hip_graph_api_tutorial_streams
+hip_graph_api_tutorial_graph_capture
+hip_graph_api_tutorial_graph_creation
+tiff.dll
+libtiff.so*