Update porting guide docs on -stdlib
이 커밋은 다음에 포함됨:
Ben Sander
@@ -26,7 +26,7 @@ and provides practical suggestions on how to port CUDA code and work through com
|
||||
* [Linking With hipcc](#linking-with-hipcc" aria-hidden="true"><span aria-hidden="true)
|
||||
* [-lm Option](#-lm-option" aria-hidden="true"><span aria-hidden="true)
|
||||
* [Linking Code With Other Compilers](#linking-code-with-other-compilers" aria-hidden="true"><span aria-hidden="true)
|
||||
* [libc and libstdc ](#libc-and-libstdc" aria-hidden="true"><span aria-hidden="true)
|
||||
* [libc and libstdc ](#libc-and-libstdc" aria-hidden="true"><span aria-hidden="true)
|
||||
* [HIP Headers (hip_runtime.h, hip_runtime_api.h)](#hip-headers-hip_runtimeh-hip_runtime_apih" aria-hidden="true"><span aria-hidden="true)
|
||||
* [Using a Standard C Compiler](#using-a-standard-c-compiler" aria-hidden="true"><span aria-hidden="true)
|
||||
* [cuda.h](#cudah" aria-hidden="true"><span aria-hidden="true)
|
||||
@@ -295,41 +295,43 @@ 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 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.
|
||||
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.
|
||||
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++
|
||||
|
||||
hcc uses the LLVM "libc++" standard library, whereas GCC uses the "libstdc++" standard library. Generally, libc++ provides a broader set of C++ features; libstdc++ is the standard for more compilers.
|
||||
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.
|
||||
|
||||
Note that C++ code that doesnt use the standard library, or pure-C code, can be linked across compiler boundaries. The following suggestions may help you to meet these requirements:
|
||||
Applications with these interfaces should use the default libstdc++ linking.
|
||||
|
||||
- Use the libc++ header and library for standard compilers. For GCC you can do so by passing the following:
|
||||
- `g++ -std=c++11 -I/usr/include/c++/v1 `; note that the host code will compile as C++ 11 code.
|
||||
- Use hipcc to compile the entire application
|
||||
- Partition the code into separate files so that standard C++ types dont apply across compiler boundaries. For example, placing the kernels in a separate file compiled using hcc will resolve the issue (provided they avoid using types from the C++ library).
|
||||
|
||||
A future hcc version may support libstdc++ in addition to libc++.
|
||||
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 C++ 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 C++ 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_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:
|
||||
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
|
||||
@@ -341,8 +343,11 @@ You can capture the hipconfig output and passed it to the standard compiler; bel
|
||||
CPPFLAGS += $(shell $(HIP_PATH)/bin/hipconfig --cpp_config)
|
||||
```
|
||||
|
||||
nvcc includes some headers by default. Files that call HIP run-time APIs or define HIP kernels must explicitly include 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.
|
||||
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
|
||||
|
||||
@@ -366,6 +371,8 @@ Code should not assume a warp size of 32 or 64. See [Warp Cross-Lane Functions]
|
||||
|
||||
#### 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.
|
||||
|
||||
새 이슈에서 참조
사용자 차단