From d7c59e29928f86fadde8fb9b80749a2bc84ef5a5 Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 13:49:47 -0500 Subject: [PATCH 1/7] Update hip_porting_guide.md Adding hyperlink to bin/hipconvertinplace.sh [ROCm/hip commit: d9e03872ab316ccd83058094339dc0f3ab85cee9] --- projects/hip/docs/markdown/hip_porting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index 2487d16e09..976a0a61d6 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -54,7 +54,7 @@ and provides practical suggestions on how to port CUDA code and work through com - Starting the port on a Cuda machine is often the easiest approach, since you can incrementally port pieces of the code to HIP while leaving the rest in Cuda. (Recall that on Cuda machines HIP is just a thin layer over Cuda, so the two code types can interoperate on nvcc platforms.) Also, the HIP port can be compared with the original Cuda code for function and performance. - Once the Cuda code is ported to HIP and is running on the Cuda machine, compile the HIP code using hcc on an AMD machine. - HIP ports can replace Cuda versions---HIP can deliver the same performance as a native Cuda implementation, with the benefit of portability to both Nvidia and AMD architectures as well as a path to future C++ standard support. You can handle platform-specific features through conditional compilation or by adding them to the open-source HIP infrastructure. -- Use **bin/hipconvertinplace.sh** to hipify all code files in the Cuda source directory. +- Use **[bin/hipconvertinplace.sh](https://github.com/ROCm-Developer-Tools/HIP/blob/master/bin/hipconvertinplace.sh)** to hipify all code files in the Cuda source directory. ### Scanning existing CUDA code to scope the porting effort The hipexamine.sh tool will scan a source directory to determine which files contain CUDA code and how much of that code can be automatically hipified, From 87580d3090c733fdce3210bd70621291ce5a548d Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 13:56:51 -0500 Subject: [PATCH 2/7] Fixing a broken indentation Minor (cosmetic) edit to make items appear in ordered bulleted list [ROCm/hip commit: 2ef15fd5b63db242282dfca2d1858475888180ee] --- projects/hip/docs/markdown/hip_porting_guide.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index 976a0a61d6..85aa7ceaad 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -53,7 +53,7 @@ and provides practical suggestions on how to port CUDA code and work through com ### General Tips - Starting the port on a Cuda machine is often the easiest approach, since you can incrementally port pieces of the code to HIP while leaving the rest in Cuda. (Recall that on Cuda machines HIP is just a thin layer over Cuda, so the two code types can interoperate on nvcc platforms.) Also, the HIP port can be compared with the original Cuda code for function and performance. - Once the Cuda code is ported to HIP and is running on the Cuda machine, compile the HIP code using hcc on an AMD machine. -- HIP ports can replace Cuda versions---HIP can deliver the same performance as a native Cuda implementation, with the benefit of portability to both Nvidia and AMD architectures as well as a path to future C++ standard support. You can handle platform-specific features through conditional compilation or by adding them to the open-source HIP infrastructure. +- HIP ports can replace Cuda versions: HIP can deliver the same performance as a native Cuda implementation, with the benefit of portability to both Nvidia and AMD architectures as well as a path to future C++ standard support. You can handle platform-specific features through conditional compilation or by adding them to the open-source HIP infrastructure. - Use **[bin/hipconvertinplace.sh](https://github.com/ROCm-Developer-Tools/HIP/blob/master/bin/hipconvertinplace.sh)** to hipify all code files in the Cuda source directory. ### Scanning existing CUDA code to scope the porting effort @@ -77,7 +77,7 @@ info: TOTAL-converted 89 CUDA->HIP refs( dev:3 mem:32 kern:2 builtin:37 math:0 s kernels (1 total) : kmeansPoint(1) ``` -hipexamine scans each code file (cpp, c, h, hpp, etc) found in the specified directory: +hipexamine scans each code file (cpp, c, h, hpp, etc.) found in the specified directory: * Files with no CUDA code (ie kmeans.h) print one line summary just listing the source file name. * Files with CUDA code print a summary of what was found - for example the kmeans_cuda_kernel.cu file: @@ -85,11 +85,11 @@ hipexamine scans each code file (cpp, c, h, hpp, etc) found in the specified dir info: hipify ./kmeans_cuda_kernel.cu =====> info: converted 40 CUDA->HIP refs( dev:0 mem:0 kern:0 builtin:37 math:0 stream:0 event:0 ``` -* Some of the most interesting information in kmeans_cuda_kernel.cu : - * How many CUDA calls were converted to HIP (40) - * Breakdown of the different CUDA functionality used (dev:0 mem:0 etc). This file uses many CUDA builtins (37) and texture functions (3). - * Warning for code that looks like CUDA API but was not converted (0 in this file). - * Count Lines-of-Code (LOC) - 185 for this file. +* Interesting information in kmeans_cuda_kernel.cu : + * How many CUDA calls were converted to HIP (40) + * Breakdown of the CUDA functionality used (dev:0 mem:0 etc). This file uses many CUDA builtins (37) and texture functions (3). + * Warning for code that looks like CUDA API but was not converted (0 in this file). + * Count Lines-of-Code (LOC) - 185 for this file. * hipexamine also presents a summary at the end of the process for the statistics collected across all files. This has similar format to the per-file reporting, and also includes a list of all kernels which have been called. An example from above: @@ -138,7 +138,7 @@ Many projects use a mixture of an accelerator compiler (hcc or nvcc) and a stand ### Identifying the Compiler: hcc, hip-clang or nvcc -Often, it’s useful to know whether the underlying compiler is hcc, hip-clang or nvcc. This knowledge can guard platform-specific code (features that only work on the nvcc, hip-clang or hcc path but not all) or aid in platform-specific performance tuning. +Often, it's useful to know whether the underlying compiler is hcc, hip-clang or nvcc. This knowledge can guard platform-specific code (features that only work on the nvcc, hip-clang or hcc path but not all) or aid in platform-specific performance tuning. ``` #ifdef __HCC__ From d78e52fa0c2e178dec8e6b42e121109b50c54ca3 Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 14:11:25 -0500 Subject: [PATCH 3/7] Small editing changes to clean up document [ROCm/hip commit: b1b93666566ec9fd69413306a99bafce54cb32a8] --- .../hip/docs/markdown/hip_porting_guide.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index 85aa7ceaad..34e0f22d5d 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -111,9 +111,9 @@ For each input file FILE, this script will: This is useful for testing improvements to the hipify toolset. -The "hipconvertinplace.sh" script will perform inplace conversion for all code files in the specified directory. +The [hipconvertinplace.sh](https://github.com/ROCm-Developer-Tools/HIP/blob/master/bin/hipconvertinplace.sh) script will perform inplace conversion for all code files in the specified directory. This can be quite handy when dealing with an existing CUDA code base since the script preserves the existing directory structure -and filenames - so includes work. After converting in-place, you can review the code to add additional parameters to +and filenames - and includes work. After converting in-place, you can review the code to add additional parameters to directory names. @@ -164,7 +164,7 @@ Often, it's useful to know whether the underlying compiler is hcc, hip-clang or // Compiled with nvcc (Cuda language extensions enabled) ``` -hcc and hip-clang directly generates the host code (using the Clang x86 target) and passes the code to another host compiler. Thus, it lacks the equivalent of the \__CUDA_ACC define. +hcc and hip-clang directly generates the host code (using the Clang x86 target) and passes the code to another host compiler. Thus, they have no equivalent of the \__CUDA_ACC define. The macro `__HIPCC__` is set if either `__HCC__`, `__HIP__` or `__CUDACC__` is defined. This configuration is useful in determining when code is being compiled using an accelerator-enabled compiler (hcc or nvcc) as opposed to a standard host compiler (GCC, ICC, Clang, etc.). @@ -177,7 +177,7 @@ Both nvcc and hcc make two passes over the code: one for host code and one for d #if __HIP_DEVICE_COMPILE__ ``` -Unlike `__CUDA_ARCH__`, the `__HIP_DEVICE_COMPILE__` value is 1 or undefined, and it doesn’t represent the feature capability of the target device. +Unlike `__CUDA_ARCH__`, the `__HIP_DEVICE_COMPILE__` value is 1 or undefined, and it doesn't represent the feature capability of the target device. ### Compiler Defines: Summary @@ -212,7 +212,7 @@ Some Cuda code tests `__CUDA_ARCH__` for a specific value to determine whether t #if (__CUDA_ARCH__ >= 130) // doubles are supported ``` -This type of code requires special attention, since hcc/AMD and nvcc/Cuda devices have different architectural capabilities. Moreover, you can’t determine the presence of a feature using a simple comparison against an architecture’s version number. HIP provides a set of defines and device properties to query whether a specific architectural feature is supported. +This type of code requires special attention, since hcc/AMD and nvcc/Cuda devices have different architectural capabilities. Moreover, you can't determine the presence of a feature using a simple comparison against an architecture's version number. HIP provides a set of defines and device properties to query whether a specific architectural feature is supported. The `__HIP_ARCH_*` defines can replace comparisons of `__CUDA_ARCH__` values: ``` @@ -259,9 +259,8 @@ The table below shows the full set of architectural properties that HIP supports |`__HIP_ARCH_HAS_WARP_FUNNEL_SHIFT__` | hasFunnelShift |Funnel shift two input words into one |Sync: | | |`__HIP_ARCH_HAS_THREAD_FENCE_SYSTEM__` | hasThreadFenceSystem |threadfence\_system -|`__HIP_ARCH_HAS_SYNC_THREAD_EXT__` | hasSyncThreadsExt |syncthreads\_count, syncthreads\_and, syncthreads\_or -| -|Miscellaneous: | | +|`__HIP_ARCH_HAS_SYNC_THREAD_EXT__` | hasSyncThreadsExt |syncthreads\_count, syncthreads\_and, syncthreads\_or +|Miscellaneous: | | |`__HIP_ARCH_HAS_SURFACE_FUNCS__` | hasSurfaceFuncs | |`__HIP_ARCH_HAS_3DGRID__` | has3dGrid | Grids and groups are 3D |`__HIP_ARCH_HAS_DYNAMIC_PARALLEL__` | hasDynamicParallelism | @@ -343,7 +342,7 @@ It also uses a standard compiler (g++) for the rest of the application. nvcc is Code compiled using this tool can employ only the intersection of language features supported by both nvcc and the host compiler. In some cases, you must take care to ensure the data types and alignment of the host compiler are identical to those of the device compiler. Only some host compilers are supported---for example, recent nvcc versions lack Clang host-compiler capability. -hcc generates both device and host code using the same Clang-based compiler. The code uses the same API as gcc, which allows code generated by different gcc-compatible compilers to be linked together. For example, code compiled using hcc can link with code compiled using "standard" compilers (such as gcc, ICC and Clang). You must take care to ensure all compilers use the same standard C++ header and library formats. +hcc generates both device and host code using the same Clang-based compiler. The code uses the same API as gcc, which allows code generated by different gcc-compatible compilers to be linked together. For example, code compiled using hcc can link with code compiled using "standard" compilers (such as gcc, ICC and Clang). Take care to ensure all compilers use the same standard C++ header and library formats. ### libc++ and libstdc++ @@ -553,7 +552,7 @@ hipcc-cmd: /opt/hcc/bin/hcc -hc -I/opt/hcc/include -stdlib=libc++ -I../../../.. #### /usr/include/c++/v1/memory:5172:15: error: call to implicitly deleted default constructor of 'std::__1::bad_weak_ptr' throw bad_weak_ptr(); -If you pass a ".cu" file, hcc will attempt to compile it as a Cuda language file. You must tell hcc that it’s in fact a C++ file: use the "-x c++" option. +If you pass a ".cu" file, hcc will attempt to compile it as a Cuda language file. You must tell hcc that it's in fact a C++ file: use the "-x c++" option. ### HIP Environment Variables From f73bac6908a03751e30ca62c3bfee92149e7f361 Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 14:25:07 -0500 Subject: [PATCH 4/7] Adding library equivalent section [ROCm/hip commit: 32c122eae527888ff447190a96d5d4f646556388] --- .../hip/docs/markdown/hip_porting_guide.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index 34e0f22d5d..38ce0b4b99 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -45,6 +45,8 @@ and provides practical suggestions on how to port CUDA code and work through com + [/usr/include/c++/v1/memory:5172:15: error: call to implicitly deleted default constructor of 'std::__1::bad_weak_ptr' throw bad_weak_ptr();](#usrincludecv1memory517215-error-call-to-implicitly-deleted-default-constructor-of-std__1bad_weak_ptr-throw-bad_weak_ptr) * [HIP Environment Variables](#hip-environment-variables) * [Editor Highlighting](#editor-highlighting) + * [CUDA to HIP Math Library Equivalents](#libraries-convert) + @@ -576,3 +578,20 @@ HIP_VISIBLE_DEVICES = 0 : Only devices whose index is present in the ### Editor Highlighting See the utils/vim or utils/gedit directories to add handy highlighting to hip files. + + +### Library Equivalents + +| CUDA Library | ROCm Library | Comment | +|------- | --------- | ----- | +| cuBLAS | rocBLAS | Basic Linear Algebra Subroutines +| cuFFT | rocFFT | Fast Fourier Transfer Library +| cuSPARSE | rocSPARSE | Sparse BLAS + SPMV +| cuSolver | rocSolver | Lapack library +| AMG-X | rocALUTION | Sparse iterative solvers and preconditioners with Geometric and Algebraic MultiGrid +| Thrust | hipThrust | C++ parallel algorithms library +| CUB | rocPRIM | Low Level Optimized Parallel Primitives +| cuDNN | MIOpen | Deep learning Solver Library +| cuRAND | rocRAND | Random Number Generator Library +| EIGEN | EIGEN – HIP port | C++ template library for linear algebra: matrices, vectors, numerical solvers, +| NCCL | RCCL | Communications Primitives Library based on the MPI equivalents From 97e7234a47944e830b629dc398cad6633b92980d Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 14:25:54 -0500 Subject: [PATCH 5/7] Fixing a link [ROCm/hip commit: 29db8e9678b6f9c5f25b1c3211623ba58413a390] --- projects/hip/docs/markdown/hip_porting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index 38ce0b4b99..4d193ce2e8 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -45,7 +45,7 @@ and provides practical suggestions on how to port CUDA code and work through com + [/usr/include/c++/v1/memory:5172:15: error: call to implicitly deleted default constructor of 'std::__1::bad_weak_ptr' throw bad_weak_ptr();](#usrincludecv1memory517215-error-call-to-implicitly-deleted-default-constructor-of-std__1bad_weak_ptr-throw-bad_weak_ptr) * [HIP Environment Variables](#hip-environment-variables) * [Editor Highlighting](#editor-highlighting) - * [CUDA to HIP Math Library Equivalents](#libraries-convert) + * [CUDA to HIP Math Library Equivalents](#libraries-equivalent) From ebcc1919cd85ce5120764a0584fffa44bcc75798 Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 14:26:49 -0500 Subject: [PATCH 6/7] Fixing link [ROCm/hip commit: 62c57a65bded8c97e1ad0f3fb0bf2cf110b0d1fa] --- projects/hip/docs/markdown/hip_porting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index 4d193ce2e8..adc95e4d1e 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -45,7 +45,7 @@ and provides practical suggestions on how to port CUDA code and work through com + [/usr/include/c++/v1/memory:5172:15: error: call to implicitly deleted default constructor of 'std::__1::bad_weak_ptr' throw bad_weak_ptr();](#usrincludecv1memory517215-error-call-to-implicitly-deleted-default-constructor-of-std__1bad_weak_ptr-throw-bad_weak_ptr) * [HIP Environment Variables](#hip-environment-variables) * [Editor Highlighting](#editor-highlighting) - * [CUDA to HIP Math Library Equivalents](#libraries-equivalent) + * [CUDA to HIP Math Library Equivalents](#library-equivalent) From 45be6e01d39c104301fed31fee6b9fb67742e14c Mon Sep 17 00:00:00 2001 From: Nicholas Malaya Date: Wed, 17 Oct 2018 14:27:11 -0500 Subject: [PATCH 7/7] Update hip_porting_guide.md [ROCm/hip commit: 26e948928722a050a7a90cc203ab63b46887df93] --- projects/hip/docs/markdown/hip_porting_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/hip/docs/markdown/hip_porting_guide.md b/projects/hip/docs/markdown/hip_porting_guide.md index adc95e4d1e..6fa0b958a8 100644 --- a/projects/hip/docs/markdown/hip_porting_guide.md +++ b/projects/hip/docs/markdown/hip_porting_guide.md @@ -45,7 +45,7 @@ and provides practical suggestions on how to port CUDA code and work through com + [/usr/include/c++/v1/memory:5172:15: error: call to implicitly deleted default constructor of 'std::__1::bad_weak_ptr' throw bad_weak_ptr();](#usrincludecv1memory517215-error-call-to-implicitly-deleted-default-constructor-of-std__1bad_weak_ptr-throw-bad_weak_ptr) * [HIP Environment Variables](#hip-environment-variables) * [Editor Highlighting](#editor-highlighting) - * [CUDA to HIP Math Library Equivalents](#library-equivalent) + * [CUDA to HIP Math Library Equivalents](#library-equivalents)