Sync HIP documentation 2025-10-20 (#1258)

* Add examples to tools folder
* Correct P2P memory access section
* Sync poriting guide
* Add HIP Graph tutorial
* Add hint about using amdgpu-dkms for IPC API
* Add a few more env variables

projects/hip/docs/reference/complex_math_api.rst

@@ -337,117 +337,7 @@ The kernel function ``computeDFT`` shows various HIP complex math operations in
 The example also demonstrates proper use of complex number handling on both host and device, including
 memory allocation, transfer, and validation of results between CPU and GPU implementations.
 
-.. code-block:: cpp
-
-    #include <hip/hip_runtime.h>
-    #include <hip/hip_complex.h>
-    #include <iostream>
-    #include <vector>
-    #include <cmath>
-
-    #define HIP_CHECK(expression)              \
-        {                                      \
-            const hipError_t err = expression; \
-            if (err != hipSuccess) {           \
-                std::cerr << "HIP error: "     \
-                        << hipGetErrorString(err) \
-                        << " at " << __LINE__ << "\n"; \
-                exit(EXIT_FAILURE);            \
-            }                                  \
-        }
-
-    // Kernel to compute DFT
-    __global__ void computeDFT(const float* input,
-                            hipFloatComplex* output,
-                            const int N)
-    {
-        int k = blockIdx.x * blockDim.x + threadIdx.x;
-        if (k >= N) return;
-
-        hipFloatComplex sum = make_hipFloatComplex(0.0f, 0.0f);
-
-        for (int n = 0; n < N; n++) {
-            float angle = -2.0f * M_PI * k * n / N;
-            hipFloatComplex w = make_hipFloatComplex(cosf(angle), sinf(angle));
-            hipFloatComplex x = make_hipFloatComplex(input[n], 0.0f);
-            sum = hipCaddf(sum, hipCmulf(x, w));
-        }
-
-        output[k] = sum;
-    }
-
-    // CPU implementation of DFT for verification
-    std::vector<hipFloatComplex> cpuDFT(const std::vector<float>& input) {
-        const int N = input.size();
-        std::vector<hipFloatComplex> result(N);
-
-        for (int k = 0; k < N; k++) {
-            hipFloatComplex sum = make_hipFloatComplex(0.0f, 0.0f);
-            for (int n = 0; n < N; n++) {
-                float angle = -2.0f * M_PI * k * n / N;
-                hipFloatComplex w = make_hipFloatComplex(cosf(angle), sinf(angle));
-                hipFloatComplex x = make_hipFloatComplex(input[n], 0.0f);
-                sum = hipCaddf(sum, hipCmulf(x, w));
-            }
-            result[k] = sum;
-        }
-        return result;
-    }
-
-    int main() {
-        const int N = 256;  // Signal length
-        const int blockSize = 256;
-
-        // Generate input signal: sum of two sine waves
-        std::vector<float> signal(N);
-        for (int i = 0; i < N; i++) {
-            float t = static_cast<float>(i) / N;
-            signal[i] = sinf(2.0f * M_PI * 10.0f * t) +  // 10 Hz component
-                    0.5f * sinf(2.0f * M_PI * 20.0f * t);  // 20 Hz component
-        }
-
-        // Compute reference solution on CPU
-        std::vector<hipFloatComplex> cpu_output = cpuDFT(signal);
-
-        // Allocate device memory
-        float* d_signal;
-        hipFloatComplex* d_output;
-        HIP_CHECK(hipMalloc(&d_signal, N * sizeof(float)));
-        HIP_CHECK(hipMalloc(&d_output, N * sizeof(hipFloatComplex)));
-
-        // Copy input to device
-        HIP_CHECK(hipMemcpy(d_signal, signal.data(), N * sizeof(float),
-                        hipMemcpyHostToDevice));
-
-        // Launch kernel
-        dim3 grid((N + blockSize - 1) / blockSize);
-        dim3 block(blockSize);
-        computeDFT<<<grid, block>>>(d_signal, d_output, N);
-        HIP_CHECK(hipGetLastError());
-
-        // Get GPU results
-        std::vector<hipFloatComplex> gpu_output(N);
-        HIP_CHECK(hipMemcpy(gpu_output.data(), d_output, N * sizeof(hipFloatComplex),
-                        hipMemcpyDeviceToHost));
-
-        // Verify results
-        bool passed = true;
-        const float tolerance = 1e-5f;  // Adjust based on precision requirements
-
-        for (int i = 0; i < N; i++) {
-            float diff_real = std::abs(hipCrealf(gpu_output[i]) - hipCrealf(cpu_output[i]));
-            float diff_imag = std::abs(hipCimagf(gpu_output[i]) - hipCimagf(cpu_output[i]));
-
-            if (diff_real > tolerance || diff_imag > tolerance) {
-                passed = false;
-                break;
-            }
-        }
-
-        std::cout << "DFT Verification: " << (passed ? "PASSED" : "FAILED") << "\n";
-
-        // Cleanup
-        HIP_CHECK(hipFree(d_signal));
-        HIP_CHECK(hipFree(d_output));
-        return passed ? 0 : 1;
-    }
+.. literalinclude:: ../tools/example_codes/complex_math.hip
+    :start-after: // [sphinx-start]
+    :end-before: // [sphinx-end]
+    :language: cpp