From 4f2dab9c8677662859cd58d21be998fd7329b076 Mon Sep 17 00:00:00 2001 From: jujiang Date: Tue, 12 Jan 2021 20:20:00 -0500 Subject: [PATCH] SWDEV-265003-Update HIP documents Change-Id: I3aea36f9a817ff0d2a379fc902b1ba7794f9736e [ROCm/clr commit: 32f35bbd2ae07df36f2ddc69f0fc7850bd9806ec] --- projects/clr/hipamd/README.md | 7 +++---- .../clr/hipamd/docs/markdown/hip_porting_guide.md | 14 +++++++------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/projects/clr/hipamd/README.md b/projects/clr/hipamd/README.md index 0891780613..3dd7e1b80f 100644 --- a/projects/clr/hipamd/README.md +++ b/projects/clr/hipamd/README.md @@ -135,17 +135,16 @@ make * Guide to [Porting a New Cuda Project](docs/markdown/hip_porting_guide.md#porting-a-new-cuda-project") - + ## More Examples The GitHub repository [HIP-Examples](https://github.com/ROCm-Developer-Tools/HIP-Examples.git) contains a hipified version of the popular Rodinia benchmark suite. The README with the procedures and tips the team used during this porting effort is here: [Rodinia Porting Guide](https://github.com/ROCm-Developer-Tools/HIP-Examples/blob/master/rodinia_3.0/hip/README.hip_porting) ## Tour of the HIP Directories * **include**: - * **hip_runtime_api.h** : Defines HIP runtime APIs and can be compiled with many standard Linux compilers (hcc, GCC, ICC, CLANG, etc), in either C or C++ mode. - * **hip_runtime.h** : Includes everything in hip_runtime_api.h PLUS hipLaunchKernel and syntax for writing device kernels and device functions. hip_runtime.h can only be compiled with hcc. + * **hip_runtime_api.h** : Defines HIP runtime APIs and can be compiled with many standard Linux compilers (GCC, ICC, CLANG, etc), in either C or C++ mode. + * **hip_runtime.h** : Includes everything in hip_runtime_api.h PLUS hipLaunchKernel and syntax for writing device kernels and device functions. hip_runtime.h can be compiled using a standard C++ compiler but will expose a subset of the available functions. * **amd_detail/**** , **nvidia_detail/**** : Implementation details for specific platforms. HIP applications should not include these files directly. - * **hcc.h** : Includes interop APIs for HIP and HCC * **bin**: Tools and scripts to help with hip porting * **hipify-perl** : Script based tool to convert CUDA code to portable CPP. Converts CUDA APIs and kernel builtins. diff --git a/projects/clr/hipamd/docs/markdown/hip_porting_guide.md b/projects/clr/hipamd/docs/markdown/hip_porting_guide.md index ba1d5e8dd6..2300bd115d 100644 --- a/projects/clr/hipamd/docs/markdown/hip_porting_guide.md +++ b/projects/clr/hipamd/docs/markdown/hip_porting_guide.md @@ -85,13 +85,13 @@ hipexamine-perl scans each code file (cpp, c, h, hpp, etc.) found in the specifi * Files with CUDA code print a summary of what was found - for example the kmeans_cuda_kernel.cu file: ``` 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 + info: converted 40 CUDA->HIP refs( dev:0 mem:0 kern:0 builtin:37 math:0 stream:0 event:0 ``` * 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. + * Count Lines-of-Code (LOC) - 185 for this file. * hipexamine-perl 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: @@ -99,7 +99,7 @@ info: hipify ./kmeans_cuda_kernel.cu =====> info: TOTAL-converted 89 CUDA->HIP refs( dev:3 mem:32 kern:2 builtin:37 math:0 stream:0 event:0 err:0 def:0 tex:15 other:0 ) warn:0 LOC:3607 kernels (1 total) : kmeansPoint(1) ``` - + ### Converting a project "in-place" ```shell @@ -147,9 +147,9 @@ directory names. ### Identifying HIP Target Platform All HIP projects target either AMD or NVIDIA platform. The platform affects which headers are included and which libraries are used for linking. -- `HIP_PLATFORM_HCC` is defined if the HIP platform targets AMD +- `HIP_PLATFORM_AMD` is defined if the HIP platform targets AMD -- `HIP_PLATFORM_NVCC` is defined if the HIP platform targets NVIDIA +- `HIP_PLATFORM_NVIDA` is defined if the HIP platform targets NVIDIA ### Identifying the Compiler: hip-clang or nvcc Often, it's useful to know whether the underlying compiler is HIP-Clang or nvcc. This knowledge can guard platform-specific code or aid in platform-specific performance tuning. @@ -285,7 +285,7 @@ HIP_PATH ?= $(shell hipconfig --path) HIP can depend on ROCclr, or NVCC as runtime - AMD platform -`HIP_ROCclr` is defined on AMD platform that HIP use Radeon Open Compute Common Language Runtime, called ROCclr. +On AMD platform, HIP uses Radeon Open Compute Common Language Runtime, called ROCclr. ROCclr is a virtual device interface that HIP runtimes interact with different backends which allows runtimes to work on Linux , as well as Windows without much efforts. @@ -388,7 +388,7 @@ Applications which are compiled entirely with hipcc, and which benefit from adva The hip_runtime.h and hip_runtime_api.h files define the types, functions and enumerations needed to compile a HIP program: - hip_runtime_api.h: defines all the HIP runtime APIs (e.g., hipMalloc) and the types required to call them. A source file that is only calling HIP APIs but neither defines nor launches any kernels can include hip_runtime_api.h. hip_runtime_api.h uses no custom hc language features and can be compiled using a standard C++ compiler. -- hip_runtime.h: included in hip_runtime_api.h. It additionally provides the types and defines required to create and launch kernels. hip_runtime.h does use custom hc language features, but they are guarded by ifdef checks. It can be compiled using a standard C++ compiler but will expose a subset of the available functions. +- hip_runtime.h: included in hip_runtime_api.h. It additionally provides the types and defines required to create and launch kernels. hip_runtime.h can be compiled using a standard C++ compiler but will expose a subset of the available functions. CUDA has slightly different contents for these two files. In some cases you may need to convert hipified code to include the richer hip_runtime.h instead of hip_runtime_api.h.