# HIP porting guide: overview and how-to¶

## HIP Porting Guide¶

In addition to providing a portable C++ programming environment for GPUs, HIP is designed to ease the porting of existing CUDA code into the HIP environment. This section describes the available tools and provides practical suggestions on how to port CUDA code and work through common issues.

## Porting a New Cuda Project¶

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

• Use 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,

> cd examples/rodinia_3.0/cuda/kmeans


## hipLaunchKernelGGL¶

hipLaunchKernelGGL is a variadic macro which accepts as parameters the launch configurations (grid dims, group dims, stream, dynamic shared size) followed by a variable number of kernel arguments. This sequence is then expanded into the appropriate kernel launch syntax depending on the platform. While this can be a convenient single-line kernel launch syntax, the macro implementation can cause issues when nested inside other macros. For example, consider the following:

// Will cause compile error:
#define MY_LAUNCH(command, doTrace) \
{\
if (doTrace) printf ("TRACE: %s\n", #command); \
(command);   /* The nested ( ) will cause compile error */\
}



Avoid nesting macro parameters inside parenthesis - here’s an alternative that will work:

#define MY_LAUNCH(command, doTrace) \
{\
if (doTrace) printf ("TRACE: %s\n", #command); \
command;\
}



## Compiler Options¶

hipcc is a portable compiler driver that will call nvcc or hcc (depending on the target system) and attach all required include and library options. It passes options through to the target compiler. Tools that call hipcc must ensure the compiler options are appropriate for the target compiler. The hipconfig script may helpful in making infrastructure that identifies the target platform and sets options appropriately. It returns either “nvcc” or “hcc.” The following sample shows the script in a makefile:

HIP_PLATFORM=$(shell hipconfig --compiler) ifeq (${HIP_PLATFORM}, nvcc)
HIPCC_FLAGS = -gencode=arch=compute_20,code=sm_20
endif
ifeq ({HIP_PLATFORM}, hcc) HIPCC_FLAGS = -Wno-deprecated-register endif  ## Linking Issues¶ ### Linking With hipcc¶ hipcc adds the necessary libraries for HIP as well as for the accelerator compiler (nvcc or hcc). We recommend linking with hipcc. ### -lm Option¶ hipcc adds -lm by default to the link command. ## Linking Code With Other Compilers¶ Cuda code often uses nvcc for accelerator code (defining and launching kernels, typically defined in .cu or .cuh files). It also uses a standard compiler (g++) for the rest of the application. nvcc is a preprocessor that employs a standard host compiler (e.g., gcc) to generate the host code. 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. ### libc++ and libstdc++¶ Version 0.86 of hipcc now uses libstdc++ by default for the HCC platform. This improves cross-linking support between G++ and hcc, in particular for interfaces that use standard C++ libraries (ie std::vector, std::string). If you pass “–stdlib=libc++” to hipcc, hipcc will use the libc++ library. Generally, libc++ provides a broader set of C++ features while libstdc++ is the standard for more compilers (notably including g++). When cross-linking C++ code, any C++ functions that use types from the C++ standard library (including std::string, std::vector and other containers) must use the same standard-library implementation. They include the following: • Functions or kernels defined in hcc that are called from a standard compiler • Functions defined in a standard compiler that are called from hcc. Applications with these interfaces should use the default libstdc++ linking. Applications which are compiled entirely with hipcc, and which benefit from advanced C++ features not supported in libstdc++, and which do not require portability to nvcc, may choose to use libc++. ### HIP Headers (hip_runtime.h, hip_runtime_api.h)¶ 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. 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. ### Using a Standard C++ Compiler¶ You can compile hip_runtime_api.h using a standard C or C++ compiler (e.g., gcc or ICC). The HIP include paths and defines (__HIP_PLATFORM_HCC__ or __HIP_PLATFORM_NVCC__) must pass to the standard compiler; hipconfig then returns the necessary options: > hipconfig --cxx_config -D__HIP_PLATFORM_HCC__ -I/home/user1/hip/include  You can capture the hipconfig output and passed it to the standard compiler; below is a sample makefile syntax: CPPFLAGS +=(shell $(HIP_PATH)/bin/hipconfig --cpp_config)  nvcc includes some headers by default. However, HIP does not include default headers, and instead all required files must be explicitly included. Specifically, files that call HIP run-time APIs or define HIP kernels must explicitly include the appropriate HIP headers. If the compilation process reports that it cannot find necessary APIs (for example, “error: identifier ‘hipSetDevice’ is undefined”), ensure that the file includes hip_runtime.h (or hip_runtime_api.h, if appropriate). The hipify script automatically converts “cuda_runtime.h” to “hip_runtime.h,” and it converts “cuda_runtime_api.h” to “hip_runtime_api.h”, but it may miss nested headers or macros. cuda.h The hcc path provides an empty cuda.h file. Some existing Cuda programs include this file but don’t require any of the functions. Choosing HIP File Extensions Many existing Cuda projects use the “.cu” and “.cuh” file extensions to indicate code that should be run through the nvcc compiler. For quick HIP ports, leaving these file extensions unchanged is often easier, as it minimizes the work required to change file names in the directory and #include statements in the files. For new projects or ports which can be re-factored, we recommend the use of the extension “.hip.cpp” for header files, and “.hip.h” or “.hip.hpp” for header files. This indicates that the code is standard C++ code, but also provides a unique indication for make tools to run hipcc when appropriate. ## Workarounds¶ warpSize Code should not assume a warp size of 32 or 64. See Warp Cross-Lane Functions for information on how to write portable wave-aware code. ### memcpyToSymbol¶ HIP support for hipMemCpyToSymbol is complete. This feature allows a kernel to define a device-side data symbol which can be accessed on the host side. The symbol can be in __constant or device space. Note that the symbol name needs to be encased in the HIP_SYMBOL macro, as shown in the code example below. This also applies to hipMemcpyFromSymbol, hipGetSymbolAddress, and hipGetSymbolSize. For example: Device Code: #include<hip/hip_runtime.h> #include<hip/hip_runtime_api.h> #include<iostream> #define HIP_ASSERT(status) \ assert(status == hipSuccess) #define LEN 512 #define SIZE 2048 __constant__ int Value[LEN]; __global__ void Get(int *Ad) { int tid = hipThreadIdx_x + hipBlockIdx_x * hipBlockDim_x; Ad[tid] = Value[tid]; } int main() { int *A, *B, *Ad; A = new int[LEN]; B = new int[LEN]; for(unsigned i=0;i<LEN;i++) { A[i] = -1*i; B[i] = 0; } HIP_ASSERT(hipMalloc((void**)&Ad, SIZE)); HIP_ASSERT(hipMemcpyToSymbol(HIP_SYMBOL(Value), A, SIZE, 0, hipMemcpyHostToDevice)); hipLaunchKernelGGL(Get, dim3(1,1,1), dim3(LEN,1,1), 0, 0, Ad); HIP_ASSERT(hipMemcpy(B, Ad, SIZE, hipMemcpyDeviceToHost)); for(unsigned i=0;i<LEN;i++) { assert(A[i] == B[i]); } std::cout<<"Passed"<<std::endl; }  ## threadfence_system¶ Threadfence_system makes all device memory writes, all writes to mapped host memory, and all writes to peer memory visible to CPU and other GPU devices. Some implementations can provide this behavior by flushing the GPU L2 cache. HIP/HCC does not provide this functionality. As a workaround, users can set the environment variable HSA_DISABLE_CACHE=1 to disable the GPU L2 cache. This will affect all accesses and for all kernels and so may have a performance impact. Textures and Cache Control Texture support is under-development and not yet supported by HIP. Compute programs sometimes use textures either to access dedicated texture caches or to use the texture-sampling hardware for interpolation and clamping. The former approach uses simple point samplers with linear interpolation, essentially only reading a single point. The latter approach uses the sampler hardware to interpolate and combine multiple point samples. AMD hardware, as well as recent competing hardware, has a unified texture/L1 cache, so it no longer has a dedicated texture cache. But the nvcc path often caches global loads in the L2 cache, and some programs may benefit from explicit control of the L1 cache contents. We recommend the __ldg instruction for this purpose. AMD compilers currently load all data into both the L1 and L2 caches, so __ldg is treated as a no-op. We recommend the following for functional portability: • For programs that use textures only to benefit from improved caching, use the __ldg instruction • Programs that use texture object and reference APIs, work well on HIP ### More Tips¶ HIPTRACE Mode On an hcc/AMD platform, set the HIP_TRACE_API environment variable to see a textural API trace. Use the following bit mask: • 0x1 = trace APIs • 0x2 = trace synchronization operations • 0x4 = trace memory allocation / deallocation Environment Variables On hcc/AMD platforms, set the HIP_PRINT_ENV environment variable to 1 and run an application that calls a HIP API to see all HIP-supported environment variables and their current values: • HIP_PRINT_ENV = 1: print HIP environment variables • HIP_TRACE_API = 1: trace each HIP API call. Print the function name and return code to stderr as the program executes. • HIP_LAUNCH_BLOCKING = 0: make HIP APIs ‘host-synchronous’ so they are blocked until any kernel launches or data-copy commands are complete (an alias is CUDA_LAUNCH_BLOCKING) • KMDUMPISA = 1 : Will dump the GCN ISA for all kernels into the local directory. (This flag is provided by HCC). Debugging hipcc To see the detailed commands that hipcc issues, set the environment variable HIPCC_VERBOSE to 1. Doing so will print to stderr the hcc (or nvcc) commands that hipcc generates. export HIPCC_VERBOSE=1 make ... hipcc-cmd: /opt/hcc/bin/hcc -hc -I/opt/hcc/include -stdlib=libc++ -I../../../../hc/include -I../../../../include/hcc_detail/cuda - I../../../../ include -x c++ -I../../common -O3 -c backprop_cuda.cu  What Does This Error Mean? /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. ### HIP Environment Variables¶ On the HCC path, HIP provides a number of environment variables that control the behavior of HIP. Some of these are useful for application development (for example HIP_VISIBLE_DEVICES, HIP_LAUNCH_BLOCKING), some are useful for performance tuning or experimentation (for example HIP_STAGING* ), and some are useful for debugging (HIP_DB). You can see the environment variables supported by HIP as well as their current values and usage with the environment var “HIP_PRINT_ENV” - set this and then run any HIP application. For example: $ HIP_PRINT_ENV=1 ./myhipapp
HIP_PRINT_ENV                  =  1 : Print HIP environment variables.
HIP_LAUNCH_BLOCKING            =  0 : Make HIP APIs 'host-synchronous', so they block until any kernel launches or data copy commands complete.       Alias: CUDA_LAUNCH_BLOCKING.